Azure Container Apps 中的無伺服器程式碼解譯器工作階段

Azure Container Apps 動態工作階段提供快速且可擴展的程式碼解譯器存取。每個程式碼解譯器工作階段都會透過 Hyper-V 界限來完全隔離，其設計目的是為了執行不受信任的程式碼。

程式碼解譯器工作階段的使用情境

程式碼解譯器工作階段非常適合需要執行可能具惡意性或可能對主機系統或其他使用者造成危害的程式碼之情境，例如：

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

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

您的應用程式也可以使用 REST API，與程式碼解譯器工作階段整合。 API 可讓您：

在工作階段中執行程式碼並擷取結果
將檔案上傳到工作階段並從工作階段下載檔案。

您可以上傳與下載可執行的程式碼檔案，或您的程式碼可以處理的資料檔案。

內建的程式碼解譯器工作階段支援最常見的程式碼執行情境，而不需要管理基礎結構或容器。

如果您需要完全控制程式碼執行環境，或有需要隔離沙箱的不同情境，您可以使用自訂程式碼解譯器工作階段。

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

若要使用程式代碼解釋器會話，您需要稱為會話集區的 Azure 資源，以定義程式代碼解釋器會話的組態。

在工作階段集區中，您可以指定組態設定，例如最大並行工作階段數，以及工作階段在終止前可閒置多久。

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

如需如何建立和設定會話集區的詳細資訊，請參閱使用會話集區。

工作階段中的程式碼執行

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

工作階段識別碼

重要事項

工作階段識別碼屬於敏感資訊，您必須使用安全流程來管理其值。此流程的一部分需要您的應用程式確保每位使用者或租用戶只能存取自己的工作階段。

無法保護會話存取的安全，可能會導致濫用或未經授權存取儲存在您用戶會話中的數據。如需詳細資訊，請參閱會話標識符。

當您與集區中的會話互動時，您會使用會話標識符來參考每個會話。會話標識符是您在會話集區中定義的唯一字串。如果您正在建置 Web 應用程式，您可以使用使用者的 ID。如果您正在建置聊天機器人，您可以使用交談 ID。

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

驗證

驗證是使用 Microsoft Entra 令牌來處理。有效的 Microsoft Entra 權杖由在工作階段集區上具有 Azure ContainerApps Session Executor 與參與者角色的身分所產生。

如果您使用 LLM 架構整合，該架構會為您處理權杖產生與管理。請確保應用程式設定了具備受控識別，並在工作階段集區上具有必要角色指派。

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

若要深入瞭解，請參閱驗證和授權。

處理檔案

您可以上傳和下載檔案，並列出程式代碼解釋器會話中的所有檔案。

支援角色

檔名與路徑必須僅使用以下支援的字元：

大寫與小寫字母： A-Z， a-z
數字： 0-9
特殊字元：-, _, , ., @, $, &, =, ;, ,, #, %, ^, (, )
Unicode 字元：包含中文、日文及其他國際字元
路徑不允許： .

上傳檔案

若要將檔案上傳到工作階段，請對 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 要求以下載檔案。

在送出要求之前，請將 <> 括號中的預留位置取代為您的要求特定值。

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"
            }
        }
    ]
}

安全性

程式代碼解釋器會話的設計目的是在隔離的環境中執行不受信任的程式碼，以確保您的應用程式和數據保持保護。

LLM 架構整合

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

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

管理 API 端點

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

在工作階段中執行程式碼

若要在工作階段中執行程式碼，請對 POST 端點送出 code/execute 要求，並在要求本文中包含要執行的程式碼。每次程式碼執行時間限制為 220 秒。

下列範例會在 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!')"
    }
}

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

將檔案上傳到工作階段

上傳的檔案會儲存在工作階段檔案系統的 /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--

附註

檔案上傳限制為 128MB。如果超過此限制，可能會回傳 HTTP 413。

從工作階段下載檔案

若要從工作階段的 /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 搭配程式碼解譯器工作階段

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-30

共用方式為

Azure Container Apps 中的無伺服器程式碼解譯器工作階段

程式碼解譯器工作階段的使用情境

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

工作階段中的程式碼執行

工作階段識別碼

驗證

處理檔案

支援角色

上傳檔案

下載檔案

列出檔案

安全性

LLM 架構整合

管理 API 端點

在工作階段中執行程式碼

將檔案上傳到工作階段

從工作階段下載檔案

列出工作階段中的檔案

預先安裝的套件

記錄

計費

後續步驟

意見反應

其他資源