Pievienot dokumentus kolekcijai
Šajā lapā
Atjaunināts 2026. gada 2. novembrī. Šī nodarbība atspoguļo
xai-sdk1.21.0 un xAI dokumentāciju:awaitizsaukumiem ir nepieciešams asinhronaisAsyncClient, indeksēšanas statuss tiek salīdzināts ar konstanticollections_pb2.DOCUMENT_STATUS_PROCESSED(nevis virkni), un masveida ielādei tiek izmantotsupload_document, kas apvieno abus soļus vienā izsaukumā. Avoti: Kolekcijas, izmantojot API · xai-sdk-python.
Kāpēc pievienošana notiek divos soļos
Tu varētu gaidīt, ka PDF failu var vienkārši ievietot kolekcijā, it kā vilktu failu mapē. xAI API strādā citādāk: dokuments vispirms nonāk Files API, kas to saglabā un piešķir tam file_id, un pēc tam Management API, kas saista šo identifikatoru ar kolekciju. Divi izsaukumi, divas atslēgas, divi soļi.
Šim nodalījumam ir tiešas un noderīgas sekas: fails krātuvē eksistē tikai vienreiz, bet to var saistīt ar tik daudz kolekcijām, cik nepieciešams. Viens un tas pats tehniskais ziņojums var barot gan produktu komandas datubāzi, gan atbalsta komandas datubāzi, netiekot augšupielādēts divreiz, neizlietojot kvotu divreiz un neradot risku atšķirībām starp divām kopijām.
1. solis: Augšupielādē failu
Šeit nav nekā jauna; šis ir galapunkts, ko esi apguvis jau pirmajā nodarbībā:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Iegūsti file_id no atbildes: tā ir atslēga nākamajam solim.
2. solis: Pievieno kolekcijai
Pievienošana notiek, veicot POST pieprasījumu URL adresē, kas apvieno abus identifikatorus – kolekcijas ID un faila ID – un tai nav nepieciešams pieprasījuma ķermenis:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Tiklīdz šis izsaukums ir akceptēts, xAI sāk satura indeksēšanu. Dokuments pēc tam iziet cauri vairākiem apstrādes stāvokļiem, pirms tas faktiski kļūst pieejams meklēšanai.
Pagaidi, līdz indeksēšana ir pabeigta
Šī ir izplatīta kļūda pirmajā darbplūsmā: pievienošanas pieprasījums atgriež veiksmi, tu uzreiz veic meklēšanu, un kolekcija atbild, ka neko neatrod. Dokuments eksistē, bet vēl nav indeksēts. Statuss, uz kuru jāgaida, ir DOCUMENT_STATUS_PROCESSED, un SDK ļauj to pareizi aptaujāt:
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"))
Aizkave ir tieši atkarīga no lieluma: dažu lappušu PDF tiek indeksēts dažās sekundēs, savukārt 100 MB dokuments var prasīt vairākas minūtes. Nakts ielādei šis cikls ar trīs sekunžu pauzi ir pietiekams; saskarnē, kur lietotājs augšupielādē failu un gaida, nodroši vizuālu atgriezenisko saiti, nevis sasalušu ekrānu.
Noņem dokumentu, to nezaudējot
Faila atsaistīšana no kolekcijas ir atsevišķa operācija no tā dzēšanas:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Fails pazūd no šīs kolekcijas indeksa, bet paliek pieejams, izmantojot Files API, un to var saistīt citur. Tieši tā tev jārīkojas, kad produkta lapa kļūst novecojusi atbalsta vajadzībām, bet saglabā savu arhīva vērtību: tu to noņem no operatīvās datubāzes, neiznīcinot dokumentu.
Aizpildi kolekciju masveidā
Inicializējot datubāzi no veselas mapes, uzraksti ciklu vienreiz; tas tev kalpos ilgi:
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. un 2. solis vienā izsaukumā: augšupielāde, izmantojot Files API, tad pievienošana
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"))
Ievēro formatu sajaukumu sarakstā – PDF, Markdown un vienkāršs teksts līdzās pastāv vienā kolekcijā bez problēmām, kas ietaupa tevi no avotu standartizēšanas pirms ielādes.
Divas atslēgas, divas darbības jomas
Šis process izmanto divus piekļuves identifikatorus, kurus nedrīkst jaukt: standarta API atslēgu (XAI_API_KEY) 1. soļa augšupielādei un Management atslēgu (XAI_MANAGEMENT_API_KEY) 2. soļa pievienošanai. SDK saņem abas klienta izveides brīdī, un upload_document tās izmanto vienu pēc otras. Pārliecinies, ka pēdējai ir AddFileToCollection atļauja: bez tās augšupielāde būs veiksmīga, bet pievienošana neizdosies ar 403 kļūdu, un tu uzkrāsi failus, kas ir pareizi saglabāti, bet nav nevienā kolekcijā.
Galvenās atziņas
- Pievienošana kolekcijai notiek divos soļos: vispirms augšupielāde, tad pievienošana
- Viens fails var vienlaicīgi piederēt vairākām kolekcijām
- Dokumentam ir jāsasniedz statuss
DOCUMENT_STATUS_PROCESSED, pirms to var meklēt - Dokumenta noņemšana no kolekcijas nedzēš pamatā esošo failu
- Nepieciešamas divas dažādas API atslēgas: standarta augšupielādei un Management kolekcijai