collections_search et file_search dans l'API Responses

Integrer la recherche directement dans les conversations

L’endpoint POST /v1/documents/search est utile pour des recherches isolees. Mais la puissance reelle des collections se revele quand vous les integrez comme outils dans l’API Responses. Grok peut alors automatiquement interroger vos bases de connaissances pendant qu’il repond a vos questions.

L’outil collections_search

Quand vous ajoutez collections_search a la liste des outils d’une requete Responses, Grok peut fouiller dans vos collections de maniere autonome :

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

Avec cette configuration, Grok :

1. Analyse la question de l’utilisateur
2. Formule une requete de recherche optimisee pour la collection
3. Recupere les passages pertinents
4. Synthetise une reponse basee sur les documents trouves
5. Cite les sources utilisees

Vous n’avez pas besoin de gerer manuellement le flux recherche-puis-reponse : Grok le fait automatiquement.

L’outil file_search

L’outil file_search fonctionne de maniere similaire mais pour des fichiers individuels (non organises en collection). Il est active automatiquement quand vous utilisez input_file dans votre requete :

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

L’outil attachment_search (equivalent de file_search) s’active automatiquement. Pas besoin de le declarer explicitement dans les tools.

Difference entre les deux approches

Combiner collections_search avec d’autres outils

L’interet majeur de l’approche par outils est la combinaison. Vous pouvez fournir plusieurs outils a Grok et il choisira ceux qui sont pertinents :

response = await client.responses.create(
    model="grok-3",
    input="Compare notre politique interne avec les dernieres reglementations europeennes sur le sujet.",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_politiques_internes"]
        },
        {
            "type": "web_search"
        }
    ]
)

Grok va automatiquement :

1. Chercher dans la collection interne pour trouver la politique
2. Effectuer une recherche web pour les reglementations europeennes
3. Comparer les deux sources dans sa reponse

Parametrer la recherche

Vous pouvez affiner le comportement de collections_search :

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

• collection_ids : interrogez plusieurs collections simultanement
• max_results : limitez le nombre de resultats pour reduire le contexte injecte
• retrieval_mode : choisissez le mode de recherche (hybrid par defaut)

Points cles a retenir

• collections_search permet a 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 cheres 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