Documentation
¶
Overview ¶
Package embed turns text into vectors via a single client speaking the OpenAI embeddings wire format — not per-provider adapters. That format is a de-facto standard: OpenAI's own API, and any "OpenAI-compatible" gateway in front of another provider (this package defaults to EdenAI's EU gateway), speak it identically, so switching provider is a config change rather than a new adapter.
Index ¶
Constants ¶
const ( // DefaultBaseURL is EdenAI's EU-region gateway — keeps embedding // requests in-region for data residency. DefaultBaseURL = "https://api.eu.edenai.run/v3" // DefaultModel proxies gemini-embedding-001 without needing a direct // GCP setup. DefaultModel = "google/gemini-embedding-001" // DefaultDimension is the pgvector width this package's default // configuration targets. DefaultDimension = 1536 )
Variables ¶
var ErrRateLimited = errors.New("embedding service rate limited")
ErrRateLimited marks a 429. Retryable, but worth a longer, deliberate backoff than a transient failure — see ErrUnavailable.
ErrUnavailable marks a transport/deployment failure — network error or a 5xx from the embedding service itself. Retryable: the request, not the input, is at fault.
Functions ¶
func Fingerprint ¶
Fingerprint is the canonical identity of the space an embedder embeds into. Two embedders with the same fingerprint produce comparable vectors; different fingerprints do not, even if they happen to share a dimension.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client embeds text via an OpenAI-wire-compatible /embeddings endpoint: request {model, input, dimensions, encoding_format}, response {data: [{index, embedding}]}.
Not every backend honors the `dimensions` field reliably — EdenAI, for gemini-embedding-001, always returns the native 3072-wide vector regardless of what was requested. When the response is wider than the configured Dimension, Client Matryoshka-truncates and L2-renormalizes to fit — valid for MRL-trained embeddings like Gemini's. A narrower-than- requested response is a hard error: there's no safe way to pad it back to more information.
func NewOpenAICompatible ¶
func NewOpenAICompatible(cfg OpenAICompatibleConfig) (*Client, error)
NewOpenAICompatible builds a Client. Errors if the API key is missing.
type Embedder ¶
type Embedder interface {
// Embed embeds a batch of texts, preserving order.
Embed(ctx context.Context, texts []string) ([]Vector, error)
// Provider identifies the backend, e.g. "edenai".
Provider() string
// Model is the active embedding model id.
Model() string
// Dimension is the embedding width stored in pgvector.
Dimension() int
}
Embedder turns text into vectors.
type OpenAICompatibleConfig ¶
type OpenAICompatibleConfig struct {
APIKey string
BaseURL string
Model string
// Provider is a free-form label used only in Fingerprint (e.g. "edenai",
// "openai") — not sent on the wire.
Provider string
// Dimension is the target pgvector width. Defaults to DefaultDimension.
Dimension int
// HTTPClient overrides the default client (2 minute timeout).
HTTPClient *http.Client
}
OpenAICompatibleConfig configures Client. BaseURL/Model default to EdenAI's EU gateway and gemini-embedding-001 when unset.
type Space ¶ added in v0.3.0
type Space struct {
// Provider identifies the backend that produced the vectors, e.g.
// "xberg". It is part of the identity: the same model served by two
// providers is not reliably the same space.
Provider string
// Model is the embedding model id, e.g. "bge-base-en-v1.5".
Model string
// Dimension is the vector width, and must match the width the schema was
// generated for.
Dimension int
}
Space identifies an embedding space on its own, for vectors that were produced somewhere ragit cannot call — an extraction service that embeds as a side effect of extracting, say, or a batch job that ran last week.
It exists so the identity of those vectors is *declared* rather than formatted by hand. Retrieval filters on the fingerprint, so a corpus written under a string that disagrees by one character with what the query embedder reports returns nothing at all — indistinguishable from an empty corpus, and silent. A struct with three named fields cannot drift that way.
func (Space) Fingerprint ¶ added in v0.3.0
Fingerprint is the canonical identity of the space: provider|model|dimension.
Source Files