你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

教程：将语义内核中的代码解释器会话与 Azure 容器应用配合使用

项目
11/19/2024

语义内核是 Microsoft 为使用大型语言模型 (LLM) 的 .NET、Python 和 Java 开发人员创建的开源 AI 框架。当你使用语义内核生成 AI 代理时，LLM 会解释用户输入并生成响应。当 AI 代理需要执行数学和符号推理来生成响应时，它通常会遇到困难。通过将 Azure 容器应用动态会话与语义内核集成，可以为代理提供代码解释器以用于执行专业任务。

本教程介绍如何在 Web API 中运行语义内核 AI 代理。 API 接受用户输入并返回由 AI 代理生成的响应。代理在动态会话中使用代码解释器来执行计算。

先决条件

具有活动订阅的 Azure 帐户。
- 如果没有帐户，可以免费创建一个帐户。
安装 Azure CLI。
Git。
Python 3.10 或更高版本。

创建 Azure 资源

本快速入门中的示例应用使用 Azure OpenAI 中的 LLM。它还使用 Azure 容器应用会话来运行由 LLM 生成的代码。

将 Azure CLI 更新到最新版本。
```
 az upgrade
```
如果 Azure 容器应用扩展已安装，请将其删除，然后安装包含会话命令的 Azure 容器应用扩展的预览版本：
```
az extension remove --name containerapp
az extension add \
    --name containerapp \
    --allow-preview true -y
```
登录 Azure：
```
az login
```

设置本快速入门中使用的变量：

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 帐户的唯一名称。

创建资源组：

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

创建 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

在 Azure OpenAI 帐户中创建名为 gpt-35-turbo 的 GPT 3.5 Turbo 模型部署：

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"

创建代码解释器会话池：

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 容器应用之前，可以在本地运行它以对其进行测试。

克隆应用

克隆 Azure 容器应用会话示例存储库。

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

更改为包含示例应用的目录：

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

配置应用

创建 Python 虚拟环境并激活它：
```
python3.11 -m venv .venv
source .venv/bin/activate
```
如果使用其他版本，请更改命令中的 Python 版本。建议使用 Python 3.10 或更高版本。

注意

如果使用的是 Windows，请将 .venv/bin/activate 替换为 .venv\Scripts\activate。

安装所需的 Python 包：

python -m pip install -r requirements.txt

若要运行应用，需要配置数据源环境变量。

检索 Azure OpenAI 帐户终结点：

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

检索 Azure 容器应用会话池管理终结点：

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

在示例应用目录的根目录中创建 .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> 替换为会话池管理终结点。

该应用使用 DefaultAzureCredential 通过 Azure 服务进行身份验证。在本地计算机上，它使用当前的 Azure CLI 登录凭据。必须在 Azure OpenAI 帐户上为自己提供“认知服务 OpenAI 用户”角色，以便应用能够访问模型端点，并在会话池上为自己指定“Azure ContainerApps 会话执行者”角色，以便该应用能够访问会话池。
1. 检索 Azure CLI 用户名：
```
az account show --query user.name --output tsv
```
2. 运行以下命令以检索 Azure OpenAI 帐户资源 ID：
```
az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
```
3. 将“认知服务 OpenAI 用户”角色分配给 Azure OpenAI 帐户上的 Azure CLI 用户：
```
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 帐户资源 ID。
4. 运行以下命令以检索会话池资源 ID：
```
az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
```
5. 使用 ID 将“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> 替换为会话池资源 ID。

运行应用

在运行示例应用之前，请在编辑器中打开 main.py 并查看代码。该应用使用 FastAPI 来创建接受查询字符串中的用户消息的 Web API。

以下代码行实例化 SessionsPythonTool 并将其提供给语义内核代理：

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

需要执行计算时，内核将使用 SessionsPythonTool 中的代码解释器来运行代码。该代码在会话池的会话中执行。默认情况下，实例化该工具时会生成随机会话标识符。如果内核使用工具运行多个 Python 代码片段，则它会使用相同的会话。若要确保每个最终用户都有唯一的会话，请对每个用户使用单独的内核和工具。

SessionsPythonTool 在版本 0.9.8b1 或更高版本的 semantic-kernel 包中提供。

运行示例应用：
```
fastapi dev main.py
```
打开浏览器并导航到 http://localhost:8000/docs 。可以看到示例应用的 Swagger UI。
展开 /chat 终结点并选择“试用”。
在 message 字段中输入 What time is it right now?，然后选择“执行”。

代理将以当前时间进行响应。在终端中，可以查看显示代理生成的 Python 代码的日志，以获取当前时间并在代码解释器会话中运行它。
若要停止应用，请在终端中输入 Ctrl+C。

可选：将示例应用部署到 Azure 容器应用

若要将 FastAPI 应用部署到 Azure 容器应用，需要创建容器映像并将其推送到容器注册表。然后，可以将映像部署到 Azure 容器应用。 az containerapp up 命令会将这些步骤合并到单个命令中。

然后，需要为应用配置托管标识，并为其分配适当的角色来访问 Azure OpenAI 和会话池。

设置容器应用环境的变量和应用名称：

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

生成应用并将其部署到 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> 替换为会话池管理终结点。

为应用启用系统分配的托管标识：

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

若要使应用能够访问 Azure OpenAI 和会话池，需要为托管标识分配适当的角色。

检索托管标识的主体 ID：

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

检索会话池资源 ID：

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

在会话池上为托管标识分配 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>

检索 Azure OpenAI 帐户资源 ID：

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

在 Azure OpenAI 帐户上为托管标识分配 Cognitive Services OpenAI User 角色：

在运行以下命令之前，请将 <PRINCIPAL_ID> 和 <AZURE_OPENAI_RESOURCE_ID> 替换为在前面步骤中检索到的值。
```
az role assignment create \
    --role "Cognitive Services OpenAI User" \
    --assignee <PRINCIPAL_ID> \
    --scope <AZURE_OPENAI_RESOURCE_ID>
```

检索应用的完全限定的域名 (FQDN)：

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

打开浏览器以转到 https://<FQDN>/docs，测试已部署的应用。

清理资源

处理资源后，可以将其删除以避免产生费用：

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

后续步骤

代码解释器会话

通过