Formati di file supportati
In questa pagina
L’unico criterio che conta
Prima di chiederti se un formato specifico funziona, poniti una domanda più semplice: il file contiene testo estraibile? Le Files API di xAI gestiscono file di testo. Se qualsiasi strumento riesce a estrarne i caratteri senza ricorrere al riconoscimento ottico dei caratteri (OCR), il documento verrà probabilmente accettato. I file puramente binari—immagini, audio, video—non appartengono a questa categoria; per un’immagine, l’approccio corretto è utilizzare input_image nelle Responses API, non nelle Files API.
Questo singolo criterio spiega la maggior parte dei rifiuti che incontrerai. Spiega anche perché un report finanziario in PDF funziona perfettamente mentre un PDF proveniente da uno scanner desktop fallisce: il primo possiede un livello di testo, il secondo è solo una serie di fotografie di pagine.
Le quattro categorie supportate
I formati supportati rientrano in quattro categorie, ognuna con i suoi usi preferiti.
| Categoria | Formati | Cosa estrae Grok |
|---|---|---|
| Documenti per ufficio | PDF, DOCX, ODT, EPUB, RTF | Testo, tabelle, struttura delle sezioni |
| Codice sorgente | .py, .js, .ts, .java, .go, .rs, .cpp, HTML, CSS, XML e oltre 80 linguaggi | Import, dipendenze, struttura dei file |
| Dati strutturati | CSV, TSV, JSON, JSON-LD, vCard | Gerarchia dei campi, statistiche, trend |
| Testo semplice | TXT, MD | Contenuto lineare, titoli ed elenchi Markdown |
Per quanto riguarda i documenti per ufficio, il PDF rimane il formato più comune e Grok ne estrae il testo, le tabelle e la suddivisione in sezioni. Un DOCX di Word mantiene la sua formattazione—grassetto, corsivo, elenchi—nell’estrazione, proprio come il suo equivalente open source ODT. L’EPUB diventa interessante non appena lavori su pubblicazioni lunghe, un white paper o un intero manuale, mentre l’RTF, sebbene più datato, rimane abbastanza diffuso da essere supportato.
Il codice sorgente è l’ambito in cui le Files API si distinguono più chiaramente dal copia-incolla. Inviare payment.py nella sua interezza invece di una funzione isolata cambia la natura dell’analisi: Grok vede gli import, le dipendenze e l’organizzazione del file, e può quindi individuare che un’eccezione viene catturata trenta righe più su o che una costante definita all’inizio contraddice un commento alla fine. Sono coperti oltre 80 linguaggi con sintassi basata sul testo.
I formati di dati servono principalmente all’analisi quantitativa. Un CSV delle vendite mensili permette a Grok di calcolare le varianze, individuare la stagionalità e riassumere un dataset di diverse migliaia di righe; una configurazione JSON o una risposta API gli danno accesso alla gerarchia e alle relazioni tra i campi, cosa che una tabella appiattita non mostrerebbe. JSON-LD aggiunge contesto semantico ai dati collegati e vCard copre i biglietti da visita. Infine, TXT e MD funzionano come previsto, con Markdown che offre il vantaggio di trasmettere una struttura leggera di titoli ed elenchi.
Errori comuni
Quattro vincoli ricorrono costantemente in produzione. Il primo è la dimensione: 48 MB per file, oltre i quali devi suddividere il documento. Il secondo è la codifica: i tuoi file devono essere in UTF-8 e un’esportazione in ISO-8859 o Windows-1252 produrrà caratteri accentati corrotti, a volte in modo sottile—un `é` che diventa `é` nel mezzo di un contratto passa inosservato finché una ricerca non restituisce nulla. Il terzo è la mancanza di elaborazione delle immagini: PNG, JPG o GIF non appartengono a questo contesto, devi usare input_image. Il quarto riguarda il caso di un PDF scansionato privo di livello di testo OCR, che verrà accettato al caricamento ma non restituirà risultati quando interrogato.
Quest’ultima situazione richiede una semplice abitudine: prima di caricare un lotto di PDF di origine incerta, aprine uno e prova a selezionare un paragrafo con il mouse. Se non si seleziona nulla, i tuoi documenti devono passare attraverso un processo di OCR preliminare.
Scegli il formato più strutturato possibile
Quando la stessa informazione esiste in più forme, scegli sempre quella più strutturata. Per l’analisi di report, preferisci il PDF o il DOCX originale, che preservano la gerarchia, piuttosto che un’esportazione di testo piatto. Per l’analisi dei dati, un CSV per le tabelle e JSON per i dati gerarchici daranno risultati migliori rispetto a un’esportazione di foglio di calcolo trasformata in testo semplice. Per una revisione del codice, invia il file sorgente originale con la sua estensione originale. Per la documentazione, Markdown o PDF funzionano a seconda di ciò che hai alla fonte. La regola si riassume in una frase: ogni livello di struttura che mantieni è un livello di contesto che il modello non dovrà ricostruire.
Punti chiave
- Le Files API supportano documenti (PDF, DOCX, EPUB), codice (oltre 80 linguaggi), dati (CSV, JSON) e testo semplice
- Il limite è di 48 MB per file con codifica UTF-8
- Immagini e file binari non sono supportati: usa
input_imageper le immagini - Preferisci sempre il formato più strutturato possibile per ottenere un’analisi migliore