Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

A dokumentumkeresési végpont

9. lecke 16 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Tudásbázisaid lekérdezése
  2. A kérés felépítése
  3. A válasz értelmezése
  4. Keresés több kollekcióban
  5. Költség
  6. Főbb megállapítások

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.

POST
/v1/documents/search
3 mód
kulcsszavas, szemantikus, hibrid
$2.50
1000 hívásonként
Többes
Több kollekció

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, semantic vagy hybrid)

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/search vé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