embed

package
v0.15.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package embed turns text into a vector, in process, with no network call.

Spec 0012 D1 keeps inference local: a question embedded here never leaves the machine, which is what lets 0010 D5's retention promise stay a promise about storage rather than about a third party. It costs nothing per call, which matters because retrieval runs on every question including the declined ones.

The model is vendored (0012 D8) and loaded straight from the embedded filesystem — the runtime can build a session from a reader, so there is no cache directory to populate and no first-run download to fail.

Index

Constants

View Source
const DefaultModel = "all-MiniLM-L6-v2"

DefaultModel is the vendored model's directory within the asset bundle.

Variables

View Source
var ErrEmptyText = errors.NewSentinel("embed.empty_text", "embed: text produced no tokens")

ErrEmptyText is returned for text the tokenizer reduces to nothing.

Functions

func Bundle

func Bundle() fs.FS

Bundle is the vendored model, as a filesystem rooted at the model directory.

Returned as an fs.FS rather than a path so a larger model can later shadow it by mounting a directory over the same prefix, without this package learning anything about where models come from.

func Cosine

func Cosine(a, b []float32) float64

Cosine is a dot product, because Embed returns normalised vectors.

Types

type Embedder

type Embedder struct {
	// contains filtered or unexported fields
}

Embedder holds a loaded model. It is safe for use by one goroutine at a time.

func Open

func Open(libPath string, models fs.FS, m Model) (*Embedder, error)

Open loads the runtime, the model and its tokenizer.

libPath is the ONNX Runtime shared library. models is where the model lives — pass Bundle() for the vendored one.

func (*Embedder) Close

func (e *Embedder) Close() error

Close releases the session, the environment and the runtime, in that order.

The order is load-bearing, not stylistic. Runtime.Close sets apiFuncs to nil, and Env.Close only releases when runtime.apiFuncs is non-nil — so an env closed after its runtime is silently never released, and the leak looks exactly like correct code. One OrtEnv per Open, for the life of the process.

func (*Embedder) Dims

func (e *Embedder) Dims() int

Dims reports the vector width. Zero until the first successful call, because it is read from the model's output rather than declared.

func (*Embedder) Embed

func (e *Embedder) Embed(ctx context.Context, text string) ([]float32, error)

Embed returns one L2-normalised vector for the text, with no prefix applied.

func (*Embedder) EmbedDoc

func (e *Embedder) EmbedDoc(ctx context.Context, text string) ([]float32, error)

EmbedDoc embeds a passage, applying the model's passage prefix. The emptiness check is here for the same reason as EmbedQuery's.

func (*Embedder) EmbedQuery

func (e *Embedder) EmbedQuery(ctx context.Context, text string) ([]float32, error)

EmbedQuery embeds a question, applying the model's query prefix.

The emptiness check is here rather than left to Embed, because a prefix would defeat it: "query: " prepended to nothing is not empty, so an empty question would sail past the guard and return a vector for the marker alone.

type Model

type Model struct {
	// Dir is the directory holding model.onnx and tokenizer.json.
	Dir string

	Pooling Pooling

	// QueryPrefix and DocPrefix are markers some models require — e5 wants
	// "query: " and "passage: ". Omitting a required prefix degrades results
	// quietly rather than obviously. MiniLM uses neither.
	QueryPrefix string
	DocPrefix   string
}

Model names a model in the bundle and the conventions it was trained with.

func MiniLM

func MiniLM() Model

MiniLM is the vendored default: 384 dimensions, mean pooling, no prefixes.

type Pooling

type Pooling int

Pooling is how a model turns token vectors into one sentence vector.

It is a property of how the model was TRAINED, not a tuning choice. bge uses the CLS token; MiniLM and e5 average the tokens. Choosing the wrong one does not fail — it quietly returns a worse vector.

const (
	MeanPooling Pooling = iota
	CLSPooling
)

The pooling modes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL