인용 (Citations)¶

Claude의 응답을 여러분의 원본 문서에 근거하게 만들 수 있어요. 인용(Citations)은 각 주장을 뒷받침하는 정확한 구절을 돌려주기 때문에, 답변을 검증하고 출처를 사용자에게 노출할 수 있습니다.

Claude는 문서에 대한 질문에 답할 때 상세한 인용을 제공할 수 있고, 이를 통해 각 응답 뒤에 있는 출처를 추적하고 검증할 수 있어요.

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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에 인용을 통합할 수 있어요:

문서를 제공하고 인용을 활성화¶
지원되는 형식(PDF, 일반 텍스트, 커스텀 콘텐츠 문서) 중 하나로 문서를 포함하세요.
각 문서에 citations.enabled=true를 설정하세요. 현재 요청 내 모든 문서에 인용을 켜거나 끄거나, 둘 중 하나로 통일해야 합니다.
지금은 텍스트 인용만 지원됩니다. 이미지 인용은 아직 불가능해요.
문서가 처리됨¶
문서 내용이 "chunking"되어 가능한 인용의 최소 단위가 정해집니다. 예를 들어 문장 단위 청킹(sentence chunking)을 쓰면 Claude가 한 문장을 인용하거나, 여러 연속 문장을 이어서 한 문단이나 더 긴 구절을 인용할 수 있어요.
PDF: PDF 지원에 설명된 대로 텍스트가 추출되고 문장 단위로 청킹됩니다. PDF에서 이미지 인용은 현재 지원되지 않아요.
일반 텍스트 문서: 내용이 인용 가능한 문장 단위로 청킹됩니다.
커스텀 콘텐츠 문서: 제공한 콘텐츠 블록이 그대로 사용되며 추가 청킹은 일어나지 않습니다.
Claude가 인용된 응답을 제공¶
응답에 이제 여러 개의 텍스트 블록이 포함될 수 있고, 각 텍스트 블록은 Claude가 하는 주장과 그 주장을 뒷받침하는 인용 목록을 담을 수 있어요.
인용은 소스 문서의 특정 위치를 가리킵니다. 이 인용의 형식은 인용 대상 문서의 유형에 따라 달라집니다.
PDF: 인용에 페이지 번호 범위가 포함됩니다 (1부터 시작).
일반 텍스트 문서: 인용에 문자 인덱스 범위가 포함됩니다 (0부터 시작).
커스텀 콘텐츠 문서: 인용에 원래 제공한 콘텐츠 목록에 대응하는 콘텐츠 블록 인덱스 범위가 포함됩니다 (0부터 시작).
문서 인덱스는 참조 대상 소스를 나타내며, 원래 요청의 전체 문서 목록 기준으로 0부터 시작합니다.

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

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

인용 인덱스¶

문서 인덱스는 요청 안에 있는 모든 문서 콘텐츠 블록(모든 메시지에 걸쳐) 목록 기준으로 0부터 시작합니다.
문자 인덱스는 0부터 시작하고 종료 인덱스는 exclusive(끝을 포함하지 않음)입니다.
페이지 번호는 1부터 시작하고 종료 페이지 번호는 exclusive입니다.
콘텐츠 블록 인덱스는 커스텀 콘텐츠 문서에 제공된 content 목록 기준으로 0부터 시작하며 종료 인덱스는 exclusive입니다.

토큰 비용¶

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

기능 호환성¶

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

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

인용과 프롬프트 캐싱은 효과적으로 함께 사용할 수 있어요.

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

client = anthropic.Anthropic()

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

response = client.messages.create(
    model="claude-opus-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"
                    },  # 문서 콘텐츠를 캐시
                },
                {
                    "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로 참조해 제공할 수 있어요:

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

스트리밍 지원¶

스트리밍 응답의 경우 인용은 content_block_delta 이벤트 안의 citations_delta 델타 유형으로 도착합니다. 각 델타는 현재 text 콘텐츠 블록의 citations 목록에 추가할 인용 하나를 담고 있어요.

다음 단계¶

텍스트 델타와 함께 citations_delta 델타 유형을 처리해서, 스트리밍되는 동안 인용된 응답을 렌더링하세요.

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

Claude가 PDF에서 텍스트를 추출하는 방식과 페이지 기반 인용이 소스 파일로 다시 매핑되는 방식을 알아보세요.

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

호환성¶

지원 플랫폼	- Claude API - Claude Platform on AWS - Amazon Bedrock - Google Cloud - Microsoft Foundry