Цитирование

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

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

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

Индексы цитирования

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

Стоимость токенов

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

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

Цитирования работают в сочетании с другими функциями API, включая кэширование подсказок, подсчет токенов и пакетную обработку.

Использование кэширования подсказок с цитированиями

Цитирования и кэширование подсказок можно использовать вместе эффективно.

Блоки цитирования, созданные в ответах, не могут быть кэшированы напрямую, но исходные документы, на которые они ссылаются, могут быть кэшированы. Для оптимизации производительности примените cache_control к вашим блокам содержимого документа верхнего уровня.

В этом примере:

• Содержимое документа кэшируется с использованием cache_control на блоке документа
• Цитирования включены в документе
• Claude может генерировать ответы с цитированиями, получая преимущества от кэшированного содержимого документа
• Последующие запросы, использующие тот же документ, будут получать преимущества от кэшированного содержимого

Типы документов

Выбор типа документа

Три типа документов поддерживаются для цитирований. Документы могут быть предоставлены непосредственно в сообщении (base64, текст или URL) или загружены через Files API и указаны по file_id:

Документы простого текста

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