工具

细粒度工具流式传输

了解如何使用细粒度工具流式传输来减少接收大型参数的延迟。

细粒度工具流式传输已在所有模型和所有平台上正式可用，无需 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?