Przejdź do głównej treści
Polski— Wybierz język
Menu

Dodawanie dokumentów do kolekcji

Lekcja 6 z 16 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Dlaczego dodawanie odbywa się w dwóch krokach
  2. Krok 1: Przesłanie pliku
  3. Krok 2: Dołączenie do kolekcji
  4. Poczekaj na zakończenie indeksowania
  5. Usuwanie dokumentu bez jego utraty
  6. Masowe wypełnianie kolekcji
  7. Dwa klucze, dwa zakresy
  8. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 r. Lekcja odzwierciedla wersję xai-sdk 1.21.0 oraz dokumentację xAI: wywołania await wymagają asynchronicznego klienta AsyncClient, status indeksowania porównuje się ze stałą collections_pb2.DOCUMENT_STATUS_PROCESSED (a nie ciągiem znaków), a masowe przesyłanie danych korzysta z metody upload_document, która łączy oba kroki w jedno wywołanie. Źródła: Kolekcje przez API · xai-sdk-python.

Dlaczego dodawanie odbywa się w dwóch krokach

Możesz oczekiwać, że wrzucisz plik PDF bezpośrednio do kolekcji, tak jak przeciągasz plik do folderu. Tak jednak nie działa API xAI: dokument najpierw trafia do Files API, które go przechowuje i przydziela mu file_id, a następnie do Management API, które wiąże ten identyfikator z kolekcją. Dwa wywołania, dwa klucze, dwa kroki.

To rozdzielenie ma bezpośredni i użyteczny skutek: plik istnieje tylko raz po stronie magazynu, ale może być powiązany z dowolną liczbą kolekcji. Ten sam raport techniczny może zasilać bazę danych zespołu produktowego i zespołu wsparcia bez konieczności dwukrotnego przesyłania, bez podwójnego zużycia limitu i bez ryzyka rozbieżności między dwiema kopiami.

Krok 1: Przesłanie pliku

Nic nowego – to punkt końcowy, który opanowałeś już podczas pierwszej lekcji:

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

Pobierz file_id z odpowiedzi: to klucz do następnego kroku.

Krok 2: Dołączenie do kolekcji

Dodanie przyjmuje formę żądania POST na adres URL łączący dwa identyfikatory: ID kolekcji i ID pliku. Nie wymaga ono żadnego ciała żądania:

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

Gdy to wywołanie zostanie zaakceptowane, xAI rozpoczyna indeksowanie treści. Dokument przechodzi następnie przez kilka stanów przetwarzania, zanim będzie faktycznie dostępny do wyszukiwania.

Poczekaj na zakończenie indeksowania

To częsta pułapka w pierwszym etapie potoku: żądanie dodania zwraca sukces, natychmiast wykonujesz wyszukiwanie, a kolekcja odpowiada, że nic nie znalazła. Dokument istnieje, ale nie został jeszcze zaindeksowany. Status, na który musisz poczekać, to DOCUMENT_STATUS_PROCESSED, a SDK pozwala poprawnie odpytywać go w pętli:

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

Opóźnienie zależy bezpośrednio od rozmiaru: PDF liczący kilka stron zostanie zaindeksowany w ciągu kilku sekund, podczas gdy dokument o wielkości 100 MB może zająć kilka minut. Przy nocnym przesyłaniu danych ta pętla z trzusekundową przerwą wystarczy; w interfejsie, gdzie użytkownik przesyła plik i czeka, zapewnij informację zwrotną wizualną, zamiast zamrażać ekran.

Usuwanie dokumentu bez jego utraty

Odłączenie pliku od kolekcji to operacja odrębna od jego usunięcia:

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

Plik znika z indeksu tej kolekcji, ale pozostaje dostępny przez Files API i może zostać powiązany gdzie indziej. To dokładnie to, co powinieneś zrobić, gdy karta produktu staje się przestarzała dla wsparcia, zachowując jednocześnie swoją wartość archiwalną: usuwasz ją z bazy operacyjnej, nie niszcząc samego dokumentu.

Masowe wypełnianie kolekcji

Gdy inicjujesz bazę danych z całego folderu, napisz pętlę raz – posłuży Ci ona przez długi czas:

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):
        # Kroki 1 i 2 w jednym wywołaniu: przesłanie przez Files API, a następnie dołączenie
        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"))

Zauważ mieszankę formatów na liście – PDF, Markdown i zwykły tekst współistnieją bez problemu w tej samej kolekcji, co oszczędza Ci konieczności standaryzacji źródeł przed ingestią.

Dwa klucze, dwa zakresy

Proces ten wykorzystuje dwa identyfikatory dostępu, których nie należy mylić: standardowy klucz API (XAI_API_KEY) do przesyłania w kroku 1 oraz klucz Management (XAI_MANAGEMENT_API_KEY) do dołączania w kroku 2. SDK otrzymuje oba podczas tworzenia klienta, a metoda upload_document używa ich po kolei. Upewnij się, że ten drugi posiada uprawnienie AddFileToCollection: bez niego przesyłanie zakończy się sukcesem, ale dodanie zakończy się błędem 403, a Ty zgromadzisz pliki poprawnie przechowywane, ale nieobecne w żadnej kolekcji.

Kluczowe wnioski

  • Dodawanie do kolekcji odbywa się w dwóch krokach: najpierw przesłanie, potem dodanie
  • Plik może należeć jednocześnie do wielu kolekcji
  • Dokument musi osiągnąć status DOCUMENT_STATUS_PROCESSED, zanim będzie możliwy do wyszukania
  • Usunięcie dokumentu z kolekcji nie usuwa bazowego pliku
  • Wymagane są dwa różne klucze API: standardowy do przesyłania i Management do obsługi kolekcji