### map example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::map, which applies a function to the Ok value, leaving Err untouched. The example parses lines and multiplies by two.

```rust
let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{n}"),
        Err(..) => {}
    }
}
```

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

### ok example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::ok, which converts a Result into an Option, returning Some(value) for Ok and None for Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

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

### as_ref example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::as_ref, which converts &Result<T, E> to Result<&T, &E>, leaving the original in place.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

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

### Example for Result::is_ok_and

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Returns `true` if the result is `Ok` and the value inside matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### is_err_and example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Shows how to use Result::is_err_and to check if the result is an Err and the error value matches a predicate. The example uses std::io::Error and demonstrates true/false cases.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, String> = Err("ownership".to_string());
assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### Example for Result::is_ok

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Returns `true` if the result is `Ok`.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

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

### Example for Result::cloned on &T

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates cloning the contents of an `Ok` part from a `Result<&T, E>` to `Result<T, E>`.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

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

### Example for Result::copied on &mut T

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates copying the contents of an `Ok` part from a `Result<&mut T, E>` to `Result<T, E>`.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

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

### as_mut example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::as_mut, which converts &mut Result<T, E> to Result<&mut T, &mut E>, allowing mutation of the contained value.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### Example for Result::cloned on &mut T

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates cloning the contents of an `Ok` part from a `Result<&mut T, E>` to `Result<T, E>`.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

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

### Example for Result::copied on &T

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates copying the contents of an `Ok` part from a `Result<&T, E>` to `Result<T, E>`.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

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

### err example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::err, which converts a Result into an Option, returning Some(error) for Err and None for Ok.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.err(), None);

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.err(), Some("Nothing here"));
```

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

### Build vision-language prompt for Qwen3

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Constructs a prompt string with system, user, and assistant sections. Optionally includes vision start/end tokens and user text. The instruction is placed in the system section.

```rust
fn build_vl_prompt(text: Option<&str>, include_image: bool, instruction: &str) -> String {
    let mut prompt = String::new();
    prompt.push_str("system\n");
    prompt.push_str(instruction);
    prompt.push_str("\nuser\n");
    if include_image {
        prompt.push_str("<|vision_start|><|image_pad|><|vision_end|>");
    }
    if let Some(text) = text {
        prompt.push_str(text);
    }
    prompt.push_str("\nassistant\n");
    prompt
}
```

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

### BaseInitOptions

Source: https://docs.rs/fastembed/latest/fastembed/struct.BaseInitOptions.html

Configuration options for initializing a fastembed model, including model name, execution providers, cache directory, download progress, and intra-op threads.

```APIDOC
## Struct BaseInitOptions

### Description
Configuration options for initializing a fastembed model.

### Fields
- **model_name** (`M`) - The name of the model.
- **execution_providers** (`Vec<ExecutionProviderDispatch>`) - The execution providers for the model.
- **cache_dir** (`PathBuf`) - The cache directory for the model file.
- **show_download_progress** (`bool`) - Whether to show download progress.
- **intra_threads** (`Option<usize>`) - Number of intra-op threads for ONNX Runtime. `None` uses every available CPU core.

### Methods

#### `new(model_name: M) -> Self`
Create a new InitOptions with the given model name.

#### `with_cache_dir(self, cache_dir: PathBuf) -> Self`
Set the cache directory for the model file.

#### `with_execution_providers(self, execution_providers: Vec<ExecutionProviderDispatch>) -> Self`
Set the execution providers for the model.

#### `with_intra_threads(self, intra_threads: usize) -> Self`
Set the number of intra-op threads ONNX Runtime uses. By default (`None`) all available CPU cores are used; capping this limits CPU usage at the cost of per-inference throughput.

#### `with_show_download_progress(self, show_download_progress: bool) -> Self`
Set whether to show download progress.
```

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

### Instantiating TextEmbedding with default and custom options

Source: https://docs.rs/fastembed/latest/fastembed/index.html

Shows how to create a TextEmbedding model using default TextInitOptions, list supported models, and create a model with custom options (AllMiniLML6V2) and download progress display. Uses the fastembed crate.

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

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

// List all supported models
dbg!(TextEmbedding::list_supported_models());

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

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

### TextEmbedding::get_model_info

Source: https://docs.rs/fastembed/latest/fastembed/struct.TextEmbedding.html

Gets ModelInfo from an EmbeddingModel.

```APIDOC
## TextEmbedding::get_model_info

### Description
Get ModelInfo from EmbeddingModel.

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

### Parameters
- **model** (&EmbeddingModel) - Required - The embedding model to get info for.

### Returns
- **Result<&ModelInfo<EmbeddingModel>>** - A Result containing a reference to the ModelInfo or an error.
```

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

### get_model_info

Source: https://docs.rs/fastembed/latest/fastembed/struct.ImageEmbedding.html

Gets the ModelInfo for a given ImageEmbeddingModel.

```APIDOC
## get_model_info

### Description
Get ModelInfo from ImageEmbeddingModel.

### Method
`pub fn get_model_info(model: &ImageEmbeddingModel) -> ModelInfo<ImageEmbeddingModel>`

### Parameters
- **model** (&ImageEmbeddingModel) - Required - The model to get info for.

### Returns
- `ModelInfo<ImageEmbeddingModel>` - The model information.
```

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

### Qwen3Attention Initialization

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Initializes the Qwen3Attention module with configuration and variable builder.

```rust
impl Qwen3Attention {
    pub fn new(cfg: &Config, vb: VarBuilder) -> Result<Self> {
        let head_dim = cfg.head_dim();
        let num_heads = cfg.num_attention_heads;
        let num_kv_heads = cfg.num_key_value_heads;
        let num_kv_groups = cfg.num_kv_groups();
        assert!(
            num_heads.is_multiple_of(num_kv_heads),
            "num_heads must be multiple of num_kv_heads"
        );

        let q_out = num_heads * head_dim;
        let kv_out = num_kv_heads * head_dim;

        let q_proj = if cfg.attention_bias {
            linear(cfg.hidden_size, q_out, vb.pp("q_proj"))?
        } else {
            linear_no_bias(cfg.hidden_size, q_out, vb.pp("q_proj"))?
        };
        let k_proj = if cfg.attention_bias {
            linear(cfg.hidden_size, kv_out, vb.pp("k_proj"))?
        } else {
            linear_no_bias(cfg.hidden_size, kv_out, vb.pp("k_proj"))?
        };
        let v_proj = if cfg.attention_bias {
            linear(cfg.hidden_size, kv_out, vb.pp("v_proj"))?
        } else {
            linear_no_bias(cfg.hidden_size, kv_out, vb.pp("v_proj"))?
        };
        let o_proj = if cfg.attention_bias {
            linear(q_out, cfg.hidden_size, vb.pp("o_proj"))?
        } else {
            linear_no_bias(q_out, cfg.hidden_size, vb.pp("o_proj"))?
        };

        // q_norm/k_norm are RMSNorm(head_dim)
        let q_norm = Qwen3RMSNorm::new(head_dim, cfg.rms_norm_eps, vb.pp("q_norm"))?;
        let k_norm = Qwen3RMSNorm::new(head_dim, cfg.rms_norm_eps, vb.pp("k_norm"))?;

        Ok(Self {
            q_proj,
            k_proj,
            v_proj,
            o_proj,
            q_norm,
            k_norm,
            num_heads,
            num_kv_heads,
            num_kv_groups,
            head_dim,
            scaling: (head_dim as f32).powf(-0.5),
        })
    }
```

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

### Preprocess Image for Qwen3 VL

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Preprocesses an image for Qwen3 VL: validates config, resizes with smart_resize, and computes grid dimensions. Returns a PreparedImage. Errors on invalid config or grid size.

```rust
fn preprocess_image(
    img: &DynamicImage,
    cfg: &Qwen3VLPreprocessorConfig,
    max_image_tokens: usize,
) -> Result<PreparedImage> {
    if cfg.image_mean.len() != 3 || cfg.image_std.len() != 3 {
        return Err(candle_core::Error::Msg(
            "Expected image_mean and image_std length to be 3".into(),
        ));
    }
    if cfg.patch_size == 0 || cfg.temporal_patch_size == 0 || cfg.merge_size == 0 {
        return Err(candle_core::Error::Msg(
            "patch_size, temporal_patch_size and merge_size must be > 0".into(),
        ));
    }

    let rgb = img.to_rgb8();
    let (orig_w, orig_h) = rgb.dimensions();
    let factor = cfg.patch_size * cfg.merge_size;

    let effective_max_pixels = cfg.max_pixels.min(max_image_tokens * factor * factor);
    let (resized_h, resized_w) = smart_resize(
        orig_h as usize,
        orig_w as usize,
        factor,
        cfg.min_pixels,
        effective_max_pixels,
    )?;

    let resized = image::imageops::resize(
        &rgb,
        resized_w as u32,
        resized_h as u32,
        FilterType::CatmullRom,
    );

    let grid_t = 1usize;
    let grid_h = resized_h / cfg.patch_size;
    let grid_w = resized_w / cfg.patch_size;
    let merge = cfg.merge_size;

    if !grid_h.is_multiple_of(merge) || !grid_w.is_multiple_of(merge) {
        return Err(candle_core::Error::Msg(
            "grid_h and grid_w must be divisible by merge_size".into(),
        ));
    }

    let channels = 3usize;
    let patch_dim = channels * cfg.temporal_patch_size * cfg.patch_size * cfg.patch_size;
}
```

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

### SparseTextEmbedding::get_model_info

Source: https://docs.rs/fastembed/latest/src/fastembed/sparse_text_embedding/impl.rs.html

Gets the ModelInfo for a given SparseModel.

```APIDOC
## SparseTextEmbedding::get_model_info

### Description
Retrieves the ModelInfo for a specified SparseModel.

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

### Parameters
- **model** (&SparseModel) - Required - The model to retrieve information for.

### Returns
- `ModelInfo<SparseModel>` - The model information for the given model.

### Panics
- Panics if the model is not found in the supported models list.

### Example
```rust
let model_info = SparseTextEmbedding::get_model_info(&SparseModel::SomeModel);
```
```

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

### Example for Result::is_err

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Returns `true` if the result is `Err`.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### Configuration Parsing Utility

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Parses raw bytes into either a standard Qwen3 configuration or a Qwen3-VL configuration, returning the appropriate text configuration and weight prefix.

```rust
fn parse_config_and_weight_prefix(config_bytes: &[u8]) -> Result<(Config, Option<&'static str>)> {
    if let Ok(cfg) = serde_json::from_slice::<Config>(config_bytes) {
        return Ok((cfg, None));
    }

    if let Ok(cfg) = serde_json::from_slice::<Qwen3VLConfig>(config_bytes) {
        return Ok((cfg.text_config, Some("model.language_model")));
    }

    Err(candle_core::Error::Msg(
        "Failed to parse config as Qwen3 or Qwen3-VL text config".into(),
    ))
}
```

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

### Example for Result::transpose

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Transposes a `Result` of an `Option` into an `Option` of a `Result`.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

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

### Example for Result::flatten

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Converts from `Result<Result<T, E>, E>` to `Result<T, E>`.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

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

### Instantiating TextEmbedding with default and custom options

Source: https://docs.rs/fastembed/latest/src/fastembed/lib.rs.html

Shows how to create a TextEmbedding model using default options or with custom TextInitOptions, and how to list supported models. Requires the hf-hub feature.

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

# fn model_demo() -> fastembed::Result<()> {
// With default TextInitOptions
let model = TextEmbedding::try_new(Default::default())?;

// List all supported models
dbg!(TextEmbedding::list_supported_models());

// With custom TextInitOptions
let model = TextEmbedding::try_new(
       TextInitOptions::new(EmbeddingModel::AllMiniLML6V2).with_show_download_progress(true),
)?;
# Ok(())
# }

```

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

### ImageInitOptionsUserDefined::new

Source: https://docs.rs/fastembed/latest/fastembed/struct.ImageInitOptionsUserDefined.html

Creates a new ImageInitOptionsUserDefined instance with default settings.

```APIDOC
## ImageInitOptionsUserDefined::new

### Description
Creates a new `ImageInitOptionsUserDefined` instance with default settings.

### Method
`pub fn new() -> Self`

### Parameters
None

### Returns
- `Self` - A new `ImageInitOptionsUserDefined` instance.

```

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

### Initialize Qwen3-VL Model

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Initializes the Qwen3-VL model, vision components, and tokenizer with padding and truncation settings.

```rust
let vb = unsafe { VarBuilder::from_mmaped_safetensors(&weight_files, dtype, device)? };
let model = Qwen3Model::new(cfg.text_config, vb.pp("model").pp("language_model"))?;
let vision = Qwen3VLVisionModel::new(&cfg.vision_config, vb.pp("model").pp("visual"))?;

let tok_path: PathBuf = repo.get("tokenizer.json").map_err(map_err)?;
let mut tokenizer = tokenizers::Tokenizer::from_file(tok_path).map_err(map_err)?;
let _ = tokenizer.with_padding(Some(PaddingParams {
    strategy: PaddingStrategy::BatchLongest,
    direction: PaddingDirection::Right,
    ..Default::default()
}));
let _ = tokenizer.with_truncation(Some(TruncationParams {
    max_length,
    ..Default::default()
}));

let max_image_tokens = {
    let base_prompt = build_vl_prompt(None, true, "Represent the user's input.");
    let enc = tokenizer.encode(base_prompt, false).map_err(map_err)?;
    let img_count = enc
        .get_ids()
        .iter()
        .filter(|&&id| id == cfg.image_token_id)
        .count();
    let overhead = enc.get_ids().len() - img_count;
    max_length.saturating_sub(overhead)
};

Ok(Self {
    model,
    vision,
    tokenizer,
    preprocessor,
    image_token_id: cfg.image_token_id,
    default_instruction: "Represent the user's input.".to_string(),
    max_image_tokens,
})
```

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

### EmbeddingModel::get_model_info

Source: https://docs.rs/fastembed/latest/fastembed/enum.EmbeddingModel.html

Get model information by model code. This method is part of the ModelTrait implementation.

```APIDOC
## get_model_info

### Description
Get model information by model code.

### Method
get_model_info

### Signature
fn get_model_info(model: &EmbeddingModel) -> Option<&ModelInfo<EmbeddingModel>>

### Parameters
- **model** (&EmbeddingModel) - The model code.

### Returns
- **Option<&ModelInfo<EmbeddingModel>>** - The model information, if found.

```

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

### Example for Result::flatten with nested nesting

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Shows that flattening only removes one level of nesting at a time.

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

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

### TextInitOptions::new

Source: https://docs.rs/fastembed/latest/fastembed/type.TextInitOptions.html

Creates a new TextInitOptions with the given model name. This is the constructor for the initialization options.

```APIDOC
## TextInitOptions::new

### Description
Creates a new InitOptionsWithLength with the given model name.

### Method
new

### Signature
pub fn new(model_name: M) -> Self

### Parameters
- **model_name** (M) - Required - The embedding model to use.

### Returns
- **Self** - A new instance of InitOptionsWithLength.
```

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

### and method usage

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates how and returns the second result if the first is Ok, or the first error if it is Err.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

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

### Load Preprocessor Configuration

Source: https://docs.rs/fastembed/latest/src/fastembed/image_embedding/utils.rs.html

Parses a JSON configuration to initialize a sequence of image transformers.

```rust
fn load_preprocessor(config: serde_json::Value) -> Result<Compose> {
    let mut transformers: Vec<Box<dyn Transform>> = vec![];
    transformers.push(Box::new(ConvertToRGB));

    let mode = config["image_processor_type"]
        .as_str()
        .unwrap_or("CLIPImageProcessor");
    match mode {
        "CLIPImageProcessor" => {
            if config["do_resize"].as_bool().unwrap_or(false) {
                let size = config["size"].clone();
                let shortest_edge = size["shortest_edge"].as_u64();
                let (height, width) = (size["height"].as_u64(), size["width"].as_u64());

                if let Some(shortest_edge) = shortest_edge {
                    let size = (shortest_edge as u32, shortest_edge as u32);
                    transformers.push(Box::new(Resize {
                        size,
                        resample: FilterType::CatmullRom,
                    }));
                } else if let (Some(height), Some(width)) = (height, width) {
                    let size = (height as u32, width as u32);
                    transformers.push(Box::new(Resize {
                        size,
                        resample: FilterType::CatmullRom,
                    }));
                } else {
                    return Err(Error::PreprocessorConfig(
                        "Size must contain either 'shortest_edge' or 'height' and 'width'.".into(),
                    ));
                }
            }

            if config["do_center_crop"].as_bool().unwrap_or(false) {
                let crop_size = config["crop_size"].clone();
                let (height, width) = if crop_size.is_u64() {
                    let size = crop_size.as_u64().ok_or_else(|| {
                        Error::PreprocessorConfig("crop_size must be a valid u64".into())
                    })? as u32;
```

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

### InitOptions and InitOptionsWithLength Builder Methods

Source: https://docs.rs/fastembed/latest/src/fastembed/init.rs.html

Builder methods for configuring initialization options for the fastembed library.

```APIDOC
## InitOptionsWithLength::new

### Description
Creates a new `InitOptionsWithLength` with the given model name, using default values for other fields.

### Method
Constructor

### Parameters
- **model_name** (M) - Required - The model name to use.

### Returns
A new `InitOptionsWithLength<M>` instance.

```

```APIDOC
## InitOptionsWithLength::with_max_length

### Description
Sets the maximum length for the model input.

### Method
Builder method

### Parameters
- **max_length** (usize) - Required - The maximum length to set.

### Returns
The updated `InitOptionsWithLength<M>` instance.

```

```APIDOC
## InitOptionsWithLength::with_cache_dir

### Description
Sets the cache directory for the model file.

### Method
Builder method

### Parameters
- **cache_dir** (PathBuf) - Required - The cache directory path.

### Returns
The updated `InitOptionsWithLength<M>` instance.

```

```APIDOC
## InitOptionsWithLength::with_execution_providers

### Description
Sets the execution providers for the model.

### Method
Builder method

### Parameters
- **execution_providers** (Vec<ExecutionProviderDispatch>) - Required - The execution providers to use.

### Returns
The updated `InitOptionsWithLength<M>` instance.

```

```APIDOC
## InitOptionsWithLength::with_intra_threads

### Description
Sets the number of intra-op threads ONNX Runtime uses. By default (`None`) all available CPU cores are used; capping this limits CPU usage at the cost of per-inference throughput.

### Method
Builder method

### Parameters
- **intra_threads** (usize) - Required - The number of intra-op threads to set.

### Returns
The updated `InitOptionsWithLength<M>` instance.

```

```APIDOC
## InitOptionsWithLength::with_show_download_progress

### Description
Sets whether to show download progress.

### Method
Builder method

### Parameters
- **show_download_progress** (bool) - Required - Whether to show download progress.

### Returns
The updated `InitOptionsWithLength<M>` instance.

```

```APIDOC
## InitOptions::new

### Description
Creates a new `InitOptions` with the given model name, using default values for other fields.

### Method
Constructor

### Parameters
- **model_name** (M) - Required - The model name to use.

### Returns
A new `InitOptions<M>` instance.

```

```APIDOC
## InitOptions::with_cache_dir

### Description
Sets the cache directory for the model file.

### Method
Builder method

### Parameters
- **cache_dir** (PathBuf) - Required - The cache directory path.

### Returns
The updated `InitOptions<M>` instance.

```

```APIDOC
## InitOptions::with_execution_providers

### Description
Sets the execution providers for the model.

### Method
Builder method

### Parameters
- **execution_providers** (Vec<ExecutionProviderDispatch>) - Required - The execution providers to use.

### Returns
The updated `InitOptions<M>` instance.

```

```APIDOC
## InitOptions::with_intra_threads

### Description
Sets the number of intra-op threads ONNX Runtime uses. By default (`None`) all available CPU cores are used; capping this limits CPU usage at the cost of per-inference throughput.

### Method
Builder method

### Parameters
- **intra_threads** (usize) - Required - The number of intra-op threads to set.

### Returns
The updated `InitOptions<M>` instance.

```

```APIDOC
## InitOptions::with_show_download_progress

### Description
Sets whether to show download progress.

### Method
Builder method

### Parameters
- **show_download_progress** (bool) - Required - Whether to show download progress.

### Returns
The updated `InitOptions<M>` instance.

```

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

### TextEmbedding::get_quantization_mode

Source: https://docs.rs/fastembed/latest/fastembed/struct.TextEmbedding.html

Gets the quantization mode of the model. Models with a 'Q' suffix in their name are quantized models.

```APIDOC
## TextEmbedding::get_quantization_mode

### Description
Get the quantization mode of the model. Any models with a `Q` suffix in their name are quantized models. Currently only 6 supported models have dynamic quantization.

### Method
pub fn get_quantization_mode(model_name: &EmbeddingModel) -> QuantizationMode

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

### Returns
- **QuantizationMode** - The quantization mode of the model.
```

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

### Access Model Configuration and Device

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Methods to retrieve the model configuration and the device it is running on.

```rust
pub fn config(&self) -> &Config {
    self.model.config()
}

pub fn device(&self) -> &Device {
    self.model.device()
}
```

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

### FromIterator Result short-circuit behavior

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Example showing that iteration stops and no further elements are processed after the first Err is encountered.

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

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

### FromIterator Result underflow check

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Example demonstrating how to subtract integers in a vector while checking for underflow using FromIterator.

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

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

### FromIterator Result overflow check

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Example demonstrating how to increment integers in a vector while checking for overflow using FromIterator.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

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

### Load Qwen3-VL model from Hugging Face

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

The from_hf function initializes a Qwen3-VL model by downloading configuration, preprocessor settings, and model weights from a specified Hugging Face repository.

```rust
pub fn from_hf(
        repo_id: &str,
        device: &Device,
        dtype: DType,
        max_length: usize,
    ) -> Result<Self> {
        use tokenizers::{PaddingDirection, PaddingParams, PaddingStrategy, TruncationParams};

        let api = ApiBuilder::new()
            .with_progress(true)
            .build()
            .map_err(map_err)?;
        let repo = api.model(repo_id.to_string());

        let cfg_path: PathBuf = repo.get("config.json").map_err(map_err)?;
        let cfg_bytes = std::fs::read(&cfg_path).map_err(map_err)?;
        let cfg: Qwen3VLFullConfig = serde_json::from_slice(&cfg_bytes).map_err(map_err)?;

        let preproc_path: PathBuf = repo.get("preprocessor_config.json").map_err(map_err)?;
        let preprocessor_bytes = std::fs::read(&preproc_path).map_err(map_err)?;
        let preprocessor: Qwen3VLPreprocessorConfig =
            serde_json::from_slice(&preprocessor_bytes).map_err(map_err)?;

        let weight_files: Vec<PathBuf> = if let Ok(p) = repo.get("model.safetensors") {
            vec![p]
        } else {
            let mut files = Vec::new();
            for i in 1.. {
                let candidates: Vec<_> = (1..=20)
                    .filter_map(|total| {
                        let fname = format!("model-{:05}-of-{:05}.safetensors", i, total);
                        repo.get(&fname).ok()
                    })
                    .collect();
                if candidates.is_empty() {
                    break;
                }
                files.extend(candidates.into_iter().take(1));
            }
            if files.is_empty() {
                return Err(candle_core::Error::Msg(
                    "Could not locate model.safetensors or sharded weight files".into(),
                ));
            }
            files
        };
```

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

### map_or_else example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::map_or_else, which applies a fallback function to the Err value or a function to the Ok value.

```rust
let k = 21;

let x : Result<_, &str> = Ok("foo");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);

let x : Result<&str, _> = Err("bar");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);
```

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

### InitOptionsWithLength::with_show_download_progress

Source: https://docs.rs/fastembed/latest/fastembed/struct.InitOptionsWithLength.html

Sets whether to show download progress.

```APIDOC
## InitOptionsWithLength::with_show_download_progress

### Description
Sets whether to show download progress.

### Method
`pub fn with_show_download_progress(self, show_download_progress: bool) -> Self`

### Parameters
- **show_download_progress** (bool) - Required - Whether to show download progress.

### Returns
- **Self** - The updated InitOptionsWithLength instance.

```

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

### TextInitOptions::with_show_download_progress

Source: https://docs.rs/fastembed/latest/fastembed/type.TextInitOptions.html

Sets whether to show download progress. This is a builder method that returns the modified options.

```APIDOC
## TextInitOptions::with_show_download_progress

### Description
Set whether to show download progress.

### Method
with_show_download_progress

### Signature
pub fn with_show_download_progress(self, show_download_progress: bool) -> Self

### Parameters
- **show_download_progress** (bool) - Required - Whether to show download progress.

### Returns
- **Self** - The modified options.
```

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

### unwrap basic usage

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates the basic usage of unwrap to retrieve the Ok value.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

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

### map_or_default example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::map_or_default, which applies a function to the Ok value or returns the default value for the type U if Err.

```rust
let x: Result<_, &str> = Ok("foo");
let y: Result<&str, _> = Err("bar");

assert_eq!(x.map_or_default(|x| x.len()), 3);
assert_eq!(y.map_or_default(|y| y.len()), 0);
```

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

### Result<T, E> - Termination::report

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

The report method is called to get the representation of the value as a status code, which is returned to the operating system.

```APIDOC
## Termination::report

### Description
Is called to get the representation of the value as status code. This status code is returned to the operating system.

### Method
report(self) -> ExitCode

### Parameters
- self - The Result value.

### Returns
- ExitCode - The status code representation.
```

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

### Parse Qwen3-VL configuration with language model prefix

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Unit test verifying that a Qwen3-VL configuration containing a text_config block is parsed correctly, identifying the language model prefix.

```rust
    #[test]
    fn parses_qwen3_vl_text_config_with_language_model_prefix() {
        let config = r#"{
            "text_config": {
                "attention_bias": false,
                "attention_dropout": 0.0,
                "head_dim": 128,
                "hidden_act": "silu",
                "hidden_size": 2048,
                "intermediate_size": 6144,
                "max_position_embeddings": 262144,
                "num_attention_heads": 16,
                "num_hidden_layers": 28,
                "num_key_value_heads": 8,
                "rms_norm_eps": 1e-6,
                "rope_scaling": {
                    "mrope_interleaved": true,
                    "mrope_section": [24, 20, 20],
                    "rope_type": "default"
                },
                "rope_theta": 5000000,
                "tie_word_embeddings": true,
                "use_cache": true,
                "vocab_size": 151936
            },
            "image_token_id": 151655,
            "video_token_id": 151656,
            "vision_start_token_id": 151652,
            "vision_end_token_id": 151653
        }"#;

        let (cfg, prefix) = parse_config_and_weight_prefix(config.as_bytes()).unwrap();
        assert_eq!(cfg.hidden_size, 2048);
        assert_eq!(prefix, Some("model.language_model"));
    }
```

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

### Find token spans in a sequence

Source: https://docs.rs/fastembed/latest/src/fastembed/models/qwen3.rs.html

Unit test for the find_token_spans function, which identifies start and end indices for specific token IDs in a vector.

```rust
    #[test]
    fn finds_token_spans() {
        let ids = vec![1u32, 42, 42, 7, 42, 42, 42, 9];
        let spans = find_token_spans(&ids, 42);
        assert_eq!(spans, vec![(1, 3), (4, 7)]);
    }
```

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

### Bgem3InitOptions

Source: https://docs.rs/fastembed/latest/fastembed/type.Bgem3InitOptions.html

Type alias for initialization options of the Bgem3Embedding model. It is an alias for InitOptionsWithLength<Bgem3Model> and includes fields for model selection, execution providers, cache directory, download progress, max length, and intra-thread settings.

```APIDOC
## Type Alias Bgem3InitOptions

### Description
Options for initializing the Bgem3Embedding model.

### Type Definition
```rust
pub type Bgem3InitOptions = InitOptionsWithLength<Bgem3Model>;
```

### Aliased Type
```rust
pub struct Bgem3InitOptions {
    pub model_name: Bgem3Model,
    pub execution_providers: Vec<ExecutionProviderDispatch>,
    pub cache_dir: PathBuf,
    pub show_download_progress: bool,
    pub max_length: usize,
    pub intra_threads: Option<usize>,
}
```

### Fields
- **model_name**: `Bgem3Model` - The model name.
- **execution_providers**: `Vec<ExecutionProviderDispatch>` - Execution providers for the model.
- **cache_dir**: `PathBuf` - Cache directory for the model file.
- **show_download_progress**: `bool` - Whether to show download progress.
- **max_length**: `usize` - Maximum length for input.
- **intra_threads**: `Option<usize>` - Number of intra-op threads for ONNX Runtime. `None` (default) uses every available CPU core via `std::thread::available_parallelism`. Set this to cap CPU usage (e.g., on laptops) at the cost of throughput.

### Implementations

#### `new(model_name: M) -> Self`
Create a new `InitOptionsWithLength` with the given model name.

#### `with_max_length(self, max_length: usize) -> Self`
Set the maximum length.

#### `with_cache_dir(self, cache_dir: PathBuf) -> Self`
Set the cache directory for the model file.

#### `with_execution_providers(self, execution_providers: Vec<ExecutionProviderDispatch>) -> Self`
Set the execution providers for the model.

#### `with_intra_threads(self, intra_threads: usize) -> Self`
Set the number of intra-op threads ONNX Runtime uses. By default (`None`) all available CPU cores are used; capping this limits CPU usage at the cost of per-inference throughput.

#### `with_show_download_progress(self, show_download_progress: bool) -> Self`
Set whether to show download progress.

### Trait Implementations
- `Clone` for `InitOptionsWithLength<M>`
- `Debug` for `InitOptionsWithLength<M>`
- `Default` for `InitOptionsWithLength<M>` where `M: Default + HasMaxLength`
```

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

### UserDefinedBgem3Model::new

Source: https://docs.rs/fastembed/latest/fastembed/struct.UserDefinedBgem3Model.html

Creates a new UserDefinedBgem3Model instance with the provided ONNX file bytes and tokenizer files.

```APIDOC
## UserDefinedBgem3Model::new

### Description
Creates a new UserDefinedBgem3Model instance with the provided ONNX file bytes and tokenizer files.

### Method
Constructor

### Signature
pub fn new(onnx_file: Vec<u8>, tokenizer_files: TokenizerFiles) -> Self

### Parameters
- **onnx_file** (Vec<u8>) - Required - The bytes of the ONNX model file.
- **tokenizer_files** (TokenizerFiles) - Required - The tokenizer files for the model.

### Returns
- **Self** - A new UserDefinedBgem3Model instance.

### Example
```rust
let model = UserDefinedBgem3Model::new(onnx_bytes, tokenizer_files);
```
```

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

### map_or example

Source: https://docs.rs/fastembed/latest/fastembed/type.Result.html

Demonstrates Result::map_or, which returns a default value for Err or applies a function to the Ok value. Note that arguments are eagerly evaluated.

```rust
let x: Result<_, &str> = Ok("foo");
assert_eq!(x.map_or(42, |v| v.len()), 3);

let x: Result<&str, _> = Err("bar");
assert_eq!(x.map_or(42, |v| v.len()), 42);
```