Dokumentumok hozzáadása egy gyűjteményhez
Ezen az oldalon
Frissítve: 2026. november 2. Ez a lecke az
xai-sdk1.21.0 verzióját és az xAI dokumentációját tükrözi: azawaithívások az aszinkronAsyncClienthasználatát igénylik, az indexelési állapot összehasonlítása acollections_pb2.DOCUMENT_STATUS_PROCESSEDkonstanssal történik (nem karakterlánccal), a tömeges betöltés pedig azupload_documentmetódust használja, amely egyetlen hívásban egyesíti mindkét lépést. Források: Collections via the API · xai-sdk-python.
Miért történik két lépésben a hozzáadás?
Talán arra számítasz, hogy közvetlenül bedobhatsz egy PDF-fájlt egy gyűjteménybe, mintha csak egy mappába húznál egy fájlt. Az xAI API azonban nem így működik: a dokumentum először áthalad a Files API-n, amely eltárolja azt és rendel hozzá egy file_id azonosítót, majd a Management API-n, amely ezt az azonosítót összekapcsolja a gyűjteménnyel. Két hívás, két kulcs, két lépés.
Ennek a szétválasztásnak közvetlen és hasznos következménye van: a fájl a tároló oldalon csak egyszer létezik, de tetszőleges számú gyűjteményhez hozzákapcsolható. Ugyanaz a technikai jelentés táplálhatja a termékcsapat és az ügyfélszolgálat adatbázisát is anélkül, hogy kétszer kellene feltölteni, anélkül, hogy kétszer fogyasztaná a kvótát, és anélkül, hogy kockáztatnád két másolat eltérését.
1. lépés: A fájl feltöltése
Itt nincs semmi új, ez az a végpont, amelyet már az első leckétől kezdve tökéletesen ismersz:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Nyerd ki a file_id értéket a válaszból: ez lesz a kulcs a következő lépéshez.
2. lépés: Hozzácsatolás a gyűjteményhez
A hozzáadás egy POST kérésként történik egy olyan URL-címre, amely egyesíti a két azonosítót (a gyűjtemény ID-jét és a fájl ID-jét), és nem igényel kéréstörzset:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Ha ezt a hívást elfogadják, az xAI elindítja a tartalom indexelését. A dokumentum ezután több feldolgozási állapoton megy keresztül, mire ténylegesen elérhetővé válik a kereséshez.
Várd meg az indexelés befejeződését
Ez egy gyakori buktató az első pipeline-okban: a hozzáadási kérés sikert jelez, te azonnal keresést indítasz, a gyűjtemény pedig azt válaszolja, hogy nem talál semmit. A dokumentum létezik, de még nincs indexelve. Az állapot, amire várnod kell, a DOCUMENT_STATUS_PROCESSED, és az SDK lehetővé teszi ennek helyes lekérdezését:
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"))
A késleltetés közvetlenül függ a mérettől: egy néhány oldalas PDF néhány másodperc alatt indexelődik, míg egy 100 MB-os dokumentum több percet is igénybe vehet. Éjszakai betöltéshez ez a hárommásodperces szünettel rendelkező ciklus elegendő; olyan felület esetén, ahol a felhasználó feltölt egy fájlt és vár, vizuális visszajelzést kell biztosítani a befagyott képernyő helyett.
Dokumentum eltávolítása elvesztés nélkül
A fájl gyűjteményből való leválasztása külön művelet a törlésétől:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
A fájl eltűnik e gyűjtemény indexéből, de a Files API-n keresztül továbbra is elérhető marad, és máshová is hozzákapcsolható. Pontosan ezt kell tenned, amikor egy terméklap elavult az ügyfélszolgálat számára, de megőrzi archiválási értékét: eltávolítod az operatív adatbázisból anélkül, hogy megsemmisítenéd a dokumentumot.
Gyűjtemény feltöltése tömegesen
Amikor egy teljes mappából inicializálsz egy adatbázist, írd meg egyszer a ciklust; hosszú távon jól fog szolgálni:
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):
# 1. és 2. lépés egyetlen hívásban: feltöltés a Files API-n keresztül, majd hozzácsatolás
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"))
Figyeld meg a formátumok keveredését a listában – a PDF, a Markdown és a sima szöveg probléma nélkül共存álhat ugyanabban a gyűjteményben, ami megkímél attól, hogy a betöltés előtt szabványosítsd a forrásaidat.
Két kulcs, két hatáskör
Ez a folyamat két hozzáférési azonosítót használ, amelyeket nem szabad összekeverned: a szabványos API-kulcsot (XAI_API_KEY) az 1. lépésben történő feltöltéshez, és a Management kulcsot (XAI_MANAGEMENT_API_KEY) a 2. lépésben történő hozzácsatoláshoz. Az SDK mindkettőt megkapja a kliens létrehozásakor, és az upload_document egymás után használja őket. Ellenőrizd, hogy ez utóbbi rendelkezik-e az AddFileToCollection engedéllyel: enélkül a feltöltésed sikerrel jár, a hozzáadásod viszont 403-as hibával meghiúsul, és olyan fájlokat halmozol fel, amelyek helyesen tárolódnak, de egyetlen gyűjteményben sem jelennek meg.
Főbb megállapítások
- A gyűjteményhez való hozzáadás két lépésben történik: először feltöltés, majd hozzáadás
- Egy fájl egyszerre több gyűjteményhez is tartozhat
- A dokumentumnak el kell érnie a
DOCUMENT_STATUS_PROCESSEDállapotot, mielőtt kereshetővé válik - A dokumentum gyűjteményből való eltávolítása nem törli az alapul szolgáló fájlt
- Két különböző API-kulcs szükséges: szabványos a feltöltéshez, Management a gyűjtemény kezeléséhez