Az xAI Python SDK: Aszinkron műveletek
Ezen az oldalon
Frissítve: 2026. november 2. Az
xai-sdk1.21.0 verzióján és a hivatalos xAI példán alapul: azawaithívásokhoz az aszinkron kliens (AsyncClient) szükséges (aClientszinkron), a visszakapott objektumok tartalmazzák acollection_id,collections,matcheséschunk_contentattribútumokat, az indexelési állapot összehasonlítása acollections_pb2.DOCUMENT_STATUS_PROCESSEDértékkel történik, azupload_documentpedig egyetlen hívással tölti fel és csatolja a fájlt (a korábbi példa kétszer töltötte fel, egyszer egy nem létező metódust használva). Források: Collections via the API · Collections Search · xai-sdk-python.
Automatizáld a RAG munkafolyamataidat Pythonban
Minden, amit ebben a tanfolyamban curl-lel hívtál meg, elérhető Pythonban is: dokumentumfeltöltés, kollekciókezelés, keresés, generálás. Az xAI SDK két klienst kínál: egy szinkront (Client) és egy aszinkront (AsyncClient), azonos metódusokkal. Utóbbi a helyes választás egy RAG munkafolyamathoz, amelynek ideje nagy részét várakozással tölti – míg befejeződik egy feltöltés, indexelődik egy dokumentum, vagy visszatér egy keresés. Az aszinkron kód ezeket a várakozásokat sorban helyett párhuzamosan kezeli.
Telepítés és konfiguráció
pip install xai-sdk
A kliens két kulcsot igényel: a kereséshez és generáláshoz szükséges szabványos API-kulcsot, valamint a kollekciók kezeléséhez szükséges Management API-kulcsot.
import os
from xai_sdk import AsyncClient
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
Minden kérés alapértelmezés szerint 27 perces időtúllépési limit előtt jár le, ami elegendő egy nagy PDF feltöltéséhez. A másodpercben megadott timeout paraméterrel szigoríthatod ezt a limitet interaktív alkalmazások esetén.
Kollekción végzett műveletek
Három hívás lefedi a teljes életciklust. A létrehozás visszaadja az azonosítót, amit mindenhol újra felhasználsz:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
A listázás főleg akkor hasznos, ha vissza kell szerezned egy el nem mentett azonosítót, vagy ellenőrizni szeretnéd egy több projekt között megosztott fiók állapotát:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
A törlés visszafordíthatatlan, és eltávolítja a dokumentumokat valamint azok indexeit is:
await client.collections.delete(collection_id)
Dokumentum hozzáadása és várakozás az indexelésre
Egyetlen hívás, az upload_document, feltölti a fájlt a Files API-n keresztül, és csatolja a kollekcióhoz:
from pathlib import Path
async def add_document(client, collection_id, file_path):
path = Path(file_path)
document = await client.collections.upload_document(
collection_id=collection_id,
name=path.name,
data=path.read_bytes(),
)
return document.file_metadata.file_id
Ha a fájl már létezik a Files API-ban, az add_existing_document(collection_id, file_id) csatolja azt anélkül, hogy újra feltöltené.
Egy dokumentum hozzáadása nem teszi azt azonnal lekérdezhetővé. Az indexelés változó ideig tart a fájlmérettől függően, és egy túl korán indított keresés egyszerűen kevesebb találatot ad vissza a vártnál – ez egy különösen fájdalmasan diagnosztizálható hiba, mivel nem dob kivételt. Ezért szükséges ez a várakozási ciklus, amely addig kérdezi le az állapotot, amíg el nem éri a DOCUMENT_STATUS_PROCESSED értéket:
import asyncio
from xai_sdk.proto import collections_pb2
async def wait_for_indexing(client, file_id, collection_id):
while True:
doc = await client.collections.get_document(file_id, collection_id)
if doc.status == collections_pb2.DOCUMENT_STATUS_PROCESSED:
print("Document ready")
return
if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
raise RuntimeError(f"Indexing failed: {doc.error_message}")
await asyncio.sleep(3)
Az állapot egy enumerációs érték, nem pedig szöveg: ha szövegesen hasonlítanád össze a "DOCUMENT_STATUS_PROCESSED" karaktersorozattal, az sosem lenne igaz, és a ciklus örökké futna. Egyszerű esetekben az upload_document(..., wait_for_indexing=True) paraméter elvégzi helyetted ezt a várakozást.
Keresés az SDK-ból
A keresés ugyanazokat a pontszámolt részleteket (chunk) adja vissza, mint a HTTP végpont, a matches listában:
results = await client.collections.search(
query="Order validation procedure",
collection_ids=[collection_id],
)
for m in results.matches:
print(f"Score: {m.score:.2f}")
print(f"Content: {m.chunk_content[:200]}")
print("---")
Egy teljes végpontok közötti (end-to-end) folyamat
A korábbi blokkok egy olyan szkriptté állnak össze, amely létrehozza a kollekciót, feltölti a dokumentumokat, megvárja az indexelést, keresést végez, majd választ generál a collections_search eszköz használatával:
import asyncio
import os
from xai_sdk import AsyncClient
from xai_sdk.chat import user
from xai_sdk.tools import collections_search
async def rag_pipeline():
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
# 1. Kollekció létrehozása
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Dokumentumok hozzáadása párhuzamosan
files = [
"docs/architecture.pdf",
"docs/api-reference.pdf",
"docs/deployment-guide.md",
]
file_ids = await asyncio.gather(*[
add_document(client, collection_id, f) for f in files
])
# 3. Várakozás az összes dokumentum indexelésére
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Keresés
results = await client.collections.search(
query="How to deploy to production?",
collection_ids=[collection_id],
)
for m in results.matches:
print(f"[{m.score:.2f}] {m.chunk_content[:150]}")
# 5. Válasz generálása a kollekció alapján
chat = client.chat.create(
model="grok-4.7",
tools=[collections_search(collection_ids=[collection_id])],
)
chat.append(user("Explain the deployment procedure and cite your sources."))
response = await chat.sample()
print(response.content)
print(response.citations)
asyncio.run(rag_pipeline())
A két asyncio.gather() hívás végzi el a munka javát. Az első egyszerre indítja el a három feltöltést ahelyett, hogy megvárná mindegyik befejezését; a második pedig egyszerre figyeli a három indexelési feladatot: a teljes idő így a leghosszabb dokumentum idejéhez közelít, nem pedig az összes összegéhez. Mivel a várakozás nem blokkolja az eseményhurkot, ez a kód közvetlenül beilleszthető egy FastAPI vagy aiohttp alkalmazásba, amely továbbra is kiszolgál más kéréseket, miközben a dokumentumaid indexelődnek.
Főbb megállapítások
- Az xAI Python SDK létezik szinkron (
Client) és aszinkron (AsyncClient) verzióban is; azawaithasználatához az utóbbi szükséges. - Mindkét kulcs (API és Management) a kliensben konfigurálható.
- Az
upload_documentegyetlen hívással tölti fel és csatolja a fájlt; az indexelést aget_documentsegítségével vagy await_for_indexing=Trueparaméterrel követheted nyomon. - Az
asyncio.gather()lehetővé teszi a feltöltés és az indexelésre való várakozás párhuzamosítását. - A generálás a kollekciót a
collections_searcheszközzel használja fel, válaszokkal és hivatkozásokkal együtt.
Teszteld a tudásod!
Fájlok, kollekciók, keresés: az xAI által kezelt RAG.
1. Mire teszi lehetővé a Files API-t?
Válasz: Fájlok feltöltése és kezelése (listázás, megtekintés, törlés) támogatott formátumokban – ez a nyersanyag a kollekciókhoz és a dokumentumokkal végzett lekérdezésekhez.
2. Mi az a kollekció?
Válasz: Dokumentumok halmaza, amelyet az xAI szerveroldalon kezel, metaadatokkal és jogosultságokkal – ez a használatra kész index, amelyet saját vektoros folyamatrendszer felépítése nélkül kérdezhetsz le.
3. Milyen keresési módok érhetők el?
Válasz: Kulcsszavas (pontos kifejezések), szemantikai (jelentésalapú) és hibrid (mindkettő) – a választás a kérdések jellegétől függ, a hibrid mód pedig az esetek többségét lefedi.
4. Hogyan integrálódik a RAG a generálásba?
Válasz: A kollekciókereső eszközön keresztül: collections_search az xAI SDK-ban, file_search kollekció-azonosítókkal a Responses API-ban. A modell a generálás során lekérdezi a dokumentumaidat, és hivatkozik a forrásokra – ez a RAG minta infrastruktúra-karbantartás nélkül.
5. Milyen pontokra kell figyelni éles környezetben?
Válasz: A feltöltött adatok bizalmassága (jogosultságok, életciklus), a relevancia optimalizálása (metaadatok, darabolás) – és az aszinkron SDK használata nagy volumenű feldolgozáshoz.
Kezelt RAG: te hozod a dokumentumokat és a kérdéseket, az xAI kezeli az indexet – tartsd kézben a bizalmasságot és a relevanciát.