Koncový bod vyhľadávania dokumentov
Na tejto strane
Dotazovanie do vašich znalostných bázi
Doteraz ste vybudovali kontajner: kolekcie, indexované dokumenty, metadáta. To všetko je však zbytočné, ak neviete, ako položiť otázku. Presne to je úlohou koncového bodu POST /v1/documents/search, ktorý prijíma dotaz v prirodzenom jazyku a vracia úryvky z vašich dokumentov, ktoré naň najlepšie odpovedajú. Predstavte si tím podpory, ktorý dostane otázku: „Aká je lehota na odstúpenie od zmluvy?“ Namiesto toho, aby agent čítal obchodné podmienky, pošlete otázku na tento koncový bod a získate tri užitočné odseky kompletne so skóre a zdrojom.
Štruktúra požiadavky
Prvá vec, ktorú si musíš zapamätať a ktorá je častým zdrojom chýb: tento koncový bod sa nachádza na štandardnom API (api.x.ai), nie na Management API, ktoré si používal na vytváranie kolekcií. Autentifikuješ sa svojím bežným API kľúčom. Minimálna požiadavka sa obmedzuje na tri polia.
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"
}
}'
Hlavné parametre
- query: tvoja otázka v prirodzenom jazyku. Čím konkrétnejšia otázka, tým relevantnejšie výsledky
- source.collection_ids: pole ID kolekcií, do ktorých sa má vyhľadávať. V rámci jednej požiadavky môžeš prehľadávať viacero kolekcií naraz
- retrieval_mode.type: režim vyhľadávania, ktorý sa má použiť (
keyword,semanticalebohybrid)
Čítanie odpovede
API nevracia celé dokumenty, ale fragmenty – časti (chunks) vytvorené počas indexovania – zoradené od najviac po najmenej relevantné.
{
"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
}
}
]
}
Každá položka obsahuje štyri informácie:
- content: textový úryvok z dokumentu
- score: skóre relevantnosti v rozmedzí od 0 do 1
- document_id: ID zdrojového súboru
- metadata: metadáta dokumentu (názov, strana, vlastné polia)
V uvedenom príklade pochádza prvý úryvok zo strany 12 súboru security-guide.pdf so skóre 0,92 a druhý zo strany 45 iného súboru so skóre 0,87. Tieto dve hodnoty stačia na vytvorenie rozhrania, ktoré zobrazí odpoveď a hneď pod ňou odkaz „zobraziť pôvodný úryvok, strana 12“. Skóre funguje ako prahová hodnota: mnohé tímy zahodia akýkoľvek výsledok pod 0,5, namiesto toho, aby nechali model uvažovať nad šumom.
Vyhľadávanie vo viacerých kolekciách
Ak je collection_ids poľom, nie je to náhoda. Zákaznícka otázka často kombinuje niekoľko svetov dokumentov a ty nechceš robiť tri samostatné volania a následne ručne spájať výsledky.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Tu sa spoločne dotazujú produktová dokumentácia, FAQ aj všeobecné obchodné podmienky. Výsledky prichádzajú zlúčené a zoradené podľa skóre bez ohľadu na ich pôvodnú kolekciu: úryvok z FAQ so skóre 0,94 sa umiestni vyššie než úryvok z obchodných podmienok so skóre 0,71. Prekračuješ heterogénne zdroje v rámci jediného sieťového prenosu.
Cena
Vyhľadávanie v kolekciách stojí 2,50 USD za 1 000 volaní a táto sadzba sa nemení v závislosti od počtu dotazovaných kolekcií ani veľkosti indexovaných dokumentov. Porovnaj to s prílohami súborov, teda jednotlivými súbormi odovzdanými cez input_file, ktoré sú spoplatnené sumou 10 USD za 1 000 volaní: akonáhle opakovane dotazuješ tie isté dokumenty, kolekcie sú štyrikrát lacnejšie. Interný asistent, ktorý vybaví 20 000 otázok mesačne, zaplatí pri kolekciách 50 USD oproti 200 USD pri prílohách – a navyše získa rýchlejšie výsledky, keďže index už existuje.
Cenník platný k 5. augustu 2026 – ceny sa pravidelne menia: pred akýmkoľvek výpočtom rozpočtu si over aktuálny cenník na oficiálnej stránke modelov a cien xAI.
Kľúčové poznatky
- Koncový bod
POST /v1/documents/searchumožňuje dotazovať sa do vašich kolekcií v prirodzenom jazyku - K dispozícii sú tri režimy vyhľadávania: keyword, semantic, hybrid
- Môžete vyhľadávať vo viacerých kolekciách súčasne
- Výsledky sú zoradené podľa skóre relevantnosti spolu so zdrojovým obsahom
- Cena je 2,50 USD za 1 000 volaní, čo je štyrikrát lacnejšie než pri prílohách súborov