Dokumentų paieškos galinis taškas
Šiame puslapyje
Užklausų teikimas savo žinių bazėms
Iki šiol sukūrei konteinerį: kolekcijas, indeksuotus dokumentus, metaduomenis. Visa tai neturi prasmės, jei nemoki užduoti klausimo. Būtent tai ir daro POST /v1/documents/search – jis priima užklausą natūralia kalba ir grąžina ištraukas iš tavo dokumentų, kurios geriausiai į ją atsako. Įsivaizduok palaikymo komandą, gaunančią klausimą „Koks yra atsisakymo terminas?“. Vietoj to, kad agentas skaitytų naudojimo sąlygas, tu siunti klausimą į galinį tašką ir gauni tris naudingas pastraipas kartu su jų įverčiu ir šaltiniu.
Užklausos struktūra
Pirmas dalykas, kurį reikia atminti, ir tai dažna klaidų priežastis: šis galinis taškas veikia standartiniame API (api.x.ai), o ne Valdymo API, kuriuo naudojai kurdamas kolekcijas. Autentifikacijai naudoji savo įprastą API raktą. Minimalią užklausą sudaro tik trys laukai.
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"
}
}'
Pagrindiniai parametrai
- query: tavo klausimas natūralia kalba. Kuo konkretesnis klausimas, tuo tikslesni rezultatai
- source.collection_ids: kolekcijų ID masyvas, kuriame ieškoma. Vienoje užklausoje gali ieškoti keliose kolekcijose vienu metu
- retrieval_mode.type: naudojamas paieškos režimas (
keyword,semanticarbahybrid)
Atsakymo skaitymas
API grąžina ne visus dokumentus, o fragmentus – indeksavimo metu sukurtas dalis, surikiuotas nuo labiausiai iki mažiausiai tinkamų.
{
"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
}
}
]
}
Kiekvienas įrašas turi keturis informacijos elementus:
- content: teksto ištrauka iš dokumento
- score: tinkamumo įvertis nuo 0 iki 1
- document_id: šaltinio failo ID
- metadata: dokumento metaduomenys (pavadinimas, puslapis, papildomi laukai)
Pirmiau pateiktame pavyzdyje pirmoji ištrauka yra iš security-guide.pdf 12 puslapio su 0,92 įverčiu, antroji – iš kito failo 45 puslapio su 0,87 įverčiu. Šių dviejų verčių pakanka sukurti sąsają, rodančią atsakymą, o tiesiai po juo – nuorodą „žiūrėti originalią ištrauką, 12 puslapis“. Įvertis veikia kaip slenkstis: daugelis komandų atmeta visus rezultatus, kurių įvertis mažesnis nei 0,5, kad modelis nereikštų triukšmo.
Paieška keliose kolekcijose
Jei collection_ids yra masyvas, tai nėra atsitiktinumas. Kliento klausimas dažnai apima kelias dokumentų erdves, ir tu nenori atlikti trijų užklausų, o tada rankiniu būdu sujungti rezultatus.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Čia kartu užklausiama produkto dokumentacija, DUK ir bendrosios sąlygos. Rezultatai grąžinami sujungti ir surikiuoti pagal įvertį, nepaisant jų originalios kolekcijos: DUK ištrauka su 0,94 įverčiu bus aukščiau nei bendrųjų sąlygų ištrauka su 0,71 įverčiu. Taip vienu tinklo užklausos ciklu apdoroji nevienalyčius šaltinius.
Kaina
Kolekcijų paieška kainuoja 2,50 USD už 1 000 užklausų, ir šis tarifas nekinta priklausomai nuo užklaustų kolekcijų skaičiaus ar indeksuotų dokumentų dydžio. Palygink tai su failų priedais – tais atskirais failais, perduodamais per input_file, kurie kainuoja 10 USD už 1 000 užklausų: kai tik tu pakartotinai užklausi tuos pačius dokumentus, kolekcijos kainuoja keturis kartus mažiau. Vidinis asistentas, apdorojantis 20 000 klausimų per mėnesį, su kolekcijomis kainuos 50 USD, o su priedais – 200 USD, be to, gausi greitesnius rezultatus, nes indeksas jau sukurtas.
Kainodara nuo 2026 m. rugpjūčio 5 d. – kainos keičiasi reguliariai: prieš atlikdami bet kokius biudžeto skaičiavimus, patikrinkite dabartinius įkainius oficialiame xAI modelių ir kainodaros puslapyje.
Svarbiausi punktai
- Galinis taškas
POST /v1/documents/searchleidžia užklausti tavo kolekcijas natūralia kalba - Yra trys paieškos režimai: raktinių žodžių, semantinis, hibridinis
- Vienu metu gali ieškoti keliose kolekcijose
- Rezultatai surikiuojami pagal tinkamumo įvertį kartu su šaltinio turiniu
- Kaina – 2,50 USD už 1 000 užklausų, tai keturis kartus pigiau nei naudojant failų priedus