Vai al contenuto principale
Italiano— Scegli una lingua
Menu

input_file e attachment_search nelle API Responses

Lezione 4 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Due percorsi per lo stesso blocco
  2. Il percorso file_id
  3. Il percorso file_url
  4. Cosa fa attachment_search
  5. Combinare più documenti
  6. Scegliere tra i due
  7. Punti chiave

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.

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:

  1. Estrazione del contenuto dal file: testo, tabelle, struttura
  2. Indicizzazione temporanea di questo contenuto, per la durata della richiesta
  3. Ricerca dei passaggi rilevanti in base alla tua domanda
  4. 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

Criteriofile_idfile_url
Caricamento preliminareSìNo
File riservatoConsigliatoSconsigliato
Query ripetutePerformante (1 caricamento)Lento (riscaricamento)
File pubblicoPossibileIdeale
Gestione del ciclo di vitaTu controlliDipende dall’host

Punti chiave

  • input_file con file_id riferisce un file caricato, file_url un documento pubblico
  • Lo strumento attachment_search si attiva automaticamente per estrarre il contenuto rilevante
  • Puoi combinare più file in un’unica richiesta
  • Preferisci file_id per file riservati o frequentemente interrogati
  • Preferisci file_url per documenti pubblici o test rapidi