Creare e gestire le raccolte
In questa pagina
Da file isolati a una base di conoscenza
Fino ad ora, ogni documento era isolato: lo caricavi, lo riferivi e l’indice costruito per l’occasione scompariva con la query. Le raccolte cambiano la scala: raggruppano i tuoi file in basi di conoscenza strutturate, indicizzate una volta sola e interrogabili all’infinito. Questa è la base del RAG (Retrieval-Augmented Generation) con Grok, e la differenza si nota subito quando un team di supporto interroga duecento schede prodotto invece di un singolo PDF.
Pensa a una raccolta come a una cartella intelligente. Depositi i documenti, xAI li indicizza per la ricerca semantica e Grok esplora questa base per rispondere con precisione, estraendo i tre passaggi utili tra migliaia.
Un’API separata, e perché
Non gestisci le raccolte dall’API che hai usato dall’inizio del corso. Rientrano nella Management API, ospitata su management-api.x.ai, con l’URL di base:
https://management-api.x.ai/v1
Questa separazione non è un capriccio architetturale. Creare, modificare o eliminare una raccolta sono operazioni amministrative con conseguenze pesanti, e xAI richiede una chiave dedicata per esse: una Management API Key, con il permesso AddFileToCollection. Il vantaggio è immediato per i team: il servizio che interroga la base dalla tua applicazione pubblica riceve la chiave standard e non può distruggere nulla; solo la tua pipeline di ingestione possiede la chiave di gestione.
Crea la tua prima raccolta
La creazione si riduce a una singola chiamata con un nome:
curl -X POST https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_name": "technical-docs"}'
La risposta restituisce l’identificatore da conservare:
{
"collection_id": "col_xyz789",
"collection_name": "technical-docs",
"created_at": "2026-04-01T10:00:00Z"
}
Scegli questo nome con cura: apparirà in tutti i tuoi elenchi e, tra sei mesi, sarà l’unico indizio che ti permetterà di distinguere due basi vicine. technical-docs svolge questo ruolo; test2 no. Adotta una convenzione fin dalla prima raccolta, perché rinominare una base già referenziata da tre applicazioni costa più che darle un buon nome fin dall’inizio.
Le cinque operazioni disponibili
La Management API espone un set CRUD completo sulle raccolte:
| Operazione | Metodo | Endpoint |
|---|---|---|
| Creare | POST | /v1/collections |
| Elencare | GET | /v1/collections |
| Dettagli | GET | /v1/collections/{collection_id} |
| Aggiornare | PUT | /v1/collections/{collection_id} |
| Eliminare | DELETE | /v1/collections/{collection_id} |
L’elenco delle tue raccolte avviene senza parametri e offre una panoramica utile prima di qualsiasi operazione di manutenzione:
curl https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
L’eliminazione segue la stessa logica, designando l’identificatore ottenuto alla creazione:
curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Una cosa dovrebbe rassicurarti quando esegui questo comando: eliminare una raccolta rimuove l’indicizzazione, non i file. I tuoi documenti rimangono accessibili tramite la Files API e possono essere reindicizzati altrove. Perdi la struttura di ricerca, non la materia prima, il che rende la ricostruzione di una base mal organizzata molto meno rischiosa di quanto sembri.
Punti chiave
- Le raccolte raggruppano i tuoi file in basi di conoscenza indicizzate per il RAG
- La gestione avviene tramite la Management API (
management-api.x.ai), non l’API standard - È richiesta una Management API Key con il permesso
AddFileToCollection - I limiti sono 100.000 file e 100 GB per account
- Le cinque operazioni CRUD coprono creazione, lettura, aggiornamento ed eliminazione