Gemini.Types.Request.EmbedContentRequest (GeminiEx v0.8.4)

View Source

Request structure for embedding content using Gemini embedding models.

Represents a request to generate text embeddings from input content. Embeddings are numerical representations of text that enable use cases such as clustering, similarity measurement, and information retrieval.

API Differences

This module handles the differences between Gemini API and Vertex AI embedding models:

  • Gemini API (gemini-embedding-001): Uses taskType parameter

  • Vertex AI (embeddinggemma): Uses prompt prefixes like "task: search result | query: "

The new/2 function automatically detects the model type and formats accordingly.

Fields

  • model: The embedding model to use (e.g., "gemini-embedding-001" or "embeddinggemma")
  • content: The content to embed (only text parts will be processed)
  • task_type: Optional task type for optimized embeddings
  • title: Optional title for retrieval documents
  • output_dimensionality: Optional dimension reduction for embeddings

Examples

# Simple embedding request (auto-detects model from auth)
EmbedContentRequest.new("What is the meaning of life?")

# With task type - automatically formats for model type
EmbedContentRequest.new("Document text here",
  task_type: :retrieval_document,
  title: "Important Document",
  output_dimensionality: 256
)

# For EmbeddingGemma, the text becomes:
# "title: Important Document | text: Document text here"

Summary

Types

t()
task_type()

Functions

format_for_embedding_gemma(text, task_type, opts \\ [])

Format text with the appropriate prompt prefix for EmbeddingGemma models.

new(text, opts \\ [])

Creates a new embedding request from text content.

new_for_api(text, api_type, opts \\ [])

Creates an embedding request with explicit API type specification.

to_api_map(request)

Converts the request struct to API-compatible map format.

Types

t()

@type t() :: %Gemini.Types.Request.EmbedContentRequest{
  content: Gemini.Types.Content.t(),
  model: String.t(),
  output_dimensionality: pos_integer() | nil,
  task_type: task_type() | nil,
  title: String.t() | nil
}

task_type()

@type task_type() ::
  :task_type_unspecified
  | :retrieval_query
  | :retrieval_document
  | :semantic_similarity
  | :classification
  | :clustering
  | :question_answering
  | :fact_verification
  | :code_retrieval_query

Functions

format_for_embedding_gemma(text, task_type, opts \\ [])

@spec format_for_embedding_gemma(String.t(), task_type() | nil, keyword()) ::
  String.t()

Format text with the appropriate prompt prefix for EmbeddingGemma models.

This is exposed for cases where you need to manually format text for EmbeddingGemma without going through the full request creation.

Parameters

  • text: The original text
  • task_type: Task type atom
  • opts: Options including :title for retrieval_document

Examples

format_for_embedding_gemma("My query", :retrieval_query)
#=> "task: search result | query: My query"

format_for_embedding_gemma("My document", :retrieval_document, title: "Title")
#=> "title: Title | text: My document"

new(text, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Creates a new embedding request from text content.

Automatically handles model-specific formatting:

  • For Gemini embedding models: Uses taskType parameter
  • For EmbeddingGemma: Prepends prompt prefix to text content

Parameters

  • text: The text to embed
  • opts: Optional keyword list of options
    • :model: Model to use (default: auto-detected based on auth)
    • :task_type: Task type for optimized embeddings
    • :title: Title for retrieval documents (required for EmbeddingGemma with :retrieval_document)
    • :output_dimensionality: Dimension reduction

Examples

# Basic usage (auto-detects model)
EmbedContentRequest.new("What is AI?")

# With task type (works with both APIs)
EmbedContentRequest.new("Document content",
  task_type: :retrieval_document,
  title: "AI Overview"
)

# Explicit model selection
EmbedContentRequest.new("Query text",
  model: "embeddinggemma",
  task_type: :retrieval_query
)
# Text becomes: "task: search result | query: Query text"

new_for_api(text, api_type, opts \\ [])

@spec new_for_api(String.t(), :gemini | :vertex_ai, keyword()) :: t()

Creates an embedding request with explicit API type specification.

Use this when you need to force a specific API's embedding model regardless of the current authentication configuration.

Parameters

  • text: The text to embed
  • api_type: :gemini or :vertex_ai
  • opts: Same options as new/2

Examples

# Force Gemini API embedding model
EmbedContentRequest.new_for_api("Query", :gemini, task_type: :retrieval_query)

# Force Vertex AI embedding model
EmbedContentRequest.new_for_api("Document", :vertex_ai, task_type: :retrieval_document)

to_api_map(request)

@spec to_api_map(t()) :: map()

Converts the request struct to API-compatible map format.

Converts snake_case field names to camelCase as required by the Gemini API. For EmbeddingGemma models, the task type is already embedded in the text content.