Dodawanie dokumentów do kolekcji
Na tej stronie
Zaktualizowano 2 listopada 2026 r. Lekcja odzwierciedla wersję
xai-sdk1.21.0 oraz dokumentację xAI: wywołaniaawaitwymagają asynchronicznego klientaAsyncClient, 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 metodyupload_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