class RubyLLM::Embedding

An Embedding is the result of turning text into numerical vectors. RubyLLM.embed returns one:

embedding = RubyLLM.embed("Ruby is a programmer's best friend")
embedding.vectors # => [0.018, -0.027, ...]

Pass an array to embed several texts in one call on supported models:

RubyLLM.embed(["Ruby", "Rails"]).vectors # => [[...], [...]]

Store the vectors for similarity search. tokens and cost report usage when the provider supplies it.

Attributes

model [R]

The id of the model that produced the vectors, as a String.

sparse_vectors [R]

The sparse vectors, for models that return one beside the dense vector, as a Hash mapping token id to weight. Shaped like vectors: one Hash for a single text, an array of them for an array of texts. nil on models that return only dense vectors.

vectors [R]

The embedding vectors. A flat array of floats when a single text was embedded, an array of such arrays when an array of texts was embedded.

Public Class Methods

embed (text, model: nil, provider: nil, assume_model_exists: false, context: nil, dimensions: nil, task_type: nil, title: nil, with: nil, provider_options: {}, metadata: nil)

Source

# File lib/ruby_llm/embedding.rb, line 100
def self.embed(text,
               model: nil,
               provider: nil,
               assume_model_exists: false,
               context: nil,
               dimensions: nil,
               task_type: nil,
               title: nil,
               with: nil,
               provider_options: {},
               metadata: nil)
  config = context&.config || RubyLLM.config
  model ||= config.default_embedding_model
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  model_id = model.id
  empty_tokens = Tokens.new

  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.class.display_name,
    model: model_id,
    model_info: model,
    input: text,
    dimensions: dimensions,
    task_type: task_type,
    title: title,
    attachment_count: Attachment.wrap(with).size,
    provider_options: provider_options,
    metadata: metadata,
    tokens: empty_tokens,
    cost: Cost.new(tokens: empty_tokens, model:, category: :embeddings)
  }

  RubyLLM.instrument('embedding.ruby_llm', payload, config: config) do |event|
    result = provider_instance.embed(text, model:, dimensions:, task_type:, title:, with:, provider_options:)
    event[:result] = result
    event[:response_model] = result.model
    event[:tokens] = result.tokens
    event[:cost] = result.cost
    event[:embedding_dimensions] = vector_dimensions(result.vectors)
    event[:embedding_count] = embedding_count(result.vectors)
    result
  end
end

Generates embeddings for text and returns an Embedding. text may be a single string or, on supported models, an array of strings. An array produces one vector per string in a single API call.

RubyLLM.embed "Ruby is a programmer's best friend"
RubyLLM.embed ["Ruby", "Python", "JavaScript"]
RubyLLM.embed "This is a test sentence",
              model: "text-embedding-3-large",
              dimensions: 512
RubyLLM.embed "RubyLLM makes provider APIs feel native to Ruby.",
              model: "gemini-embedding-001",
              provider: :vertexai,
              task_type: "RETRIEVAL_DOCUMENT",
              title: "RubyLLM docs"
RubyLLM.embed "The Ruby logo",
              model: "gemini-embedding-2",
              with: "logo.png"

model: selects the embedding model and defaults to the configured default_embedding_model. provider: forces a specific provider, and assume_model_exists: true skips the model registry check. context: supplies a Context whose configuration is used instead of the global one. dimensions: requests a specific vector size on models that support it. task_type: names the embedding task in the provider’s own vocabulary: Vertex AI and Gemini take values such as "RETRIEVAL_QUERY" or "RETRIEVAL_DOCUMENT", while Bedrock Cohere takes an input type such as "search_document". title: labels the document on Vertex AI and Gemini retrieval tasks. Providers that have no task concept ignore both. with: passes one or more media attachments (images, audio, video, PDFs) to embed alongside the text on multimodal embedding models such as Gemini’s gemini-embedding-2; providers without multimodal embeddings raise UnsupportedAttachmentError. provider_options: takes options in the provider’s request vocabulary and merges them into the request as-is. metadata: is not sent to the provider; it is attached to the emitted embedding.ruby_llm instrumentation event.

Public Instance Methods

cost ()

Source

# File lib/ruby_llm/embedding.rb, line 51
def cost
  return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?

  Cost.new(tokens:, model: model_info, category: :embeddings)
end

Returns the embedding cost across every provider attempt.

tokens ()

Source

# File lib/ruby_llm/embedding.rb, line 44
def tokens
  return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?

  Tokens.new(input: @input_tokens, reported_cost: @reported_cost)
end

Returns usage aggregated across every provider attempt.