Koncový bod pro vyhledávání v dokumentech
Na této stránce
Dotazování do tvých znalostních bází
Doposud jsi vybudoval kontejner: kolekce, indexované dokumenty, metadata. To vše je k ničemu, pokud nevíš, jak položit otázku. To je úkolem POST /v1/documents/search, který přijímá dotaz v přirozeném jazyce a vrací úryvky z tvých dokumentů, které na něj nejlépe odpovídají. Představ si tým podpory, který dostane otázku „Jaká je lhůta pro odstoupení od smlouvy?“. Místo toho, aby agent četl obchodní podmínky, pošleš tuto otázku na koncový bod a získáš tři užitečné odstavce včetně jejich skóre a zdroje.
Struktura požadavku
První věc, kterou si musíš zapamatovat a která je častým zdrojem chyb: tento koncový bod běží na standardním API (api.x.ai), nikoliv na Management API, které jsi používal k vytváření kolekcí. Autentizuješ se svým běžným API klíčem. Minimální požadavek se skládá ze tří polí.
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í parametry
- query: tvá otázka v přirozeném jazyce. Čím konkrétnější otázka, tím relevantnější výsledky.
- source.collection_ids: pole ID kolekcí, do kterých se má dotazovat. V rámci jednoho požadavku můžeš vyhledávat napříč více kolekcemi.
- retrieval_mode.type: režim vyhledávání, který chceš použít (
keyword,semanticnebohybrid).
Čtení odpovědi
API nevrací celé dokumenty, ale fragmenty – chunky vytvořené během indexování – seřazené od nejvíce po nejméně 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 čtyři informace:
- content: textový úryvek z dokumentu
- score: skóre relevance mezi 0 a 1
- document_id: ID zdrojového souboru
- metadata: metadata dokumentu (název, stránka, vlastní pole)
V příkladu výše pochází první úryvek ze stránky 12 souboru security-guide.pdf se skóre 0,92, druhý ze stránky 45 jiného souboru se skóre 0,87. Tyto dvě hodnoty stačí k vytvoření rozhraní, které zobrazí odpověď a hned pod ní odkaz „zobrazit původní úryvek, strana 12“. Skóre funguje jako práh: mnoho týmů zahodí jakýkoli výsledek pod 0,5, místo aby nechaly model uvažovat nad šumem.
Vyhledávání napříč více kolekcemi
Pokud je collection_ids pole, není to náhoda. Zákaznický dotaz často kombinuje několik světů dokumentů a ty nechceš dělat tři volání a poté ručně slučovat výsledky.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Zde se společně dotazujete produktové dokumentace, FAQ i obchodních podmínek. Výsledky přicházejí sloučené a seřazené podle skóre bez ohledu na jejich původní kolekci: úryvek z FAQ se skóre 0,94 se umístí výše než úryvek z obchodních podmínek se skóre 0,71. Křížíš heterogenní zdroje v rámci jediného síťového přenosu.
Cena
Vyhledávání v kolekcích stojí 2,50 $ za 1 000 volání a tato sazba se nemění v závislosti na počtu dotazovaných kolekcí ani velikosti indexovaných dokumentů. Porovnej to s přílohami souborů, tedy jednotlivými soubory předávanými přes input_file, které jsou účtovány za 10 $ za 1 000 volání: jakmile začneš stejné dokumenty dotazovat opakovaně, jsou kolekce čtyřikrát levnější. Interní asistent zpracovávající 20 000 otázek měsíčně zaplatí s kolekcemi 50 $ oproti 200 $ u příloh – a navíc získá rychlejší výsledky, protože index již existuje.
Ceník platný k 5. srpnu 2026 – ceny se pravidelně mění: před jakýmkoli výpočtem rozpočtu si ověř aktuální ceník na oficiální stránce modelů a cen xAI.
Klíčové poznatky
- Koncový bod
POST /v1/documents/searchdotazuje tvé kolekce v přirozeném jazyce - K dispozici jsou tři režimy vyhledávání: klíčová slova, sémantické, hybridní
- Můžeš vyhledávat napříč více kolekcemi současně
- Výsledky jsou seřazeny podle skóre relevance spolu se zdrojovým obsahem
- Cena činí 2,50 $ za 1 000 volání, což je čtyřikrát méně než u příloh souborů