Mengonfigurasi layanan pencarian untuk menyambungkan menggunakan identitas terkelola di Azure AI Search

Artikel
07/02/2024

Penting

Penetapan identitas terkelola yang ditetapkan pengguna berada dalam pratinjau publik di bawah Ketentuan Penggunaan Tambahan. REST API Pratinjau manajemen menyediakan penetapan identitas terkelola yang ditetapkan pengguna untuk Azure AI Search. Dukungan untuk identitas terkelola yang ditetapkan sistem umumnya tersedia.

Anda dapat menggunakan ID Microsoft Entra dan penetapan peran untuk koneksi keluar dari Azure AI Search ke sumber daya yang menyediakan data, AI yang diterapkan, atau vektorisasi selama pengindeksan atau kueri.

Untuk menggunakan peran pada koneksi keluar, pertama-tama konfigurasikan layanan pencarian Anda untuk menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna sebagai prinsip keamanan untuk layanan pencarian Anda di penyewa Microsoft Entra. Setelah Anda memiliki identitas terkelola, Anda dapat menetapkan peran untuk akses resmi. Identitas terkelola dan penetapan peran menghilangkan kebutuhan untuk meneruskan rahasia dan kredensial dalam string koneksi atau kode.

Prasyarat

Layanan pencarian di tingkat Dasar atau lebih tinggi, wilayah mana pun.
Sumber daya Azure yang menerima permintaan masuk dari perwakilan keamanan Microsoft Entra yang memiliki penetapan peran yang valid.

Skenario yang didukung

Pencarian Azure AI dapat tersambung ke sumber daya Azure lainnya di bawah identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna.

layanan Pencarian konfigurasi identitas terkelola yang ditetapkan sistem umumnya tersedia.
layanan Pencarian konfigurasi identitas terkelola yang ditetapkan pengguna berada dalam pratinjau publik, di bawah ketentuan penggunaan tambahan.
Penggunaan data plane dari identitas terkelola, baik sistem atau yang ditetapkan pengguna, umumnya tersedia. Misalnya, jika Anda menginginkan identitas terkelola yang ditetapkan pengguna pada koneksi sumber data pengindeks, brankas kunci, sesi debug, atau cache pengayaan, Anda dapat menggunakan versi REST API yang tersedia secara umum untuk membuat koneksi, dengan asumsi fitur yang Anda gunakan juga tersedia secara umum.

Identitas terkelola sistem ditunjukkan ketika string koneksi adalah ID sumber daya unik dari layanan atau aplikasi sadar ID Microsoft Entra. Identitas terkelola yang ditetapkan pengguna ditentukan melalui properti "identitas".

Layanan pencarian menggunakan Azure Storage sebagai sumber data pengindeks dan sebagai sink data untuk sesi debug, penembolokan pengayaan, dan penyimpanan pengetahuan. Untuk fitur pencarian yang menulis kembali ke penyimpanan, identitas terkelola memerlukan penetapan peran kontributor seperti yang dijelaskan di bagian "Tetapkan peran" .

Skenario	Sistem	Ditetapkan pengguna
Koneksi pengindeks ke sumber ^{data Azure yang didukung 1}	Ya	Ya
Azure Key Vault untuk kunci yang dikelola pelanggan	Ya	Ya
Sesi debug (dihosting di Azure Storage)¹	Ya	Tidak
Cache pengayaan (dihosting di Azure Storage) 1,^²	Ya	Ya
Penyimpanan Pengetahuan (dihosting di Azure Storage) ¹	Ya	Ya
Koneksi ke Azure OpenAI atau Azure AI ³	Ya	Ya

¹ Untuk konektivitas antara pencarian dan penyimpanan, konfigurasi keamanan jaringan Anda memberlakukan batasan jenis identitas terkelola yang dapat Anda gunakan. Hanya identitas terkelola sistem yang dapat digunakan untuk koneksi wilayah yang sama ke penyimpanan melalui pengecualian layanan tepercaya atau aturan instans sumber daya. Lihat Akses ke akun penyimpanan yang dilindungi jaringan untuk detailnya.

² Layanan pencarian AI saat ini tidak dapat tersambung ke tabel pada akun penyimpanan yang telah menonaktifkan akses kunci bersama.

³ Koneksi ke Azure OpenAI atau Azure AI meliputi: Keterampilan kustom, Vektorizer kustom, keterampilan penyematan Azure OpenAI, vektorizer Azure OpenAI, keterampilan AML, vektorizer katalog model Azure AI Studio, keterampilan penyematan multimodal Azure AI Vision, vektorizer Azure AI Vision.

Membuat identitas terkelola sistem

Saat Anda mengaktifkan identitas terkelola yang ditetapkan sistem, MICROSOFT Entra ID membuat identitas untuk layanan pencarian Anda yang dapat digunakan untuk mengautentikasi ke layanan Azure lainnya dalam penyewa yang sama. Anda kemudian dapat menggunakan identitas ini dalam penetapan peran untuk mengakses data dan model.

Identitas terkelola yang ditetapkan sistem bersifat unik untuk layanan pencarian Anda dan terikat ke layanan selama masa pakainya. Layanan pencarian hanya dapat memiliki satu identitas terkelola yang ditetapkan sistem.

Masuk ke portal Azure dan temukan layanan pencarian Anda.
Di Pengaturan, pilih Identitas.
Pada tab Sistem yang ditetapkan, di bawah Status, pilih Aktif.
Pilih Simpan.

Setelah Anda menyimpan pengaturan, halaman diperbarui untuk menampilkan pengidentifikasi objek yang ditetapkan ke layanan pencarian Anda.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Untuk informasi selengkapnya, lihat Membuat layanan pencarian dengan identitas terkelola yang ditetapkan sistem (Azure PowerShell.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Untuk informasi selengkapnya, lihat Membuat layanan pencarian dengan identitas terkelola yang ditetapkan sistem (Azure CLI).

Merumuskan permintaan untuk Membuat atau Memperbarui layanan pencarian.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Konfirmasi dan pengidentifikasi objek untuk identitas terkelola sistem dikembalikan dalam respons.

Untuk informasi selengkapnya, lihat Membuat atau Memperbarui Layanan (Management REST API).

Membuat identitas terkelola yang ditetapkan pengguna

Penting

Bagian dari skenario ini ada dalam pratinjau publik di bawah Ketentuan Penggunaan Tambahan. REST API Pratinjau manajemen menyediakan konfigurasi identitas terkelola yang ditetapkan pengguna untuk Azure AI Search.

Identitas terkelola yang ditetapkan pengguna adalah sumber daya di Azure. Anda dapat membuat beberapa identitas terkelola yang ditetapkan pengguna jika Anda menginginkan lebih banyak granularitas dalam penetapan peran. Misalnya, Anda mungkin menginginkan identitas terpisah untuk aplikasi dan skenario yang berbeda.

Langkah-langkahnya adalah:

Di langganan Azure Anda, buat identitas terkelola yang ditetapkan pengguna.
Pada layanan pencarian Anda, perbarui definisi layanan untuk mengaktifkan identitas terkelola yang ditetapkan pengguna (langkah ini dalam pratinjau).
Di layanan Azure lain yang ingin Anda sambungkan, buat penetapan peran untuk identitas tersebut.
Dalam koneksi sumber data di Azure AI Search, seperti sumber data pengindeks, referensikan identitas yang dikelola pengguna dalam detail koneksi (langkah ini umumnya tersedia jika dukungan untuk fitur tersebut tersedia secara umum).

Identitas terkelola yang ditetapkan pengguna dapat dilingkup ke langganan, grup sumber daya, atau jenis sumber daya.

Mengaitkan identitas terkelola yang ditetapkan pengguna didukung di portal Azure, dalam versi pratinjau API REST Manajemen, dan dalam paket SDK beta yang menyediakan fitur tersebut.

Portal Azure
REST API

Masuk ke portal Microsoft Azure.
Pilih Buat sumber daya.
Di bilah pencarian "Cari layanan dan marketplace", cari "Identitas Terkelola Yang Ditetapkan Pengguna" lalu pilih Buat.
Pilih langganan, grup sumber daya, dan wilayah. Beri nama yang deskriptif pada identitas tersebut.
Pilih Buat dan tunggu hingga sumber daya selesai disebarkan.

Dibutuhkan beberapa menit sebelum Anda dapat menggunakan identitas.
Di halaman layanan pencarian Anda, di bawah Pengaturan, pilih Identitas.
Pada tab Ditetapkan pengguna, pilih Tambahkan.
Pilih langganan lalu pilih sumber daya terkelola yang ditetapkan pengguna yang Anda buat di langkah sebelumnya.

Anda dapat menggunakan pratinjau Management REST API alih-alih portal untuk menetapkan identitas terkelola yang ditetapkan pengguna. Gunakan versi API atau yang lebih 2021-04-01-preview baru. Contoh ini menggunakan2024-06-01-preview.

Merumuskan permintaan untuk MEMPERBARUI layanan pencarian.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Atur properti "identitas" untuk menentukan identitas terkelola yang sepenuhnya memenuhi syarat:
- "type" adalah jenis identitas. Nilai yang valid adalah "SystemAssigned", "UserAssigned", atau "SystemAssigned, UserAssigned" jika Anda ingin menggunakan keduanya. Nilai "None" menghapus identitas yang ditetapkan sebelumnya dari layanan pencarian.
- "userAssignedIdentities" menyertakan detail identitas terkelola yang ditetapkan pengguna. Identitas ini harus sudah ada sebelum Anda dapat menentukannya dalam permintaan Layanan Pembaruan.

Menetapkan peran

Setelah Anda memiliki identitas terkelola, tetapkan peran yang menentukan izin layanan pencarian di sumber daya Azure.

Izin baca diperlukan untuk koneksi data pengindeks dan untuk mengakses kunci yang dikelola pelanggan di Azure Key Vault.
Izin tulis diperlukan untuk fitur pengayaan AI yang menggunakan Azure Storage untuk menghosting data sesi debug, penembolokan pengayaan, dan penyimpanan konten jangka panjang di penyimpanan pengetahuan.

Langkah-langkah berikut mengilustrasikan alur kerja penetapan peran. Contoh ini untuk Azure OpenAI. Untuk sumber daya Azure lainnya, lihat Menyambungkan ke Azure Storage, Menyambungkan ke Azure Cosmos DB, atau Menyambungkan ke Azure SQL.

Masuk ke portal Azure dengan akun Azure Anda, dan buka sumber daya Azure OpenAI Anda.
Pilih Kontrol akses dari menu sebelah kiri.
Pilih Tambahkan lalu pilih Tambahkan penetapan peran.
Di bawah Peran fungsi pekerjaan, pilih Pengguna OpenAI Cognitive Services lalu pilih Berikutnya.
Di bawah Anggota, pilih Identitas terkelola lalu pilih Anggota.
Filter menurut langganan dan jenis sumber daya (layanan Pencarian), lalu pilih identitas terkelola layanan pencarian Anda.
Pilih Tinjau + tetapkan.

Contoh string koneksi

Setelah identitas terkelola didefinisikan untuk layanan pencarian dan diberi penetapan peran, koneksi keluar dapat dimodifikasi untuk menggunakan ID sumber daya unik dari sumber daya Azure lainnya. Berikut adalah beberapa contoh string koneksi untuk berbagai skenario.

Anda dapat menggunakan versi REST API yang tersedia secara umum dan paket Azure SDK untuk koneksi ini.

Tip

Anda dapat membuat sebagian besar objek ini di portal Azure, menentukan identitas terkelola yang ditetapkan sistem atau pengguna, lalu melihat definisi JSON untuk mendapatkan string koneksi.

Sumber data blob (sistem):

Sumber data pengindeks menyertakan properti "info masuk" yang menentukan bagaimana koneksi dibuat ke sumber data. Contoh berikut menunjukkan string koneksi menentukan ID sumber daya unik dari akun penyimpanan.

MICROSOFT Entra ID mengautentikasi permintaan menggunakan identitas terkelola sistem dari layanan pencarian. Perhatikan bahwa string koneksi tidak menyertakan kontainer. Dalam definisi sumber data, nama kontainer ditentukan dalam properti "kontainer" (tidak ditampilkan), bukan string koneksi.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Sumber data blob (pengguna):

Permintaan pencarian ke Azure Storage juga dapat dibuat di bawah identitas terkelola yang ditetapkan pengguna. Identitas pengguna layanan pencarian ditentukan dalam properti "identitas".

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Penyimpanan pengetahuan:

Definisi penyimpanan pengetahuan menyertakan string koneksi ke Azure Storage. string koneksi adalah ID sumber daya unik dari akun penyimpanan Anda. Perhatikan bahwa string tidak menyertakan kontainer atau tabel di jalur. Ini didefinisikan dalam definisi proyeksi yang disematkan, bukan string koneksi.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Cache pengayaan:

Pengindeks membuat, menggunakan, dan mengingat kontainer yang digunakan untuk pengayaan cache. Tidak perlu menyertakan kontainer dalam cache string koneksi. Anda dapat menemukan ID objek di halaman Identitas layanan pencarian Anda di portal.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sesi debug:

Sesi debug berjalan di portal dan mengambil string koneksi saat Anda memulai sesi. Anda dapat menempelkan string yang mirip dengan contoh berikut.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Keterampilan kustom:

Keterampilan kustom menargetkan titik akhir fungsi Azure atau kode kustom hosting aplikasi. Titik akhir ditentukan dalam definisi keterampilan kustom. Kehadiran "authResourceId" memberi tahu layanan pencarian untuk terhubung menggunakan identitas terkelola, meneruskan ID aplikasi fungsi atau aplikasi target di properti .

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Keterampilan penyematan Azure OpenAI dan vektorizer Azure OpenAI:

Keterampilan dan vektorizer penyematan Azure OpenAI di Pencarian AI menargetkan titik akhir layanan Azure OpenAI yang menghosting model penyematan. Titik akhir ditentukan dalam definisi keterampilan penyematan Azure OpenAI dan/atau dalam definisi vektorizer Azure OpenAI. Identitas yang dikelola sistem digunakan jika dikonfigurasi dan jika "apikey" dan "authIdentity" kosong. Properti "authIdentity" hanya digunakan untuk identitas terkelola yang ditetapkan pengguna.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

Periksa akses firewall

Jika sumber daya Azure Anda berada di belakang firewall, pastikan ada aturan masuk yang mengakui permintaan dari layanan pencarian Anda.

Untuk koneksi wilayah yang sama ke Azure Blob Storage atau Azure Data Lake Storage Gen2, gunakan identitas terkelola sistem dan pengecualian layanan tepercaya. Secara opsional, Anda dapat mengonfigurasi aturan instans sumber daya untuk mengakui permintaan.
Untuk semua sumber daya dan koneksi lainnya, konfigurasikan aturan firewall IP yang mengakui permintaan dari Pencarian. Lihat Akses pengindeks ke konten yang dilindungi oleh fitur keamanan jaringan Azure untuk detailnya.

Bagikan melalui