Руководство. Использование сеансов интерпретатора кода в семантическом ядре с помощью приложений контейнеров Azure

Семантический ядро — это платформа искусственного интеллекта с открытым кодом, созданная корпорацией Майкрософт для .NET, Python и Java, работающих с крупными языковыми моделями (LLMs). При создании агента ИИ с семантического ядра LLM интерпретирует входные данные пользователя и создает ответ. Агент ИИ часто борется, когда он должен выполнять математические и символические причины для создания ответа. Интеграция динамических сеансов приложений контейнеров Azure с семантического ядра дает агенту интерпретатор кода для выполнения специализированных задач.

В этом руководстве описано, как запустить агент ИИ семантического ядра в веб-API. API принимает входные данные пользователя и возвращает ответ, созданный агентом ИИ. Агент использует интерпретатор кода в динамических сеансах для выполнения вычислений.

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

• Учетная запись Azure с активной подпиской.
  • Если у вас нет учетной записи, вы можете создать ее бесплатно.
• Установите интерфейс командной строки Azure.
• Git.
• Python 3.10 или более поздней версии.

Создание ресурсов Azure

Пример приложения в этом кратком руководстве использует LLM из Azure OpenAI. Он также использует сеансы приложений контейнеров Azure для запуска кода, созданного LLM.

1. Обновите Azure CLI до последней версии.

    az upgrade
   

2. Удалите расширение Azure Container Apps, если оно уже установлено и установите предварительную версию расширения Azure Container Apps, содержащего команды для сеансов:

   az extension remove --name containerapp
   az extension add \
       --name containerapp \
       --allow-preview true -y
   

3. Войдите в Azure.

   az login
   

4. Задайте переменные, используемые в этом кратком руководстве:

   RESOURCE_GROUP_NAME=aca-sessions-tutorial
   AZURE_OPENAI_LOCATION=swedencentral
   AZURE_OPENAI_NAME=<UNIQUE_OPEN_AI_NAME>
   SESSION_POOL_LOCATION=eastasia
   SESSION_POOL_NAME=code-interpreter-pool
   

   Замените <UNIQUE_OPEN_AI_NAME> уникальным именем для создания учетной записи Azure OpenAI.

5. Создание группы ресурсов.

   az group create --name $RESOURCE_GROUP_NAME --location $SESSION_POOL_LOCATION
   

6. Создайте учетную запись Azure OpenAI:

   az cognitiveservices account create \
       --name $AZURE_OPENAI_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $AZURE_OPENAI_LOCATION \
       --kind OpenAI \
       --sku s0 \
       --custom-domain $AZURE_OPENAI_NAME
   

7. Создайте развертывание модели GPT 3.5 Turbo с именем gpt-35-turbo в учетной записи Azure OpenAI:

   az cognitiveservices account deployment create \
       --resource-group $RESOURCE_GROUP_NAME \
       --name $AZURE_OPENAI_NAME \
       --deployment-name gpt-35-turbo \
       --model-name gpt-35-turbo \
       --model-version "1106" \
       --model-format OpenAI \
       --sku-capacity "100" \
       --sku-name "Standard"
   

8. Создайте пул сеансов интерпретатора кода:

   az containerapp sessionpool create \
       --name $SESSION_POOL_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --max-sessions 100 \
       --container-type PythonLTS \
       --cooldown-period 300
   

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

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

Клонирование приложения

1. Клонируйте репозиторий примеров сеансов приложений контейнеров Azure.

   git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
   

2. Перейдите в каталог, содержащий пример приложения:

   cd container-apps-dynamic-sessions-samples/semantic-kernel-python-webapi
   

Настройка приложения

1. Создайте виртуальную среду Python и активируйте ее:

   python3.11 -m venv .venv
   source .venv/bin/activate
   

   Измените версию Python в команде, если вы используете другую версию. Рекомендуется использовать Python 3.10 или более поздней версии.

   Примечание.

   Если вы используете Windows, замените .venv/bin/activate на .venv\Scripts\activate.

2. Установите необходимые пакеты Python:

   python -m pip install -r requirements.txt
   

3. Чтобы запустить приложение, необходимо настроить переменные среды.

   1. Получите конечную точку учетной записи Azure OpenAI:

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.endpoint \
          --output tsv
      

   2. Получите конечную точку управления пулом сеансов контейнеров Azure:

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.poolManagementEndpoint \
          --output tsv
      

   3. .env Создайте файл в корневом каталоге примера приложения (то же расположение, что main.pyи ). Добавьте в этот файл приведенное ниже содержимое.

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      Замените <AZURE_OPENAI_ENDPOINT> конечной точкой учетной записи Azure OpenAI и <SESSION_POOL_MANAGEMENT_ENDPOINT> конечной точкой управления пулом сеансов.

4. Приложение используется DefaultAzureCredential для проверки подлинности с помощью служб Azure. На локальном компьютере используется текущие учетные данные для входа в Azure CLI. Для доступа к конечным точкам модели приложение должно предоставить себе роль пользователя OpenAI Cognitive Services OpenAI, а также роль исполнителя сеансов Azure ContainerApps в пуле сеансов для доступа к пулу сеансов приложения для доступа к пулу сеансов.

   1. Получите имя пользователя Azure CLI:

      az account show --query user.name --output tsv
      

   2. Выполните следующие команды, чтобы получить идентификатор ресурса учетной записи Azure OpenAI:

      az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   3. Назначьте роль пользователя OpenAI Cognitive Services пользователю Azure CLI в учетной записи Azure OpenAI:

      az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
      

      Замените <CLI_USERNAME> именем пользователя Azure CLI и <AZURE_OPENAI_RESOURCE_ID> идентификатором ресурса учетной записи Azure OpenAI.

   4. Выполните следующие команды, чтобы получить идентификатор ресурса пула сеансов:

      az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   5. Назначьте роль исполнителя сеансов Azure ContainerApps с помощью идентификатора пользователю Azure CLI в пуле сеансов:

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <CLI_USERNAME> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

      Замените <CLI_USERNAME> имя пользователя Azure CLI и <SESSION_POOL_RESOURCE_ID> идентификатор ресурса пула сеансов.

Выполнить приложение

Перед запуском примера приложения откройте main.py в редакторе и просмотрите код. Приложение использует FastAPI для создания веб-API, который принимает пользовательское сообщение в строке запроса.

Следующие строки кода создайте экземпляр SessionPythonTool и предоставьте его агенту семантического ядра:

sessions_tool = SessionsPythonTool(
    pool_management_endpoint,
    auth_callback=auth_callback_factory("https://dynamicsessions.io/.default"),
)
kernel.add_plugin(sessions_tool, "SessionsTool")

При выполнении вычислений ядро использует интерпретатор кода в SessionPythonTool для выполнения кода. Код выполняется в сеансе в пуле сеансов. По умолчанию при создании экземпляра средства создается идентификатор случайного сеанса. Если ядро использует средство для запуска нескольких фрагментов кода Python, он использует один и тот же сеанс. Чтобы убедиться, что каждый пользователь имеет уникальный сеанс, используйте отдельное ядро и средство для каждого пользователя.

SessionPythonTool доступен в версии или более поздней semantic-kernel версии 0.9.8b1 пакета.

1. Запустите пример приложения:

   fastapi dev main.py
   

2. Откройте веб-браузер и перейдите по адресу http://localhost:8000/docs. Вы увидите пользовательский интерфейс Swagger для примера приложения.

3. Разверните конечную точку /chat и выберите "Попробовать".

4. Введите What time is it right now? поле message и нажмите кнопку "Выполнить".

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

5. Чтобы остановить приложение, введите Ctrl+C в терминале.

Необязательно. Развертывание примера приложения в приложениях контейнеров Azure

Чтобы развернуть приложение FastAPI в приложениях контейнеров Azure, необходимо создать образ контейнера и отправить его в реестр контейнеров. Затем вы можете развернуть образ в приложениях контейнеров Azure. Команда az containerapp up объединяет эти шаги в одну команду.

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

1. Задайте переменные для среды "Приложения контейнеров" и имени приложения:

   ENVIRONMENT_NAME=aca-sessions-tutorial-env
   CONTAINER_APP_NAME=chat-api
   

2. Создайте и разверните приложение в приложениях контейнеров Azure:

   az containerapp up \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --environment $ENVIRONMENT_NAME \
       --env-vars "AZURE_OPENAI_ENDPOINT=<OPEN_AI_ENDPOINT>" "POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGMENT_ENDPOINT>" \
       --source .
   

   Замените <OPEN_AI_ENDPOINT> конечной точкой учетной записи Azure OpenAI и <SESSION_POOL_MANAGMENT_ENDPOINT> конечной точкой управления пулом сеансов.

3. Включите управляемое удостоверение, назначаемое системой для приложения:

   az containerapp identity assign \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --system-assigned
   

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

   1. Получите идентификатор субъекта управляемого удостоверения:

      az containerapp show \
          --name $CONTAINER_APP_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query identity.principalId \
          --output tsv
      

   2. Получение идентификатора ресурса пула сеансов:

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   3. Назначьте управляемое удостоверение Azure ContainerApps Session Executor и Contributor роли в пуле сеансов:

      Перед выполнением следующей команды замените <PRINCIPAL_ID> значения <SESSION_POOL_RESOURCE_ID> , полученные на предыдущих шагах.

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      
      az role assignment create \
          --role "Contributor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

   4. Получите идентификатор ресурса учетной записи Azure OpenAI:

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   5. Назначьте управляемое удостоверение Cognitive Services OpenAI User роли в учетной записи Azure OpenAI:

      Перед выполнением следующей команды замените <PRINCIPAL_ID> значения <AZURE_OPENAI_RESOURCE_ID> , полученные на предыдущих шагах.

      az role assignment create \
          --role "Cognitive Services OpenAI User" \
          --assignee <PRINCIPAL_ID> \
          --scope <AZURE_OPENAI_RESOURCE_ID>
      

5. Получение полного доменного имени приложения (FQDN):

   az containerapp show \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --query properties.configuration.ingress.fqdn \
       --output tsv
   

6. Откройте браузер для https://<FQDN>/docs тестирования развернутого приложения.

Очистка ресурсов

После завершения работы с ресурсами их можно удалить, чтобы избежать расходов:

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

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

Сеансы интерпретатора кода