Citations

Claude peut fournir des citations détaillées lorsqu'il répond à des questions sur des documents, vous aidant ainsi à 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",
    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)



Fonctionnement des citations

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



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 ne sont pas 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é en chaîne.



Index de citation

• Les index de documents sont indexés à partir de 0 à partir de la liste de tous les blocs de contenu de document dans la requête (couvrant tous les messages).
• Les index de caractères sont indexés à partir de 0 avec des index de fin exclusifs.
• Les numéros de page sont indexés à partir de 1 avec des numéros de page de fin exclusifs.
• Les index de blocs de contenu sont indexés à partir de 0 avec des index de fin exclusifs à partir 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 à 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é qui est ensuite analysé en texte cité et en index d'emplacement de document. Le champ cited_text est fourni pour plus de commodité et n'est pas comptabilisé dans les tokens de sortie.
• Lorsqu'il est retransmis dans les tours de conversation suivants, cited_text n'est pas non plus comptabilisé 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.



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 auxquels ils font référence peuvent l'être. Pour optimiser les performances, appliquez cache_control à vos blocs de contenu de document de niveau supérieur.

client = anthropic.Anthropic()

# Contenu de document long (par exemple, 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",
    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 en utilisant 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 ultérieures 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éversés via l'API Files et référencés par file_id :



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": "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, d'URL ou par file_id. Le texte du 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",
    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",
    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 du bloc de contenu text actuel.



Étapes suivantes