Sdílet prostřednictvím

Ověřování a autorizace služby App Service pro vektorovou databázi

  • Článek

Tento článek ukazuje, jak spravovat připojení mezi vaší aplikací App Service .NET a řešením vektorové databáze. Popisuje použití spravovaných identit Microsoft Entra pro podporované služby a bezpečné ukládání připojovací řetězec pro ostatní.

Přidáním vektorové databáze do aplikace můžete povolit sémantické paměti pro vaši AI. Sémantická sada SDK jádra pro .NET umožňuje snadno implementovat úložiště paměti a odvolání pomocí preferovaného řešení vektorové databáze.

Požadavky

Použití spravované identity Microsoft Entra k ověřování

Pokud služba vektorové databáze podporuje ověřování Microsoft Entra, můžete pomocí spravované identity se službou App Service bezpečně přistupovat k vektorové databázi, aniž byste museli zřizovat nebo obměňovat tajné kódy ručně. Seznam služeb Azure, které podporují ověřování Microsoft Entra, najdete v tématu Služby Azure, které podporují ověřování Microsoft Entra.

Přidání spravované identity do služby App Service

Vaší aplikaci je možné udělit dva typy identit:

  • Identita přiřazená systémem je svázaná s vaší aplikací a při odstranění aplikace se odstraní. Aplikace může mít pouze jednu identitu přiřazenou systémem.
  • Identita přiřazená uživatelem je samostatný prostředek Azure, který je možné přiřadit k vaší aplikaci. Aplikace může mít více identit přiřazených uživatelem.

Přidání identity přiřazené systémem

  1. Na webu Azure Portal přejděte na stránku aplikace a posuňte se dolů ke skupině Nastavení.
  2. Vyberte Identita.
  3. Na kartě Přiřazený systém přepněte stav na Zapnuto a pak vyberte Uložit.

Spuštěním az webapp identity assign příkazu vytvořte identitu přiřazenou systémem:

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

Přidání identity přiřazené uživatelem

Pokud chcete do aplikace přidat identitu přiřazenou uživatelem, vytvořte identitu a pak do konfigurace aplikace přidejte její identifikátor prostředku.

  1. Podle těchto pokynů vytvořte prostředek spravované identity přiřazené uživatelem.

  2. V levém navigačním podokně stránky aplikace se posuňte dolů ke skupině Nastavení.

  3. Vyberte Identita.

  4. Vyberte Přidat přiřazený>uživatelem.

  5. Vyhledejte identitu, kterou jste vytvořili dříve, vyberte ji a pak vyberte Přidat.

    Důležité

    Po výběru možnosti Přidat se aplikace restartuje.

  1. Vytvořte identitu přiřazenou uživatelem:

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

  2. Přiřaďte identitu k aplikaci:

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

Přidání role Azure do spravované identity

  1. Na webu Azure Portal přejděte do oboru, kterému chcete udělit přístup k vektorové databázi. Oborem může být skupina pro správu, předplatné, skupina prostředků nebo konkrétní prostředek Azure.
  2. V levém navigačním podokně vyberte Řízení přístupu (IAM).
  3. Vyberte Přidat a pak vyberte Přidat přiřazení role.
  4. Na kartě Role vyberte příslušnou roli, která uděluje přístup pro čtení k vaší vektorové databázi.
  5. Na kartě Členové vyberte spravovanou identitu.
  6. Na kartě Zkontrolovat a přiřadit vyberte možnost Zkontrolovat a přiřadit a přiřaďte roli.

Rozsah prostředků

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

Rozsah skupiny prostředků

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

Rozsah předplatného

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

Rozsah skupiny pro správu

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

Implementace ověřování založeného na tokenech s vektorovou databází

Následující ukázky kódu vyžadují tyto další knihovny:

  1. Inicializace objektu DefaultAzureCredential pro vyzvednutí spravované identity vaší aplikace:

    // 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. Inicializace objektu IMemoryStore pro vektorovou databázi a jeho následné použití k vytvoření 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. Sestavte Kernel objekt a pak objekt naimportujte ISemanticTextMemory pomocí příkazu 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. Pomocí objektu Kernel můžete vyvolat výzvu, která obsahuje odvolání paměti:

    // 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}");

Použití služby Key Vault k ukládání tajných kódů připojení

Pokud vektorová databáze nepodporuje ověřování Microsoft Entra, můžete pomocí služby Key Vault uložit tajné kódy připojení a načíst je pomocí aplikace App Service. Pomocí služby Key Vault k ukládání tajných kódů připojení je můžete sdílet s více aplikacemi a řídit přístup k jednotlivým tajným kódům na aplikaci.

Než budete postupovat podle těchto kroků, načtěte připojovací řetězec pro vaši vektorovou databázi. Podívejte se například na použití Azure Cache for Redis s webovou aplikací ASP.NET Core.

Přidání připojovací řetězec do služby Key Vault

Důležité

Než budete postupovat podle těchto kroků, ujistěte se, že jste vytvořili službu Key Vault pomocí webu Azure Portal.

  1. Na webu Azure Portal přejděte ke svému trezoru klíčů.
  2. V levém navigačním panelu služby Key Vault vyberte Objekty a pak vyberte Tajné kódy.
  3. Vyberte + Generovat/Importovat.
  4. Na obrazovce Vytvořit tajný kód zvolte následující hodnoty:
    • Možnosti nahrávání: Manual.
    • Název: Zadejte název tajného kódu. Název tajného kódu musí být v rámci služby Key Vault jedinečný.
    • Hodnota: připojovací řetězec pro vaši vektorové databáze.
    • U ostatních hodnot ponechte jejich výchozí nastavení. Vyberte Vytvořit.
  5. Když se zobrazí zpráva o úspěšném vytvoření tajného kódu, je připravená k použití ve vaší aplikaci.

Důležité

Než budete postupovat podle těchto kroků, ujistěte se, že jste vytvořili službu Key Vault pomocí Azure CLI.

  1. Udělte svému trezoru klíčů oprávnění k účtu uživatele prostřednictvím řízení přístupu na základě role (RBAC), přiřaďte roli pomocí příkazu 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. Přidejte připojovací řetězec do služby Key Vault pomocí příkazu az keyvault secret setAzure CLI:

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

Udělení přístupu ke službě App Service ke službě Key Vault

  1. Přiřaďte spravovanou identitu ke službě App Service.
  2. Přidejte role Key Vault Secrets User a Key Vault Reader role do spravované identity.

Implementace načítání připojovací řetězec ze služby Key Vault

Pokud chcete použít následující ukázky kódu, potřebujete tyto další knihovny:

Tyto ukázky kódu používají databázi Redis, ale můžete je použít na libovolnou vektorovou databázi, která podporuje připojovací řetězec.

  1. Inicializace objektu DefaultAzureCredential pro vyzvednutí spravované identity vaší aplikace:

    // 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. Přidejte službu Key Vault při vytváření konfigurace. Tím se namapuje tajné kódy služby Key Vault na IConfigurationRoot objekt:

    // 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. Pomocí vektorové databáze připojovací řetězec ze služby Key Vault inicializovat IMemoryStore objekt a pak ho použít k vytvoření objektuISemanticTextMemory:

    // 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. Sestavte Kernel objekt a pak objekt naimportujte ISemanticTextMemory pomocí příkazu 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. Pomocí objektu Kernel můžete vyvolat výzvu, která obsahuje odvolání paměti:

    // 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}");

Ukládání tajných kódů připojení pomocí nastavení aplikace

Pokud vektorová databáze nepodporuje ověřování Microsoft Entra, můžete k ukládání tajných kódů připojení použít nastavení aplikace služby App Service. Pomocí nastavení aplikace můžete ukládat tajné kódy připojení, aniž byste zřídili další prostředky Azure.

Než budete postupovat podle těchto kroků, načtěte připojovací řetězec pro vaši vektorovou databázi. Příklad najdete v tématu Použití služby Azure Cache for Redis v rozhraní .NET Framework.

Přidání připojovací řetězec do nastavení aplikace

  1. Na webu Azure Portal přejděte na stránku vaší aplikace.
  2. V nabídce vlevo aplikace vyberte Nastavení konfigurační>aplikace.
    • Ve výchozím nastavení jsou hodnoty pro nastavení aplikace skryté na portálu pro zabezpečení.
    • Pokud chcete zobrazit skrytou hodnotu nastavení aplikace, vyberte její pole Hodnota.
  3. Vyberte Nové nastavení připojení.
  4. Na obrazovce Přidat nebo upravit připojovací řetězec zvolte následující hodnoty:
    • Název: Zadejte název nastavení. Název nastavení musí být jedinečný.
    • Hodnota: připojovací řetězec pro vaši vektorové databáze.
    • Typ: Typ připojení, Custom pokud žádné jiné nepoužijí.
    • U ostatních hodnot ponechte jejich výchozí nastavení. Vyberte OK.
  5. Na stránce Konfigurace vyberte Uložit zpět.

Přidání nebo úprava nastavení aplikace pomocí příkazu 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>'

Implementace načítání připojovací řetězec z nastavení aplikace

Pokud chcete použít následující ukázky kódu, potřebujete tyto další knihovny:

Tyto ukázky kódu používají databázi Redis, ale můžete je použít na libovolnou vektorovou databázi, která podporuje připojovací řetězec.

  1. Při sestavování konfigurace přidejte proměnné prostředí, které mapují vaše připojovací řetězec na IConfigurationRoot objekt:

    // 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. K inicializaci objektu IMemoryStore použijte vektorovou databázi připojovací řetězec z nastavení aplikace a pak ji použijte k vytvoření objektuISemanticTextMemory:

    // 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. Sestavte Kernel objekt a pak objekt naimportujte ISemanticTextMemory pomocí příkazu 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. Pomocí objektu Kernel můžete vyvolat výzvu, která obsahuje odvolání paměti:

    // 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}");

Související obsah