Цитирование
Обоснуйте ответы 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)Как работает цитирование
Цитирование работает в три этапа:
Вы предоставляете документы и включаете цитирование
- Включите документы в любом из поддерживаемых форматов: PDF, обычный текст или документы с пользовательским содержимым.
- Установите
citations.enabled=trueдля каждого из ваших документов. В одном запросе нельзя смешивать документы с включённым цитированием и документы без него. - Claude может цитировать текст, но не изображения.
API обрабатывает документы
- Содержимое документов разбивается на «chunks» (фрагменты), чтобы определить минимальную гранулярность возможных цитат. Например, разбиение на предложения позволяет Claude цитировать одно предложение или объединять несколько последовательных предложений, чтобы процитировать абзац или более длинный отрывок.
- Для PDF: API извлекает текст, как описано в разделе Поддержка PDF, и разбивает его на предложения. Claude не может цитировать изображения в PDF.
- Для документов с обычным текстом: API разбивает содержимое на предложения.
- Для документов с пользовательским содержимым: API использует ваши блоки содержимого как есть и не выполняет дальнейшего разбиения.
- Содержимое документов разбивается на «chunks» (фрагменты), чтобы определить минимальную гранулярность возможных цитат. Например, разбиение на предложения позволяет Claude цитировать одно предложение или объединять несколько последовательных предложений, чтобы процитировать абзац или более длинный отрывок.
Claude отвечает с цитатами
- Ответ может содержать несколько текстовых блоков. Каждый текстовый блок может содержать утверждение Claude и список цитат, подтверждающих его.
- Цитаты ссылаются на конкретные места в исходных документах. Формат цитаты зависит от типа документа, который цитирует Claude.
- Для PDF: Цитаты включают диапазон номеров страниц (нумерация с 1).
- Для документов с обычным текстом: Цитаты включают диапазон индексов символов (нумерация с 0).
- Для документов с пользовательским содержимым: Цитаты включают диапазон индексов блоков содержимого (нумерация с 0), соответствующий исходному предоставленному списку содержимого.
- Индексы документов предоставляются для указания источника ссылки и нумеруются с 0 в соответствии со списком всех документов в вашем исходном запросе.
Цитируемое и нецитируемое содержимое
- Текст, находящийся в содержимом
sourceдокумента, может быть процитирован. titleиcontext— необязательные поля, которые передаются модели, но не используются для цитируемого содержимого.titleограничено по длине, поэтому полеcontextполезно для хранения метаданных документа в виде текста или сериализованного JSON.
Индексы цитат
- Индексы документов нумеруются с 0 по списку всех блоков содержимого документов в запросе (охватывая все сообщения).
- Индексы символов нумеруются с 0, конечные индексы исключающие.
- Номера страниц нумеруются с 1, конечные номера страниц исключающие.
- Индексы блоков содержимого нумеруются с 0, конечные индексы исключающие, по списку
content, предоставленному в документе с пользовательским содержимым.
Стоимость в токенах
- Включение цитирования приводит к небольшому увеличению входных токенов из-за дополнений к системной подсказке и разбиения документов.
- Однако функция цитирования очень эффективна с точки зрения выходных токенов. Внутри модель выводит цитаты в стандартизированном формате, а затем эти цитаты разбираются на цитируемый текст и индексы местоположения в документе. Поле
cited_textпредоставляется для удобства и не учитывается в выходных токенах. - При передаче обратно в последующих ходах разговора
cited_textтакже не учитывается во входных токенах.
Совместимость функций
Цитирование работает с другими функциями API, включая «prompt caching» (кэширование подсказок), подсчёт токенов и пакетную обработку.
Получение структурированных данных с цитатами
Чтобы получить цитату для каждого извлечённого значения, попросите Claude отвечать по одной строке на каждое поле. Затем преобразуйте эти строки в структурированные данные в своём коде.
Избегайте пользовательских или системных подсказок, которые запрашивают только JSON, например «Верни только JSON-объект, без какого-либо другого текста.» Запрос с такой подсказкой выполняется успешно, но ответ может содержать мало цитат или не содержать их вовсе.
Следующая подсказка запрашивает два поля из документа с обычным текстом из примера в начале этой страницы. Отправьте её вместо вопроса из того примера:
Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.В следующем ответе у каждого значения есть собственные цитаты:
{
"content": [
{ "type": "text", "text": "grass_color: " },
{
"type": "text",
"text": "green",
"citations": [
{
"type": "char_location",
"cited_text": "The grass is green. ",
"document_index": 0,
"document_title": "My Document",
"start_char_index": 0,
"end_char_index": 20
}
]
},
{ "type": "text", "text": "\nsky_color: " },
{
"type": "text",
"text": "blue",
"citations": [
{
"type": "char_location",
"cited_text": "The sky is blue.",
"document_index": 0,
"document_title": "My Document",
"start_char_index": 20,
"end_char_index": 36
}
]
}
]
}Чтобы разобрать ответ, выполните следующие шаги:
- Прочитайте блоки
textпо порядку и добавляйте текст каждого блока к текущей строке. Начинайте новую строку при каждом символе новой строки. - Прикрепите
citationsкаждого блока к каждой строке, содержащей часть его текста. Блок с цитатой может содержать только значение, как в этом примере, или целую строку. - Пропускайте строки без двоеточия. Разделите каждую оставшуюся строку по первому двоеточию на имя поля и значение и удалите пробелы по краям у обоих. Пропускайте строки, имя которых не входит в число ваших полей, например заключительное примечание.
- Проверьте, что у каждого поля есть значение и хотя бы одна цитата. API не гарантирует ни того, ни другого.
Использование кэширования подсказок с цитированием
Блоки цитат, генерируемые в ответах, нельзя кэшировать напрямую, но исходные документы, на которые они ссылаются, кэшировать можно. Для оптимизации производительности примените 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-файлы с текстовым содержимым | По предложениям | Номера страниц (нумерация с 1) | |
| Пользовательское содержимое | Списки, стенограммы, специальное форматирование, более гранулярные цитаты | Без дополнительного разбиения | Индексы блоков (нумерация с 0) |
Документы с обычным текстом
Документы с обычным текстом автоматически разбиваются на предложения. Вы можете предоставить их встроенными или по ссылке с помощью их file_id:
Полный запрос с обычным текстом см. в первом примере на этой странице. Блок документа использует источник 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 }
}В этих примерах source блока document ссылается на файл, загруженный через Files API. Идентификатор файла в каждом примере — это id, который возвращается при загрузке (см. Загрузка файла).
cited_response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file_id},
"title": "Document Title",
"context": "Context about the document that will not be cited from",
"citations": {"enabled": True},
},
{"type": "text", "text": "Summarize this document."},
],
}
],
)
print(cited_response){
"type": "char_location",
"cited_text": "The exact text being cited", // not counted toward output tokens
"document_index": 0,
"document_title": "Document Title",
"start_char_index": 0, // 0-indexed
"end_char_index": 50 // exclusive
}PDF-документы
Вы можете предоставить PDF-документы в виде данных в кодировке base64, в виде URL или по file_id. API извлекает их текст и разбивает его на предложения.
Claude не может цитировать изображения, поэтому он не может процитировать 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": "url",
"url": "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf",
},
"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)В этих примерах source блока document ссылается на файл, загруженный через Files API. Идентификатор файла в каждом примере — это id, который возвращается при загрузке (см. Загрузка файла).
cited_response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file_id},
"title": "Document Title",
"context": "Context about the document that will not be cited from",
"citations": {"enabled": True},
},
{"type": "text", "text": "Summarize this document."},
],
}
],
)
print(cited_response){
"type": "page_location",
"cited_text": "The exact text being cited", // not counted toward output tokens
"document_index": 0,
"document_title": "Document Title",
"start_page_number": 1, // 1-indexed
"end_page_number": 2 // exclusive
}Документы с пользовательским содержимым
Документы с пользовательским содержимым дают вам контроль над гранулярностью цитат. В source документа type имеет значение content, а поле content содержит список блоков содержимого. API не выполняет дальнейшего разбиения: каждый предоставленный вами текстовый блок является одним фрагментом — наименьшей единицей, которую может процитировать Claude.
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){
"type": "content_block_location",
"cited_text": "The exact text being cited", // not counted toward output tokens
"document_index": 0,
"document_title": "Document Title",
"start_block_index": 0, // 0-indexed
"end_block_index": 1 // exclusive
}Структура ответа
Когда цитирование включено, ответы включают несколько текстовых блоков с цитатами:
{
"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» (потоковой передачей) цитаты поступают как тип дельты citations_delta внутри событий content_block_delta. Каждая дельта содержит одну цитату для добавления в список citations текущего блока содержимого text.
event: message_start
data: {"type": "message_start", ...}
event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
"delta": {"type": "text_delta", "text": "According to..."}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
"delta": {"type": "citations_delta",
"citation": {
"type": "char_location",
"cited_text": "...",
"document_index": 0,
...
}}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: message_stop
data: {"type": "message_stop"}Следующие шаги
Узнайте о потоке событий и других типах дельт блоков контента, которые поступают вместе с citations_delta.
Передавайте результаты поиска из вашего RAG-конвейера как полноценные блоки содержимого со встроенной поддержкой цитирования.
Узнайте, как Claude извлекает текст из PDF и как цитаты на основе страниц соотносятся с вашими исходными файлами.
Загружайте документы один раз и ссылайтесь на них по file_id в нескольких запросах с цитированием.
Доступность
Claude API
- API
- Messages API
- Managed Agents Не поддерживается
- Модели
- Все модели
Amazon Bedrock
- API
- Messages API
- Модели
- Все модели
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Модели
- Все модели
Claude Platform on AWS
- API
- Messages API
- Managed Agents Не поддерживается
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Не поддерживается
- Модели
- Все модели
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Модели
- Все модели
Microsoft Foundry
- API
- Messages API
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/messages
Кроме Охватываемые модели
Эта страница была полезной?