Skip to main content

Références

Les citations relient des passages d’une réponse de l’assistant aux sources qui les étayent. Activez enableCitations lorsque vous créez ou reprenez une session, puis lisez la charge utile citations dans les événements assistant.message pour afficher des notes de bas de page, des listes de sources ou des liens intégrés.

Avertissement

Les citations sont expérimentales. Le nom de l’option, la charge utile d’événement et la couverture du fournisseur peuvent changer dans une version ultérieure.

Fonctionnement des citations

Les citations sont produites par le fournisseur de modèles, et non par le Kit de développement logiciel (SDK). Le flux comporte trois parties :

  1. Votre application fournit des documents citables, tels qu’une pièce jointe de document ou un résultat d’outil qui contient du contenu source.
  2. L’environnement d’exécution marque ce contenu comme pouvant être cité sur le réseau lorsque enableCitations est activé. Pour les modèles Anthropic, les fichiers joints sont envoyés sous forme de blocs document avec les citations activées.
  3. Le modèle renvoie des métadonnées de citation, et l’environnement d’exécution les normalise en un objet citations indépendant du fournisseur lors de l’événement final assistant.message.

La prise en charge du fournisseur est limitée. Champ provider sur chaque enregistrement source à partir duquel la citation provient :

Valeur du fournisseurSens
anthropicCitation produite par une réponse du modèle Anthropic (Claude)
openaiCitation produite par une réponse de modèle OpenAI
clientCitation synthétisée par le runtime à partir de la sortie de l’outil

Remarque

L’activation enableCitations ne garantit pas qu’une réponse contient des citations. Les modèles les émettent uniquement lorsque la réponse est ancrée dans le matériau source citable. Traitez toujours le citations champ comme facultatif.

Activer les citations sur une session

Définissez l’option sur la création de session et définissez-la à nouveau sur reprise si vous souhaitez des citations après un redémarrage.

Langages de code navigation

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

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

Lire des citations à partir de messages d’assistant

Les citations arrivent lors de l’événement final assistant.message, et non lors des événements assistant.message_delta. Attendez le message final avant de restituer les marqueurs sources.

Langages de code 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}`);
        }
    }
});

Informations de référence sur la charge utile de citation

L’objet citations sépare les sources dédupliquées des étendues qui les référencent. Par conséquent, une source citée cinq fois apparaît une fois dans sources.

TypeChampDescription
CitationssourcesEnsemble dédupliqué des sources référencées dans les segments de citation
CitationsspansSegments de texte généré annotés avec leurs sources justificatives
CitationSourceidIdentificateur stable et délimité par tour référencé par CitationReference.sourceId
CitationSourceproviderSystème qui a produit la citation : anthropic, openaiou client
CitationSourcetitle?Titre lisible par l’homme de la source
CitationSourceurl?URL de la source, lorsqu’il s’agit d’une ressource web
CitationSourcepath?Chemin d’accès du fichier par rapport au répertoire racine de l’espace de travail de l’agent, si la source est un fichier
CitationSpanstartIndexDécalage de début dans le contenu final du message (unités de code UTF-16, à base de zéro, inclusif)
CitationSpanendIndexDécalage de fin dans le contenu final du message (unités de code UTF-16, de base zéro, exclusives)
CitationSpanreferencesSources qui prennent en charge cette étendue
CitationReferencesourceIdIdentificateur de CitationSource vers lequel pointe cette référence
CitationReferencecitedText?Texte exact de la source qui prend en charge l’étendue, lorsque le modèle le fournit
CitationReferencelocation?Emplacement dans le texte source qui justifie le segment
CitationReferenceproviderMetadata?Données de corrélation natives du fournisseur, transmises de manière opaque

Conseil

Les décalages d’étendue sont mesurés en unités de code UTF-16 par rapport à la chaîne finale content . TypeScript, Java et chaînes .NET sont déjà UTF-16. Vous pouvez donc les découper directement. Les chaînes Python sont indexées selon les points de code Unicode, et les chaînes Go et Rust sont encodées en UTF-8 ; convertissez donc le contenu en unités de code UTF-16 avant de les découper, comme le montrent les exemples ci-dessus.

Emplacements de citation

CitationReference.location est une union discriminée indexée par type :

Type d’emplacementFieldsUtilisation
char
startIndex, endIndexPlage de caractères dans le texte source
page
startPage, endPagePlage de pages dans un document paginé
block
startBlock, endBlockPlage de blocs de contenu dans un document structuré

Fournir des sources citables

Les citations ont besoin d’un matériau source que le modèle peut attribuer. Il existe deux façons de le fournir.

Joindre des documents à un message

Lorsque des citations sont activées et que la session utilise un fournisseur de Anthropic, les pièces jointes de fichiers sont envoyées sous forme document de blocs avec des citations activées, afin que le modèle puisse citer des passages à partir d’eux.

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

Consultez Entrée d’image pour l’API des pièces jointes ainsi que les formats de pièces jointes file et blob.

Retourner des sources citables à partir d’un outil

Les résultats de l’outil incluent un tableau expérimental citableSources. Chaque entrée fournit content que le modèle peut citer, ainsi qu’un id et, éventuellement, title, url et path. Ces sources sont conservées avec le résultat de l’outil, de sorte qu’elles restent disponibles après la reprise de la session, et les citations générées à partir de celles-ci sont étiquetées avec le fournisseur client.

Limitations

  • Les citations sont expérimentales dans chaque Kit de développement logiciel (SDK) et ne sont pas couvertes par des garanties de compatibilité.
  • La couverture dépend du fournisseur de modèles. Une session configurée pour un fournisseur sans prise en charge des citations n’émet aucun payload citations.
  • Les citations ne sont présentes que dans le dernier événement assistant.message, de sorte que les clients en streaming ne peuvent pas les afficher en cours de réponse.
  • Les citations de code public et de duplication IP ne font pas partie de cette surface.

Lectures complémentaires