本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
若要讓模型使用工具來完成訊息的回應,您可以將訊息和一或多個工具的定義傳送到模型。如果模型判斷其中一個工具可協助產生回應,則會傳回請求,讓您使用該工具並將工具結果傳回模型。模型接著會使用結果來產生對原始訊息的回應。
下列步驟說明如何搭配 使用工具 Converse API。 如需範例程式碼,請參閱 Converse API 工具使用範例。
步驟 1:傳送訊息和工具定義
若要傳送訊息和工具定義,您可以使用 Converse 或 ConverseStream(用於串流回應) 操作。
注意
Meta 有特定的建議,可用來建立使用工具搭配 的提示 Llama 3.1 (或更新版本) 模型。如需詳細資訊,請參閱 中的 JSON 型工具呼叫
工具的定義是您在 toolConfig
(ToolConfiguration) JSON 請求參數中傳遞至 Converse
操作的結構描述。如需結構描述的資訊,請參閱JSON結構描述
{
"tools": [
{
"toolSpec": {
"name": "top_song",
"description": "Get the most popular song played on a radio station.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
}
},
"required": [
"sign"
]
}
}
}
}
]
}
在相同的請求中,您也會在 messages
(訊息) 請求參數中傳遞使用者訊息。
[
{
"role": "user",
"content": [
{
"text": "What is the most popular song on WZPZ?"
}
]
}
]
如果您使用的是 Anthropic Claude 3 模型,您可以在toolConfig
請求參數中指定 toolChoice
(ToolChoice) 欄位,強制使用工具。強制使用工具在開發期間測試您的工具非常有用。下列範例示範如何強制使用名為 top_song 的工具。
{"tool" : {"name" : "top_song"}}
如需您可以傳遞的其他參數的相關資訊,請參閱 與 進行對話 Converse API 操作。
步驟 2:從模型取得工具請求
當您使用訊息和工具定義叫用 Converse
操作時,模型會使用工具定義來判斷是否需要工具來回應訊息。例如,如果您的聊天應用程式使用者傳送訊息 上最熱門的歌曲是什麼WZPZ?,則模型會將訊息與 top_song 工具定義中的結構描述相符,並判斷工具可協助產生回應。
當模型決定需要工具來產生回應時,模型會將stopReason
回應欄位設定為 tool_use
。回應也會識別模型希望您執行的工具 (top_song),以及希望您使用工具查詢的廣播站 (WZPZ)。所請求工具的相關資訊位於模型在 output
(ConverseOutput) 欄位中傳回的訊息中。特別是 toolUse
(ToolUseBlock) 欄位。您可以在稍後的呼叫中使用 toolUseId
欄位來識別工具請求。
下列範例顯示當您傳遞 中討論的訊息Converse
時,來自 的回應步驟 1:傳送訊息和工具定義。
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"toolUse": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
]
}
},
"stopReason": "tool_use"
}
步驟 3:為模型提出工具請求
從模型回應中的 toolUse
欄位,使用 name
欄位來識別工具的名稱。然後呼叫您實作工具,並從 input
欄位傳遞輸入參數。
接著,建構包含 toolResult
(ToolResultBlock) 內容區塊的使用者訊息。在內容區塊中,包含工具的回應,以及您在上一個步驟中取得的工具請求 ID。
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"content": [
{
"json": {
"song": "Elemental Hotel",
"artist": "8 Storey Hike"
}
}
]
}
}
]
}
如果工具中發生錯誤,例如對非現有廣播站的請求,您可以將錯誤資訊傳送至 toolResult
欄位中的模型。若要指出錯誤,請在 status
error
欄位中指定 。下列範例錯誤適用於工具找不到廣播站的情況。
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"content": [
{
"text": "Station WZPA not found."
}
],
"status": "error"
}
}
]
}
步驟 4:取得模型回應
透過包含您在對 的呼叫中上一個步驟中建立的使用者訊息,繼續與模型的對話Converse
。模型接著會產生回應,以您在訊息toolResult
欄位中提供的資訊來回答原始訊息 ( 上最熱門的歌曲是什麼WZPZ?)。
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
}
]
}
},
"stopReason": "end_turn"