Documentation
¶
Overview ¶
Package reranker implements RAG's optional second-pass reranking step: an HTTP client speaking the Cohere-compatible rerank API shape ({query, documents, top_n} -> {results: [{index, relevance_score}]}), which LangSearch's hosted API, vLLM's built-in reranker endpoint, and Cohere itself all speak. HuggingFace Text Embeddings Inference (TEI) uses a slightly different shape ({query, texts} -> a bare array of {index, score}) - HTTPReranker sends both request field names and parses both response shapes, so the same client works against either without needing to know in advance which server is on the other end.
This means a fully free, self-hosted alternative to LangSearch's hosted API is just a BaseURL away: point RAG_RERANK_URL at a local TEI or vLLM instance serving BAAI/bge-reranker-v2-m3 (Apache 2.0, runs on CPU) and no API key or external network call is needed at all.
Index ¶
Constants ¶
const ( StyleCohere = "cohere" // {model, query, documents, top_n} -> {results: [{index, relevance_score}]} StyleVoyage = "voyage" // {model, query, documents, top_k} -> {data: [{index, relevance_score}]} )
Request shapes. The default ("") sends the fields of every known server in one request (documents and texts, top_n), which suits a self-hosted TEI or vLLM instance; a hosted provider with a strict schema gets exactly its own fields.
Variables ¶
This section is empty.
Functions ¶
func NormalizeScores ¶
NormalizeScores min-max scales scores into [0,1] so a rerank score can be safely blended with a differently-scaled retrieval score (e.g. cosine similarity), regardless of which provider produced it - Cohere/LangSearch return an already-calibrated [0,1] relevance_score, but some cross-encoder endpoints (raw logits) don't. Mirrors RAGFlow's Base._normalize_rank: scores already inside [0,1] are left untouched rather than needlessly rescaled; only an out-of-range batch is rescaled.
A spreadless batch (every score identical, so max == min) would divide by zero - returns 0.5 for every entry instead. That constant doesn't bias relative order: added the same amount to every item in a blend, the blended ranking for that batch just falls back to whatever the other blend term (the original retrieval score) already ordered.
Types ¶
type Config ¶
type Config struct {
// BaseURL is the full rerank endpoint URL, e.g.
// "https://api.langsearch.com/v1/rerank" or "http://localhost:8080/rerank"
// for a self-hosted TEI/vLLM instance. Empty means unconfigured -
// IsConfigured() reports false and Rerank refuses to run.
BaseURL string
// APIKey is sent as "Authorization: Bearer <key>" when non-empty.
// Self-hosted servers (TEI, a local vLLM instance) typically don't need
// one; LangSearch and Cohere do.
APIKey string
// Model is sent as the "model" request field when non-empty. Ignored by
// single-model servers like TEI, required by LangSearch/Cohere/vLLM.
Model string
// Style selects the request shape of a hosted provider (StyleCohere,
// StyleVoyage); empty sends the fields of every known server, which is
// what a self-hosted endpoint wants.
Style string
Timeout time.Duration
}
Config configures an HTTPReranker.
func FromEnv ¶
func FromEnv() Config
FromEnv reads reranker configuration from environment variables:
RAG_RERANK_PROVIDER — a provider of the catalog (cohere, voyage, openrouter, langsearch): its endpoint,
request shape, default model and key variable (COHERE_API_KEY, VOYAGE_API_KEY,
OPENROUTER_API_KEY, LANGSEARCH_API_KEY) are used
RAG_RERANK_URL — full rerank endpoint URL (self-hosted TEI/vLLM, or any Cohere-compatible service);
wins over the provider's endpoint
RAG_RERANK_MODEL — model name (ignored by single-model servers such as TEI)
RAG_RERANK_API_KEY — optional; omit for a self-hosted server that doesn't require auth
When RAG_RERANK_URL isn't set, falls back to LangSearch's hosted endpoint if LANGSEARCH_API_KEY is set - the previous zero-config default, kept for backward compatibility. Returns a zero Config (IsConfigured() == false) when neither is configured.
type HTTPReranker ¶
type HTTPReranker struct {
// contains filtered or unexported fields
}
HTTPReranker reranks documents via a Cohere-compatible (or TEI-compatible) HTTP rerank endpoint.
func NewFromEnv ¶
func NewFromEnv() *HTTPReranker
NewFromEnv creates an HTTPReranker from environment variables (see FromEnv).
func (*HTTPReranker) IsConfigured ¶
func (r *HTTPReranker) IsConfigured() bool
IsConfigured reports whether a rerank endpoint is set.
func (*HTTPReranker) Rerank ¶
func (r *HTTPReranker) Rerank(ctx context.Context, query string, docs []string, topN int) ([]int, []float32, error)
Rerank sends docs to the configured endpoint and returns their indices sorted by descending relevance, along with the score for each position. topN caps the returned list; pass 0 to return all.
type LangSearchReranker ¶
type LangSearchReranker = HTTPReranker
LangSearchReranker is HTTPReranker preconfigured for LangSearch's hosted rerank API (langsearch.com - no credit card required for the free tier). Kept as a distinct name for backward compatibility; for a fully free, self-hosted alternative requiring no API key, use New/NewFromEnv with a BaseURL pointing at a local TEI or vLLM instance instead - see reranker.go's package doc.
func NewLangSearchReranker ¶
func NewLangSearchReranker() *LangSearchReranker
NewLangSearchReranker reads LANGSEARCH_API_KEY from the environment.
func NewLangSearchRerankerWithKey ¶
func NewLangSearchRerankerWithKey(apiKey string) *LangSearchReranker
NewLangSearchRerankerWithKey builds a LangSearch-configured reranker. An empty apiKey produces an unconfigured reranker (IsConfigured() == false) rather than one pointed at LangSearch with no credentials, since LangSearch's API requires a key - matches the pre-generalization behavior.
type Profile ¶ added in v1.8.0
type Profile struct {
ID string
DisplayName string
URL string
EnvVars []string // environment variables that can carry the API key
Style string
// Models lists the rerank models; the first is the default.
Models []string
}
Profile describes a hosted rerank provider: where it is, which key it takes, the request shape it expects and its models. It is the rerank counterpart of the chat catalog in internal/providers; RAG_RERANK_PROVIDER selects one.
func ProfileFor ¶ added in v1.8.0
ProfileFor returns the profile of a provider ID, case-insensitively.
func Profiles ¶ added in v1.8.0
func Profiles() []Profile
Profiles returns the rerank providers this build knows.
func (Profile) DefaultModel ¶ added in v1.8.0
DefaultModel returns the model used when none is configured.
Source Files