Salt la conținutul principal
Română— Alege o limbă
Meniu

Adăugarea de documente într-o colecție

Lecția 6 din 16 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De ce adăugarea se face în doi pași
  2. Pasul 1: Încărcarea fișierului
  3. Pasul 2: Atașarea la colecție
  4. Așteptați finalizarea indexării
  5. Eliminarea unui document fără a-l pierde
  6. Popularea unei colecții în masă
  7. Două chei, două domenii de aplicare
  8. Puncte cheie

Actualizat pe 2 noiembrie 2026. Această lecție reflectă versiunea xai-sdk 1.21.0 și documentația xAI: apelurile await necesită clientul asincron AsyncClient, starea de indexare se compară cu constanta collections_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