Rerank

Urutkan sekumpulan dokumen dari yang paling relevan sampai yang paling tidak relevan terhadap sebuah query. Pakai sebagai tahap kedua pencarian: ambil kandidat dengan embeddings atau pencarian keyword, lalu rerank beberapa yang terbaik. Request dan response mengikuti gaya rerank Cohere dan Jina, karena OpenAI tidak punya API rerank.

POST /v1/rerank

Endpoint ini hanya melayani model rerank. Kalau dipanggil dengan model chat, hasilnya 400. Lihat model rerank yang sedang tersedia lewat panggilan publik yang tidak butuh key:

curl "https://kenari.id/v1/models?modality=rerank"

GET /v1/models tanpa parameter tidak menampilkan model embedding, rerank, moderasi, atau System One. Endpoint ini menampilkan model chat, gambar, suara, transkripsi, dan video. Contoh di bawah memakai bge-reranker-base. Ganti dengan id mana pun yang dikembalikan panggilan di atas. Harga ada di Model & harga.

Request

Field	Tipe	Wajib	Keterangan
`model`	string	ya	Id model rerank.
`query`	string	ya	Acuan untuk mengukur relevansi. Maksimum 8.192 byte.
`documents`	array string	ya	Dokumen yang diurutkan. Maksimum 100, masing-masing string tidak kosong dengan ukuran maksimum 8.192 byte, dan total maksimum 512 KiB.
`top_n`	integer	tidak	Kembalikan hanya `n` hasil terbaik. Dari 1 sampai jumlah dokumen. Default: semua dokumen.
`return_documents`	boolean	tidak	Sertakan teks tiap dokumen di hasilnya. Default: `false`.

Response

results berisi satu entri per dokumen yang dikembalikan, dari kecocokan terbaik. Setiap entri punya index, yaitu posisi dokumen dalam array documents yang kamu kirim, dan relevance_score. Skor lebih tinggi berarti lebih cocok. document berupa objek dengan field text dan hanya muncul kalau return_documents bernilai true. usage melaporkan token input.

{
  "object": "list",
  "model": "bge-reranker-base",
  "results": [
    { "index": 2, "relevance_score": 0.91 },
    { "index": 0, "relevance_score": 0.42 }
  ],
  "usage": { "prompt_tokens": 24, "total_tokens": 24 }
}

Contoh

curl

curl https://kenari.id/v1/rerank \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-base",
    "query": "resep nasi goreng pedas",
    "documents": [
      "cara menyeduh kopi dingin",
      "menanam cabai di pot",
      "resep nasi goreng pedas ala rumahan"
    ],
    "top_n": 2
  }'

Python

SDK OpenAI tidak punya method rerank, jadi pakai requests.

import os
import requests

resp = requests.post(
    "https://kenari.id/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['KENARI_API_KEY']}"},
    json={
        "model": "bge-reranker-base",
        "query": "resep nasi goreng pedas",
        "documents": [
            "cara menyeduh kopi dingin",
            "menanam cabai di pot",
            "resep nasi goreng pedas ala rumahan",
        ],
        "top_n": 2,
    },
)
print(resp.json()["results"])

JavaScript

const resp = await fetch("https://kenari.id/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KENARI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "bge-reranker-base",
    query: "resep nasi goreng pedas",
    documents: [
      "cara menyeduh kopi dingin",
      "menanam cabai di pot",
      "resep nasi goreng pedas ala rumahan",
    ],
    top_n: 2,
  }),
});
const { results } = await resp.json();

Penagihan

Rerank ditagih per token input, diperkirakan dari query ditambah seluruh dokumen. Perkiraan itulah yang ditagihkan, dan angka usage di response hanya untuk ditampilkan. Lihat Cara penagihan untuk cara penahanan saldo dan dimensi harga.

Error

Batas ukuran diperiksa lebih dulu. Request yang melewati batas gagal dengan 400 sebelum ada tagihan.

Status	Kode	Kapan
400	`bad_request`	`model` tidak dikenal atau bukan model rerank, `query` atau `documents` tidak ada atau kosong, batas terlampaui, atau `top_n` bukan integer antara 1 dan jumlah dokumen.
400	`model_not_found`	Modelnya terdaftar tetapi saat ini tidak ada provider yang melayaninya. Coba lagi nanti.

Kode bersama, seperti insufficient_balance dan all_providers_failed, ada di Error.