Przejdź do głównej treści
Polski— Wybierz język
Menu

Python SDK xAI: operacje asynchroniczne

Lekcja 16 z 16 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Automatyzacja przepływów pracy RAG w Pythonie
  2. Instalacja i konfiguracja
  3. Operacje na kolekcjach
  4. Dodawanie dokumentu i oczekiwanie na indeksowanie
  5. Wyszukiwanie z poziomu SDK
  6. Kompleksowy potok end-to-end
  7. Kluczowe wnioski
  8. Sprawdź swoją wiedzę

Zaktualizowano 2 listopada 2026 r. Na podstawie kodu xai-sdk w wersji 1.21.0 oraz oficjalnego przykładu xAI: wywołania z await wymagają klienta asynchronicznego AsyncClient (klient Client jest synchroniczny), zwracane obiekty udostępniają pola collection_id, collections, matches oraz chunk_content, status indeksowania porównuje się z wartością collections_pb2.DOCUMENT_STATUS_PROCESSED, a metoda upload_document przesył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); await wymaga tej drugiej.
  • Oba klucze (API i Management) konfiguruje się w kliencie.
  • upload_document przesyła i dołącza plik w jednym wywołaniu; monitoruj indeksowanie przez get_document lub użyj wait_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ą.