Crate embedrs 

embedrs

Unified embedding solution — cloud APIs + local inference through one interface. Opinionated defaults backed by benchmark data.

Design: just works (好用就好用)

• local() → all-MiniLM-L6-v2 (23MB, free, no API key)
• cloud(key) → OpenAI text-embedding-3-small (best discrimination, cheapest)
• Both produce the same EmbedResult — write code once, switch backends in one line

Defaults chosen by 8-dimension benchmark across 8 models. See benchrs.

Quick start

// cloud — one key, done
let client = embedrs::cloud("sk-...");
let result = client.embed(vec!["hello world".into()]).await?;
println!("dimensions: {}", result.embeddings[0].len());

With the local feature enabled:

// local — zero config, free, 23MB model downloaded on first use
let client = embedrs::local();
let result = client.embed(vec!["hello world".into()]).await?;

Batch embedding

let client = embedrs::cloud("sk-...");
let texts: Vec<String> = (0..5000).map(|i| format!("text {i}")).collect();
let result = client.embed_batch(texts)
    .concurrency(5)
    .await?;

Provider fallback

Chain fallback providers for automatic failover:

let client = embedrs::Client::openai("sk-...")
    .with_fallback(embedrs::Client::cohere("cohere-key"));
// if OpenAI fails, automatically tries Cohere
let result = client.embed(vec!["hello".into()]).await?;

Cost tracking

Enable the cost-tracking feature to get estimated cost per request via tiktoken pricing data. The Usage::cost field will be Some(f64) for models with pricing info, None otherwise.

embedrs = { version = "0.2", features = ["cost-tracking"] }

Error handling

All fallible operations return Result<T>. Match on Error variants for fine-grained control:

• Error::Api — API returned an error status (e.g., 429 rate limit, 401 unauthorized)
• Error::Timeout — request exceeded the configured timeout
• Error::Http — network-level failure
• Error::Json — response body could not be parsed
• Error::InputTooLarge — input exceeded the provider’s batch size limit

Similarity

let a = vec![1.0, 0.0, 0.0];
let b = vec![0.0, 1.0, 0.0];
let sim = embedrs::cosine_similarity(&a, &b);
assert!(sim.abs() < 1e-6);

Re-exports

pub use backoff::BackoffConfig;

pub use client::Client;

pub use client::EmbedResult;

pub use error::Error;

pub use error::Result;

pub use similarity::cosine_similarity;

pub use similarity::dot_product;

pub use similarity::euclidean_distance;

pub use usage::Usage;

Modules

backoff

batch

client

error

prelude

Prelude for convenient imports.

similarity

usage

Enums

InputType

The type of input being embedded, used by providers that support it.

Functions

cloud

Create a cloud embedding client with the recommended default provider (OpenAI text-embedding-3-small).