Citations

Claude est capable de fournir des citations détaillées lors de la réponse à des questions sur des documents, vous aidant à suivre et vérifier les sources d'information dans les réponses.

Tous les modèles actifs supportent les citations, à l'exception de Haiku 3.

Voici un exemple de la façon d'utiliser les citations avec l'API Messages :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 :

Contenu citable vs non-citable

• Le texte trouvé dans le contenu source du 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, vous pouvez donc trouver le champ context utile pour stocker les métadonnées du document sous forme de texte ou de json stringifié.

Indices de citation

• Les indices de document sont indexés à partir de 0 à partir de 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 à partir de la liste content fournie dans le document de contenu personnalisé.

Coûts en jetons

• L'activation des citations entraîne une légère augmentation des jetons d'entrée en raison des ajouts de messages système et de la fragmentation des documents.
• Cependant, la fonctionnalité de citations est très efficace avec les jetons de sortie. Sous le capot, 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 la commodité et ne compte pas vers les jetons de sortie.
• Lorsqu'il est renvoyé dans les tours de conversation ultérieurs, cited_text n'est pas non plus compté vers les jetons d'entrée.

Compatibilité des fonctionnalités

Les citations fonctionnent en conjonction avec d'autres fonctionnalités de l'API, notamment la mise en cache des invites, le comptage des jetons et le traitement par lots.

Utilisation de la mise en cache des invites avec les citations

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

Les blocs de citations générés dans les réponses ne peuvent pas être mis en cache directement, mais les documents source 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()

# Long document content (e.g., technical documentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-7",
    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éficieront du contenu mis en cache

Types de documents

Choisir un type de document

Trois types de documents sont supportés 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 :

Documents en texte brut

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

Documents PDF

Les documents PDF peuvent être fournis sous forme de données codées en base64 ou par file_id. Le texte PDF est extrait et fragmenté en phrases. Comme les citations d'images ne sont pas encore supportées, les PDFs qui sont des scans de documents et ne contiennent pas de texte extractible ne seront pas citables.

Documents de contenu personnalisé

Les documents de contenu personnalisé vous donnent le contrôle sur la granularité des citations. Aucune fragmentation supplémentaire n'est effectuée et les fragments sont fournis au modèle selon les blocs de contenu fournis.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"},
        ],
    },
    "title": "Document Title",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "citations": {"enabled": True},
}

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,
                }
            ],
        },
    ]
}

Support du streaming

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