Премини към основното съдържание
Български— Изберете език
Меню

Python SDK на xAI: Асинхронни операции

Урок 16 от 16 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Автоматизирайте вашите RAG работни потоци в Python
  2. Инсталация и конфигурация
  3. Операции с колекции
  4. Добавяне на документ и изчакване на индексирането
  5. Търсене чрез SDK
  6. Пълен端到ен (End-to-End) конвейер
  7. Ключови изводи
  8. Проверете знанията си

Обновено на 2 ноември 2026 г. Въз основа на код на xai-sdk 1.21.0 и официалния пример на xAI: извикванията с await изискват асинхронния клиент AsyncClient (докато Client е синхронен); върнатите обекти предоставят collection_id, collections, matches и chunk_content; статусът на индексиране се сравнява с collections_pb2.DOCUMENT_STATUS_PROCESSED; а upload_document качва и прикачва файла с едно извикване (предишният пример го качваше два пъти, използвайки несъществуващ метод). Източници: Collections via the API · Collections Search · xai-sdk-python.

Автоматизирайте вашите RAG работни потоци в Python

Всичко, което сте извиквали чрез curl през този курс, съществува и в Python: качване на документи, управление на колекции, търсене и генериране. xAI SDK предлага два клиента – един синхронен (Client) и един асинхронен (AsyncClient), с идентични методи. Вторият е правилният избор за RAG работен поток, който прекарва по-голямата част от времето си в очакване – докато приключи качването, докато се индексира документът или докато се върне резултат от търсенето. Асинхронният код обработва тези изчаквания паралелно, а не последователно.

Инсталация и конфигурация

pip install xai-sdk

Клиентът изисква два ключа: стандартния API ключ за търсене и генериране, и ключа за Management API за колекциите.

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"),
)

Всяка заявка има по подразбиране таймаут от 27 минути преди изтичане, което покрива качването на голям PDF файл. Параметърът timeout, в секунди, Ви позволява да стегнете този лимит за интерактивно приложение.

Операции с колекции

Три извиквания покриват целия жизнен цикъл. Създаването връща ID, което ще преизползвате навсякъде другаде:

collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")

Списъкът с колекции помага основно за възстановяване на ID, което не сте запазили, или за проверка на състоянието на акаунт, споделен между множество проекти:

response = await client.collections.list()
for col in response.collections:
    print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")

Изтриването е необратимо и премахва документите и техните индекси:

await client.collections.delete(collection_id)

Добавяне на документ и изчакване на индексирането

Едно единствено извикване, upload_document, качва файла чрез Files API и го прикачва към колекцията:

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

Ако файлът вече съществува във Files API, add_existing_document(collection_id, file_id) го прикачва, без да го качва отново.

Добавянето на документ не го прави незабавно достъпен за заявки. Индексирането отнема променливо време в зависимост от размера на файла, а търсене, стартирано твърде рано, просто връща по-малко резултати от очакваното – бъг, който е особено болезнен за диагностициране, тъй като не генерира грешка. Затова е необходим този цикъл на изчакване, който опитва статуса, докато не стане 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)

Статусът е стойност на изброение (enum), а не низ: сравняването му с текста "DOCUMENT_STATUS_PROCESSED" никога няма да върне истина и цикълът ще работи безкрайно. За прост случай, upload_document(..., wait_for_indexing=True) обработва това изчакване вместо Вас.

Търсене чрез SDK

Търсенето връща същите оценени парчета (chunks) като HTTP крайната точка, в списъка 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("---")

Пълен端到ен (End-to-End) конвейер

Предишните блокове се сглобяват в скрипт, който създава колекцията, качва документите, изчаква индексирането, търси и след това генерира отговор, използвайки инструмента 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. Създаване на колекцията
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Добавяне на документи паралелно
    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. Изчакване всички документи да се индексират
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Търсене
    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. Генериране на отговор въз основа на колекцията
    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())

Двете извиквания на asyncio.gather() вършат цялата работа. Първото стартира трите качвания едновременно, вместо да чака всяко да приключи; второто наблюдава трите задачи за индексиране едновременно: общото време се доближава до това на най-дългия документ, а не до сумата от всички. И тъй като изчакването не блокира цикъла на събитията, същият код се вписва директно във FastAPI или aiohttp приложение, което продължава да обслужва други заявки, докато документите Ви се индексират.

Ключови изводи

  • Python SDK на xAI съществува в синхронна (Client) и асинхронна (AsyncClient) версия; await изисква последната.
  • И двата ключа (API и Management) се конфигурират в клиента.
  • upload_document качва и прикачва с едно извикване; следете индексирането чрез get_document или wait_for_indexing=True.
  • asyncio.gather() Ви позволява да качвате и чакате индексирането паралелно.
  • Генерирането използва колекцията чрез инструмента collections_search, включително отговор и цитати.

Проверете знанията си

Файлове, колекции, търсене: RAG, управляван от xAI.

1. Какво Ви позволява да правите Files API?

Отговор: Качване и управление на файлове (списък, преглед, изтриване) в поддържани формати – суровият материал за колекции и заявки с документи.

2. Какво представлява една колекция?

Отговор: Набор от документи, управлявани сървърно от xAI, с метаданни и права – готовият за употреба индекс, който заявявате, без да изграждате собствен векторен конвейер.

3. Кои режими на търсене са налични?

Отговор: Ключови думи (точни термини), семантично (смисъл) и хибридно (и двете) – изборът следва естеството на въпросите, като хибридното покрива повечето случаи.

4. Как се интегрира RAG с генерирането?

Отговор: Чрез инструмента за търсене в колекции: collections_search в xAI SDK, file_search с ID на колекции в Responses API. Моделът заявява Вашите документи по време на генерирането и цитира източниците си – RAG шаблонът без инфраструктура за поддръжка.

5. Кои точки изискват внимание за продукция?

Отговор: Поверителност на качените данни (права, жизнен цикъл), релевантност за оптимизиране (метаданни, разделяне на части) – и асинхронният SDK за обработка на големи обеми.

Управляван RAG: Вие предоставяте документите и въпросите, xAI се грижи за индекса – запазете контрол върху поверителността и релевантността.