input_file e attachment_search nelle API Responses
In questa pagina
Due percorsi per lo stesso blocco
Le API Responses di Grok accettano un documento in due modi: tramite file_id, ovvero un file che hai caricato in precedenza, o tramite file_url, un indirizzo pubblico che xAI recupera al momento della richiesta. Il blocco utilizza lo stesso nome in entrambi i casi, input_file, e l’elaborazione a valle è identica: Grok attiva lo strumento attachment_search ed estrae i passaggi che rispondono alla tua domanda. Ciò che cambia è il ciclo di vita del documento, la sua riservatezza e il costo di ogni chiamata ripetuta.
Il percorso file_id
Una volta inviato il file tramite POST /v1/files, lo riferisci tramite il suo identificatore, insieme alla tua domanda in testo semplice:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123"
},
{
"type": "input_text",
"text": "What are the main risks mentioned in this report?"
}
]
}
Questo percorso ha senso in tre situazioni. La prima riguarda le query ripetute: se il tuo team legale pone quindici domande successive sullo stesso contratto, un singolo caricamento seguito da quindici riferimenti è preferibile a quindici trasferimenti dello stesso PDF. La seconda è la riservatezza, quando il documento non deve essere esposto dietro un URL accessibile a chiunque possieda il link. La terza riguarda l’architettura della tua applicazione: se i file vengono precaricati durante l’ingestione notturna, le tue richieste gestiscono solo gli identificatori.
Il percorso file_url
Quando il documento è già pubblicato da qualche parte, il caricamento diventa un passaggio inutile e puoi puntare direttamente all’indirizzo:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_url": "https://exemple.com/specifications-api.pdf"
},
{
"type": "input_text",
"text": "Summarize the endpoints described in this documentation."
}
]
}
I casi d’uso tipici includono documentazione aperta che non hai motivo di archiviare, un file ospitato sulla tua infrastruttura dietro un URL temporaneo o un test rapido in cui desideri verificare un’ipotesi senza configurare un’intera pipeline di caricamento.
Tre limitazioni accompagnano questa comodità e tutte ti costano in produzione. L’URL deve essere veramente pubblico, senza autenticazione: un indirizzo protetto da token o cookie restituisce una pagina di errore a xAI, che il modello analizzerà diligentemente al posto del tuo documento. Il download si aggiunge al tempo di elaborazione della richiesta, rendendo i PDF di grandi dimensioni significativamente più lenti rispetto all’uso di file_id. Infine, non esiste alcuna cache lato xAI: ogni chiamata riscarica il file, quindi un singolo documento interrogato cinquanta volte al giorno attraversa la rete cinquanta volte.
Cosa fa attachment_search
Non appena appare un input_file nella tua richiesta, Grok attiva attachment_search senza alcuna configurazione da parte tua. L’elaborazione avviene in quattro fasi:
- Estrazione del contenuto dal file: testo, tabelle, struttura
- Indicizzazione temporanea di questo contenuto, per la durata della richiesta
- Ricerca dei passaggi rilevanti in base alla tua domanda
- Iniezione degli estratti nel contesto del modello
Concentrati sull’aggettivo “temporanea” nel secondo passaggio, perché spiega una differenza di costo che molti scoprono troppo tardi: l’indice viene ricostruito a ogni chiamata e scompare successivamente. Questo è esattamente il problema che le collezioni risolvono con l’indicizzazione persistente. Nota inoltre che il modello cita i passaggi che ha effettivamente utilizzato nella sua risposta, permettendoti di verificare il suo lavoro piuttosto che prenderlo sulla parola.
Combinare più documenti
Niente ti obbliga a limitarti a un file per richiesta. Sovrapponendo più blocchi input_file, chiedi al modello di ragionare sull’insieme:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_rapport_q1"
},
{
"type": "input_file",
"file_id": "file_rapport_q2"
},
{
"type": "input_text",
"text": "Compare the Q1 and Q2 results."
}
]
}
Grok analizza entrambi i documenti e incrocia le informazioni per rispondere, il che apre la porta a confronti trimestrali, revisioni di versioni successive di contratti o confronti tra una specifica e la sua implementazione.
Scegliere tra i due
| Criterio | file_id | file_url |
|---|---|---|
| Caricamento preliminare | Sì | No |
| File riservato | Consigliato | Sconsigliato |
| Query ripetute | Performante (1 caricamento) | Lento (riscaricamento) |
| File pubblico | Possibile | Ideale |
| Gestione del ciclo di vita | Tu controlli | Dipende dall’host |
Punti chiave
input_fileconfile_idriferisce un file caricato,file_urlun documento pubblico- Lo strumento
attachment_searchsi attiva automaticamente per estrarre il contenuto rilevante - Puoi combinare più file in un’unica richiesta
- Preferisci
file_idper file riservati o frequentemente interrogati - Preferisci
file_urlper documenti pubblici o test rapidi