教學課程：搭配 Azure Container Apps 在語意核心中使用程式代碼解釋器會話

發行項
05/17/2024

語意核心是由 Microsoft 針對 .NET、Python 和 Java 開發人員所建立的開放原始碼 AI 架構，使用大型語言模型（LLM）。當您使用語意核心建置 AI 代理程式時，LLM 會解譯使用者輸入併產生回應。 AI 代理程式通常需要執行數學和符號推理來產生回應時，通常會苦苦掙扎。藉由整合 Azure Container Apps 動態會話與 Semantic Kernel，您可以為代理程式提供程式代碼解釋器，以用來執行特製化工作。

在本教學課程中，您將瞭解如何在 Web API 中執行語意核心 AI 代理程式。 API 接受使用者輸入，並傳回 AI 代理程式所產生的回應。代理程式會在動態會話中使用程式代碼解釋器來執行計算。

注意

Azure Container Apps 動態作業階段目前為預覽狀態。如需詳細資訊，請參閱預覽限制。

必要條件

具有有效訂用帳戶的 Azure 帳戶。
- 如果您沒有，可以免費建立一個。
安裝 Azure CLI。
Git。
Python 3.10 或更新版本。

建立 Azure 資源

本快速入門中的範例應用程式會使用來自 Azure OpenAI 的 LLM。它也會使用 Azure Container Apps 會話來執行 LLM 所產生的程式代碼。

將 Azure CLI 更新為最新版本。
```
 az upgrade
```
如果已安裝 Azure Container Apps 延伸模組，並安裝包含會話命令的 Azure Container Apps 擴充功能預覽版本，請移除它：
```
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 Container Apps 之前，您可以在本機執行應用程式以進行測試。

複製應用程式

複製 Azure Container Apps 作業階段範例存放庫。

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 Container Apps 會話集區管理端點：

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 帳戶端點，並將 <SESSION_POOL_MANAGEMENT_ENDPOINT> 取代<AZURE_OPENAI_ENDPOINT>為工作階段集區管理端點。

應用程式會使用 DefaultAzureCredential 向 Azure 服務進行驗證。在您的本機計算機上，它會使用您目前的 Azure CLI 登入認證。您必須在 Azure OpenAI 帳戶上提供 認知服務 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 使用者 角色指派給 Azure OpenAI 帳戶上的 Azure CLI 使用者：
```
az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
```
  以您的 Azure CLI 使用者名稱和 <AZURE_OPENAI_RESOURCE_ID> Azure OpenAI 帳戶資源識別碼取代 <CLI_USERNAME> 。
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>
```
  將取代為您的 Azure CLI 用戶名稱，並將 <SESSION_POOL_RESOURCE_ID> 取代<CLI_USERNAME>為工作階段集區資源識別碼。

執行應用程式

執行範例應用程式之前，請在編輯器中開啟 main.py ，然後檢閱程序代碼。應用程式會使用 FastAPI 來建立 Web API，以接受查詢字串中的使用者訊息。

下列幾行程式代碼會具現化 SessionsPythonTool ，並將其提供給 Semantic Kernel 代理程式：

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.8b1semantic-kernel取得。

執行範例應用程式：
```
fastapi dev main.py
```
開啟瀏覽器並巡覽至 http://localhost:8000/docs。您會看到範例應用程式的 Swagger UI。
展開端點，/chat然後選取 [試用]。
在message欄位中輸入 What time is it right now? ，然後選取 [執行]。

代理程式會以目前時間回應。在終端機中，您會看到記錄顯示代理程式產生的 Python 程式代碼，以取得目前的時間，並在程式代碼解釋器會話中執行。
若要停止應用程式，請在終端機中輸入 Ctrl+C 。

選擇性：將範例應用程式部署至 Azure Container Apps

若要將 FastAPI 應用程式部署至 Azure Container Apps，您需要建立容器映射，並將其推送至容器登錄。然後，您可以將映射部署至 Azure Container Apps。命令 az containerapp up 會將這些步驟合併成單一命令。

接著，您必須設定應用程式的受控識別，併為其指派適當的角色，以存取 Azure OpenAI 和會話集區。

設定 Container Apps 環境與應用程式名稱的變數：

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

建置應用程式並將其部署至 Azure Container Apps：

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 .

將取代為 Azure OpenAI 帳戶端點，並將 <SESSION_POOL_MANAGMENT_ENDPOINT> 取代<OPEN_AI_ENDPOINT>為工作階段集區管理端點。

為應用程式啟用系統指派的受控識別：

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

若要讓應用程式存取 Azure OpenAI 和會話集區，您必須將受控識別指派適當的角色。

擷取受控識別的主體標識碼：

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

擷取會話集區資源標識碼：

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

在會話集區上指派和 Contributor 角色的受控識別Azure ContainerApps Session Executor：

執行下列命令之前，請將和 <SESSION_POOL_RESOURCE_ID> 取代<PRINCIPAL_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 帳戶資源識別碼：

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

將 Azure OpenAI 帳戶上的角色指派給受控識別 Cognitive Services OpenAI User ：

執行下列命令之前，請將和 <AZURE_OPENAI_RESOURCE_ID> 取代<PRINCIPAL_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

下一步

程式代碼解釋器會話

共用方式為