Meklēšanas galapunkts dokumentiem
Šajā lapā
Vaicājumi tavām zināšanu bāzēm
Līdz šim tu esi izveidojis konteineru: kolekcijas, indeksētus dokumentus, metadatus. Tam visam nav jēgas, ja nezini, kā uzdot jautājumu. Tieši to dara POST /v1/documents/search, kas pieņem vaicājumu dabiskajā valodā un atgriež no taviem dokumentiem iegūtos fragmentus, kas uz to atbild visprecīzāk. Iedomājies atbalsta komandu, kas saņem jautājumu „Kāds ir atteikuma termiņš?”. Tā vietā, lai liktu aģentam lasīt noteikumus un nosacījumus, tu nosūti jautājumu galapunktam un saņem trīs noderīgus rindkopas, kopā ar to vērtējumu un avotu.
Pieprasījuma struktūra
Pirmā lieta, kas jāatceras, un tas ir biežs kļūdu avots: šis galapunkts atrodas standarta API (api.x.ai), nevis pārvaldības API, ko izmantoji kolekciju izveidei. Tu autentificējies, izmantojot savu parasto API atslēgu. Minimālais pieprasījums sastāv no trim laukiem.
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"
}
}'
Galvenie parametri
- query: tavs jautājums dabiskajā valodā. Jo specifiskāks ir jautājums, jo atbilstošāki ir rezultāti.
- source.collection_ids: kolekciju ID masīvs, kurā veikt vaicājumu. Vienā pieprasījumā vari meklēt vairākās kolekcijās.
- retrieval_mode.type: izmantojamais meklēšanas režīms (
keyword,semanticvaihybrid).
Atbildes lasīšana
API neatgriež veselus dokumentus, bet gan fragmentus – indeksēšanas laikā izveidotos gabalus, kas sakārtoti no visatbilstošākā uz mazāk atbilstošo.
{
"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
}
}
]
}
Katrs ieraksts satur četras informācijas daļas:
- content: teksta fragments no dokumenta.
- score: atbilstības vērtējums robežās no 0 līdz 1.
- document_id: avota faila ID.
- metadata: dokumenta metadati (nosaukums, lappuse, pielāgoti lauki).
Iepriekšējā piemērā pirmais fragments ir no security-guide.pdf 12. lappuses ar vērtējumu 0,92, bet otrais – no cita faila 45. lappuses ar vērtējumu 0,87. Šīs divas vērtības ir pietiekamas, lai izveidotu saskarni, kas parāda atbildi un tieši zem tās saiti „skatīt oriģinālo fragmentu, 12. lappuse”. Vērtējums darbojas kā slieksnis: daudzas komandas atsakās no jebkura rezultāta, kas ir zem 0,5, tā vietā, lai ļautu modelim spriest, balstoties uz trokšņiem.
Meklēšana vairākās kolekcijās
Ja collection_ids ir masīvs, tas nav nejauši. Klienta jautājums bieži aptver vairākus dokumentu universus, un tu nevēlies veikt trīs atsevišķus izsaukumus, lai pēc tam manuāli apvienotu rezultātus.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Šeit kopā tiek vaicāta produktu dokumentācija, BUJ un vispārīgie noteikumi. Rezultāti tiek atgriezti apvienoti un sakārtoti pēc vērtējuma neatkarīgi no to sākotnējās kolekcijas: BUJ fragments ar vērtējumu 0,94 būs augstāk nekā noteikumu fragments ar 0,71. Tu šķērso neviendabīgus avotus vienā tīkla apritē.
Izmaksas
Kolekciju meklēšana maksā 2,50 USD par 1000 izsaukumiem, un šī likme nemainās atkarībā no vaicāto kolekciju skaita vai indeksēto dokumentu lieluma. Salīdzini to ar failu pielikumiem – tiem atsevišķajiem failiem, kas tiek nodoti, izmantojot input_file, kuriem tiek piemērota maksa 10 USD par 1000 izsaukumiem: tiklīdz tu atkārtoti vaicā tos pašus dokumentus, kolekcijas izmaksā četras reizes lētāk. Iekšējais asistents, kas apstrādā 20 000 jautājumu mēnesī, maksā 50 USD, izmantojot kolekcijas, pretstatā 200 USD, izmantojot pielikumus, un turklāt saņem ātrākus rezultātus, jo indekss jau pastāv.
Cenas spēkā no 2026. gada 5. augusta — cenas regulāri mainās: pirms jebkādiem budžeta aprēķiniem pārbaudi aktuālo cenu lapu oficiālajā xAI modeļu un cenu lapā.
Galvenās atziņas
- Galapunkts
POST /v1/documents/searchvaicā tavas kolekcijas dabiskajā valodā. - Pieejami trīs meklēšanas režīmi: atslēgvārdu, semantiskais, hibrīda.
- Vari meklēt vairākās kolekcijās vienlaicīgi.
- Rezultāti tiek rangēti pēc atbilstības vērtējuma kopā ar avota saturu.
- Izmaksas ir 2,50 USD par 1000 izsaukumiem, kas ir četras reizes lētāk nekā failu pielikumiem.