collections_search și file_search în API-ul Responses
Pe această pagină
Integrarea căutării direct în conversații
Endpoint-ul POST /v1/documents/search funcționează bine pentru întrebări izolate, dar lasă întreaga muncă de orchestrare în seama dumneavoastră: formularea interogării, preluarea fragmentelor, injectarea lor într-un prompt și apelarea modelului. API-ul Responses inversează această sarcină. Prin declararea colecțiilor dumneavoastră ca instrumente, îi permiteți lui Grok să decidă când să caute, ce să caute și cum să transforme aceste informații într-un răspuns. Treceți de la un flux pe care îl conduceți dumneavoastră la un asistent care caută singur în documentele dumneavoastră.
Instrumentul collections_search
Trebuie doar să adăugați un obiect în lista tools pentru a activa acest acces:
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"]
}
]
)
În spatele acestui singur apel, Grok analizează întrebarea, formulează o interogare de căutare adaptată colecției, preia pasajele relevante, le rezumă și citează documentele utilizate. În practică, pentru întrebarea de mai sus, va traduce „concediu de paternitate“ într-o căutare în col_rh_policies, va reține paragrafele din acordul companiei și va returna un număr de zile împreună cu sursa acestora, fără ca dumneavoastră să scrieți o singură linie de logică de preluare.
Instrumentul file_search
Omulogul există pentru fișiere individuale, cele care nu sunt stocate într-o colecție. Nu este nevoie să îl declarați: se activează automat imediat ce cererea dumneavoastră conține 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": "Does this contract contain a non-compete clause?"
}
]
)
Instrumentul attachment_search, echivalent cu file_search, este cel care se activează în fundal. Acest comportament implicit explică o confuzie frecventă: utilizatorii se întreabă de ce declararea file_search în tools pare să nu aibă niciun efect, când de fapt este pur și simplu redundantă.
Două mecanisme, două structuri de costuri
| Aspect | collections_search | file_search / attachment_search |
|---|---|---|
| Sursă | Colecție(i) indexată(e) | Fișier(e) individual(e) |
| Declarare | Explicită în tools | Automată cu input_file |
| Indexare | Pre-calculată | Dinamică (on the fly) |
| Cost | 2,50 $ / 1.000 | 10 $ / 1.000 |
| Performanță | Rapidă (index existent) | Mai lentă (indexare în timp real) |
| Caz de utilizare | Bază de cunoștințe permanentă | Analiză unică |
Rândul „Indexare“ determină toate celelalte. O colecție este indexată o singură dată pentru totdeauna, astfel încât fiecare întrebare reutilizează acea muncă: este rapidă și facturat la 2,50 $ per mie de apeluri. Un fișier atașat este indexat la fiecare cerere, de unde latența suplimentară și costul de 10 $ per mie. Contractul pe care consilierul dumneavoastră juridic îl analizează o singură dată intră în a doua categorie; repository-ul HR interogat de o sută de ori pe zi intră evident în prima.
Combinarea mai multor instrumente
Adevăratul beneficiu al acestei abordări apare atunci când îi oferiți lui Grok mai multe dintre ele, permițându-i să le selecteze pe cele care servesc întrebării.
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"
}
]
)
Această întrebare necesită două mișcări succesive: Grok interogează mai întâi colecția pentru a găsi politica dumneavoastră internă, apoi lansează o căutare pe web pentru reglementările europene actuale și, în final, contrastează cele două în răspunsul său. Nicio orchestrare din partea dumneavoastră, nicio instrucțiune if pentru a decide care dintre cele două surse este relevantă – iar dacă întrebarea s-ar fi concentrat exclusiv pe politica dumneavoastră internă, web-ul nu ar fi fost utilizat.
Rafinarea comportamentului instrumentelor
Trei parametri vă permit să strângeți căutarea declarată în tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: interogarea mai multor colecții simultan
- max_results: limitarea numărului de rezultate pentru a reduce contextul injectat
- retrieval_mode: alegerea modului de căutare (hibrid implicit)
max_results merită o atenție specială: fiecare fragment returnat ocupă context și costă tokeni. Pentru un asistent de suport unde răspunsurile se încadrează în general în două sau trei pasaje, scăderea de la valoarea implicită la cinci rezultate reduce costul fără a degrada calitatea percepută.
Prețuri la data de 5 august 2026 — prețurile se modifică regulat: înainte de a calcula orice buget, verificați prețurile actuale pe pagina oficială a modelelor și prețurilor xAI.
Puncte cheie
collections_searchpermite lui Grok să interogheze automat colecțiile dumneavoastră în timpul unei conversațiifile_search/attachment_searchse activează automat pentru fișierele individuale- Colecțiile sunt de patru ori mai ieftine și mai rapide decât atașamentele de fișiere
- Puteți combina
collections_searchcuweb_searchși alte instrumente - Grok alege automat ce instrumente să utilizeze în funcție de întrebare