Exploiter les Citations dans les Résultats

Des réponses traçables grâce aux citations

Quand un utilisateur pose une question factuelle à votre application, il veut pouvoir vérifier l’information. Les citations de l’API Grok répondent exactement à ce besoin : chaque fait récupéré par la recherche web est accompagné de sa source. Vous pouvez ainsi construire des interfaces où chaque affirmation est cliquable et vérifiable.

L’API propose deux mécanismes complémentaires de citations : les citations globales et les citations inline. Comprendre leur fonctionnement vous permettra de créer des expériences utilisateur professionnelles et transparentes.

Citations globales : la liste complète des sources

Les citations globales sont retournées par défaut dans l’attribut citations de la réponse. Elles contiennent la liste de toutes les URLs consultées par le modèle, même celles qui ne sont pas directement référencées dans le texte de la réponse.

response = client.responses.create(
    model="grok-3",
    input="Quels sont les derniers règlements IA en Europe ?",
    tools=[{"type": "web_search"}]
)

# Accéder aux citations globales
for citation in response.citations:
    print(f"Source : {citation.url}")

Aucune configuration supplémentaire n’est nécessaire. C’est le comportement natif de l’API.

Citations inline : des références dans le texte

Les citations inline insèrent des liens Markdown directement dans le texte de la réponse, au format [[N]](url) où N est un numéro séquentiel commençant à 1. Si la même source est citée plusieurs fois, le numéro original est réutilisé.

Le comportement par défaut dépend du SDK utilisé :

• Responses API directe : citations inline activées par défaut
• xAI SDK : citations inline désactivées par défaut (opt-in)

Activer les citations inline avec le xAI SDK

response = client.responses.create(
    model="grok-3",
    input="État actuel de l'IA Act européen",
    tools=[{"type": "web_search"}],
    include=["inline_citations"]
)

Désactiver les citations inline sur l’API Responses

response = client.responses.create(
    model="grok-3",
    input="État actuel de l'IA Act européen",
    tools=[{"type": "web_search"}],
    include=["no_inline_citations"]
)

Le schéma d’annotation structuré

Chaque citation inline génère un objet d’annotation avec des métadonnées précises. Cette structure permet un traitement programmatique avancé :

{
  "type": "url_citation",
  "url": "https://eur-lex.europa.eu/eli/reg/2024/1689",
  "start_index": 145,
  "end_index": 178,
  "title": "1"
}

Les champs start_index et end_index suivent la convention Python slice. Vous pouvez les utiliser pour extraire le texte exact de la citation ou pour créer un rendu HTML personnalisé :

text = response.output_text

for annotation in response.annotations:
    cited_text = text[annotation.start_index:annotation.end_index]
    print(f"Texte cité : {cited_text}")
    print(f"Source : {annotation.url}")

Comportement en streaming

Lorsque vous utilisez le streaming, les citations inline apparaissent progressivement dans les chunks de texte. Les annotations complètes ne sont cependant disponibles que sur la réponse finale. Prévoyez un traitement en deux temps si votre interface affiche les sources en temps réel.

Construire une interface avec sources

Voici un exemple de transformation des citations en HTML structuré :

def format_response_with_sources(response):
    text = response.output_text
    sources = []

    # Collecter les sources uniques
    seen_urls = set()
    for citation in response.citations:
        if citation.url not in seen_urls:
            sources.append(citation.url)
            seen_urls.add(citation.url)

    # Construire le rendu
    html = f"<div class='response'>{text}</div>"
    html += "<div class='sources'><h4>Sources</h4><ul>"
    for i, url in enumerate(sources, 1):
        html += f"<li><a href='{url}'>[{i}] {url}</a></li>"
    html += "</ul></div>"

    return html

Citations des collections

Si vous utilisez l’outil collections_search en parallèle de web_search, les citations provenant de vos documents uploadés utilisent un format URI spécifique : collections://collection_id/files/file_id. Distinguez-les des citations web classiques pour adapter le rendu côté front-end.

Mise en pratique

Créez une application qui affiche les résultats de recherche Grok avec un système de notes de bas de page. Chaque fait doit renvoyer vers sa source d’origine. Testez avec des questions d’actualité et vérifiez manuellement que les liens sont valides et pertinents.

Points clés à retenir

• Les citations globales (liste d’URLs) sont retournées par défaut, sans configuration
• Les citations inline (liens dans le texte) s’activent via le paramètre include
• Le comportement par défaut des citations inline varie selon le SDK utilisé
• Chaque annotation contient l’URL, les indices de position et le numéro de citation
• En streaming, les annotations complètes ne sont disponibles que sur la réponse finale
• Les citations de collections utilisent un format URI distinct (collections://)