Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

An xAI Python SDK: Oibríochtaí Asincronacha

Ceacht 16 as 16 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Do Shreabha Oibre RAG a Uathoibriú i bPython
  2. Suiteáil agus Cumraíocht
  3. Oibríochtaí Bailiúcháin
  4. Doiciméad a Chur leis agus Fanacht le hInnéacsú
  5. Cuardach ón SDK
  6. Píblíne Iomlán ó Thús go Deireadh
  7. Príomhphointí
  8. Do Chuid Eolais a Thástáil

Nuashonraithe an 2 Samhain, 2026. Bunaithe ar chód xai-sdk 1.21.0 agus ar shampla oifigiúil xAI: éilíonn glaonna await an cliant asincronach AsyncClient (tá an Client sioncronach), nochtann na hoibiachtaí a thuirlingítear collection_id, collections, matches, agus chunk_content, déanann stádas innéacsaithe comparáid le collections_pb2.DOCUMENT_STATUS_PROCESSED, agus uaslódálann upload_document an comhad agus ceanglaíonn sé é i nglaon amháin (d’uaslódáil an sampla roimhe seo dhá uair é, ag baint úsáide as modh nach raibh ann). Foinse: Collections via the API · Collections Search · xai-sdk-python.

Do Shreabha Oibre RAG a Uathoibriú i bPython

Tá gach rud a d’úsáid tú le curl ar fud an chúrsa seo ar fáil i bPython: uaslódáil doiciméad, bainistiú bailiúcháin, cuardach, giniúint. Tairgeann xAI SDK dhá chliant, ceann sioncronach (Client) agus ceann asincronach (AsyncClient), le modhanna comhionanna. Is é an ceann deireanach an rogha cheart do shreabha oibre RAG, a chaitheann an chuid is mó den am ag fanacht—ar uaslódáil le críochnú, ar dhoiciméad le hinnéacsú, ar chuardach le freagra a thabhairt. Déileálann cód asincronach leis na fanachtanna seo go comhthreomhar seachas go seicheamhach.

Suiteáil agus Cumraíocht

pip install xai-sdk

Éilíonn an cliant dhá eochair: an eochair API caighdeánach le haghaidh cuardaigh agus giniúna, agus an eochair API Bainistíochta le haghaidh bailiúcháin.

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

Tá teorainn ama réamhshocraithe 27 nóiméad ag gach iarracht sula dtagann sí in éag, rud a chlúdaíonn PDF mór a uaslódáil. Ligeann an paraiméadar timeout, i soicindí, duit an teorainn seo a dhéanamh níos doichte d’fheidhmchlár idirghníomhach.

Oibríochtaí Bailiúcháin

Clúdaíonn trí ghlao an timthriall saoil iomlán. Filleann an chruthú an ID a athúsáidfidh tú i ngach áit eile:

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

Is é is príomhchuspóir don liostú ná ID nach ndearna tú buanú a fháil ar ais, nó stádas cuntais a roinntear ar fud tionscadal iolracha a sheiceáil:

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

Tá an scriosadh dochúlaithe agus baineann sé na doiciméid agus a n-innéacsanna:

await client.collections.delete(collection_id)

Doiciméad a Chur leis agus Fanacht le hInnéacsú

Uaslódálann glaon amháin, upload_document, an comhad tríd an API Comhad agus ceanglaíonn sé leis an mbailiúchán é:

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

Má tá an comhad ann cheana féin san API Comhad, ceanglaíonn add_existing_document(collection_id, file_id) é gan é a uaslódáil arís.

Ní dhéanann doiciméad a chur leis in-iniúchta láithreach é. Tógann innéacsú am athraitheach ag brath ar mhéid an chomhaid, agus fillfidh cuardach a sheoltar ró-luath níos lú torthaí ná mar a bhíothas ag súil leis—fabht atá thar a bheith pianmhar le diagnóisiú, ós rud é nach n-ardaíonn sé aon earráid. Mar sin, seo an lúb fanachta seo, a dhéanann polaithe ar an stádas go dtí go mbaintear DOCUMENT_STATUS_PROCESSED amach:

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)

Is luach áirithe é an stádas, ní teaghrán: dá ndéanfá comparáid idir é agus an téacs "DOCUMENT_STATUS_PROCESSED" ní bheadh sé fíor riamh, agus rithfeadh an lúb go deo. I gcás simplí, déileálann upload_document(..., wait_for_indexing=True) leis an bhfanacht seo duit.

Cuardach ón SDK

Filleann an cuardach na píosaí scórálthe céanna leis an bpointe deiridh HTTP, sa liosta 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("---")

Píblíne Iomlán ó Thús go Deireadh

Tagann na blocanna roimhe seo le chéile i script a chruthaíonn an bailiúchán, a uaslódálann doiciméid, a fhanann le hinnéacsú, a dhéanann cuardach, agus ansin a ghineann freagra ag baint úsáide as an uirlis 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. Cruthaigh an bailiúchán
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Cuir doiciméid leis go comhthreomhar
    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. Fan go ndéanfar innéacsú ar gach doiciméad
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Cuardach
    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. Gine freagra bunaithe ar an mbailiúchán
    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())

Déanann an dá ghlao asyncio.gather() an obair go léir. Seolann an chéad cheann na trí uaslódáil le chéile in ionad fanacht le gach ceann acu críochnú; déanann an dara ceann monatóireacht ar na trí phost innéacsaithe go comhuaineach: téann an t-am iomlán i dtreo am an doiciméid is faide, seachas suim na ndoiciméad go léir. Agus ós rud é nach mbacann an fanacht an lúb imeachta, oireann an cód céanna go díreach d’fheidhmchlár FastAPI nó aiohttp, a leanann ar aghaidh ag freastal ar iarratais eile agus do chuid doiciméad á n-innéacsú.

Príomhphointí

  • Tá xAI Python SDK ar fáil i leaganacha sioncronacha (Client) agus asincronacha (AsyncClient); éilíonn await an ceann deireanach
  • Cumraítear an dá eochair (API agus Bainistíochta) sa chliant
  • Uaslódálann upload_document agus ceanglaíonn sé i nglaon amháin; déan monatóireacht ar innéacsú trí get_document nó wait_for_indexing=True
  • Ligeann asyncio.gather() duit uaslódáil agus fanacht le hinnéacsú a dhéanamh go comhthreomhar
  • Baineann an ghiniúint úsáid as an mbailiúchán leis an uirlis collections_search, le freagra agus luachana san áireamh

Do Chuid Eolais a Thástáil

Comhaid, bailiúcháin, cuardach: RAG arna bhainistiú ag xAI.

1. Cad a ligeann an API Comhad duit a dhéanamh?

Freagra: Comhaid a uaslódáil agus a bhainistiú (liostú, amharc, scriosadh) i bhformáidí tacaithe—amhábhar le haghaidh bailiúcháin agus ceisteanna le doiciméid.

2. Cad é bailiúchán?

Freagra: Tacar doiciméad arna mbainistiú ar an bhfreastalaí ag xAI, le meiteashonraí agus ceadanna—an t-innéacs réidh le húsáid a dhéanann tú ceist air gan do phíblíne veicteoir féin a thógáil.

3. Cén cineálacha cuardaigh atá ar fáil?

Freagra: Eochairfhocal (téarmaí cruinne), seimeantach (brí), agus hibrideach (an dá cheann)—leanann an rogha nádúr na gceisteanna, agus clúdaíonn an modh hibrideach an chuid is mó de na cásanna.

4. Conas a chomhtháthaítear RAG le giniúint?

Freagra: Tríd an uirlis cuardaigh bailiúcháin: collections_search in xAI SDK, file_search le IDanna bailiúcháin san API Freagraí. Déanann an tsamhail ceist ar do dhoiciméid le linn na giniúna agus luaíonn sí a foinse—an patrún RAG gan bonneagar le cothabháil.

5. Cén pointe a éilíonn aird le haghaidh táirgeachta?

Freagra: Rúndacht na sonraí a uaslódáladh (ceadanna, timthriall saoil), ábharthacht le barrfheabhsú (meiteashonraí, píosaí)—agus an SDK asincronach le haghaidh próiseála ardtoirte.

RAG bainistithe: tugann tusa na doiciméid agus na ceisteanna, déileálann xAI leis an innéacs—coinnigh smacht ar rúndacht agus ar ábharthacht.