Struct EmbeddingsBuilder 

pub struct EmbeddingsBuilder<M, T>
where
    M: EmbeddingModel,
    T: Embed,
{ /* private fields */ }

Builder for creating embeddings from one or more documents of type T. Note: T can be any type that implements the Embed trait.

Using the builder is preferred over using EmbeddingModel::embed_text directly as it will batch the documents in a single request to the model provider.

Example

use rig_core::{
    client::{EmbeddingsClient, ProviderClient},
    embeddings::EmbeddingsBuilder,
    providers::openai,
};

// Create OpenAI client
let openai_client = openai::Client::from_env()?;

let model = openai_client.embedding_model(openai::TEXT_EMBEDDING_3_SMALL);

let embeddings = EmbeddingsBuilder::new(model.clone())
    .documents(vec![
        "1. *flurbo* (noun): A green alien that lives on cold planets.".to_string(),
        "2. *flurbo* (noun): A fictional digital currency.".to_string(),
        "1. *glarb-glarb* (noun): An ancient tool used by the ancestors of the inhabitants of planet Jiro to farm the land.".to_string(),
        "2. *glarb-glarb* (noun): A fictional creature from marshlands.".to_string(),
        "1. *linlingdong* (noun): A term used by inhabitants of the sombrero galaxy to describe humans.".to_string(),
        "2. *linlingdong* (noun): A rare instrument.".to_string(),
    ])?
    .build()
    .await?;

Implementations

impl<M, T> EmbeddingsBuilder<M, T>

where M: EmbeddingModel, T: Embed,

pub fn new(model: M) -> Self

Create a new embedding builder with the given embedding model

pub fn document(self, document: T) -> Result<Self, EmbedError>

Add a document to be embedded to the builder. document must implement the Embed trait.

pub fn documents( self, documents: impl IntoIterator<Item = T>, ) -> Result<Self, EmbedError>

Add multiple documents to be embedded to the builder. documents must be iterable with items that implement the Embed trait.

impl<M, T> EmbeddingsBuilder<M, T>

where M: EmbeddingModel, T: Embed + Send,

pub async fn build(self) -> Result<Vec<(T, Vec<Embedding>)>, EmbeddingError>

Generate embeddings for all documents in the builder.

Returns (document, embeddings) pairs. A document may produce one or many embeddings depending on how its Embed implementation uses TextEmbedder.

Order

Both levels are ordered, and callers may rely on it:

• pairs come back in the order the documents were added — positional callers depend on this, for example InMemoryVectorStore::add_documents, which derives its document ids from this sequence; and
• each document’s embeddings come back in the order its Embed impl produced the texts.

Neither depends on how the texts were batched or on which batch the provider answered first. Both have been silently violated before (rig#2344, rig#2345), so treat the guarantee as load-bearing rather than incidental.

The second bullet inherits one assumption this type cannot check: providers pair a batch’s embeddings to its texts positionally, so a provider that reordered within a single response would still be believed. That is the provider’s contract, not this builder’s.

Errors

Alongside whatever the provider and the transport return, two cases originate here:

• A document that produces no text fails the whole build rather than coming back with an empty list. This is easy to hit by accident: an empty collection in an #[embed] field embeds nothing, because Embed is implemented for Vec<T> element-wise.
• A provider returning fewer embeddings than the texts it was sent fails rather than handing back a short list, since a short list cannot be told apart from a document that legitimately has fewer texts.

Both name the offending document.

pub async fn build_with_usage( self, ) -> Result<(Vec<(T, Vec<Embedding>)>, Usage), EmbeddingError>

Generate embeddings for all documents in the builder and return accumulated token usage.

Returns (document, embeddings) pairs and the total token usage across all batches. A document may produce one or many embeddings depending on how its Embed implementation uses TextEmbedder.

Ordering is guaranteed at both levels, and the same two errors originate here; both are described on Self::build.