Vai al contenuto principale
Italiano— Scegli una lingua
Menu

collections_search e file_search nelle API Responses

Lezione 11 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Integra la ricerca direttamente nelle conversazioni
  2. Lo strumento collections_search
  3. Lo strumento file_search
  4. Due meccanismi, due strutture di costo
  5. Combina più strumenti
  6. Affina il comportamento degli strumenti
  7. Punti chiave

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.

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.

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

Aspettocollections_searchfile_search / attachment_search
FonteCollezione/i indicizzata/eFile singoli
DichiarazioneEsplicita in toolsAutomatica con input_file
IndicizzazionePre-calcolataAl volo
Costo$2.50 / 1.000$10 / 1.000
PrestazioniVeloci (indice esistente)Più lente (indicizzazione in tempo reale)
Caso d’usoBase di conoscenza permanenteAnalisi 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_search permette a Grok di interrogare automaticamente le tue collezioni durante una conversazione
  • file_search / attachment_search si 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