embeddings

package module
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: BSD-3-Clause Imports: 25 Imported by: 3

README

go-embeddings

Go package defining a common interface for generating text and image embeddings.

Documentation

godoc is currently incomplete.

Motivation

This is a simple abstraction library, written in Go, around a variety of services which produce vector embeddings. There are many such libraries and this one is ours. It tries to be the "simplest dumbest" thing for the most common operations and data needs. These ideas are encapsulated in the EmbeddingsRequest and EmbeddingsResponse types.

type EmbeddingsRequest struct {
	Id    string `json:"id,omitempty"`
	Model string `json:"model"`
	Body  []byte `json:"body"`
}

type EmbeddingsResponse[T Float] interface {
	Id() string
	Model() string
	Embeddings() []T
	Dimensions() int32
	Precision() string
	Created() int64
}

The default implementation of the EmbeddingsResponse interface is the CommonEmbeddingsResponse type:

type CommonEmbeddingsResponse[T Float] struct {
	EmbeddingsResponse[T] `json:",omitempty"`
	CommonId              string `json:"id,omitempty"`
	CommonEmbeddings      []T    `json:"embeddings"`
	CommonModel           string `json:"model"`
	CommonCreated         int64  `json:"created"`
	CommonPrecision       string `json:"precision"`
}

While not specific to SFO Museum this package is targeted at the kinds of things SFO Museum needs to today meaning it may be lacking features you need or want.

Design

To account for the fact that most embeddings models still return float32 vector data but an increasing number of models return float64 vectors this package wraps both options in a Float interface.

type Float interface{ ~float32 | ~float64 }

That Float is then used as a generic value (for embeddings) in a common EmbeddingsResponse interface:

type EmbeddingsResponse[T Float] interface {
	Id() string
	Model() string
	Embeddings() []T
	Dimensions() int32
	Precision() string
	Created() int64
}

That interface is then used as the return value for an Embedder interface:

type Embedder[T Float] interface {
	TextEmbeddings(context.Context, *EmbeddingsRequest) (EmbeddingsResponse[T], error)
	ImageEmbeddings(context.Context, *EmbeddingsRequest) (EmbeddingsResponse[T], error)
}

This means that you need to specify the float type you want the interface to return when you instantiate that interface. For example:

ctx := context.Backgroud()

uri32 := "ollama://?model=embeddinggemma"
uri64 := "encoderfile://"

cl, _ := embeddings.NewEmbedder[float32](ctx, uri32)
cl, _ := embeddings.NewEmbedder[float64](ctx, uri64)

There are also handy NewEmbedder32 and NewEmbedder64 methods which are little more than syntactic sugar. For example:

ctx := context.Backgroud()

uri32 := "ollama://?model=embeddinggemma"
uri64 := "encoderfile://"

cl, _ := embeddings.NewEmbedder32(ctx, uri32)
cl, _ := embeddings.NewEmbedder64(ctx, uri64)

The NewEmbedder, NewEmbedder32 and NewEmbedder64 all have the same signature: A context.Context instance and a URI string used to configure and instantiate the underlying embeddings provider implementation. These are discussed in detail below.

Both the TextEmbeddings and ImageEmbeddings methods take the same input, a EmbeddingsRequest struct:

type EmbeddingsRequest struct {
	Id    string `json:"id,omitempty"`
	Model string `json:"model"`
	Body  []byte `json:"body"`
}

As mentioned both methods return an EmbeddingsResponse[T] instance. The default implementation of the EmbeddingsResponse[T] interface used by this package is the CommonEmbeddingsResponse type. See response.go for details.

Example

Error handling omitted for the sake of brevity.

import (
	"context"
	"encoding/json"
	"os"

	"github.com/sfomuseum/go-embeddings"
)

func main() {

	ctx := context.Background()

	emb, _ := embeddings.NewEmbedder32(ctx, "ollama://?model=embeddinggemma")

	req := &embeddings.EmbeddingsRequest{
		Body: []byte("Hello world"),
	}

	rsp, _ := emb.TextEmbeddings(ctx, req)

	enc := json.NewEncoder(os.Stdout)
	enc.Encode(rsp)

Which would return the following:

{
  "embeddings": [
    -0.21400317549705505,
    0.02651195414364338,
    ... more embeddings
    -0.04678588733077049,
    -0.042774248868227005
  ],
  "model": "ollama/embeddinggemma",
  "created": 1771985811,
  "precision": "float32"
}

Precision

The convention for precision values is a string, for example "float32". Typically an embeddings service will return vector embeddings with a single precision but the Embedder interface allows you to derive embeddings as either float32 or float64 value. In order to preserve the origin precision information if embeddings are requested in a precision other than that generated by a service the requested precision will be appened to the origin value.

For example, if you request float64 values from a service that returns float32 values those data will be recast and the precision string will be updated to read "float32#as-float64".

Implementations

encoderfile://

Derive vector embeddings from an instance of the Mozilla encoderfile application, running as an HTTP server.

encoderfile://?{PARAMETERS}
Name Value Required Notes
client-uri string no The URI for the embedderfile HTTP server endpoint. Default is http://localhost:8080. The gRPC server endpoint provided by encoderfile is not supported yet.
See also
llamafile://

Derive vector embedding from an instance of the Mozilla llamafile application. Note that newer versions of llamafile not longer expose an interface for deriving embeddings so this implementation will only work with older builds. See the encoderfile:// implementation for an alternative.

llamafile://?{PARAMETERS}
Name Value Required Notes
client-uri string no The URI for the llamafile HTTP server endpoint. Default is http://localhost:8080.
See also
mlxclip://

Derive vector embeddings from a Python script using the harperreed/mlx_clip library. The option requires a device using an Apple Silicon chip and involves a non-zero manual set up process discussed below.

Set up

The set up process for using mlx_clip is involved. The first step is to create a Python virtual environment:

$> python -mvenv /usr/local/src/mlxclip
$> cd  /usr/local/src/mlxclip
$> bash ./bin/activate

Next create some sub-folders used to store dependencies and data:

$> mkdir src
$> mkdir -p data/openai/clip-vit-base-patch32

First, install the mlx-data package:

$> cd /usr/local/src/mlxclip/src
$> git clone git@github.com:ml-explore/mlx-data.git
$> cd mlx-data
$> ../../bin/python install setup.py

Next, install the MLX clip package from the mlx-examples package:

$> cd /usr/local/src/mlxclip/src
$> git clone git@github.com:ml-explore/mlx-examples.git
$> cd mlx-examples/clip
$> ../../bin/pip install -r requirements.txt
$> ../../bin/python ./convert.py --mlx-path /usr/local/src/mlxclip/data/openai/clip-vit-base-patch32

Finally install the harperreed/mlx_clip package and copy it to the root of your virtual environment:

$> cd /usr/local/src/mlxclip/src
$> git clone git@github.com:harperreed/mlx_clip.git
$> cd mlx_clip
$> ../../bin/pip install -r requirements.txt
$> cp -r mlx_clip ../../

At this point you should be ready to use the command line tools. By the time you read this something may have changed or there may be additional steps to account for your environment. This is what has worked for me so far.

Command line (mlxclip://)
mlxclip://{PATH_TO_EMBEDDINGS_DOT_PY}?{PARAMETERS}

Valid query parameters are:

Name Value Required Notes
model string yes The path to directory with MLX-compatible model data.
python string no The path to the Python runtime to use. For example one created by a Python virtual environment.

The mlxclip:// scheme will derive embeddings from a command line Python script (details below). For example:

./bin/embeddings \
	-client-uri 'mlxclip:///usr/local/src/mlxclip/mlx_cli.py?model=/usr/local/src/mlxclip/data/openai/clip-vit-base-patch32&python=/usr/local/src/mlxclip/bin/python' \
	image \
	test20.jpg
	
{"embeddings":[0.0049408292,0.034288883,... and so on
Set up

Copy the contents of mlxclip_cli_py.txt to /usr/local/src/mlxclip/mlxclip_cli.py.

Client-server (mlxclip-client://)
mlxclip-client://?{PARMETERS}

Valid query parameters are:

Name Value Required Notes
server-uri string no The URI of the mlx clip server producing embeddings. Default is http://localhost:5000.

For example:

$> echo "Hello world" | ./bin/embeddings -client-uri 'mlxclip-client://' text -
{"embeddings":[0.008282159, ... and so on
Set up

In addition to the set up steps above you will also need to do the following to set up the server that the (mlx) client will connect to:

$> cd /usr/local/src/mlxclip
$> bin/pip install fastapi uvicorn asyncio

Now copy the contents of mlxclip_server_py.txt to /usr/local/src/mlxclip/mlxclip_server.py. To start the server you would do this (adjusting as necessary for your environment):

$> ./bin/python ./mlx_server.py -h
usage: mlx_server.py [-h] --model_dir MODEL_DIR [--host HOST] [--port PORT] [--max-workers MAX_WORKERS]

MLX-Clip FastAPI embedding service

options:
  -h, --help            show this help message and exit
  --model_dir MODEL_DIR
                        Path to MLX CLIP model directory
  --host HOST           The host the service will listen on.
  --port PORT           The port the service will listen on.
  --max-workers MAX_WORKERS
                        The maximum number of concurrent mlx processes.
			
$> ./bin/python ./mlx_server.py --model_dir=data/openai/clip-vit-base-patch32/
INFO:__main__:Loading MLX-CLIP model from data/openai/clip-vit-base-patch32/
INFO:mlx_clip:Loading CLIP model from directory: data/openai/clip-vit-base-patch32/
INFO:     Started server process [22613]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:5000 (Press CTRL+C to quit)
INFO:     127.0.0.1:60982 - "POST /embeddings/image HTTP/1.1" 200 OK
INFO:     127.0.0.1:60983 - "POST /embeddings/image HTTP/1.1" 200 OK
INFO:     127.0.0.1:60984 - "POST /embeddings HTTP/1.1" 200 OK
See also
mobileclip://

Derive vector embeddings from the MobileCLIP models exposed via an instance of the sfomuseum/swift-mobileclip gRPC endpoint.

mobileclip://?{PARAMETERS}
Name Value Required Notes
client-uri string yes The URI for the swift-mobileclip gRPC server endpoint. Default is grpc://localhosr:8080.
See also
null://

Derive null (empty) vector embeddings. This is a "placeholder" implementation that will always return a zero-length list of embeddings.

null://
ollama://

Derive vector embeddings from an instance of the Ollama application.

ollama://?{PARAMETERS}
Name Value Required Notes
client-uri string no Default is http://localhost:11434.
model string yes The name of the model to use for generating embeddings.
See also
openclip://

Derive vector embeddings from a web service exposing the OpenCLIP model and library.

Set up

Create a new Python virtual environment and install the necessary dependencies:

$> python -m venv openclip
$> cd openclip/
$> bash bin/activate
$> bin/pip install open_clip_torch Pillow
Command-line (openclip://)

This option is not suported yet.

Client-server (openclip-client://)
openclip-client://?{PARAMETERS}
Name Value Required Notes
server-uri string no The URI of the HTTP endpoint exposing the OpenCLIP model functionality. Default is http://localhost:5000.

Derive OpenCLIP embeddings from an HTTP service. For example:

$> echo "hi there" | ./bin/embeddings -client-uri 'openclip-client://' text -
{"embeddings":[-0.24023438,0.09472656,0.12695312, ... and so on
Set up

In addition to the set up steps above you will also need to do the following to set up the server that the (openclip) client will connect to:

$> cd /usr/local/src/siglip
$> bin/pip install fastapi uvicorn

Then, copy the included code in openclip_server_py.txt in to a file called openclip_server.py and launch it as follows:

$> ./bin/python ./openclip_server.py
INFO:     Started server process [67888]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:5000 (Press CTRL+C to quit)
INFO:     127.0.0.1:61064 - "POST /embeddings HTTP/1.1" 200 OK
route://

Derive embeddings by routing requests to different underlying clients depending on the requested model. Clients and models are defined in one or more ?client-uri= parameters which take the form of:

route://?client-uri=CLIENT_URI...MODEL...MODEL

Any given ?client-uri= parameter must have one or more {MODEL} definitions.

For example:

$> echo "hello world" | \
	./bin/embeddings \
	-client-uri 'route://?client-uri=siglip-client://?server-uri=http://10.28.67.136:8087...google/siglip2-so400m-patch14-384&client-uri=siglip-client://?server-uri=http://10.28.67.136:8086...google/siglip2-so400m-patch16-naflex' \
	-model google/siglip2-so400m-patch16-naflex \
	text \
	-
siglip://

Derive vector embeddings from a Python script using the Google SigLIP (2) models.

Set up

Set up is not yet automated so you'll need to do something like this:

$> cd /usr/local/src
$> python -m venv siglip
$> cd siglip/
$> bash bin/activate
$> bin/pip install torch transformers pillow protobuf SentencePiece
Command line (siglip://)
siglip://{OPTIONAL_HOST}{PATH_TO_SIGLIP_CLI_PY}?{PARAMETERS}`

Valid query parameters are:

Name Value Required Notes
model string yes The HuggingFace checkpoint URI of the model to use. For example "google/siglip-so400m-patch14-384"
python string no The path to the Python runtime to use. For example one created by a Python virtual environment.

Derive embeddings from a local Python script operating on a siglip model (described below). For example:

$> echo "Hello world" | ./bin/embeddings -client-uri 'siglip://venv/usr/local/src/siglip/embeddings.py?model=google/siglip-base-patch16-224&python=/usr/local/src/siglip/bin/python' text -
{"embeddings":[0.010030805,-0.02573614,0.029724538,... and so on
Set up

Copy the siglip_cli_py.txt file in to a /usr/local/src/siglip/siglip_cli.py (or whatever suits your environment).

Client-server (siglip-client://)
siglip-client://?{PARAMETERS}

Valid parameters are:

Name Value Required Notes
server-uri string no The URI of the HTTP endpoint exposing the SigLIP model functionality. Default is http://localhost:5000.

Derive siglip embeddings from an HTTP service. For example:

$> ./bin/embeddings -client-uri 'siglip-client://' image test.pmg
{"embeddings":[-0.017064538,0.00726526,-0.0042089703 ... and so on
Set up

In addition to the set up steps above you will also need to do the following to set up the server that the (siglip) client will connect to:

$> cd /usr/local/src/siglip
$> bin/pip install fastapi uvicorn

Copy the contents of siglip_server_py.txt to /usr/local/src/siglip/siglip_server.py. To start the server you would do this (adjusting as necessary for your environment):

$> ./bin/python ./siglip_server.py --model_name google/siglip2-so400m-patch16-naflex
INFO:     Started server process [54813]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:5000 (Press CTRL+C to quit)
See also
yzma://

Derive vector embeddings using the hybridgroup/yzma Go package which wraps a local instance of llama.cpp.

yzma://{PATH_TO_YZMA_LIB}?{QUERY_PARAMETERS)

Where {PATH_TO_YZMA} is the path the yzma-specific llama.cpp build. If empty then the code will check for a YZMA_LIB environment variable. If the path remains empty then a temporary directory will be created and an device-specific build will be downloaded. Valid query parameters are:

Name Value Required Notes

| context-size | int | no | Maximum number of tokens in a llama context. If omitted, the default of 0 (use library default) is used. | | batch-size | int | no | Maximum number of tokens processed per batch. If omitted, the default of 0 (use library default) is used. | | pooling | string | no Pooling strategy used to aggregate token embeddings. Accepted values are the same strings that the llama.PoolingType type understands (e.g. "mean", "sum"). The default is "mean". | | processor | string | no | Target CPU instruction set for the downloaded yzma binary (e.g. avx, neon). If omitted, the library will automatically select an appropriate processor. | | version | string | no | The yzma release version to download. The default is "" which corresponding to the most recently tagged release of hybridgroup/yzma. | | model-root | string | no | Directory where the llama model files are stored. If omitted, a subdirectory models of the library root (lib_path) is used. |

For example:

$> ./bin/embeddings \
	-verbose \
	-client-uri 'yzma:///usr/local/sfomuseum/src/yzma-llama2' \
	-model https://huggingface.co/QuantFactory/SmolLM2-135M-GGUF/resolve/main/SmolLM2-135M.Q4_K_M.gguf \
	text README.md

2026/09/04 15:59:19 DEBUG Verbose logging enabled
2026/09/04 15:59:19 DEBUG Reassign batch size based on input old=0 new=6448
{"embeddings":[-0.00427622,-0.00952815,-0.028462801,0.010853989,-0.0005393807 ... and so on

Or to download all the components at runtime:

$> ./bin/embeddings \
	-verbose \
	-client-uri 'yzma://' \
	-model https://huggingface.co/QuantFactory/SmolLM2-135M-GGUF/resolve/main/SmolLM2-135M.Q4_K_M.gguf \
	text README.md

2026/09/04 16:11:07 DEBUG Verbose logging enabled
2026/09/04 16:11:07 DEBUG Download llama arch=arm64 os=darwin proc=metal version=v0.3.0
[##################################################]  100.0% - 10/10 MiB (5.62 MiB/s)
2026/09/04 16:11:16 DEBUG Download model model=https://huggingface.co/QuantFactory/SmolLM2-135M-GGUF/resolve/main/SmolLM2-135M.Q4_K_M.gguf target=/var/folders/_k/h7ndzcyx3dq027gsrg1q45xm0000gn/T/yzma3627492138/models
2026/09/04 16:11:56 DEBUG Reassign batch size based on input old=0 new=6590

{"embeddings":[-0.011574293,-0.009547655, ...and so on

2026/09/04 16:11:58 DEBUG Remove tmp dir path=/var/folders/_k/h7ndzcyx3dq027gsrg1q45xm0000gn/T/yzma3627492138

Tests

Because so many of the implementations above depend on the availability of external, third-party services their tests depend on the presence of Go build tags to run. They are :

Implementation Build tag
encoderfile:// encoderfile
llamafile:// llamafile
mlxclip:// mlxclip
mobileclip:// mobileclip
ollama:// ollama
openclip:// openclip
siglip:// siglip
yzma:// yzma

Documentation

Index

Constants

View Source 
const ROUTE_SEPARATOR string = "..."

ROUTE_SEPARATOR is the token that separates the client URI from the list of model names in the `client-uri` query parameter. It is defined here to make it easy to change the separator without touching every place in the code that uses it.

Variables

View Source 
var NotImplemented = errors.New("Not implemented")

Functions

func AsFloat32 added in v0.0.2 

func AsFloat32(data []float64) []float32

func AsFloat64 added in v0.0.2 

func AsFloat64(data []float32) []float64

func EmbedderSchemes 

func EmbedderSchemes() []string

Schemes returns the list of schemes that have been registered.

func RegisterEmbedder 

func RegisterEmbedder[T Float](ctx context.Context, scheme string, init_func EmbedderInitializationFunc[T]) error

RegisterEmbedder registers 'scheme' as a key pointing to 'init_func' in an internal lookup table used to create new `Embedder` instances by the `NewEmbedder` method.

Types

type CommonEmbeddingsResponse added in v0.1.0 

type CommonEmbeddingsResponse[T Float] struct {
	EmbeddingsResponse[T] `json:",omitempty"`
	CommonId              string `json:"id,omitempty"`
	CommonEmbeddings      []T    `json:"embeddings"`
	CommonModel           string `json:"model"`
	CommonCreated         int64  `json:"created"`
	CommonPrecision       string `json:"precision"`
}

func (*CommonEmbeddingsResponse[T]) Created added in v0.1.0 

func (r *CommonEmbeddingsResponse[T]) Created() int64

func (*CommonEmbeddingsResponse[T]) Dimensions added in v0.1.0 

func (r *CommonEmbeddingsResponse[T]) Dimensions() int32

func (*CommonEmbeddingsResponse[T]) Embeddings added in v0.1.0 

func (r *CommonEmbeddingsResponse[T]) Embeddings() []T

func (*CommonEmbeddingsResponse[T]) Id added in v0.1.0 

func (r *CommonEmbeddingsResponse[T]) Id() string

func (*CommonEmbeddingsResponse[T]) Model added in v0.1.0 

func (r *CommonEmbeddingsResponse[T]) Model() string

func (*CommonEmbeddingsResponse[T]) Precision added in v0.1.0 

func (r *CommonEmbeddingsResponse[T]) Precision() string

type Embedder 

type Embedder[T Float] interface {
	TextEmbeddings(context.Context, *EmbeddingsRequest) (EmbeddingsResponse[T], error)
	ImageEmbeddings(context.Context, *EmbeddingsRequest) (EmbeddingsResponse[T], error)
	Close() error
}

Embedder defines an interface for generating (vector) embeddings

func NewEmbedder 

func NewEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

newEmbedder returns a new `Embedder` instance configured by 'uri'. The value of 'uri' is parsed as a `url.URL` and its scheme is used as the key for a corresponding `EmbedderInitializationFunc` function used to instantiate the new `Embedder`. It is assumed that the scheme (and initialization function) have been registered by the `RegisterEmbedder` method.

func NewEmbedder32 added in v0.1.0 

func NewEmbedder32(ctx context.Context, uri string) (Embedder[float32], error)

func NewEmbedder64 added in v0.1.0 

func NewEmbedder64(ctx context.Context, uri string) (Embedder[float64], error)

func NewEncoderfileEmbedder added in v0.1.0 

func NewEncoderfileEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewLlamafileEmbedder added in v0.1.0 

func NewLlamafileEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewMLXClipEmbedder added in v0.1.0 

func NewMLXClipEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewMLXClipLocalClientEmbedder added in v0.4.0 

func NewMLXClipLocalClientEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewMobileCLIPEmbedder added in v0.1.0 

func NewMobileCLIPEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewNullEmbedder 

func NewNullEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewOllamaEmbedder added in v0.1.0 

func NewOllamaEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewOpenCLIPEmbedder added in v0.1.0 

func NewOpenCLIPEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewRouteEmbedder added in v0.5.0 

func NewRouteEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

NewRouteEmbedder creates a new RouteEmbedder from the supplied URI. The URI must be in the form: 

route://?client-uri=CLIENT_URI…MODEL…MODEL

The client URI may be repeated to register multiple clients. Each client URI is passed to NewEmbedder64 or NewEmbedder32 depending on the precision requested by the scheme suffix.

func NewSigLIPCommandLineEmbedder added in v0.3.0 

func NewSigLIPCommandLineEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewSigLIPLocalClientEmbedder added in v0.3.0 

func NewSigLIPLocalClientEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

func NewYzmaEmbedder added in v0.6.0 

func NewYzmaEmbedder[T Float](ctx context.Context, uri string) (Embedder[T], error)

NewYzmaEmbedder creates a new YzmaEmbedder based on the provided URI.

The URI may include query parameters that configure the embedder. The function downloads the yzma binary if it is not already present and ensures that the model root directory exists. It returns an error if the URI is malformed, the binary cannot be downloaded, or the configuration parameters are invalid. YzmaEmbedder is instantiated by 'uri' which is expected to take the form of: The URI may contain query parameters that configure the embedder. The supported parameters are: 

yzma://{PATH_TO_YZMA_LIB}?{QUERY_PARAMETERS)

Where `{PATH_TO_YZMA}` is the path the yzma-specific llama.cpp build. If empty then the code will check for a `YZMA_LIB` environment variable. If the path remains empty then a temporary directory will be created and an device-specific build will be downloaded. Valid query parameters are:

  • **context-size** – Maximum number of tokens in a llama context. If omitted, the default of 0 (use library default) is used.
  • **batch-size** – Maximum number of tokens processed per batch. If omitted, the default of 0 (use library default) is used.
  • **pooling** – Pooling strategy used to aggregate token embeddings. Accepted values are the same strings that the `llama.PoolingType` type understands (e.g. `"mean"`, `"sum"`). The default is `"mean"`.
  • **processor** – Target CPU instruction set for the downloaded yzma binary (e.g. `avx`, `neon`). If omitted, the library will automatically select an appropriate processor.
  • **version** – The yzma release version to download. The default is `"v0.3.0"`. The value should be a full git tag (e.g. `v0.3.0`), not an empty string.
  • **model-root** – Directory where the llama model files are stored. If omitted, a subdirectory `models` of the library root (`lib_path`) is used.

type EmbedderInitializationFunc 

type EmbedderInitializationFunc[T Float] func(ctx context.Context, uri string) (Embedder[T], error)

EmbedderInitializationFunc is a function defined by individual embedder package and used to create an instance of that embedder

type EmbeddingsRequest added in v0.1.0 

type EmbeddingsRequest struct {
	Id    string `json:"id,omitempty"`
	Model string `json:"model"`
	Body  []byte `json:"body"`
}

type EmbeddingsResponse added in v0.1.0 

type EmbeddingsResponse[T Float] interface {
	Id() string
	Model() string
	Embeddings() []T
	Dimensions() int32
	Precision() string
	Created() int64
}

type EncoderfileEmbedder added in v0.1.0 

type EncoderfileEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

EncoderfileEmbedder implements the `Embedder` interface using an Encoderfile API endpoint to derive embeddings.

func (*EncoderfileEmbedder[T]) ImageEmbeddings added in v0.1.0 

func (e *EncoderfileEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*EncoderfileEmbedder[T]) TextEmbeddings added in v0.1.0 

func (e *EncoderfileEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type Float added in v0.1.0 

type Float interface{ ~float32 | ~float64 }

type LlamafileEmbedder added in v0.1.0 

type LlamafileEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

LlamafileEmbedder implements the `Embedder` interface using an Llamafile API endpoint to derive embeddings.

func (*LlamafileEmbedder[T]) Close added in v0.6.0 

func (e *LlamafileEmbedder[T]) Close() error

func (*LlamafileEmbedder[T]) ImageEmbeddings added in v0.1.0 

func (e *LlamafileEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*LlamafileEmbedder[T]) TextEmbeddings added in v0.1.0 

func (e *LlamafileEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type LocalClient added in v0.3.0 

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

func NewLocalClient added in v0.3.0 

func NewLocalClient(ctx context.Context, uri string) (*LocalClient, error)

type LocalClientEmbeddingRequest added in v0.3.0 

type LocalClientEmbeddingRequest struct {
	Content   string                                  `json:"content,omitempty"`
	ImageData []*LocalClientImageDataEmbeddingRequest `json:"image_data,omitempty"`
}

type LocalClientEmbeddingResponse added in v0.3.0 

type LocalClientEmbeddingResponse struct {
	Model      string    `json:"model,omitempty"`
	Embeddings []float64 `json:"embeddings,omitempty"`
}

type LocalClientImageDataEmbeddingRequest added in v0.3.0 

type LocalClientImageDataEmbeddingRequest struct {
	Id   int64  `json:"id"`
	Data string `json:"data"`
}

type MLXClipEmbedder added in v0.1.0 

type MLXClipEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

func (*MLXClipEmbedder[T]) ImageEmbeddings added in v0.1.1 

func (e *MLXClipEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*MLXClipEmbedder[T]) TextEmbeddings added in v0.1.1 

func (e *MLXClipEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type MLXClipEmbeddingsResponse added in v0.4.0 

type MLXClipEmbeddingsResponse struct {
	Embeddings []float64 `json:"embeddings"`
	Model      string    `json:"model"`
}

type MLXClipLocalClientEmbedder added in v0.4.0 

type MLXClipLocalClientEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

func (*MLXClipLocalClientEmbedder[T]) Close added in v0.6.0 

func (e *MLXClipLocalClientEmbedder[T]) Close() error

func (*MLXClipLocalClientEmbedder[T]) ImageEmbeddings added in v0.4.0 

func (e *MLXClipLocalClientEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*MLXClipLocalClientEmbedder[T]) TextEmbeddings added in v0.4.0 

func (e *MLXClipLocalClientEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type MobileCLIPEmbedder added in v0.1.0 

type MobileCLIPEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

MobileCLIPEmbedder implements the `Embedder` interface using an MobileCLIP API endpoint to derive embeddings.

func (*MobileCLIPEmbedder[T]) Close added in v0.6.0 

func (e *MobileCLIPEmbedder[T]) Close() error

func (*MobileCLIPEmbedder[T]) ImageEmbeddings added in v0.1.0 

func (e *MobileCLIPEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*MobileCLIPEmbedder[T]) TextEmbeddings added in v0.1.0 

func (e *MobileCLIPEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type NullEmbedder 

type NullEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

NullEmbedder implements the `Embedder` interface using an Null API endpoint to derive embeddings.

func (*NullEmbedder[T]) Close added in v0.6.0 

func (e *NullEmbedder[T]) Close() error

func (*NullEmbedder[T]) ImageEmbeddings 

func (e *NullEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*NullEmbedder[T]) TextEmbeddings added in v0.1.0 

func (e *NullEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type OllamaEmbedder added in v0.1.0 

type OllamaEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

OllamaEmbedder implements the `Embedder` interface using an Ollama API endpoint to derive embeddings.

func (*OllamaEmbedder[T]) Close added in v0.6.0 

func (e *OllamaEmbedder[T]) Close() error

func (*OllamaEmbedder[T]) ImageEmbeddings added in v0.1.0 

func (e *OllamaEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*OllamaEmbedder[T]) TextEmbeddings added in v0.1.0 

func (e *OllamaEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type OpenCLIPEmbedder added in v0.1.0 

type OpenCLIPEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

OpenCLIPEmbedder implements the `Embedder` interface using an OpenCLIP API endpoint to derive embeddings.

func (*OpenCLIPEmbedder[T]) Close added in v0.6.0 

func (e *OpenCLIPEmbedder[T]) Close() error

func (*OpenCLIPEmbedder[T]) ImageEmbeddings added in v0.1.0 

func (e *OpenCLIPEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*OpenCLIPEmbedder[T]) TextEmbeddings added in v0.1.0 

func (e *OpenCLIPEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type RouteEmbedder added in v0.5.0 

type RouteEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

RouteEmbedder implements the Embedder interface by routing requests to different underlying clients depending on the requested model. The generic type parameter T must satisfy the Float constraint defined in another file of this package.

The struct embeds an Embedder[T] interface to satisfy the interface but the methods below provide the actual routing logic.

func (*RouteEmbedder[T]) ImageEmbeddings added in v0.5.0 

func (e *RouteEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

ImageEmbeddings implements the Embedder interface. It forwards the request to the underlying client that matches the requested model.

func (*RouteEmbedder[T]) TextEmbeddings added in v0.5.0 

func (e *RouteEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

TextEmbeddings implements the Embedder interface. It forwards the request to the underlying client that matches the requested model.

type SigLIPCommandLineEmbedder added in v0.3.0 

type SigLIPCommandLineEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

func (*SigLIPCommandLineEmbedder[T]) Close added in v0.6.0 

func (e *SigLIPCommandLineEmbedder[T]) Close() error

func (*SigLIPCommandLineEmbedder[T]) ImageEmbeddings added in v0.3.0 

func (e *SigLIPCommandLineEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*SigLIPCommandLineEmbedder[T]) TextEmbeddings added in v0.3.0 

func (e *SigLIPCommandLineEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type SigLIPLocalClientEmbedder added in v0.3.0 

type SigLIPLocalClientEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

func (*SigLIPLocalClientEmbedder[T]) ImageEmbeddings added in v0.3.0 

func (e *SigLIPLocalClientEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

func (*SigLIPLocalClientEmbedder[T]) TextEmbeddings added in v0.3.0 

func (e *SigLIPLocalClientEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

type YzmaEmbedder added in v0.6.0 

type YzmaEmbedder[T Float] struct {
	Embedder[T]
	// contains filtered or unexported fields
}

YzmaEmbedder implements the `Embedder` interface using the `hybridgroup/yzma` package to derive embeddings.

func (*YzmaEmbedder[T]) Close added in v0.6.0 

func (e *YzmaEmbedder[T]) Close() error

Close releases resources held by the yzma backend. It also removes any temporary directories that were created for downloading the yzma binary.

func (*YzmaEmbedder[T]) ImageEmbeddings added in v0.6.0 

func (e *YzmaEmbedder[T]) ImageEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

ImageEmbeddings is not implemented for the yzma backend. It returns the `NotImplemented` error to indicate that image embeddings are unsupported.

func (*YzmaEmbedder[T]) TextEmbeddings added in v0.6.0 

func (e *YzmaEmbedder[T]) TextEmbeddings(ctx context.Context, req *EmbeddingsRequest) (EmbeddingsResponse[T], error)

TextEmbeddings derives embeddings for the text contained in the request. It uses the yzma backend to tokenize the input, create a llama context, and retrieve the embedding vector. The vector is normalised to unit length and returned in the `EmbeddingsResponse`. The response includes the model name, the timestamp of creation, and the precision used.

Source Files

View all Source files

Directories

Path Synopsis
app
embeddings
cmd
embeddings command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.