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

Az xAI Python SDK: Aszinkron műveletek

16. lecke 16 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Automatizáld a RAG munkafolyamataidat Pythonban
  2. Telepítés és konfiguráció
  3. Kollekción végzett műveletek
  4. Dokumentum hozzáadása és várakozás az indexelésre
  5. Keresés az SDK-ból
  6. Egy teljes végpontok közötti (end-to-end) folyamat
  7. Főbb megállapítások
  8. Teszteld a tudásod!

Frissítve: 2026. november 2. Az xai-sdk 1.21.0 verzióján és a hivatalos xAI példán alapul: az await hívásokhoz az aszinkron kliens (AsyncClient) szükséges (a Client szinkron), a visszakapott objektumok tartalmazzák a collection_id, collections, matches és chunk_content attribútumokat, az indexelési állapot összehasonlítása a collections_pb2.DOCUMENT_STATUS_PROCESSED értékkel történik, az upload_document pedig 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; az await használatához az utóbbi szükséges.
  • Mindkét kulcs (API és Management) a kliensben konfigurálható.
  • Az upload_document egyetlen hívással tölti fel és csatolja a fájlt; az indexelést a get_document segítségével vagy a wait_for_indexing=True paramé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_search eszkö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.