Claude Platform Docs
MessagesCapacités du modèle

Citations

Ancrez les réponses de Claude dans vos documents sources. Les citations renvoient les passages exacts qui appuient chaque affirmation, afin que vous puissiez vérifier les réponses et présenter les sources à vos utilisateurs.

Claude peut fournir des citations détaillées lorsqu’il répond à des questions sur des documents, vous aidant à suivre et vérifier les sources derrière chaque réponse.

Tous les modèles actifs prennent en charge les citations.

L’exemple suivant montre comment activer les citations sur un document en texte brut avec l’API Messages :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

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 : documents PDF, texte brut ou contenu personnalisé.
    • Définissez citations.enabled=true sur chacun de vos documents. Actuellement, les citations doivent être activées sur tous les documents ou sur aucun au sein d’une requête.
    • Seules les citations de texte sont actuellement prises en charge. Les citations d’images ne sont pas encore possibles.

  2. Les documents sont traités

    • Le contenu des documents est « découpé » (chunked) pour définir la granularité minimale des citations possibles. Par exemple, le découpage par phrase permet à Claude de citer une seule phrase ou d’enchaîner plusieurs phrases consécutives pour citer un paragraphe ou un passage plus long.
      • Pour les PDF : Le texte est extrait comme décrit dans Prise en charge des PDF et le contenu est découpé en phrases. La citation d’images à partir de PDF n’est pas actuellement prise en charge.
      • 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 citée

    • Les réponses peuvent désormais inclure plusieurs blocs de texte, chacun pouvant contenir une affirmation de Claude et une liste de citations qui étayent 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 incluent la plage de numéros de page (indexée à partir de 1).
      • Pour les documents en texte brut : Les citations incluent la plage d’indices de caractères (indexée à partir de 0).
      • Pour les documents à contenu personnalisé : Les citations incluent la plage d’indices de blocs de contenu (indexée à partir de 0) correspondant à la liste de contenu originale fournie.
    • Les indices de documents 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.

Contenu citable versus non citable

  • Le texte trouvé dans le contenu source d’un document peut être cité.
  • title et context sont des champs optionnels qui sont transmis au modèle mais non utilisés pour le contenu cité.
  • title est limité en longueur, donc le champ context est utile pour stocker les métadonnées du document sous forme de texte ou de JSON sérialisé.

Indices de citation

  • Les indices de documents sont indexés à partir de 0 depuis la liste de tous les blocs de contenu de document dans la requête (couvrant 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 depuis 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 à l’invite système et du découpage des documents.
  • Cependant, la fonctionnalité de citations est très efficace en termes de tokens de sortie. En interne, le modèle produit les citations dans un format standardisé, puis ces citations sont analysées pour obtenir le texte cité et les indices d’emplacement dans le document. Le champ cited_text est fourni par commodité et n’est pas comptabilisé 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 de tokens et le traitement par lots.

Obtenir des données structurées avec des citations

Pour obtenir une citation pour chaque valeur extraite, demandez à Claude de répondre avec une ligne par champ. Analysez ensuite les lignes pour en extraire des données structurées dans votre code.

Évitez les prompts utilisateur ou les invites système qui demandent uniquement du JSON, comme « Renvoie uniquement un objet JSON, sans autre texte. » Une requête avec un tel prompt réussit, mais la réponse peut contenir peu ou pas de citations.

Le prompt suivant demande deux champs à partir du document en texte brut de l’exemple en haut de cette page. Envoyez-le à la place de la question de cet exemple :

Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.

Dans la réponse suivante, chaque valeur possède ses propres citations :

{
  "content": [
    { "type": "text", "text": "grass_color: " },
    {
      "type": "text",
      "text": "green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green. ",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": "\nsky_color: " },
    {
      "type": "text",
      "text": "blue",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The sky is blue.",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 20,
          "end_char_index": 36
        }
      ]
    }
  ]
}

Pour analyser la réponse, suivez ces étapes :

  1. Lisez les blocs text dans l’ordre et ajoutez le texte de chaque bloc à la ligne en cours. Commencez une nouvelle ligne à chaque caractère de saut de ligne.
  2. Associez les citations de chaque bloc à chaque ligne qui contient une partie de son texte. Un bloc cité peut contenir uniquement la valeur, comme dans cet exemple, ou une ligne entière.
  3. Ignorez les lignes qui ne contiennent pas de deux-points. Scindez chaque ligne restante au niveau de son premier deux-points en un nom de champ et une valeur, et supprimez les espaces au début et à la fin de chacun des deux. Ignorez les lignes dont le nom ne correspond à aucun de vos champs, comme une note de conclusion.
  4. Vérifiez que chaque champ possède une valeur et au moins une citation. L’API ne garantit ni l’une ni l’autre.

Utilisation de la mise en cache des prompts avec les citations

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

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

client = anthropic.Anthropic()

# Contenu d'un long document (par exemple, une documentation technique)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-5-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)

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éficient du contenu mis en cache.

Types de documents

Choisir un type de document

Trois types de documents sont pris en charge 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 textuelPhraseNuméros de page (indexés à partir de 1)
Contenu personnaliséListes, transcriptions, formatage spécial, citations plus granulairesAucun découpage supplémentaireIndices de blocs (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 :

L’exemple d’introduction en haut de cette page montre une requête complète en texte brut dans chaque SDK. Le bloc de document utilise une source 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 }
}

Documents PDF

Les documents PDF peuvent être fournis sous forme de données encodées en base64, sous forme d’URL ou par file_id. Le texte des 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 peuvent pas être cités.

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-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)

Documents à contenu personnalisé

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

Structure de la réponse

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

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

Prise en charge du streaming

Pour les réponses en streaming, les citations arrivent sous forme de type delta citations_delta à l’intérieur des événements content_block_delta. Chaque delta contient une seule citation à ajouter à la liste citations sur le bloc de contenu text actuel.

Prochaines étapes

Messages en streaming

Découvrez le flux d’événements et les autres types de delta de blocs de contenu qui arrivent en même temps que citations_delta.

Résultats de recherche

Transmettez les résultats de recherche de votre pipeline RAG sous forme de blocs de contenu de première classe avec prise en charge intégrée des citations.

Prise en charge des PDF

Découvrez comment Claude extrait le texte des PDF et comment les citations basées sur les pages renvoient à vos fichiers sources.

API Files

Téléchargez les documents une seule fois et référencez-les par file_id à travers plusieurs requêtes de citation.

Disponibilité

Citations
API
  • Messages API
  • Managed Agents Non pris en charge
Modèles
  • Tous les modèles

Traitement des données

Présentation du traitement des données

Points de terminaison concernés

  • /v1/messages
Zéro conservation des donnéesÉligible

Exclut Modèles couverts

HIPAAÉligible

Cette page vous a-t-elle été utile ?