Цитирование

Claude способен предоставлять подробные цитаты при ответе на вопросы о документах, помогая вам отслеживать и проверять источники информации в ответах.

Все активные модели поддерживают цитирование, за исключением Haiku 3.

Вот пример использования цитирования с API Messages:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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?"
          }
        ]
      }
    ]
  }'

Как работает цитирование

Интегрируйте цитирование с Claude в следующие шаги:

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

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

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

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

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

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

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

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

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

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

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

import anthropic

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-6",
    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?"
                }
            ]
        }
    ]
)

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

• Содержимое документа кэшируется с использованием 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.