Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Dodajanje dokumentov v zbirko

Lekcija 6 od 16 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Zakaj dodajanje poteka v dveh korakih
  2. 1. korak: Naloži datoteko
  3. 2. korak: Pripni zbirki
  4. Počakaj na zaključek indeksiranja
  5. Odstrani dokument, ne da bi ga izgubil
  6. Množično polnjenje zbirke
  7. Dva ključa, dva obsega
  8. Ključne ugotovitve

Posodobljeno 2. novembra 2026. Ta lekcija odraža različico xai-sdk 1.21.0 in dokumentacijo xAI: klici await zahtevajo asinhroni AsyncClient, stanje indeksiranja se primerja s konstanto collections_pb2.DOCUMENT_STATUS_PROCESSED (ne z nizom), množično uvažanje pa uporablja upload_document, ki združuje oba koraka v en klic. Viri: Zbirke prek API-ja · xai-sdk-python.

Zakaj dodajanje poteka v dveh korakih

Morda pričakuješ, da boš PDF preprosto spustil v zbirko, kot da bi datoteko povlekel v mapo. API xAI ne deluje tako: dokument najprej potuje prek API-ja za datoteke (Files API), ki ga shrani in dodeli file_id, nato pa prek upravljalnega API-ja (Management API), ki ta identifikator poveže z zbirko. Dva klica, dva ključa, dva koraka.

Ta ločitev ima neposredno in koristno posledico: datoteka obstaja na strani shrambe le enkrat, lahko pa je povezana s poljubnim številom zbirk. Isto tehnično poročilo lahko napaja bazo podatkov produktnega tima in bazo podpore, ne da bi ga bilo treba dvakrat naložiti, ne da bi dvakrat porabilo kvoto in brez tveganja neskladja med dvema kopijama.

1. korak: Naloži datoteko

Tukaj ni nič novega, to je končna točka, ki si jo obvladal že od prve lekcije:

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

Iz odgovora pridobi file_id: to je ključ za naslednji korak.

2. korak: Pripni zbirki

Dodajanje ima obliko zahteve POST na URL, ki združuje oba identifikatorja, ID zbirke in ID datoteke, ter ne zahteva telesa zahteve:

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

Ko je ta klic sprejet, xAI začne indeksirati vsebino. Dokument nato preide skozi več stanj obdelave, preden je dejansko na voljo za iskanje.

Počakaj na zaključek indeksiranja

To je pogosta past v prvem poteku dela: zahteva za dodajanje vrne uspeh, takoj zatem sledi iskanje, zbirka pa odgovori, da ni našla ničesar. Dokument obstaja, vendar še ni indeksiran. Stanje, na katerega moraš čakati, je DOCUMENT_STATUS_PROCESSED, SDK pa ti omogoča pravilno preverjanje:

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

Zamuda je neposredno odvisna od velikosti: PDF z nekaj stranmi se indeksira v nekaj sekundah, medtem ko lahko dokument velik 100 MB traja več minut. Za čeznočno uvažanje je ta zanka s trisekundnim premorom zadostna; v vmesniku, kjer uporabnik naloži datoteko in čaka, zagotovi vizualno povratno informacijo namesto zamrznjenega zaslona.

Odstrani dokument, ne da bi ga izgubil

Ločitev datoteke od zbirke je ločena operacija od njenega brisanja:

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

Datoteka izgine iz indeksa te zbirke, vendar ostane na voljo prek API-ja za datoteke in jo je mogoče povezati drugje. Točno to moraš storiti, ko list izdelka za podporo postane zastarel, vendar ohrani svojo arhivsko vrednost: odstraniš ga iz operativne baze podatkov, ne da bi uničil dokument.

Množično polnjenje zbirke

Ko inicializiraš bazo podatkov iz cele mape, zanko napiši enkrat; dolgo ti bo dobro služila:

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):
        # Koraka 1 in 2 v enem klicu: naloži prek Files API, nato pripni
        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"))

Opazi mešanico formatov na seznamu – PDF, Markdown in navadno besedilo sobivajo brez težav v isti zbirki, kar te reši potrebe po standardizaciji virov pred uvozom.

Dva ključa, dva obsega

Ta postopek uporablja dva dostopna identifikatorja, ki ju ne smeš zamenjati: standardni ključ API (XAI_API_KEY) za nalaganje v 1. koraku in upravljalni ključ (XAI_MANAGEMENT_API_KEY) za pripenjanje v 2. koraku. SDK prejme oba ob ustvarjanju odjemalca, upload_document pa ju uporabi enega za drugim. Preveri, ali ima slednji dovoljenje AddFileToCollection: brez njega bo tvoje nalaganje uspelo, dodajanje pa bo spodletelo s napako 403, ti pa boš kopičil pravilno shranjene datoteke, ki jih ni v nobeni zbirki.

Ključne ugotovitve

  • Dodajanje v zbirko poteka v dveh korakih: najprej naloži, nato dodaj
  • Datoteka lahko hkrati pripada več zbirkam
  • Dokument mora doseči stanje DOCUMENT_STATUS_PROCESSED, preden je mogoče iskati po njem
  • Odstranitev dokumenta iz zbirke ne izbriše osnovne datoteke
  • Potrebna sta dva različna ključa API: standardni za nalaganje in upravljalni za zbirko