Skip to main content

Цитаты

Ссылки охватывают ответ помощника обратно к источникам, поддерживающим их. enableCitations Включите при создании или возобновлении сеанса, а затем прочитайте citations полезные данные о assistant.message событиях для отображения сносок, исходных списков или встроенных ссылок.

Предупреждение

Ссылки являются экспериментальными. Имя параметра, полезные данные события и охват поставщика могут измениться в будущем выпуске.

Как работают ссылки

Ссылки создаются поставщиком модели, а не пакетом SDK. Поток состоит из трех частей:

  1. Приложение предоставляет доступный материал, например вложение документа или результат средства, который содержит исходное содержимое.
  2. Среда выполнения помечает этот материал как доступный на проводе при enableCitations включении. Для моделей Anthropic файлы отправляются в виде document блоков с включенными ссылками.
  3. Модель возвращает метаданные ссылки, а среда выполнения нормализует ее в объект, не зависящий citations от поставщика, на последнем assistant.message событии.

Поддержка поставщика ограничена. provider Поле для каждой исходной записи, из которой была получена ссылка:

Значение провайдераMeaning
anthropicЦитата, созданная ответом модели Anthropic (Claude)
openaiСсылка, созданная ответом модели OpenAI
clientЦитата, синтезируемая средой выполнения из выходных данных средства

Примечание.

enableCitations Включение не гарантирует, что ответ содержит ссылки. Модели выдают их только в том случае, если ответ находится в доступном исходном материале. Всегда рассматривать citations поле как необязательное.

Включение ссылок на сеанс

Задайте параметр для создания сеанса и снова установите его в возобновлении, если вы хотите, чтобы ссылки после перезапуска.

Языки кода navigation

TypeScript
const session = await client.createSession({
    onPermissionRequest: approveAll,
    enableCitations: true,
});

const resumed = await client.resumeSession(session.sessionId, {
    onPermissionRequest: approveAll,
    enableCitations: true,
});

Чтение ссылок из сообщений помощника

Ссылки приходят на окончательное assistant.message событие, а не на assistant.message_delta события. Дождитесь окончательного сообщения перед отображением исходных маркеров.

Языки кода navigation

TypeScript
session.on((event) => {
    if (event.type !== "assistant.message" || !event.data.citations) {
        return;
    }

    const { sources, spans } = event.data.citations;
    const sourceById = new Map(sources.map((source) => [source.id, source]));

    for (const span of spans) {
        const quoted = event.data.content.slice(span.startIndex, span.endIndex);
        for (const reference of span.references) {
            const source = sourceById.get(reference.sourceId);
            const label = source?.title ?? source?.url ?? source?.path ?? source?.id;
            console.log(`"${quoted}" — ${label}`);
        }
    }
});

Справочник по полезным данным ссылки на ссылки

Объект citations отделяет дедупликированные источники от диапазонов, ссылающихся на них, поэтому источник, цитируемый пять раз, отображается один раз в sources.

ТипПолеDescription
CitationssourcesДедупликированный набор источников, на которые ссылается диапазон ссылок
CitationsspansДиапазоны созданных текстовых аннотированных с поддержкой источников
CitationSourceidСтабильный идентификатор с заданной областью действия, на который ссылается CitationReference.sourceId
CitationSourceproviderСистема, которая произвела ссылку: anthropic, openaiили client
CitationSourcetitle?Читаемый человеком заголовок источника
CitationSourceurl?URL-адрес источника, когда он является веб-ресурсом
CitationSourcepath?Путь к файлу относительно корневого каталога рабочей области агента, когда источник является файлом
CitationSpanstartIndexСмещение запуска в окончательном содержимом сообщения (единицы кода UTF-16, отсчитываемые от нуля)
CitationSpanendIndexЗавершение смещения в окончательном содержимом сообщения (единицы кода UTF-16, отсчитываемые от нуля, эксклюзивные)
CitationSpanreferencesИсточники, поддерживающие этот диапазон
CitationReferencesourceId
CitationSource Идентификатор этих ссылочных точек
CitationReferencecitedText?Точный текст из источника, поддерживающего диапазон, когда модель предоставляет ее.
CitationReferencelocation?Расположение в источнике, поддерживающее диапазон
CitationReferenceproviderMetadata?Данные корреляции, передаваемые через непрозрачные данные корреляции поставщика

Совет

Смещения диапазона измеряются в единицах кода UTF-16 по последней content строке. Строки TypeScript, Java и .NET уже являются UTF-16, поэтому их можно срезать напрямую. Python строки индексируются точкой кода Юникода и строками Go и Rust являются UTF-8, поэтому перед фрагментированием преобразуйте содержимое в единицы кода UTF-16, как показано выше.

Расположения ссылок

CitationReference.location является дискриминированным объединением, ключом к type:

Тип местоположенияFieldsИспользование
char
startIndex, endIndexДиапазон символов в исходном тексте
page
startPage, endPageДиапазон страниц в документе с разбивкой на страницы
block
startBlock, endBlockДиапазон блоков содержимого в структурированном документе

Предоставление доступных источников

Ссылки нуждаются в исходном материале, который может атрибутом модели. Существует два способа его предоставления.

Присоединение документов к сообщению

Если ссылки включены и сеанс использует поставщик Anthropic, вложения файлов отправляются в виде document блоков с включенными ссылками, поэтому модель может ссылаться на фрагменты из них.

await session.sendAndWait({
    prompt: "Summarize the attached PDF and cite the passages you used.",
    attachments: [
        {
            type: "blob",
            data: pdfBase64,
            displayName: "quarterly-report.pdf",
            mimeType: "application/pdf",
        },
    ],
});

См. раздел AUTOTITLE для API вложений и file``blob фигуры вложений.

Возврат доступных источников из средства

Результаты инструментов содержат экспериментальный citableSources массив. Каждая запись предоставляет, к которым может ссылаться content модель, id а также необязательный title, urlи path. Эти источники сохраняются с результатом средства, поэтому они выживают возобновление сеанса, а ссылки, созданные из них, помечены поставщиком client .

Ограничения

  • Ссылки являются экспериментальными в каждом пакете SDK и не охватываются гарантиями совместимости.
  • Покрытие зависит от поставщика модели. Сеанс, настроенный для поставщика без поддержки ссылок, не выдает citations полезных данных.
  • Ссылки присутствуют только в последнем assistant.message событии, поэтому потребители потоковой передачи не могут отображать их в середине ответа.
  • Общедоступный код и ссылки на дублирование IP-адресов не являются частью этой поверхности.

Дополнительные материалы