Embedding Models

Embedding converts text into binary vectors for encrypted storage and search. The embed_len dimension must match the value set on your ExecutionContext.

Supported providers:

• Ollama — local, no API key required

• Sentence Transformers — local, models downloaded from Hugging Face (requires [embedding] extra)

• OpenAI — cloud-based

For end-to-end privacy, run Ollama or Sentence Transformers locally. OpenAI can be used when privacy is not a concern.

The INFERENCE_API_KEY environment variable is read automatically when api_key is not passed explicitly.

Ollama

from xtrace_sdk.x_vec.inference.embedding import Embedding

embed = Embedding("ollama", "mxbai-embed-large", 1024)
vector = await embed.bin_embed("some text")

For Ollama setup instructions, see https://ollama.com/docs/installation.

Sentence Transformers

Models are downloaded from Hugging Face on first use. See https://www.sbert.net/docs/pretrained_models.html for available models. Requires pip install "xtrace-ai-sdk[embedding]".

from xtrace_sdk.x_vec.inference.embedding import Embedding

embed = Embedding("sentence_transformer", "mixedbread-ai/mxbai-embed-large-v1", 512)
vector = await embed.bin_embed("some text")

OpenAI

Set your OpenAI API key via the INFERENCE_API_KEY environment variable or pass it directly as api_key.

from xtrace_sdk.x_vec.inference.embedding import Embedding

embed = Embedding("openai", "text-embedding-3-small", 1536)
vector = await embed.bin_embed("some text")

Bring Your Own Vectors

If you already have float vectors from another source, convert them to the binary format XTrace expects using Embedding.float_2_bin. The length of the resulting list must match embed_len on your homomorphic client.

from xtrace_sdk.x_vec.inference.embedding import Embedding

your_vector = [0.1, -0.2, 0.3, ...]   # list of floats, length = embed_len
binary_vector = Embedding.float_2_bin(your_vector)