Dodajanje dokumentov v zbirko
Na tej strani
Posodobljeno 2. novembra 2026. Ta lekcija odraža različico
xai-sdk1.21.0 in dokumentacijo xAI: kliciawaitzahtevajo asinhroniAsyncClient, stanje indeksiranja se primerja s konstantocollections_pb2.DOCUMENT_STATUS_PROCESSED(ne z nizom), množično uvažanje pa uporabljaupload_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