Crearea și gestionarea colecțiilor
Pe această pagină
De la fișiere izolate la o bază de cunoștințe
Până acum, fiecare document stătea singur: îl încărcați, făceați referire la el, iar indexul construit pentru acea ocazie dispărea odată cu interogarea. Colecțiile schimbă scala: ele grupează fișierele dumneavoastră în baze de cunoștințe structurate, indexate o singură dată și interogabile la infinit. Aceasta este fundația RAG (Retrieval-Augmented Generation) cu Grok, iar diferența se observă imediat când o echipă de suport interogează două sute de fișe de produs în loc de un singur PDF.
Gândiți-vă la o colecție ca la un dosar inteligent. Depuneți documente, xAI le indexează pentru căutare semantică, iar Grok caută în această bază pentru a răspunde cu precizie, extrăgând cele trei pasaje utile din mii de alte date.
Un API separat și motivul existenței sale
Nu gestionați colecțiile prin API-ul pe care l-ați utilizat de la începutul cursului. Acestea intră sub incidența Management API, găzduit pe management-api.x.ai, cu URL-ul de bază:
https://management-api.x.ai/v1
Această separare nu este un moft arhitectural. Crearea, modificarea sau ștergerea unei colecții sunt operațiuni administrative cu consecințe majore, iar xAI solicită o cheie dedicată pentru acestea: o cheie Management API, cu permisiunea AddFileToCollection. Beneficiul este imediat pentru echipe: serviciul care interoghează baza din aplicația dumneavoastră publică primește cheia standard și nu poate distruge nimic; doar pipeline-ul dumneavoastră de ingestie deține cheia de management.
Crearea primei dumneavoastră colecții
Crearea se reduce la un singur apel cu un nume:
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"}'
Răspunsul returnează identificatorul pe care trebuie să îl păstrați:
{
"collection_id": "col_xyz789",
"collection_name": "technical-docs",
"created_at": "2026-04-01T10:00:00Z"
}
Alegeți acest nume cu grijă: acesta va apărea în toate listele dumneavoastră și, peste șase luni, va fi singurul indiciu care vă va permite să distingeți două baze vecine. technical-docs îndeplinește acest rol; test2 nu o va face. Adoptați o convenție încă de la prima colecție, deoarece redenumirea unei baze deja referențiate de trei aplicații costă mai mult decât denumirea ei corectă de la început.
Cele cinci operațiuni disponibile
Management API expune un set complet de operațiuni CRUD pentru colecții:
| Operațiune | Metodă | Endpoint |
|---|---|---|
| Creare | POST | /v1/collections |
| Listare | GET | /v1/collections |
| Detalii | GET | /v1/collections/{collection_id} |
| Actualizare | PUT | /v1/collections/{collection_id} |
| Ștergere | DELETE | /v1/collections/{collection_id} |
Listarea colecțiilor dumneavoastră se face fără parametri și oferă o imagine de ansamblu utilă înainte de orice operațiune de mentenanță:
curl https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Ștergerea urmează aceeași logică, desemnând identificatorul obținut la creare:
curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Un aspect ar trebui să vă liniștească atunci când executați această comandă: ștergerea unei colecții elimină indexarea, nu fișierele. Documentele dumneavoastră rămân accesibile prin Files API și pot fi reindexate în altă parte. Pierdeți structura de căutare, nu materia primă – ceea ce face reconstrucția unei baze organizate necorespunzător mult mai puțin riscantă decât pare.
Puncte cheie
- Colecțiile grupează fișierele dumneavoastră în baze de cunoștințe indexate pentru RAG
- Gestionarea se face prin Management API (
management-api.x.ai), nu prin API-ul standard - Este necesară o cheie Management API cu permisiunea
AddFileToCollection - Limitele sunt de 100.000 de fișiere și 100 GB per cont
- Cele cinci operațiuni CRUD acoperă crearea, citirea, actualizarea și ștergerea