Kurti ir valdyti kolekcijas
Šiame puslapyje
Nuo pavienių failų iki žinių bazės
Iki šiol kiekvienas dokumentas egzistavo atskirai: jį įkeldavai, naudodavai užklausai, o tam tikslui sukurtas indeksas išnykdavo kartu su užklausa. Kolekcijos keičia mastelį: jos sugrupuoja tavo failus į struktūrizuotas žinių bazes, kurios indeksuojamos vieną kartą ir gali būti užklausiamos neribotą laiką. Tai RAG (Retrieval-Augmented Generation) su Grok pagrindas, o skirtumas tampa akivaizdus, kai pagalbos komanda užuot klaususi vieno PDF failo, užklausia du šimtus produktų lapų.
Įsivaizduok kolekciją kaip išmanųjį aplanką. Į jį dedate dokumentus, xAI juos indeksuoja semantinei paieškai, o Grok ieško šioje bazėje, kad pateiktų tikslų atsakymą, iš tūkstančių ištraukdamas tris naudingiausius fragmentus.
Atskiras API ir kodėl taip yra
Kolekcijų nevaldai per API, kurį naudojai nuo pat kurso pradžios. Jos priklauso Valdymo API (Management API), kuris talpinamas serveryje management-api.x.ai, o jo bazinis URL yra:
https://management-api.x.ai/v1
Šis atskyrimas nėra architektūrinė užgaida. Kolekcijos kūrimas, keitimas ar šalinimas yra administracinės operacijos, turinčios didelių pasekmių, todėl xAI joms reikalauja atskiro rakto: Valdymo API rakto (Management API Key) su leidimu AddFileToCollection. Komandoms nauda akivaizdi iškart: tarnyba, kuri tavo viešojoje programoje užklausia bazę, gauna standartinį raktą ir negali nieko sunaikinti; valdymo raktą turi tik tavo duomenų įkėlimo grandinė.
Sukurk savo pirmąją kolekciją
Kūrimas sumažėja iki vieno užklausos su pavadinimu:
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"}'
Atsakyme gauni identifikatorių, kurį privalai išsaugoti:
{
"collection_id": "col_xyz789",
"collection_name": "technical-docs",
"created_at": "2026-04-01T10:00:00Z"
}
Šį pavadinimą rinkis atsargiai: jis bus matomas visuose sąrašuose ir po šešių mėnesių bus vienintelė užuomina, leidžianti atskirti dvi gretimas bazes. technical-docs šį vaidmenį atlieka puikiai, o test2 – ne. Priimk susitarimą jau nuo pirmosios kolekcijos, nes pervadinti bazę, kurią jau naudoja trys programos, kainuoja daugiau nei tinkamai ją pavadinti iš pradžių.
Penkios galimos operacijos
Valdymo API pateikia visą CRUD operacijų rinkinį kolekcijoms:
| Operacija | Metodas | Galutinio taško adresas (Endpoint) |
|---|---|---|
| Kurti | POST | /v1/collections |
| Sąrašas | GET | /v1/collections |
| Detalės | GET | /v1/collections/{collection_id} |
| Atnaujinti | PUT | /v1/collections/{collection_id} |
| Ištrinti | DELETE | /v1/collections/{collection_id} |
Kolekcijų sąrašo gavimas vyksta be parametrų ir suteikia naudingą apžvalgą prieš atliekant bet kokius priežiūros darbus:
curl https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Trinimas vyksta pagal tą pačią logiką, nurodant kūrimo metu gautą identifikatorių:
curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Vienas dalykas turėtų tave nuraminti vykdant šią komandą: ištrinus kolekciją, pašalinamas tik indeksavimas, bet ne patys failai. Tavo dokumentai lieka pasiekiami per Failų API ir gali būti perindeksuoti kitur. Prarandi paieškos struktūrą, bet ne žaliavą – tai reiškia, kad netvarkingai sutvarkytos bazės atkūrimas yra kur kas mažiau rizikingas, nei gali atrodyti.
Svarbiausi punktai
- Kolekcijos sugrupuoja tavo failus į indeksuotas žinių bazes, skirtas RAG
- Valdymas vykdomas per Valdymo API (
management-api.x.ai), o ne per standartinį API - Būtinas Valdymo API raktas su leidimu
AddFileToCollection - Limitai: 100 000 failų ir 100 GB vienai paskyrai
- Penkios CRUD operacijos apima kūrimą, skaitymą, atnaujinimą ir šalinimą