Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Končna točka za iskanje dokumentov

Lekcija 9 od 16 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Poizvedovanje po svojih bazah znanja
  2. Struktura zahteve
  3. Branje odgovora
  4. Iskanje po več zbirkah
  5. Stroški
  6. Ključne ugotovitve

Poizvedovanje po svojih bazah znanja

Do zdaj si zgradil vsebnik: zbirke, indeksirane dokumente, metapodatke. Vse to je brez pomena, če ne veš, kako zastaviti vprašanje. To je naloga končne točke POST /v1/documents/search, ki sprejme poizvedbo v naravnem jeziku in vrne odlomke iz tvojih dokumentov, ki nanjo najbolje odgovorijo. Predstavljaj si ekipo za podporo, ki prejme vprašanje: „Kakšen je odpovedni rok?” Namesto da bi agent prebral splošne pogoje, vprašanje pošlješ končni točki in pridobiš tri uporabne odstavke, skupaj z njihovo oceno in virom.

POST
/v1/documents/search
3 načini
ključne besede, semantično, hibridno
$2.50
Na 1.000 klicev
Več
Več zbirk

Struktura zahteve

Prva stvar, ki si jo moraš zapomniti in ki je pogost vir napak: ta končna točka deluje na standardnem API-ju (api.x.ai), ne na upravljalnem API-ju, ki si ga uporabljal za ustvarjanje zbirk. Avtentikacijo opraviš s svojim običajnim ključem API. Minimalni zahtevek obsega tri polja.

curl -X POST https://api.x.ai/v1/documents/search \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I configure OAuth authentication?",
    "source": {
      "collection_ids": ["col_xyz789"]
    },
    "retrieval_mode": {
      "type": "hybrid"
    }
  }'

Glavni parametri

  • query: tvoje vprašanje v naravnem jeziku. Bolj specifično kot je vprašanje, bolj relevantni so rezultati.
  • source.collection_ids: polje ID-jev zbirk, po katerih želiš iskati. V enem zahtevku lahko iščeš po več zbirkah hkrati.
  • retrieval_mode.type: način iskanja, ki ga želiš uporabiti (keyword, semantic ali hybrid).

Branje odgovora

API ne vrne celotnih dokumentov, temveč fragmente – dele, ustvarjene med indeksiranjem – razvrščene od najbolj do najmanj relevantnih.

{
  "results": [
    {
      "content": "To configure OAuth, start by...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "security-guide.pdf",
        "page": 12
      }
    },
    {
      "content": "The OAuth 2.0 flow uses...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "api-reference.pdf",
        "page": 45
      }
    }
  ]
}

Vsak vnos vsebuje štiri informacije:

  • content: besedilni izsek iz dokumenta
  • score: ocena relevantnosti med 0 in 1
  • document_id: ID izvorne datoteke
  • metadata: metapodatki dokumenta (ime, stran, polja po meri)

V zgornjem primeru prvi izsek izvira s 12. strani datoteke security-guide.pdf z oceno 0,92, drugi pa s 45. strani druge datoteke z oceno 0,87. Ti dve vrednosti zadostujeta za izgradnjo vmesnika, ki prikaže odgovor in tik pod njim povezavo „ogled izvirnega odlomka, stran 12”. Ocena deluje kot prag: številne ekipe zavrnejo vsak rezultat pod 0,5, namesto da bi modelu dovolile razmišljati na podlagi šuma.

Iskanje po več zbirkah

Če je collection_ids polje, to ni naključje. Vprašanje stranke pogosto združuje več svetov dokumentov, ti pa nočeš opraviti treh klicev in nato ročno združiti rezultatov.

{
  "query": "Refund policy",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Tukaj se hkrati poizveduje po dokumentaciji izdelka, pogostih vprašanjih (FAQ) in splošnih pogojih. Rezultati se vrnejo združeni in razvrščeni po oceni, ne glede na njihovo izvorno zbirko: odlomek iz FAQ z oceno 0,94 bo višje od odlomka iz splošnih pogojev z oceno 0,71. Heterogene vire prečkaš v enem samem omrežnem krogu.

Stroški

Iskanje po zbirkah stane 2,50 USD na 1.000 klicev, ta stopnja pa se ne spreminja glede na število poizvedovanih zbirk ali velikost indeksiranih dokumentov. Primerjaj to s prilogami datotek, torej posameznimi datotekami, poslanimi prek input_file, ki se zaračunavajo po 10 USD na 1.000 klicev: takoj ko večkrat poizveduješ po istih dokumentih, so zbirke štirikrat cenejše. Interni asistent, ki obdela 20.000 vprašanj na mesec, s zbirkami stane 50 USD, s prilogami pa 200 USD – poleg tega pa dobiš hitrejše rezultate, saj indeks že obstaja.

Cenik z dne 5. avgusta 2026 – cene se redno spreminjajo: pred vsakim izračunom proračuna preveri trenutni cenik na uradni strani modelov in cen xAI.

Ključne ugotovitve

  • Končna točka POST /v1/documents/search omogoča poizvedovanje po tvojih zbirkah v naravnem jeziku
  • Na voljo so trije načini iskanja: ključne besede, semantično, hibridno
  • Iščete lahko hkrati po več zbirkah
  • Rezultati so razvrščeni po oceni relevantnosti z vsebino vira
  • Strošek znaša 2,50 USD na 1.000 klicev, kar je štirikrat ceneje kot pri prilogah datotek