Les citations

Quand Claude répond à partir de vos documents, l’utilisateur ne sait pas d’où vient chaque affirmation : du document, ou des connaissances générales du modèle ? Les citations règlent ce problème. Claude rattache chaque affirmation au passage exact du document qui l’appuie, et votre interface peut l’afficher.

Activer les citations

On ajoute deux champs au bloc document : un titre lisible, et citations activé.

add_user_message(messages, [
    {
        "type": "document",
        "source": {"type": "base64", "media_type": "application/pdf", "data": file_data},
        "title": "earth.pdf",
        "citations": {"enabled": True},
    },
    {"type": "text", "text": "Comment l'atmosphère terrestre s'est-elle formée ?"},
])
response = chat(messages)

Sur Vertex, le PDF se fournit toujours ainsi, en base64 : l’offre gérée par Google n’accepte ni URL ni fichier de la Files API. La requête entière, documents compris, reste sous 30 Mo.

Trois règles à connaître :

• dans une requête, les citations s’activent sur tous les documents ou sur aucun ;
• seul le texte peut être cité : les images, y compris celles d’un PDF, ne le sont pas ;
• title et le champ facultatif context sont transmis à Claude, mais ne sont jamais cités : context sert à joindre des métadonnées.

Trois types de documents

Le découpage fixe la plus petite unité citable : avec un découpage en phrases, Claude cite une phrase, ou plusieurs phrases consécutives. Pour des listes à puces, des transcriptions ou des morceaux de RAG que vous ne voulez pas redécouper, le contenu personnalisé laisse vos blocs tels quels. Dans tous les cas, la fin d’une plage est exclusive.

Lire la réponse

Avec les citations, la réponse se compose de plusieurs blocs text. Chacun porte une affirmation, et parfois une liste citations :

for block in response.content:
    if block.type != "text":
        continue
    print(block.text, end="")
    for citation in block.citations or []:
        print(f" [{citation.document_title}, p. {citation.start_page_number} : « {citation.cited_text} »]", end="")
print()

Pour un PDF, chaque citation donne cited_text, le passage cité, document_index, la place du document dans la requête, document_title, puis start_page_number et end_page_number. Pour du texte brut, les pages sont remplacées par start_char_index et end_char_index.

Le texte cité ne coûte rien en sortie : cited_text n’est pas compté dans les jetons de sortie, ni dans les jetons d’entrée quand on le renvoie aux tours suivants. Activer les citations ajoute seulement quelques jetons d’entrée, pour les instructions et le découpage.

Les citations dans une interface

Le vrai bénéfice vient de l’affichage : un repère cliquable à côté de chaque affirmation, qui montre au survol le passage cité, le document et la page. L’utilisateur voit que la réponse s’appuie sur la source, peut la vérifier, et peut lire le contexte autour.

Une incompatibilité à connaître

Les citations ne se combinent pas avec les sorties structurées (output_config.format, leçon 9) : une requête qui active les deux reçoit une erreur 400. Les citations ont besoin d’intercaler leurs références dans le texte, ce qu’un schéma JSON strict interdit.

Quand les utiliser

• quand l’utilisateur doit pouvoir vérifier une information ;
• quand les documents font autorité : contrats, procédures, textes réglementaires ;
• quand la transparence sur les sources compte pour votre application ;
• quand l’utilisateur voudra lire le contexte autour d’un fait.

À vous de jouer

Une réponse vérifiable. Envoyez un document de quelques pages avec les citations activées, posez trois questions, et affichez chaque réponse avec ses citations. Pour chaque citation, ouvrez la page indiquée et vérifiez que le passage y figure.

Sources officielles : Citations (Claude Academy) · Citations (documentation Claude : types de documents, indices, coûts, incompatibilités) · PDF support (documentation Claude : sources en base64 sur Vertex)

Points clés à retenir

• On active les citations par document, avec "citations": {"enabled": True}, sur tous les documents de la requête ou sur aucun.
• Texte brut et PDF sont découpés en phrases ; le contenu personnalisé garde vos blocs.
• Une citation donne le passage cité et sa position : pages pour un PDF, caractères pour du texte, blocs pour un contenu personnalisé.
• cited_text ne compte ni en sortie, ni en entrée quand on le renvoie.
• Citations et sorties structurées sont incompatibles.