Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Dokumentide lisamine kogumisse

Õppetund 6 / 16 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Miks lisamine toimub kahes etapis
  2. 1. samm: Faili üleslaadimine
  3. 2. samm: Kogumiga sidumine
  4. Oota indekseerimise lõppemist
  5. Dokumendi eemaldamine ilma seda kaotamata
  6. Kogumi täitmine mahuliselt
  7. Kaks võtit, kaks ulatust
  8. Peamised punktid

Uuendatud 2. novembril 2026. See õppetund põhineb xai-sdk versioonil 1.21.0 ja xAI dokumentatsioonil: await päringud nõuavad asünkroonset AsyncClient klienti, indekseerimise olekut võrreldakse konstandiga collections_pb2.DOCUMENT_STATUS_PROCESSED (mitte stringina) ja mahuline import kasutab meetodit upload_document, mis ühendab mõlemad sammud üheks väljakutseks. Allikad: Kogumid API kaudu · xai-sdk-python.

Miks lisamine toimub kahes etapis

Võid oodata, et saad PDF-faili otse kogumisse lohistada, nagu faili kausta tõmmates. xAI API aga nii ei tööta: dokument läbib esmalt Files API, mis salvestab faili ja omistab sellele file_id, ning seejärel Management API, mis seob selle identifikaatori kogumiga. Kaks väljakutset, kaks võtit, kaks sammu.

Sellel eraldatusel on otsene ja kasulik tagajärg: fail eksisteerib salvestuspoolel vaid üks kord, kuid seda saab siduda nii paljude kogumitega kui vaja. Sama tehniline aruanne võib toita nii tootemeeskonna andmebaasi kui ka tugimeeskonna oma, ilma et seda peaks kaks korda üles laadima, ilma kvoote topelt tarbimata ja ilma riskita, et kahe koopia vahel tekivad lahknevused.

1. samm: Faili üleslaadimine

Siin pole midagi uut, see on lõpp-punkt, mille oled esimesest õppetunnist saadik selgeks saanud:

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

Hangi vastusest file_id: see on võti järgmiseks sammuks.

2. samm: Kogumiga sidumine

Lisamine toimub POST-päringuna URL-ile, mis ühendab kaks identifikaatorit – kogumi ID ja faili ID – ning ei nõua päringu keha:

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

Kui see väljakutse on vastu võetud, alustab xAI sisu indekseerimist. Dokument läbib seejärel mitu töötlemise olekut, enne kui see on otsinguks tegelikult kättesaadav.

Oota indekseerimise lõppemist

See on esimeses töövoos levinud lõks: lisamise päring tagastab edu, järgned kohe otsinguga ja kogum vastab, et midagi ei leitud. Dokument on olemas, kuid pole veel indekseeritud. Olek, mida oodata, on DOCUMENT_STATUS_PROCESSED, ja SDK võimaldab seda korrektselt pollida:

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"))

Viivitus sõltub otseselt suurusest: mõneleheküljeline PDF indekseeritakse mõne sekundiga, samas kui 100 MB dokument võib võtta mitu minutit. Öiseks impordiks piisab sellest tsüklist kolmesekundilise pausiga; liideses, kus kasutaja laeb faili üles ja ootab, paku visuaalset tagasisidet, mitte külmutatud ekraani.

Dokumendi eemaldamine ilma seda kaotamata

Faili kogumist lahtiühendamine on eraldiseisev toiming selle kustutamisest:

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

Fail kaob selle kogumi indeksist, kuid jääb Files API kaudu kättesaadavaks ja seda saab mujale siduda. See on täpselt see, mida peaksid tegema, kui tooteleht muutub toe jaoks iganenuks, säilitades samal ajal selle arhiiviväärtuse: eemaldad selle operatiivsest andmebaasist, hävitamata dokumenti ennast.

Kogumi täitmine mahuliselt

Kui algatad andmebaasi tervest kaustast, kirjuta tsükkel üks kord; see teenib sind pikka aega hästi:

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):
        # Sammud 1 ja 2 ühes väljakutses: laadi üles Files API kaudu, seejärel lisa
        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"))

Pane tähele vormingute segu loendis – PDF, Markdown ja lihttekst eksisteerivad samas kogumis probleemideta kõrvuti, mis säästab sind allikate standardiseerimisest enne importi.

Kaks võtit, kaks ulatust

See protsess kasutab kahte juurdepääsu identifikaatorit, mida ei tohi omavahel segi ajada: standardne API võti (XAI_API_KEY) 1. sammu üleslaadimiseks ja Management võti (XAI_MANAGEMENT_API_KEY) 2. sammu sidumiseks. SDK saab mõlemad kliendi loomisel kätte ja upload_document kasutab neid üksteise järel. Veendu, et viimasel on õigus AddFileToCollection: ilma selleta õnnestub üleslaadimine, lisamine ebaõnnestub veakoodiga 403 ja sul kuhjuvad failid, mis on korrektselt salvestatud, kuid puuduvad igast kogumist.

Peamised punktid

  • Kogumisse lisamine toimub kahes etapis: esmalt üleslaadimine, seejärel lisamine
  • Fail võib kuuluda samaaegselt mitmesse kogumisse
  • Dokument peab enne otsitavaks muutumist jõudma olekusse DOCUMENT_STATUS_PROCESSED
  • Dokumendi eemaldamine kogumist ei kustuta aluseks olevat faili
  • Vajalikud on kaks erinevat API võtit: standardne üleslaadimiseks ja Management kogumi jaoks