xAI Python SDK: Asynkroniset toiminnot
Tällä sivulla
Päivitetty 2. marraskuuta 2026. Perustuu
xai-sdk1.21.0 -koodiin ja viralliseen xAI-esimerkkiin:await-kutsut vaativat asynkronisen asiakkaanAsyncClient(kun taasClienton synkroninen), palautetut oliot tarjoavat attribuutitcollection_id,collections,matchesjachunk_content, indeksointitilaa verrataan arvooncollections_pb2.DOCUMENT_STATUS_PROCESSED, jaupload_documentlataa ja liittää tiedoston yhdellä kutsulla (edellinen esimerkki latasi sen kahdesti, käyttäen olematonta metodia). Lähteet: Collections via the API · Collections Search · xai-sdk-python.
Automatisoi RAG-työnkulut Pythonilla
Kaikki, mitä olet kurssin aikana kutsunut curlilla, on olemassa Pythonissa: tiedostojen lataus, kokoelmien hallinta, haku ja generointi. xAI SDK tarjoaa kaksi asiakasoliota, synkronisen (Client) ja asynkronisen (AsyncClient), joilla on identtiset metodit. Jälkimmäinen on oikea valinta RAG-työnkulkuun, jossa suurin osa ajasta kuluu odottamiseen – latauksen valmistumista, dokumentin indeksoitumista tai haun vastausta. Asynkroninen koodi käsittelee nämä odotukset rinnakkain eikä peräkkäin.
Asennus ja konfigurointi
pip install xai-sdk
Asiakasolio vaatii kaksi avainta: vakio-API-avaimen hakua ja generointia varten sekä Management API -avaimen kokoelmia varten.
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"),
)
Jokaisen pyynnön oletusaikakatkaisu on 27 minuuttia ennen vanhenemista, mikä riittää suuren PDF-tiedoston lataamiseen. timeout-parametrilla (sekunteina) voit tiukentaa tätä rajaa interaktiivisissa sovelluksissa.
Kokoelmaoperaatiot
Kolme kutsua kattaa koko elinkaaren. Luominen palauttaa tunnisteen, jota käytät kaikkialla muualla:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Listaaminen auttaa ensisijaisesti palauttamaan tunnisteen, jota et ole tallentanut, tai tarkistamaan useiden projektien yhteisen tilin tilan:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Poistaminen on peruuttamatonta ja poistaa dokumentit sekä niiden indeksit:
await client.collections.delete(collection_id)
Dokumentin lisääminen ja indeksoinnin odottaminen
Yksi kutsu, upload_document, lataa tiedoston Files API:n kautta ja liittää sen kokoelmaan:
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
Jos tiedosto on jo olemassa Files API:ssa, add_existing_document(collection_id, file_id) liittää sen uudelleenlataamatta.
Dokumentin lisääminen ei tee siitä heti haettavissa olevaa. Indeksointi vie vaihtelevan ajan tiedoston koosta riippuen, ja liian aikaisin käynnistetty haku palauttaa yksinkertaisesti odotettua vähemmän tuloksia – virhe, jonka diagnosointi on erityisen tuskallista, koska se ei nosta virhettä. Tästä syystä tämä odotussilmukka, joka kyselyttää tilaa, kunnes saavutetaan 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)
Tila on luetelma-arvo (enum), ei merkkijono: sen vertaaminen tekstiin "DOCUMENT_STATUS_PROCESSED" ei koskaan olisi totta, ja silmukka pyörisi ikuisesti. Yksinkertaisissa tapauksissa upload_document(..., wait_for_indexing=True) hoitaa tämän odotuksen puolestasi.
Haku SDK:n kautta
Haku palauttaa samat pisteytetyt osiot kuin HTTP-päätepiste, listassa 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("---")
Täydellinen end-to-end -putki
Edelliset lohkot muodostavat skriptin, joka luo kokoelman, lataa dokumentit, odottaa indeksointia, suorittaa haun ja generoi vastauksen käyttäen collections_search-työkalua:
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. Luo kokoelma
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Lisää dokumentit rinnakkain
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. Odota kaikkien dokumenttien indeksoitumista
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Haku
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. Generoi vastaus kokoelman perusteella
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())
Kaksi asyncio.gather()-kutsua tekevät kaiken työn. Ensimmäinen käynnistää kolme latausta yhtä aikaa sen sijaan, että odotettaisiin kunkin valmistumista; toinen valvoo kolmea indeksointityötä samanaikaisesti: kokonaisaika lähestyy pisimmän dokumentin kestoa eikä kaikkien summaa. Koska odotus ei estä tapahtumasilmukkaa, sama koodi sopii suoraan FastAPI- tai aiohttp-sovellukseen, joka jatkaa muiden pyyntöjen palvelemista dokumenttiesi indeksoituessa.
Keskeiset asiat
- xAI Python SDK on saatavilla synkronisena (
Client) ja asynkronisena (AsyncClient) versiona;awaitvaatii jälkimmäistä - Molemmat avaimet (API ja Management) määritetään asiakasoliossa
upload_documentlataa ja liittää yhdellä kutsulla; seuraa indeksointia metodillaget_documenttai parametrillawait_for_indexing=Trueasyncio.gather()mahdollistaa latauksen ja indeksoinnin odotuksen rinnakkain- Generointi hyödyntää kokoelmaa
collections_search-työkalun kautta, sisältäen vastauksen ja lähdeviitteet
Testaa tietosi
Tiedostot, kokoelmat, haku: xAI:n hallinnoima RAG.
1. Mitä Files API antaa sinun tehdä?
Vastaus: Ladata ja hallita tiedostoja (listata, katsella, poistaa) tuetuissa muodoissa – raaka-aine kokoelmille ja kyselyille dokumenteilla.
2. Mikä on kokoelma?
Vastaus: xAI:n palvelinpuolella hallinnoima joukko dokumentteja, joilla on metadata ja käyttöoikeudet – valmis indeksi, jota kyselytät ilman oman vektoriputken rakentamista.
3. Mitä hakutiloja on saatavilla?
Vastaus: Avainsana (tarkat termit), semanttinen (merkitys) ja hybridi (molemmat) – valinta seuraa kysymysten luonnetta, ja hybridi kattaa useimmat tapaukset.
4. Miten RAG integroituu generointiin?
Vastaus: Kokoelman hakutyökalun kautta: collections_search xAI SDK:ssa, file_search kokoelmatunnuksilla Responses API:ssa. Malli kysyy dokumenttejasi generoinnin aikana ja siteeraa lähteitään – RAG-malli ilman ylläpidettävää infrastruktuuria.
5. Mihin kohtiin on kiinnitettävä huomiota tuotannossa?
Vastaus: Ladattujen tietojen luottamuksellisuus (käyttöoikeudet, elinkaari), relevanssin optimointi (metadata, osioitus) – ja asynkroninen SDK suurten volyymien käsittelyyn.
Hallinnoitu RAG: sinä tuot dokumentit ja kysymykset, xAI hoitaa indeksin – pidä hallussa luottamuksellisuus ja relevanssi.