Dodavanje dokumenata u kolekciju
Na ovoj stranici
Ažurirano 2. studenoga 2026. Ova lekcija odražava verziju
xai-sdk1.21.0 i dokumentaciju xAI-ja: poziviawaitzahtijevaju asinkroniAsyncClient, status indeksiranja uspoređuje se s konstantomcollections_pb2.DOCUMENT_STATUS_PROCESSED(a ne s nizom znakova), a masovno učitavanje koristiupload_document, koji objedinjuje oba koraka u jedan poziv. Izvori: Kolekcije putem API-ja · xai-sdk-python.
Zašto se dodavanje odvija u dva koraka
Možda očekuješ da ćeš moći jednostavno ubaciti PDF izravno u kolekciju, kao da povlačiš datoteku u mapu. xAI API ne funkcionira tako: dokument prvo prolazi kroz Files API, koji ga pohranjuje i dodjeljuje mu file_id, a zatim kroz Management API, koji taj identifikator povezuje s kolekcijom. Dva poziva, dva ključa, dva koraka.
Ova odvojenost ima izravnu i korisnu posljedicu: datoteka postoji samo jednom na strani pohrane, ali se može povezati s onoliko kolekcija koliko je potrebno. Isto tehničko izvješće može napajati bazu podataka tima za proizvode i tima za podršku, a da se ne učitava dvaput, ne troši kvotu dvaput i ne riskira razilaženje između dviju kopija.
Korak 1: Učitavanje datoteke
Ovdje nema ničeg novog, ovo je krajnja točka koju si savladao još u prvoj lekciji:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Dohvati file_id iz odgovora: to je ključ za sljedeći korak.
Korak 2: Pripajanje kolekciji
Dodavanje ima oblik POST zahtjeva na URL koji kombinira dva identifikatora, ID kolekcije i ID datoteke, te ne zahtijeva tijelo zahtjeva:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Kada se ovaj poziv prihvati, xAI započinje indeksiranje sadržaja. Dokument zatim prolazi kroz nekoliko stanja obrade prije nego što postane dostupan za pretraživanje.
Pričekaj završetak indeksiranja
Ovo je česta zamka u prvom pipelineu: zahtjev za dodavanje vraća uspjeh, ti odmah nastaviš s pretraživanjem, a kolekcija odgovori da ništa ne pronalazi. Dokument postoji, ali još nije indeksiran. Status kojeg trebaš čekati je DOCUMENT_STATUS_PROCESSED, a SDK ti omogućuje ispravno ispitivanje (polling):
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"))
Kašnjenje izravno ovisi o veličini: PDF od nekoliko stranica indeksira se u nekoliko sekundi, dok dokument od 100 MB može potrajati nekoliko minuta. Za noćno učitavanje ova petlja s pauzom od tri sekunde dovoljna je; u sučelju gdje korisnik učitava datoteku i čeka, osiguraj vizualnu povratnu informaciju umjesto smrznutog zaslona.
Uklanjanje dokumenta bez gubitka
Odspajanje datoteke od kolekcije zasebna je operacija od njezinog brisanja:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Datoteka nestaje iz indeksa ove kolekcije, ali ostaje dostupna putem Files API-ja i može se povezati drugdje. Točno je to ono što trebaš učiniti kada list s podacima o proizvodu postane zastario za podršku, a zadrži svoju arhivsku vrijednost: uklanjaš ga iz operativne baze podataka bez uništavanja samog dokumenta.
Masovno popunjavanje kolekcije
Kada inicijaliziraš bazu podataka iz cijele mape, napiši petlju jednom; dobro će ti služiti dugo vremena:
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):
# Koraci 1 i 2 u jednom pozivu: učitavanje putem Files API-ja, zatim pripajanje
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"))
Primijeti mješavinu formata na popisu – PDF, Markdown i običan tekst mogu nesmetano suživjeti u istoj kolekciji, što te štedi potrebe za standardizacijom izvora prije učitavanja.
Dva ključa, dva opsega
Ovaj proces koristi dva identifikatora pristupa koja ne smiješ zamijeniti: standardni API ključ (XAI_API_KEY) za učitavanje u koraku 1 i Management ključ (XAI_MANAGEMENT_API_KEY) za pripajanje u koraku 2. SDK prima oba pri stvaranju klijenta, a upload_document ih koristi jedan za drugim. Provjeri ima li potonji dopuštenje AddFileToCollection: bez njega će tvoje učitavanje uspjeti, ali će dodavanje failati s greškom 403, pa ćeš akumulirati datoteke koje su ispravno pohranjene, ali odsutne iz svake kolekcije.
Ključne točke
- Dodavanje u kolekciju odvija se u dva koraka: učitavanje pa dodavanje
- Datoteka može istovremeno pripadati više kolekcija
- Dokument mora doseći status
DOCUMENT_STATUS_PROCESSEDprije nego što postane pretraživ - Uklanjanje dokumenta iz kolekcije ne briše temeljnu datoteku
- Potrebna su dva različita API ključa: standardni za učitavanje, Management za kolekciju