collections_search och file_search i Responses API
På denna sida
Integrera sökning direkt i konversationer
Slutpunkten POST /v1/documents/search fungerar bra för isolerade frågor, men den lägger allt orchestreringsarbete på dig: att formulera frågan, hämta utdrag, injicera dem i en prompt och anropa modellen. Responses API vänder på denna börda. Genom att deklarera dina samlingar som ett verktyg låter du Grok avgöra när det ska söka, vad det ska leta efter och hur det ska omvandla det till ett svar. Du går från en pipeline du styr till en assistent som söker i dina dokument själv.
Verktyget collections_search
Du behöver bara lägga till ett objekt i listan tools för att aktivera denna åtkomst:
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"]
}
]
)
Bakom detta enda anrop analyserar Grok frågan, formulerar en sökfråga skräddarsydd för samlingen, hämtar relevanta passager, sammanfattar dem och citerar de använda dokumenten. I praktiken, för frågan ovan, kommer det att översätta “paternity leave” till en sökning i col_rh_policies, behålla styckena från företagsavtalet och returnera antalet dagar tillsammans med källan, utan att du skriver en enda rad hämtningslogik.
Verktyget file_search
Motparten finns för enskilda filer, de som inte lagras i en samling. Du behöver inte deklarera det: det aktiveras automatiskt så snart din begäran innehåller en input_file.
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?"
}
]
)
Det är verktyget attachment_search, motsvarigheten till file_search, som aktiveras i bakgrunden. Detta implicita beteende förklarar en vanlig förvirring: användare undrar varför deklarationen av file_search i tools verkar sakna effekt, när det helt enkelt är överflödigt.
Två mekanismer, två kostnadsstrukturer
| Aspekt | collections_search | file_search / attachment_search |
|---|---|---|
| Källa | Indexerad(e) samling(ar) | Enskild(a) fil(er) |
| Deklaration | Explicit i tools | Automatisk med input_file |
| Indexering | Förberäknad | I realtid |
| Kostnad | $2,50 / 1 000 | $10 / 1 000 |
| Prestanda | Snabbt (befintligt index) | Långsammare (indexering i realtid) |
| Användningsområde | Permanent kunskapsbas | Engångsanalys |
Raden “Indexering” driver alla andra. En samling indexeras en gång för alla, så varje fråga återanvänder det arbetet: det är snabbt och debiteras med $2,50 per tusen anrop. En bifogad fil indexeras vid varje begäran, vilket ger den extra latensen och kostnaden på $10 per tusen. Kontraktet som din juridiska rådgivare analyserar en gång faller i den andra kategorin; HR-arkivet som frågas ut hundra gånger om dagen faller självklart i den första.
Kombinera flera verktyg
Den verkliga fördelen med detta tillvägagångssätt visar sig när du ger Grok flera av dem och låter det välja de som tjänar frågan bäst.
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"
}
]
)
Denna fråga kräver två successiva steg: Grok frågar först samlingen för att hitta er interna policy, startar sedan en webbsökning efter gällande europeiska regleringar och ställer slutligen de två mot varandra i sitt svar. Ingen orchestrering från din sida, inget if-påstående för att avgöra vilken av de två källorna som är relevant – och om frågan hade fokuserat enbart på er interna policy hade webben inte använts.
Förfina verktygets beteende
Tre parametrar låter dig skärpa sökningen som deklareras i tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: fråga flera samlingar samtidigt
- max_results: begränsa antalet resultat för att minska den injicerade kontexten
- retrieval_mode: välj sökläge (hybrid som standard)
max_results förtjänar särskild uppmärksamhet: varje returnerat utdrag tar upp kontext och kostar tokens. På en supportassistent där svaren generellt ryms inom två eller tre passager, minskar en sänkning från standardvärdet till fem resultat kostnaden utan att försämra den upplevda kvaliteten.
Priser från den 5 augusti 2026 – priserna ändras regelbundet: innan du beräknar någon budget, kontrollera de aktuella priserna på den officiella sidan för xAI-modeller och prissättning.
Viktiga punkter
collections_searchlåter Grok automatiskt fråga dina samlingar under en konversationfile_search/attachment_searchaktiveras automatiskt för enskilda filer- Samlingar är fyra gånger billigare och snabbare än filbilagor
- Du kan kombinera collections_search med web_search och andra verktyg
- Grok väljer automatiskt vilka verktyg som ska användas baserat på frågan