Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

xAI Python SDK: Asynkroniset toiminnot

Oppitunti 16 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Automatisoi RAG-työnkulut Pythonilla
  2. Asennus ja konfigurointi
  3. Kokoelmaoperaatiot
  4. Dokumentin lisääminen ja indeksoinnin odottaminen
  5. Haku SDK:n kautta
  6. Täydellinen end-to-end -putki
  7. Keskeiset asiat
  8. Testaa tietosi

Päivitetty 2. marraskuuta 2026. Perustuu xai-sdk 1.21.0 -koodiin ja viralliseen xAI-esimerkkiin: await-kutsut vaativat asynkronisen asiakkaan AsyncClient (kun taas Client on synkroninen), palautetut oliot tarjoavat attribuutit collection_id, collections, matches ja chunk_content, indeksointitilaa verrataan arvoon collections_pb2.DOCUMENT_STATUS_PROCESSED, ja upload_document lataa 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; await vaatii jälkimmäistä
  • Molemmat avaimet (API ja Management) määritetään asiakasoliossa
  • upload_document lataa ja liittää yhdellä kutsulla; seuraa indeksointia metodilla get_document tai parametrilla wait_for_indexing=True
  • asyncio.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.