인용 - Claude API Docs

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": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "document",
            "source": {
              "type": "text",
              "media_type": "text/plain",
              "data": "The grass is green. The sky is blue."
            },
            "title": "My Document",
            "context": "This is a trustworthy document.",
            "citations": {"enabled": true}
          },
          {
            "type": "text",
            "text": "What color is the grass and sky?"
          }
        ]
      }
    ]
  }'

문서 제공 및 인용 활성화
- 지원되는 형식의 문서를 포함하세요: PDF, 일반 텍스트, 또는 사용자 정의 콘텐츠 문서
- 각 문서에 citations.enabled=true를 설정하세요. 현재 인용은 요청 내의 모든 문서에 대해 활성화하거나 모두 비활성화해야 합니다.
- 현재 텍스트 인용만 지원되며 이미지 인용은 아직 가능하지 않습니다.
문서 처리
- 문서 내용은 가능한 인용의 최소 세분화 수준을 정의하기 위해 "청킹"됩니다. 예를 들어, 문장 청킹은 Claude가 단일 문장을 인용하거나 여러 연속 문장을 연결하여 단락(또는 그 이상)을 인용할 수 있게 합니다!
  - PDF의 경우: PDF 지원에 설명된 대로 텍스트가 추출되고 내용이 문장으로 청킹됩니다. PDF에서 이미지 인용은 현재 지원되지 않습니다.
  - 일반 텍스트 문서의 경우: 내용이 인용 가능한 문장으로 청킹됩니다.
  - 사용자 정의 콘텐츠 문서의 경우: 제공된 콘텐츠 블록이 그대로 사용되며 추가 청킹이 수행되지 않습니다.
Claude가 인용된 응답 제공
- 응답에는 이제 여러 텍스트 블록이 포함될 수 있으며, 각 텍스트 블록에는 Claude가 주장하는 내용과 해당 주장을 뒷받침하는 인용 목록이 포함될 수 있습니다.
- 인용은 소스 문서의 특정 위치를 참조합니다. 이러한 인용의 형식은 인용되는 문서의 유형에 따라 다릅니다.
  - PDF의 경우: 인용에는 페이지 번호 범위(1-인덱스)가 포함됩니다.
  - 일반 텍스트 문서의 경우: 인용에는 문자 인덱스 범위(0-인덱스)가 포함됩니다.
  - 사용자 정의 콘텐츠 문서의 경우: 인용에는 제공된 원본 콘텐츠 목록에 해당하는 콘텐츠 블록 인덱스 범위(0-인덱스)가 포함됩니다.
- 문서 인덱스는 참조 소스를 나타내기 위해 제공되며 원본 요청의 모든 문서 목록에 따라 0-인덱스입니다.

import anthropic

client = anthropic.Anthropic()

# 긴 문서 콘텐츠 (예: 기술 문서)
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # 최소 캐시 가능 길이

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": long_document
                    },
                    "citations": {"enabled": True},
                    "cache_control": {"type": "ephemeral"}  # 문서 콘텐츠 캐시
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

유형	최적 용도	청킹	인용 형식
일반 텍스트	단순 텍스트 문서, 산문	문장	문자 인덱스 (0-인덱스)
PDF	텍스트 콘텐츠가 있는 PDF 파일	문장	페이지 번호 (1-인덱스)
사용자 정의 콘텐츠	목록, 트랜스크립트, 특수 서식, 더 세분화된 인용	추가 청킹 없음	블록 인덱스 (0-인덱스)

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"}
        ]
    },
    "title": "Document Title", # 선택 사항
    "context": "Context about the document that will not be cited from", # 선택 사항
    "citations": {"enabled": True}
}

{
    "content": [
        {
            "type": "text",
            "text": "According to the document, "
        },
        {
            "type": "text",
            "text": "the grass is green",
            "citations": [{
                "type": "char_location",
                "cited_text": "The grass is green.",
                "document_index": 0,
                "document_title": "Example Document",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " and "
        },
        {
            "type": "text",
            "text": "the sky is blue",
            "citations": [{
                "type": "char_location",
                "cited_text": "The sky is blue.",
                "document_index": 0,
                "document_title": "Example Document",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        },
        {
            "type": "text",
            "text": ". Information from page 5 states that ",
        },
        {
            "type": "text",
            "text": "water is essential",
            "citations": [{
                "type": "page_location",
                "cited_text": "Water is essential for life.",
                "document_index": 1,
                "document_title": "PDF Document",
                "start_page_number": 5,
                "end_page_number": 6
            }]
        },
        {
            "type": "text",
            "text": ". The custom document mentions ",
        },
        {
            "type": "text",
            "text": "important findings",
            "citations": [{
                "type": "content_block_location",
                "cited_text": "These are important findings.",
                "document_index": 2,
                "document_title": "Custom Content Document",
                "start_block_index": 0,
                "end_block_index": 1
            }]
        }
    ]
}

인용

인용

인용 작동 방식

인용 가능 vs 인용 불가능 콘텐츠

인용 인덱스

토큰 비용

기능 호환성

인용과 함께 프롬프트 캐싱 사용

문서 유형

문서 유형 선택

일반 텍스트 문서

PDF 문서

사용자 정의 콘텐츠 문서

응답 구조

스트리밍 지원

인용 작동 방식

인용 가능 vs 인용 불가능 콘텐츠

인용 인덱스

토큰 비용

기능 호환성

인용과 함께 프롬프트 캐싱 사용

문서 유형

문서 유형 선택

일반 텍스트 문서

일반 텍스트 인용 예시

PDF 문서

PDF 인용 예시

사용자 정의 콘텐츠 문서

인용 예시

응답 구조

스트리밍 지원

스트리밍 이벤트 예시