Claude est capable de fournir des citations détaillées lorsqu’il répond à des questions sur des documents, vous aidant à suivre et à vérifier les sources d’information dans les réponses.

La fonctionnalité de citations est actuellement disponible sur Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (nouveau) et Haiku 3.5.

Citations avec Claude Sonnet 3.7

Claude Sonnet 3.7 peut être moins susceptible de faire des citations par rapport à d’autres modèles Claude sans instructions plus explicites de l’utilisateur. Lorsque vous utilisez des citations avec Claude Sonnet 3.7, nous recommandons d’inclure des instructions supplémentaires dans le tour user, comme "Utilisez des citations pour étayer votre réponse." par exemple.

Nous avons également observé que lorsqu’on demande au modèle de structurer sa réponse, il est peu probable qu’il utilise des citations à moins qu’on ne lui dise explicitement d’utiliser des citations dans ce format. Par exemple, si on demande au modèle d’utiliser des balises dans sa réponse, vous devriez ajouter quelque chose comme “Utilisez toujours des citations dans votre réponse, même à l’intérieur de .”

Veuillez partager vos commentaires et suggestions concernant la fonctionnalité de citations en utilisant ce formulaire.

Voici un exemple d’utilisation des citations avec l’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-20250514",
    "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?"
          }
        ]
      }
    ]
  }'

Comparaison avec les approches basées sur les prompts

Par rapport aux solutions de citations basées sur les prompts, la fonctionnalité de citations présente les avantages suivants :

  • Économies de coûts : Si votre approche basée sur les prompts demande à Claude de produire des citations directes, vous pourriez réaliser des économies grâce au fait que cited_text ne compte pas dans vos tokens de sortie.
  • Meilleure fiabilité des citations : Comme nous analysons les citations dans les formats de réponse respectifs mentionnés ci-dessus et extrayons cited_text, les citations sont garanties de contenir des pointeurs valides vers les documents fournis.
  • Amélioration de la qualité des citations : Dans nos évaluations, nous avons constaté que la fonctionnalité de citations est significativement plus susceptible de citer les citations les plus pertinentes des documents par rapport aux approches purement basées sur les prompts.

Comment fonctionnent les citations

Intégrez les citations avec Claude en suivant ces étapes :

1

Fournir le(s) document(s) et activer les citations

  • Incluez des documents dans l’un des formats pris en charge : PDF, texte brut, ou documents à contenu personnalisé
  • Définissez citations.enabled=true sur chacun de vos documents. Actuellement, les citations doivent être activées sur tous les documents d’une requête ou sur aucun.
  • Notez que seules les citations de texte sont actuellement prises en charge et que les citations d’images ne sont pas encore possibles.
2

Traitement des documents

  • Le contenu des documents est “découpé en morceaux” afin de définir la granularité minimale des citations possibles. Par exemple, le découpage en phrases permettrait à Claude de citer une seule phrase ou d’enchaîner plusieurs phrases consécutives pour citer un paragraphe (ou plus) !
    • Pour les PDF : Le texte est extrait comme décrit dans Support PDF et le contenu est découpé en phrases. La citation d’images à partir de PDF n’est pas prise en charge actuellement.
    • Pour les documents en texte brut : Le contenu est découpé en phrases qui peuvent être citées.
    • Pour les documents à contenu personnalisé : Vos blocs de contenu fournis sont utilisés tels quels et aucun découpage supplémentaire n’est effectué.
3

Claude fournit une réponse avec citations

  • Les réponses peuvent désormais inclure plusieurs blocs de texte où chaque bloc de texte peut contenir une affirmation que Claude fait et une liste de citations qui soutiennent cette affirmation.
  • Les citations font référence à des emplacements spécifiques dans les documents sources. Le format de ces citations dépend du type de document cité.
    • Pour les PDF : les citations incluront la plage de numéros de page (indexée à partir de 1).
    • Pour les documents en texte brut : Les citations incluront la plage d’indices de caractères (indexée à partir de 0).
    • Pour les documents à contenu personnalisé : Les citations incluront la plage d’indices de blocs de contenu (indexée à partir de 0) correspondant à la liste de contenu originale fournie.
  • Les indices de document sont fournis pour indiquer la source de référence et sont indexés à partir de 0 selon la liste de tous les documents dans votre requête originale.

Découpage automatique vs contenu personnalisé

Par défaut, les documents en texte brut et PDF sont automatiquement découpés en phrases. Si vous avez besoin de plus de contrôle sur la granularité des citations (par exemple, pour les listes à puces ou les transcriptions), utilisez plutôt des documents à contenu personnalisé. Voir Types de documents pour plus de détails.

Par exemple, si vous voulez que Claude puisse citer des phrases spécifiques de vos fragments RAG, vous devriez mettre chaque fragment RAG dans un document en texte brut. Sinon, si vous ne voulez pas qu’un découpage supplémentaire soit effectué, ou si vous voulez personnaliser tout découpage supplémentaire, vous pouvez mettre les fragments RAG dans un ou des documents à contenu personnalisé.

Contenu citable vs non citable

  • Le texte trouvé dans le contenu source d’un document peut être cité.
  • title et context sont des champs optionnels qui seront transmis au modèle mais ne seront pas utilisés pour le contenu cité.
  • title est limité en longueur, donc vous pourriez trouver le champ context utile pour stocker des métadonnées de document sous forme de texte ou de json stringifié.

Indices de citation

  • Les indices de document sont indexés à partir de 0 dans la liste de tous les blocs de contenu de document dans la requête (s’étendant sur tous les messages).
  • Les indices de caractères sont indexés à partir de 0 avec des indices de fin exclusifs.
  • Les numéros de page sont indexés à partir de 1 avec des numéros de page de fin exclusifs.
  • Les indices de blocs de contenu sont indexés à partir de 0 avec des indices de fin exclusifs de la liste content fournie dans le document à contenu personnalisé.

Coûts en tokens

  • L’activation des citations entraîne une légère augmentation des tokens d’entrée en raison des ajouts au prompt système et du découpage des documents.
  • Cependant, la fonctionnalité de citations est très efficace avec les tokens de sortie. En coulisses, le modèle produit des citations dans un format standardisé qui sont ensuite analysées en texte cité et en indices d’emplacement de document. Le champ cited_text est fourni pour plus de commodité et ne compte pas dans les tokens de sortie.
  • Lorsqu’il est renvoyé dans les tours de conversation suivants, cited_text n’est pas non plus compté dans les tokens d’entrée.

Compatibilité des fonctionnalités

Les citations fonctionnent conjointement avec d’autres fonctionnalités de l’API, notamment la mise en cache des prompts, le comptage des tokens et le traitement par lots.

Utilisation de la mise en cache des prompts avec les citations

Les citations et la mise en cache des prompts peuvent être utilisées efficacement ensemble.

Les blocs de citation générés dans les réponses ne peuvent pas être mis en cache directement, mais les documents sources auxquels ils font référence peuvent être mis en cache. Pour optimiser les performances, appliquez cache_control à vos blocs de contenu de document de niveau supérieur.

import anthropic

client = anthropic.Anthropic()

# Contenu de document long (par exemple, documentation technique)
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # Longueur minimale pour la mise en cache

response = client.messages.create(
    model="claude-opus-4-20250514",
    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"}  # Mettre en cache le contenu du document
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

Dans cet exemple :

  • Le contenu du document est mis en cache à l’aide de cache_control sur le bloc de document
  • Les citations sont activées sur le document
  • Claude peut générer des réponses avec des citations tout en bénéficiant du contenu de document mis en cache
  • Les requêtes suivantes utilisant le même document bénéficieront du contenu mis en cache

Types de documents

Choisir un type de document

Nous prenons en charge trois types de documents pour les citations. Les documents peuvent être fournis directement dans le message (base64, texte ou URL) ou téléchargés via l’API Files et référencés par file_id :

TypeIdéal pourDécoupageFormat de citation
Texte brutDocuments texte simples, prosePhraseIndices de caractères (indexés à partir de 0)
PDFFichiers PDF avec contenu textePhraseNuméros de page (indexés à partir de 1)
Contenu personnaliséListes, transcriptions, formatage spécial, citations plus granulairesPas de découpage supplémentaireIndices de bloc (indexés à partir de 0)

Documents en texte brut

Les documents en texte brut sont automatiquement découpés en phrases. Vous pouvez les fournir en ligne ou par référence avec leur file_id :

{
    "type": "document",
    "source": {
        "type": "text",
        "media_type": "text/plain",
        "data": "Contenu en texte brut..."
    },
    "title": "Titre du document", # optionnel
    "context": "Contexte sur le document qui ne sera pas cité", # optionnel
    "citations": {"enabled": True}
}

Documents PDF

Les documents PDF peuvent être fournis sous forme de données encodées en base64 ou par file_id. Le texte PDF est extrait et découpé en phrases. Comme les citations d’images ne sont pas encore prises en charge, les PDF qui sont des numérisations de documents et ne contiennent pas de texte extractible ne seront pas citables.

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": donnees_pdf_encodees_base64
    },
    "title": "Titre du document", # optionnel
    "context": "Contexte sur le document qui ne sera pas cité", # optionnel
    "citations": {"enabled": True}
}

Documents à contenu personnalisé

Les documents à contenu personnalisé vous donnent un contrôle sur la granularité des citations. Aucun découpage supplémentaire n’est effectué et les morceaux sont fournis au modèle selon les blocs de contenu fournis.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "Premier morceau"},
            {"type": "text", "text": "Deuxième morceau"}
        ]
    },
    "title": "Titre du document", # optionnel
    "context": "Contexte sur le document qui ne sera pas cité", # optionnel
    "citations": {"enabled": True}
}

Structure de réponse

Lorsque les citations sont activées, les réponses incluent plusieurs blocs de texte avec des citations :

{
    "content": [
        {
            "type": "text",
            "text": "Selon le document, "
        },
        {
            "type": "text",
            "text": "l'herbe est verte",
            "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": " et "
        },
        {
            "type": "text",
            "text": "le ciel est bleu",
            "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
            }]
        }
    ]
}

Support du streaming

Pour les réponses en streaming, nous avons ajouté un type citations_delta qui contient une seule citation à ajouter à la liste citations sur le bloc de contenu text actuel.