Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Dokumentumok hozzáadása egy gyűjteményhez

6. lecke 16 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Miért történik két lépésben a hozzáadás?
  2. 1. lépés: A fájl feltöltése
  3. 2. lépés: Hozzácsatolás a gyűjteményhez
  4. Várd meg az indexelés befejeződését
  5. Dokumentum eltávolítása elvesztés nélkül
  6. Gyűjtemény feltöltése tömegesen
  7. Két kulcs, két hatáskör
  8. Főbb megállapítások

Frissítve: 2026. november 2. Ez a lecke az xai-sdk 1.21.0 verzióját és az xAI dokumentációját tükrözi: az await hívások az aszinkron AsyncClient használatát igénylik, az indexelési állapot összehasonlítása a collections_pb2.DOCUMENT_STATUS_PROCESSED konstanssal történik (nem karakterlánccal), a tömeges betöltés pedig az upload_document metó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