### Initialize InitOptionsUserDefined

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

Example showing how to instantiate and configure InitOptionsUserDefined.

```rust
use fastembed::InitOptionsUserDefined;

let options = InitOptionsUserDefined::new()
    .with_max_length(256)
    .with_intra_threads(2);
```

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

### Initialize ImageInitOptions

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

Example showing how to instantiate and configure ImageInitOptions for an image embedding model.

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

let options = ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32)
    .with_show_download_progress(true)
    .with_intra_threads(2);

let model = ImageEmbedding::try_new(options)?;
```

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

### Initialize RerankInitOptions

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

Example usage of the builder pattern for RerankInitOptions.

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

let options = RerankInitOptions::new(RerankerModel::BGERerankerBase)
    .with_max_length(512)
    .with_show_download_progress(true);

let model = TextRerank::try_new(options)?;
```

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

### Example: Initializing from User-Defined Models

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

Demonstrates loading custom ONNX and tokenizer files to initialize the reranker.

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

let onnx_bytes = fs::read("my_reranker.onnx")?;
let tokenizer_json = fs::read("tokenizer.json")?;
let config_json = fs::read("config.json")?;
let special_tokens = fs::read("special_tokens_map.json")?;
let tokenizer_config = fs::read("tokenizer_config.json")?;

let tokenizer_files = TokenizerFiles {
    tokenizer_file: tokenizer_json,
    config_file: config_json,
    special_tokens_map_file: special_tokens,
    tokenizer_config_file: tokenizer_config,
};

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

let mut model = TextRerank::try_new_from_user_defined(
    user_model,
    RerankInitOptionsUserDefined::new(),
)?;
```

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

### Example: Initializing TextRerank

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

Demonstrates initializing the reranker with default settings or custom configuration options.

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

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

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

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

### Initialize from User-Defined Model

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

Example demonstrating how to load a custom sparse model from local files.

```rust
use fastembed::{SparseTextEmbedding, InitOptionsUserDefined, UserDefinedSparseModel, TokenizerFiles};
use std::fs;

let onnx_bytes = fs::read("my_sparse_model.onnx")?;
let tokenizer_json = fs::read("tokenizer.json")?;
let config_json = fs::read("config.json")?;
let special_tokens = fs::read("special_tokens_map.json")?;
let tokenizer_config = fs::read("tokenizer_config.json")?;

let tokenizer_files = TokenizerFiles {
    tokenizer_file: tokenizer_json,
    config_file: config_json,
    special_tokens_map_file: special_tokens,
    tokenizer_config_file: tokenizer_config,
};

let user_model = UserDefinedSparseModel::new(onnx_bytes, tokenizer_files);

let mut model = SparseTextEmbedding::try_new_from_user_defined(
    user_model,
    InitOptionsUserDefined::new().with_max_length(256),
)?;
```

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

### Initialize SparseTextEmbedding

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

Examples for initializing the embedding model using default or custom configuration options.

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

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

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

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

### Install fastembed via Cargo

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

Add the library to your project using the cargo CLI or by manually updating your Cargo.toml file.

```bash
cargo add fastembed
```

```toml
[dependencies]
fastembed = "5"
```

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

### Configure CUDA Execution Provider

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

Requires the cuda feature and the CUDA toolkit installed.

```rust
use fastembed::TextInitOptions;
use ort::ep::CUDA;

let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_execution_providers(vec![CUDA::default().into()]);

let model = TextEmbedding::try_new(options)?;
```

```toml
[dependencies]
fastembed = { version = "6", features = ["cuda"] }
```

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

### Index Sparse Embeddings in Search Engines

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

Example structure for indexing sparse embedding output into Elasticsearch or OpenSearch.

```rust
// After generating sparse embeddings, index in Elasticsearch/OpenSearch:
// PUT /my_index/_doc/1
// {
//   "title": "My Document",
//   "sparse_embedding": {
//     "indices": [token_id_1, token_id_2, ...],
//     "values": [weight_1, weight_2, ...]
//   }
// }
```

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

### get_default_pooling_method

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

Get the default pooling strategy for a given model.

```APIDOC
## pub fn get_default_pooling_method(model_name: &EmbeddingModel) -> Option<Pooling>

### Description
Get the default pooling strategy for a given model.

### Parameters
- **model_name** (&EmbeddingModel) - Required - The model to query.

### Returns
- **Option<Pooling>** - The pooling strategy, either Cls or Mean.
```

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

### get_model_info

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

Get detailed information about a specific embedding model.

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

### Description
Get detailed information about a specific embedding model.

### Parameters
- **model** (&EmbeddingModel) - Required - The embedding model variant to query.

### Returns
- **Result<&ModelInfo<EmbeddingModel>>** - Model information object.

### Errors
- **InvalidArgument**: Model not found in supported models list.
```

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

### ImageInitOptions methods

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

Method signatures for configuring ImageInitOptions instances.

```rust
impl ImageInitOptions {
    pub fn new(model_name: ImageEmbeddingModel) -> Self
    pub fn with_cache_dir(mut self, cache_dir: PathBuf) -> Self
    pub fn with_execution_providers(
        mut self,
        execution_providers: Vec<ExecutionProviderDispatch>
    ) -> Self
    pub fn with_intra_threads(mut self, intra_threads: usize) -> Self
    pub fn with_show_download_progress(mut self, show_download_progress: bool) -> Self
}
```

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

### Get Model Information

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

Query details for a specific embedding model variant.

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

let info = TextEmbedding::get_model_info(&EmbeddingModel::AllMiniLML6V2)?;
println!("Dimension: {}", info.dim);
println!("Description: {}", info.description);
println!("Model code: {}", info.model_code);
```

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

### Initialize Bgem3InitOptions in Rust

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

Configures BGE-M3 embedding models with custom length and download progress settings.

```rust
pub type Bgem3InitOptions = InitOptionsWithLength<Bgem3Model>;
```

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

let options = Bgem3InitOptions::new(Bgem3Model::BGEM3)
    .with_max_length(1024)
    .with_show_download_progress(true);

let model = Bgem3Embedding::try_new(options)?;
```

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

### Initialize TextEmbedding with options

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

Demonstrates configuring a model with custom cache, threads, and execution providers.

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

let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_show_download_progress(true)
    .with_max_length(512)
    .with_cache_dir("./.my_cache".into())
    .with_intra_threads(4)
    .with_execution_providers(vec![CUDA::default().into()]);

let model = TextEmbedding::try_new(options)?;
```

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

### pub fn try_new(options: TextInitOptions) -> Result<Self>

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

Initializes a TextEmbedding instance with specified options, including model selection and execution configuration.

```APIDOC
## try_new

### Description
Initialize a `TextEmbedding` instance with default or custom options.

### Parameters
- **options** (`TextInitOptions`) - Required - Initialization options including model selection, cache directory, execution providers, and intra-thread configuration.

### Returns
- `Result<TextEmbedding>`

### Throws
- `ModelRetrieval`: Failed to download or locate the model file from Hugging Face Hub
- `Ort`: ONNX Runtime initialization error
- `OrtBuilder`: Failed to build ONNX session
- `TokenizerConfig`: Invalid tokenizer configuration

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

// With default options (BGE small en v1.5)
let mut model = TextEmbedding::try_new(Default::default())?;

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

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

### Bgem3InitOptions

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

Configuration options for initializing BGE-M3 embedding models.

```APIDOC
## Bgem3InitOptions

### Description
Configuration for BGE-M3 embedding models.

### Usage
```rust
use fastembed::{Bgem3InitOptions, Bgem3Model};

let options = Bgem3InitOptions::new(Bgem3Model::BGEM3)
    .with_max_length(1024)
    .with_show_download_progress(true);

let model = Bgem3Embedding::try_new(options)?;
```
```

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

### Initialize ImageEmbedding with try_new

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

Demonstrates initializing the model with default settings or custom configuration options.

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

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

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

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

### Get specific model information in Rust

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

Retrieve detailed metadata for a specific SparseModel variant.

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

let info = SparseTextEmbedding::get_model_info(&SparseModel::SPLADEPPV1)?;
println!("Model code: {}", info.model_code);
println!("Description: {}", info.description);
```

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

### Configure Qwen3 Embeddings

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

Enable the qwen3 feature flag and initialize the model for text or multimodal embeddings.

```toml
[dependencies]
fastembed = { version = "5", features = ["qwen3"] }
```

```rust
use candle_core::{DType, Device};
use fastembed::Qwen3TextEmbedding;

let device = Device::Cpu;
let model = Qwen3TextEmbedding::from_hf(
    "Qwen/Qwen3-Embedding-0.6B",
    &device,
    DType::F32,
    512,
)?;

// Text-only usage with the Qwen3-VL embedding checkpoint is also supported:
// let model = Qwen3TextEmbedding::from_hf("Qwen/Qwen3-VL-Embedding-2B", &device, DType::F32, 512)?;

let embeddings = model.embed(&["query: ...", "passage: ..."])?;
println!("Embeddings length: {}", embeddings.len());
```

```rust
use candle_core::{DType, Device};
use fastembed::Qwen3VLEmbedding;

let device = Device::Cpu;
let model = Qwen3VLEmbedding::from_hf(
    "Qwen/Qwen3-VL-Embedding-2B",
    &device,
    DType::F32,
    2048,
)?;

let image_embeddings = model.embed_images(&["tests/assets/image_0.png", "tests/assets/image_1.png"])?;
let text_embeddings = model.embed_texts(&["query: blue cat", "query: red cat"])?;

println!("Image embeddings: {}", image_embeddings.len());
println!("Text embeddings: {}", text_embeddings.len());
```

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

### Get Default Pooling Method

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

Retrieve the default pooling strategy (Cls or Mean) for a specified model.

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

let pooling = TextEmbedding::get_default_pooling_method(&EmbeddingModel::BGESmallENV15);
println!("Default pooling: {:?}", pooling); // Some(Cls)
```

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

### Initialize Bgem3Embedding

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

Demonstrates initializing the model with default settings or custom configurations like quantization and thread count.

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

// With default options (BGEM3)
let mut model = Bgem3Embedding::try_new(Default::default())?;

// With custom options (quantized, higher max_length)
let mut model = Bgem3Embedding::try_new(
    Bgem3InitOptions::new(Bgem3Model::BGEM3Q)
        .with_max_length(1024)
        .with_show_download_progress(true)
        .with_intra_threads(4)
)?;
```

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

### Initialize Model with CPU Provider

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

CPU is the default execution provider and requires no additional configuration.

```rust
use fastembed::TextInitOptions;

// No configuration needed; CPU is default
let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2);
let model = TextEmbedding::try_new(options)?;
```

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

### Get specific model information

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

Retrieves detailed information for a specific ImageEmbeddingModel variant. Panics if the model is not found.

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

let info = ImageEmbedding::get_model_info(&ImageEmbeddingModel::ClipVitB32);
println!("Dimension: {}", info.dim);
```

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

### TextInitOptions implementation methods

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

Lists the builder methods available for configuring TextInitOptions.

```rust
impl TextInitOptions {
    pub fn new(model_name: EmbeddingModel) -> Self
    pub fn with_cache_dir(mut self, cache_dir: PathBuf) -> Self
    pub fn with_execution_providers(
        mut self,
        execution_providers: Vec<ExecutionProviderDispatch>
    ) -> Self
    pub fn with_max_length(mut self, max_length: usize) -> Self
    pub fn with_intra_threads(mut self, intra_threads: usize) -> Self
    pub fn with_show_download_progress(mut self, show_download_progress: bool) -> Self
}
```

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

### Get specific model information

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

Retrieves detailed metadata for a specific reranker model variant. Panics if the model is not found.

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

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

let info = TextRerank::get_model_info(&RerankerModel::BGERerankerBase);
println!("Description: {}", info.description);
println!("Model file: {}", info.model_file);
```

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

### Configure Execution Providers for ONNX Models

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

Demonstrates initializing models with specific execution providers like CPU, CUDA, or DirectML. Ensure the corresponding compilation features are enabled for the chosen provider.

```rust
use ort::ep::{CPU, CUDA, DirectML};

// CPU (default)
let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2);

// CUDA on Linux/Windows with NVIDIA GPUs
let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_execution_providers(vec![CUDA::default().into()]);

// DirectML on Windows (GPU-accelerated)
let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_execution_providers(vec![DirectML::default().into()]);
```

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

### ImageInitOptionsUserDefined builder methods

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

Builder methods for configuring ImageInitOptionsUserDefined instances.

```rust
impl ImageInitOptionsUserDefined {
    pub fn new() -> Self
    pub fn with_execution_providers(
        mut self,
        execution_providers: Vec<ExecutionProviderDispatch>
    ) -> Self
    pub fn with_intra_threads(mut self, intra_threads: usize) -> Self
}
```

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

### Initialize TextEmbedding with try_new

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

Creates a new instance using default or custom configuration options. Requires the fastembed crate and appropriate model selection.

```rust
pub fn try_new(options: TextInitOptions) -> Result<Self>
```

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

// With default options (BGE small en v1.5)
let mut model = TextEmbedding::try_new(Default::default())?;

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

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

### Define Default Dependencies

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

Shows the default feature set enabled when using the fastembed crate.

```toml
[dependencies]
fastembed = "6"

# Equivalent to:
# fastembed = { version = "6", features = [
#     "ort-download-binaries-native-tls",
#     "hf-hub-native-tls",
#     "image-models"
# ] }
```

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

### Initialize Bgem3Embedding from User-Defined Files

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

Initializes the model using local ONNX and tokenizer files instead of downloading them automatically.

```rust
use fastembed::{Bgem3Embedding, InitOptionsUserDefined, UserDefinedBgem3Model, TokenizerFiles};
use std::fs;

let onnx_bytes = fs::read("bgem3.onnx")?;
let tokenizer_json = fs::read("tokenizer.json")?;
let config_json = fs::read("config.json")?;
let special_tokens = fs::read("special_tokens_map.json")?;
let tokenizer_config = fs::read("tokenizer_config.json")?;

let tokenizer_files = TokenizerFiles {
    tokenizer_file: tokenizer_json,
    config_file: config_json,
    special_tokens_map_file: special_tokens,
    tokenizer_config_file: tokenizer_config,
};

let user_model = UserDefinedBgem3Model::new(onnx_bytes, tokenizer_files);

let mut model = Bgem3Embedding::try_new_from_user_defined(
    user_model,
    InitOptionsUserDefined::new().with_max_length(512),
)?;
```

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

### SparseInitOptions

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

Configuration options for initializing sparse embedding models.

```APIDOC
## SparseInitOptions

### Description
Configuration for sparse embedding models.

### Usage
```rust
use fastembed::{SparseInitOptions, SparseModel};

let options = SparseInitOptions::new(SparseModel::SPLADEPPV1)
    .with_max_length(256)
    .with_show_download_progress(true);

let model = SparseTextEmbedding::try_new(options)?;
```
```

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

### Initialize Embedding Model in Rust

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

Demonstrates creating a model instance using default settings or custom initialization options.

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

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

// Custom options
let model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
        .with_max_length(512)
        .with_intra_threads(4)
)?;
```

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

### Enable Metal Acceleration

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

Configure the project for Apple Metal support using the metal feature and execution providers.

```toml
[dependencies]
fastembed = { version = "6", features = ["metal"] }
```

```rust
use ort::ep::Metal;

let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_execution_providers(vec![Metal::default().into()]);
```

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

### Initialize SparseInitOptions in Rust

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

Configures sparse embedding models using the SparseInitOptions structure.

```rust
pub type SparseInitOptions = InitOptionsWithLength<SparseModel>;
```

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

let options = SparseInitOptions::new(SparseModel::SPLADEPPV1)
    .with_max_length(256)
    .with_show_download_progress(true);

let model = SparseTextEmbedding::try_new(options)?;
```

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

### ImageInitOptionsUserDefined

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

Configuration structure for initializing user-provided image models, allowing customization of execution providers and thread counts.

```APIDOC
## ImageInitOptionsUserDefined

### Description
Configuration for user-provided image models.

### Methods
- **new()** -> Self: Creates a new instance of ImageInitOptionsUserDefined.
- **with_execution_providers(execution_providers: Vec<ExecutionProviderDispatch>)** -> Self: Sets the execution providers.
- **with_intra_threads(intra_threads: usize)** -> Self: Sets the intra-op thread count.
```

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

### Initialize model with DirectML

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

Pass a DirectML execution provider during model initialization to utilize GPU resources.

```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()]),
)?;
```

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

### pub fn try_new_from_user_defined(model: UserDefinedEmbeddingModel, options: InitOptionsUserDefined) -> Result<Self>

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

Creates a TextEmbedding instance from user-provided model files and configuration.

```APIDOC
## try_new_from_user_defined

### Description
Create a `TextEmbedding` instance from user-provided model files.

### Parameters
- **model** (`UserDefinedEmbeddingModel`) - Required - Struct containing ONNX file bytes and tokenizer files.
- **options** (`InitOptionsUserDefined`) - Required - Execution providers, max_length, and thread configuration.

### Returns
- `Result<TextEmbedding>`

### Throws
- `OrtBuilder`: Failed to build ONNX session from memory
- `TokenizerConfig`: Invalid tokenizer configuration in provided files

### Example
```rust
use fastembed::{TextEmbedding, InitOptionsUserDefined, UserDefinedEmbeddingModel, TokenizerFiles};
use std::fs;

let onnx_bytes = fs::read("my_model.onnx")?;
let tokenizer_json = fs::read("tokenizer.json")?;
let config_json = fs::read("config.json")?;
let special_tokens = fs::read("special_tokens_map.json")?;
let tokenizer_config = fs::read("tokenizer_config.json")?;

let tokenizer_files = TokenizerFiles {
    tokenizer_file: tokenizer_json,
    config_file: config_json,
    special_tokens_map_file: special_tokens,
    tokenizer_config_file: tokenizer_config,
};

let user_model = UserDefinedEmbeddingModel::new(onnx_bytes, tokenizer_files)
    .with_pooling(Pooling::Mean);

let mut model = TextEmbedding::try_new_from_user_defined(
    user_model,
    InitOptionsUserDefined::new(),
)?;
```
```

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

### Initialize TextRerank with try_new_from_user_defined

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

Method signature for initializing a TextRerank instance using custom model files.

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

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

### Configure Text Embedding Initialization

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

Use TextInitOptions to customize model loading, cache location, and performance settings for text embeddings.

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

let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_cache_dir(PathBuf::from("/models"))
    .with_show_download_progress(true)
    .with_max_length(1024)
    .with_intra_threads(4);
```

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

### ImageEmbedding::try_new

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

Initializes an ImageEmbedding instance with default or custom configuration options.

```APIDOC
## ImageEmbedding::try_new

### Description
Initialize an `ImageEmbedding` instance with default or custom options, including model selection and execution providers.

### Parameters
- **options** (`ImageInitOptions`) - Required - Initialization options with model selection, cache directory, and execution providers.

### Returns
`Result<ImageEmbedding>`

### Throws
- **ModelRetrieval**: Failed to download model files or preprocessor config.
- **PreprocessorConfig**: Invalid preprocessor configuration JSON.
- **OrtBuilder**: Failed to build ONNX session.
```

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

### TextInitOptions::with_execution_providers

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

Configures the execution providers for the model initialization. This allows users to specify hardware acceleration backends like CUDA or DirectML.

```APIDOC
## TextInitOptions::with_execution_providers

### Description
Sets the execution providers for the model. This method allows the user to override the default CPU execution with hardware-accelerated providers.

### Signature
`pub fn with_execution_providers(mut self, providers: Vec<ExecutionProvider>) -> Self`

### Parameters
- **providers** (Vec<ExecutionProvider>) - Required - A list of execution providers to use for model inference. Supported providers depend on enabled compilation features (e.g., `cuda`, `directml`, `metal`).

### Example
```rust
let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_execution_providers(vec![CUDA::default().into()]);
```
```

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

### Enable CUDA Acceleration

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

Configure the project for NVIDIA GPU support using the cuda feature and execution providers.

```toml
[dependencies]
fastembed = { version = "6", features = ["cuda"] }
```

```rust
use fastembed::TextInitOptions;
use ort::ep::CUDA;

let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_execution_providers(vec![CUDA::default().into()]);
```

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

### Initialize TextEmbedding from user-defined files

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

Loads a custom model from local file bytes. Ensure all required tokenizer and configuration files are provided.

```rust
pub fn try_new_from_user_defined(
    model: UserDefinedEmbeddingModel,
    options: InitOptionsUserDefined,
) -> Result<Self>
```

```rust
use fastembed::{TextEmbedding, InitOptionsUserDefined, UserDefinedEmbeddingModel, TokenizerFiles};
use std::fs;

let onnx_bytes = fs::read("my_model.onnx")?;
let tokenizer_json = fs::read("tokenizer.json")?;
let config_json = fs::read("config.json")?;
let special_tokens = fs::read("special_tokens_map.json")?;
let tokenizer_config = fs::read("tokenizer_config.json")?;

let tokenizer_files = TokenizerFiles {
    tokenizer_file: tokenizer_json,
    config_file: config_json,
    special_tokens_map_file: special_tokens,
    tokenizer_config_file: tokenizer_config,
};

let user_model = UserDefinedEmbeddingModel::new(onnx_bytes, tokenizer_files)
    .with_pooling(Pooling::Mean);

let mut model = TextEmbedding::try_new_from_user_defined(
    user_model,
    InitOptionsUserDefined::new(),
)?;
```

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

### Enable Optional Features

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

Configures dependencies to include GPU support and specific candle-based models.

```toml
[dependencies]
fastembed = { version = "6", features = ["cuda", "qwen3", "nomic-v2-moe"] }
```

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

### Initialize ImageEmbedding from user-defined files

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

Initializes the model using custom ONNX bytes and preprocessor configuration files.

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

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

let user_model = UserDefinedImageEmbeddingModel::new(onnx_bytes, preprocessor_config);

let mut model = ImageEmbedding::try_new_from_user_defined(
    user_model,
    ImageInitOptionsUserDefined::new(),
)?;
```

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

### Enable DirectML Acceleration

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

Configure the project for Windows DirectML support using the directml feature and execution providers.

```toml
[dependencies]
fastembed = { version = "6", features = ["directml"] }
```

```rust
use ort::ep::DirectML;

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

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

### Configure Reranking Initialization

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

Use RerankInitOptions to initialize reranking models, which extend standard text initialization parameters.

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

let options = RerankInitOptions::new(RerankerModel::BGERerankerBase)
    .with_max_length(512)
    .with_show_download_progress(true);
```

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

### Bgem3Embedding::try_new

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

Initializes a new Bgem3Embedding instance using default or custom configuration options.

```APIDOC
## pub fn try_new(options: Bgem3InitOptions) -> Result<Self>

### Description
Initializes a `Bgem3Embedding` instance with default or custom options, including model variant, cache directory, max_length, and execution providers.

### Parameters
- **options** (`Bgem3InitOptions`) - Required - Initialization options including model variant, cache directory, max_length, and execution providers.

### Returns
`Result<Bgem3Embedding>`

### Throws
- `ModelRetrieval`: Failed to download BGE-M3 model files
- `Ort`: ONNX Runtime initialization error
- `OrtBuilder`: Failed to build ONNX session
- `TokenizerConfig`: Invalid tokenizer configuration
```

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

### ImageInitOptions

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

Configuration structure for image embedding models. Includes methods for setting the model name, cache directory, execution providers, and download progress visibility.

```APIDOC
## ImageInitOptions

### Description
Configuration for image embedding models.

### Methods
- **new(model_name: ImageEmbeddingModel) -> Self**: Creates a new instance with the specified model.
- **with_cache_dir(cache_dir: PathBuf) -> Self**: Sets the cache directory.
- **with_execution_providers(execution_providers: Vec<ExecutionProviderDispatch>) -> Self**: Sets the execution providers.
- **with_intra_threads(intra_threads: usize) -> Self**: Sets the intra-op thread count.
- **with_show_download_progress(show_download_progress: bool) -> Self**: Toggles download progress display.

### Example
```rust
use fastembed::{ImageInitOptions, ImageEmbeddingModel};

let options = ImageInitOptions::new(ImageEmbeddingModel::ClipVitB32)
    .with_show_download_progress(true)
    .with_intra_threads(2);

let model = ImageEmbedding::try_new(options)?;
```
```

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

### List Supported Models

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

Retrieve metadata for all available embedding models.

```rust
use fastembed::TextEmbedding;

let models = TextEmbedding::list_supported_models();
for model_info in models {
    println!("{:?}: {} dims", model_info.model, model_info.dim);
}
```

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

### Initialize TextRerank with try_new

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

Method signature for initializing a TextRerank instance.

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

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

### Enable Apple Accelerate

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

Requires the accelerate feature.

```toml
[dependencies]
fastembed = { version = "6", features = ["accelerate"] }
```

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

### Configure Model Caching

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

Set the cache directory via environment variables or programmatically using TextInitOptions.

```bash
# Default cache: .fastembed_cache
# Override with environment variable:
export FASTEMBED_CACHE_DIR=/custom/path

# Or use Hugging Face cache:
export HF_HOME=/data/huggingface
```

```rust
use fastembed::TextInitOptions;
use std::path::PathBuf;

let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_cache_dir(PathBuf::from("/custom/cache"))
    .with_show_download_progress(true);
```

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

### Enable Intel MKL Acceleration

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

Requires the mkl feature and the Intel MKL library.

```toml
[dependencies]
fastembed = { version = "6", features = ["mkl"] }
```

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

### TextRerank::try_new

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

Initializes a new TextRerank instance using specified initialization options, such as model selection and execution providers.

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

### Description
Initializes a `TextRerank` instance with default or custom options for reranking tasks.

### Parameters
- **options** (`RerankInitOptions`) - Required - Initialization options including model selection, cache directory, max_length, and execution providers.

### Returns
- `Result<TextRerank>`

### Throws
- `ModelRetrieval`: Failed to download model files from Hugging Face.
- `Ort`: ONNX Runtime initialization error.
- `OrtBuilder`: Failed to build ONNX session.
- `TokenizerConfig`: Invalid tokenizer configuration.
```

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

### Configure Hugging Face home directory

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

Sets the HF_HOME environment variable to define the shared Hugging Face cache location.

```bash
export HF_HOME=/data/huggingface
# FastEmbed models will be cached in /data/huggingface/hub
```

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

### Define TokenizerFiles struct

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

Required configuration files for custom model tokenization.

```rust
pub struct TokenizerFiles {
    pub tokenizer_file: Vec<u8>,          // tokenizer.json
    pub config_file: Vec<u8>,             // config.json
    pub special_tokens_map_file: Vec<u8>, // special_tokens_map.json
    pub tokenizer_config_file: Vec<u8>,   // tokenizer_config.json
}
```

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

### Configure Default Threading

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

Initializes the model using all available CPU cores by default.

```rust
use fastembed::TextInitOptions;

// Uses all available CPU cores (std::thread::available_parallelism)
let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2);
```

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

### InitOptionsUserDefined methods

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

Method signatures for configuring InitOptionsUserDefined instances.

```rust
impl InitOptionsUserDefined {
    pub fn new() -> Self
    pub fn with_execution_providers(
        mut self,
        execution_providers: Vec<ExecutionProviderDispatch>
    ) -> Self
    pub fn with_max_length(mut self, max_length: usize) -> Self
    pub fn with_intra_threads(mut self, intra_threads: usize) -> Self
}
```

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

### Enable DirectML dependency

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

Add the directml feature to your Cargo.toml dependencies to enable GPU acceleration on Windows.

```toml
[dependencies]
fastembed = { version = "5", features = ["directml"] }
```

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

### Define ImageInitOptionsUserDefined struct

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

Configuration structure for user-provided image models.

```rust
pub struct ImageInitOptionsUserDefined {
    pub execution_providers: Vec<ExecutionProviderDispatch>,
    pub intra_threads: Option<usize>,
}
```

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

### SparseTextEmbedding::try_new

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

Initializes a new SparseTextEmbedding instance using default or custom configuration options.

```APIDOC
## SparseTextEmbedding::try_new

### Description
Initializes a `SparseTextEmbedding` instance with default or custom options, such as model selection and execution providers.

### Signature
`pub fn try_new(options: SparseInitOptions) -> Result<Self>`

### Parameters
- **options** (SparseInitOptions) - Required - Initialization options including model selection, cache directory, max_length, and execution providers.

### Returns
- `Result<SparseTextEmbedding>`

### Errors
- `ModelRetrieval`: Failed to download sparse embedding model files.
- `Ort`: ONNX Runtime initialization error.
- `OrtBuilder`: Failed to build ONNX session.
- `TokenizerConfig`: Invalid tokenizer configuration.
```

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

### TextInitOptions

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

Configuration struct for text embedding models, providing methods to customize model loading and execution behavior.

```APIDOC
## TextInitOptions

### Description
Configuration struct used to initialize text embedding models. It allows setting the model name, execution providers, cache directory, sequence length, and threading options.

### Fields
- **model_name** (EmbeddingModel) - Default: BGESmallENV15 - The embedding model to load.
- **execution_providers** (Vec<ExecutionProviderDispatch>) - Default: [] - ONNX Runtime execution providers (e.g., CPU, CUDA, DirectML).
- **cache_dir** (PathBuf) - Default: .fastembed_cache - Directory to cache downloaded models.
- **show_download_progress** (bool) - Default: true - Whether to display a download progress bar.
- **max_length** (usize) - Default: 512 - Maximum sequence length for the tokenizer.
- **intra_threads** (Option<usize>) - Default: None - ONNX Runtime intra-op thread count.

### Methods
- **new(model_name: EmbeddingModel) -> Self** - Creates a new instance with default values.
- **with_cache_dir(cache_dir: PathBuf) -> Self** - Sets the model cache directory.
- **with_execution_providers(providers: Vec<ExecutionProviderDispatch>) -> Self** - Sets the ONNX execution providers.
- **with_max_length(max_length: usize) -> Self** - Sets the maximum sequence length.
- **with_intra_threads(intra_threads: usize) -> Self** - Sets the number of intra-op threads.
- **with_show_download_progress(show: bool) -> Self** - Toggles the download progress bar.

### Usage Example
```rust
let options = TextInitOptions::new(EmbeddingModel::BGELargeENV15)
    .with_show_download_progress(true)
    .with_max_length(512)
    .with_cache_dir("./.my_cache".into())
    .with_intra_threads(4)
    .with_execution_providers(vec![CUDA::default().into()]);
```
```

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

### Configure Fastembed-rs via Cargo.toml

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

Define feature flags in Cargo.toml to enable GPU support or specific model architectures.

```toml
# Default (text + image, CPU)
fastembed = "6"

# With GPU support
fastembed = { version = "6", features = ["cuda"] }

# With specialized models
fastembed = { version = "6", features = ["qwen3", "nomic-v2-moe"] }

# Full featured
fastembed = { version = "6", features = ["cuda", "qwen3", "nomic-v2-moe"] }
```

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

### TextRerank::try_new_from_user_defined

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

Creates a TextRerank instance from user-provided model files and tokenizer configurations.

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

### Description
Creates a `TextRerank` instance from user-provided model files, allowing for custom ONNX sources and tokenizer configurations.

### Parameters
- **model** (`UserDefinedRerankingModel`) - Required - Struct containing ONNX source (memory or file) and tokenizer files.
- **options** (`RerankInitOptionsUserDefined`) - Required - Execution providers, max_length, and thread configuration.

### Returns
- `Result<TextRerank>`

### Throws
- `OrtBuilder`: Failed to build ONNX session.
- `TokenizerConfig`: Invalid tokenizer files.
```

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

### List supported models

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

Retrieve and iterate through the list of models supported by the library.

```rust
use fastembed::TextEmbedding;

let models = TextEmbedding::list_supported_models();
for model_info in models {
    println!("{:?}: {} dimensions", model_info.model, model_info.dim);
}
```

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

### Implement UserDefinedEmbeddingModel methods

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

Methods for initializing and configuring a custom embedding model instance.

```rust
impl UserDefinedEmbeddingModel {
    pub fn new(onnx_file: Vec<u8>, tokenizer_files: TokenizerFiles) -> Self
    pub fn with_quantization(mut self, quantization: QuantizationMode) -> Self
    pub fn with_pooling(mut self, pooling: Pooling) -> Self
    pub fn with_external_initializer(mut self, file_name: String, buffer: Vec<u8>) -> Self
}
```

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

### RerankInitOptionsUserDefined builder methods

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

Builder methods for configuring RerankInitOptionsUserDefined instances.

```rust
impl RerankInitOptionsUserDefined {
    pub fn new() -> Self
    pub fn with_execution_providers(
        mut self,
        execution_providers: Vec<ExecutionProviderDispatch>
    ) -> Self
    pub fn with_max_length(mut self, max_length: usize) -> Self
    pub fn with_intra_threads(mut self, intra_threads: usize) -> Self
}
```

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

### Configure Cache Environment Variables

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

Sets environment variables to control cache directory location and Hugging Face mirror settings.

```bash
# Use custom cache
export FASTEMBED_CACHE_DIR=/data/models/fastembed

# Or use Hugging Face hub cache
export HF_HOME=/data/models/huggingface

# Optional: set custom Hugging Face mirror
export HF_ENDPOINT=https://mirrors.example.com
```

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

### List supported sparse models in Rust

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

Retrieve a list of all available sparse embedding models and their descriptions.

```rust
use fastembed::SparseTextEmbedding;

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

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

### Handle Initialization Errors

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

Pattern match on TextEmbedding initialization to handle specific model retrieval errors.

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

match TextEmbedding::try_new(Default::default()) {
    Ok(model) => { /* use model */ }
    Err(Error::ModelRetrieval { file, source }) => {
        eprintln!("Could not download {}: {}", file, source);
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

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

### Generate Sparse Text Embeddings

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

Initialize the SparseTextEmbedding model and generate sparse embeddings for documents.

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

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

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

let documents = vec![
    "passage: Hello, World!",
    "query: Hello, World!",
    "passage: This is an example passage.",
    "fastembed-rs is licensed under Apache 2.0"
];

// Generate embeddings with the default batch size, 256
let embeddings: Vec<SparseEmbedding> = model.embed(documents, None)?;
```

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

### Configure DirectML Execution Provider

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

Requires the directml feature and a Windows environment. Note that memory pattern optimization and parallel execution are automatically disabled.

```rust
use fastembed::TextInitOptions;
use ort::ep::DirectML;

let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_execution_providers(vec![DirectML::default().into()]);

let model = TextEmbedding::try_new(options)?;
```

```toml
[dependencies]
fastembed = { version = "6", features = ["directml"] }
```

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

### Calculate Top-K Similarity in Rust

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

Demonstrates embedding documents and a query, then retrieving the top-k most similar documents using the similarity module.

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

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

let documents = vec!["doc1", "doc2", "doc3"];
let embeddings = model.embed(documents, None)?;

// Embed a query
let query_embedding = model.embed(vec!["query"], None)?[0].clone();

// Find most similar documents
let top_results = similarity::top_k(&query_embedding, &embeddings, 3);
for (idx, score) in top_results {
    println!("Document {} matches with score {:.4}", idx, score);
}
```

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

### Configure Metal Execution Provider

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

Requires the metal feature and a macOS environment.

```rust
use fastembed::TextInitOptions;
use ort::ep::Metal;

let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_execution_providers(vec![Metal::default().into()]);

let model = TextEmbedding::try_new(options)?;
```

```toml
[dependencies]
fastembed = { version = "6", features = ["metal"] }
```

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

### try_new_from_user_defined Method Signature

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

Method signature for creating an instance from user-provided model files.

```rust
pub fn try_new_from_user_defined(
    model: UserDefinedSparseModel,
    options: InitOptionsUserDefined,
) -> Result<Self>
```

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

### Configure cache directory programmatically

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

Sets the cache directory using the TextInitOptions struct in Rust.

```rust
use fastembed::TextInitOptions;
use std::path::PathBuf;

let options = TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
    .with_cache_dir(PathBuf::from("/custom/cache"));
```

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

### Environment Variables

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

Environment variables used to configure cache directory resolution and Hugging Face settings.

```APIDOC
## Environment Variables

### Description
Cache directory resolution follows this precedence:
1. `HF_HOME` — Hugging Face cache directory (highest priority)
2. `FASTEMBED_CACHE_DIR` — FastEmbed-specific cache directory
3. `.fastembed_cache` — Default relative to current working directory

### Example
```bash
# Use custom cache
export FASTEMBED_CACHE_DIR=/data/models/fastembed

# Or use Hugging Face hub cache
export HF_HOME=/data/models/huggingface

# Optional: set custom Hugging Face mirror
export HF_ENDPOINT=https://mirrors.example.com
```
```