Skip to content

Embeddings

BaseRagasEmbedding

BaseRagasEmbedding(cache: Optional[CacheInterface] = None)

Bases: CachedCopyable, ABC

Modern abstract base class for Ragas embedding implementations.

This class provides a consistent interface for embedding text using various providers. Implementations should provide both sync and async methods for embedding single texts, with batch methods automatically provided.

Args: cache: Optional cache backend for caching embeddings. Use DiskCacheBackend() for persistent caching.

Source code in src/ragas/embeddings/base.py
def __init__(self, cache: t.Optional[CacheInterface] = None):
    """Initialize embedding with optional caching.

    Args:
        cache: Optional cache backend for caching embeddings.
            Use DiskCacheBackend() for persistent caching.
    """
    self.cache = cache
    self._wrap_with_cache()

embed_text abstractmethod

embed_text(text: str, **kwargs: Any) -> List[float]

Embed a single text.

Args: text: The text to embed **kwargs: Additional arguments for the embedding call

Returns: List of floats representing the embedding

Source code in src/ragas/embeddings/base.py
@abstractmethod
def embed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Embed a single text.

    Args:
        text: The text to embed
        **kwargs: Additional arguments for the embedding call

    Returns:
        List of floats representing the embedding
    """
    pass

aembed_text abstractmethod async

aembed_text(text: str, **kwargs: Any) -> List[float]

Asynchronously embed a single text.

Args: text: The text to embed **kwargs: Additional arguments for the embedding call

Returns: List of floats representing the embedding

Source code in src/ragas/embeddings/base.py
@abstractmethod
async def aembed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Asynchronously embed a single text.

    Args:
        text: The text to embed
        **kwargs: Additional arguments for the embedding call

    Returns:
        List of floats representing the embedding
    """
    pass

embed_texts

embed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Embed multiple texts.

Default implementation processes texts individually. Override for batch optimization.

Args: texts: List of texts to embed **kwargs: Additional arguments for the embedding calls

Returns: List of embeddings, one for each input text

Source code in src/ragas/embeddings/base.py
def embed_texts(self, texts: t.List[str], **kwargs: t.Any) -> t.List[t.List[float]]:
    """Embed multiple texts.

    Default implementation processes texts individually. Override for
    batch optimization.

    Args:
        texts: List of texts to embed
        **kwargs: Additional arguments for the embedding calls

    Returns:
        List of embeddings, one for each input text
    """
    texts = validate_texts(texts)
    return [self.embed_text(text, **kwargs) for text in texts]

aembed_texts async

aembed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Asynchronously embed multiple texts.

Default implementation processes texts concurrently. Override for batch optimization.

Args: texts: List of texts to embed **kwargs: Additional arguments for the embedding calls

Returns: List of embeddings, one for each input text

Source code in src/ragas/embeddings/base.py
async def aembed_texts(
    self, texts: t.List[str], **kwargs: t.Any
) -> t.List[t.List[float]]:
    """Asynchronously embed multiple texts.

    Default implementation processes texts concurrently. Override for
    batch optimization.

    Args:
        texts: List of texts to embed
        **kwargs: Additional arguments for the embedding calls

    Returns:
        List of embeddings, one for each input text
    """
    texts = validate_texts(texts)
    tasks = [self.aembed_text(text, **kwargs) for text in texts]
    return await asyncio.gather(*tasks)

OpenAIEmbeddings

OpenAIEmbeddings(
    client: Any,
    model: str = "text-embedding-3-small",
    cache: Optional[CacheInterface] = None,
)

Bases: BaseRagasEmbedding

OpenAI embeddings implementation with batch optimization.

Supports both sync and async OpenAI clients with automatic detection. Provides optimized batch processing for better performance.

Source code in src/ragas/embeddings/openai_provider.py
def __init__(
    self,
    client: t.Any,
    model: str = "text-embedding-3-small",
    cache: t.Optional[CacheInterface] = None,
):
    super().__init__(cache=cache)
    self.client = client
    self.model = model
    self.is_async = self._check_client_async(client)

embed_text

embed_text(text: str, **kwargs: Any) -> List[float]

Embed a single text using OpenAI.

For async clients, this will run the async method in the appropriate event loop.

Source code in src/ragas/embeddings/openai_provider.py
def embed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Embed a single text using OpenAI.

    For async clients, this will run the async method in the appropriate event loop.
    """
    if self.is_async:
        return self._run_async_in_current_loop(self.aembed_text(text, **kwargs))
    response = self.client.embeddings.create(**self._request(text, kwargs))
    return self._vectors(response)[0]

aembed_text async

aembed_text(text: str, **kwargs: Any) -> List[float]

Asynchronously embed a single text using OpenAI.

Source code in src/ragas/embeddings/openai_provider.py
async def aembed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Asynchronously embed a single text using OpenAI."""
    if not self.is_async:
        # A sync client runs on a worker thread, so the async collections
        # metrics work with OpenAI() too (#68).
        return await asyncio.to_thread(self.embed_text, text, **kwargs)
    response = await self.client.embeddings.create(**self._request(text, kwargs))
    return self._vectors(response)[0]

embed_texts

embed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Embed multiple texts using OpenAI's batch API for optimization.

Source code in src/ragas/embeddings/openai_provider.py
def embed_texts(self, texts: t.List[str], **kwargs: t.Any) -> t.List[t.List[float]]:
    """Embed multiple texts using OpenAI's batch API for optimization."""
    texts = validate_texts(texts)
    if not texts:
        return []
    if self.is_async:
        return self._run_async_in_current_loop(self.aembed_texts(texts, **kwargs))
    # OpenAI supports batch embedding natively
    response = self.client.embeddings.create(**self._request(texts, kwargs))
    return self._vectors(response)

aembed_texts async

aembed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Asynchronously embed multiple texts using OpenAI's batch API.

Source code in src/ragas/embeddings/openai_provider.py
async def aembed_texts(
    self, texts: t.List[str], **kwargs: t.Any
) -> t.List[t.List[float]]:
    """Asynchronously embed multiple texts using OpenAI's batch API."""
    texts = validate_texts(texts)
    if not texts:
        return []
    if not self.is_async:
        # A sync client runs on a worker thread, so the async collections
        # metrics work with OpenAI() too (#68).
        return await asyncio.to_thread(self.embed_texts, texts, **kwargs)
    response = await self.client.embeddings.create(**self._request(texts, kwargs))
    return self._vectors(response)

GoogleEmbeddings

GoogleEmbeddings(
    client: Optional[Any] = None,
    model: str = "gemini-embedding-001",
    use_vertex: bool = False,
    project_id: Optional[str] = None,
    location: Optional[str] = "us-central1",
    cache: Optional[CacheInterface] = None,
    **kwargs: Any,
)

Bases: BaseRagasEmbedding

Google embeddings using Vertex AI or Google AI (Gemini).

Supports both Vertex AI and Google AI (Gemini) embedding models. For Vertex AI, requires google-cloud-aiplatform package. For Google AI, supports both: - New SDK (google-genai): Recommended, uses genai.Client() - Old SDK (google-generativeai): Deprecated (support ends Aug 2025)

The client parameter is flexible: - For new SDK: genai.Client(api_key="...") instance - For old SDK: None (auto-imports), the genai module, or a GenerativeModel instance - For Vertex (required): a google-genai genai.Client(vertexai=True, ...), a vertexai.language_models.TextEmbeddingModel instance, or any other object once vertexai.init() has been called (the model named by model is then loaded once, on first use, and reused)

Note: Unlike LLM generation, embeddings work correctly with both SDKs. The known instructor safety settings issue (github.com/567-labs/instructor/issues/1658) only affects LLM generation, not embeddings.

Examples: # New SDK (google-genai) - recommended from google import genai client = genai.Client(api_key="...") embeddings = GoogleEmbeddings(client=client, model="gemini-embedding-001")

# Old SDK (google-generativeai) - deprecated
import google.generativeai as genai
genai.configure(api_key="...")
embeddings = GoogleEmbeddings(client=genai, model="gemini-embedding-2")

# Auto-import (tries new SDK first, falls back to old)
embeddings = GoogleEmbeddings(model="gemini-embedding-2")
Source code in src/ragas/embeddings/google_provider.py
def __init__(
    self,
    client: t.Optional[t.Any] = None,
    model: str = "gemini-embedding-001",
    use_vertex: bool = False,
    project_id: t.Optional[str] = None,
    location: t.Optional[str] = "us-central1",
    cache: t.Optional[CacheInterface] = None,
    **kwargs: t.Any,
):
    super().__init__(cache=cache)
    self._original_client = client
    self.model = model
    self.use_vertex = use_vertex
    self.project_id = project_id
    self.location = location
    self.kwargs = kwargs

    # Track which SDK is being used (new google-genai vs old google-generativeai)
    self._use_new_sdk = False
    # Vertex TextEmbeddingModel, loaded once by _get_vertex_model() (#216)
    self._vertex_model: t.Any = None

    # Resolve the actual client to use
    self.client = self._resolve_client(client, use_vertex)

embed_text

embed_text(text: str, **kwargs: Any) -> List[float]

Embed a single text using Google's embedding service.

Source code in src/ragas/embeddings/google_provider.py
def embed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Embed a single text using Google's embedding service."""
    if self._uses_vertex_sdk():
        return self._embed_text_vertex(text, **kwargs)
    else:
        return self._embed_text_genai(text, **kwargs)

aembed_text async

aembed_text(text: str, **kwargs: Any) -> List[float]

Asynchronously embed a single text using Google's embedding service.

Google's SDK doesn't provide native async support, so we use ThreadPoolExecutor.

Source code in src/ragas/embeddings/google_provider.py
async def aembed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Asynchronously embed a single text using Google's embedding service.

    Google's SDK doesn't provide native async support, so we use ThreadPoolExecutor.
    """
    return await run_sync_in_async(self.embed_text, text, **kwargs)

embed_texts

embed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Embed multiple texts using Google's embedding service.

Source code in src/ragas/embeddings/google_provider.py
def embed_texts(self, texts: t.List[str], **kwargs: t.Any) -> t.List[t.List[float]]:
    """Embed multiple texts using Google's embedding service."""
    texts = validate_texts(texts)
    if not texts:
        return []

    if self._uses_vertex_sdk():
        return self._embed_texts_vertex(texts, **kwargs)
    else:
        return self._embed_texts_genai(texts, **kwargs)

aembed_texts async

aembed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Asynchronously embed multiple texts using Google's embedding service.

Source code in src/ragas/embeddings/google_provider.py
async def aembed_texts(
    self, texts: t.List[str], **kwargs: t.Any
) -> t.List[t.List[float]]:
    """Asynchronously embed multiple texts using Google's embedding service."""
    texts = validate_texts(texts)
    if not texts:
        return []

    return await run_sync_in_async(self.embed_texts, texts, **kwargs)

LiteLLMEmbeddings

LiteLLMEmbeddings(
    model: str,
    api_key: Optional[str] = None,
    api_base: Optional[str] = None,
    api_version: Optional[str] = None,
    timeout: int = 600,
    max_retries: int = 3,
    batch_size: Optional[int] = None,
    cache: Optional[CacheInterface] = None,
    rate_limit: Optional[RateLimit] = None,
    **litellm_params: Any,
)

Bases: BaseRagasEmbedding

Universal embedding interface using LiteLLM.

Supports 100+ models across OpenAI, Azure, Google, Cohere, Anthropic, and more. Provides intelligent batching and provider-specific optimizations.

rate_limit (a ragas.rate_limit.RateLimit) paces every embedding request: one per call, or one per batch (#171).

Source code in src/ragas/embeddings/litellm_provider.py
def __init__(
    self,
    model: str,
    api_key: t.Optional[str] = None,
    api_base: t.Optional[str] = None,
    api_version: t.Optional[str] = None,
    timeout: int = 600,
    max_retries: int = 3,
    batch_size: t.Optional[int] = None,
    cache: t.Optional[CacheInterface] = None,
    rate_limit: t.Optional["RateLimit"] = None,
    **litellm_params: t.Any,
):
    super().__init__(cache=cache)
    self.litellm = safe_import("litellm", "litellm")
    self.model = model
    self.api_key = api_key
    self.api_base = api_base
    self.api_version = api_version
    self.timeout = timeout
    self.max_retries = max_retries
    # The table is keyed by the real provider ("openai", "cohere", ...),
    # which LiteLLM reads from the model string. Passing "litellm" made
    # every model get the fallback of 10 (#216).
    self._default_batch_size = get_optimal_batch_size(
        _litellm_provider(self.litellm, model), model
    )
    self.batch_size = batch_size or self._default_batch_size
    self.litellm_params = litellm_params
    self.rate_limit = rate_limit

embed_text

embed_text(text: str, **kwargs: Any) -> List[float]

Embed a single text using LiteLLM.

Source code in src/ragas/embeddings/litellm_provider.py
def embed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Embed a single text using LiteLLM."""
    return self._embed_batch([text], kwargs)[0]

aembed_text async

aembed_text(text: str, **kwargs: Any) -> List[float]

Asynchronously embed a single text using LiteLLM.

Source code in src/ragas/embeddings/litellm_provider.py
async def aembed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Asynchronously embed a single text using LiteLLM."""
    return (await self._aembed_batch([text], kwargs))[0]

embed_texts

embed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Embed multiple texts using LiteLLM with intelligent batching.

Source code in src/ragas/embeddings/litellm_provider.py
def embed_texts(self, texts: t.List[str], **kwargs: t.Any) -> t.List[t.List[float]]:
    """Embed multiple texts using LiteLLM with intelligent batching."""
    texts = validate_texts(texts)
    embeddings: t.List[t.List[float]] = []
    for batch in batch_texts(texts, self.batch_size) if texts else []:
        embeddings.extend(self._embed_batch(batch, kwargs))
    return embeddings

aembed_texts async

aembed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Asynchronously embed multiple texts using LiteLLM with intelligent batching.

Source code in src/ragas/embeddings/litellm_provider.py
async def aembed_texts(
    self, texts: t.List[str], **kwargs: t.Any
) -> t.List[t.List[float]]:
    """Asynchronously embed multiple texts using LiteLLM with intelligent batching."""
    texts = validate_texts(texts)
    embeddings: t.List[t.List[float]] = []
    for batch in batch_texts(texts, self.batch_size) if texts else []:
        embeddings.extend(await self._aembed_batch(batch, kwargs))
    return embeddings

HuggingFaceEmbeddings

HuggingFaceEmbeddings(
    model: str,
    use_api: bool = False,
    api_key: Optional[str] = None,
    device: Optional[str] = None,
    normalize_embeddings: bool = True,
    batch_size: int = 32,
    cache: Optional[CacheInterface] = None,
    **model_kwargs: Any,
)

Bases: BaseRagasEmbedding

HuggingFace embeddings supporting both local and API-based models.

Supports sentence-transformers for local models and HuggingFace API for hosted models. Provides efficient batch processing and caching.

Source code in src/ragas/embeddings/huggingface_provider.py
def __init__(
    self,
    model: str,
    use_api: bool = False,
    api_key: t.Optional[str] = None,
    device: t.Optional[str] = None,
    normalize_embeddings: bool = True,
    batch_size: int = 32,
    cache: t.Optional[CacheInterface] = None,
    **model_kwargs: t.Any,
):
    super().__init__(cache=cache)
    self.model = model
    self.use_api = use_api
    self.api_key = api_key
    self.device = device
    self.normalize_embeddings = normalize_embeddings
    self.batch_size = batch_size
    self.model_kwargs = model_kwargs

    if use_api:
        self._setup_api_client()
    else:
        self._setup_local_model()

embed_text

embed_text(text: str, **kwargs: Any) -> List[float]

Embed a single text using HuggingFace.

Source code in src/ragas/embeddings/huggingface_provider.py
def embed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Embed a single text using HuggingFace."""
    if self.use_api:
        return self._embed_text_api(text, **kwargs)
    else:
        return self._embed_text_local(text, **kwargs)

aembed_text async

aembed_text(text: str, **kwargs: Any) -> List[float]

Asynchronously embed a single text using HuggingFace.

Source code in src/ragas/embeddings/huggingface_provider.py
async def aembed_text(self, text: str, **kwargs: t.Any) -> t.List[float]:
    """Asynchronously embed a single text using HuggingFace."""
    if self.use_api:
        return await self._aembed_text_api(text, **kwargs)
    else:
        return await run_sync_in_async(self._embed_text_local, text, **kwargs)

embed_texts

embed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Embed multiple texts using HuggingFace with batching.

Source code in src/ragas/embeddings/huggingface_provider.py
def embed_texts(self, texts: t.List[str], **kwargs: t.Any) -> t.List[t.List[float]]:
    """Embed multiple texts using HuggingFace with batching."""
    texts = validate_texts(texts)
    if not texts:
        return []

    if self.use_api:
        return self._embed_texts_api(texts, **kwargs)
    else:
        return self._embed_texts_local(texts, **kwargs)

aembed_texts async

aembed_texts(
    texts: List[str], **kwargs: Any
) -> List[List[float]]

Asynchronously embed multiple texts using HuggingFace.

Source code in src/ragas/embeddings/huggingface_provider.py
async def aembed_texts(
    self, texts: t.List[str], **kwargs: t.Any
) -> t.List[t.List[float]]:
    """Asynchronously embed multiple texts using HuggingFace."""
    texts = validate_texts(texts)
    if not texts:
        return []

    if self.use_api:
        return await run_sync_in_async(self._embed_texts_api, texts, **kwargs)
    else:
        return await run_sync_in_async(self._embed_texts_local, texts, **kwargs)

embedding_factory

embedding_factory(*args, **kwargs)

Deprecated: Use embedding_factory from base module directly.

Source code in src/ragas/embeddings/__init__.py
def embedding_factory(*args, **kwargs):
    """Deprecated: Use embedding_factory from base module directly."""
    import warnings

    warnings.warn(
        "Importing embedding_factory from ragas.embeddings is deprecated. "
        "Import directly from ragas.embeddings.base or use modern providers: "
        "from ragas.embeddings import OpenAIEmbeddings, GoogleEmbeddings, HuggingFaceEmbeddings",
        DeprecationWarning,
        stacklevel=2,
    )
    return _embedding_factory(*args, **kwargs)