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

發行項
11/19/2024

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

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

必要條件

具有有效訂用帳戶的 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

下一步

程式碼解譯器工作階段

共用方式為