Documentation
¶
Overview ¶
Package embed generates sentence embeddings with a local ONNX model (all-MiniLM-L6-v2, 384-dim). Inference runs fully in-process against a single ONNX Runtime session — no network, no API key. The runtime library and model files are downloaded once (see download.go) and cached under the OS cache dir (see paths.go).
Index ¶
- Constants
- func Check() error
- func CosineSim(a, b Vec) float64
- func DownloadAll(logf func(string, ...any)) error
- func DownloadModel(logf func(string, ...any)) error
- func DownloadOrt(logf func(string, ...any)) error
- func ModelCacheDir() string
- func OrtCacheDir() string
- func OrtDownloadURL() string
- func OrtLibFilename() string
- func RepresentationID() string
- type Vec
Constants ¶
const ( ModelURL = "https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx" TokenizerURL = "https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main/tokenizer.json" //nolint:gosec // G101 false positive: a public asset URL, not a credential )
ModelURL and TokenizerURL are where `semantic init` fetches the embedding model. ModelURL is the full model (~86MB); the quantized model (model_quantized.onnx) is ~23MB.
const OrtVersion = "1.26.0"
OrtVersion is the ONNX Runtime release whose C API onnxruntime_go v1.31.0 is built against. The two are coupled: the binding compiles against one version of the headers and dlopens whatever this constant downloaded, so bumping the Go module without bumping this constant produces a binary that loads a library it was not compiled for. Nothing in CI catches that — the tests skip inference when no model is installed — so the versions move together, in one commit, or not at all.
Variables ¶
This section is empty.
Functions ¶
func Check ¶
func Check() error
Check reports whether the ONNX runtime library and model files are all present on disk, without initializing the runtime. Returns nil when embedding is ready, or an error naming the first missing piece — suitable for `semantic status`. Get performs the same checks lazily.
func CosineSim ¶
CosineSim returns cosine similarity in [-1, 1]. Vectors from Get are already L2-normalized, so for those this reduces to the dot product, but the full formula is kept so callers can pass un-normalized inputs.
func DownloadAll ¶
DownloadAll downloads the ONNX Runtime library and model files. logf receives progress messages.
func DownloadModel ¶
DownloadModel downloads and caches model.onnx and tokenizer.json.
func DownloadOrt ¶
DownloadOrt downloads and caches the ONNX Runtime shared library.
func ModelCacheDir ¶
func ModelCacheDir() string
ModelCacheDir returns the directory where model files are cached. $SEMANTIC_MODEL_DIR overrides.
func OrtCacheDir ¶
func OrtCacheDir() string
OrtCacheDir returns the directory where the ONNX Runtime library is cached.
The version is part of the path. The binding is compiled against one release of the C API and will not load a library from another, so a single unversioned path would make an upgrade find the old file already present, skip the download, and fail at the first embed with "Error setting ORT API base". Keying by version makes the upgrade fetch what it needs and leaves the superseded library sitting harmlessly beside it.
func OrtDownloadURL ¶
func OrtDownloadURL() string
OrtDownloadURL returns the GitHub release URL for the ORT shared library archive for the current platform.
func OrtLibFilename ¶
func OrtLibFilename() string
OrtLibFilename returns the platform-appropriate shared library filename.
func RepresentationID ¶
func RepresentationID() string
RepresentationID names the vector space this package produces. The index stores it and rebuilds itself when it stops matching, so anything that changes what Get returns for the same input must be reflected here.
Every component is load-bearing:
- the checkpoint, because different weights mean different vectors;
- the pooling and normalization, because mean-vs-CLS pooling or dropping the L2 norm rewrites the space without changing its dimension;
- the dimension, which is the one mismatch that would fail loudly anyway;
- the sequence cap, because raising it changes the vector for every chunk long enough to have been truncated at the old cap — silently, and only for the long chunks, which is the worst kind of drift to debug.
It is a function rather than a const so it stays derived from the constants it names. A hand-written string would be free to drift from them, which is the exact failure this guards against.
Types ¶
type Vec ¶
type Vec []float32
Vec is a float32 embedding vector.
func Get ¶
Get returns a normalized embedding vector for text using the local ONNX model. Returns an error if the model is not installed — run the binary's `init` command to download it (~23 MB).
v1 has no warm daemon: every process pays the ONNX session cold-start (~800ms) on its first Get. The session then stays warm for the life of the process, so batch indexing amortizes the cost.
Source Files