도구

세밀한 도구 스트리밍

버퍼링이나 JSON 검증 없이 도구 사용 매개변수 값을 스트리밍하여 대규모 매개변수 수신 시작 지연 시간을 줄이는 방법을 알아보세요.

세밀한 도구 스트리밍은 모든 모델과 모든 플랫폼에서 일반적으로 사용 가능하며, 베타 헤더가 필요하지 않습니다. 이 기능은 버퍼링이나 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가 lines_of_text 매개변수가 유효한 JSON인지 검증하기 위해 버퍼링하지 않고, 긴 시의 행들을 도구 호출 make_file로 스트리밍할 수 있게 합니다. 이는 전체 매개변수가 버퍼링되고 검증될 때까지 기다릴 필요 없이, 매개변수 스트림이 도착하는 대로 볼 수 있다는 것을 의미합니다.

세밀한 도구 스트리밍을 사용하면, 도구 사용 청크가 더 빠르게 스트리밍되기 시작하며, 종종 더 길고 단어 분할이 적습니다. 이는 청킹 동작의 차이 때문입니다.

예시:

세밀한 스트리밍 없이 (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임을 이해하는 데 도움이 되며, 디버깅 목적으로 원래의 잘못된 형식의 데이터를 보존합니다.

Was this page helpful?