Dokumentide otsimise lõpp-punkt
Sellel lehel
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.
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,semanticvõihybrid).
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/searchpä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.