Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Asiakirjahakupäätepiste

Oppitunti 9 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tietokantojesi kyselyt
  2. Pyynnön rakenne
  3. Vastauksen lukeminen
  4. Haku useista kokoelmista
  5. Kustannukset
  6. Keskeiset asiat

Tietokantojesi kyselyt

Olet tähän mennessä rakentanut säiliön: kokoelmat, indeksoidut asiakirjat ja metatiedot. Mikään tästä ei kuitenkaan merkitse mitään, ellei tiedä, miten kysymys esitetään. Tämä on tehtävä, jonka hoitaa POST /v1/documents/search. Se ottaa vastaan luonnollisen kielen kyselyn ja palauttaa asiakirjoistasi ne kohdat, jotka vastaavat siihen parhaiten. Kuvittele tukitiimi, joka saa kysymyksen: “Mikä on peruutusaika?” Agentin sijaan, joka lukisi käyttöehdot läpi, lähetät kysymyksen päätepisteeseen ja haet kolme hyödyllistä kappaletta täydellisinä pisteytyksineen ja lähteineen.

POST
/v1/documents/search
3 tilaa
avainsana, semanttinen, hybridi
$2.50
Per 1 000 pyyntöä
Moni
Useita kokoelmia

Pyynnön rakenne

Ensimmäinen muistettava asia, ja tämä on yleinen virhelähde: tämä päätepiste sijaitsee vakio-API:ssa (api.x.ai), ei hallinta-API:ssa, jota käytit kokoelmien luomiseen. Todennat itsesi tavallisella API-avaimellasi. Minimipyyntö tiivistyy kolmeen kenttään.

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"
    }
  }'

Tärkeimmät parametrit

  • query: kysymyksesi luonnollisella kielellä. Mitä tarkempi kysymys, sitä osuvampia tulokset ovat.
  • source.collection_ids: taulukko kysyttävistä kokoelmatunnuksista. Voit hakea useista kokoelmista yhdellä pyynnöllä.
  • retrieval_mode.type: käytettävä hakutila (keyword, semantic tai hybrid).

Vastauksen lukeminen

API ei palauta kokonaisia asiakirjoja, vaan indeksoinnin aikana luotuja katkelmia, jotka on järjestetty osuvimmasta vähiten osuvaan.

{
  "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
      }
    }
  ]
}

Jokainen merkintä sisältää neljä tietoa:

  • content: tekstikatkelma asiakirjasta
  • score: osuvuuspisteet välillä 0–1
  • document_id: lähdeasiakirjan tunnus
  • metadata: asiakirjan metatiedot (nimi, sivu, mukautetut kentät)

Yllä olevassa esimerkissä ensimmäinen katkelma on peräisin tiedoston security-guide.pdf sivulta 12 pisteytyksellä 0,92 ja toinen toisen tiedoston sivulta 45 pisteytyksellä 0,87. Nämä kaksi arvoa riittävät käyttöliittymän rakentamiseen, joka näyttää vastauksen ja sen alapuolella linkin “katso alkuperäinen kohta, sivu 12”. Pisteytys toimii kynnysarvona: monet tiimit hylkäävät kaikki tulokset, joiden arvo on alle 0,5, sen sijaan että antaisivat mallin päätellä kohinaa.

Haku useista kokoelmista

Se, että collection_ids on taulukko, ei ole sattumaa. Asiakkaan kysymys yhdistää usein useita asiakiramaailmoja, etkä halua tehdä kolmea erillistä pyyntöä ja yhdistää tuloksia käsin.

{
  "query": "Refund policy",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Tässä haetaan samanaikaisesti tuotedokumentaatiosta, usein kysytyistä kysymyksistä ja yleisistä ehdoista. Tulokset palautetaan yhdistettynä ja lajiteltuna pisteytyksen mukaan riippumatta alkuperäisestä kokoelmasta: FAQ-katkelma, jonka arvo on 0,94, nousee yleisiä ehtoja koskevan katkelman edelle, jonka arvo on 0,71. Yhdistät heterogeenisiä lähteitä yhdessä verkkopyynnössä.

Kustannukset

Kokoelmien haku maksaa 2,50 dollaria 1 000 pyyntöä kohden. Tämä hinta ei muutu riippuen kysyttyjen kokoelmien määrästä tai indeksoitujen asiakirjojen koosta. Vertaa tätä tiedostoliitteisiin, eli yksittäisiin tiedostoihin, jotka välitetään parametrilla input_file ja joista veloitetaan 10 dollaria 1 000 pyyntöä kohden: heti kun kysyt samoja asiakirjoja toistuvasti, kokoelmat maksavat neljä kertaa vähemmän. Sisäinen avustaja, joka käsittelee 20 000 kysymystä kuukaudessa, maksaa kokoelmilla 50 dollaria verrattuna 200 dollariin liitteillä – ja saa lisäksi nopeammat tulokset, koska indeksi on jo olemassa.

Hinnoittelu 5. elokuuta 2026 – hinnat muuttuvat säännöllisesti: ennen budjetin laskemista tarkista nykyinen hinnasto xAI:n viralliselta mallien ja hinnoittelun sivulta.

Keskeiset asiat

  • POST /v1/documents/search -päätepiste kysyy kokoelmiasi luonnollisella kielellä
  • Käytettävissä on kolme hakutilaa: avainsana, semanttinen ja hybridi
  • Voit hakea useista kokoelmista samanaikaisesti
  • Tulokset järjestetään osuvuuspisteiden mukaan lähdesisällön kera
  • Kustannus on 2,50 dollaria 1 000 pyyntöä kohden, mikä on neljä kertaa halvempaa kuin tiedostoliitteet