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

教程：使用 Azure 容器应用上的 LlamaIndex 中的代码解释器会话

项目
10/11/2024

LlamaIndex 是用于构建上下文扩充语言模型 (LLM) 应用程序的强大框架。使用 LlamaIndex 生成 AI 代理时，LLM 会解释用户输入并生成响应。当 AI 代理需要执行数学和符号推理来生成响应时，它通常会遇到困难。通过将 Azure 容器应用动态会话与 LlamaIndex 集成，可以为代理提供代码解释器以用于执行专业任务。

本教程介绍如何在 Web API 中运行 LlamaIndex 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/llamaindex-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。

以下代码行可实例化 AzureCodeInterpreterToolSpec 并将其提供给 LlamaIndex 代理：

code_interpreter_tool = AzureCodeInterpreterToolSpec(
    pool_managment_endpoint=pool_management_endpoint,
)
agent = ReActAgent.from_tools(code_interpreter_tool.to_tool_list(), llm=llm, verbose=True)

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

AzureCodeInterpreterToolSpec 在 llama-index-tools-azure-code-interpreter 包中提供。

运行示例应用：
```
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

后续步骤

代码解释器会话

通过