Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Luontia ja hallintaa kokoelmille

Oppitunti 5 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Yksittäisistä tiedostoista tietämyskantaan
  2. Erillinen API ja sen syy
  3. Luo ensimmäinen kokoelmasi
  4. Viisi käytettävissä olevaa toimenpidettä
  5. Keskeiset asiat

Yksittäisistä tiedostoista tietämyskantaan

Tähän asti jokainen asiakirja on ollut erillään: latasit sen, viittasit siihen, ja sitä varten rakennettu indeksi katosi kyselyn mukana. Kokoelmat muuttavat mittakaavaa: ne ryhmittelevät tiedostosi jäsennellyiksi tietämyskannoiksi, jotka indeksoidaan kerran ja joita voi kysyä rajattomasti. Tämä on RAG:n (Retrieval-Augmented Generation) perusta Grokin kanssa, ja ero näkyy heti, kun tukitiimi hakee tietoa kahdestasadasta tuote-esitteestä yhden PDF-tiedoston sijaan.

Ajattele kokoelmaa älykkäänä kansiona. Talletat siihen dokumentteja, xAI indeksoi ne semanttista hakua varten, ja Grok etsii tästä kannasta vastatakseen tarkasti poimimalla kolme hyödyllistä kohtaa tuhansien joukosta.

100k
Files per account
100 GB
Total capacity
CRUD
Full operations
$2.50
Per 1,000 searches

Erillinen API ja sen syy

Et hallinnoi kokoelmia samalla API:lla, jota olet käyttänyt kurssin alusta lähtien. Ne kuuluvat Management API:n piiriin, joka toimii osoitteessa management-api.x.ai perus-URLilla:

https://management-api.x.ai/v1

Tämä erottelu ei ole arkkitehtoninen oikku. Kokoelman luominen, muokkaaminen tai poistaminen ovat hallinnollisia toimenpiteitä, joilla on laajat seuraukset, joten xAI vaatii niihin erillisen avaimen: Management API Key, jossa on AddFileToCollection-oikeus. Hyöty tiimeille on välitön: palvelu, joka hakee tietoa kannasta julkisesta sovelluksestasi, saa käyttöönsä vakioavaimen eikä voi tuhota mitään; vain ingestio-pipelineesi hallitsee management-avainta.

Luo ensimmäinen kokoelmasi

Luominen tiivistyy yhteen kutsuun nimen avulla:

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"}'

Vastaus palauttaa tallennettavan tunnisteen:

{
  "collection_id": "col_xyz789",
  "collection_name": "technical-docs",
  "created_at": "2026-04-01T10:00:00Z"
}

Valitse tämä nimi huolella: se näkyy kaikissa listoissasi, ja kuuden kuukauden kuluttua se on ainoa vihje, jonka avulla erotat kaksi vierekkäistä kantaa. technical-docs toimii tässä roolissa; test2 ei. Omaksu nimikäytäntö jo ensimmäisestä kokoelmasta lähtien, sillä kolmen sovelluksen jo viittaaman kannan nimeäminen uudelleen maksaa enemmän kuin sen nimeäminen oikein alusta alkaen.

Viisi käytettävissä olevaa toimenpidettä

Management API tarjoaa täyden CRUD-toiminnallisuuden kokoelmille:

ToimenpideMetodiPäätepiste
LuoPOST/v1/collections
ListaaGET/v1/collections
TiedotGET/v1/collections/{collection_id}
PäivitäPUT/v1/collections/{collection_id}
PoistaDELETE/v1/collections/{collection_id}

Kokoelmiesi listaaminen tapahtuu ilman parametreja ja antaa hyödyllisen yleiskatsauksen ennen ylläpitotoimenpiteitä:

curl https://management-api.x.ai/v1/collections \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Poistaminen noudattaa samaa logiikkaa viittaamalla luonnin yhteydessä saatuun tunnisteeseen:

curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Yksi asia pitäisi rauhoittaa sinua tätä komentoa suorittaessasi: kokoelman poistaminen poistaa indeksoinnin, ei tiedostoja. Dokumenttisi pysyvät saatavilla Files API:n kautta ja ne voidaan indeksoidä uudelleen muualle. Menetät hakurakenteen, et raaka-ainetta – mikä tekee huonosti järjestetyn kannan uudelleenrakentamisesta paljon vähemmän riskialtista kuin miltä se ensi silmäyksellä vaikuttaa.

Keskeiset asiat

  • Kokoelmat ryhmittelevät tiedostosi indeksoiduiksi tietämyskannoiksi RAG-käyttöä varten
  • Hallinta tapahtuu Management API:n (management-api.x.ai) kautta, ei vakio-API:n
  • Vaaditaan Management API Key, jossa on AddFileToCollection-oikeus
  • Rajat ovat 100 000 tiedostoa ja 100 GB tiliä kohden
  • Viisi CRUD-toimenpidettä kattavat luonnin, lukemisen, päivittämisen ja poistamisen