### Initialize SparseTextEmbedding with Defaults

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Creates a new SparseTextEmbedding instance using the default SPLADE PP v1 model. This is a convenient way to get started.

```rust
use fastembed::{SparseTextEmbedding, SparseInitOptions, SparseModel};

// With defaults (SPLADE PP v1)
let mut model = SparseTextEmbedding::try_new(Default::default())?;
```

--------------------------------

### Example Usage of TextRerank::rerank

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Demonstrates how to initialize TextRerank, provide a query and documents, and then use the rerank method. Results are printed, showing the index, score, and document text.

```rust
use fastembed::{TextRerank, RerankInitOptions, RerankerModel};

let mut model = TextRerank::try_new(Default::default())?;

let query = "What is machine learning?ிகளில்";
let documents = vec![
    "Machine learning is a subset of artificial intelligence.",
    "The weather is sunny today.",
    "ML models learn patterns from data.",
    "I like pizza.",
];

let results = model.rerank(query, documents, true, None)?;

// Results are sorted by score (highest first)
for result in results {
    println!(
        "Index {}: score {:.3} - {}",
        result.index,
        result.score,
        result.document.as_ref().unwrap_or(&"".to_string())
    );
}

// Output (example):
// Index 0: score 0.945 - Machine learning is a subset of artificial intelligence.
// Index 2: score 0.823 - ML models learn patterns from data.
// Index 3: score 0.102 - I like pizza.
// Index 1: score 0.045 - The weather is sunny today.
```

--------------------------------

### Install fastembed with Cargo

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Add the fastembed crate to your project's dependencies using Cargo.

```bash
cargo add fastembed
```

--------------------------------

### Create Image Embedding Model with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes an image embedding model with custom options, including specifying the model and download progress. Use `ImageEmbeddingModel::ClipVitB32` for this example.

```rust
use fastembed::{ImageEmbedding, ImageInitOptions, ImageEmbeddingModel};

// With custom options
let mut model = ImageEmbedding::try_new(
    ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32).with_show_download_progress(true),
)?;
```

--------------------------------

### Create Sparse Text Embedding Model with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes a sparse text embedding model with custom options, including specifying the model and download progress. Use `SparseModel::SPLADEPPV1` for this example.

```rust
use fastembed::{SparseEmbedding, SparseInitOptions, SparseModel, SparseTextEmbedding};

// With custom options
let mut model = SparseTextEmbedding::try_new(
    SparseInitOptions::new(SparseModel::SPLADEPPV1).with_show_download_progress(true),
)?;
```

--------------------------------

### Create Text Reranking Model with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes a text reranking model with custom options, including specifying the model and download progress. Use `RerankerModel::BGERerankerBase` for this example.

```rust
use fastembed::{TextRerank, RerankInitOptions, RerankerModel};

// With custom options
let mut model = TextRerank::try_new(
    RerankInitOptions::new(RerankerModel::BGERerankerBase).with_show_download_progress(true),
)?;
```

--------------------------------

### List Supported Image Models

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Call `ImageEmbedding::list_supported_models` to get a list of all available image embedding models and their metadata.

```rust
pub fn list_supported_models() -> Vec<ModelInfo<ImageEmbeddingModel>>
```

--------------------------------

### Configure Reranker Initialization (Default Model)

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Configures reranker initialization using builder methods, starting with a default model. Allows customization of max length, cache directory, execution providers, intra-thread count, and download progress display.

```rust
RerankInitOptions::new(RerankerModel::BGERerankerBase)
    .with_max_length(256)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

--------------------------------

### Create Text Embedding Model with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes a text embedding model with custom options, including specifying the model and thread count. Use `EmbeddingModel::AllMiniLML6V2` for this example.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};

// With custom options
let mut model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::AllMiniLML6V2).with_show_download_progress(true).with_intra_threads(4),
)?;
```

--------------------------------

### ImageInitOptions Builder Methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Demonstrates how to use the builder pattern to configure ImageInitOptions, allowing customization of cache directory, execution providers, thread count, and download progress display.

```APIDOC
## ImageInitOptions Builder Methods

Use the builder pattern to configure image embedding initialization.

### Example Usage

```rust
ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

### Builder Methods

| Method | Parameter Type | Description |
|---|---|---|
| `with_cache_dir` | `PathBuf` | Set model cache directory |
| `with_execution_providers` | `Vec<ExecutionProviderDispatch>` | Set ONNX Runtime providers |
| `with_intra_threads` | `usize` | Limit CPU thread count |
| `with_show_download_progress` | `bool` | Toggle download progress |
```

--------------------------------

### Bgem3InitOptions Builder Methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Provides builder methods for configuring BgeM3Embedding initialization. Allows customization of max length, cache directory, execution providers, threads, and download progress display.

```APIDOC
## Bgem3InitOptions Builder Methods

### Description
Builder methods for configuring BgeM3Embedding initialization.

### Methods
- `new(Bgem3Model::BGEM3)`: Initializes with the default BGE-M3 model.
- `with_max_length(usize)`: Set max token length (up to 8192).
- `with_cache_dir(PathBuf)`: Set model cache directory.
- `with_execution_providers(Vec<ExecutionProviderDispatch>)`: Set ONNX Runtime providers.
- `with_intra_threads(usize)`: Limit CPU thread count.
- `with_show_download_progress(bool)`: Toggle download progress.
```

--------------------------------

### Get Specific Sparse Model Info

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Retrieves metadata for a specific sparse text embedding model. Pass the desired `SparseModel` variant to get its details.

```rust
pub fn get_model_info(model: &SparseModel) -> ModelInfo<SparseModel>
```

--------------------------------

### Configure Sparse Embedding Initialization

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Builds `SparseInitOptions` with custom settings like max length, cache directory, execution providers, thread count, and download progress visibility.

```rust
SparseInitOptions::new(SparseModel::SPLADEPPV1)
    .with_max_length(256)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

--------------------------------

### Bgem3InitOptions

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Configuration builder for BGE-M3 models. It allows customization of max length, cache directory, and other parameters.

```APIDOC
## Bgem3InitOptions

Configuration builder for BGE-M3 models. Supports:

```rust
Bgem3InitOptions::new(Bgem3Model::BGEM3)
    .with_max_length(2048)
    .with_cache_dir(PathBuf::from("/cache"))
```
```

--------------------------------

### ModelTrait Definition

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Trait for retrieving model metadata. It defines an associated type for the model and a method to get model information.

```rust
pub trait ModelTrait {
    type Model;
    fn get_model_info(model: &Self::Model) -> Option<&ModelInfo<Self::Model>>;
}
```

--------------------------------

### Get Specific Reranker Model Info

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Retrieves metadata for a specific reranker model. Requires a `RerankerModel` enum variant as input.

```rust
pub fn get_model_info(model: &RerankerModel) -> Result<&RerankerModelInfo>
```

--------------------------------

### Configure BGE-M3 Model Initialization

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Use Bgem3InitOptions for BGE-M3 models. Customize max length and cache directory.

```rust
Bgem3InitOptions::new(Bgem3Model::BGEM3)
    .with_max_length(2048)
    .with_cache_dir(PathBuf::from("/cache"))
```

--------------------------------

### Initialize fastembed-rs Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/INDEX.md

Demonstrates the pattern for initializing various embedding types with configurable options like max length, cache directory, execution providers, and thread counts. Use this to set up your embedding models.

```rust
OptionType::new(Model::Variant)
    .with_max_length(256)        // All types except Image
    .with_cache_dir(path)        // All types
    .with_execution_providers()  // All types
    .with_intra_threads(4)       // All types
    .with_show_download_progress(false)  // All types
```

--------------------------------

### Get Specific Bgem3 Model Info

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Retrieves metadata for a specific BGE-M3 variant. Pass the desired Bgem3Model enum variant.

```rust
pub fn get_model_info(model: &Bgem3Model) -> Option<&ModelInfo<Bgem3Model>>
```

--------------------------------

### SparseTextEmbedding::get_model_info

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Retrieves metadata for a specific sparse model. This allows users to get detailed information about a particular model before using it.

```APIDOC
## SparseTextEmbedding::get_model_info

### Description
Retrieves metadata for a specific sparse model.

### Parameters
#### Path Parameters
- **model** (`&SparseModel`) - Required - Sparse model variant

### Return Type
`ModelInfo<SparseModel>` — Model metadata.
```

--------------------------------

### ImageInitOptions Builder Methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Configure options for image models.

```APIDOC
## ImageInitOptions

Image models use `InitOptions<M>` (no max_length parameter).

### Builder Methods

#### with_cache_dir

```rust
pub fn with_cache_dir(mut self, cache_dir: PathBuf) -> Self
```

Sets the model cache directory.

---

#### with_execution_providers

```rust
pub fn with_execution_providers(
    mut self,
    execution_providers: Vec<ExecutionProviderDispatch>,
) -> Self
```

Configures ONNX Runtime execution providers.

---

#### with_intra_threads

```rust
pub fn with_intra_threads(mut self, intra_threads: usize) -> Self
```

Limits CPU thread count for inference.

---

#### with_show_download_progress

```rust
pub fn with_show_download_progress(mut self, show_download_progress: bool) -> Self
```

Toggles download progress display.

---
```

--------------------------------

### Initialize TextEmbedding with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-embedding.md

Create a TextEmbedding instance with a specified model (e.g., AllMiniLML6V2) and custom initialization options like download progress display and thread count. Requires the 'hf-hub' feature.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};

// With custom model and options
let mut model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```

--------------------------------

### Get Specific Text Embedding Model Info

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-embedding.md

Retrieves metadata for a particular text embedding model. Requires the model variant as input.

```rust
pub fn get_model_info(model: &EmbeddingModel) -> Result<&ModelInfo<EmbeddingModel>>
```

--------------------------------

### Get Specific Image Model Info

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Use `ImageEmbedding::get_model_info` to retrieve metadata for a specific image model by passing the model variant.

```rust
pub fn get_model_info(model: &ImageEmbeddingModel) -> Result<&ModelInfo<ImageEmbeddingModel>>
```

--------------------------------

### SparseInitOptions builder methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Provides builder methods for configuring SparseInitOptions, allowing customization of max length, cache directory, execution providers, intra-thread count, and download progress display.

```APIDOC
## SparseInitOptions builder methods

### Description
Builder methods for configuring sparse embedding model initialization.

### Methods
- `new(SparseModel::SPLADEPPV1)`: Initializes `SparseInitOptions` with a default model.
- `with_max_length(usize)`: Set max token length.
- `with_cache_dir(PathBuf)`: Set model cache directory.
- `with_execution_providers(Vec<ExecutionProviderDispatch>)`: Set ONNX Runtime providers.
- `with_intra_threads(usize)`: Limit CPU thread count.
- `with_show_download_progress(bool)`: Toggle download progress.
```

--------------------------------

### Error Recovery for Out-of-Memory Errors in Rust

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/INDEX.md

Provides an example of handling potential out-of-memory errors during embedding generation. If an error occurs, it attempts to retry with a smaller batch size.

```rust
match model.embed(texts, Some(256)) {
    Ok(e) => { /* success */ } 
    Err(e) if e.to_string().contains("out of memory") => {
        // Retry with smaller batch
        model.embed(texts, Some(64))?
    }
    Err(e) => return Err(e),
}
```

--------------------------------

### Initialize ImageEmbedding with Custom Model and Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Creates a new ImageEmbedding instance with a specified model (e.g., Resnet50) and custom initialization options like download progress display and intra-thread count. Ensure necessary imports are present.

```rust
use fastembed::{ImageEmbedding, ImageInitOptions, ImageEmbeddingModel};

// With custom model
let mut model = ImageEmbedding::try_new(
    ImageInitOptions::new(ImageEmbeddingModel::Resnet50)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```

--------------------------------

### Initialization Pattern

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/INDEX.md

Demonstrates the common initialization pattern for all embedding types, including configuration options.

```APIDOC
## Initialization Pattern

### Description
Shows the common pattern for initializing embedding objects with various configuration options.

### Example
```rust
OptionType::new(Model::Variant)
    .with_max_length(256)        // All types except Image
    .with_cache_dir(path)
    .with_execution_providers()
    .with_intra_threads(4)
    .with_show_download_progress(false)
```
```

--------------------------------

### Retry Logic for Transient Failures

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/errors.md

Implement retry logic for embedding operations that might fail due to transient issues like 'out of memory'. This example retries with a reduced batch size.

```rust
use std::time::Duration;
use std::thread;

fn embed_with_retry(
    model: &mut TextEmbedding,
    texts: &[&str],
    max_retries: u32,
) -> anyhow::Result<Vec<Vec<f32>>> {
    for attempt in 0..max_retries {
        match model.embed(texts, Some(128)) {
            Ok(result) => return Ok(result),
            Err(e) if e.to_string().contains("out of memory") && attempt < max_retries - 1 => {
                eprintln!("OOM on attempt {}; reducing batch size...", attempt + 1);
                thread::sleep(Duration::from_millis(100));
                continue;
            }
            Err(e) => return Err(e),
        }
    }
    unreachable!()
}
```

--------------------------------

### Initialize TextEmbedding with Defaults

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-embedding.md

Create a TextEmbedding instance using the default BGE Small EN v1.5 model. Ensure the 'hf-hub' feature is enabled.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};

// With defaults (BGE Small EN v1.5)
let mut model = TextEmbedding::try_new(Default::default())?;
```

--------------------------------

### SparseInitOptions

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Configuration builder for sparse embedding models. It supports the same builder methods as TextInitOptions.

```APIDOC
## SparseInitOptions

Configuration builder for sparse embedding models. Supports same builder methods as `TextInitOptions`.
```

--------------------------------

### Hybrid Search (Dense + Sparse) in Rust

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/similarity.md

Combines dense (semantic) and sparse (keyword-based, BM25-like) embeddings for a more robust search. This example shows how to generate both types of embeddings and combine their scores with configurable weights.

```rust
use fastembed::{TextEmbedding, SparseTextEmbedding, similarity::cosine_similarity};

let mut dense_model = TextEmbedding::try_new(Default::default())?;
let mut sparse_model = SparseTextEmbedding::try_new(Default::default())?;

let corpus = vec!["doc1", "doc2", "doc3"];
let query = "search term";

// Dense search
let dense_query = dense_model.embed(vec![query], None)?[0].clone();
let dense_corpus = dense_model.embed(&corpus, None)?;
let dense_scores: Vec<f32> = dense_corpus.iter()
    .map(|doc| cosine_similarity(&dense_query, doc))
    .collect();

// Sparse search (BM25-like)
let sparse_query = sparse_model.embed(vec![query], None)?[0].clone();
let sparse_corpus = sparse_model.embed(&corpus, None)?;

// Combine scores (weights are configurable)
let combined: Vec<f32> = dense_scores.iter()
    .zip(sparse_corpus.iter())
    .map(|(dense, sparse)| {
        let sparse_score = if sparse.indices.is_empty() {
            0.0
        } else {
            sparse.indices.len() as f32  // Simple: count of matches
        };
        0.7 * dense + 0.3 * sparse_score  // Weighted combination
    })
    .collect();
```

--------------------------------

### Configure Text Embedding Model Initialization

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Use TextInitOptions to configure text embedding models. Customize max length, cache directory, download progress, and execution providers.

```rust
TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_max_length(256)
    .with_cache_dir(PathBuf::from("/custom/cache"))
    .with_show_download_progress(true)
    .with_intra_threads(4)
    .with_execution_providers(vec![/* providers */])
```

--------------------------------

### Create Sparse Text Embedding Model with Default Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes a sparse text embedding model using default settings. Ensure you have the necessary imports.

```rust
use fastembed::{SparseEmbedding, SparseInitOptions, SparseModel, SparseTextEmbedding};

// With default options
let mut model = SparseTextEmbedding::try_new(Default::default())?;
```

--------------------------------

### Initialize Bgem3Embedding with Defaults

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Creates a new Bgem3Embedding instance using default options, including the FP32 BGE-M3 model.

```rust
use fastembed::{Bgem3Embedding, Bgem3InitOptions, Bgem3Model};

// With defaults (FP32 BGE-M3)
let mut model = Bgem3Embedding::try_new(Default::default())?;
```

--------------------------------

### Configure Image Embedding Model Initialization

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Use ImageInitOptions for image embedding models. Customize cache directory, download progress, execution providers, and intra-thread count. Note that image models do not have a max_length field.

```rust
ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32)
    .with_cache_dir(PathBuf::from("/cache"))
    .with_show_download_progress(true)
    .with_execution_providers(vec![])
    .with_intra_threads(2)
```

--------------------------------

### Basic TextEmbedding Initialization with Defaults

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Initializes TextEmbedding with default options, including the BGESmallENV15 model, 512 max length, CPU execution, default cache directory, and all available CPU cores.

```rust
use fastembed::{TextEmbedding, TextInitOptions};

let mut model = TextEmbedding::try_new(Default::default())?;
// Uses: BGESmallENV15, 512 max length, CPU, .fastembed_cache, all cores
```

--------------------------------

### Initialize ImageEmbedding with Defaults

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Creates a new ImageEmbedding instance using the default CLIP ViT-B-32 model. Ensure necessary imports are present.

```rust
use fastembed::{ImageEmbedding, ImageInitOptions, ImageEmbeddingModel};

// With defaults (CLIP ViT-B-32)
let mut model = ImageEmbedding::try_new(Default::default())?;
```

--------------------------------

### TextInitOptions Builder Methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-embedding.md

Methods for configuring text embedding model initialization using a builder pattern.

```APIDOC
## TextInitOptions Builder Methods

All builder methods return `Self` for chaining.

### Example
```rust
TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_max_length(256)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

### Methods
- `with_max_length(max_length: usize)`: Set max token length.
- `with_cache_dir(cache_dir: PathBuf)`: Set model cache directory.
- `with_execution_providers(providers: Vec<ExecutionProviderDispatch>)`: Set ONNX Runtime providers (e.g., CUDA).
- `with_intra_threads(num_threads: usize)`: Limit CPU thread count for inference.
- `with_show_download_progress(show: bool)`: Toggle download progress display.
```

--------------------------------

### Create Text Reranking Model with Default Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes a text reranking model using default settings. Ensure you have the necessary imports.

```rust
use fastembed::{TextRerank, RerankInitOptions, RerankerModel};

// With default options
let mut model = TextRerank::try_new(Default::default())?;
```

--------------------------------

### Configure Bgem3 Initialization

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Configure Bgem3Embedding initialization options using a builder pattern. Customize max length, cache directory, execution providers, and thread count.

```rust
Bgem3InitOptions::new(Bgem3Model::BGEM3)
    .with_max_length(2048)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

--------------------------------

### Configure Text Embedding Initialization Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-embedding.md

Builds initialization options for text embedding models using a fluent API. Customize cache directory, max length, execution providers, and threading.

```rust
TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_max_length(256)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

--------------------------------

### Initialize TextRerank with Custom Model and Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Creates a TextRerank instance with a specified reranker model and custom initialization options, including download progress and thread count.

```rust
use fastembed::{TextRerank, RerankInitOptions, RerankerModel};

// With custom model
let mut model = TextRerank::try_new(
    RerankInitOptions::new(RerankerModel::BGERerankerV2M3)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```

--------------------------------

### ImageInitOptions

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Configuration builder for image embedding models. It allows customization of cache directory, download progress, execution providers, and intra-thread count. Note that image models do not have a max_length field.

```APIDOC
## ImageInitOptions

Configuration builder for image embedding models. Supports:

```rust
ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32)
    .with_cache_dir(PathBuf::from("/cache"))
    .with_show_download_progress(true)
    .with_execution_providers(vec![])
    .with_intra_threads(2)
```

### Fields (no max_length for image models)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| model_name | `ImageEmbeddingModel` | `ClipVitB32` | Model to load |
| cache_dir | `PathBuf` | `.fastembed_cache` | Model cache directory |
| show_download_progress | `bool` | `true` | Show download progress |
| execution_providers | `Vec<ExecutionProviderDispatch>` | `[]` | ONNX Runtime providers |
| intra_threads | `Option<usize>` | `None` | CPU thread count |
```

--------------------------------

### Text Embedding and Similarity Search in Rust

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/INDEX.md

Shows how to initialize a TextEmbedding model, generate embeddings for a corpus and a query, and perform a top-k similarity search.

```rust
use fastembed::similarity::top_k;

// Initialize
let mut model = TextEmbedding::try_new(Default::default())?;

// Generate embeddings
let corpus = vec!["doc1", "doc2"];
let query = "search";
let embeddings = model.embed(&corpus, None)?;
let query_emb = model.embed(vec![query], None)?;

// Search
let hits = top_k(&query_emb[0], &embeddings, 5);
```

--------------------------------

### Create Image Embedding Model with Default Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes an image embedding model using default settings. Ensure you have the necessary imports.

```rust
use fastembed::{ImageEmbedding, ImageInitOptions, ImageEmbeddingModel};

// With default options
let mut model = ImageEmbedding::try_new(Default::default())?;
```

--------------------------------

### Dynamic Quantization Batching

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Demonstrates correct and incorrect usage of batching with dynamic quantized models. For dynamic quantization, batch_size must be None or equal to the total number of texts.

```rust
let embeddings = model.embed(texts, None)?;
```

```rust
let embeddings = model.embed(texts, Some(100))?;
```

--------------------------------

### Model Caching for Fast Loading

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Demonstrates how to load models, with the first run downloading and subsequent runs using cached models for instant loading. Cache persistence can be managed via HF_HOME or FASTEMBED_CACHE_DIR environment variables.

```rust
// First run: Downloads models
let mut model = TextEmbedding::try_new(options)?;
```

```rust
// Subsequent runs: Uses cached models (instant load)
// Set HF_HOME or FASTEMBED_CACHE_DIR to persist across restarts
```

--------------------------------

### Create Text Embedding Model with Default Options

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Initializes a text embedding model using default settings. Ensure you have the necessary imports.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};

// With default options
let mut model = TextEmbedding::try_new(Default::default())?;
```

--------------------------------

### TextRerank::try_new

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Initializes a TextRerank instance with a pre-trained model. Supports default models or custom model names.

```APIDOC
## TextRerank::try_new

### Description
Creates a new TextRerank instance using a pre-trained reranker model.

### Method
`pub fn try_new(options: RerankInitOptions) -> Result<Self>`

### Parameters
#### Request Body
- **options** (`RerankInitOptions`) - Required - Configuration for model initialization

**RerankInitOptions fields**
- **model_name** (`RerankerModel`) - Required - Default: `BGERerankerBase` - Reranker model to use
- **execution_providers** (`Vec<ExecutionProviderDispatch>`) - Optional - ONNX Runtime execution providers
- **cache_dir** (`PathBuf`) - Optional - Default: `.fastembed_cache` - Directory to cache downloaded models
- **show_download_progress** (`bool`) - Optional - Default: `true` - Display download progress
- **max_length** (`usize`) - Optional - Default: `512` - Maximum sequence length (tokens)
- **intra_threads** (`Option<usize>`) - Optional - Default: `None` - CPU threads for ONNX inference (None = all cores)

### Return Type
`Result<Self>` — A configured `TextRerank` instance, or error.

### Throws
- `anyhow::Error` - Model download fails, ONNX session creation fails, or model not in supported list

### Example
```rust
use fastembed::{TextRerank, RerankInitOptions, RerankerModel};

// With defaults (BGE Reranker Base)
let mut model = TextRerank::try_new(Default::default())?;

// With custom model
let mut model = TextRerank::try_new(
    RerankInitOptions::new(RerankerModel::BGERerankerV2M3)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```
```

--------------------------------

### TextInitOptions

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Configuration builder for text embedding models. It allows customization of model name, token length, cache directory, download progress, execution providers, and intra-thread count.

```APIDOC
## TextInitOptions

Configuration builder for text embedding models. Supports:

```rust
TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_max_length(256)
    .with_cache_dir(PathBuf::from("/custom/cache"))
    .with_show_download_progress(true)
    .with_intra_threads(4)
    .with_execution_providers(vec![/* providers */])
```

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| model_name | `EmbeddingModel` | `BGESmallENV15` | Model to load |
| max_length | `usize` | `512` | Max token length |
| cache_dir | `PathBuf` | `.fastembed_cache` | Model cache directory |
| show_download_progress | `bool` | `true` | Show download progress |
| execution_providers | `Vec<ExecutionProviderDispatch>` | `[]` | ONNX Runtime providers |
| intra_threads | `Option<usize>` | `None` | CPU thread count (None = all cores) |
```

--------------------------------

### Initialize Bgem3Embedding with Quantized Model

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Creates a new Bgem3Embedding instance using the quantized BGE-M3 model, optimized for CPU.

```rust
use fastembed::{Bgem3Embedding, Bgem3InitOptions, Bgem3Model};

// With quantized model (optimized for CPU)
let mut model = Bgem3Embedding::try_new(
    Bgem3InitOptions::new(Bgem3Model::BGEM3Q)
)?;
```

--------------------------------

### Initialization Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/ANALYSIS_SUMMARY.md

Configuration options for initializing embedding models, allowing customization of model name, length, cache directory, and execution providers.

```APIDOC
## Initialization Options

### Options Types
- `TextInitOptions`: Configuration for text embedding models.
- `SparseInitOptions`: Configuration for sparse embedding models (shares fields with TextInitOptions).
- `ImageInitOptions`: Configuration for image embedding models.
- `RerankInitOptions`: Configuration for reranker models (shares fields with TextInitOptions).
- `Bgem3InitOptions`: Configuration for BGEM3 models (shares fields with TextInitOptions).

### Builder Methods
Each options type provides `.with_*` methods for setting fields such as `model_name`, `max_length`, `cache_dir`, `execution_providers`, `intra_threads`, and `show_download_progress`.
```

--------------------------------

### Custom Text Embedding Model and Configuration

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/README.md

Initializes the text embedding model with a specific model (AllMiniLML6V2) and custom configurations for max length, intra-thread count, and download progress display. Requires specifying model and configuration options.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};

let mut model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
        .with_max_length(256)
        .with_intra_threads(4)
        .with_show_download_progress(true)
)?;

let embeddings = model.embed(texts, Some(128))?;
```

--------------------------------

### Initialize Text Options with Cache Directory

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Specifies the directory for caching models. This can be an absolute or relative path.

```rust
TextInitOptions::new(EmbeddingModel::BGESmallENV15)
    .with_cache_dir("/models/fastembed".into())
```

--------------------------------

### Initialize Bgem3Embedding with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Creates a new Bgem3Embedding instance with custom initialization options, such as max length and intra-thread count.

```rust
use fastembed::{Bgem3Embedding, Bgem3InitOptions, Bgem3Model};

// With custom max length (supports up to 8192 tokens)
let mut model = Bgem3Embedding::try_new(
    Bgem3InitOptions::new(Bgem3Model::BGEM3)
        .with_max_length(1024)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```

--------------------------------

### TextEmbedding Initialization with Custom Model Cache Directory

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Sets a custom directory for model caching using the .with_cache_dir() option. Downloaded models will be stored in the specified path.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};
use std::path::PathBuf;

let mut model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::BGESmallENV15)
        .with_cache_dir(PathBuf::from("/data/models"))
)?;
// Models download to /data/models/hub/
```

--------------------------------

### Create Rerank Init Options Builder

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/configuration.md

Initializes a builder for custom reranker models with default settings.

```rust
pub fn new() -> Self
```

--------------------------------

### RerankInitOptionsUserDefined builder methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Configure user-defined reranker initialization options using builder methods.

```APIDOC
## RerankInitOptionsUserDefined builder methods

### Description
Configure user-defined reranker initialization options using builder methods.

### Builder Methods
- `with_max_length(max_length: usize)`: Set max sequence length.
- `with_execution_providers(providers: Vec<ExecutionProviderDispatch>)`: Set ONNX providers.
- `with_intra_threads(threads: usize)`: Limit CPU threads.

### Example
```rust
let options = RerankInitOptionsUserDefined::new()
    .with_max_length(512)
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(2);
```
```

--------------------------------

### RerankInitOptions builder methods

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Configure reranker initialization options using builder methods.

```APIDOC
## RerankInitOptions builder methods

### Description
Configure reranker initialization options using builder methods.

### Builder Methods
- `with_max_length(max_length: usize)`: Set max token length.
- `with_cache_dir(cache_dir: PathBuf)`: Set model cache directory.
- `with_execution_providers(providers: Vec<ExecutionProviderDispatch>)`: Set ONNX Runtime providers.
- `with_intra_threads(threads: usize)`: Limit CPU thread count.
- `with_show_download_progress(show: bool)`: Toggle download progress.

### Example
```rust
let options = RerankInitOptions::new(RerankerModel::BGERerankerBase)
    .with_max_length(256)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false);
```
```

--------------------------------

### List Supported Bgem3 Models

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/bgem3-embedding.md

Retrieves metadata for all supported BGE-M3 variants. Use this to discover available models.

```rust
pub fn list_supported_models() -> Vec<ModelInfo<Bgem3Model>>
```

--------------------------------

### Initialize SparseTextEmbedding with Custom Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Creates a new SparseTextEmbedding instance with custom initialization options, allowing control over the model, download progress, and threading.

```rust
use fastembed::{SparseTextEmbedding, SparseInitOptions, SparseModel};

// With custom options
let mut model = SparseTextEmbedding::try_new(
    SparseInitOptions::new(SparseModel::SPLADEPPV1)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```

--------------------------------

### Initialize Model with DirectML Execution Provider

Source: https://github.com/anush008/fastembed-rs/blob/main/README.md

Pass a DirectML execution provider when initializing a TextEmbedding model to leverage GPU acceleration. This requires importing the DirectML execution provider from the ort crate.

```rust
use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};
use ort::ep::DirectML;

let model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
        .with_execution_providers(vec![DirectML::default().into()])
)?;
```

--------------------------------

### Initialize ImageEmbedding from User-Defined Model

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Creates an ImageEmbedding instance from custom ONNX model and preprocessor files. This requires reading the model and preprocessor files into byte vectors. Ensure necessary imports and file paths are correct.

```rust
use fastembed::{ImageEmbedding, ImageInitOptionsUserDefined, UserDefinedImageEmbeddingModel};
use std::fs;

let onnx_bytes = fs::read("vision_model.onnx")?;
let preprocessor = fs::read("preprocessor_config.json")?;

let model = UserDefinedImageEmbeddingModel::new(onnx_bytes, preprocessor);
let mut embedding = ImageEmbedding::try_new_from_user_defined(
    model,
    ImageInitOptionsUserDefined::default(),
)?;
```

--------------------------------

### TextRerank::try_new_from_user_defined

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Initializes a TextRerank instance using custom ONNX model files and tokenizer data.

```APIDOC
## TextRerank::try_new_from_user_defined

### Description
Creates a TextRerank instance from custom ONNX model files and tokenizer data.

### Method
`pub fn try_new_from_user_defined(
    model: UserDefinedRerankingModel,
    options: RerankInitOptionsUserDefined,
) -> Result<Self>`

### Parameters
#### Request Body
- **model** (`UserDefinedRerankingModel`) - Required - User-provided ONNX model and tokenizer
  **UserDefinedRerankingModel fields**
  - **onnx_source** (`OnnxSource`) - ONNX model source (in-memory bytes or file path)
    **OnnxSource enum**
    - `Memory(Vec<u8>)` - In-memory ONNX bytes
    - `File(PathBuf)` - Path to .onnx file
  - **tokenizer_files** (`TokenizerFiles`) - Tokenizer configuration files
- **options** (`RerankInitOptionsUserDefined`) - Required - Configuration for initialization
  **RerankInitOptionsUserDefined fields**
  - **execution_providers** (`Vec<ExecutionProviderDispatch>`) - Optional - ONNX Runtime providers
  - **max_length** (`usize`) - Optional - Default: `512` - Maximum sequence length
  - **intra_threads** (`Option<usize>`) - Optional - Default: `None` - CPU thread count

### Return Type
`Result<Self>` — Configured instance or error.

### Example
```rust
use fastembed::{TextRerank, RerankInitOptionsUserDefined, UserDefinedRerankingModel, TokenizerFiles, OnnxSource};
use std::fs;

let onnx_bytes = fs::read("reranker.onnx")?;
let tokenizer_files = TokenizerFiles {
    tokenizer_file: fs::read("tokenizer.json")?,
    config_file: fs::read("config.json")?,
    special_tokens_map_file: fs::read("special_tokens_map.json")?,
    tokenizer_config_file: fs::read("tokenizer_config.json")?,
};

let model = UserDefinedRerankingModel::new(
    OnnxSource::Memory(onnx_bytes),
    tokenizer_files,
);

let mut reranker = TextRerank::try_new_from_user_defined(
    model,
    RerankInitOptionsUserDefined::default(),
)?;
```
```

--------------------------------

### Configure Image Embedding Options

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/image-embedding.md

Set custom cache directories, execution providers, intra-thread count, and download progress visibility when initializing image embedding options.

```rust
ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32)
    .with_cache_dir("/custom/cache".into())
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(4)
    .with_show_download_progress(false)
```

--------------------------------

### RerankInitOptions

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/types.md

Configuration builder for reranking models. It supports the same methods as TextInitOptions.

```APIDOC
## RerankInitOptions

Configuration builder for reranking models. Supports same methods as `TextInitOptions`.
```

--------------------------------

### Configure User-Defined Reranker Initialization

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Configures reranker initialization for user-defined models using builder methods. Allows customization of max sequence length, execution providers, and intra-thread count.

```rust
RerankInitOptionsUserDefined::new()
    .with_max_length(512)
    .with_execution_providers(vec![/* providers */])
    .with_intra_threads(2)
```

--------------------------------

### Initialize TextRerank with Default Model

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/text-rerank.md

Creates a TextRerank instance using the default BGE Reranker Base model. No additional configuration is needed.

```rust
use fastembed::{TextRerank, RerankInitOptions, RerankerModel};

// With defaults (BGE Reranker Base)
let mut model = TextRerank::try_new(Default::default())?;
```

--------------------------------

### List Supported Sparse Models

Source: https://github.com/anush008/fastembed-rs/blob/main/_autodocs/api-reference/sparse-text-embedding.md

Retrieves metadata for all supported sparse text embedding models. Use this to discover available models and their descriptions.

```rust
pub fn list_supported_models() -> Vec<ModelInfo<SparseModel>>
```

```rust
let models = SparseTextEmbedding::list_supported_models();
for info in models {
    println!("Model: {:?}", info.model);
    println!("Description: {}", info.description);
}
```