Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
"zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지는 API 및 데이터 보존을 참조하세요.
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에게 출처를 인용하도록 프롬프트하는 것과 비교하여, 인용 기능은 다음과 같은 이점을 제공합니다:
cited_text는 출력 토큰에 포함되지 않으므로 비용 절감 효과를 볼 수 있습니다.cited_text를 직접 추출하기 때문에, 인용은 제공된 문서에 대한 유효한 포인터를 포함하는 것이 보장됩니다.다음 단계에 따라 Claude와 인용을 통합하세요:
문서 제공 및 인용 활성화
citations.enabled=true를 설정하세요. 현재 인용은 요청 내의 모든 문서에서 활성화하거나 모두 비활성화해야 합니다.문서 처리
Claude가 인용된 응답 제공
자동 청킹 vs 사용자 정의 콘텐츠
기본적으로 일반 텍스트와 PDF 문서는 자동으로 문장 단위로 청킹됩니다. 인용 세분성에 대해 더 많은 제어가 필요한 경우(예: 글머리 기호 목록이나 대본), 대신 사용자 정의 콘텐츠 문서를 사용하세요. 자세한 내용은 문서 유형을 참조하세요.
예를 들어, Claude가 RAG 청크에서 특정 문장을 인용할 수 있도록 하려면 각 RAG 청크를 일반 텍스트 문서에 넣어야 합니다. 그렇지 않고 추가 청킹을 원하지 않거나 추가 청킹을 사용자 정의하려는 경우, RAG 청크를 사용자 정의 콘텐츠 문서에 넣을 수 있습니다.
source 콘텐츠 내에서 발견된 텍스트는 인용할 수 있습니다.title과 context는 모델에 전달되지만 인용된 콘텐츠에는 사용되지 않는 선택적 필드입니다.title은 길이가 제한되어 있으므로, context 필드는 문서 메타데이터를 텍스트 또는 문자열화된 JSON으로 저장하는 데 유용합니다.content 목록에서 0부터 시작하며 끝 인덱스는 배타적입니다.cited_text 필드는 편의를 위해 제공되며 출력 토큰에 포함되지 않습니다.cited_text는 입력 토큰에도 포함되지 않습니다.인용은 프롬프트 캐싱, 토큰 계산, 배치 처리를 포함한 다른 API 기능과 함께 작동합니다.
인용과 구조화된 출력은 호환되지 않습니다
인용은 구조화된 출력과 함께 사용할 수 없습니다. 사용자가 제공한 문서(document 블록 또는 search_result 블록)에서 인용을 활성화하고 output_config.format 매개변수(또는 더 이상 사용되지 않는 output_format 매개변수)도 포함하면 API가 400 오류를 반환합니다.
이는 인용이 텍스트 출력과 인용 블록을 교차 배치해야 하는데, 이것이 구조화된 출력의 엄격한 JSON 스키마 제약 조건과 호환되지 않기 때문입니다.
인용과 프롬프트 캐싱은 효과적으로 함께 사용할 수 있습니다.
응답에서 생성된 인용 블록은 직접 캐시할 수 없지만, 참조하는 소스 문서는 캐시할 수 있습니다. 성능을 최적화하려면 최상위 문서 콘텐츠 블록에 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",
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을 사용하여 캐시됩니다.인용에는 세 가지 문서 유형이 지원됩니다. 문서는 메시지에 직접 제공(base64, 텍스트 또는 URL)하거나 Files API를 통해 업로드하고 file_id로 참조할 수 있습니다:
| 유형 | 적합한 용도 | 청킹 | 인용 형식 |
|---|---|---|---|
| 일반 텍스트 | 간단한 텍스트 문서, 산문 | 문장 | 문자 인덱스(0부터 시작) |
| 텍스트 콘텐츠가 있는 PDF 파일 | 문장 | 페이지 번호(1부터 시작) | |
| 사용자 정의 콘텐츠 | 목록, 대본, 특수 서식, 더 세분화된 인용 | 추가 청킹 없음 | 블록 인덱스(0부터 시작) |
document 블록이 지원하지 않는 파일 유형(예: .docx 및 .xlsx)의 경우, 파일을 일반 텍스트로 변환하고 콘텐츠를 메시지 콘텐츠에 직접 포함하세요. .csv 및 .md 파일과 같이 이미 일반 텍스트인 파일은 명시적인 text/plain 콘텐츠 유형으로 업로드할 수도 있습니다. 다른 파일 형식으로 작업하기를 참조하세요.
일반 텍스트 문서는 자동으로 문장 단위로 청킹됩니다. 인라인으로 제공하거나 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 문서는 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로 참조하세요.
Was this page helpful?