Pridávanie dokumentov do kolekcie
Na tejto strane
Aktualizované 2. novembra 2026. Táto lekcia vychádza z verzie
xai-sdk1.21.0 a dokumentácie xAI: volaniaawaitvyžadujú asynchrónny klientAsyncClient, stav indexovania sa porovnáva s konštantoucollections_pb2.DOCUMENT_STATUS_PROCESSED(nie ako reťazec) a hromadné načítanie využíva metóduupload_document, ktorá spája oba kroky do jedného volania. Zdroje: Kolekcie cez API · xai-sdk-python.
Prečo prebieha pridávanie v dvoch krokoch
Možno očakávaš, že PDF jednoducho „prehodíš“ do kolekcie, akoby si presúval súbor do priečinka. API xAI však funguje inak: dokument najprv prejde cez Files API, ktoré ho uloží a pridelí mu file_id, a následne cez Management API, ktoré tento identifikátor prepojí s kolekciou. Dva volania, dva kľúče, dva kroky.
Toto oddelenie má priamy a užitočný dôsledok: súbor existuje na úložisku len raz, no môže byť prepojený s ľubovoľným počtom kolekcií. Ten istý technický report môže napájať databázu produktového tímu aj tímu podpory bez potreby dvojitého nahrávania, bez dvojitej spotreby kvóty a bez rizika rozdielov medzi dvoma kópiami.
Krok 1: Nahratie súboru
Nič nové, toto je koncový bod, ktorý si zvládol už v prvej lekcii:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Z odpovede získaš file_id: toto je kľúč pre ďalší krok.
Krok 2: Pripojenie ku kolekcii
Pridanie prebieha ako požiadavka POST na URL, ktorá kombinuje oba identifikátory – ID kolekcie a ID súboru – a nevyžaduje žiadne telo požiadavky:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Akonáhle je toto volanie prijaté, xAI začne indexovať obsah. Dokument potom prejde niekoľkými stavmi spracovania, kým bude skutočne dostupný na vyhľadávanie.
Počkaj na dokončenie indexovania
Toto je častá pasca pri prvom nasadení: požiadavka na pridanie vráti úspech, ty okamžite nasleduješ vyhľadávaním a kolekcia odpovie, že nič nenašla. Dokument síce existuje, ale ešte nie je zindexovaný. Stav, na ktorý musíš čakať, je DOCUMENT_STATUS_PROCESSED, a SDK ti umožňuje správne ho dotazovať:
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"))
Oneskorenie priamo závisí od veľkosti: PDF s niekoľkými stranami sa zindexuje za pár sekúnd, zatiaľ čo 100 MB dokument môže trvať niekoľko minút. Pri nočnom načítavaní stačí tento cyklus s trojsekundovou pauzou; v rozhraní, kde používateľ nahráva súbor a čaká, poskytni vizuálnu spätnú väzbu namiesto zamrznutej obrazovky.
Odstránenie dokumentu bez jeho straty
Odpojenie súboru od kolekcie je samostatná operácia, odlišná od jeho vymazania:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Súbor zmizne z indexu tejto konkrétnej kolekcie, ale zostane dostupný cez Files API a môže byť prepojený inde. Presne to by si mal urobiť, keď sa produktový list stane pre podporu zastaraným, no stále má archívnu hodnotu: odstrániš ho z prevádzkovej databázy, ale nezničíš samotný dokument.
Hromadné naplnenie kolekcie
Pri inicializácii databázy z celého priečinka napíš cyklus raz; bude ti dlho slúžiť:
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):
# Kroky 1 a 2 v jednom volaní: nahratie cez Files API a následné pripojenie
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"))
Všimni si zmes formátov v zozname – PDF, Markdown a čistý text môžu v tej istej kolekcii koexistovať bez problémov, čo ťa zbavuje potreby štandardizovať zdroje pred načítaním.
Dva kľúče, dva rozsahy
Tento proces využíva dva prístupové identifikátory, ktoré si nesmieš pomýliť: štandardný kľúč API (XAI_API_KEY) pre krok 1 (nahratie) a kľúč Management (XAI_MANAGEMENT_API_KEY) pre krok 2 (pripojenie). SDK prijíma oba pri vytvorení klienta a metóda upload_document ich používa postupne za sebou. Over, či ten druhý má oprávnenie AddFileToCollection: bez neho sa nahratie úspešne dokončí, ale pridanie zlyhá s chybou 403, čo povedie k hromadeniu správne uložených súborov, ktoré však chýbajú v akejkoľvek kolekcii.
Kľúčové poznatky
- Pridanie do kolekcie prebieha v dvoch krokoch: najprv nahratie, potom pridanie
- Jeden súbor môže súčasne patriť do viacerých kolekcií
- Dokument musí dosiahnuť stav
DOCUMENT_STATUS_PROCESSED, aby bol vyhľadávateľný - Odstránenie dokumentu z kolekcie nevymaže underlying súbor
- Sú potrebné dva odlišné API kľúče: štandardný pre nahratie a Management pre kolekciu