Разработка приложений служб ИИ Azure с помощью Key Vault

  • Статья

Узнайте, как безопасно разрабатывать приложения служб ИИ Azure с помощью Azure Key Vault.

Key Vault снижает риск случайной утечки секретов, так как в приложении не сохраняется информация о безопасности.

Необходимые компоненты

Примечание.

Ознакомьтесь с документацией и краткими руководствами по службе искусственного интеллекта Azure, которую вы используете для получения сведений о следующих статьях:

  • учетные данные и другие сведения, необходимые для отправки вызовов API;
  • пакеты и код, необходимые для работы приложения.

Получение учетных данных из ресурса служб искусственного интеллекта Azure

Прежде чем добавлять учетные данные в хранилище ключей Azure, необходимо получить их из ресурса служб искусственного интеллекта Azure. Например, если службе требуется ключ и конечная точка, их можно найти, выполнив следующие действия:

  1. На портале Azure перейдите к своему ресурсу Azure.

  2. В свертываемом меню слева выберите элемент Ключи и конечная точка.

    A screenshot showing the key and endpoint page in the Azure portal.

Для проверки подлинности вызовов API для некоторых служб ИИ Azure требуются различные сведения, такие как ключ и регион. Прежде чем продолжить, обязательно получите эти сведения.

Добавление учетных данных в хранилище ключей

Чтобы приложение могла получить и использовать учетные данные для проверки подлинности вызовов API, такие данные необходимо добавить в секреты хранилища ключей.

Повторите эти действия, чтобы создать секрет для всех требуемых учетных данных ресурса, например для ключа и конечной точки. Эти имена секретов будут использоваться позже для проверки подлинности приложения.

  1. Откройте новую вкладку или окно браузера. Перейдите в хранилище ключей в портал Azure.

  2. В свертываемом меню слева выберите элементы Объекты>Секреты.

  3. Выберите Создать/импортировать.

    A screenshot showing the key vault key page in the Azure portal.

  4. На экране Создание секрета введите следующие значения:

    Имя. Значение
    Параметры отправки Руководство
    Имя. Имя секрета для ключа или конечной точки, например CognitiveServicesKey или CognitiveServicesEndpoint.
    Значение Ключ ресурса или конечная точка служб искусственного интеллекта Azure.

    Позже приложение будет использовать секрет Name для безопасного доступа к Value.

  5. Оставьте другие значения по умолчанию. Нажмите кнопку создания.

    Совет

    Обязательно запомните имена, заданные для секретов, так как позднее они будут использоваться в приложении.

Теперь у вас должны быть именованные секреты для сведений о ресурсе.

Создание переменной среды для имени хранилища ключей

Рекомендуем создать переменную среды для имени хранилища ключей Azure. Приложение считывает эту переменную среды во время выполнения, чтобы получить сведения о ключе и конечной точке.

Чтобы задать переменные среды, используйте одну из следующих команд. Замените KEY_VAULT_NAME именем переменной среды, а — Your-Key-Vault-Name именем хранилища ключей, которое будет храниться в переменной среды.

Создайте хранимую переменную среды и присвойте ей значение.

setx KEY_VAULT_NAME "Your-Key-Vault-Name"

В новом экземпляре командной строки считывает переменную среды.

echo %KEY_VAULT_NAME%

Проверка подлинности в Azure с использованием Visual Studio

Разработчики, использующие Visual Studio 2017 или более поздней версии, могут пройти проверку подлинности учетной записи Microsoft Entra через Visual Studio. Это позволяет получить доступ к секретам в хранилище ключей, выполнив вход в подписку Azure из IDE.

Чтобы выполнить проверку подлинности в Visual Studio, выберите элемент Средства сверху в меню навигации и выберите пункт Параметры. Перейдите к параметру Проверка подлинности служб Azure, чтобы войти в систему с использованием имени пользователя и пароля.

Проверка подлинности с помощью командной строки

Прежде чем предоставить доступ к хранилищу ключей, необходимо пройти проверку подлинности с помощью имени пользователя и пароля Microsoft Entra.

Для проверки подлинности с помощью Azure CLI выполните команду az login.

az login

В системах с веб-браузером по умолчанию Azure CLI запустит браузер для проверки подлинности. Для систем без веб-браузера по умолчанию команда az login будет использовать поток проверки подлинности в коде устройства. Вы можете принудительно указать Azure CLI использовать поток кода устройства, а не запускать браузер с аргументом --use-device-code.

Если у вас несколько подписок, обязательно выберите подписку Azure, содержащую хранилище ключей.

Предоставление доступа к хранилищу ключей

Создайте для хранилища ключей политику доступа, которая предоставляет учетной записи пользователя разрешения на использование секрета.

Чтобы установить политику доступа, выполните команду az keyvault set-policy. Замените Your-Key-Vault-Name именем своего хранилища ключей. Замените user@domain.com имя пользователя Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Создание нового приложения C#

С помощью интегрированной среды разработки Visual Studio создайте консольное приложение .NET Core. Будет создан проект Hello World с одним исходным файлом C#: program.cs

Установите следующие клиентские библиотеки, щелкнув правой кнопкой мыши решение в Обозревателе решений и выбрав Управление пакетами NuGet. В открывшемся диспетчере пакетов выберите элемент Обзор и выполните поиск по следующим библиотекам. Затем выберите команду Установить для каждой из них.

  • Azure.Security.KeyVault.Secrets
  • Azure.Identity

Импорт примера кода

Скопируйте следующий код в свой файл program.cs. Замените Your-Key-Secret-Name и Your-Endpoint-Secret-Name именами секретов, которые вы задали в хранилище ключей.

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using System.Net;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            //Name of your key vault
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");

            //variables for retrieving the key and endpoint from your key vault.
            //Set these variables to the names you created for your secrets
            const string keySecretName = "Your-Key-Secret-Name";
            const string endpointSecretName = "Your-Endpoint-Secret-Name";

            //Endpoint for accessing your key vault
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var keyVaultClient = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.WriteLine($"Retrieving your secrets from {keyVaultName}.");

            //Key and endpoint secrets retrieved from your key vault
            var keySecret = await keyVaultClient.GetSecretAsync(keySecretName);
            var endpointSecret = await keyVaultClient.GetSecretAsync(endpointSecretName);
            Console.WriteLine($"Your key secret value is: {keySecret.Value.Value}");
            Console.WriteLine($"Your endpoint secret value is: {endpointSecret.Value.Value}");
            Console.WriteLine("Secrets retrieved successfully");

        }
    }
}

Выполнение приложения

Запустите приложение, нажав кнопку Отладка в верхней части окна Visual Studio. Из хранилища ключей будут извлечены секреты ключа и конечной точки.

Отправка тестового вызова службы языка (необязательно)

Если вы используете ресурс с несколькими службами или ресурс языковой службы, вы можете обновить свое приложение, выполнив следующие действия. Это позволит отправить пример вызова Распознавания именованных сущностей с извлечением ключа и конечной точки из хранилища ключей.

  1. Установите библиотеку Azure.AI.TextAnalytics, щелкнув правой кнопкой мыши решение в обозревателе решений и выбрав элемент Управление пакетами NuGet. В открывшемся диспетчере пакетов выберите элемент Обзор и выполните поиск по следующим библиотекам. Затем выберите команду Установить для каждой из них.

  2. Добавьте следующую директиву в начало своего файла program.cs.

    using Azure.AI.TextAnalytics;

  3. Добавьте следующий пример кода в свое приложение.

    // Example method for extracting named entities from text 
private static void EntityRecognitionExample(string keySecret, string endpointSecret)
{
    //String to be sent for Named Entity Recognition
    var exampleString = "I had a wonderful trip to Seattle last week.";

    AzureKeyCredential azureKeyCredential = new AzureKeyCredential(keySecret);
    Uri endpoint = new Uri(endpointSecret);
    var languageServiceClient = new TextAnalyticsClient(endpoint, azureKeyCredential);

    Console.WriteLine($"Sending a Named Entity Recognition (NER) request");
    var response = languageServiceClient.RecognizeEntities(exampleString);
    Console.WriteLine("Named Entities:");
    foreach (var entity in response.Value)
    {
        Console.WriteLine($"\tText: {entity.Text},\tCategory: {entity.Category},\tSub-Category: {entity.SubCategory}");
        Console.WriteLine($"\t\tScore: {entity.ConfidenceScore:F2},\tLength: {entity.Length},\tOffset: {entity.Offset}\n");
    }
}

  4. Добавьте следующий код для вызова EntityRecognitionExample() из основного метода, указав значения ключа и конечной точки.

    EntityRecognitionExample(keySecret.Value.Value, endpointSecret.Value.Value);

  5. Запустите приложение.

Аутентификация приложения

Прежде чем предоставить доступ к хранилищу ключей, необходимо пройти проверку подлинности с помощью имени пользователя и пароля Microsoft Entra.

Для проверки подлинности с помощью Azure CLI выполните команду az login.

az login

В системах с веб-браузером по умолчанию Azure CLI запустит браузер для проверки подлинности. Для систем без веб-браузера по умолчанию команда az login будет использовать поток проверки подлинности в коде устройства. Вы можете принудительно указать Azure CLI использовать поток кода устройства, а не запускать браузер с аргументом --use-device-code.

Если у вас несколько подписок, обязательно выберите подписку Azure, содержащую хранилище ключей.

Предоставление доступа к хранилищу ключей

Создайте для хранилища ключей политику доступа, которая предоставляет учетной записи пользователя разрешения на использование секрета.

Чтобы установить политику доступа, выполните команду az keyvault set-policy. Замените Your-Key-Vault-Name именем своего хранилища ключей. Замените user@domain.com имя пользователя Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Создание приложения Python

Создайте папку с именем keyVaultExample. Затем с помощью предпочитаемого редактора кода создайте файл с именем program.py в созданной папке.

Установка Key Vault и пакетов языковых служб

  1. В терминале или командной строке перейдите в папку проекта и установите библиотеку удостоверений Microsoft Entra:

    pip install azure-identity

  2. Установите библиотеку секретов Azure Key Vault:

    pip install azure-keyvault-secrets

Импорт примера кода

Добавьте в файл с именем program.py следующий пример кода. Замените Your-Key-Secret-Name и Your-Endpoint-Secret-Name именами секретов, которые вы задали в хранилище ключей.

import os
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
from azure.core.credentials import AzureKeyCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]

# Set these variables to the names you created for your secrets
keySecretName = "Your-Key-Secret-Name"
endpointSecretName = "Your-Endpoint-Secret-Name"

# URI for accessing key vault
KVUri = f"https://{keyVaultName}.vault.azure.net"

# Instantiate the client and retrieve secrets
credential = DefaultAzureCredential()
kv_client = SecretClient(vault_url=KVUri, credential=credential)

print(f"Retrieving your secrets from {keyVaultName}.")

retrieved_key = kv_client.get_secret(keySecretName).value
retrieved_endpoint = kv_client.get_secret(endpointSecretName).value

print(f"Your secret key value is {retrieved_key}.");
print(f"Your secret endpoint value is {retrieved_endpoint}.");

Выполнение приложения

Запустите приложение с помощью следующей команды. Из хранилища ключей будут извлечены секреты ключа и конечной точки.

python ./program.py

Отправка тестового вызова службы языка (необязательно)

Если вы используете ресурс с несколькими службами или ресурс языковой службы, вы можете обновить свое приложение, выполнив следующие действия. Это позволит отправить пример вызова Распознавания именованных сущностей с извлечением ключа и конечной точки из хранилища ключей.

  1. Установите библиотеку языковой службы:

    pip install azure-ai-textanalytics==5.1.0

  2. Добавьте в приложение следующий код:

    from azure.ai.textanalytics import TextAnalyticsClient
# Authenticate the key vault secrets client using your key and endpoint 
azure_key_credential = AzureKeyCredential(retrieved_key)
# Now you can use key vault credentials with the Language service
language_service_client = TextAnalyticsClient(
    endpoint=retrieved_endpoint, 
    credential=azure_key_credential)

# Example of recognizing entities from text

print("Sending NER request")

try:
    documents = ["I had a wonderful trip to Seattle last week."]
    result = language_service_client.recognize_entities(documents = documents)[0]
    print("Named Entities:\n")
    for entity in result.entities:
        print("\tText: \t", entity.text, "\tCategory: \t", entity.category, "\tSubCategory: \t", entity.subcategory,
                "\n\tConfidence Score: \t", round(entity.confidence_score, 2), "\tLength: \t", entity.length, "\tOffset: \t", entity.offset, "\n")

except Exception as err:
    print("Encountered exception. {}".format(err))

  3. Запустите приложение.

Аутентификация приложения

Прежде чем предоставить доступ к хранилищу ключей, необходимо пройти проверку подлинности с помощью имени пользователя и пароля Microsoft Entra.

Для проверки подлинности с помощью Azure CLI выполните команду az login.

az login

В системах с веб-браузером по умолчанию Azure CLI запустит браузер для проверки подлинности. Для систем без веб-браузера по умолчанию команда az login будет использовать поток проверки подлинности в коде устройства. Вы можете принудительно указать Azure CLI использовать поток кода устройства, а не запускать браузер с аргументом --use-device-code.

Если у вас несколько подписок, обязательно выберите подписку Azure, содержащую хранилище ключей.

Предоставление доступа к хранилищу ключей

Создайте для хранилища ключей политику доступа, которая предоставляет учетной записи пользователя разрешения на использование секрета.

Чтобы установить политику доступа, выполните команду az keyvault set-policy. Замените Your-Key-Vault-Name именем своего хранилища ключей. Замените user@domain.com имя пользователя Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Создание приложения Java

В предпочитаемой IDE создайте проект консольного приложения Java и класс с именем Example.

Добавление зависимостей

В своем проекте добавьте в файл pom.xml следующие зависимости.

<dependencies>

        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-security-keyvault-secrets</artifactId>
            <version>4.2.3</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.2.0</version>
        </dependency>
    </dependencies>

Импорт примера кода

Скопируйте следующий код в файл Example.java. Замените Your-Key-Secret-Name и Your-Endpoint-Secret-Name именами секретов, которые вы задали в хранилище ключей.

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.core.credential.AzureKeyCredential;

public class Example {

    public static void main(String[] args) {

        String keyVaultName = System.getenv("KEY_VAULT_NAME");
        String keyVaultUri = "https://" + keyVaultName + ".vault.azure.net";

        //variables for retrieving the key and endpoint from your key vault.
        //Set these variables to the names you created for your secrets
        String keySecretName = "Your-Key-Secret-Name";
        String endpointSecretName = "Your-Endpoint-Secret-Name";

        //Create key vault secrets client
        SecretClient secretClient = new SecretClientBuilder()
                .vaultUrl(keyVaultUri)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();

        //retrieve key and endpoint from key vault
        String keyValue = secretClient.getSecret(keySecretName).getValue();
        String endpointValue = secretClient.getSecret(endpointSecretName).getValue();
        System.out.printf("Your secret key value is: %s", keyValue)
        System.out.printf("Your secret endpoint value is: %s", endpointValue)
    }
}

Отправка тестового вызова службы языка (необязательно)

Если вы используете ресурс с несколькими службами или ресурс языковой службы, вы можете обновить свое приложение, выполнив следующие действия. Это позволит отправить пример вызова Распознавания именованных сущностей с извлечением ключа и конечной точки из хранилища ключей.

  1. В своем приложении добавьте следующую зависимость:

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
    <version>5.1.12</version>
</dependency>

  2. Добавьте следующие инструкции импорта в файл.

    import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;

  3. Добавьте в метод main() следующий код:

    
TextAnalyticsClient languageClient = new TextAnalyticsClientBuilder()
        .credential(new AzureKeyCredential(keyValue))
        .endpoint(endpointValue)
        .buildClient();

// Example for recognizing entities in text
String text = "I had a wonderful trip to Seattle last week.";

for (CategorizedEntity entity : languageClient.recognizeEntities(text)) {
    System.out.printf(
            "Recognized entity: %s, entity category: %s, entity sub-category: %s, score: %s, offset: %s, length: %s.%n",
            entity.getText(),
            entity.getCategory(),
            entity.getSubcategory(),
            entity.getConfidenceScore(),
            entity.getOffset(),
            entity.getLength());
}

  4. Запуск приложения

Аутентификация приложения

Прежде чем предоставить доступ к хранилищу ключей, необходимо пройти проверку подлинности с помощью имени пользователя и пароля Microsoft Entra.

Для проверки подлинности с помощью Azure CLI выполните команду az login.

az login

В системах с веб-браузером по умолчанию Azure CLI запустит браузер для проверки подлинности. Для систем без веб-браузера по умолчанию команда az login будет использовать поток проверки подлинности в коде устройства. Вы можете принудительно указать Azure CLI использовать поток кода устройства, а не запускать браузер с аргументом --use-device-code.

Если у вас несколько подписок, обязательно выберите подписку Azure, содержащую хранилище ключей.

Предоставление доступа к хранилищу ключей

Создайте для хранилища ключей политику доступа, которая предоставляет учетной записи пользователя разрешения на использование секрета.

Чтобы установить политику доступа, выполните команду az keyvault set-policy. Замените Your-Key-Vault-Name именем своего хранилища ключей. Замените user@domain.com имя пользователя Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Создание нового приложения Node.js

Создайте приложение Node.js, использующее ваше хранилище ключей.

В терминале создайте папку с именем key-vault-js-example и измените в этой папке:

mkdir key-vault-js-example && cd key-vault-js-example

Инициализация проекта Node.js:

npm init -y

Установка Key Vault и пакетов языковых служб

  1. С помощью терминала установите библиотеку секретов Azure Key Vault, @azure/keyvault-secrets для Node.js.

    npm install @azure/keyvault-secrets

  2. Установите библиотеку удостоверений Azure, пакет @azure/identity для проверки подлинности в Key Vault.

    npm install @azure/identity

Импорт примера кода

Добавьте в файл с именем index.js следующий пример кода. Замените Your-Key-Secret-Name и Your-Endpoint-Secret-Name именами секретов, которые вы задали в хранилище ключей.

const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");
// Load the .env file if it exists
const dotenv = require("dotenv");
dotenv.config();

async function main() {
    const credential = new DefaultAzureCredential();

    const keyVaultName = process.env["KEY_VAULT_NAME"];
    const url = "https://" + keyVaultName + ".vault.azure.net";

    const kvClient = new SecretClient(url, credential);

    // Set these variables to the names you created for your secrets
    const keySecretName = "Your-Key-Secret-Name";
    const endpointSecretName = "Your-Endpoint-Secret-Name";

    console.log("Retrieving secrets from ", keyVaultName);
    const retrievedKey = await (await kvClient.getSecret(keySecretName)).value;
    const retrievedEndpoint = await (await kvClient.getSecret(endpointSecretName)).value;
    console.log("Your secret key value is: ", retrievedKey);
    console.log("Your secret endpoint value is: ", retrievedEndpoint);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Запуск примера приложения

Запустите приложение с помощью следующей команды. Из хранилища ключей будут извлечены секреты ключа и конечной точки.

node index.js

Отправка тестового вызова службы языка (необязательно)

Если вы используете ресурс с несколькими службами или ресурс языковой службы, вы можете обновить свое приложение, выполнив следующие действия. Это позволит отправить пример вызова Распознавания именованных сущностей с извлечением ключа и конечной точки из хранилища ключей.

  1. Установите службу ИИ Azure для языковой библиотеки, @azure/ai-text-analytics для отправки запросов API в языковую службу.

    npm install @azure/ai-text-analytics@5.1.0

  2. Добавьте в приложение следующий код:

    const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
// Authenticate the language client with your key and endpoint
const languageClient = new TextAnalyticsClient(retrievedEndpoint,  new AzureKeyCredential(retrievedKey));

// Example for recognizing entities in text
console.log("Sending NER request")
const entityInputs = [
    "I had a wonderful trip to Seattle last week."
];
const entityResults = await languageClient.recognizeEntities(entityInputs);
entityResults.forEach(document => {
    console.log(`Document ID: ${document.id}`);
    document.entities.forEach(entity => {
        console.log(`\tName: ${entity.text} \tCategory: ${entity.category} \tSubcategory: ${entity.subCategory ? entity.subCategory : "N/A"}`);
        console.log(`\tScore: ${entity.confidenceScore}`);
    });
});

  3. Запустите приложение.

Следующие шаги