Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Krajnja točka za pretraživanje dokumenata

Lekcija 9 od 16 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Upitivanje tvojih baza znanja
  2. Struktura zahtjeva
  3. Čitanje odgovora
  4. Pretraživanje kroz više kolekcija
  5. Trošak
  6. Ključne točke

Upitivanje tvojih baza znanja

Do sada si izgradio kontejner: kolekcije, indeksirane dokumente, metapodatke. Ništa od toga nema smisla ako ne znaš kako postaviti pitanje. To je zadaća POST /v1/documents/search, koja prima upit na prirodnom jeziku i vraća odlomke iz tvojih dokumenata koji najbolje odgovaraju na njega. Zamisli tim za podršku koji prima upit „Koji je rok za odustajanje?“. Umjesto da agent čita opće uvjete, šalješ pitanje krajnjoj točki i dohvaćaš tri korisna odlomka, zajedno s njihovom ocjenom i izvorom.

POST
/v1/documents/search
3 načina
ključne riječi, semantički, hibridni
$2.50
Po 1.000 poziva
Višestruko
Više kolekcija

Struktura zahtjeva

Prva stvar koju trebaš zapamtiti, a čest je izvor pogrešaka: ova krajnja točka nalazi se na standardnom API-ju (api.x.ai), a ne na Upravljačkom API-ju koji si koristio za stvaranje kolekcija. Autentificiraš se svojim uobičajenim API ključem. Minimalni zahtjev svodi se na tri polja.

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

Glavni parametri

  • query: tvoje pitanje na prirodnom jeziku. Što je pitanje specifičnije, to su rezultati relevantniji
  • source.collection_ids: niz ID-ova kolekcija za pretraživanje. Možeš pretraživati više kolekcija u jednom zahtjevu
  • retrieval_mode.type: način pretraživanja koji ćeš koristiti (keyword, semantic ili hybrid)

Čitanje odgovora

API ne vraća cijele dokumente već fragmente, dijelove stvorene tijekom indeksiranja, rangirane od najrelevantnijih prema najmanje relevantnima.

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

Svaki unos sadrži četiri informacije:

  • content: tekstualni isječak iz dokumenta
  • score: ocjena relevantnosti između 0 i 1
  • document_id: ID izvorne datoteke
  • metadata: metapodaci dokumenta (naziv, stranica, prilagođena polja)

U gornjem primjeru, prvi isječak dolazi sa stranice 12 datoteke security-guide.pdf s ocjenom 0,92, a drugi sa stranice 45 druge datoteke s ocjenom 0,87. Ove dvije vrijednosti dovoljne su za izgradnju sučelja koje prikazuje odgovor i, neposredno ispod njega, poveznicu „pogledaj izvorni odlomak, stranica 12“. Ocjena djeluje kao prag: mnogi timovi odbacuju svaki rezultat ispod 0,5 umjesto da dopuste modelu da rasuđuje na temelju šuma.

Pretraživanje kroz više kolekcija

Ako je collection_ids niz, to nije slučajno. Pitanje kupca često miješa nekoliko svemira dokumenata, a ti ne želiš izvršiti tri poziva pa ručno spajati rezultate.

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

Ovdje se zajedno upituju dokumentacija o proizvodu, FAQ i opći uvjeti. Rezultati se vraćaju spojeni i sortirani po ocjeni, bez obzira na njihovu izvornu kolekciju: isječak iz FAQ-a s ocjenom 0,94 rangirat će se iznad isječka iz općih uvjeta s ocjenom 0,71. Ukrštaš heterogene izvore u jednom mrežnom putovanju (round-trip).

Trošak

Pretraživanje kolekcija košta 2,50 USD po 1.000 poziva, a ta se stopa ne mijenja ovisno o broju upitanih kolekcija ili veličini indeksiranih dokumenata. Usporedi to s privicima datoteka, onim pojedinačnim datotekama proslijeđenim putem input_file, koje se naplaćuju po 10 USD za 1.000 poziva: čim više puta upituješ iste dokumente, kolekcije su četiri puta jeftinije. Interni asistent koji obrađuje 20.000 pitanja mjesečno plaća 50 USD s kolekcijama naspram 200 USD s privicima – i uz to dobiva brže rezultate, jer indeks već postoji.

Cjenik od 5. kolovoza 2026. — cijene se redovito mijenjaju: prije bilo kakvog proračuna proračuna, provjeri trenutnu cjenovnu listu na službenoj stranici xAI modela i cijena.

Ključne točke

  • Krajnja točka POST /v1/documents/search upituje tvoje kolekcije na prirodnom jeziku
  • Dostupna su tri načina pretraživanja: ključne riječi, semantički, hibridni
  • Možeš pretraživati više kolekcija istovremeno
  • Rezultati su rangirani po ocjeni relevantnosti sa sadržajem izvora
  • Trošak iznosi 2,50 USD po 1.000 poziva, što je četiri puta jeftinije od privitaka datoteka