Documentation
¶
Overview ¶
Package embed defines provider-agnostic embedding types and the Provider interface that all embedding model backends implement.
It is the parallel of pkg/chat for vector embeddings: the types in this package form the canonical request/response shape used across the SDK, and concrete providers translate to and from them. Providers in pkg/provider/* may implement both chat.Provider and embed.Provider when the underlying backend exposes both capabilities.
Index ¶
- Variables
- func CosineSimilarity(a, b []float32) (float32, error)
- func DotProduct(a, b []float32) (float32, error)
- func Norm(v []float32) float32
- func ProviderOptionsFor[T any](po map[string]any, providerName string) (T, error)
- type Client
- type Embedding
- type Index
- func (idx *Index) Add(id string, vector []float32, meta map[string]any) error
- func (idx *Index) AddEmbedding(id string, e Embedding, meta map[string]any) error
- func (idx *Index) Dim() int
- func (idx *Index) EnforceModel(queryModel string) error
- func (idx *Index) Len() int
- func (idx *Index) Search(query []float32, topK int) ([]SearchHit, error)
- type IndexItem
- type Provider
- type Request
- type Response
- type SearchHit
- type Usage
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoProvider indicates the Client has no underlying Provider configured. ErrNoProvider = errors.New("embed: no provider configured") // ErrInvalidRequest indicates the Request is malformed or missing // required fields (for example, no Model or no Inputs). ErrInvalidRequest = errors.New("embed: invalid request") // unreachable or returned a transient failure. ErrProviderUnavailable = errors.New("embed: provider unavailable") // ErrRateLimited indicates the upstream provider rejected the request // due to rate limiting or quota exhaustion. ErrRateLimited = errors.New("embed: rate limited") // ErrAuthFailed indicates the provider rejected the supplied credentials. ErrAuthFailed = errors.New("embed: authentication failed") // ErrUnsupported indicates the provider does not support a requested // capability. ErrUnsupported = errors.New("embed: unsupported operation") // ErrModelMismatch indicates an embedding produced by one model is // being mixed with embeddings produced by another. Cosine distances // across heterogeneous models are not meaningful, so the SDK refuses // the operation rather than silently producing garbage scores. ErrModelMismatch = errors.New("embed: embedding model mismatch") // ErrDimMismatch indicates an embedding's dimensionality does not // match the rest of the index. ErrDimMismatch = errors.New("embed: embedding dimension mismatch") )
Functions ¶
func CosineSimilarity ¶
CosineSimilarity returns the cosine similarity between two equal-length vectors a and b. The result is in the range [-1, 1] for non-zero vectors: 1 means identical direction, 0 means orthogonal, -1 means opposite.
CosineSimilarity returns ErrInvalidRequest when the vectors differ in length or either vector has zero magnitude (cosine similarity is undefined for the zero vector).
func DotProduct ¶
DotProduct returns the dot product of a and b. Returns ErrInvalidRequest if the vectors differ in length.
func ProviderOptionsFor ¶
ProviderOptionsFor extracts the provider-specific options bucket from a ProviderOptions map (typically Request.ProviderOptions) into a typed value.
See the chat package's equivalent helper for the full description; the behaviour is identical.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a thin, provider-agnostic facade over a Provider. It centralises concerns that are independent of the underlying backend and provides a single entry point that higher-level code can depend on.
func NewClient ¶
NewClient returns a Client backed by the given Provider. The Provider may be nil; in that case the Client's methods will return ErrNoProvider.
func (*Client) Embed ¶
Embed produces embeddings for req.Inputs by delegating to the underlying Provider. If the Client or its Provider is nil, Embed returns ErrNoProvider. If req.Inputs is empty, Embed returns ErrInvalidRequest.
func (*Client) EmbedOne ¶
EmbedOne is a convenience wrapper around Embed for the single-input case. It returns the produced embedding, the request's usage, and any error.
EmbedOne returns ErrNoProvider when the Client has no provider, and ErrInvalidRequest when value is empty or the provider returns no embeddings.
type Embedding ¶
Embedding is a single embedding vector produced for one input in a Request.
Index identifies which entry in Request.Inputs this vector corresponds to.
type Index ¶
Index is a minimal in-memory vector index that enforces a single embedding model across all stored items. Embeddings produced by different models are not directly comparable, so Index refuses to mix them — callers must produce queries with the same Model that was used to build the index.
Index is intended for small/medium workloads (tens of thousands of items). For larger corpora, persist to a vector database.
func NewIndex ¶
NewIndex returns an empty Index bound to the given embedding model. model must be non-empty.
func (*Index) Add ¶
Add inserts an item into the index. Returns ErrDimMismatch when the vector's dimensionality differs from previously-added items, and ErrInvalidRequest for empty IDs or empty vectors.
func (*Index) AddEmbedding ¶
AddEmbedding adds an Embedding to the index using its Vector. It is a convenience for use with Provider.Embed results.
func (*Index) Dim ¶
Dim reports the dimensionality of vectors stored in the index, or 0 if no items have been added yet.
func (*Index) EnforceModel ¶
EnforceModel returns ErrModelMismatch if queryModel differs from the model bound to the index. Callers should call EnforceModel before performing a search whose query vector was produced by a separate embedding call, to catch model drift early.
func (*Index) Search ¶
Search returns the topK most-similar items to query by cosine similarity, sorted descending by Score. topK <= 0 returns an empty result. Returns ErrDimMismatch when the query vector dimensionality differs from the index, and ErrInvalidRequest when the index is empty or the query vector is empty.
Search does NOT validate that the query was produced by Index.Model — call EnforceModel separately when you have the query model available.
type IndexItem ¶
IndexItem is a single entry stored in an Index: an opaque identifier, an embedding vector, and arbitrary application metadata.
type Provider ¶
type Provider interface {
// Name returns a short, stable identifier for the provider
// (for example, "openai", "ollama").
Name() string
// Embed produces one embedding vector per entry in req.Inputs, in the
// same order.
Embed(ctx context.Context, req Request) (Response, error)
}
Provider is implemented by embedding model backends. Implementations translate between the provider-agnostic Request/Response types defined in this package and their underlying API.
type Request ¶
type Request struct {
Model string `json:"model"`
Inputs []string `json:"inputs"`
ProviderOptions map[string]any `json:"provider_options,omitempty"`
}
Request is a provider-agnostic embedding request.
Inputs is a batch of one or more strings to embed; providers must produce one Embedding per input, preserving order via Embedding.Index.
ProviderOptions carries provider-specific options keyed by provider name (e.g. "ollama", "gemini"). See chat.ProviderOptionsFor for the extraction helper; embed providers use the same pattern.
type Response ¶
type Response struct {
Model string `json:"model,omitempty"`
Embeddings []Embedding `json:"embeddings"`
Usage Usage `json:"usage"`
}
Response is the result of an embedding request. Embeddings appear in the same order as Request.Inputs.
Source Files