Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Is-SDK tal-Python ta' xAI: Operazzjonijiet Asinkroni

Lezzjoni 16 / 16 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Awtomatizza l-Flussi tax-Xogħol RAG tiegħek fil-Python
  2. Installazzjoni u Konfigurazzjoni
  3. Operazzjonijiet tal-Kollezzjoni
  4. Żid Dokument u Stenna l-Indiċjar
  5. Tfittxija mill-SDK
  6. Pipeline Sħiħa Minn Truf għal Truf
  7. Punti Ewlenin
  8. Ittestja l-Għarfien Tiegħek

Aġġornat fit-2 ta’ Novembru, 2026. Ibbażat fuq il-kodiċi xai-sdk 1.21.0 u l-eżempju uffiċjali ta’ xAI: is-sejħiet await jeħtieġu l-klijent asinkronu AsyncClient (il-Client huwa sinkronu), l-oġġetti rritornati jesponu collection_id, collections, matches, u chunk_content, l-istatus tal-indiċjar jitqabbel ma’ collections_pb2.DOCUMENT_STATUS_PROCESSED, u upload_document itella’ u jwaħħal il-fajl f’sejħa waħda (l-eżempju preċedenti kien itellgħu darbtejn, darba bl-użu ta’ metodu li ma jeżistix). Sorsi: Collections via the API · Collections Search · xai-sdk-python.

Awtomatizza l-Flussi tax-Xogħol RAG tiegħek fil-Python

Kollox li sejjaħt permezz ta’ curl matul dan il-kors jeżisti fil-Python: it-tlugħ ta’ dokumenti, il-ġestjoni tal-kollezzjonijiet, it-tfittxija, u l-ġenerazzjoni. L-SDK ta’ xAI joffri żewġ klijenti, wieħed sinkronu (Client) u ieħor asinkronu (AsyncClient), b’metodi identiċi. Dan tal-aħħar huwa l-għażla t-tajba għal fluss tax-xogħol RAG, li jqatta’ l-biċċa l-kbira tal-ħin jistenna—biex titlesta tlugħ, biex jiġi indiċjat dokument, jew biex tirritorna tfittxija. Il-kodiċi asinkronu jimmaniġġja dawn l-istenzi b’mod parallel minflok f’sekwenza.

Installazzjoni u Konfigurazzjoni

pip install xai-sdk

Il-klijent jeħtieġ żewġ ċwievet: iċ-ċavetta standard tal-API għat-tfittxija u l-ġenerazzjoni, u ċ-ċavetta tal-API tal-Ġestjoni għall-kollezzjonijiet.

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

Kull talba għandha limitu ta’ żmien (timeout) predefinit ta’ 27 minuta qabel ma tiskadi, li jkopri t-tlugħ ta’ PDF kbir. Il-parametru timeout, f’sekondi, jippermettilek tissikka dan il-limitu għal applikazzjoni interattiva.

Operazzjonijiet tal-Kollezzjoni

Tliet sejħiet ikopru ċ-ċiklu tal-ħajja kollu. Il-ħolqien jirritorna l-ID li se terġa’ tużah kullimkien ieħor:

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

Il-lista tgħin prinċipalment biex tirkupra ID li ma ħżintx, jew biex tiċċekkja l-istatus ta’ kont kondiviż bejn proġetti multipli:

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

It-tħassir huwa irreversibbli u jneħħi d-dokumenti u l-indiċi tagħhom:

await client.collections.delete(collection_id)

Żid Dokument u Stenna l-Indiċjar

Sejħa waħda, upload_document, itella’ l-fajl permezz tal-API tal-Fajls u jwaħħlu mal-kollezzjoni:

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

Jekk il-fajl diġà jeżisti fl-API tal-Fajls, add_existing_document(collection_id, file_id) iwaħħlu mingħajr ma jerġa’ jitella’.

Iż-żieda ta’ dokument ma tagħmilux disponibbli għall-mistoqsijiet immedjatament. L-indiċjar jieħu żmien varjabbli skont id-daqs tal-fajl, u tfittxija mnedija kmieni wisq sempliċiment tirritorna inqas riżultati milli mistenni—bug li huwa partikolarment doloruż biex tiddijanostika, peress li ma tqajjem l-ebda żball. Għalhekk dan iċ-ċiklu ta’ stennija, li jivverifika l-istatus sakemm jilħaq 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)

L-istatus huwa valwu ta’ enumerazzjoni, mhux stringa: li tqabblu mat-test "DOCUMENT_STATUS_PROCESSED" qatt ma jkun veru, u ċ-ċiklu jimxi għal dejjem. Għal każ sempliċi, upload_document(..., wait_for_indexing=True) jimmaniġġja din l-istennija għalik.

Tfittxija mill-SDK

It-tfittxija tirritorna l-istess biċċiet (chunks) b’punteġġi bħall-endpoint HTTP, fil-lista 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("---")

Pipeline Sħiħa Minn Truf għal Truf

Il-blokki preċedenti jingħaqdu f’script li joħloq il-kollezzjoni, itella’ d-dokumenti, jistenna l-indiċjar, ifittex, u mbagħad jiġġenera tweġiba bl-użu tal-għodda 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. Oħloq il-kollezzjoni
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Żid id-dokumenti b'mod parallel
    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. Stenna sakemm jiġu indiċjati d-dokumenti kollha
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Fittex
    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. Iġġenera tweġiba bbażata fuq il-kollezzjoni
    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())

Iż-żewġ sejħiet asyncio.gather() jagħmlu x-xogħol kollu. L-ewwel waħda tniedi t-tliet tligħat flimkien minflok ma tistenna li kull waħda tispiċċa; it-tieni waħda timmonitorja t-tliet kompiti ta’ indiċjar simultanjament: il-ħin totali jersaq lejn dak tad-dokument l-itwal, minflok is-somma ta’ kollha kemm huma. U peress li l-istennija ma timblokkax iċ-ċiklu tal-avvenimenti (event loop), l-istess kodiċi jidħol direttament f’applikazzjoni FastAPI jew aiohttp, li tkompli sservi talbiet oħra waqt li d-dokumenti tiegħek qed jiġu indiċjati.

Punti Ewlenin

  • L-SDK tal-Python ta’ xAI jeżisti f’verżjonijiet sinkroni (Client) u asinkroni (AsyncClient); await jeħtieġ dan tal-aħħar
  • Iż-żewġ ċwievet (API u Ġestjoni) jiġu kkonfigurati fil-klijent
  • upload_document itella’ u jwaħħal f’sejħa waħda; immonitorja l-indiċjar permezz ta’ get_document jew wait_for_indexing=True
  • asyncio.gather() jippermettilek itella’ u tistenna l-indiċjar b’mod parallel
  • Il-ġenerazzjoni tisfrutta l-kollezzjoni bl-għodda collections_search, kompluta b’tweġiba u ċitazzjonijiet

Ittestja l-Għarfien Tiegħek

Fajls, kollezzjonijiet, tfittxija: RAG immaniġġjat minn xAI.

1. X'tippermettilek tagħmel l-API tal-Fajls?

Tweġiba: Ittella’ u timmaniġġja fajls (lista, viżwalizzazzjoni, tħassir) f’formati appoġġjati—il-materja prima għall-kollezzjonijiet u l-mistoqsijiet b’dokumenti.

2. X'inhi kollezzjoni?

Tweġiba: Sett ta’ dokumenti ġestiti fuq is-server minn xAI, b’metadejta u permessi—l-indiċi lest għall-użu li tista’ tikkonsulta mingħajr ma tibni l-pipeline vettorjali tiegħek stess.

3. Liema modalitajiet ta' tfittxija huma disponibbli?

Tweġiba: Eżatta (kelmiet eżatti), semantika (tifsira), u ibrida (it-tnejn)—l-għażla ssegwi n-natura tal-mistoqsijiet, bl-ibrida tkopri l-biċċa l-kbira tal-każijiet.

4. Kif tintegra r-RAG mal-ġenerazzjoni?

Tweġiba: Permezz tal-għodda ta’ tfittxija tal-kollezzjoni: collections_search fl-SDK ta’ xAI, file_search b’IDs tal-kollezzjoni fl-API tar-Risposti. Il-mudell jikkonsulta d-dokumenti tiegħek waqt il-ġenerazzjoni u jiċċita s-sorsi tiegħu—il-mudell RAG mingħajr infrastruttura biex tinżamm.

5. Liema punti jeħtieġu attenzjoni għall-produzzjoni?

Tweġiba: Kunfidenzjalità tad-data mtellgħa (permessi, ċiklu tal-ħajja), rilevanza biex tiġi ottimizzata (metadejta, qsim f’biċċiet)—u l-SDK asinkronu għal ipproċessar ta’ volum għoli.

RAG Immaniġġjat: int iġġib id-dokumenti u l-mistoqsijiet, xAI jimmaniġġja l-indiċi—żomm il-kontroll tal-kunfidenzjalità u r-rilevanza.