Python SDK xAI: operacje asynchroniczne
Na tej stronie
Zaktualizowano 2 listopada 2026 r. Na podstawie kodu
xai-sdkw wersji 1.21.0 oraz oficjalnego przykładu xAI: wywołania zawaitwymagają klienta asynchronicznegoAsyncClient(klientClientjest synchroniczny), zwracane obiekty udostępniają polacollection_id,collections,matchesorazchunk_content, status indeksowania porównuje się z wartościącollections_pb2.DOCUMENT_STATUS_PROCESSED, a metodaupload_documentprzesyła plik i dołącza go do kolekcji w jednym wywołaniu (poprzedni przykład robił to dwukrotnie, używając nieistniejącej metody). Źródła: Kolekcje przez API · Wyszukiwanie w kolekcjach · xai-sdk-python.
Automatyzacja przepływów pracy RAG w Pythonie
Wszystko, co wywoływałeś za pomocą curla w trakcie tego kursu, istnieje również w Pythonie: przesyłanie dokumentów, zarządzanie kolekcjami, wyszukiwanie i generowanie. SDK xAI oferuje dwóch klientów: synchronicznego (Client) i asynchronicznego (AsyncClient), posiadających identyczne metody. Ten drugi jest właściwym wyborem dla przepływu pracy RAG, który większość czasu spędza na oczekiwaniu – na zakończenie przesyłania, zaindeksowanie dokumentu czy zwrócenie wyników wyszukiwania. Kod asynchroniczny obsługuje te oczekiwania równolegle, a nie sekwencyjnie.
Instalacja i konfiguracja
pip install xai-sdk
Klient wymaga dwóch kluczy: standardowego klucza API do wyszukiwania i generowania oraz klucza Management API do zarządzania kolekcjami.
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"),
)
Każde żądanie domyślnie czeka 27 minut przed upływem limitu czasu, co wystarcza do przesłania dużego pliku PDF. Parametr timeout (w sekundach) pozwala tightened ten limit w aplikacjach interaktywnych.
Operacje na kolekcjach
Trzy wywołania pokrywają pełny cykl życia. Tworzenie zwraca identyfikator, którego będziesz używać wszędzie indziej:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Listowanie przydaje się głównie do odzyskania identyfikatora, którego nie zapisałeś trwale, lub do sprawdzenia stanu konta współdzielonego między wieloma projektami:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Usunięcie jest nieodwracalne i usuwa zarówno dokumenty, jak i ich indeksy:
await client.collections.delete(collection_id)
Dodawanie dokumentu i oczekiwanie na indeksowanie
Jedno wywołanie, upload_document, przesyła plik przez Files API i dołącza go do kolekcji:
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
Jeśli plik już istnieje w Files API, metoda add_existing_document(collection_id, file_id) dołącza go bez ponownego przesyłania.
Dodanie dokumentu nie czyni go natychmiast dostępnym do zapytań. Indeksowanie zajmuje zmienny czas w zależności od rozmiaru pliku, a wyszukiwanie uruchomione zbyt wcześnie po prostu zwróci mniej wyników niż oczekiwano – błąd szczególnie trudny do zdiagnozowania, ponieważ nie generuje on żadnego wyjątku. Stąd poniższa pętla oczekująca, która odpytuje status aż do momentu uzyskania DOCUMENT_STATUS_PROCESSED:
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)
Status jest wartością wyliczeniową (enum), a nie ciągiem znaków: porównanie go do tekstu "DOCUMENT_STATUS_PROCESSED" nigdy nie zwróci prawdy, a pętla będzie działać w nieskończoność. W prostych przypadkach wywołanie upload_document(..., wait_for_indexing=True) obsłuży to oczekiwanie za Ciebie.
Wyszukiwanie z poziomu SDK
Wyszukiwanie zwraca te same oceniane fragmenty co punkt końcowy HTTP, w liście matches:
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("---")
Kompleksowy potok end-to-end
Poprzednie bloki składają się w skrypt, który tworzy kolekcję, przesyła dokumenty, czeka na indeksowanie, przeprowadza wyszukiwanie, a następnie generuje odpowiedź przy użyciu narzędzia collections_search:
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. Utwórz kolekcję
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Dodaj dokumenty równolegle
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. Poczekaj na zaindeksowanie wszystkich dokumentów
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Wyszukaj
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. Wygeneruj odpowiedź na podstawie kolekcji
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())
Dwa wywołania asyncio.gather() wykonują całą pracę. Pierwsze uruchamia trzy przesyłania jednocześnie, zamiast czekać na zakończenie każdego z nich; drugie monitoruje trzy zadania indeksowania równocześnie: całkowity czas zbliża się do czasu trwania najdłuższego dokumentu, a nie sumy wszystkich. Ponieważ oczekiwanie nie blokuje pętli zdarzeń, ten sam kod pasuje bezpośrednio do aplikacji FastAPI lub aiohttp, które mogą继续 obsługiwać inne żądania podczas indeksowania Twoich dokumentów.
Kluczowe wnioski
- Python SDK xAI istnieje w wersjach synchronicznej (
Client) i asynchronicznej (AsyncClient);awaitwymaga tej drugiej. - Oba klucze (API i Management) konfiguruje się w kliencie.
upload_documentprzesyła i dołącza plik w jednym wywołaniu; monitoruj indeksowanie przezget_documentlub użyjwait_for_indexing=True.asyncio.gather()pozwala przesyłać pliki i czekać na indeksowanie równolegle.- Generowanie wykorzystuje kolekcję dzięki narzędziu
collections_search, zapewniając odpowiedź wraz z cytowaniami.
Sprawdź swoją wiedzę
Pliki, kolekcje, wyszukiwanie: RAG zarządzane przez xAI.
1. Co pozwala robić Files API?
Odpowiedź: Przesyłać i zarządzać plikami (listowanie, podgląd, usuwanie) w obsługiwanych formatach – to surowiec do tworzenia kolekcji i zapytań z dokumentami.
2. Czym jest kolekcja?
Odpowiedź: Zbiór dokumentów zarządzany po stronie serwera przez xAI, posiadający metadane i uprawnienia – gotowy do użycia indeks, który odpytujesz bez budowania własnego potoku wektorowego.
3. Jakie tryby wyszukiwania są dostępne?
Odpowiedź: Słów kluczowych (dokładne terminy), semantyczny (znaczenie) i hybrydowy (oba) – wybór zależy od natury pytań, przy czym tryb hybrydowy pokrywa większość przypadków.
4. Jak RAG integruje się z generowaniem?
Odpowiedź: Poprzez narzędzie wyszukiwania w kolekcji: collections_search w SDK xAI lub file_search z identyfikatorami kolekcji w Responses API. Model odpytuje Twoje dokumenty podczas generowania i cytuje źródła – wzorzec RAG bez infrastruktury do utrzymania.
5. Na jakie punkty należy zwrócić uwagę w środowisku produkcyjnym?
Odpowiedź: Poufność przesyłanych danych (uprawnienia, cykl życia), trafność do optymalizacji (metadane, chunking) – oraz asynchroniczne SDK do przetwarzania dużych wolumenów.
Zarządzany RAG: Ty dostarczasz dokumenty i pytania, xAI zajmuje się indeksem – zachowaj kontrolę nad poufnością i trafnością.