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

Kokoelmien käyttöoikeudet ja rajat

Oppitunti 8 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tietokantojen erityisriskit
  2. Kaksi avainta, kaksi roolia
  3. AddFileToCollection-oikeus
  4. Kiintiöt ja niiden kustannukset
  5. Eristä, kierrätä, valvo
  6. Yksi tiedosto, useita kokoelmia
  7. Keskeiset asiat

Tietokantojen erityisriskit

Yrityksen tietokanta ei ole koskaan merkityksetön: se sisältää sisäisiä muistiinpanoja, luottamuksellisia raportteja ja neuvotteluvaiheessa olevia sopimuksia. Jos käyttöoikeuksien hallinta pettää, et vuoda vain yhtä tiedostoa – paljastat koko tietokannan yhdessä sen hakukoneen kanssa, jolla arvokas tieto löytyy. xAI:n käyttöoikeusjärjestelmä vähentää tätä riskiä erottamalla oikeudet toisistaan, kun taas kiintiöt säätelevät käyttöä ja laskutusta.

Kaksi avainta, kaksi roolia

xAI-ekosysteemi luottaa kahteen tunnistetietoon eri laajuisia toimintoja varten:

AvainKäyttöLaajuus
XAI_API_KEYTiedostojen lataus ja hakuLuku- ja käyttötoiminnot
XAI_MANAGEMENT_API_KEYKokoelmien hallintaHallintatoiminnot

Tämä erottelu toteuttaa konkreettisesti vähimmäisoikeuksien periaatetta. Kehittäjä, joka yhdistää tukichatbotin tietokantaasi, tarvitsee oikeuden vain kysellä kokoelmaa, ei koskaan poistaa sitä. Antamalla hänelle vain vakioavaimen varmistat, että skriptivirhe tai kompromissoitunut avain ei tuhoa kuukausien aikana rakennettua indeksiä.

AddFileToCollection-oikeus

Management API -avain ei ole oletuksena kaikkivaltias. Sen oikeudet ovat nimenomaisia, ja kokoelmien kannalta kriittisin niistä on AddFileToCollection. Ilman tätä oikeutta voit luoda ja luetella kokoelmia, mutta et voi lisätä yhtäkään asiakirjaa. Tilanne on hämmentävä, sillä kaikki näyttää toimivan aina tiedonsyöttöön saakka. Oikean avaimen luominen vaatii neljä vaihetta:

  1. Kirjaudu xAI-konsoliin
  2. Luo uusi Management API -avain
  3. Ota käyttöön AddFileToCollection-oikeus
  4. Tallenna avain turvallisesti: ympäristömuuttujaan tai avaintenhallintajärjestelmään

Kun oikeus puuttuu, API on selkeä ja palauttaa virhekoodin 403:

{
  "error": {
    "message": "Insufficient permissions",
    "type": "permission_error",
    "code": 403
  }
}

Ensimmäinen toimenpiteesi pitäisi olla avaimen oikeuksien tarkistaminen konsolista sen sijaan, että epäilisit pyyntöä, jonka syntaksilla ei ole mitään tekemistä hylkäyksen kanssa.

Kiintiöt ja niiden kustannukset

Tilin tallennustilaa rajoittaa kolme kattoa: yhteensä 100 000 tiedostoa, 100 Gt kumulatiivista kapasiteettia ja 100 Mt yksittäistä tiedostoa kohden kokoelmissa. Tämä on yli kaksinkertainen määrä verrattuna Files API:n yksinään sallimaan 48 Mt:n rajaan, joten voit sisällyttää asiakirjoja, joita et voisi lähettää suorina liitteinä.

Laskutuksen puolella kaksi riviä nousevat esiin: Kokoelmien haku (Collections Search) maksaa 2,50 dollaria 1 000 hakukertaa kohden, kun taas tiedostoliitteet (File Attachments) maksavat 10 dollaria 1 000 kertaa kohden. Ero on merkittävä ja vaikuttaa arkkitehtuurivalintoihin. Suuressa käytössä indeksoidun kokoelman kysely on huomattavasti edullisempaa kuin saman asiakirjan liittäminen uudelleen jokaisen kysymyksen yhteydessä.

Jos tarpeesi ylittävät nämä kiintiöt, xAI:n tuki voi myöntää korotuksen. Valmistele pyyntösi konkreettisilla luvuilla – tavoiteltu tiedostomäärä, kokonaistilavuus ja odotettu hakutiheys – äläkä epämääräisillä arvioilla. Tämä nopeuttaa pyynnön käsittelyä.

Eristä, kierrätä, valvo

Ensimmäinen käytäntö koskee avaimia. Määritä eri avaimet jokaiselle ympäristölle, jotta kehitysskripti ei voi koskaan koskea tuotantokantaan. Älä koskaan anna Management-avainta palvelulle, jonka ainoa tarve on haku. Kierrätä nämä avaimet säännöllisesti, erityisesti sen jälkeen, kun salaisuuksiin pääsyä ollut yhteistyökumppani on lähtenyt.

Toinen käytäntö koskee rakennetta. Yhden kokoelman sijaan, jossa julkinen dokumentaatio ja sopimukset coexistoivat, erota tietokantasi luottamuksellisuustason mukaan: “julkinen” kanta avoimeen dokumentaatioon, “sisäinen” kanta yrityksen asiakirjoille ja “luottamuksellinen” kanta arkaluonteiselle datalle. Jokainen palvelu saa tällöin vain tarvitsemansa pääsyn, ja kysymykseen “voiko tämä chatbot siteerata sopimusta?” vastataan jo suunnitteluvaiheessa.

Kolmas on valvonta. Tarkista kulutuksesi xAI-konsolista, aseta hälytys odottamattomalle hakumäärien nousulle – mikä on usein ensimmäinen merkki silmukasta, joka on karannut käsistä – ja pidä kirjallista rekisteriä siitä, mitkä palvelut käyttävät mitkäkin kokoelmat.

Yksi tiedosto, useita kokoelmia

Tämä eristäminen ei vaadi asiakirjojesi monistamista, sillä sama tiedosto voi kuulua useisiin kokoelmiin. Tekninen raportti voi siis esiintyä kokoelmassa “product-documentation” tekniselle tiimille, kokoelmassa “quarterly-reports” johdolle ja kokoelmassa “support-base” asiakaspalvelulle. Se tallennetaan vain kerran, lasketaan kiintiöihin vain kerran ja pysyy haettavana kaikissa kolmessa kontekstissa – teemakohtaisia näkymiä kohdeyleisölle ilman eroavia kopioita.

Keskeiset asiat

  • Kaksi erillistä API-avainta: vakio käyttöön, Management hallintoon
  • AddFileToCollection-oikeus on välttämätön kokoelmien täyttämiseen
  • Rajat ovat 100 000 tiedostoa, 100 Gt ja 100 Mt tiedostoa kohden
  • Erota kokoelmasi luottamuksellisuustason mukaan
  • Tiedosto voi kuulua useisiin kokoelmiin ilman monistamista