A dokumentumkeresési végpont
Ezen az oldalon
Tudásbázisaid lekérdezése
Eddig felépítetted a konténert: kollekciókat, indexelt dokumentumokat, metaadatokat. Mindez semmit sem ér, ha nem tudod, hogyan tegyél fel kérdést. Erre való a POST /v1/documents/search végpont, amely természetes nyelvű lekérdezést fogad, és visszaadja a dokumentumaidból azt a szövegrészt, amely a legjobban megválaszolja azt. Képzeld el egy ügyfélszolgálati csapatot, amely megkapja a „Mennyi az elállási idő?“ kérdést. Ahelyett, hogy egy ügynöknek kellene végigolvasnia az általános szerződési feltételeket, elküldöd a kérdést a végpontnak, és visszakeresed a három hasznos bekezdést, a hozzájuk tartozó pontszámmal és forrással együtt.
A kérés felépítése
Az első dolog, amit észben kell tartanod – és ez a hibák gyakori forrása –, hogy ez a végpont a szabványos API-n (api.x.ai) érhető el, nem pedig azon a Kezelési API-n, amelyet a kollekciók létrehozásához használtál. A hitelesítéshez a szokásos API-kulcsodat használod. A minimális kérés három mezőre redukálódik.
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"
}
}'
Fő paraméterek
- query: a kérdésed természetes nyelven. Minél specifikusabb a kérdés, annál relevánsabbak az eredmények
- source.collection_ids: a lekérdezni kívánt kollekcióazonosítók tömbje. Egyetlen kérésben több kollekcióban is kereshetsz
- retrieval_mode.type: a használni kívánt keresési mód (
keyword,semanticvagyhybrid)
A válasz értelmezése
Az API nem egész dokumentumokat ad vissza, hanem töredékeket: az indexelés során létrehozott chunkokat, amelyek a legrelevánsabbtól a legkevésbé relevánsig vannak rangsorolva.
{
"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
}
}
]
}
Minden bejegyzés négy információdarabot tartalmaz:
- content: a szövegrészlet a dokumentumból
- score: egy 0 és 1 közötti relevancia-pontszám
- document_id: a forrásfájl azonosítója
- metadata: a dokumentum metaadatai (név, oldal, egyéni mezők)
A fenti példában az első részlet a security-guide.pdf 12. oldaláról származik 0,92-es pontszámmal, a második egy másik fájl 45. oldaláról 0,87-es pontszámmal. Ez a két érték elég ahhoz, hogy olyan felületet építs, amely megjeleníti a választ, és közvetlenül alatta egy „Eredeti részlet megtekintése, 12. oldal“ hivatkozást. A pontszám küszöbértékként működik: sok csapat elvet minden 0,5 alatti eredményt, ahelyett, hogy hagyná a modellt zajon gondolkodni.
Keresés több kollekcióban
Ha a collection_ids egy tömb, annak nincs véletlen oka. Egy ügyfélkérdés gyakran több dokumentumvilágot is érint, és nem szeretnéd, ha három hívást kellene indítanod, majd kézzel egyesítenéd az eredményeket.
{
"query": "Refund policy",
"source": {
"collection_ids": [
"col_docs_produit",
"col_faq",
"col_conditions_generales"
]
},
"retrieval_mode": {
"type": "hybrid"
}
}
Itt a termékdokumentációt, a GYIK-ot és az általános szerződési feltételeket együtt kérdezed le. Az eredmények egyesítve és pontszám szerint rendezve érkeznek vissza, függetlenül az eredeti kollekciójuktól: egy 0,94-es pontszámú GYIK-részlet magasabban rangsorol, mint egy 0,71-es ÁSZF-részlet. Heterogén forrásokat keresel át egyetlen hálózati körút során.
Költség
A kollekciók keresése 1000 hívásonként 2,50 USD-be kerül, és ez az arány nem változik a lekérdezett kollekciók száma vagy az indexelt dokumentumok mérete alapján. Hasonlítsd ezt a fájlmellékletekhez: ezek az input_file útján átadott egyes fájlok, amelyek díjazása 1000 hívásonként 10 USD. Amint ugyanazokat a dokumentumokat ismételten kérdezed le, a kollekciók használata négyszer olcsóbb. Egy belső asszisztens, amely havi 20 000 kérdést kezel, kollekciókkal 50 USD-t, míg mellékletekkel 200 USD-t fizet – ráadásul gyorsabb eredményeket kap, mivel az index már létezik.
Árak 2026. augusztus 5-i állapot szerint – az árak rendszeresen változnak: bármilyen költségvetési számítás előtt ellenőrizd az aktuális díjszabást a hivatalos xAI modellek és árazási oldalon.
Főbb megállapítások
- A
POST /v1/documents/searchvégpont természetes nyelven kérdezi le a kollekcióidat - Három keresési mód áll rendelkezésre: kulcsszavas, szemantikus, hibrid
- Több kollekcióban is kereshetsz egyszerre
- Az eredmények relevancia-pontszám szerint vannak rangsorolva, a forrásszöveggel együtt
- A költség 1000 hívásonként 2,50 USD, ami négyszer olcsóbb, mint a fájlmellékletek használata