載入中

細粒度工具呼叫

第 29 課15 分鐘
載入中

當您在 Claude 中將工具使用與串流結合時,您會在 AI 生成工具參數時獲得即時更新。這會創造更具回應性的使用者體驗,但您需要了解一些關於其幕後運作方式的重要細節。

基本工具串流

啟用串流後,Claude 在處理您的請求時會回傳不同類型的事件。您已經熟悉像 ContentBlockDelta 這樣用於常規文字生成的事件。對於工具使用,您還需要處理一種名為 InputJsonEvent 的新事件類型。

Claude 依序發出的串流事件,從 MessageStart 到 MessageStop,其中 ContentBlockDelta 事件承載文字。

每個 InputJsonEvent 包含兩個關鍵屬性:

  • partial_json - 代表部分工具參數的一段 JSON
  • snapshot - 由目前收到的所有片段累積建構而成的 JSON

以下是您在串流管線中處理這些事件的方式:

python
for chunk in stream:
    if chunk.type == "input_json":
        # 處理部分 JSON 區塊
        print(chunk.partial_json)
        # 或使用目前為止完整的快照
        current_args = chunk.snapshot

啟用串流後,三個 InputJsonEvent 回應的 partial_json 片段建構出快照標題「Vector Storage」。

JSON 驗證的運作方式

這裡就是事情變得有趣的地方。Anthropic API 不會在 Claude 生成每個片段時立即傳送給您。相反地,它會先緩衝這些片段並進行驗證。

我們的伺服器傳送 save_article_schema 和一則使用者訊息;Anthropic API 顯示「abstract」、「This paper」和「pre」等片段。

API 會等待完整的頂層鍵值對才會傳送任何內容。例如,如果您的工具預期這樣的結構:

json
{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

API 會:

  1. 等待整個 abstract 值完成
  2. 根據您的結構描述驗證該鍵值對
  3. 一次性傳送 abstract 的所有緩衝片段
  4. 對 meta 物件重複此過程

四個緩衝片段合併成一個「abstract」鍵與值,Anthropic API 會根據 save_article_schema 進行檢查。

這個驗證過程解釋了為什麼即使啟用了串流,您仍然會看到延遲後接著一陣文字湧出。這些片段會被保留,直到一個完整、有效的頂層鍵值對準備就緒。

API 會緩衝四個片段,直到頂層的「abstract」鍵值對有效為止,然後一次傳送全部四個給我們的伺服器。

細粒度工具呼叫

如果您需要更快、更細緻的串流——或許是為了向使用者顯示即時更新,或快速開始處理部分結果——您可以啟用細粒度工具呼叫。

Anthropic API 向伺服器傳送多組部分 JSON 片段的示意圖,每組都在值的中間結束,而非在鍵的位置。

細粒度工具呼叫主要做一件事:它停用了 API 端的 JSON 驗證。這意味著:

  • 您會在 Claude 生成片段後立即收到它們
  • 頂層鍵之間沒有緩衝延遲
  • 更傳統的串流行為
  • 重要: JSON 驗證被停用——您的程式碼必須處理無效的 JSON

透過在工具上將 eager_input_streaming 設為 True 來啟用它:

python
run_conversation(
    messages, 
    tools=[{**save_article_schema, "eager_input_streaming": True}]
)

使用細粒度工具呼叫時,您可能會更早在串流中收到 word_count 值,而無需等待整個 meta 物件完成。

處理無效的 JSON

使用細粒度工具呼叫時,Claude 可能會生成無效的 JSON,例如 "word_count": undefined,而不是正確的數字。您的應用程式需要妥善處理這些情況:

python
try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # 適當處理無效的 JSON
    print("Received invalid JSON, continuing...")

如果不使用細粒度工具呼叫,API 的驗證會捕捉到這個錯誤,並可能將有問題的值包裝成字串,這可能與您預期的結構描述不符。

何時使用細粒度工具呼叫

在以下情況考慮啟用細粒度工具呼叫:

  • 您需要向使用者顯示工具參數生成的即時進度
  • 您希望盡快開始處理部分工具結果
  • 緩衝延遲對您的使用者體驗產生負面影響
  • 您能夠自在地實作穩健的 JSON 錯誤處理

對於大多數應用程式而言,具有驗證功能的預設行為已經完全足夠。但當您需要額外的回應速度時,細粒度工具呼叫能讓您掌控,以 Claude 生成片段的最快速度來取得它們。