工具

細粒度工具串流

了解如何使用細粒度工具串流來減少接收大型參數的延遲。

細粒度工具串流已在所有模型和所有平台上正式可用，無需 beta 標頭。它能夠在不進行緩衝或 JSON 驗證的情況下串流工具使用參數值，減少開始接收大型參數的延遲。

使用細粒度工具串流時，您可能會收到無效或不完整的 JSON 輸入。請確保在您的程式碼中處理這些邊界情況。

如何使用細粒度工具串流

細粒度工具串流可在所有模型和所有平台上使用（Claude API、Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry）。要使用它，請在任何您想啟用細粒度串流的工具上將 eager_input_streaming 設定為 true，並在您的請求中啟用串流。

以下是如何透過 API 使用細粒度工具串流的範例：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 65536,
    "tools": [
      {
        "name": "make_file",
        "description": "Write text to a file",
        "eager_input_streaming": true,
        "input_schema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "The filename to write text to"
            },
            "lines_of_text": {
              "type": "array",
              "description": "An array of lines of text to write to the file"
            }
          },
          "required": ["filename", "lines_of_text"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Can you write a long poem and make a file called poem.txt?"
      }
    ],
    "stream": true
  }' | jq '.usage'

在此範例中，細粒度工具串流使 Claude 能夠將長詩的各行串流到工具呼叫 make_file 中，而無需緩衝來驗證 lines_of_text 參數是否為有效的 JSON。這意味著您可以在參數串流到達時即時查看，而無需等待整個參數緩衝和驗證完成。

使用細粒度工具串流時，工具使用區塊開始串流的速度更快，且通常更長並包含更少的斷詞。這是由於分塊行為的差異所致。

範例：

不使用細粒度串流（15 秒延遲）：

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

使用細粒度串流（3 秒延遲）：

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

由於細粒度串流在不進行緩衝或 JSON 驗證的情況下傳送參數，因此無法保證產生的串流會以有效的 JSON 字串完成。特別是，如果達到停止原因 max_tokens，串流可能會在參數中途結束且可能不完整。您通常需要編寫特定的支援來處理達到 max_tokens 的情況。

處理工具回應中的無效 JSON

使用細粒度工具串流時，您可能會從模型收到無效或不完整的 JSON。如果您需要在錯誤回應區塊中將此無效 JSON 傳回模型，您可以將其包裝在 JSON 物件中以確保正確處理（使用合理的鍵名）。例如：

{
  "INVALID_JSON": "<your invalid json string>"
}

這種方法有助於模型理解內容是無效的 JSON，同時保留原始的格式錯誤資料以供除錯使用。

包裝無效 JSON 時，請確保正確轉義無效 JSON 字串中的任何引號或特殊字元，以維持包裝物件中有效的 JSON 結構。

Was this page helpful?

如何使用細粒度工具串流

以下是如何透過 API 使用細粒度工具串流的範例：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 65536,
    "tools": [
      {
        "name": "make_file",
        "description": "Write text to a file",
        "eager_input_streaming": true,
        "input_schema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "The filename to write text to"
            },
            "lines_of_text": {
              "type": "array",
              "description": "An array of lines of text to write to the file"
            }
          },
          "required": ["filename", "lines_of_text"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Can you write a long poem and make a file called poem.txt?"
      }
    ],
    "stream": true
  }' | jq '.usage'

使用細粒度工具串流時，工具使用區塊開始串流的速度更快，且通常更長並包含更少的斷詞。這是由於分塊行為的差異所致。

範例：

不使用細粒度串流（15 秒延遲）：

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

使用細粒度串流（3 秒延遲）：

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

處理工具回應中的無效 JSON

{
  "INVALID_JSON": "<your invalid json string>"
}

這種方法有助於模型理解內容是無效的 JSON，同時保留原始的格式錯誤資料以供除錯使用。

包裝無效 JSON 時，請確保正確轉義無效 JSON 字串中的任何引號或特殊字元，以維持包裝物件中有效的 JSON 結構。

Was this page helpful?