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

Lisää dokumentteja kokoelmaan

Oppitunti 6 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miksi lisääminen tapahtuu kahdessa vaiheessa
  2. Vaihe 1: Lataa tiedosto
  3. Vaihe 2: Liitä kokoelmaan
  4. Odota indeksoinnin valmistumista
  5. Poista dokumentti menettämättä sitä
  6. Täytä kokoelma massasisällöllä
  7. Kaksi avainta, kaksi laajuutta
  8. Keskeiset asiat

Päivitetty 2. marraskuuta 2026. Tämä oppitunti perustuu versioon xai-sdk 1.21.0 ja xAI:n dokumentaatioon: await-kutsut vaativat asynkronisen AsyncClient-asiakkaan, indeksointitilaa verrataan collections_pb2.DOCUMENT_STATUS_PROCESSED-vakioon (ei merkkijonoon), ja massasisältö käyttää upload_document-metodia, joka yhdistää molemmat vaiheet yhdeksi kutsuksi. Lähteet: Collections via the API · xai-sdk-python.

Miksi lisääminen tapahtuu kahdessa vaiheessa

Saatat odottaa voivasi pudottaa PDF-tiedoston suoraan kokoelmaan kuin vetäisit tiedoston kansioon. xAI:n API ei toimi näin: dokumentti kulkee ensin Files API:n läpi, joka tallentaa sen ja määrittää sille file_id:n, ja sen jälkeen Management API:n läpi, joka linkittää tämän tunnisteen kokoelmaan. Kaksi kutsua, kaksi avainta, kaksi vaihetta.

Tällä erottelulla on suora ja hyödyllinen seuraus: tiedosto on olemassa tallennustasolla vain kerran, mutta se voidaan linkittää niin moneen kokoelmaan kuin tarvitaan. Sama tekninen raportti voi syöttää sekä tuotetiimin tietokantaa että tukitiimin tietokantaa ilman, että sitä ladataan kahdesti, ilman että kiintiötä kulutetaan kahdesti ja ilman riskiä kahden kopion eroavaisuuksista.

Vaihe 1: Lataa tiedosto

Tässä ei ole mitään uutta; tämä on päätepiste, jonka olet hallinnut ensimmäisestä oppitunnista lähtien:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "[email protected]" \
  -F "purpose=assistants"

Hae file_id vastauksesta: se on avain seuraavaan vaiheeseen.

Vaihe 2: Liitä kokoelmaan

Lisääminen tapahtuu POST-pyyntönä URL-osoitteeseen, joka yhdistää kaksi tunnistetta: kokoelman ID:n ja tiedoston ID:n. Pyyntö ei vaadi sisältöä (body):

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

Kun tämä kutsu on hyväksytty, xAI aloittaa sisällön indeksoinnin. Dokumentti käy läpi useita käsittelytiloja, ennen kuin se on todella käytettävissä hakuun.

Odota indeksoinnin valmistumista

Tämä on yleinen sudenkuoppa ensimmäisessä putkistossa: lisäyspyyntö palauttaa onnistumisen, suoritat heti perään haun, ja kokoelma vastaa, ettei se löydä mitään. Dokumentti on olemassa, mutta sitä ei ole vielä indeksoitu. Tilana, jota tulee odottaa, on DOCUMENT_STATUS_PROCESSED, ja SDK mahdollistaa sen kyselyn oikein:

import asyncio
import os

from xai_sdk import AsyncClient
from xai_sdk.proto import collections_pb2

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)


async def wait_for_indexing(file_id, collection_id):
    doc = await client.collections.get_document(file_id, collection_id)
    while doc.status != collections_pb2.DOCUMENT_STATUS_PROCESSED:
        if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
            raise RuntimeError(f"Indexing failed: {doc.error_message}")
        await asyncio.sleep(3)
        doc = await client.collections.get_document(file_id, collection_id)
    print("Document indexed and ready for search")


asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))

Viive riippuu suoraan koosta: muutaman sivun PDF indeksoituu muutamassa sekunnissa, kun taas 100 Mt:n dokumentti voi viedä useita minuutteja. Yöaikaiseen massasisältöön tämä silmukka kolmen sekunnin tauolla riittää; käyttöliittymässä, jossa käyttäjä lataa tiedoston ja odottaa, tarjoa visuaalista palautetta jäätymisen sijaan.

Poista dokumentti menettämättä sitä

Tiedoston irrottaminen kokoelmasta on erillinen toiminto sen poistamisesta:

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

Tiedosto katoaa tämän kokoelman hakemistosta, mutta se pysyy saatavilla Files API:n kautta ja se voidaan linkittää muualle. Tämä on juuri se, mitä sinun tulee tehdä, kun tuotesivu vanhentuu tuen kannalta, mutta sen arkistoarvo säilytetään: poistat sen operatiivisesta tietokannasta tuhoamatta itse dokumenttia.

Täytä kokoelma massasisällöllä

Kun alustat tietokantaa koko kansiosta, kirjoita silmukka kerran; se palvelee sinua pitkään:

import asyncio
import os
from pathlib import Path

from xai_sdk import AsyncClient

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)

files = [
    "docs/guide-installation.pdf",
    "docs/reference-api.pdf",
    "docs/faq.md",
    "docs/changelog.txt",
]


async def populate(collection_id):
    for file_path in map(Path, files):
        # Vaiheet 1 ja 2 yhdessä kutsussa: lataa Files API:n kautta, sitten liitä
        await client.collections.upload_document(
            collection_id=collection_id,
            name=file_path.name,
            data=file_path.read_bytes(),
        )
        print(f"Added: {file_path}")


asyncio.run(populate("col_xyz789"))

Huomaa listan sekamuotoisuus: PDF, Markdown ja pelkkä teksti coexistoivat ongelmitta samassa kokoelmassa, mikä säästää sinua lähteiden standardoinnilta ennen sisällön lisäämistä.

Kaksi avainta, kaksi laajuutta

Tämä prosessi käyttää kahta käyttöoikeustunnistetta, joita ei tule sekoittaa keskenään: tavallinen API-avain (XAI_API_KEY) vaiheen 1 latausta varten ja Management-avain (XAI_MANAGEMENT_API_KEY) vaiheen 2 liittämistä varten. SDK vastaanottaa molemmat asiakasta luotaessa, ja upload_document käyttää niitä peräkkäin. Varmista, että jälkimmäisellä on AddFileToCollection-oikeus: ilman sitä latauksesi onnistuu, mutta lisäys epäonnistuu 403-virheellä, ja keräät tiedostoja, jotka on tallennettu oikein mutta eivät kuulu mihinkään kokoelmaan.

Keskeiset asiat

  • Kokoelmaan lisääminen tapahtuu kahdessa vaiheessa: lataus ja sen jälkeen lisäys
  • Tiedosto voi kuulua useaan kokoelmaan samanaikaisesti
  • Dokumentin on saavutettava tila DOCUMENT_STATUS_PROCESSED, ennen kuin se on haettavissa
  • Dokumentin poistaminen kokoelmasta ei poista taustalla olevaa tiedostoa
  • Tarvitaan kaksi erillistä API-avainta: tavallinen lataukseen ja Management kokoelmaan