Цитирование

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, выполнив следующие шаги:



Цитируемое и нецитируемое содержимое

• Текст, находящийся в содержимом source документа, может быть процитирован.
• title и context — необязательные поля, которые передаются модели, но не используются в качестве цитируемого содержимого.
• Длина title ограничена, поэтому поле context полезно для хранения метаданных документа в виде текста или сериализованного JSON.



Индексы цитат

• Индексы документов индексируются с 0 по списку всех блоков содержимого документов в запросе (охватывая все сообщения).
• Индексы символов индексируются с 0 с исключающими конечными индексами.
• Номера страниц индексируются с 1 с исключающими конечными номерами страниц.
• Индексы блоков содержимого индексируются с 0 с исключающими конечными индексами по списку content, предоставленному в документе с пользовательским содержимым.



Затраты на токены

• Включение цитирования приводит к небольшому увеличению входных токенов из-за дополнений к системной подсказке и разбиения документов на фрагменты.
• Однако функция цитирования очень эффективна в отношении выходных токенов. Внутренне модель выводит цитаты в стандартизированном формате, которые затем разбираются в цитируемый текст и индексы местоположения в документе. Поле cited_text предоставляется для удобства и не учитывается в выходных токенах.
• При передаче обратно в последующих ходах разговора cited_text также не учитывается во входных токенах.



Совместимость функций

Цитирование работает совместно с другими функциями 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",
    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:



Документы с обычным текстом

Документы с обычным текстом автоматически разбиваются на предложения. Вы можете предоставить их встроенными или по ссылке с их 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, 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,
                }
            ],
        },
    ]
}



Поддержка потоковой передачи

Для ответов с потоковой передачей цитаты поступают как тип дельты citations_delta внутри событий content_block_delta. Каждая дельта содержит одну цитату, которую нужно добавить в список citations текущего блока содержимого text.



Дальнейшие шаги