kjarni::embedder

High-level text embedding API.

Generate dense vector embeddings for semantic search, clustering, and similarity.

Quick Start

use kjarni::embedder;

// One-liner
let embedding = embedder::embed("minilm-l6-v2", "Hello world").await?;

// Builder pattern
let embedder = Embedder::builder("nomic-embed-text")
    .gpu()
    .normalize(true)
    .pooling(PoolingStrategy::Mean)
    .build()
    .await?;

let embedding = embedder.embed("Hello world").await?;
let similarity = embedder.similarity("text1", "text2").await?;

Embedder

pub struct Embedder

High-level text embedder.

Generates dense vector representations of text for semantic search, clustering, and similarity tasks.

builder

pub fn builder(model: impl Into<String>) -> EmbedderBuilder

Create a builder for a model.

from_preset

pub fn from_preset(preset: &EmbedderPreset) -> EmbedderBuilder

Create a builder from a preset.

new

pub async fn new(model: &str) -> EmbedderResult<Self>

Create an Embedder with default settings.

from_path

pub fn from_path(path: impl Into<std::path::PathBuf>) -> EmbedderBuilder

Load an embedder from a local path.

Example

let embedder = Embedder::from_path("/models/my-custom-encoder")
    .build()
    .await?;

embed

pub async fn embed(&self, text: &str) -> EmbedderResult<Vec<f32>>

Embed a single text.

embed_with_config

pub async fn embed_with_config(&self, text: &str, overrides: &EmbeddingOverrides) -> EmbedderResult<Vec<f32>>

Embed with custom overrides.

embed_batch_flat

pub async fn embed_batch_flat(&self, texts: &[&str]) -> EmbedderResult<(Vec<f32>, usize, usize)>

embed_batch

pub async fn embed_batch(&self, texts: &[&str]) -> EmbedderResult<Vec<Vec<f32>>>

Embed multiple texts.

embed_batch_with_config

pub async fn embed_batch_with_config(&self, texts: &[&str], overrides: &EmbeddingOverrides) -> EmbedderResult<Vec<Vec<f32>>>

Embed multiple texts with custom overrides.

similarity

pub async fn similarity(&self, text1: &str, text2: &str) -> EmbedderResult<f32>

Compute cosine similarity between two texts.

similarities

pub async fn similarities(&self, query: &str, documents: &[&str]) -> EmbedderResult<Vec<f32>>

Compute similarities between a query and multiple documents.

rank_by_similarity

pub async fn rank_by_similarity(&self, query: &str, documents: &[&str]) -> EmbedderResult<Vec<(usize, f32)>>

Rank documents by similarity to a query.

model_type

pub fn model_type(&self) -> ModelType

model_name

pub fn model_name(&self) -> &str

device

pub fn device(&self) -> Device

dimension

pub fn dimension(&self) -> usize

Get the embedding dimension.

max_seq_length

pub fn max_seq_length(&self) -> usize

Get maximum sequence length.

EmbedderBuilder

pub struct EmbedderBuilder

Builder for configuring and constructing an Embedder.

new

pub fn new(model: impl Into<String>) -> Self

Create a new builder for the specified model.

from_preset

pub fn from_preset(preset: &EmbedderPreset) -> Self

Create a builder from a preset.

cpu

pub fn cpu(mut self) -> Self

Run on CPU

gpu

pub fn gpu(mut self) -> Self

Run on GPU.

auto_device

pub fn auto_device(mut self) -> Self

Auto-select device.

with_context

pub fn with_context(mut self, context: Arc<WgpuContext>) -> Self

Provide a pre-created WgpuContext.

cache_dir

pub fn cache_dir(mut self, path: impl Into<PathBuf>) -> Self

Set custom cache directory.

model_path

pub fn model_path(mut self, path: impl Into<PathBuf>) -> Self

Load model from a local path.

model

pub fn model(mut self, model: impl Into<String>) -> Self

Set model name from registry.

load_config

pub fn load_config(mut self, config: LoadConfig) -> Self

Set model loading configuration.

with_load_config

pub fn with_load_config<F>(mut self, f: F) -> Self where F: FnOnce(LoadConfigBuilder) -> LoadConfigBuilder,

Configure loading with a builder.

download_policy

pub fn download_policy(mut self, policy: DownloadPolicy) -> Self

Set download policy.

offline

pub fn offline(mut self) -> Self

Never download models.

pooling

pub fn pooling(mut self, strategy: PoolingStrategy) -> Self

Set default pooling strategy.

normalize

pub fn normalize(mut self, normalize: bool) -> Self

Set whether to normalize embeddings.

max_length

pub fn max_length(mut self, max_length: usize) -> Self

Set maximum sequence length.

overrides

pub fn overrides(mut self, overrides: EmbeddingOverrides) -> Self

Apply full overrides.

quiet

pub fn quiet(mut self, quiet: bool) -> Self

Suppress non-error output.

build

pub async fn build(self) -> EmbedderResult<Embedder>

Build the Embedder.

EmbedderPreset

pub struct EmbedderPreset

An embedding model preset.

Fields

• pub name: &'static str,: Preset name.
• pub model: &'static str,: CLI model name.
• pub dimension: usize,: Embedding dimension.
• pub default_pooling: PoolingStrategy,: Default pooling strategy.
• pub normalize_default: bool,: Whether to normalize by default.
• pub recommended_device: KjarniDevice,: Recommended device.
• pub memory_mb: usize,: Approximate memory in MB.
• pub description: &'static str,: Description.

EmbeddingOverrides

pub struct EmbeddingOverrides

Overrides for embedding behavior.

Fields

• pub pooling: Option<PoolingStrategy>,: Pooling strategy (model default if None).
• pub normalize: Option<bool>,: L2 normalize output (default: true for most models).
• pub max_length: Option<usize>,: Truncate inputs longer than this.

EmbedderError

pub enum EmbedderError

Errors specific to embedding.

Variants

• UnknownModel(String),: Model not found.
• IncompatibleModel: Model cannot embed.
• ModelNotDownloaded(String),: Model not downloaded.
• DownloadFailed: Download failed.
• LoadFailed: Load failed.
• EmbeddingFailed(#[from] anyhow::Error),: Embedding failed.
• GpuUnavailable,: GPU unavailable.
• InvalidConfig(String),: Invalid configuration.

EmbedderResult

pub type EmbedderResult<T> = Result<T, EmbedderError>

Result type for embedder operations.

EmbedderTier

pub enum EmbedderTier

Tier-based preset selection.

Variants

• Small,: Smallest, fastest.
• Medium,: Balanced.
• Large,: Highest quality.

resolve

pub fn resolve(&self) -> &'static EmbedderPreset

Resolve tier to default preset.

available_models

pub fn available_models() -> Vec<&'static str>

List all available embedding models.

embed

pub async fn embed(model: &str, text: &str) -> EmbedderResult<Vec<f32>>

Embed a single text using the specified model.

Example

let embedding = kjarni::embedder::embed("minilm-l6-v2", "Hello world").await?;
println!("Dimension: {}", embedding.len());

is_embedding_model

pub fn is_embedding_model(model: &str) -> EmbedderResult<()>

Check if a model is valid for embedding.

similarity

pub async fn similarity(model: &str, text1: &str, text2: &str) -> EmbedderResult<f32>

Compute cosine similarity between two texts.

embedder::presets

Versioned presets for embedding models.

ALL_V1_PRESETS

pub const ALL_V1_PRESETS: &[&EmbedderPreset] = &[&EMBEDDING_SMALL_V1, &EMBEDDING_NOMIC_V1]

All V1 presets.

EMBEDDING_NOMIC_V1

pub const EMBEDDING_NOMIC_V1: EmbedderPreset = EmbedderPreset

Nomic embedding model

EMBEDDING_SMALL_V1

pub const EMBEDDING_SMALL_V1: EmbedderPreset = EmbedderPreset

find_preset

pub fn find_preset(name: &str) -> Option<&'static EmbedderPreset>

Find a preset by name.