collections_search en file_search in de Responses API
Op deze pagina
Zoeken direct integreren in conversaties
Het eindpunt POST /v1/documents/search werkt goed voor geïsoleerde vragen, maar het laat al het orchestratiewerk aan u over: het formuleren van de query, het ophalen van fragmenten, het injecteren ervan in een prompt en het aanroepen van het model. De Responses API draait deze last om. Door uw collecties als tool te declareren, laat u Grok beslissen wanneer er gezocht moet worden, waarnaar gezocht moet worden en hoe dit omgezet wordt in een antwoord. U schakelt over van een pipeline die u aanstuurt naar een assistent die zelf in uw documenten zoekt.
De collections_search-tool
U hoeft slechts één object aan de tools-lijst toe te voegen om deze toegang mogelijk te maken:
response = await client.responses.create(
model="grok-4.5",
input="What is our paternity leave policy?",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_rh_policies"]
}
]
)
Achter deze ene aanroep analyseert Grok de vraag, formuleert het een zoekopdracht op maat voor de collectie, haalt het relevante passages op, vat deze samen en citeert de gebruikte documenten. In de praktijk zal het voor bovenstaande vraag “vaderschapsverlof” vertalen naar een zoekopdracht in col_rh_policies, de paragrafen uit de cao behouden en een aantal dagen retourneren samen met de bron, zonder dat u ook maar één regel ophaallogica hoeft te schrijven.
De file_search-tool
Het tegenhanger bestaat voor individuele bestanden, die niet in een collectie zijn opgeslagen. Het is niet nodig dit te declareren: het activeert automatisch zodra uw verzoek een input_file bevat.
response = await client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_file",
"file_id": "file_contrat_abc"
},
{
"type": "input_text",
"text": "Does this contract contain a non-compete clause?"
}
]
)
Het is de attachment_search-tool, equivalent aan file_search, die op de achtergrond activeert. Dit impliciete gedrag verklaart een veelvoorkomende verwarring: gebruikers vragen zich af waarom het declareren van file_search in tools geen effect lijkt te hebben, terwijl het simpelweg overbodig is.
Twee mechanismen, twee kostenstructuren
| Aspect | collections_search | file_search / attachment_search |
|---|---|---|
| Bron | Geïndexeerde collectie(s) | Individueel bestand (bestanden) |
| Declaratie | Expliciet in tools | Automatisch met input_file |
| Indexering | Vooraf berekend | Real-time |
| Kosten | $2,50 / 1.000 | $10 / 1.000 |
| Prestatie | Snel (bestaande index) | Langzamer (real-time indexering) |
| Use case | Permanente kennisbank | Eenmalige analyse |
De regel “indexering” stuurt alle andere aan. Een collectie wordt eenmalig en voor altijd geïndexeerd, zodat elke vraag dat werk hergebruikt: het is snel en wordt gefactureerd tegen $2,50 per duizend aanroepen. Een bijgevoegd bestand wordt bij elk verzoek geïndexeerd, vandaar de extra latentie en de $10 per duizend. Het contract dat uw juridisch adviseur eenmaal analyseert, valt in de tweede categorie; het HR-archief dat honderd keer per dag wordt bevraagd, valt uiteraard in de eerste.
Meerdere tools combineren
Het echte voordeel van deze aanpak wordt duidelijk wanneer u Grok meerdere tools geeft, zodat het de tools kan selecteren die het beste bij de vraag passen.
response = await client.responses.create(
model="grok-4.5",
input="Compare our internal policy with the latest European regulations on the subject.",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_politiques_internes"]
},
{
"type": "web_search"
}
]
)
Deze vraag vereist twee opeenvolgende stappen: Grok raadpleegt eerst de collectie om uw interne beleid te vinden, start vervolgens een webzoekopdracht voor de huidige Europese regelgeving en contrasteert vervolgens de twee in zijn antwoord. Geen orchestratie aan uw kant, geen if-statement om te beslissen welke van de twee bronnen relevant is—en als de vraag zich uitsluitend op uw interne beleid had gericht, zou het web niet zijn gebruikt.
Tool-gedrag verfijnen
Drie parameters stellen u in staat het zoeken dat in tools is gedeclareerd, aan te scherpen.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: vraag meerdere collecties gelijktijdig af
- max_results: beperk het aantal resultaten om de geïnjecteerde context te verminderen
- retrieval_mode: kies de zoekmodus (standaard hybride)
max_results verdient speciale aandacht: elk teruggegeven fragment neemt context in beslag en kost tokens. Bij een supportassistent waar antwoorden doorgaans binnen twee of drie passages passen, verlaagt het verlagen van de standaardwaarde naar vijf resultaten de kosten zonder de waargenomen kwaliteit te verslechteren.
Prijzen per 5 augustus 2026 — prijzen wijzigen regelmatig: controleer voordat u een budget berekent de huidige prijzen op de officiële xAI-modellen en prijzenpagina.
Belangrijkste punten
collections_searchlaat Grok automatisch uw collecties raadplegen tijdens een conversatiefile_search/attachment_searchactiveert automatisch voor individuele bestanden- Collecties zijn vier keer goedkoper en sneller dan bestandsbijlagen
- U kunt collections_search combineren met web_search en andere tools
- Grok kiest automatisch welke tools het gebruikt op basis van de vraag