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 an embedding space: provider|model|dimension. 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.
Source Files