Claude는 문서에 관한 질문에 답변할 때 상세한 인용을 제공할 수 있어, 응답에서 정보 출처를 추적하고 확인하는 데 도움을 줍니다.

인용 기능은 현재 Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (신규) 및 Haiku 3.5에서 사용 가능합니다.

Claude Sonnet 3.7의 인용

Claude Sonnet 3.7은 사용자의 명시적인 지시 없이는 다른 Claude 모델에 비해 인용을 할 가능성이 낮을 수 있습니다. Claude Sonnet 3.7에서 인용을 사용할 때는 user 턴에 "답변을 뒷받침하기 위해 인용을 사용하세요."와 같은 추가 지시사항을 포함하는 것이 좋습니다.

또한 모델이 응답 구조화를 요청받았을 때, 해당 형식 내에서 명시적으로 인용을 사용하라는 지시가 없으면 인용을 사용할 가능성이 낮다는 것을 관찰했습니다. 예를 들어, 모델이 응답에 태그를 사용하도록 요청받은 경우, “답변에 항상 인용을 사용하세요, 내에서도 포함해야 합니다.”와 같은 내용을 추가해야 합니다.

인용 기능에 대한 피드백과 제안 사항을 이 양식을 통해 공유해 주세요.

다음은 Messages 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-20250514",
    "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?"
          }
        ]
      }
    ]
  }'

프롬프트 기반 접근법과의 비교

프롬프트 기반 인용 솔루션과 비교하여, 인용 기능은 다음과 같은 장점이 있습니다:

  • 비용 절감: 프롬프트 기반 접근법에서 Claude에게 직접 인용구를 출력하도록 요청하는 경우, cited_text가 출력 토큰으로 계산되지 않기 때문에 비용 절감 효과를 볼 수 있습니다.
  • 더 나은 인용 신뢰성: 인용을 위에서 언급한 응답 형식으로 파싱하고 cited_text를 추출하기 때문에, 인용은 제공된 문서에 대한 유효한 참조를 포함하도록 보장됩니다.
  • 향상된 인용 품질: 평가에서 인용 기능이 순수 프롬프트 기반 접근법에 비해 문서에서 가장 관련성 높은 인용구를 인용할 가능성이 크게 높다는 것을 발견했습니다.

​
인용 작동 방식

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

1

문서 제공 및 인용 활성화

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

문서 처리

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

Claude가 인용된 응답 제공

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

자동 청크화 vs 사용자 정의 콘텐츠

기본적으로 일반 텍스트 및 PDF 문서는 자동으로 문장으로 청크화됩니다. 인용 세분성에 대한 더 많은 제어가 필요한 경우(예: 글머리 기호 또는 대화록), 대신 사용자 정의 콘텐츠 문서를 사용하세요. 자세한 내용은 문서 유형을 참조하세요.

예를 들어, Claude가 RAG 청크에서 특정 문장을 인용할 수 있기를 원한다면, 각 RAG 청크를 일반 텍스트 문서에 넣어야 합니다. 그렇지 않고 추가 청크화를 원하지 않거나 추가 청크화를 사용자 정의하려면 RAG 청크를 사용자 정의 콘텐츠 문서에 넣을 수 있습니다.

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

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

​
인용 인덱스

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

​
토큰 비용

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

​
기능 호환성

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

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

인용과 프롬프트 캐싱은 효과적으로 함께 사용될 수 있습니다.

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

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

이 예시에서:

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

​
문서 유형

​
문서 유형 선택하기

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

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

​
일반 텍스트 문서

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

{
    "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로 인코딩된 데이터나 file_id로 제공할 수 있습니다. PDF 텍스트는 추출되어 문장으로 청크화됩니다. 이미지 인용은 아직 지원되지 않으므로, 추출 가능한 텍스트가 없는 문서 스캔 PDF는 인용할 수 없습니다.

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": base64_encoded_pdf_data
    },
    "title": "Document Title", # 선택 사항
    "context": "Context about the document that will not be cited from", # 선택 사항
    "citations": {"enabled": True}
}

​
사용자 정의 콘텐츠 문서

사용자 정의 콘텐츠 문서는 인용 세분성을 제어할 수 있게 해줍니다. 추가 청크화는 수행되지 않으며 청크는 제공된 콘텐츠 블록에 따라 모델에 제공됩니다.

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

​
스트리밍 지원

스트리밍 응답의 경우, 현재 text 콘텐츠 블록의 citations 목록에 추가될 단일 인용을 포함하는 citations_delta 유형을 추가했습니다.