Azure AI Foundry 入口網站中流程的 Python 工具

2025-06-30

這很重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

提示流程 Python 工具提供自定義的代碼段作為獨立的可執行節點。您可以快速建立 Python 工具、編輯程式代碼及驗證結果。

使用 Python 工具建置

在 Azure AI Foundry 中建立或開啟流程。如需詳細資訊，請參閱建立流程。
選取 [+ Python ] 將 Python 工具新增至您的流程。
輸入輸入數據表中所述之 Python 工具輸入參數的值。例如，在 [ 程序代碼 輸入] 文字框中，您可以輸入下列 Python 程式代碼：
```
from promptflow import tool

@tool
def my_python_tool(message: str) -> str:
    return 'hello ' + message
```
如需詳細資訊，請參閱 Python 程式代碼輸入需求。
視需要將更多工具新增至您的流程。或選取 [執行] 以執行流程。
輸出會在 Outputs 資料表中描述。根據先前的 Python 程式代碼輸入範例，如果輸入訊息是「world」，則輸出為 hello world。

輸入

儲存程式代碼之後，輸入清單會根據工具函式的自變數而變更。將類型新增至自變數和 return 值可協助工具正確顯示類型。

名稱	類型	說明	為必填項目
程式碼	字符串	Python 代碼段。	是的
輸入	-	工具函式參數及其指派的清單。	-

輸出

輸出是 return Python 工具函式的值。例如，請考慮下列 Python 工具函式：

from promptflow import tool

@tool
def my_python_tool(message: str) -> str:
    return 'hello ' + message

如果輸入訊息為「world」，則輸出為 hello world。

型別

類型	Python 範例	說明
整數 (int)	param： int	整數類型
布爾 (bool)	param： bool	布林值類型
字符串	param： str	字串類型
雙倍	param： float	雙精度型別
清單	param： list or param： List[T]	清單類型
物體	param： dict 或 param： Dict[K， V]	物件類型
連線	param：CustomConnection	線上類型是特別處理的。

具有 Connection 類型批注的參數會被視為連線輸入，這表示：

提示流程延伸模組會顯示選取器以選取連線。
在運行時間期間，提示流程會嘗試從傳入的參數值尋找具有相同名稱的連接。

備註

Union[...]只有連接類型才支持類型批注。例如 param: Union[CustomConnection, OpenAIConnection]。

Python 程式代碼輸入需求

本節說明 Python 工具的 Python 程式代碼輸入需求。

Python 工具程式代碼應該包含完整的 Python 程式代碼，包括任何必要的模組匯入。
Python 工具程式代碼必須包含以 @tool （tool 函式）裝飾的函式，做為執行的進入點。裝飾 @tool 項目應該只在代碼段內套用一次。
必須在區段中指派 Inputs Python 工具函式參數。
Python 工具函式應具有 return 語句和值，這是工具的輸出。

下列 Python 程式代碼是最佳做法的範例：

from promptflow import tool

@tool
def my_python_tool(message: str) -> str:
    return 'hello ' + message

在 Python 工具中取用自定義連線

如果您要開發需要使用驗證呼叫外部服務的 Python 工具，您可以在提示流程中使用自定義連線。它可讓您安全地儲存存取密鑰，然後在 Python 程式代碼中擷取它。

建立自定義連線

建立自定義連線，以儲存所有大型語言模型 API 金鑰或其他必要認證。

備註

您必須針對這項功能使用 中樞型專案 。不支援 Foundry 專案 。請參閱如何知道我所擁有的項目類型？和建立中樞型專案。

Azure 訂用帳戶。如果您沒有 Azure 訂閱，請建立免費帳戶。
如果您沒有中樞專案，請建立中樞型專案。

移至專案的 [管理中心 ] 頁面。
在 [ 中樞 ] 或 [ 專案 ] 標題下，選取 [ 已連線的資源]。
選取 [+ 新增連線]。
選取 [自定義 服務]。您可以定義連線名稱。您可以選擇 [ 新增金鑰/值群組] 來新增多個金鑰/值組來儲存您的認證和金鑰。

備註

請確定至少有一個機碼/值組設定為秘密。否則，將不會成功建立連線。若要將一個金鑰/值組設定為秘密，請選取 [秘密 ] 來加密並儲存您的金鑰值。

在 Python 中取用自定義連線

若要在 Python 程式代碼中取用自訂連線：

在 Python 節點的程式代碼區段中，匯入自訂連接連結庫 from promptflow.connections import CustomConnection。在工具函式中定義型 CustomConnection 別的輸入參數。
剖析輸入區段的輸入。然後在 [值] 下拉式清單中選取您的目標自定義連線。

例如：

from promptflow import tool
from promptflow.connections import CustomConnection

@tool
def my_python_tool(message: str, myconn: CustomConnection) -> str:
    # Get authentication key-values from the custom connection
    connection_key1_value = myconn.key1
    connection_key2_value = myconn.key2

後續步驟

深入了解如何建立流程