Добавяне на документи към колекция
На тази страница
Обновено на 2 ноември 2026 г. Този урок отразява версия
xai-sdk1.21.0 и документацията на xAI: извикванията сawaitизискват асинхроннияAsyncClient, статусът на индексиране се сравнява с константатаcollections_pb2.DOCUMENT_STATUS_PROCESSED(а не със низ), а масовото зареждане използваupload_document, което комбинира двете стъпки в едно извикване. Източници: Колекции чрез API · xai-sdk-python.
Защо добавянето става на две стъпки
Може би очаквате да пуснете PDF файл директно в колекция, все едно влачите файл в папка. API на xAI не работи така: документът първо преминава през Files API, който го съхранява и присвоява file_id, а след това през Management API, който свързва този идентификатор с колекцията. Две извиквания, два ключа, две стъпки.
Това разделение има пряко и полезно следствие: файлът съществува само веднъж от страната на хранилището, но може да бъде свързан с толкова колекции, колкото е необходимо. Един и същ технически доклад може да захранва базата данни на екипа по продукта и тази на екипа за поддръжка, без да се качва два пъти, без да се консумира квота двойно и без риск от разминаване между две копия.
Стъпка 1: Качване на файла
Тук няма нищо ново; това е крайната точка, която усвоихте още от първия урок:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Извлечете file_id от отговора: това е ключът за следващата стъпка.
Стъпка 2: Прикачване към колекцията
Добавянето става чрез POST заявка към URL, който комбинира двата идентификатора – ID на колекцията и ID на файла – и не изисква тяло на заявката:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
След като това извикване бъде прието, xAI започва индексирането на съдържанието. Документът преминава през няколко състояния на обработка, преди да стане действително достъпен за търсене.
Изчакайте приключването на индексирането
Това е често срещана грешка в първия конвейер: заявката за добавяне връща успех, веднага правите последващо търсене и колекцията отговаря, че не намира нищо. Документът съществува, но все още не е индексиран. Статусът, който трябва да изчакате, е DOCUMENT_STATUS_PROCESSED, а SDK Ви позволява да го проверите правилно:
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"))
Закъснението зависи пряко от размера: PDF от няколко страници се индексира за няколко секунди, докато документ от 100 MB може да отнеме няколко минути. За през нощта зареждане този цикъл с пауза от три секунди е достатъчен; в интерфейс, където потребителят качва файл и чака, осигурете визуална обратна връзка, вместо замръзнал екран.
Премахване на документ, без да го губите
Премахването на файл от колекция е отделна операция от неговото изтриване:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Файлът изчезва от индекса на тази колекция, но остава достъпен чрез Files API и може да бъде свързан на друго място. Това е точно това, което трябва да направите, когато листовка с продукт остарее за поддръжката, но запазва архивната си стойност: премахвате я от оперативната база данни, без да унищожавате документа.
Попълване на колекция масово
Когато инициализирате база данни от цяла папка, напишете цикъла веднъж; той ще Ви служи дълго време:
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):
# Стъпки 1 и 2 в едно извикване: качване чрез Files API, след това прикачване
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"))
Забележете смесването на формати в списъка – PDF, Markdown и обикновен текст съществуват без проблем в една и съща колекция, което Ви спестява необходимостта да стандартизирате източниците си преди зареждането.
Два ключа, два обхвата
Този процес използва два идентификатора за достъп, които не бива да бъркате: стандартния API ключ (XAI_API_KEY) за качването в стъпка 1 и ключа за управление (XAI_MANAGEMENT_API_KEY) за прикачването в стъпка 2. SDK получава и двата при създаването на клиента, а upload_document ги използва един след друг. Уверете се, че последният има разрешението AddFileToCollection: без него качването Ви ще успее, добавянето ще се провали с грешка 403 и ще натрупате файлове, правилно съхранени, но липсващи във всяка колекция.
Ключови изводи
- Добавянето към колекция става на две стъпки: качване, след това добавяне
- Един файл може да принадлежи към множество колекции едновременно
- Документът трябва да достигне статус
DOCUMENT_STATUS_PROCESSED, преди да може да се търси - Премахването на документ от колекция не изтрива основния файл
- Необходими са два различни API ключа: стандартен за качване и за управление за колекцията