Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Přidání dokumentů do kolekce

Lekce 6 z 16 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Proč probíhá přidávání ve dvou krocích
  2. Krok 1: Nahrání souboru
  3. Krok 2: Připojení ke kolekci
  4. Počkej na dokončení indexování
  5. Odebrání dokumentu bez jeho ztráty
  6. Hromadné naplnění kolekce
  7. Dva klíče, dva rozsahy
  8. Klíčové poznatky

Aktualizováno 2. listopadu 2026. Tato lekce odpovídá verzi xai-sdk 1.21.0 a dokumentaci xAI: volání await vyžadují asynchronní AsyncClient, stav indexování se porovnává s konstantou collections_pb2.DOCUMENT_STATUS_PROCESSED (nikoli řetězcem) a hromadné načítání využívá metodu upload_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