Pridėti dokumentus į kolekciją
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. Ši pamoka atspindi
xai-sdk1.21.0 versiją ir xAI dokumentaciją:awaitkvietimai reikalauja asinchroninioAsyncClient, indeksavimo būsena lyginama su konstantacollections_pb2.DOCUMENT_STATUS_PROCESSED(ne su eilute), o masinis įkėlimas naudojaupload_document, kuris abu veiksmus sujungia į vieną kvietimą. Šaltiniai: Kolekcijos per API · xai-sdk-python.
Kodėl pridėjimas vyksta dviem etapais
Galbūt tikiesi, kad PDF failą galėsi tiesiog „įmesti“ į kolekciją tarsi į aplanką. xAI API veikia kitaip: pirmiausia dokumentas patenka į Files API, kuris jį saugo ir priskiria file_id, o tada į Management API, kuris šį identifikatorių susieja su kolekcija. Du kvietimai, du raktai, du žingsniai.
Šis atskyrimas turi tiesioginę ir naudingą pasekmę: failas saugykloje egzistuoja tik vieną kartą, tačiau gali būti susietas su tiek kolekcijų, kiek reikia. Tas pats techninis raportas gali maitinti tiek produktų komandos duomenų bazę, tiek palaikymo komandos bazę, nereikalaujant jo įkelti dukart, neeikvojant kvotos dukart ir nerizikuojant, kad atsiras skirtumų tarp dviejų kopijų.
1 žingsnis: įkelkite failą
Čia nieko naujo – tai galutinė taškas, kurį įvaldei jau nuo pirmosios pamokos:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Iš atsakymo gauk file_id: tai raktas kitam žingsniui.
2 žingsnis: pridėkite prie kolekcijos
Pridėjimas vykdomas siunčiant POST užklausą URL adresu, kuriame sujungiami abu identifikatoriai – kolekcijos ID ir failo ID – ir kūnas (body) nereikalingas:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Kai šis kvietimas priimamas, xAI pradeda turinio indeksavimą. Dokumentas pereina kelias apdorojimo būsenas, kol tampa prieinamas paieškai.
Palaukite, kol baigsis indeksavimas
Tai dažna klaida kuriant pirmąjį kanalą: pridėjimo užklausa grąžina sėkmę, tu iškart atlieki paiešką, o kolekcija atsako, kad nieko neranda. Dokumentas egzistuoja, bet dar nėra indeksuotas. Būsena, kurios reikia laukti, yra DOCUMENT_STATUS_PROCESSED, o SDK leidžia tai tinkamai tikrinti ciklu:
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"))
Delsa tiesiogiai priklauso nuo dydžio: kelių puslapių PDF indeksuojamas per kelias sekundes, o 100 MB dokumentui gali prireikti kelių minučių. Naktiniam įkėlimui šis ciklas su trijų sekundžių pauze pakanka; sąsajoje, kurioje vartotojas įkelia failą ir laukia, suteikite vizualinį grįžtamąjį ryšį, o ne rodykite užšalusį ekraną.
Pašalinkite dokumentą jo neprarandant
Failo atskyrimas nuo kolekcijos yra atskira operacija nuo jo ištrynimo:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Failas dingsta iš šios kolekcijos indekso, bet lieka prieinamas per Files API ir gali būti susietas kitur. Būtent tai turėtum daryti, kai produkto lapelis tampa nebeaktualus palaikymui, bet išlaiko savo archyvinę vertę: pašalini jį iš operacinės duomenų bazės nesunaikindamas paties dokumento.
Užpildykite kolekciją masiniu būdu
Inicializuojant duomenų bazę iš viso aplanko, ciklą parašykite vieną kartą – jis jums ilgai tarnaus:
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):
# 1 ir 2 žingsniai vienu kvietimu: įkėlimas per Files API, tada pridėjimas
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"))
Atkreipk dėmesį į formatų mišinį sąraše – PDF, Markdown ir paprastas tekstas toje pačioje kolekcijoje egzistuoja be jokių problemų, todėl tau nereikia standartizuoti šaltinių prieš įkėlimą.
Du raktai, dvi apimtys
Šis procesas naudoja du prieigos identifikatorius, kurių nereikėtų painioti: standartinį API raktą (XAI_API_KEY) 1 žingsnio įkėlimui ir valdymo raktą (XAI_MANAGEMENT_API_KEY) 2 žingsnio pridėjimui. SDK abu gauna kuriant klientą, o upload_document juos naudoja vieną po kito. Įsitikink, kad pastarasis turi AddFileToCollection leidimą: be jo įkėlimas pavyks, bet pridėjimas žlugs su 403 klaida, ir tu sukauptum failus, kurie yra tinkamai saugomi, bet nepriklauso jokiai kolekcijai.
Svarbiausi punktai
- Pridėjimas į kolekciją vyksta dviem etapais: pirmiausia įkėlimas, tada pridėjimas
- Failas vienu metu gali priklausyti kelioms kolekcijoms
- Prieš dokumentą tapant ieškomu, jis turi pasiekti
DOCUMENT_STATUS_PROCESSEDbūseną - Dokumento pašalinimas iš kolekcijos neištrina pagrindinio failo
- Reikalingi du skirtingi API raktai: standartinis įkėlimui ir valdymo raktas kolekcijai