Claude Platform Docs
MessagesВозможности модели

Цитирование

Обоснуйте ответы Claude вашими исходными документами. Цитаты возвращают точные фрагменты, подтверждающие каждое утверждение, чтобы вы могли проверять ответы и показывать источники вашим пользователям.

Claude может предоставлять подробные «citations» (цитаты) при ответах на вопросы о документах, помогая вам отслеживать и проверять источники, лежащие в основе каждого ответа.

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

Следующий пример показывает, как включить цитирование для документа с обычным текстом с помощью 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, выполнив следующие шаги:

  1. Предоставьте документ(ы) и включите цитирование

    • Включите документы в любом из поддерживаемых форматов: PDF, обычный текст или документы с пользовательским содержимым.
    • Установите citations.enabled=true для каждого из ваших документов. В настоящее время цитирование должно быть включено либо для всех документов в запросе, либо ни для одного.
    • В настоящее время поддерживаются только текстовые цитаты. Цитирование изображений пока невозможно.

  2. Документы обрабатываются

    • Содержимое документов разбивается на «chunks» (фрагменты), чтобы определить минимальную гранулярность возможных цитат. Например, разбиение на предложения позволяет Claude цитировать одно предложение или объединять несколько последовательных предложений, чтобы процитировать абзац или более длинный отрывок.
      • Для PDF: Текст извлекается, как описано в разделе Поддержка PDF, и содержимое разбивается на предложения. Цитирование изображений из PDF в настоящее время не поддерживается.
      • Для документов с обычным текстом: Содержимое разбивается на предложения, которые можно цитировать.
      • Для документов с пользовательским содержимым: Предоставленные вами блоки содержимого используются как есть, и дальнейшее разбиение не выполняется.

  3. 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» (кэширование подсказок), подсчёт токенов и пакетную обработку.

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

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

Блоки цитат, генерируемые в ответах, нельзя кэшировать напрямую, но исходные документы, на которые они ссылаются, кэшировать можно. Для оптимизации производительности примените 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:

ТипЛучше всего подходит дляРазбиениеФормат цитаты
Обычный текстПростые текстовые документы, прозаПо предложениямИндексы символов (нумерация с 0)
PDFPDF-файлы с текстовым содержимымПо предложениямНомера страниц (нумерация с 1)
Пользовательское содержимоеСписки, стенограммы, специальное форматирование, более гранулярные цитатыБез дополнительного разбиенияИндексы блоков (нумерация с 0)

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

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

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
        }
      ]
    }
  ]
}

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

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

Следующие шаги

Потоковая передача сообщений

Обрабатывайте тип дельты citations_delta вместе с текстовыми дельтами, чтобы отображать ответы с цитатами по мере их потоковой передачи.

Результаты поиска

Передавайте результаты поиска из вашего RAG-конвейера как полноценные блоки содержимого со встроенной поддержкой цитирования.

Поддержка PDF

Узнайте, как Claude извлекает текст из PDF и как цитаты на основе страниц соотносятся с вашими исходными файлами.

Files API

Загружайте документы один раз и ссылайтесь на них по file_id в нескольких запросах с цитированием.

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?