Python SDK на xAI: Асинхронни операции
На тази страница
Обновено на 2 ноември 2026 г. Въз основа на код на
xai-sdk1.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 се грижи за индекса – запазете контрол върху поверителността и релевантността.