Adăugarea de documente într-o colecție
Pe această pagină
Actualizat pe 2 noiembrie 2026. Această lecție reflectă versiunea
xai-sdk1.21.0 și documentația xAI: apelurileawaitnecesită clientul asincronAsyncClient, starea de indexare se compară cu constantacollections_pb2.DOCUMENT_STATUS_PROCESSED(nu un șir de caractere), iar ingestia în masă utilizeazăupload_document, care combină ambii pași într-un singur apel. Surse: Colecții prin API · xai-sdk-python.
De ce adăugarea se face în doi pași
Ați putea crede că puteți plasa un PDF direct într-o colecție, la fel cum trageți un fișier într-un dosar. Însă API-ul xAI nu funcționează așa: documentul trece mai întâi prin API-ul Files, care îl stochează și îi atribuie un file_id, apoi prin API-ul de Management, care leagă acest identificator de colecție. Două apeluri, două chei, doi pași.
Această separare are o consecință directă și utilă: fișierul există o singură dată în stocare, dar poate fi legat de câte colecții este necesar. Același raport tehnic poate alimenta baza de date a echipei de produs și pe cea a echipei de suport fără a fi încărcat de două ori, fără a consuma cota de două ori și fără riscul divergenței între două copii.
Pasul 1: Încărcarea fișierului
Nimic nou aici, acesta este endpoint-ul pe care l-ați stăpânit încă de la prima lecție:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Recuperați file_id din răspuns: aceasta este cheia pentru pasul următor.
Pasul 2: Atașarea la colecție
Adăugarea ia forma unui POST către un URL care combină cei doi identificatori, ID-ul colecției și ID-ul fișierului, și nu necesită niciun corp al cererii:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Odată ce acest apel este acceptat, xAI începe indexarea conținutului. Documentul trece apoi prin mai multe stări de procesare înainte de a fi disponibil pentru căutare.
Așteptați finalizarea indexării
Aceasta este o capcană frecventă în primul pipeline: cererea de adăugare returnează succesul, urmați imediat cu o căutare, iar colecția răspunde că nu găsește nimic. Documentul există, dar nu este încă indexat. Starea pe care trebuie să o așteptați este DOCUMENT_STATUS_PROCESSED, iar SDK-ul vă permite să interogați acest status corect:
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"))
Durata depinde direct de dimensiune: un PDF de câteva pagini este indexat în câteva secunde, în timp ce un document de 100 MB poate dura câteva minute. Pentru ingestia nocturnă, această buclă cu o pauză de trei secunde este suficientă; într-o interfață unde utilizatorul încarcă un fișier și așteaptă, asigurați un feedback vizual în loc de un ecran blocat.
Eliminarea unui document fără a-l pierde
Detașarea unui fișier dintr-o colecție este o operațiune distinctă de ștergerea acestuia:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Fișierul dispare din indexul acestei colecții, dar rămâne disponibil prin API-ul Files și poate fi legat în altă parte. Acesta este exact lucrul pe care trebuie să îl faceți când o fișă de produs devine învechită pentru suport, păstrându-și totuși valoarea de arhivă: îl eliminați din baza de date operațională fără a distruge documentul.
Popularea unei colecții în masă
Când inițializați o bază de date dintr-un întreg dosar, scrieți bucla o singură dată; vă va fi de folos mult timp:
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):
# Pașii 1 și 2 într-un singur apel: încărcare prin API-ul Files, apoi atașare
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"))
Observați amestecul de formate din listă—PDF, Markdown și text simplu coexistă fără probleme în aceeași colecție, ceea ce vă scutește de standardizarea surselor înainte de ingestie.
Două chei, două domenii de aplicare
Acest proces utilizează doi identificatori de acces pe care nu trebuie să îi confundați: cheia API standard (XAI_API_KEY) pentru încărcarea din pasul 1 și cheia de Management (XAI_MANAGEMENT_API_KEY) pentru atașarea din pasul 2. SDK-ul primește ambele chei la crearea clientului, iar upload_document le utilizează una după alta. Verificați dacă aceasta din urmă are permisiunea AddFileToCollection: fără ea, încărcarea va reuși, dar adăugarea va eșua cu o eroare 403, iar dumneavoastră veți acumula fișiere stocate corect, dar absente din orice colecție.
Puncte cheie
- Adăugarea într-o colecție se face în doi pași: încărcare, apoi adăugare
- Un fișier poate aparține mai multor colecții simultan
- Documentul trebuie să atingă starea
DOCUMENT_STATUS_PROCESSEDînainte de a fi căutabil - Eliminarea unui document dintr-o colecție nu șterge fișierul subiacent
- Sunt necesare două chei API distincte: standard pentru încărcare, Management pentru colecție