細粒度工具呼叫

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

基本工具串流

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

每個 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

JSON 驗證如何運作

這正是有趣的地方。Anthropic API 不會在 Claude 生成每個區塊時立即傳送給您。相反地，它會先緩衝區塊並進行驗證。

API 會等待完整的頂層鍵值對後才傳送任何內容。例如，如果您的工具預期以下結構：

json

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

API 將會：

等待整個 abstract 值完成
根據您的結構驗證該鍵值對
一次性傳送 abstract 的所有緩衝區塊
對 meta 物件重複此過程

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

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

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

您會在 Claude 生成區塊後立即收到它們
頂層鍵之間沒有緩衝延遲
更傳統的串流行為
關鍵： JSON 驗證已停用——您的程式碼必須處理無效的 JSON

透過在您的 API 呼叫中加入 fine_grained=True 來啟用它：

python

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=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 能生成的最快速度取得區塊。

基本工具串流

JSON 驗證如何運作