Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Pievienot dokumentus kolekcijai

Nodarbība 6 no 16 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Kāpēc pievienošana notiek divos soļos
  2. 1. solis: Augšupielādē failu
  3. 2. solis: Pievieno kolekcijai
  4. Pagaidi, līdz indeksēšana ir pabeigta
  5. Noņem dokumentu, to nezaudējot
  6. Aizpildi kolekciju masveidā
  7. Divas atslēgas, divas darbības jomas
  8. Galvenās atziņas

Atjaunināts 2026. gada 2. novembrī. Šī nodarbība atspoguļo xai-sdk 1.21.0 un xAI dokumentāciju: await izsaukumiem ir nepieciešams asinhronais AsyncClient, indeksēšanas statuss tiek salīdzināts ar konstanti collections_pb2.DOCUMENT_STATUS_PROCESSED (nevis virkni), un masveida ielādei tiek izmantots upload_document, kas apvieno abus soļus vienā izsaukumā. Avoti: Kolekcijas, izmantojot API · xai-sdk-python.

Kāpēc pievienošana notiek divos soļos

Tu varētu gaidīt, ka PDF failu var vienkārši ievietot kolekcijā, it kā vilktu failu mapē. xAI API strādā citādāk: dokuments vispirms nonāk Files API, kas to saglabā un piešķir tam file_id, un pēc tam Management API, kas saista šo identifikatoru ar kolekciju. Divi izsaukumi, divas atslēgas, divi soļi.

Šim nodalījumam ir tiešas un noderīgas sekas: fails krātuvē eksistē tikai vienreiz, bet to var saistīt ar tik daudz kolekcijām, cik nepieciešams. Viens un tas pats tehniskais ziņojums var barot gan produktu komandas datubāzi, gan atbalsta komandas datubāzi, netiekot augšupielādēts divreiz, neizlietojot kvotu divreiz un neradot risku atšķirībām starp divām kopijām.

1. solis: Augšupielādē failu

Šeit nav nekā jauna; šis ir galapunkts, ko esi apguvis jau pirmajā nodarbībā:

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

Iegūsti file_id no atbildes: tā ir atslēga nākamajam solim.

2. solis: Pievieno kolekcijai

Pievienošana notiek, veicot POST pieprasījumu URL adresē, kas apvieno abus identifikatorus – kolekcijas ID un faila ID – un tai nav nepieciešams pieprasījuma ķermenis:

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

Tiklīdz šis izsaukums ir akceptēts, xAI sāk satura indeksēšanu. Dokuments pēc tam iziet cauri vairākiem apstrādes stāvokļiem, pirms tas faktiski kļūst pieejams meklēšanai.

Pagaidi, līdz indeksēšana ir pabeigta

Šī ir izplatīta kļūda pirmajā darbplūsmā: pievienošanas pieprasījums atgriež veiksmi, tu uzreiz veic meklēšanu, un kolekcija atbild, ka neko neatrod. Dokuments eksistē, bet vēl nav indeksēts. Statuss, uz kuru jāgaida, ir DOCUMENT_STATUS_PROCESSED, un SDK ļauj to pareizi aptaujāt:

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

Aizkave ir tieši atkarīga no lieluma: dažu lappušu PDF tiek indeksēts dažās sekundēs, savukārt 100 MB dokuments var prasīt vairākas minūtes. Nakts ielādei šis cikls ar trīs sekunžu pauzi ir pietiekams; saskarnē, kur lietotājs augšupielādē failu un gaida, nodroši vizuālu atgriezenisko saiti, nevis sasalušu ekrānu.

Noņem dokumentu, to nezaudējot

Faila atsaistīšana no kolekcijas ir atsevišķa operācija no tā dzēšanas:

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

Fails pazūd no šīs kolekcijas indeksa, bet paliek pieejams, izmantojot Files API, un to var saistīt citur. Tieši tā tev jārīkojas, kad produkta lapa kļūst novecojusi atbalsta vajadzībām, bet saglabā savu arhīva vērtību: tu to noņem no operatīvās datubāzes, neiznīcinot dokumentu.

Aizpildi kolekciju masveidā

Inicializējot datubāzi no veselas mapes, uzraksti ciklu vienreiz; tas tev kalpos ilgi:

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. un 2. solis vienā izsaukumā: augšupielāde, izmantojot Files API, tad pievienošana
        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"))

Ievēro formatu sajaukumu sarakstā – PDF, Markdown un vienkāršs teksts līdzās pastāv vienā kolekcijā bez problēmām, kas ietaupa tevi no avotu standartizēšanas pirms ielādes.

Divas atslēgas, divas darbības jomas

Šis process izmanto divus piekļuves identifikatorus, kurus nedrīkst jaukt: standarta API atslēgu (XAI_API_KEY) 1. soļa augšupielādei un Management atslēgu (XAI_MANAGEMENT_API_KEY) 2. soļa pievienošanai. SDK saņem abas klienta izveides brīdī, un upload_document tās izmanto vienu pēc otras. Pārliecinies, ka pēdējai ir AddFileToCollection atļauja: bez tās augšupielāde būs veiksmīga, bet pievienošana neizdosies ar 403 kļūdu, un tu uzkrāsi failus, kas ir pareizi saglabāti, bet nav nevienā kolekcijā.

Galvenās atziņas

  • Pievienošana kolekcijai notiek divos soļos: vispirms augšupielāde, tad pievienošana
  • Viens fails var vienlaicīgi piederēt vairākām kolekcijām
  • Dokumentam ir jāsasniedz statuss DOCUMENT_STATUS_PROCESSED, pirms to var meklēt
  • Dokumenta noņemšana no kolekcijas nedzēš pamatā esošo failu
  • Nepieciešamas divas dažādas API atslēgas: standarta augšupielādei un Management kolekcijai