인용

빌드모델 기능

인용

Claude가 문서에 대한 질문에 답할 때 상세한 인용을 제공하는 방법을 알아봅니다.

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.

Claude는 문서에 대한 질문에 답할 때 상세한 인용을 제공할 수 있으며, 이를 통해 응답의 정보 출처를 추적하고 검증할 수 있습니다.

모든 활성 모델이 인용을 지원하며, Haiku 3은 예외입니다.

이 양식을 사용하여 인용 기능에 대한 피드백과 제안을 공유하세요.

Messages API에서 인용을 사용하는 방법의 예시입니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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에게 직접 인용을 출력하도록 요청하는 경우, cited_text가 출력 토큰으로 계산되지 않기 때문에 비용 절감을 볼 수 있습니다.
더 나은 인용 신뢰성: 인용이 위에서 언급한 각 응답 형식으로 파싱되고 cited_text가 추출되기 때문에, 인용은 제공된 문서에 대한 유효한 포인터를 포함하도록 보장됩니다.
향상된 인용 품질: 평가에서 인용 기능은 순수 프롬프트 기반 접근 방식과 비교하여 문서에서 가장 관련성 있는 인용을 인용할 가능성이 훨씬 더 높은 것으로 나타났습니다.

인용이 작동하는 방식

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

문서를 제공하고 인용 활성화
- 지원되는 형식 중 하나로 문서를 포함하세요: PDF, 일반 텍스트, 또는 사용자 정의 콘텐츠 문서
- 각 문서에서 citations.enabled=true를 설정하세요. 현재 인용은 요청 내의 모든 문서에서 활성화되거나 모두 비활성화되어야 합니다.
- 현재 텍스트 인용만 지원되며 이미지 인용은 아직 불가능합니다.
문서가 처리됨
- 문서 내용이 "청킹"되어 가능한 인용의 최소 세분성을 정의합니다. 예를 들어, 문장 청킹은 Claude가 단일 문장을 인용하거나 여러 연속 문장을 함께 연결하여 단락(또는 더 긴 내용)을 인용할 수 있도록 합니다!
  - PDF의 경우: 텍스트는 PDF 지원에 설명된 대로 추출되고 콘텐츠는 문장으로 청킹됩니다. PDF에서 이미지 인용은 현재 지원되지 않습니다.
  - 일반 텍스트 문서의 경우: 콘텐츠는 인용할 수 있는 문장으로 청킹됩니다.
  - 사용자 정의 콘텐츠 문서의 경우: 제공된 콘텐츠 블록이 그대로 사용되며 추가 청킹은 수행되지 않습니다.
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 기능과 함께 작동합니다.

인용과 구조화된 출력은 호환되지 않음

인용은 구조화된 출력과 함께 사용할 수 없습니다. 사용자 제공 문서(문서 블록 또는 RequestSearchResultBlock)에서 인용을 활성화하고 output_config.format 매개변수(또는 더 이상 사용되지 않는 output_format 매개변수)를 포함하면 API가 400 오류를 반환합니다.

이는 인용이 텍스트 출력과 인용 블록을 인터리빙해야 하기 때문에 구조화된 출력의 엄격한 JSON 스키마 제약과 호환되지 않기 때문입니다.

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

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

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

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-7",
    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-인덱싱)

.csv, .xlsx, .docx, .md, .txt 파일은 문서 블록으로 지원되지 않습니다. 이를 일반 텍스트로 변환하고 메시지 콘텐츠에 직접 포함하세요. 다른 파일 형식으로 작업을 참조하세요.

일반 텍스트 문서

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

PDF 문서

PDF 문서는 base64 인코딩된 데이터 또는 file_id로 제공될 수 있습니다. PDF 텍스트는 추출되고 문장으로 청킹됩니다. 이미지 인용이 아직 지원되지 않으므로, 문서의 스캔이며 추출 가능한 텍스트를 포함하지 않는 PDF는 인용할 수 없습니다.

사용자 정의 콘텐츠 문서

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

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"},
        ],
    },
    "title": "Document Title",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "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,
                }
            ],
        },
    ]
}

스트리밍 지원

스트리밍 응답의 경우, citations_delta 유형이 포함되며, 현재 text 콘텐츠 블록의 citations 목록에 추가할 단일 인용을 포함합니다.

Was this page helpful?

빌드모델 기능

인용

Claude가 문서에 대한 질문에 답할 때 상세한 인용을 제공하는 방법을 알아봅니다.

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.

Claude는 문서에 대한 질문에 답할 때 상세한 인용을 제공할 수 있으며, 이를 통해 응답의 정보 출처를 추적하고 검증할 수 있습니다.

모든 활성 모델이 인용을 지원하며, Haiku 3은 예외입니다.

이 양식을 사용하여 인용 기능에 대한 피드백과 제안을 공유하세요.

Messages API에서 인용을 사용하는 방법의 예시입니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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에게 직접 인용을 출력하도록 요청하는 경우, cited_text가 출력 토큰으로 계산되지 않기 때문에 비용 절감을 볼 수 있습니다.
더 나은 인용 신뢰성: 인용이 위에서 언급한 각 응답 형식으로 파싱되고 cited_text가 추출되기 때문에, 인용은 제공된 문서에 대한 유효한 포인터를 포함하도록 보장됩니다.
향상된 인용 품질: 평가에서 인용 기능은 순수 프롬프트 기반 접근 방식과 비교하여 문서에서 가장 관련성 있는 인용을 인용할 가능성이 훨씬 더 높은 것으로 나타났습니다.

인용이 작동하는 방식

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

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

자동 청킹 vs 사용자 정의 콘텐츠

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

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

인용 인덱스

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

토큰 비용

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

기능 호환성

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

인용과 구조화된 출력은 호환되지 않음

이는 인용이 텍스트 출력과 인용 블록을 인터리빙해야 하기 때문에 구조화된 출력의 엄격한 JSON 스키마 제약과 호환되지 않기 때문입니다.

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

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

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-7",
    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는 캐시된 문서 콘텐츠의 이점을 누리면서 인용과 함께 응답을 생성할 수 있습니다
동일한 문서를 사용하는 후속 요청은 캐시된 콘텐츠의 이점을 누릴 것입니다

문서 유형

문서 유형 선택

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

일반 텍스트 문서

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

PDF 문서

사용자 정의 콘텐츠 문서

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

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"},
        ],
    },
    "title": "Document Title",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "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,
                }
            ],
        },
    ]
}

스트리밍 지원

스트리밍 응답의 경우, citations_delta 유형이 포함되며, 현재 text 콘텐츠 블록의 citations 목록에 추가할 단일 인용을 포함합니다.

Was this page helpful?

인용이 작동하는 방식

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

인용 인덱스

토큰 비용

기능 호환성

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

문서 유형

문서 유형 선택

일반 텍스트 문서

일반 텍스트 인용 예시

PDF 문서

PDF 인용 예시

사용자 정의 콘텐츠 문서

인용 예시

응답 구조

스트리밍 지원

스트리밍 이벤트 예시

인용이 작동하는 방식

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

인용 인덱스

토큰 비용

기능 호환성

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

문서 유형

문서 유형 선택

일반 텍스트 문서

일반 텍스트 인용 예시

PDF 문서

PDF 인용 예시

사용자 정의 콘텐츠 문서

인용 예시

응답 구조

스트리밍 지원

스트리밍 이벤트 예시