collections_search e file_search nelle API Responses
In questa pagina
Integra la ricerca direttamente nelle conversazioni
L’endpoint POST /v1/documents/search funziona bene per domande isolate, ma lascia tutto il lavoro di orchestrazione a te: formulare la query, recuperare gli estratti, iniettarli in un prompt e chiamare il modello. Le API Responses ribaltano questo onere. Dichiarando le tue collezioni come strumento, lasci che Grok decida quando cercare, cosa cercare e come trasformare i risultati in una risposta. Passi da una pipeline che guidi tu a un assistente che cerca nei tuoi documenti autonomamente.
Lo strumento collections_search
Ti basta aggiungere un oggetto alla lista tools per abilitare questo accesso:
response = await client.responses.create(
model="grok-4.5",
input="Qual è la nostra politica sul congedo di paternità?",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_rh_policies"]
}
]
)
Dietro questa singola chiamata, Grok analizza la domanda, formula una query di ricerca adattata alla collezione, recupera i passaggi rilevanti, li riassume e cita i documenti utilizzati. In pratica, per la domanda sopra, tradurrà “congedo di paternità” in una ricerca in col_rh_policies, conserverà i paragrafi dell’accordo aziendale e restituirà un numero di giorni insieme alla sua fonte, senza che tu scriva una sola riga di logica di recupero.
Lo strumento file_search
Esiste un equivalente per i singoli file, quelli non archiviati in una collezione. Non c’è bisogno di dichiararlo: si attiva automaticamente non appena la tua richiesta contiene 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": "Questo contratto contiene una clausola di non concorrenza?"
}
]
)
È lo strumento attachment_search, equivalente a file_search, che si attiva in background. Questo comportamento implicito spiega una confusione comune: gli utenti si chiedono perché dichiarare file_search in tools sembri non avere alcun effetto, quando in realtà è semplicemente ridondante.
Due meccanismi, due strutture di costo
| Aspetto | collections_search | file_search / attachment_search |
|---|---|---|
| Fonte | Collezione/i indicizzata/e | File singoli |
| Dichiarazione | Esplicita in tools | Automatica con input_file |
| Indicizzazione | Pre-calcolata | Al volo |
| Costo | $2.50 / 1.000 | $10 / 1.000 |
| Prestazioni | Veloci (indice esistente) | Più lente (indicizzazione in tempo reale) |
| Caso d’uso | Base di conoscenza permanente | Analisi una tantum |
La riga “Indicizzazione” guida tutte le altre. Una collezione viene indicizzata una volta per tutte, quindi ogni domanda riutilizza quel lavoro: è veloce e fatturata a $2.50 per mille chiamate. Un file allegato viene indicizzato a ogni richiesta, da qui la latenza aggiuntiva e il costo di $10 per mille. Il contratto che il tuo consulente legale analizza una volta rientra nella seconda categoria; il repository HR interrogato cento volte al giorno rientra ovviamente nella prima.
Combina più strumenti
Il vero vantaggio di questo approccio emerge quando fornisci a Grok diversi strumenti, lasciandogli la possibilità di selezionare quelli utili alla domanda.
response = await client.responses.create(
model="grok-4.5",
input="Confronta la nostra politica interna con le ultime normative europee in materia.",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_politiques_internes"]
},
{
"type": "web_search"
}
]
)
Questa domanda richiede due mosse successive: Grok interroga prima la collezione per trovare la tua politica interna, poi lancia una ricerca web per le normative europee attuali, infine confronta le due cose nella sua risposta. Nessuna orchestrazione da parte tua, nessuna istruzione if per decidere quale delle due fonti sia rilevante; e se la domanda si fosse concentrata solo sulla tua politica interna, il web non sarebbe stato utilizzato.
Affina il comportamento degli strumenti
Tre parametri ti permettono di stringere la ricerca dichiarata in tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: interroga più collezioni simultaneamente
- max_results: limita il numero di risultati per ridurre il contesto iniettato
- retrieval_mode: scegli la modalità di ricerca (ibrida per impostazione predefinita)
max_results merita un’attenzione speciale: ogni estratto restituito occupa contesto e costa token. Su un assistente di supporto dove le risposte rientrano generalmente in due o tre passaggi, scendere dal valore predefinito a cinque risultati riduce il costo senza degradare la qualità percepita.
Prezzi aggiornati al 5 agosto 2026 — i prezzi cambiano regolarmente: prima di calcolare qualsiasi budget, verifica i prezzi attuali sulla pagina ufficiale dei modelli e dei prezzi xAI.
Punti chiave
collections_searchpermette a Grok di interrogare automaticamente le tue collezioni durante una conversazionefile_search/attachment_searchsi attiva automaticamente per i file singoli- Le collezioni sono quattro volte più economiche e veloci degli allegati file
- Puoi combinare collections_search con web_search e altri strumenti
- Grok sceglie automaticamente quali strumenti utilizzare in base alla domanda