Azure Container Apps 中的無伺服器程式代碼解釋器會話

發行項
11/19/2024

Azure 容器應用程式動態工作階段可讓您以快速且可調整的方式存取程式碼解譯器。每個程式碼解譯器工作階段都會透過 Hyper-V 界限來完全隔離，其設計目的是為了執行不受信任的程式碼。

用於程式碼解譯器工作階段

程式碼解譯器工作階段非常適合以下案例：您需要執行可能有惡意，或可能會對主機系統或其他使用者造成傷害的程式碼，例如：

大型語言模型 (LLM) 所產生的程式碼。
由終端使用者在 Web 或 SaaS 應用程式中提交的程式碼。

對於 LangChain、LlamaIndex 或 Semantic Kernel 等熱門 LLM 架構，您可以使用工具和外掛程式來整合 AI 應用程式與程式碼解譯器工作階段。

您的應用程式也可以使用 REST API 與程式碼解譯器工作階段整合。該 API 可讓您在工作階段中執行程式碼並擷取結果。您也可以在工作階段中上傳和下載檔案。您可以上傳和下載可執行的程式碼檔案，或您的程式碼可以處理的資料檔案。

內建程式碼解譯器工作階段支援最常見的程式碼執行案例，而不需要管理基礎結構或容器。如果您需要完全控制程式碼執行環境，或是您有需要隔離沙箱的不同案例，則可以使用自訂程式碼解譯器工作階段。

程式碼解譯器工作階段集區

若要使用程式碼解譯器工作階段，您需要稱為工作階段集區的 Azure 資源，以定義程式碼解譯器工作階段的設定。在該工作階段集區中，您可以指定各項設定，例如並行工作階段數目上限，以及工作階段要閒置多久才加以終止。

您可以使用 Azure 入口網站、Azure CLI 或 Azure Resource Manager 範本來建立工作階段集區。建立工作階段集區之後，您可以使用集區的管理 API 端點來管理和執行工作階段內的程式碼。

使用 Azure CLI 建立工作階段集區

若要使用 Azure CLI 建立程式碼解譯器工作階段集區，請使用下列命令確定您有最新版本的 Azure CLI 和 Azure 容器應用程式延伸模組：

# Upgrade the Azure CLI
az upgrade

# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y

使用 az containerapps sessionpool create 命令建立集區。下列範例會建立名為 my-session-pool 的 Python 程式碼解譯器工作階段集區。執行命令之前，請務必將 <RESOURCE_GROUP> 取代為您的資源群組名稱。

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --location westus2 \
    --container-type PythonLTS \
    --max-sessions 100 \
    --cooldown-period 300 \
    --network-status EgressDisabled

您可以在建立工作階段集區時定義下列設定：

設定	描述
`--container-type`	要使用的程式碼解譯器類型。唯一支援的值為 `PythonLTS`。
`--max-sessions`	允許並行配置的工作階段數目上限。最大值為 `600`。
`--cooldown-period`	終止前允許的閑置秒數。每次呼叫工作階段的 API 時，都會重設閒置期間。允許的範圍是 `300` 到 `3600` 之間。
`--network-status`	指定是否允許來自工作階段的輸出網路流量。有效值為 `EgressDisabled` (預設值) 和 `EgressEnabled`。

重要

如果您啟用輸出，在工作階段中執行的程式碼便可以存取網際網路。當程式碼不受信任時請小心使用，因為其可用來執行惡意活動，例如拒絕服務的攻擊。

使用 Azure CLI 取得集區管理 API 端點

若要透過 LLM 架構整合或藉由直接呼叫管理 API 端點來使用程式碼解譯器工作階段，您需要集區的管理 API 端點。該端點的格式如下：https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>。

若要擷取工作階段集區的管理 API 端點，請使用 az containerapps sessionpool show 命令。執行命令之前，請務必將 <RESOURCE_GROUP> 取代為您的資源群組名稱。

az containerapp sessionpool show \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --query 'properties.poolManagementEndpoint' -o tsv

工作階段中的程式碼執行

在建立工作階段集區之後，您的應用程式可以透過與 LLM 架構的整合，或藉由直接使用集區的管理 API 端點，來與集區中的工作階段互動。

工作階段識別碼

重要

工作階段識別項是敏感性資訊，因此您必須使用安全的程序來管理其值。此程序有一部分需要您的應用程式確保每個使用者或租用戶只能存取其自己的工作階段。無法保護工作階段的存取，可能會導致濫用或未獲授權存取使用者工作階段中儲存的資料。如需詳細資訊，請參閱工作階段識別項

當您與集區中的工作階段互動時，請使用工作階段識別項來參考每個工作階段。工作階段識別項是您在工作階段集區中定義的唯一字串。如果您要建置 Web 應用程式，可以使用使用者的識別碼。如果您要建置聊天機器人，可以使用交談識別碼。

如果有具有該識別項的執行中工作階段，系統會重複使用該工作階段。如果沒有具有該識別項的執行中工作階段，則系統會自動建立新的工作階段。

若要深入了解工作階段識別項，請參閱工作階段概觀。

驗證

驗證是使用 Microsoft Entra (先前稱為 Azure Active Directory) 權杖來處理。有效的 Microsoft Entra 權杖是由屬於工作階段集區上「Azure ContainerApps 工作階段執行者」和「參與者」角色的身分識別所產生。

如果您使用 LLM 架構整合，架構會為您處理權杖產生和管理。確定應用程式會使用對工作階段集區具有必要角色指派的受控識別進行設定。

如果您是直接使用集區的管理 API 端點，則必須產生權杖，並將其包含在 HTTP 要求的 Authorization 標頭中。除了先前提及的角色指派之外，權杖還需要包含值為 https://dynamicsessions.io 的對象( aud) 宣告。

若要深入了解，請參閱驗證。

LLM 架構整合

下列 LLM 架構會提供與程式碼解譯器工作階段的整合，而不是直接使用工作階段集區管理 API：

架構	套件	教學課程
LangChain	Python： `langchain-azure-dynamic-sessions`	教學課程
LlamaIndex	Python： `llama-index-tools-azure-code-interpreter`	教學課程
語意核心	Python：`semantic-kernel` (0.9.8-b1 版或更新版本)	教學課程

管理 API 端點

如果您未使用 LLM 架構整合，則可以使用管理 API 端點直接與工作階段集區互動。

下列端點可用於管理集區中的工作階段：

端點路徑	方法	描述
`code/execute`	`POST`	在工作階段中執行程式碼。
`files/upload`	`POST`	將檔案上傳至工作階段。
`files/content/{filename}`	`GET`	從工作階段中下載檔案。
`files`	`GET`	列出工作階段中的檔案。

將集區的管理 API 端點與端點路徑串連，以建置每個端點的完整 URL。查詢字串必須包含含有工作階段識別項的 identifier 參數，以及值為 2024-02-02-preview 的 api-version 參數。

例如：https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>

在工作階段中執行程式碼

若要在工作階段中執行程式碼，請將 POST 要求傳送至 code/execute 端點，並附上要在要求本文中執行的程式碼。此範例會在 Python 中列印「Hello, world!」。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為工作階段集區和工作階段識別項的適當值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <token>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "print('Hello, world!')"
    }
}

若要重複使用工作階段，請在後續要求中指定相同的工作階段識別項。

將檔案上傳至工作階段

若要將檔案上傳至工作階段，請將 POST 要求傳送至多部分表單資料中的 uploadFile 端點。在要求本文中包含檔案資料。檔案必須包含檔案名稱。

所上傳的檔案會儲存在工作階段檔案系統的 /mnt/data 目錄底下。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為您要求特有的值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/upload?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <token>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

從工作階段中下載檔案

若要從工作階段的 /mnt/data 目錄中下載檔案，請將 GET 要求傳送至 file/content/{filename} 端點。回應會包含檔案資料。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為您要求特有的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/content/<FILE_NAME_AND_EXTENSION>?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

列出工作階段中的檔案

若要列出工作階段 /mnt/data 目錄中的檔案，請將 GET 要求傳送至 files 端點。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為您要求特有的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

回應會包含工作階段中的檔案清單。

下列清單會顯示在要求工作階段內容時應該會有的回應類型範例。

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

已預先安裝的套件

Python 程式碼解譯器工作階段包含熱門的 Python 套件，例如 NumPy、pandas 和 scikit-learn。

若要輸出已預先安裝之套件的清單，請使用下列程式碼呼叫 code/execute 端點。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為您要求特有的值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/identifier/<SESSION_ID>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "import pkg_resources\n[(d.project_name, d.version) for d in pkg_resources.working_set]"
    }
}

記錄

程式代碼解釋器會話不支援直接記錄。與會話互動的應用程式可以將要求記錄至會話集區管理 API 及其回應。

計費

程式代碼解釋器會話是根據每個會話的持續時間計費。如需詳細資訊，請參閱計費。

下一步

快速入門：透過 LangChain 使用程式碼解譯器工作階段

共用方式為

Azure Container Apps 中的無伺服器程式代碼解釋器會話

用於程式碼解譯器工作階段

程式碼解譯器工作階段集區

使用 Azure CLI 建立工作階段集區

使用 Azure CLI 取得集區管理 API 端點

工作階段中的程式碼執行

工作階段識別碼

驗證

LLM 架構整合

管理 API 端點

在工作階段中執行程式碼

將檔案上傳至工作階段

從工作階段中下載檔案

列出工作階段中的檔案

已預先安裝的套件

記錄

計費

下一步

意見反應

其他資源