collections_search et file_search dans l'API Responses

Intégrer la recherche directement dans les conversations

L’endpoint POST /v1/documents/search répond très bien à une question isolée, mais il vous laisse tout le travail d’orchestration : formuler la requête, récupérer les extraits, les injecter dans un prompt, appeler le modèle. L’API Responses inverse la charge. En déclarant vos collections comme un outil, vous laissez Grok décider quand fouiller, quoi chercher et comment en faire une réponse. Vous passez d’un pipeline que vous pilotez à un assistant qui va chercher lui-même dans vos documents.

L’outil collections_search

Il suffit d’ajouter un objet dans la liste tools pour ouvrir cet accès :

response = await client.responses.create(
    model="grok-4.5",
    input="Quelle est notre politique de conge paternite ?",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_rh_policies"]
        }
    ]
)

Derrière cet appel unique, Grok analyse la question posée, formule une requête de recherche adaptée à la collection, récupère les passages pertinents, en fait une synthèse et cite les documents utilisés. Concrètement, sur la question ci-dessus, il traduira « congé paternité » en une recherche dans col_rh_policies, retiendra les paragraphes de l’accord d’entreprise et vous rendra un nombre de jours accompagné de sa source, sans que vous ayez écrit une seule ligne de logique de récupération.

L’outil file_search

Le pendant existe pour les fichiers isolés, ceux qui ne sont pas rangés dans une collection. Nul besoin de le déclarer : il s’arme tout seul dès que votre requête contient un input_file.

response = await client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_file",
            "file_id": "file_contrat_abc"
        },
        {
            "type": "input_text",
            "text": "Ce contrat contient-il une clause de non-concurrence ?"
        }
    ]
)

C’est l’outil attachment_search, équivalent de file_search, qui s’active en arrière-plan. Ce comportement implicite explique une confusion fréquente : on cherche pourquoi la déclaration de file_search dans tools semble sans effet, alors qu’elle est simplement redondante.

Deux mécanismes, deux économies

La ligne « indexation » commande toutes les autres. Une collection est indexée une fois pour toutes, donc chaque question réutilise ce travail : c’est rapide et facturé 2,50 $ par millier d’appels. Un fichier joint est indexé à chaque requête, d’où la latence supplémentaire et les 10 $ par millier. Le contrat que votre juriste analyse une seule fois relève du second cas ; le référentiel RH interrogé cent fois par jour relève évidemment du premier.

Combiner plusieurs outils

L’intérêt véritable de cette approche apparaît quand vous en donnez plusieurs à Grok, qui sélectionne alors ceux qui servent la question.

response = await client.responses.create(
    model="grok-4.5",
    input="Compare notre politique interne avec les dernières réglementations européennes sur le sujet.",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_politiques_internes"]
        },
        {
            "type": "web_search"
        }
    ]
)

Cette question appelle deux mouvements successifs : Grok interroge d’abord la collection pour retrouver votre politique interne, lance ensuite une recherche web pour la réglementation européenne en vigueur, puis confronte les deux dans sa réponse. Aucune orchestration de votre côté, aucun if pour décider laquelle des deux sources est pertinente — et si la question avait porté uniquement sur votre politique interne, le web n’aurait pas été sollicité.

Affiner le comportement de l’outil

Trois paramètres permettent de resserrer la recherche déclarée dans tools.

tools=[
    {
        "type": "collections_search",
        "collection_ids": ["col_docs_1", "col_docs_2"],
        "max_results": 10,
        "retrieval_mode": "hybrid"
    }
]

• collection_ids : interrogez plusieurs collections simultanément
• max_results : limitez le nombre de résultats pour réduire le contexte injecté
• retrieval_mode : choisissez le mode de recherche (hybrid par défaut)

max_results mérite votre attention particulière : chaque extrait remonté occupe du contexte et se paie en tokens. Sur un assistant de support où les réponses tiennent en général dans deux ou trois passages, descendre de la valeur par défaut à cinq résultats allège la facture sans dégrader la qualité perçue.

Tarifs relevés le 5 août 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille en vigueur sur la page officielle des modèles et tarifs xAI.

Points clés à retenir

• collections_search permet à Grok d’interroger automatiquement vos collections pendant une conversation
• file_search / attachment_search s’active automatiquement pour les fichiers individuels
• Les collections sont quatre fois moins chères et plus rapides que les file attachments
• Vous pouvez combiner collections_search avec web_search et d’autres outils
• Grok choisit automatiquement quels outils utiliser selon la question