Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Dokumentide otsimise lõpp-punkt

Õppetund 9 / 16 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Oma teadmiste baaside päringutamine
  2. Päringu struktuur
  3. Vastuse lugemine
  4. Otsing mitmes kollektsioonis
  5. Hind
  6. Peamised punktid

Oma teadmiste baaside päringutamine

Seni oled ehitanud konteineri: kollektsioonid, indekseeritud dokumendid, metaandmed. Sellel kõigel pole mõtet, kui sa ei tea, kuidas küsimust esitada. Selle eest hoolitseb POST /v1/documents/search, mis võtab vastu loomulikus keeles küsimuse ja tagastab sinu dokumentidest lõigud, mis sellele kõige paremini vastavad. Kujuta ette tugimeeskonda, kes saab küsimuse: „Mis on taganemistähtaeg?“ Selle asemel, et panna agent tingimusi lugema, saadad küsimuse lõpp-punkti ja tood välja kolm kasulikku lõiku koos nende skoori ja allikaga.

POST
/v1/documents/search
3 režiimi
märksõna, semantiline, hübriid
$2.50
1000 päringu kohta
Multi
Mitu kollektsiooni

Päringu struktuur

Esimene asi, mida meeles pidada – ja see on sagedane vigade allikas: see lõpp-punkt asub standardses API-s (api.x.ai), mitte haldus-API-s, mida kasutasid kollektsioonide loomiseks. Autenditud oma tavalise API-võtmega. Minimaalne päring taandub kolmele väljale.

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"
    }
  }'

Peamised parameetrid

  • query: sinu küsimus loomulikus keeles. Mida spetsiifilisem on küsimus, seda asjakohasemad on tulemused.
  • source.collection_ids: kollektsioonide ID-de massiiv, mida pärida. Saad otsida mitmest kollektsioonist ühe päringuga.
  • retrieval_mode.type: kasutatav otsingurežiim (keyword, semantic või hybrid).

Vastuse lugemine

API ei tagasta terviklikke dokumente, vaid fragmente – indekseerimise käigus loodud tükke, järjestatuna kõige asjakohasemast vähem asjakohemani.

{
  "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
      }
    }
  ]
}

Iga kirje sisaldab nelja teabekildu:

  • content: tekstilõik dokumendist.
  • score: asjakohasuse skoor vahemikus 0 kuni 1.
  • document_id: lähtefaili ID.
  • metadata: dokumendi metaandmed (nimi, lehekülg, kohandatud väljad).

Ülaltoodud näites pärineb esimene lõik faili security-guide.pdf 12. leheküljelt skooriga 0,92, teine aga teise faili 45. leheküljelt skooriga 0,87. Neist kahest väärtusest piisab liidese loomiseks, mis kuvab vastuse ja selle all lingi „Vaata algset lõiku, lk 12“. Skoor toimib lävendina: paljud meeskonnad viskavad minna kõik tulemused, mille skoor on alla 0,5, selle asemel et lasta mudelil müra põhjal järeldusi teha.

Otsing mitmes kollektsioonis

Kui collection_ids on massiiv, pole see juhuslik. Kliendi küsimus hõlmab sageli mitut dokumendimaailma ja sa ei taha teha kolme päringut, et tulemused seejärel käsitsi ühendada.

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

Siin päritakse koos tootedokumentatsiooni, KKK-d ja üldtingimusi. Tulemused saabuvad ühendatuna ja sordituna skoori alusel, sõltumata nende algsest kollektsioonist: KKK lõik skooriga 0,94 edestab üldtingimuste lõiku skooriga 0,71. Ristid heterogeenseid allikaid ühe võrgupäringuga.

Hind

Kollektsioonide otsimine maksab 2,50 dollarit 1000 päringu kohta ja see määr ei muutu sõltuvalt päritavate kollektsioonide arvust ega indekseeritud dokumentide suurusest. Võrdle seda failimanustega – need üksikud failid, mis edastatakse input_file kaudu ja mida arveldatakse 10 dollari eest 1000 päringu kohta: niipea kui pärid samu dokumente korduvalt, on kollektsioonid neli korda odavamad. Sisene assistent, mis töötleb kuus 20 000 küsimust, maksab kollektsioonidega 50 dollarit versus 200 dollarit manustega – ja saab kaasa kiiremad tulemused, kuna indeks on juba olemas.

Hinnad seisuga 5. august 2026 – hinnad muutuvad regulaarselt: enne eelarve arvutamist kontrolli kehtivat hinnakirja xAI mudelite ja hindade ametlikult lehelt.

Peamised punktid

  • Lõpp-punkt POST /v1/documents/search pärib sinu kollektsioone loomulikus keeles.
  • Saadaval on kolm otsingurežiimi: märksõna, semantiline, hübriid.
  • Saad otsida mitmest kollektsioonist samaaegselt.
  • Tulemused järjestatakse asjakohasuse skoori alusel koos allika sisuga.
  • Hind on 2,50 dollarit 1000 päringu kohta, mis on neli korda odavam kui failimanused.