Премини към основното съдържание
Български— Изберете език
Меню

Добавяне на документи към колекция

Урок 6 от 16 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Защо добавянето става на две стъпки
  2. Стъпка 1: Качване на файла
  3. Стъпка 2: Прикачване към колекцията
  4. Изчакайте приключването на индексирането
  5. Премахване на документ, без да го губите
  6. Попълване на колекция масово
  7. Два ключа, два обхвата
  8. Ключови изводи

Обновено на 2 ноември 2026 г. Този урок отразява версия xai-sdk 1.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 ключа: стандартен за качване и за управление за колекцията