Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Dodavanje dokumenata u kolekciju

Lekcija 6 od 16 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Zašto se dodavanje odvija u dva koraka
  2. Korak 1: Učitavanje datoteke
  3. Korak 2: Pripajanje kolekciji
  4. Pričekaj završetak indeksiranja
  5. Uklanjanje dokumenta bez gubitka
  6. Masovno popunjavanje kolekcije
  7. Dva ključa, dva opsega
  8. Ključne točke

Ažurirano 2. studenoga 2026. Ova lekcija odražava verziju xai-sdk 1.21.0 i dokumentaciju xAI-ja: pozivi await zahtijevaju asinkroni AsyncClient, status indeksiranja uspoređuje se s konstantom collections_pb2.DOCUMENT_STATUS_PROCESSED (a ne s nizom znakova), a masovno učitavanje koristi upload_document, koji objedinjuje oba koraka u jedan poziv. Izvori: Kolekcije putem API-ja · xai-sdk-python.

Zašto se dodavanje odvija u dva koraka

Možda očekuješ da ćeš moći jednostavno ubaciti PDF izravno u kolekciju, kao da povlačiš datoteku u mapu. xAI API ne funkcionira tako: dokument prvo prolazi kroz Files API, koji ga pohranjuje i dodjeljuje mu file_id, a zatim kroz Management API, koji taj identifikator povezuje s kolekcijom. Dva poziva, dva ključa, dva koraka.

Ova odvojenost ima izravnu i korisnu posljedicu: datoteka postoji samo jednom na strani pohrane, ali se može povezati s onoliko kolekcija koliko je potrebno. Isto tehničko izvješće može napajati bazu podataka tima za proizvode i tima za podršku, a da se ne učitava dvaput, ne troši kvotu dvaput i ne riskira razilaženje između dviju kopija.

Korak 1: Učitavanje datoteke

Ovdje nema ničeg novog, ovo je krajnja točka koju si savladao još u prvoj lekciji:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "[email protected]" \
  -F "purpose=assistants"

Dohvati file_id iz odgovora: to je ključ za sljedeći korak.

Korak 2: Pripajanje kolekciji

Dodavanje ima oblik POST zahtjeva na URL koji kombinira dva identifikatora, ID kolekcije i ID datoteke, te ne zahtijeva tijelo zahtjeva:

curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Kada se ovaj poziv prihvati, xAI započinje indeksiranje sadržaja. Dokument zatim prolazi kroz nekoliko stanja obrade prije nego što postane dostupan za pretraživanje.

Pričekaj završetak indeksiranja

Ovo je česta zamka u prvom pipelineu: zahtjev za dodavanje vraća uspjeh, ti odmah nastaviš s pretraživanjem, a kolekcija odgovori da ništa ne pronalazi. Dokument postoji, ali još nije indeksiran. Status kojeg trebaš čekati je DOCUMENT_STATUS_PROCESSED, a SDK ti omogućuje ispravno ispitivanje (polling):

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"))

Kašnjenje izravno ovisi o veličini: PDF od nekoliko stranica indeksira se u nekoliko sekundi, dok dokument od 100 MB može potrajati nekoliko minuta. Za noćno učitavanje ova petlja s pauzom od tri sekunde dovoljna je; u sučelju gdje korisnik učitava datoteku i čeka, osiguraj vizualnu povratnu informaciju umjesto smrznutog zaslona.

Uklanjanje dokumenta bez gubitka

Odspajanje datoteke od kolekcije zasebna je operacija od njezinog brisanja:

curl -X DELETE \
  https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Datoteka nestaje iz indeksa ove kolekcije, ali ostaje dostupna putem Files API-ja i može se povezati drugdje. Točno je to ono što trebaš učiniti kada list s podacima o proizvodu postane zastario za podršku, a zadrži svoju arhivsku vrijednost: uklanjaš ga iz operativne baze podataka bez uništavanja samog dokumenta.

Masovno popunjavanje kolekcije

Kada inicijaliziraš bazu podataka iz cijele mape, napiši petlju jednom; dobro će ti služiti dugo vremena:

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):
        # Koraci 1 i 2 u jednom pozivu: učitavanje putem Files API-ja, zatim pripajanje
        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"))

Primijeti mješavinu formata na popisu – PDF, Markdown i običan tekst mogu nesmetano suživjeti u istoj kolekciji, što te štedi potrebe za standardizacijom izvora prije učitavanja.

Dva ključa, dva opsega

Ovaj proces koristi dva identifikatora pristupa koja ne smiješ zamijeniti: standardni API ključ (XAI_API_KEY) za učitavanje u koraku 1 i Management ključ (XAI_MANAGEMENT_API_KEY) za pripajanje u koraku 2. SDK prima oba pri stvaranju klijenta, a upload_document ih koristi jedan za drugim. Provjeri ima li potonji dopuštenje AddFileToCollection: bez njega će tvoje učitavanje uspjeti, ali će dodavanje failati s greškom 403, pa ćeš akumulirati datoteke koje su ispravno pohranjene, ali odsutne iz svake kolekcije.

Ključne točke

  • Dodavanje u kolekciju odvija se u dva koraka: učitavanje pa dodavanje
  • Datoteka može istovremeno pripadati više kolekcija
  • Dokument mora doseći status DOCUMENT_STATUS_PROCESSED prije nego što postane pretraživ
  • Uklanjanje dokumenta iz kolekcije ne briše temeljnu datoteku
  • Potrebna su dva različita API ključa: standardni za učitavanje, Management za kolekciju