Loading...
    • 빌드
    • 관리
    • 모델 및 가격
    • 클라이언트 SDK
    • API 참조
    Search...
    ⌘K
    시작하기
    Claude 소개빠른 시작
    Claude로 구축하기
    기능 개요Messages API 사용중지 이유 처리
    모델 기능
    확장 사고적응형 사고노력빠른 모드 (베타: 리서치 프리뷰)구조화된 출력인용스트리밍 메시지일괄 처리검색 결과스트리밍 거부다국어 지원임베딩
    도구
    개요도구 사용 방법웹 검색 도구웹 가져오기 도구코드 실행 도구메모리 도구Bash 도구컴퓨터 사용 도구텍스트 편집기 도구
    도구 인프라
    도구 검색프로그래밍 방식 도구 호출세밀한 도구 스트리밍
    컨텍스트 관리
    컨텍스트 윈도우압축컨텍스트 편집프롬프트 캐싱토큰 계산
    파일 작업
    Files APIPDF 지원이미지 및 비전
    스킬
    개요빠른 시작모범 사례엔터프라이즈용 스킬API의 스킬
    MCP
    원격 MCP 서버MCP 커넥터
    프롬프트 엔지니어링
    개요프롬프트 모범 사례Console 프롬프트 도구
    테스트 및 평가
    성공 기준 정의 및 평가 구축Console의 평가 도구 사용지연 시간 줄이기
    가드레일 강화
    환각 줄이기출력 일관성 높이기탈옥 방지프롬프트 유출 줄이기
    리소스
    용어집
    릴리스 노트
    Claude Platform
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    도구 인프라

    세밀한 도구 스트리밍

    지연 시간에 민감한 애플리케이션을 위해 도구 입력을 문자 단위로 스트리밍합니다.

    This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

    세밀한 도구 스트리밍은 모든 모델과 모든 플랫폼에서 일반적으로 사용 가능합니다. 이 기능은 버퍼링이나 JSON 유효성 검사 없이 도구 사용 매개변수 값의 스트리밍을 가능하게 하여, 대용량 매개변수 수신을 시작하는 데 걸리는 지연 시간을 줄입니다.

    세밀한 도구 스트리밍을 사용할 때 유효하지 않거나 불완전한 JSON 입력을 받을 수 있습니다. 코드에서 이러한 엣지 케이스를 반드시 처리하세요.

    세밀한 도구 스트리밍 사용 방법

    세밀한 도구 스트리밍은 모든 모델과 모든 플랫폼(Claude API, Amazon Bedrock, Google Vertex AI, Microsoft Foundry)에서 사용 가능합니다. 사용하려면 세밀한 스트리밍을 활성화하려는 사용자 정의 도구에서 eager_input_streaming을 true로 설정하고, 요청에서 스트리밍을 활성화하세요.

    다음은 API와 함께 세밀한 도구 스트리밍을 사용하는 예시입니다:

    Was this page helpful?

    • 도구 응답에서 유효하지 않은 JSON 처리
    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
      }'

    이 예시에서 세밀한 도구 스트리밍은 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에 도달했을 때를 처리하기 위한 특별한 지원 코드를 작성해야 합니다.

    도구 입력 델타 누적

    tool_use 콘텐츠 블록이 스트리밍될 때, 초기 content_block_start 이벤트에는 input: {}(빈 객체)가 포함됩니다. 이것은 플레이스홀더입니다. 실제 입력은 각각 partial_json 문자열 조각을 포함하는 일련의 input_json_delta 이벤트로 도착합니다. 코드는 이 조각들을 연결하고 블록이 닫히면 결과를 파싱해야 합니다.

    누적 계약:

    1. type: "tool_use"인 content_block_start에서 빈 문자열을 초기화합니다: input_json = ""
    2. type: "input_json_delta"인 각 content_block_delta에 대해 추가합니다: input_json += event.delta.partial_json
    3. content_block_stop에서 누적된 문자열을 파싱합니다: json.loads(input_json)

    초기 input: {}(객체)와 partial_json(문자열) 사이의 타입 불일치는 의도적인 설계입니다. 빈 객체는 콘텐츠 배열의 슬롯을 표시하고, 델타 문자열이 실제 값을 구성합니다.

    import json
    import anthropic
    
    client = anthropic.Anthropic()
    
    tool_inputs = {}  # index -> accumulated JSON string
    
    with client.messages.stream(
        model="claude-opus-4-6",
        max_tokens=1024,
        tools=[
            {
                "name": "get_weather",
                "description": "Get current weather for a city",
                "eager_input_streaming": True,
                "input_schema": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
            }
        ],
        messages=[{"role": "user", "content": "Weather in Paris?"}],
    ) as stream:
        for event in stream:
            if (
                event.type == "content_block_start"
                and event.content_block.type == "tool_use"
            ):
                tool_inputs[event.index] = ""
            elif (
                event.type == "content_block_delta"
                and event.delta.type == "input_json_delta"
            ):
                tool_inputs[event.index] += event.delta.partial_json
            elif event.type == "content_block_stop" and event.index in tool_inputs:
                parsed = json.loads(tool_inputs[event.index])
                print(f"Tool input: {parsed}")

    Python 및 TypeScript SDK는 이 누적을 자동으로 수행하는 상위 수준 스트림 헬퍼(stream.get_final_message(), stream.finalMessage())를 제공합니다. 위의 수동 패턴은 블록이 닫히기 전에 부분 입력에 반응해야 할 때, 예를 들어 진행 표시기를 렌더링하거나 다운스트림 요청을 일찍 시작할 때만 사용하세요.

    도구 응답에서 유효하지 않은 JSON 처리

    세밀한 도구 스트리밍을 사용할 때 모델에서 유효하지 않거나 불완전한 JSON을 받을 수 있습니다. 이 유효하지 않은 JSON을 오류 응답 블록에서 모델에 다시 전달해야 하는 경우, 적절한 처리를 위해 JSON 객체로 감쌀 수 있습니다(합리적인 키 사용). 예를 들어:

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

    이 접근 방식은 모델이 콘텐츠가 유효하지 않은 JSON임을 이해하는 데 도움을 주면서 디버깅 목적으로 원래의 잘못된 형식의 데이터를 보존합니다.

    유효하지 않은 JSON을 감쌀 때, 래퍼 객체에서 유효한 JSON 구조를 유지하기 위해 유효하지 않은 JSON 문자열의 따옴표나 특수 문자를 적절히 이스케이프해야 합니다.

    다음 단계

    스트리밍 메시지

    서버 전송 이벤트 및 스트림 이벤트 유형에 대한 전체 참조.

    도구 호출 처리

    도구를 실행하고 필요한 메시지 형식으로 결과를 반환합니다.

    도구 참조

    Anthropic 스키마 도구 및 버전 문자열의 전체 디렉토리.