Přidání dokumentů do kolekce
Na této stránce
Aktualizováno 2. listopadu 2026. Tato lekce odpovídá verzi
xai-sdk1.21.0 a dokumentaci xAI: voláníawaitvyžadují asynchronníAsyncClient, stav indexování se porovnává s konstantoucollections_pb2.DOCUMENT_STATUS_PROCESSED(nikoli řetězcem) a hromadné načítání využívá metoduupload_document, která oba kroky sloučí do jednoho volání. Zdroje: Kolekce přes API · xai-sdk-python.
Proč probíhá přidávání ve dvou krocích
Možná očekáváš, že PDF jednoduše přetáhneš do kolekce, jako když házíš soubor do složky. API xAI tak nefunguje: dokument nejprve projde přes Files API, které jej uloží a přidělí mu file_id, a následně přes Management API, které tento identifikátor propojí s kolekcí. Dva požadavky, dva klíče, dva kroky.
Toto oddělení má přímý a užitečný důsledek: soubor existuje na úložišti pouze jednou, ale může být propojen s libovolným počtem kolekcí. Stejná technická zpráva může napájet databázi produktového týmu i týmu podpory, aniž by byla nahrávána dvakrát, aniž by dvojnásobně spotřebovávala kvótu a aniž by hrozilo rozdílné verzování dvou kopií.
Krok 1: Nahrání souboru
Zde není nic nového, tento endpoint už ovládáš od první lekce:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Z odpovědi získej file_id: ten bude klíčem pro další krok.
Krok 2: Připojení ke kolekci
Přidání probíhá formou požadavku POST na URL, která kombinuje oba identifikátory – ID kolekce a ID souboru – a nevyžaduje žádné tělo požadavku:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Jakmile je tento požadavek přijat, xAI zahájí indexování obsahu. Dokument pak projde několika stavy zpracování, než je skutečně dostupný pro vyhledávání.
Počkej na dokončení indexování
To je častá past v prvním pipeline: požadavek na přidání vrátí úspěch, ty okamžitě provedeš vyhledávání a kolekce odpoví, že nic nenašla. Dokument sice existuje, ale ještě není zaindexován. Stav, na který musíš čekat, je DOCUMENT_STATUS_PROCESSED, a SDK ti umožňuje jej správně dotazovat:
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"))
Prodleva závisí přímo na velikosti: PDF o několika stránkách se zaindexuje během několika sekund, zatímco dokument o velikosti 100 MB může trvat několik minut. Pro noční načítání stačí tato smyčka s třísekundovou pauzou; v rozhraní, kde uživatel nahrává soubor a čeká, poskytni vizuální zpětnou vazbu, nikoliv zamrzlou obrazovku.
Odebrání dokumentu bez jeho ztráty
Odpojení souboru od kolekce je samostatná operace, odlišná od jeho smazání:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Soubor zmizí z indexu této kolekce, ale zůstane dostupný přes Files API a lze jej propojit jinde. Přesně to bys měl udělat, když se produktový list pro podporu stane zastaralým, ale stále má archívní hodnotu: odstraníš jej z provozní databáze, aniž bys zničil samotný dokument.
Hromadné naplnění kolekce
Při inicializaci databáze z celé složky napiš smyčku jednou; bude ti dlouho sloužit:
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 jediném volání: nahrání přes Files API a následné připojení
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 mixu formátů v seznamu – PDF, Markdown a prostý text mohou bez problémů koexistovat ve stejné kolekci, což tě zbavuje nutnosti standardizovat zdroje před načtením.
Dva klíče, dva rozsahy
Tento proces využívá dva přístupové identifikátory, které si nesmíš plést: standardní klíč API (XAI_API_KEY) pro krok 1 (nahrání) a klíč Management (XAI_MANAGEMENT_API_KEY) pro krok 2 (připojení). SDK oba přijímá při vytvoření klienta a metoda upload_document je využívá jeden po druhém. Ověř, že ten druhý má oprávnění AddFileToCollection: bez něj se nahrání povede, ale přidání selže s chybou 403, a ty budeš hromadit soubory, které jsou sice správně uloženy, ale chybí v jakékoli kolekci.
Klíčové poznatky
- Přidání do kolekce probíhá ve dvou krocích: nejprve nahrání, poté přidání
- Soubor může patřit do více kolekcí současně
- Dokument musí dosáhnout stavu
DOCUMENT_STATUS_PROCESSED, než je vyhledatelný - Odebrání dokumentu z kolekce nemaže underlying soubor
- Jsou zapotřebí dva odlišné klíče API: standardní pro nahrání, Management pro kolekci