ReqLLM.Embedding (ReqLLM v1.12.0)

Embedding functionality for ReqLLM.

This module provides embedding generation capabilities with support for:

Single text embedding generation
Batch text embedding generation
Model validation for embedding support

Usage Tracking

By default, embed/3 returns only the embedding vectors. To also retrieve token usage data, pass return_usage: true:

{:ok, %{embedding: vectors, usage: usage}} =
  ReqLLM.embed("openai:text-embedding-3-small", "Hello", return_usage: true)

Usage maps include canonical token fields and, when model pricing is available, flat cost fields such as total_cost.

Summary

Functions

embed(model_spec, input, opts \\ [])

Generates embeddings for single or multiple text inputs.

schema()

Returns the base embedding options schema.

supported_models()

Returns the list of supported embedding model specifications.

validate_model(model_spec)

Validates that a model supports embedding operations.

Functions

embed(model_spec, input, opts \\ [])

@spec embed(
  ReqLLM.model_input(),
  String.t() | [String.t()],
  keyword()
) :: {:ok, [float()] | [[float()]] | map()} | {:error, term()}

Generates embeddings for single or multiple text inputs.

Accepts either a single string or a list of strings, automatically handling both cases using pattern matching.

Parameters

model_spec - Model specification in various formats
input - Text string or list of text strings to generate embeddings for
opts - Additional options (keyword list)

Options

:dimensions - Number of dimensions for embeddings
:encoding_format - Format for encoding ("float" or "base64")
:user - User identifier for tracking
:provider_options - Provider-specific options
:return_usage - When true, returns %{embedding: vectors, usage: map} (default: false)

Examples

# Single text input
{:ok, embedding} = ReqLLM.Embedding.embed("openai:text-embedding-3-small", "Hello world")
#=> {:ok, [0.1, -0.2, 0.3, ...]}

# Multiple text inputs
{:ok, embeddings} = ReqLLM.Embedding.embed(
  "openai:text-embedding-3-small",
  ["Hello", "World"]
)
#=> {:ok, [[0.1, -0.2, ...], [0.3, 0.4, ...]]}

# With usage data
{:ok, %{embedding: vectors, usage: usage}} = ReqLLM.Embedding.embed(
  "openai:text-embedding-3-small",
  "Hello world",
  return_usage: true
)
Map.has_key?(usage, :total_cost)
#=> true

schema()

@spec schema() :: NimbleOptions.t()

Returns the base embedding options schema.

This schema contains embedding-specific options that are vendor-neutral.

supported_models()

@spec supported_models() :: [String.t()]

Returns the list of supported embedding model specifications.

Examples

ReqLLM.Embedding.supported_models()
#=> ["openai:text-embedding-3-small", "openai:text-embedding-3-large", "openai:text-embedding-ada-002", "google:gemini-embedding-001"]

validate_model(model_spec)

@spec validate_model(ReqLLM.model_input()) ::
  {:ok, LLMDB.Model.t()} | {:error, term()}

Validates that a model supports embedding operations.

Parameters

model_spec - Model specification in various formats

Examples

ReqLLM.Embedding.validate_model("openai:text-embedding-3-small")
#=> {:ok, %LLMDB.Model{provider: :openai, model: "text-embedding-3-small"}}

ReqLLM.Embedding.validate_model("anthropic:claude-3-sonnet")
#=> {:error, :embedding_not_supported}