Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

collections_search en file_search in de Responses API

Les 11 van 16 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Zoeken direct integreren in conversaties
  2. De collections_search-tool
  3. De file_search-tool
  4. Twee mechanismen, twee kostenstructuren
  5. Meerdere tools combineren
  6. Tool-gedrag verfijnen
  7. Belangrijkste punten

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

Aspectcollections_searchfile_search / attachment_search
BronGeïndexeerde collectie(s)Individueel bestand (bestanden)
DeclaratieExpliciet in toolsAutomatisch met input_file
IndexeringVooraf berekendReal-time
Kosten$2,50 / 1.000$10 / 1.000
PrestatieSnel (bestaande index)Langzamer (real-time indexering)
Use casePermanente kennisbankEenmalige 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_search laat Grok automatisch uw collecties raadplegen tijdens een conversatie
  • file_search / attachment_search activeert 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