Mengautentikasi dan mengotorisasi App Service ke database vektor

Artikel ini menunjukkan cara mengelola koneksi antara aplikasi .NET App Service Anda dan solusi database vektor. Ini mencakup penggunaan identitas terkelola Microsoft Entra untuk layanan yang didukung dan menyimpan string koneksi dengan aman untuk orang lain.

Dengan menambahkan database vektor ke aplikasi, Anda dapat mengaktifkan memori semantik untuk AI Anda. Semantic Kernel SDK for .NET memungkinkan Anda untuk dengan mudah menerapkan penyimpanan memori dan pengenalan menggunakan solusi database vektor pilihan Anda.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• .NET SDK
• Microsoft.SemanticKernel Paket NuGet
• Microsoft.SemanticKernel.Plugins.Memory Paket NuGet
• Membuat dan menyebarkan aplikasi .NET ke App Service
• Membuat dan menyebarkan solusi database vektor

Menggunakan identitas terkelola Microsoft Entra untuk autentikasi

Jika layanan database vektor mendukung autentikasi Microsoft Entra, Anda dapat menggunakan identitas terkelola dengan App Service Anda untuk mengakses database vektor Anda dengan aman tanpa harus menyediakan atau memutar rahasia apa pun secara manual. Untuk daftar layanan Azure yang mendukung autentikasi Microsoft Entra, lihat Layanan Azure yang mendukung autentikasi Microsoft Entra.

Menambahkan identitas terkelola ke App Service

Aplikasi Anda dapat diberikan dua jenis identitas:

• Identitas yang ditetapkan sistem terkait dengan aplikasi Anda dan dihapus jika aplikasi Anda dihapus. Aplikasi hanya dapat memiliki satu identitas yang ditetapkan sistem.
• Identitas yang ditetapkan pengguna adalah sumber daya Azure mandiri yang dapat ditetapkan ke aplikasi Anda. Aplikasi dapat memiliki beberapa identitas yang ditetapkan pengguna.

Tambahkan identitas yang ditetapkan sistem

1. Navigasi ke halaman aplikasi Anda di portal Azure, lalu gulir ke bawah ke grup Pengaturan.
2. Pilih Identitas.
3. Pada tab Yang ditetapkan sistem, alihkan Status ke Aktif, lalu pilih Simpan.

Jalankan perintah az webapp identity assign untuk membuat identitas yang ditetapkan sistem:

az webapp identity assign --name <appName> --resource-group <groupName>

Menambahkan identitas yang ditetapkan pengguna

Untuk menambahkan identitas yang ditetapkan pengguna ke aplikasi Anda, buat identitas, lalu tambahkan pengidentifikasi sumber dayanya ke konfigurasi aplikasi Anda.

1. Buat sumber daya identitas terkelola yang ditetapkan pengguna dengan mengikuti instruksi ini.

2. Di panel navigasi kiri halaman aplikasi Anda, gulir ke bawah ke grup Pengaturan.

3. Pilih Identitas.

4. Pilih Tambahkan yang> ditetapkan pengguna.

5. Temukan identitas yang Anda buat sebelumnya, pilih identitas tersebut, lalu pilih Tambahkan.

   Penting

   Setelah Anda memilih Tambahkan, aplikasi dimulai ulang.

1. Buat identitas yang ditetapkan pengguna:

   az identity create --resource-group <groupName> --name <identityName>
   

2. Tetapkan identitas ke aplikasi Anda:

   az webapp identity assign --resource-group <groupName> --name <appName> --identities <identityId>
   

Menambahkan peran Azure ke identitas terkelola Anda

1. Di Portal Microsoft Azure, navigasikan ke cakupan yang ingin Anda beri akses database vektor. Cakupan dapat berupa grup Manajemen, Langganan, Grup sumber daya, atau sumber daya Azure tertentu.
2. Di panel navigasi kiri, pilih Kontrol akses (IAM).
3. Pilih Tambahkan, lalu pilih Tambahkan penetapan peran.
4. Pada tab Peran , pilih peran yang sesuai yang memberikan akses baca ke database vektor Anda.
5. Pada tab Anggota , pilih identitas terkelola.
6. Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.

Cakupan sumber daya

az role assignment create --assignee "<managedIdentityObjectID>" \
--role "<myVectorDbReaderRole>" \
--scope "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/<providerName>/<resourceType>/<resourceSubType>/<resourceName>"

Cakupan grup sumber daya

az role assignment create --assignee "<managedIdentityObjectID>" \
--role "<myVectorDbReaderRole>" \
--scope "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>"

Cakupan langganan

az role assignment create --assignee "<managedIdentityObjectID>" \
--role "<myVectorDbReaderRole>" \
--scope "/subscriptions/<subscriptionId>"

Cakupan grup manajemen

az role assignment create --assignee "<managedIdentityObjectID>" \
--role "<myVectorDbReaderRole>" \
--scope "/providers/Microsoft.Management/managementGroups/<managementGroupName>"

Menerapkan autentikasi berbasis token dengan database vektor

Sampel kode berikut memerlukan pustaka tambahan ini:

• Azure.Identity Paket NuGet
• Microsoft.SemanticKernel.Connectors.AzureAISearch Paket NuGet

1. Inisialisasi DefaultAzureCredential objek untuk mengambil identitas terkelola aplikasi Anda:

   // Initialize a DefaultAzureCredential.
   // This credential type will try several authentication flows in order until one is available.
   // Will pickup Visual Studio or Azure CLI credentials in local environments.
   // Will pickup managed identity credentials in production deployments.
   TokenCredential credentials = new DefaultAzureCredential(
       new DefaultAzureCredentialOptions
       {
           // If using a user-assigned identity specify either:
           // ManagedIdentityClientId or ManagedIdentityResourceId.
           // e.g.: ManagedIdentityClientId = "myIdentityClientId".
       }
   );
   

2. Inisialisasi IMemoryStore objek untuk database vektor Anda, lalu gunakan untuk membangun ISemanticTextMemory:

   // Retrieve the endpoint obtained from the Azure AI Search deployment.
   // Retrieve the endpoint and deployments obtained from the Azure OpenAI deployment.
   // Must use the deployment name not the underlying model name.
   IConfigurationRoot config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
   string searchEndpoint = config["AZURE_AISEARCH_ENDPOINT"]!;
   string openAiEndpoint = config["AZURE_OPENAI_ENDPOINT"]!;
   string embeddingModel = config["AZURE_OPENAI_EMBEDDING_NAME"]!;
   
   // The Semantic Kernel SDK provides a connector extension for Azure AI Search.
   // Initialize an AzureAISearchMemoryStore using your managed identity credentials.
   IMemoryStore memoryStore = new AzureAISearchMemoryStore(searchEndpoint, credentials);
   
   // Build a SemanticMemoryStore with Azure AI Search as the store.
   // Must also include a text embedding generation service.
   ISemanticTextMemory memory = new MemoryBuilder()
       .WithAzureOpenAITextEmbeddingGeneration(embeddingModel, openAiEndpoint, credentials)
       .WithMemoryStore(memoryStore)
       .Build();
   

3. Buat Kernel objek, lalu impor ISemanticTextMemory objek menggunakan TextMemoryPlugin:

   // Build a Kernel, include a chat completion service.
   string chatModel = config["AZURE_OPENAI_GPT_NAME"]!;
   Kernel kernel = Kernel
       .CreateBuilder()
       .AddAzureOpenAIChatCompletion(chatModel, openAiEndpoint, credentials)
       .Build();
   
   // Import the semantic memory store as a TextMemoryPlugin.
   // The TextMemoryPlugin enable recall via prompt expressions.
   kernel.ImportPluginFromObject(new TextMemoryPlugin(memory));
   

4. Kernel Gunakan objek untuk memanggil perintah yang menyertakan pengenalan memori:

   // Must configure the memory collection, number of memories to recall, and relevance score.
   // The {{...}} syntax represents an expression to Semantic Kernel.
   // For more information on this syntax see:
   // https://learn.microsoft.com/semantic-kernel/prompts/prompt-template-syntax
   string memoryCollection = config["AZURE_OPENAI_MEMORY_NAME"]!;
   string? result = await kernel.InvokePromptAsync<string>(
       "{{recall 'where did I grow up?'}}",
       new()
       {
           [TextMemoryPlugin.CollectionParam] = memoryCollection,
           [TextMemoryPlugin.LimitParam] = "2",
           [TextMemoryPlugin.RelevanceParam] = "0.79",
       }
   );
   Console.WriteLine($"Output: {result}");
   

Menggunakan Key Vault untuk menyimpan rahasia koneksi

Jika database vektor tidak mendukung autentikasi Microsoft Entra, Anda dapat menggunakan Key Vault untuk menyimpan rahasia koneksi Anda dan mengambilnya dengan aplikasi App Service Anda. Dengan menggunakan Key Vault untuk menyimpan rahasia koneksi, Anda dapat membagikannya dengan beberapa aplikasi, dan mengontrol akses ke rahasia individual per aplikasi.

Sebelum mengikuti langkah-langkah ini, ambil string koneksi untuk database vektor Anda. Misalnya, lihat Menggunakan Azure Cache for Redis dengan aplikasi web ASP.NET Core.

Menambahkan string koneksi ke Key Vault

Penting

Sebelum mengikuti langkah-langkah ini, pastikan Anda telah membuat Key Vault menggunakan Portal Microsoft Azure.

1. Navigasikan ke brankas kunci Anda di Portal Microsoft Azure.
2. Di navigasi kiri Key Vault, pilih Objek lalu pilih Rahasia.
3. Pilih + Hasilkan/Impor.
4. Pada layar Buat rahasia pilih nilai berikut ini:
   • Opsi unggah: Manual.
   • Nama: Ketik nama untuk rahasia. Nama rahasia dalam Key Vault harus unik.
   • Nilai: String koneksi untuk database vektor Anda.
   • Biarkan nilai lainnya mengikuti default. Pilih Buat.
5. Ketika Anda menerima pesan bahwa rahasia telah berhasil dibuat, rahasia siap digunakan dalam aplikasi Anda.

Penting

Sebelum mengikuti langkah-langkah ini, pastikan Anda telah membuat Key Vault menggunakan Azure CLI.

1. Berikan izin akun pengguna Anda ke brankas kunci Anda melalui Kontrol Akses Berbasis Peran (RBAC), tetapkan peran menggunakan perintah az role assignment createAzure CLI :

   az role assignment create \
   --role "Key Vault Secrets User" \
   --assignee "<yourEmailAddress>" \
   --scope "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<keyVaultName>"
   

2. Tambahkan string koneksi ke Key Vault menggunakan perintah az keyvault secret setAzure CLI :

   az keyvault secret set \
   --vault-name "<keyVaultName>" \
   --name "<secretName>" \
   --value "<connectionString>"
   

Memberikan akses App Service Anda ke Key Vault

1. Tetapkan identitas terkelola ke App Service Anda.
2. Tambahkan peran dan Key Vault Reader ke Key Vault Secrets User identitas terkelola Anda.

Menerapkan pengambilan string koneksi dari Key Vault

Untuk menggunakan sampel kode berikut, Anda memerlukan pustaka tambahan ini:

• Azure.Identity Paket NuGet
• Azure.Extensions.AspNetCore.Configuration.Secrets Paket NuGet
• Microsoft.Extensions.Configuration Paket NuGet

Sampel kode ini menggunakan database Redis, tetapi Anda dapat menerapkannya ke database vektor apa pun yang mendukung string koneksi.

1. Inisialisasi DefaultAzureCredential objek untuk mengambil identitas terkelola aplikasi Anda:

   // Initialize a DefaultAzureCredential.
   // This credential type will try several authentication flows in order until one is available.
   // Will pickup Visual Studio or Azure CLI credentials in local environments.
   // Will pickup managed identity credentials in production deployments.
   TokenCredential credentials = new DefaultAzureCredential(
       new DefaultAzureCredentialOptions
       {
           // If using a user-assigned identity specify either:
           // ManagedIdentityClientId or ManagedIdentityResourceId.
           // e.g.: ManagedIdentityClientId = "myIdentityClientId".
       }
   );
   

2. Tambahkan Key Vault saat membangun konfigurasi Anda, ini akan memetakan rahasia Key Vault Anda ke IConfigurationRoot objek:

   // User secrets let you provide connection strings when testing locally
   // For more info see: https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets
   IConfigurationRoot config = new ConfigurationBuilder()
       .AddUserSecrets<Program>()
       .AddAzureKeyVault(new Uri("{vaultURI}"), credentials)
       .Build();
   
   // Retrieve the Redis connection string obtained from the Key Vault.
   string redisConnectionString = config["AZURE_REDIS_CONNECT_STRING"]!;
   

3. Gunakan database vektor Anda string koneksi dari Key Vault untuk menginisialisasi IMemoryStore objek, lalu gunakan untuk membangun ISemanticTextMemory:

   // Use the connection string to connect to the database
   IDatabase database = (
       await ConnectionMultiplexer.ConnectAsync(redisConnectionString)
   ).GetDatabase();
   
   // The Semantic Kernel SDK provides a connector extension for Redis.
   // Initialize an RedisMemoryStore using your managed identity credentials.
   IMemoryStore memoryStore = new RedisMemoryStore(database);
   
   // Retrieve the endpoint and deployments obtained from the Azure OpenAI deployment.
   // Must use the deployment name not the underlying model name.
   string openAiEndpoint = config["AZURE_OPENAI_ENDPOINT"]!;
   string embeddingModel = config["AZURE_OPENAI_EMBEDDING_NAME"]!;
   
   // Build a SemanticMemoryStore with Azure AI Search as the store.
   // Must also include a text embedding generation service.
   ISemanticTextMemory memory = new MemoryBuilder()
       .WithAzureOpenAITextEmbeddingGeneration(embeddingModel, openAiEndpoint, credentials)
       .WithMemoryStore(memoryStore)
       .Build();
   

4. Buat Kernel objek, lalu impor ISemanticTextMemory objek menggunakan TextMemoryPlugin:

   // Build a Kernel, include a chat completion service.
   string chatModel = config["AZURE_OPENAI_GPT_NAME"]!;
   Kernel kernel = Kernel
       .CreateBuilder()
       .AddAzureOpenAIChatCompletion(chatModel, openAiEndpoint, credentials)
       .Build();
   
   // Import the semantic memory store as a TextMemoryPlugin.
   // The TextMemoryPlugin enable recall via prompt expressions.
   kernel.ImportPluginFromObject(new TextMemoryPlugin(memory));
   

5. Kernel Gunakan objek untuk memanggil perintah yang menyertakan pengenalan memori:

   // Must configure the memory collection, number of memories to recall, and relevance score.
   // The {{...}} syntax represents an expression to Semantic Kernel.
   // For more information on this syntax see:
   // https://learn.microsoft.com/semantic-kernel/prompts/prompt-template-syntax
   string memoryCollection = config["AZURE_OPENAI_MEMORY_NAME"]!;
   string? result = await kernel.InvokePromptAsync<string>(
       "{{recall 'where did I grow up?'}}",
       new()
       {
           [TextMemoryPlugin.CollectionParam] = memoryCollection,
           [TextMemoryPlugin.LimitParam] = "2",
           [TextMemoryPlugin.RelevanceParam] = "0.79",
       }
   );
   Console.WriteLine($"Output: {result}");
   

Menggunakan pengaturan aplikasi untuk menyimpan rahasia koneksi

Jika database vektor tidak mendukung autentikasi Microsoft Entra, Anda dapat menggunakan pengaturan aplikasi App Service untuk menyimpan rahasia koneksi Anda. Dengan menggunakan pengaturan aplikasi, Anda dapat menyimpan rahasia koneksi tanpa menyediakan sumber daya Azure tambahan.

Sebelum mengikuti langkah-langkah ini, ambil string koneksi untuk database vektor Anda. Misalnya, lihat Menggunakan Azure Cache for Redis di .NET Framework.

Menambahkan string koneksi ke pengaturan aplikasi

1. Navigasi ke halaman aplikasi Anda di Portal Microsoft Azure.
2. Di menu sebelah kiri aplikasi, pilih Konfigurasi>Pengaturan aplikasi.
   • Secara default, nilai untuk pengaturan aplikasi disembunyikan di portal untuk keamanan.
   • Untuk melihat nilai tersembunyi dari pengaturan aplikasi, pilih bidang Nilainya.
3. Pilih Pengaturan koneksi baru.
4. Pada layar Tambahkan/Edit string koneksi pilih nilai berikut ini:
   • Nama: Ketik nama untuk pengaturan. Nama pengaturan harus unik.
   • Nilai: String koneksi untuk database vektor Anda.
   • Jenis: Jenis koneksi, Custom jika tidak ada koneksi lain yang berlaku.
   • Biarkan nilai lainnya mengikuti default. Pilih OK.
5. Pilih Simpan kembali di halaman Konfigurasi.

Tambahkan atau edit pengaturan aplikasi dengan perintah az webapp config connection-string setAzure CLI :

az webapp config connection-string set \
--name "<appName>" \
--resource-group "<groupName>" \
--connection-string-type "<connectionType>" \
--settings <connectionName>='<connectionString>'

Menerapkan pengambilan string koneksi dari pengaturan aplikasi

Untuk menggunakan sampel kode berikut, Anda memerlukan pustaka tambahan ini:

• Microsoft.Extensions.Configuration Paket NuGet
• Microsoft.Extensions.Configuration.EnvironmentVariables Paket NuGet

Sampel kode ini menggunakan database Redis, tetapi Anda dapat menerapkannya ke database vektor apa pun yang mendukung string koneksi.

1. Tambahkan variabel lingkungan saat membangun konfigurasi Anda, ini akan memetakan string koneksi Anda ke IConfigurationRoot objek:

   // User secrets let you provide connection strings when testing locally
   // For more info see: https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets
   IConfigurationRoot config = new ConfigurationBuilder()
       .AddUserSecrets<Program>()
       .AddEnvironmentVariables()
       .Build();
   
   // Retrieve the Redis connection string obtained from the app settings.
   // The connection string name should match the entry in application settings
   string redisConnectionString = config.GetConnectionString("AZURE_REDIS")!;
   

2. Gunakan database vektor Anda string koneksi dari pengaturan aplikasi untuk menginisialisasi IMemoryStore objek, lalu gunakan untuk membangun ISemanticTextMemory:

   // Use the connection string to connect to the database
   IDatabase database = (
       await ConnectionMultiplexer.ConnectAsync(redisConnectionString)
   ).GetDatabase();
   
   // The Semantic Kernel SDK provides a connector extension for Redis.
   // Initialize an RedisMemoryStore using your managed identity credentials.
   IMemoryStore memoryStore = new RedisMemoryStore(database);
   
   // Retrieve the endpoint and deployments obtained from the Azure OpenAI deployment.
   // Must use the deployment name not the underlying model name.
   string openAiEndpoint = config["AZURE_OPENAI_ENDPOINT"]!;
   string embeddingModel = config["AZURE_OPENAI_EMBEDDING_NAME"]!;
   
   // Build a SemanticMemoryStore with Azure AI Search as the store.
   // Must also include a text embedding generation service.
   ISemanticTextMemory memory = new MemoryBuilder()
       .WithAzureOpenAITextEmbeddingGeneration(embeddingModel, openAiEndpoint, credentials)
       .WithMemoryStore(memoryStore)
       .Build();
   

3. Buat Kernel objek, lalu impor ISemanticTextMemory objek menggunakan TextMemoryPlugin:

   // Build a Kernel, include a chat completion service.
   string chatModel = config["AZURE_OPENAI_GPT_NAME"]!;
   Kernel kernel = Kernel
       .CreateBuilder()
       .AddAzureOpenAIChatCompletion(chatModel, openAiEndpoint, credentials)
       .Build();
   
   // Import the semantic memory store as a TextMemoryPlugin.
   // The TextMemoryPlugin enable recall via prompt expressions.
   kernel.ImportPluginFromObject(new TextMemoryPlugin(memory));
   

4. Kernel Gunakan objek untuk memanggil perintah yang menyertakan pengenalan memori:

   // Must configure the memory collection, number of memories to recall, and relevance score.
   // The {{...}} syntax represents an expression to Semantic Kernel.
   // For more information on this syntax see:
   // https://learn.microsoft.com/semantic-kernel/prompts/prompt-template-syntax
   string memoryCollection = config["AZURE_OPENAI_MEMORY_NAME"]!;
   string? result = await kernel.InvokePromptAsync<string>(
       "{{recall 'where did I grow up?'}}",
       new()
       {
           [TextMemoryPlugin.CollectionParam] = memoryCollection,
           [TextMemoryPlugin.LimitParam] = "2",
           [TextMemoryPlugin.RelevanceParam] = "0.79",
       }
   );
   Console.WriteLine($"Output: {result}");
   

Konten terkait

• [Gunakan Redis untuk penyimpanan memori dengan Semantic Kernel SDK]
• Cara menggunakan identitas terkelola untuk App Service dan Azure Functions
• Langkah-langkah untuk menetapkan peran Microsoft Azure