Żid dokumenti ma' ġabra
F'din il-paġna
Aġġornat fit-2 ta’ Novembru 2026. Din il-lezzjoni tirrifletti l-verżjoni
xai-sdk1.21.0 u d-dokumentazzjoni ta’ xAI: is-sejħietawaitjeħtieġu l-AsyncClientasinkronu, l-istatus tal-indiċjar jitqabbel mal-kostanticollections_pb2.DOCUMENT_STATUS_PROCESSED(mhux stringa), u l-inġestjoni bl-ingrossa tużaupload_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_PROCESSEDqabel 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