Claude Platform Docs
Messages모델 기능

인용

Claude의 응답을 소스 문서에 근거하도록 합니다. 인용은 각 주장을 뒷받침하는 정확한 구절을 반환하므로, 답변을 검증하고 사용자에게 출처를 표시할 수 있습니다.

Claude는 문서에 대한 질문에 답변할 때 상세한 "citations"(인용)을 제공할 수 있어, 각 응답의 근거가 되는 출처를 추적하고 검증하는 데 도움이 됩니다.

모든 활성 모델이 인용을 지원합니다.

다음 예시는 Messages API를 사용하여 일반 텍스트 문서에서 인용을 활성화하는 방법을 보여줍니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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?"},
            ],
        }
    ],
)
print(response)

인용 작동 방식

다음 단계에 따라 Claude에 인용을 통합하세요:

  1. 문서를 제공하고 인용 활성화

    • 지원되는 형식 중 하나로 문서를 포함하세요: PDF, 일반 텍스트 또는 사용자 정의 콘텐츠 문서.
    • 각 문서에 citations.enabled=true를 설정하세요. 현재 인용은 요청 내의 모든 문서에 활성화하거나 모두 비활성화해야 합니다.
    • 현재 텍스트 인용만 지원됩니다. 이미지 인용은 아직 불가능합니다.

  2. 문서 처리

    • 문서 내용은 가능한 인용의 최소 단위를 정의하기 위해 "청크"로 분할됩니다. 예를 들어, 문장 단위 청킹을 통해 Claude는 단일 문장을 인용하거나 여러 연속된 문장을 연결하여 단락 또는 더 긴 구절을 인용할 수 있습니다.
      • PDF의 경우: PDF 지원에 설명된 대로 텍스트가 추출되고 내용이 문장으로 청킹됩니다. PDF의 이미지 인용은 현재 지원되지 않습니다.
      • 일반 텍스트 문서의 경우: 내용이 인용 가능한 문장으로 청킹됩니다.
      • 사용자 정의 콘텐츠 문서의 경우: 제공된 콘텐츠 블록이 그대로 사용되며 추가 청킹은 수행되지 않습니다.

  3. Claude가 인용이 포함된 응답 제공

    • 이제 응답에는 여러 텍스트 블록이 포함될 수 있으며, 각 텍스트 블록에는 Claude가 제시하는 주장과 그 주장을 뒷받침하는 인용 목록이 포함될 수 있습니다.
    • 인용은 소스 문서의 특정 위치를 참조합니다. 이러한 인용의 형식은 인용되는 문서의 유형에 따라 다릅니다.
      • PDF의 경우: 인용에 페이지 번호 범위(1부터 시작)가 포함됩니다.
      • 일반 텍스트 문서의 경우: 인용에 문자 인덱스 범위(0부터 시작)가 포함됩니다.
      • 사용자 정의 콘텐츠 문서의 경우: 인용에 제공된 원본 콘텐츠 목록에 해당하는 콘텐츠 블록 인덱스 범위(0부터 시작)가 포함됩니다.
    • 참조 출처를 나타내기 위해 문서 인덱스가 제공되며, 원래 요청의 모든 문서 목록에 따라 0부터 시작합니다.

인용 가능한 콘텐츠와 인용 불가능한 콘텐츠

  • 문서의 source 콘텐츠 내에 있는 텍스트는 인용할 수 있습니다.
  • title과 context는 모델에 전달되지만 인용 콘텐츠로는 사용되지 않는 선택적 필드입니다.
  • title은 길이가 제한되어 있으므로, context 필드는 문서 메타데이터를 텍스트 또는 문자열화된 JSON으로 저장하는 데 유용합니다.

인용 인덱스

  • 문서 인덱스는 요청 내 모든 문서 콘텐츠 블록 목록(모든 메시지에 걸쳐)에서 0부터 시작합니다.
  • 문자 인덱스는 0부터 시작하며 종료 인덱스는 배타적(exclusive)입니다.
  • 페이지 번호는 1부터 시작하며 종료 페이지 번호는 배타적입니다.
  • 콘텐츠 블록 인덱스는 사용자 정의 콘텐츠 문서에 제공된 content 목록에서 0부터 시작하며 종료 인덱스는 배타적입니다.

토큰 비용

  • 인용을 활성화하면 시스템 프롬프트 추가 및 문서 청킹으로 인해 입력 토큰이 약간 증가합니다.
  • 그러나 인용 기능은 출력 토큰 측면에서 매우 효율적입니다. 내부적으로 모델은 표준화된 형식으로 인용을 출력하며, 이는 이후 인용 텍스트와 문서 위치 인덱스로 파싱됩니다. cited_text 필드는 편의를 위해 제공되며 출력 토큰에 포함되지 않습니다.
  • 이후 대화 턴에서 다시 전달될 때도 cited_text는 입력 토큰에 포함되지 않습니다.

기능 호환성

인용은 프롬프트 캐싱, 토큰 카운팅, 배치 처리를 포함한 다른 API 기능과 함께 작동합니다.

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

인용과 "prompt caching"(프롬프트 캐싱)은 함께 효과적으로 사용할 수 있습니다.

응답에서 생성된 인용 블록은 직접 캐시할 수 없지만, 인용이 참조하는 소스 문서는 캐시할 수 있습니다. 성능을 최적화하려면 최상위 문서 콘텐츠 블록에 cache_control을 적용하세요.

client = anthropic.Anthropic()

# 긴 문서 콘텐츠(예: 기술 문서)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-5-5",
    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"
                    },  # Cache the document content
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?",
                },
            ],
        }
    ],
)
print(response)

이 예시에서:

  • 문서 콘텐츠는 문서 블록의 cache_control을 사용하여 캐시됩니다.
  • 문서에 인용이 활성화되어 있습니다.
  • Claude는 캐시된 문서 콘텐츠의 이점을 누리면서 인용이 포함된 응답을 생성할 수 있습니다.
  • 동일한 문서를 사용하는 후속 요청은 캐시된 콘텐츠의 이점을 누립니다.

문서 유형

문서 유형 선택

인용에는 세 가지 문서 유형이 지원됩니다. 문서는 메시지에 직접 제공하거나(base64, 텍스트 또는 URL) Files API를 통해 업로드하고 file_id로 참조할 수 있습니다:

유형적합한 용도청킹인용 형식
일반 텍스트간단한 텍스트 문서, 산문문장문자 인덱스(0부터 시작)
PDF텍스트 콘텐츠가 있는 PDF 파일문장페이지 번호(1부터 시작)
사용자 정의 콘텐츠목록, 대화 기록, 특수 서식, 더 세밀한 인용추가 청킹 없음블록 인덱스(0부터 시작)

일반 텍스트 문서

일반 텍스트 문서는 자동으로 문장 단위로 청킹됩니다. 인라인으로 제공하거나 file_id로 참조하여 제공할 수 있습니다:

이 페이지 상단의 소개 예시는 모든 SDK에서의 완전한 일반 텍스트 요청을 보여줍니다. 문서 블록은 text 소스를 사용합니다:

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "Plain text content..."
  },
  "title": "Document Title",
  "context": "Context about the document that will not be cited from",
  "citations": { "enabled": true }
}

PDF 문서

PDF 문서는 base64로 인코딩된 데이터, URL 또는 file_id로 제공할 수 있습니다. PDF 텍스트는 추출되어 문장 단위로 청킹됩니다. 이미지 인용은 아직 지원되지 않으므로, 문서를 스캔한 것으로 추출 가능한 텍스트가 없는 PDF는 인용할 수 없습니다.

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

사용자 정의 콘텐츠 문서

사용자 정의 콘텐츠 문서를 사용하면 인용 단위를 제어할 수 있습니다. 추가 청킹은 수행되지 않으며, 제공된 콘텐츠 블록에 따라 청크가 모델에 제공됩니다.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "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},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

응답 구조

인용이 활성화되면 응답에는 인용이 포함된 여러 텍스트 블록이 포함됩니다:

{
  "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
        }
      ]
    }
  ]
}

스트리밍 지원

"streaming"(스트리밍) 응답의 경우, 인용은 content_block_delta 이벤트 내에서 citations_delta 델타 유형으로 전달됩니다. 각 델타에는 현재 text 콘텐츠 블록의 citations 목록에 추가할 단일 인용이 포함됩니다.

다음 단계

메시지 스트리밍

텍스트 델타와 함께 citations_delta 델타 유형을 처리하여 인용이 포함된 응답을 스트리밍되는 대로 렌더링하세요.

검색 결과

RAG 파이프라인의 검색 결과를 내장 인용 지원이 있는 일급 콘텐츠 블록으로 전달하세요.

PDF 지원

Claude가 PDF에서 텍스트를 추출하는 방법과 페이지 기반 인용이 소스 파일에 어떻게 매핑되는지 알아보세요.

Files API

문서를 한 번 업로드하고 여러 인용 요청에서 file_id로 참조하세요.

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?