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

Żid dokumenti ma' ġabra

Lezzjoni 6 / 16 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Għaliex iż-żieda sseħħ f’żewġ passi
  2. Pass 1: Ittella’ l-fajl
  3. Pass 2: Irbit mal-ġabra
  4. Stenna sakemm jitlesta l-indiċjar
  5. Neħħi dokument mingħajr ma titlefu
  6. Imla ġabra bl-ingrossa
  7. Żewġ ċwievet, żewġ ambitu
  8. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru 2026. Din il-lezzjoni tirrifletti l-verżjoni xai-sdk 1.21.0 u d-dokumentazzjoni ta’ xAI: is-sejħiet await jeħtieġu l-AsyncClient asinkronu, l-istatus tal-indiċjar jitqabbel mal-kostanti collections_pb2.DOCUMENT_STATUS_PROCESSED (mhux stringa), u l-inġestjoni bl-ingrossa tuża upload_document, li tgħaqqad iż-żewġ passi f’sejħa waħda. Sorsi: Ġabriet permezz tal-API · xai-sdk-python.

Għaliex iż-żieda sseħħ f’żewġ passi

Tista’ tistenna li tbaxxi fajl PDF direttament f’ġabra, bħalma tiġbed fajl f’folder. Mhux hekk taħdem l-API ta’ xAI: id-dokument l-ewwel jgħaddi mill-API tal-Fajls, li taħżnu u tassenjah file_id, imbagħad mill-API tal-Ġestjoni, li torbot dak l-identifikatur mal-ġabra. Żewġ sejħiet, żewġ ċwievet, żewġ passi.

Din is-separazzjoni għandha konsegwenza diretta u utli: il-fajl jeżisti darba biss fuq in-naħa tal-ħażna, iżda jista’ jiġi marbut ma’ kemm-il ġabra trid. L-istess rapport tekniku jista’ jħaddem il-bażi tad-data tat-tim tal-prodott u dik tat-tim tas-sapport mingħajr ma jittellgħu darbtejn, mingħajr ma jikkunsmaw il-kwota darbtejn, u mingħajr riskju ta’ diverġenza bejn żewġ kopji.

Pass 1: Ittella’ l-fajl

Xejn ġdid hawnhekk, dan huwa l-endpoint li tgħallimt tuża mill-ewwel lezzjoni:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
 -F "[email protected]" \
  -F "purpose=assistants"

Irrikupra l-file_id mir-rispons: din hija ċ-ċavetta għall-pass li jmiss.

Pass 2: Irbit mal-ġabra

Iż-żieda tieħu l-forma ta’ POST lejn URL li jgħaqqad iż-żewġ identifikaturi, l-ID tal-ġabra u l-ID tal-fajl, u ma teħtieġ l-ebda korp ta’ talba:

curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Ladarba din is-sejħa tiġi aċċettata, xAI tibbeda l-indiċjar tal-kontenut. Id-dokument imbagħad jgħaddi minn diversi stati ta’ pproċessar qabel ma jkun verament disponibbli għat-tfittxija.

Stenna sakemm jitlesta l-indiċjar

Dan huwa żball komuni fl-ewwel pipeline: it-talba ta’ żieda tirritorna suċċess, inti immedjatament tagħmel tfittxija, u l-ġabra tirrispondi li ma ssib xejn. Id-dokument jeżisti, iżda għadu ma ġiex indiċjat. L-istatus li għandek tistenna huwa DOCUMENT_STATUS_PROCESSED, u l-SDK jħallik tiċċekkjah kif suppost:

import asyncio
import os

from xai_sdk import AsyncClient
from xai_sdk.proto import collections_pb2

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)


async def wait_for_indexing(file_id, collection_id):
    doc = await client.collections.get_document(file_id, collection_id)
    while doc.status != collections_pb2.DOCUMENT_STATUS_PROCESSED:
        if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
            raise RuntimeError(f"Indexing failed: {doc.error_message}")
        await asyncio.sleep(3)
        doc = await client.collections.get_document(file_id, collection_id)
    print("Document indexed and ready for search")


asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))

Id-dipendenza tiddependi direttament mid-daqs: PDF ta’ ftit paġni jiġi indiċjat f’ftit sekondi, filwaqt li dokument ta’ 100 MB jista’ jieħu diversi minuti. Għall-inġestjoni matul il-lejl, dan iċ-ċiklu b’pażża ta’ tliet sekondi huwa biżżejjed; f’interfaċċa fejn l-utent jitella’ fajl u jistenna, ipprovdi feedback viżiv minflok skrin iffriżat.

Neħħi dokument mingħajr ma titlefu

Li tneħħi fajl minn ġabra hija operazzjoni separata milli tħassru:

curl -X DELETE \
  https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Il-fajl jisparixxi mill-indiċi ta’ din il-ġabra iżda jibqa’ disponibbli permezz tal-API tal-Fajls, u jista’ jiġi marbut f’post ieħor. Dan huwa eżattament dak li għandek tagħmel meta skeda tal-prodott issir obsoleta għas-sapport filwaqt li żżomm il-valur tal-arkivju tagħha: tneħħiha mill-bażi tad-data operattiva mingħajr ma teqred id-dokument.

Imla ġabra bl-ingrossa

Meta tinizjalizza bażi tad-data minn folder sħiħ, ikteb iċ-ċiklu darba; se jservik tajjeb għal żmien twil:

import asyncio
import os
from pathlib import Path

from xai_sdk import AsyncClient

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)

files = [
    "docs/guide-installation.pdf",
    "docs/reference-api.pdf",
    "docs/faq.md",
    "docs/changelog.txt",
]


async def populate(collection_id):
    for file_path in map(Path, files):
        # Passi 1 u 2 f'sejħa waħda: ittella' permezz tal-API tal-Fajls, imbagħad irbit
        await client.collections.upload_document(
            collection_id=collection_id,
            name=file_path.name,
            data=file_path.read_bytes(),
        )
        print(f"Added: {file_path}")


asyncio.run(populate("col_xyz789"))

Innota t-taħlita ta’ formati fil-lista—PDF, Markdown, u test sempliċi jikkoegżistu mingħajr problemi fl-istess ġabra, li tiffrankalek milli tistandardizza s-sorsi tiegħek qabel l-inġestjoni.

Żewġ ċwievet, żewġ ambitu

Dan il-proċess juża żewġ identifikaturi ta’ aċċess li m’għandekx tħawwad: iċ-ċavetta standard tal-API (XAI_API_KEY) għat-telliegħa tal-pass 1, u ċ-ċavetta tal-Ġestjoni (XAI_MANAGEMENT_API_KEY) għar-rabta tal-pass 2. L-SDK jirċievi t-tnejn waqt il-ħolqien tal-klijent, u upload_document tużahom wieħed wara l-ieħor. Ivvverifika li tal-aħħar għandha l-permess AddFileToCollection: mingħajru, it-telliegħa tiegħek tirnexxi, iżda ż-żieda tiegħek tonqos bi żball 403, u se takkumula fajls maħżuna korrettament iżda nieqsa minn kwalunkwe ġabra.

Punti Ewlenin

  • Iż-żieda f’ġabra sseħħ f’żewġ passi: telliegħa imbagħad żieda
  • Fajl jista’ jappartjeni għal ħafna ġabriet fl-istess ħin
  • Id-dokument irid jilħaq l-istatus DOCUMENT_STATUS_PROCESSED qabel ma jkun jista’ jiġi mfittex
  • Li tneħħi dokument minn ġabra ma tħassarx il-fajl sottostanti
  • Jeħtieġu żewġ ċwievet distinti tal-API: standard għat-telliegħa, u tal-Ġestjoni għall-ġabra