Skip to content

Build and run agents you can see, understand and trust.

refactor(embedding): refactor the embedding models for the agent service (#1852)

DavdGaob623ecf71be6
diff --git a/src/agentscope/app/_service/__init__.py b/src/agentscope/app/_service/__init__.py
index 280b55644..77c65bb5c 100644
--- a/src/agentscope/app/_service/__init__.py
+++ b/src/agentscope/app/_service/__init__.py
@@ -1,6 +1,7 @@
# -*- coding: utf-8 -*-
"""Service layer for the AgentScope app."""
from ._chat import ChatService
+from ._embedding import get_embedding_model
from ._model import get_model
from ._session import SessionService
from ._toolkit import get_toolkit
@@ -8,6 +9,7 @@ from ._toolkit import get_toolkit
__all__ = [
"ChatService",
"SessionService",
+ "get_embedding_model",
"get_model",
"get_toolkit",
]
diff --git a/src/agentscope/app/_service/_embedding.py b/src/agentscope/app/_service/_embedding.py
new file mode 100644
index 000000000..5fd2bc948
--- /dev/null
+++ b/src/agentscope/app/_service/_embedding.py
@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+"""Embedding model service: builds an EmbeddingModelBase from stored
+credential + config.
+
+Mirrors :mod:`._model` (which does the same for chat models).
+"""
+from fastapi import HTTPException, status
+
+from ..storage import StorageBase, EmbeddingModelConfig
+from ...credential import CredentialFactory
+from ...embedding import EmbeddingModelBase
+
+
+async def get_embedding_model(
+ user_id: str,
+ config: EmbeddingModelConfig,
+ storage: StorageBase,
+) -> EmbeddingModelBase:
+ """Construct an embedding model from a stored credential and config.
+
+ This is the embedding counterpart of
+ :func:`~agentscope.app._service._model.get_model`. It loads the
+ user's credential from storage, resolves the matching embedding
+ model class, looks up the model card for ``context_size``, and
+ constructs a ready-to-use instance.
+
+ Args:
+ user_id (`str`):
+ The authenticated user id (credential owner).
+ config (`EmbeddingModelConfig`):
+ The embedding model configuration containing
+ ``type``, ``credential_id``, ``model``, and
+ ``parameters``.
+ storage (`StorageBase`):
+ The storage backend for loading credentials.
+
+ Returns:
+ `EmbeddingModelBase`:
+ A configured embedding model instance.
+
+ Raises:
+ `HTTPException`:
+ 404 if the credential is not found.
+ 400 if the provider does not support embedding.
+ """
+ # 1. Load credential from storage.
+ credential_record = await storage.get_credential(
+ user_id,
+ config.credential_id,
+ )
+ if credential_record is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Credential {config.credential_id!r} not found.",
+ )
+
+ credential = CredentialFactory.from_dict(credential_record.data)
+
+ # 2. Resolve the embedding model class from the credential type.
+ credential_cls = CredentialFactory.get_credential_class(config.type)
+ if credential_cls is None:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=f"Provider {config.type!r} not found.",
+ )
+
+ embedding_cls = credential_cls.get_embedding_model_class()
+ if embedding_cls is None:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=(
+ f"Provider {config.type!r} does not support "
+ f"embedding models."
+ ),
+ )
+
+ # 3. Look up the model card for context_size.
+ context_size: int | None = None
+ for card in embedding_cls.list_models():
+ if card.name == config.model:
+ context_size = card.context_size
+ break
+
+ # 4. Build parameters.
+ parameters = (
+ embedding_cls.Parameters(**config.parameters)
+ if config.parameters
+ else None
+ )
+
+ # 5. Construct the model, passing context_size from the card.
+ kwargs: dict = {
+ "credential": credential,
+ "model": config.model,
+ "parameters": parameters,
+ }
+ if context_size is not None:
+ kwargs["context_size"] = context_size
+
+ return embedding_cls(**kwargs)
diff --git a/src/agentscope/app/storage/__init__.py b/src/agentscope/app/storage/__init__.py
index 3038ff139..86da74093 100644
--- a/src/agentscope/app/storage/__init__.py
+++ b/src/agentscope/app/storage/__init__.py
@@ -14,6 +14,7 @@ from ._model import (
SessionRecord,
SessionSource,
ChatModelConfig,
+ EmbeddingModelConfig,
TeamData,
TeamRecord,
UserRecord,
@@ -30,6 +31,7 @@ __all__ = [
"SessionRecord",
"SessionSource",
"ChatModelConfig",
+ "EmbeddingModelConfig",
"TeamData",
"TeamRecord",
"UserRecord",
diff --git a/src/agentscope/app/storage/_model/__init__.py b/src/agentscope/app/storage/_model/__init__.py
index e376acbec..74f61d06b 100644
--- a/src/agentscope/app/storage/_model/__init__.py
+++ b/src/agentscope/app/storage/_model/__init__.py
@@ -8,6 +8,7 @@ from ._session import (
SessionRecord,
SessionConfig,
ChatModelConfig,
+ EmbeddingModelConfig,
SessionSource,
)
from ._team import TeamRecord, TeamData
@@ -24,6 +25,7 @@ __all__ = [
"SessionRecord",
"SessionSource",
"ChatModelConfig",
+ "EmbeddingModelConfig",
"TeamData",
"TeamRecord",
"UserRecord",
diff --git a/src/agentscope/app/storage/_model/_session.py b/src/agentscope/app/storage/_model/_session.py
index 0c1e1c79f..19d97b82b 100644
--- a/src/agentscope/app/storage/_model/_session.py
+++ b/src/agentscope/app/storage/_model/_session.py
@@ -32,6 +32,28 @@ class ChatModelConfig(BaseModel):
"""The model parameters."""
+class EmbeddingModelConfig(BaseModel):
+ """Configuration for constructing an embedding model from a credential.
+
+ Mirrors :class:`ChatModelConfig` but targets
+ :class:`~agentscope.embedding.EmbeddingModelBase` subclasses.
+ Used by :class:`KnowledgeBaseRecord` to persist the user's
+ embedding model selection.
+ """
+
+ type: str
+ """The provider type (e.g. ``"openai_credential"``)."""
+
+ credential_id: str
+ """The credential id to use for authentication."""
+
+ model: str
+ """The embedding model name (e.g. ``"text-embedding-3-small"``)."""
+
+ parameters: dict
+ """The embedding model parameters (e.g. ``{"dimensions": 1024}``)."""
+
+
class SessionConfig(BaseModel):
"""Session configuration — set at creation, updatable via PATCH."""
diff --git a/src/agentscope/credential/_base.py b/src/agentscope/credential/_base.py
index 2bcd918b3..72f89940f 100644
--- a/src/agentscope/credential/_base.py
+++ b/src/agentscope/credential/_base.py
@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Type
from pydantic import BaseModel, Field
if TYPE_CHECKING:
+ from ..embedding import EmbeddingModelBase
from ..model import ChatModelBase, ModelCard
@@ -48,3 +49,18 @@ class CredentialBase(BaseModel):
A list of candidate models described by their model cards.
"""
return cls.get_chat_model_class().list_models()
+
+ @classmethod
+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"] | None:
+ """Return the :class:`EmbeddingModelBase` subclass that consumes
+ this credential, or ``None`` if this provider does not support
+ embedding models.
+
+ Subclasses that have a matching embedding implementation should
+ override this method. The default returns ``None``.
+
+ Returns:
+ `Type[EmbeddingModelBase] | None`:
+ The embedding model class, or ``None``.
+ """
+ return None
diff --git a/src/agentscope/credential/_dashscope.py b/src/agentscope/credential/_dashscope.py
index 1289acd41..8e9a85666 100644
--- a/src/agentscope/credential/_dashscope.py
+++ b/src/agentscope/credential/_dashscope.py
@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
if TYPE_CHECKING:
+ from ..embedding import EmbeddingModelBase
from ..model import ChatModelBase
_DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
@@ -41,3 +42,10 @@ class DashScopeCredential(CredentialBase):
from ..model import DashScopeChatModel
return DashScopeChatModel
+
+ @classmethod
+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+ """Return the DashScopeEmbeddingModel class."""
+ from ..embedding import DashScopeEmbeddingModel
+
+ return DashScopeEmbeddingModel
diff --git a/src/agentscope/credential/_gemini.py b/src/agentscope/credential/_gemini.py
index 67bd65656..43775cc82 100644
--- a/src/agentscope/credential/_gemini.py
+++ b/src/agentscope/credential/_gemini.py
@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
if TYPE_CHECKING:
+ from ..embedding import EmbeddingModelBase
from ..model import ChatModelBase
@@ -31,3 +32,10 @@ class GeminiCredential(CredentialBase):
from ..model import GeminiChatModel
return GeminiChatModel
+
+ @classmethod
+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+ """Return the GeminiEmbeddingModel class."""
+ from ..embedding import GeminiEmbeddingModel
+
+ return GeminiEmbeddingModel
diff --git a/src/agentscope/credential/_ollama.py b/src/agentscope/credential/_ollama.py
index 84bdee4f1..c2c27f93c 100644
--- a/src/agentscope/credential/_ollama.py
+++ b/src/agentscope/credential/_ollama.py
@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field
from ._base import CredentialBase
if TYPE_CHECKING:
+ from ..embedding import EmbeddingModelBase
from ..model import ChatModelBase
@@ -35,3 +36,10 @@ class OllamaCredential(CredentialBase):
from ..model import OllamaChatModel
return OllamaChatModel
+
+ @classmethod
+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+ """Return the OllamaEmbeddingModel class."""
+ from ..embedding import OllamaEmbeddingModel
+
+ return OllamaEmbeddingModel
diff --git a/src/agentscope/credential/_openai.py b/src/agentscope/credential/_openai.py
index a855ee66a..6cc132e7b 100644
--- a/src/agentscope/credential/_openai.py
+++ b/src/agentscope/credential/_openai.py
@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
if TYPE_CHECKING:
+ from ..embedding import EmbeddingModelBase
from ..model import ChatModelBase
@@ -46,3 +47,10 @@ class OpenAICredential(CredentialBase):
from ..model import OpenAIChatModel
return OpenAIChatModel
+
+ @classmethod
+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:
+ """Return the OpenAIEmbeddingModel class."""
+ from ..embedding import OpenAIEmbeddingModel
+
+ return OpenAIEmbeddingModel
diff --git a/src/agentscope/embedding/__init__.py b/src/agentscope/embedding/__init__.py
index de2c2711f..43731f1f0 100644
--- a/src/agentscope/embedding/__init__.py
+++ b/src/agentscope/embedding/__init__.py
@@ -2,26 +2,26 @@
"""The embedding module in agentscope."""
from ._embedding_base import EmbeddingModelBase
+from ._embedding_model_card import EmbeddingModelCard
from ._embedding_usage import EmbeddingUsage
from ._embedding_response import EmbeddingResponse
-from ._dashscope_embedding import DashScopeTextEmbedding
-from ._dashscope_multimodal_embedding import DashScopeMultiModalEmbedding
-from ._openai_embedding import OpenAITextEmbedding
-from ._gemini_embedding import GeminiTextEmbedding
-from ._ollama_embedding import OllamaTextEmbedding
+from ._dashscope import DashScopeEmbeddingModel
+from ._openai import OpenAIEmbeddingModel
+from ._gemini import GeminiEmbeddingModel
+from ._ollama import OllamaEmbeddingModel
from ._cache_base import EmbeddingCacheBase
from ._file_cache import FileEmbeddingCache
__all__ = [
"EmbeddingModelBase",
+ "EmbeddingModelCard",
"EmbeddingUsage",
"EmbeddingResponse",
- "DashScopeTextEmbedding",
- "DashScopeMultiModalEmbedding",
- "OpenAITextEmbedding",
- "GeminiTextEmbedding",
- "OllamaTextEmbedding",
+ "DashScopeEmbeddingModel",
+ "OpenAIEmbeddingModel",
+ "GeminiEmbeddingModel",
+ "OllamaEmbeddingModel",
"EmbeddingCacheBase",
"FileEmbeddingCache",
]
diff --git a/src/agentscope/embedding/_dashscope/__init__.py b/src/agentscope/embedding/_dashscope/__init__.py
new file mode 100644
index 000000000..37f3c96a6
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The DashScope embedding API modules."""
+
+from ._model import DashScopeEmbeddingModel
+
+__all__ = [
+ "DashScopeEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_dashscope/_model.py b/src/agentscope/embedding/_dashscope/_model.py
new file mode 100644
index 000000000..cd31edeca
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_model.py
@@ -0,0 +1,508 @@
+# -*- coding: utf-8 -*-
+"""The DashScope embedding model.
+
+Handles both text-only and multimodal models under a single class.
+Text models (``text-embedding-v3``, ``text-embedding-v4``) accept
+``list[str]``. Multimodal models (``qwen*-vl-embedding``,
+``multimodal-embedding-*``, ``tongyi-embedding-vision-*``)
+additionally accept :class:`~agentscope.message.DataBlock`.
+The model name determines which DashScope API endpoint is used.
+"""
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from dataclasses import dataclass
+from typing import Any
+
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._embedding_base import EmbeddingModelBase
+from ..._logging import logger
+from ...credential import CredentialBase
+from ...message import DataBlock, Base64Source, URLSource
+
+#: Model name prefixes that route to the multimodal API.
+_MULTIMODAL_PREFIXES = (
+ "multimodal-embedding-",
+ "tongyi-embedding-vision-",
+ "qwen3-vl-embedding",
+ "qwen2.5-vl-embedding",
+)
+
+
+@dataclass
+class _MultimodalLimits:
+ """Per-request constraints for a multimodal embedding model."""
+
+ max_elements: int = 20
+ """Maximum total content elements per API call."""
+
+ max_images: int = 5
+ """Maximum image elements per API call."""
+
+ max_videos: int = 1
+ """Maximum video elements per API call."""
+
+
+#: Known per-model multimodal constraints (from DashScope docs).
+_MODEL_LIMITS: dict[str, _MultimodalLimits] = {
+ "qwen3-vl-embedding": _MultimodalLimits(
+ max_elements=20,
+ max_images=5,
+ max_videos=1,
+ ),
+ "qwen2.5-vl-embedding": _MultimodalLimits(
+ max_elements=20,
+ max_images=5,
+ max_videos=1,
+ ),
+ "tongyi-embedding-vision-plus": _MultimodalLimits(
+ max_elements=20,
+ max_images=64,
+ max_videos=8,
+ ),
+ "tongyi-embedding-vision-flash": _MultimodalLimits(
+ max_elements=20,
+ max_images=64,
+ max_videos=8,
+ ),
+ "multimodal-embedding-v1": _MultimodalLimits(
+ max_elements=20,
+ max_images=1,
+ max_videos=1,
+ ),
+}
+
+#: Fallback for unknown multimodal models — safest constraints.
+_DEFAULT_LIMITS = _MultimodalLimits(
+ max_elements=20,
+ max_images=1,
+ max_videos=1,
+)
+
+
+class DashScopeEmbeddingModel(EmbeddingModelBase[str | DataBlock]):
+ """Unified DashScope embedding model.
+
+ Routes to the text or multimodal DashScope API based on the model
+ name.
+
+ - **Text mode** (``text-embedding-*``): uses the base class's
+ simple batch splitting + concurrent retry.
+ - **Multimodal mode** (``qwen*-vl-*``, ``multimodal-*``,
+ ``tongyi-embedding-vision-*``): overrides ``__call__`` to
+ perform content-aware batching that respects per-model limits
+ on total elements, images, and videos per request.
+ """
+
+ #: Text-mode batch size (from DashScope docs: 10 for v3/v4, 25 for
+ #: v1/v2). Multimodal models use :data:`_MODEL_LIMITS` instead.
+ _TEXT_BATCH_SIZE: int = 10
+
+ def __init__(
+ self,
+ credential: CredentialBase,
+ model: str,
+ parameters: "DashScopeEmbeddingModel.Parameters | None" = None,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ context_size: int = 8192,
+ max_retries: int = 3,
+ retry_delay: float = 1.0,
+ ) -> None:
+ """Initialize the DashScope embedding model.
+
+ Args:
+ credential (`CredentialBase`):
+ A :class:`~agentscope.credential.DashScopeCredential`
+ instance providing the API key.
+ model (`str`):
+ The embedding model name (e.g.
+ ``"text-embedding-v4"`` or
+ ``"qwen3-vl-embedding"``).
+ parameters (`DashScopeEmbeddingModel.Parameters | None`, \
+ defaults to ``None``):
+ User-configurable parameters (currently only
+ ``dimensions``).
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+ ``None``):
+ Optional embedding cache.
+ context_size (`int`, defaults to ``8192``):
+ Maximum input tokens per text.
+ max_retries (`int`, defaults to ``3``):
+ Number of retries on transient failures.
+ retry_delay (`float`, defaults to ``1.0``):
+ Seconds between retry attempts.
+ """
+ self._is_multimodal: bool = model.startswith(_MULTIMODAL_PREFIXES)
+
+ super().__init__(
+ credential=credential,
+ model=model,
+ parameters=parameters,
+ context_size=context_size,
+ batch_size=self._TEXT_BATCH_SIZE,
+ max_retries=max_retries,
+ retry_delay=retry_delay,
+ )
+ self.api_key: str = credential.api_key.get_secret_value()
+ self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+ # Resolve multimodal constraints.
+ if self._is_multimodal:
+ self._limits = _MODEL_LIMITS.get(model, _DEFAULT_LIMITS)
+
+ @classmethod
+ def _get_retryable_exceptions(cls) -> tuple[type[Exception], ...]:
+ """Return retryable exception types.
+
+ DashScope SDK does not expose typed exception classes. We
+ retry on ``RuntimeError``, which is raised when the API
+ returns a non-200 status code.
+ """
+ return (RuntimeError,)
+
+ # ------------------------------------------------------------------
+ # __call__ — override for multimodal content-aware batching
+ # ------------------------------------------------------------------
+
+ async def __call__(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Embed inputs with batching and retry.
+
+ For text models, delegates to the base class (simple
+ ``batch_size`` splitting). For multimodal models, performs
+ content-aware batching that respects per-model limits on
+ total elements, images, and videos per request.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ The input data to embed.
+ **kwargs:
+ Forwarded to the DashScope API.
+
+ Returns:
+ `EmbeddingResponse`: Merged response for all inputs.
+ """
+ if not self._is_multimodal:
+ # Text mode — use base class batching.
+ return await super().__call__(inputs, **kwargs)
+
+ # Multimodal mode — content-aware batching.
+ batches = self._split_multimodal_batches(inputs)
+
+ if len(batches) > 1:
+ logger.info(
+ "Embedding %d multimodal inputs in %d batches for "
+ "model %s (limits: elements=%d, images=%d, videos=%d).",
+ len(inputs),
+ len(batches),
+ self.model,
+ self._limits.max_elements,
+ self._limits.max_images,
+ self._limits.max_videos,
+ )
+
+ results: list[EmbeddingResponse] = await asyncio.gather(
+ *(self._call_with_retry(batch, **kwargs) for batch in batches),
+ )
+
+ return self._merge_responses(results)
+
+ def _split_multimodal_batches(
+ self,
+ inputs: list[str | DataBlock],
+ ) -> list[list[str | DataBlock]]:
+ """Split inputs into batches that satisfy multimodal limits.
+
+ Greedy algorithm: keep adding items to the current batch
+ until adding the next item would violate any constraint,
+ then start a new batch.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ All inputs to split.
+
+ Returns:
+ `list[list[str | DataBlock]]`: List of batches.
+ """
+ limits = self._limits
+ batches: list[list[str | DataBlock]] = []
+ current_batch: list[str | DataBlock] = []
+ n_elements = 0
+ n_images = 0
+ n_videos = 0
+
+ for item in inputs:
+ # Determine what this item contributes.
+ is_image = False
+ is_video = False
+ if isinstance(item, DataBlock):
+ media_type = item.source.media_type
+ is_image = media_type.startswith("image/")
+ is_video = media_type.startswith("video/")
+
+ # Check if adding this item would exceed any limit.
+ would_exceed = (
+ n_elements + 1 > limits.max_elements
+ or (is_image and n_images + 1 > limits.max_images)
+ or (is_video and n_videos + 1 > limits.max_videos)
+ )
+
+ if would_exceed and current_batch:
+ batches.append(current_batch)
+ current_batch = []
+ n_elements = 0
+ n_images = 0
+ n_videos = 0
+
+ current_batch.append(item)
+ n_elements += 1
+ if is_image:
+ n_images += 1
+ if is_video:
+ n_videos += 1
+
+ if current_batch:
+ batches.append(current_batch)
+
+ return batches
+
+ # ------------------------------------------------------------------
+ # _call_api — single batch dispatch
+ # ------------------------------------------------------------------
+
+ async def _call_api(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Route to the text or multimodal DashScope API.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ A single batch. For text models every element must be
+ ``str``; for multimodal models elements may also be
+ :class:`~agentscope.message.DataBlock`.
+ **kwargs:
+ Forwarded to the DashScope API.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ if self._is_multimodal:
+ return await self._call_multimodal(inputs, **kwargs)
+ return await self._call_text(inputs, **kwargs)
+
+ # ------------------------------------------------------------------
+ # Text API
+ # ------------------------------------------------------------------
+
+ async def _call_text(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the DashScope text embedding API for a single batch.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ Must all be ``str``; raises ``ValueError`` otherwise.
+ **kwargs:
+ Forwarded to the API.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ texts: list[str] = []
+ for item in inputs:
+ if not isinstance(item, str):
+ raise ValueError(
+ f"Text embedding model {self.model!r} only accepts "
+ f"str inputs, got {type(item).__name__}.",
+ )
+ texts.append(item)
+
+ api_kwargs: dict[str, Any] = {
+ "input": texts,
+ "model": self.model,
+ "dimension": self.dimensions,
+ **kwargs,
+ }
+
+ if self.embedding_cache:
+ cached = await self.embedding_cache.retrieve(
+ identifier=api_kwargs,
+ )
+ if cached:
+ return EmbeddingResponse(
+ embeddings=cached,
+ usage=EmbeddingUsage(tokens=0, time=0),
+ source="cache",
+ )
+
+ import dashscope
+
+ start_time = datetime.now()
+ response = dashscope.embeddings.TextEmbedding.call(
+ api_key=self.api_key,
+ **api_kwargs,
+ )
+ time = (datetime.now() - start_time).total_seconds()
+
+ if response.status_code != 200:
+ raise RuntimeError(
+ f"DashScope text embedding API error: {response}",
+ )
+
+ embeddings = [
+ entry["embedding"] for entry in response.output["embeddings"]
+ ]
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=api_kwargs,
+ embeddings=embeddings,
+ )
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(
+ tokens=response.usage["total_tokens"],
+ time=time,
+ ),
+ )
+
+ # ------------------------------------------------------------------
+ # Multimodal API
+ # ------------------------------------------------------------------
+
+ async def _call_multimodal(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the DashScope multimodal embedding API for a single batch.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ ``str`` for text, ``DataBlock`` for images / videos.
+ **kwargs:
+ Forwarded to the API.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ formatted: list[dict[str, str]] = []
+ for item in inputs:
+ if isinstance(item, str):
+ formatted.append({"text": item})
+ elif isinstance(item, DataBlock):
+ formatted.append(self._format_data_block(item))
+ else:
+ raise ValueError(
+ f"Invalid input: {item!r}. Expected str or DataBlock.",
+ )
+
+ api_kwargs: dict[str, Any] = {
+ "input": formatted,
+ "model": self.model,
+ "api_key": self.api_key,
+ **kwargs,
+ }
+
+ # Exclude api_key from cache identifier to avoid persisting secrets
+ # and to keep cache valid across key rotations.
+ cache_identifier = {
+ k: v for k, v in api_kwargs.items() if k != "api_key"
+ }
+
+ if self.embedding_cache:
+ cached = await self.embedding_cache.retrieve(
+ identifier=cache_identifier,
+ )
+ if cached:
+ return EmbeddingResponse(
+ embeddings=cached,
+ usage=EmbeddingUsage(tokens=0, time=0),
+ source="cache",
+ )
+
+ import dashscope
+
+ start_time = datetime.now()
+ res = dashscope.MultiModalEmbedding.call(**api_kwargs)
+ time = (datetime.now() - start_time).total_seconds()
+
+ if res.status_code != 200:
+ raise RuntimeError(
+ f"DashScope multimodal embedding API error: {res}",
+ )
+
+ embeddings = [entry["embedding"] for entry in res.output["embeddings"]]
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=cache_identifier,
+ embeddings=embeddings,
+ )
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(
+ tokens=res.usage.get("image_tokens", 0)
+ + res.usage.get("input_tokens", 0),
+ time=time,
+ ),
+ source="api",
+ )
+
+ # ------------------------------------------------------------------
+ # Helpers
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ def _format_data_block(block: DataBlock) -> dict[str, str]:
+ """Convert a :class:`~agentscope.message.DataBlock` to the dict
+ format expected by the DashScope multimodal embedding API.
+
+ The ``DataBlock.source.media_type`` determines whether the
+ block is treated as an image or video.
+
+ Args:
+ block (`DataBlock`):
+ A data block with a ``Base64Source`` or ``URLSource``.
+
+ Returns:
+ `dict[str, str]`: E.g.
+ ``{"image": "data:image/png;base64,..."}`` or
+ ``{"video": "https://..."}``.
+
+ Raises:
+ `ValueError`: If the media type is unsupported or a video
+ block uses a non-URL source.
+ """
+
+ source = block.source
+ media_type = source.media_type
+
+ if media_type.startswith("video/"):
+ if not isinstance(source, URLSource):
+ raise ValueError(
+ "Multimodal embedding API only supports URL input "
+ f"for video data, got {type(source).__name__}.",
+ )
+ return {"video": str(source.url)}
+
+ if media_type.startswith("image/"):
+ if isinstance(source, Base64Source):
+ return {
+ "image": f"data:{media_type};" f"base64,{source.data}",
+ }
+ if isinstance(source, URLSource):
+ return {"image": str(source.url)}
+
+ raise ValueError(
+ f"Unsupported media type {media_type!r} in DataBlock. "
+ f"Expected image/* or video/*.",
+ )
diff --git a/src/agentscope/embedding/_dashscope/_models/multimodal-embedding-v1.yaml b/src/agentscope/embedding/_dashscope/_models/multimodal-embedding-v1.yaml
new file mode 100644
index 000000000..b6fe26e47
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/multimodal-embedding-v1.yaml
@@ -0,0 +1,19 @@
+name: multimodal-embedding-v1
+label: Multimodal Embedding v1
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/bmp
+
+output_types:
+ - application/x-embedding
+
+context_size: 512
+
+parameter_overrides:
+ dimensions:
+ hidden: true
+ default: 1024
diff --git a/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml b/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml
new file mode 100644
index 000000000..7d6c88de8
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml
@@ -0,0 +1,22 @@
+name: qwen2.5-vl-embedding
+label: Qwen2.5 VL Embedding
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/webp
+ - image/bmp
+ - image/tiff
+ - video/mp4
+
+output_types:
+ - application/x-embedding
+
+context_size: 32000
+
+parameter_overrides:
+ dimensions:
+ default: 1024
+ enum: [2048, 1024, 768, 512]
diff --git a/src/agentscope/embedding/_dashscope/_models/qwen3-vl-embedding.yaml b/src/agentscope/embedding/_dashscope/_models/qwen3-vl-embedding.yaml
new file mode 100644
index 000000000..a2ed76053
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/qwen3-vl-embedding.yaml
@@ -0,0 +1,22 @@
+name: qwen3-vl-embedding
+label: Qwen3 VL Embedding
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/webp
+ - image/bmp
+ - image/tiff
+ - video/mp4
+
+output_types:
+ - application/x-embedding
+
+context_size: 32000
+
+parameter_overrides:
+ dimensions:
+ default: 2560
+ enum: [2560, 2048, 1536, 1024, 768, 512, 256]
diff --git a/src/agentscope/embedding/_dashscope/_models/text-embedding-v3.yaml b/src/agentscope/embedding/_dashscope/_models/text-embedding-v3.yaml
new file mode 100644
index 000000000..cc40c19c9
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/text-embedding-v3.yaml
@@ -0,0 +1,16 @@
+name: text-embedding-v3
+label: Text Embedding v3
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - application/x-embedding
+
+context_size: 8192
+
+parameter_overrides:
+ dimensions:
+ default: 1024
+ enum: [1024, 768, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope/_models/text-embedding-v4.yaml b/src/agentscope/embedding/_dashscope/_models/text-embedding-v4.yaml
new file mode 100644
index 000000000..f941108f9
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/text-embedding-v4.yaml
@@ -0,0 +1,16 @@
+name: text-embedding-v4
+label: Text Embedding v4
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - application/x-embedding
+
+context_size: 8192
+
+parameter_overrides:
+ dimensions:
+ default: 1024
+ enum: [2048, 1536, 1024, 768, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-flash.yaml b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-flash.yaml
new file mode 100644
index 000000000..0884e5f56
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-flash.yaml
@@ -0,0 +1,23 @@
+name: tongyi-embedding-vision-flash
+label: Tongyi Embedding Vision Flash
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/webp
+ - image/bmp
+ - image/tiff
+ - video/mp4
+ - video/mpeg
+
+output_types:
+ - application/x-embedding
+
+context_size: 1024
+
+parameter_overrides:
+ dimensions:
+ default: 768
+ enum: [768, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-plus.yaml b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-plus.yaml
new file mode 100644
index 000000000..06388a073
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope/_models/tongyi-embedding-vision-plus.yaml
@@ -0,0 +1,23 @@
+name: tongyi-embedding-vision-plus
+label: Tongyi Embedding Vision Plus
+status: active
+
+input_types:
+ - text/plain
+ - image/jpeg
+ - image/png
+ - image/webp
+ - image/bmp
+ - image/tiff
+ - video/mp4
+ - video/mpeg
+
+output_types:
+ - application/x-embedding
+
+context_size: 1024
+
+parameter_overrides:
+ dimensions:
+ default: 1152
+ enum: [1152, 1024, 512, 256, 128, 64]
diff --git a/src/agentscope/embedding/_dashscope_embedding.py b/src/agentscope/embedding/_dashscope_embedding.py
deleted file mode 100644
index d857663e2..000000000
--- a/src/agentscope/embedding/_dashscope_embedding.py
+++ /dev/null
@@ -1,169 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The dashscope embedding module in agentscope."""
-from datetime import datetime
-from typing import Any, List, Literal
-
-from ._cache_base import EmbeddingCacheBase
-from ._embedding_response import EmbeddingResponse
-from ._embedding_usage import EmbeddingUsage
-from ._embedding_base import EmbeddingModelBase
-from .._logging import logger
-from ..message import TextBlock
-
-
-class DashScopeTextEmbedding(EmbeddingModelBase):
- """DashScope text embedding API class.
-
- .. note:: From the `official documentation
- <https://bailian.console.aliyun.com/?tab=api#/api/?type=model&url=2712515>`_:
-
- - The max batch size that DashScope text embedding API
- supports is 10 for `text-embedding-v4` and `text-embedding-v3` models, and
- 25 for `text-embedding-v2` and `text-embedding-v1` models.
- - The max token limit for a single input is 8192 tokens for `v4` and `v3`
- models, and 2048 tokens for `v2` and `v1` models.
-
- """
-
- supported_modalities: list[str] = ["text"]
- """This class only supports text input."""
-
- def __init__(
- self,
- api_key: str,
- model_name: str,
- dimensions: int = 1024,
- embedding_cache: EmbeddingCacheBase | None = None,
- ) -> None:
- """Initialize the DashScope text embedding model class.
-
- Args:
- api_key (`str`):
- The dashscope API key.
- model_name (`str`):
- The name of the embedding model.
- dimensions (`int`, defaults to 1024):
- The dimension of the embedding vector, refer to the
- `official documentation
- <https://bailian.console.aliyun.com/?tab=api#/api/?type=model&url=2712515>`_
- for more details.
- embedding_cache (`EmbeddingCacheBase`):
- The embedding cache class instance, used to cache the
- embedding results to avoid repeated API calls.
- """
- super().__init__(model_name, dimensions)
-
- self.api_key = api_key
- self.embedding_cache = embedding_cache
- self.batch_size_limit = 10
-
- async def _call_api(self, kwargs: dict[str, Any]) -> EmbeddingResponse:
- """Call the DashScope embedding API by the given keyword arguments."""
-
- if self.embedding_cache:
- cached_embeddings = await self.embedding_cache.retrieve(
- identifier=kwargs,
- )
- if cached_embeddings:
- return EmbeddingResponse(
- embeddings=cached_embeddings,
- usage=EmbeddingUsage(
- tokens=0,
- time=0,
- ),
- source="cache",
- )
-
- import dashscope
-
- start_time = datetime.now()
- response = dashscope.embeddings.TextEmbedding.call(
- api_key=self.api_key,
- **kwargs,
- )
- time = (datetime.now() - start_time).total_seconds()
-
- if response.status_code != 200:
- raise RuntimeError(
- f"Failed to get embedding from DashScope API: {response}",
- )
-
- if self.embedding_cache:
- await self.embedding_cache.store(
- identifier=kwargs,
- embeddings=[
- _["embedding"] for _ in response.output["embeddings"]
- ],
- )
-
- return EmbeddingResponse(
- embeddings=[_["embedding"] for _ in response.output["embeddings"]],
- usage=EmbeddingUsage(
- tokens=response.usage["total_tokens"],
- time=time,
- ),
- )
-
- async def __call__(
- self,
- text: List[str | TextBlock],
- **kwargs: Any,
- ) -> EmbeddingResponse:
- """Call the DashScope embedding API.
-
- Args:
- text (`List[str | TextBlock]`):
- The input text to be embedded. It can be a list of strings.
- """
- gather_text = []
- for _ in text:
- if isinstance(_, dict) and "text" in _:
- gather_text.append(_["text"])
- elif isinstance(_, str):
- gather_text.append(_)
- else:
- raise ValueError(
- "Input text must be a list of strings or TextBlock dicts.",
- )
-
- if len(gather_text) > self.batch_size_limit:
- logger.info(
- "The input texts (%d) will be embedded with %d API calls due "
- f"to the batch size limit of {self.batch_size_limit} for "
- f"DashScope embedding API.",
- len(gather_text),
- (len(gather_text) + self.batch_size_limit - 1)
- // self.batch_size_limit,
- )
-
- # Handle the batch size limit for DashScope embedding API
- collected_embeddings = []
- collected_time = 0.0
- collected_tokens = 0
- collected_source: Literal["cache", "api"] = "cache"
- for _ in range(0, len(gather_text), self.batch_size_limit):
- batch_texts = gather_text[_ : _ + self.batch_size_limit]
- batch_kwargs = {
- "input": batch_texts,
- "model": self.model_name,
- "dimension": self.dimensions,
- **kwargs,
- }
-
- res = await self._call_api(batch_kwargs)
-
- collected_embeddings.extend(res.embeddings)
- collected_time += res.usage.time
- if res.usage.tokens:
- collected_tokens += res.usage.tokens
- if res.source == "api":
- collected_source = "api"
-
- return EmbeddingResponse(
- embeddings=collected_embeddings,
- usage=EmbeddingUsage(
- tokens=collected_tokens,
- time=collected_time,
- ),
- source=collected_source,
- )
diff --git a/src/agentscope/embedding/_dashscope_multimodal_embedding.py b/src/agentscope/embedding/_dashscope_multimodal_embedding.py
deleted file mode 100644
index e63bfc612..000000000
--- a/src/agentscope/embedding/_dashscope_multimodal_embedding.py
+++ /dev/null
@@ -1,243 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The dashscope multimodal embedding model in agentscope."""
-from datetime import datetime
-from typing import Any, Literal
-
-from ._cache_base import EmbeddingCacheBase
-from ._embedding_response import EmbeddingResponse
-from ._embedding_usage import EmbeddingUsage
-from ._embedding_base import EmbeddingModelBase
-from ..message import (
- DataBlock,
- TextBlock,
-)
-
-
-class DashScopeMultiModalEmbedding(EmbeddingModelBase):
- """The DashScope multimodal embedding API, supporting text, image and
- video embedding."""
-
- supported_modalities: list[str] = ["text", "image", "video"]
- """This class supports text, image and video input."""
-
- def __init__(
- self,
- api_key: str,
- model_name: str,
- dimensions: int | None = None,
- embedding_cache: EmbeddingCacheBase | None = None,
- ) -> None:
- """Initialize the DashScope multimodal embedding model class.
-
- Args:
- api_key (`str`):
- The dashscope API key.
- model_name (`str`):
- The name of the embedding model, e.g. "multimodal-embedding-
- v1", "tongyi-embedding-vision-plus".
- dimensions (`int`, defaults to 1024):
- The dimension of the embedding vector, refer to the
- `official documentation
- <https://bailian.console.aliyun.com/?tab=api#/api/?type=model&url=2712517>`_
- for more details.
- embedding_cache (`EmbeddingCacheBase`):
- The embedding cache class instance, used to cache the
- embedding results to avoid repeated API calls.
- """
- path_doc = (
- "https://bailian.console.aliyun.com/?tab=api#/api/?type=model&"
- "url=2712517"
- )
- self.batch_size_limit = 1
-
- if model_name.startswith("tongyi-embedding-vision-plus"):
- self.batch_size_limit = 8
- if dimensions is None:
- dimensions = 1152
- elif dimensions != 1152:
- raise ValueError(
- f"The dimension of model {model_name} must be 1152, "
- "refer to the official documentation for more details: "
- f"{path_doc}",
- )
- if model_name.startswith("tongyi-embedding-vision-flash"):
- self.batch_size_limit = 8
- if dimensions is None:
- dimensions = 768
- elif dimensions != 768:
- raise ValueError(
- f"The dimension of model {model_name} must be 768, "
- "refer to the official documentation for more details: "
- f"{path_doc}",
- )
- if model_name.startswith("multimodal-embedding-v"):
- if dimensions is None:
- dimensions = 1024
- elif dimensions != 1024:
- raise ValueError(
- f"The dimension of model {model_name} must be 1024, "
- "refer to the official documentation for more details: "
- f"{path_doc}",
- )
- refined_dimensions: int = 1024
- if dimensions is not None:
- refined_dimensions = dimensions
- super().__init__(model_name, refined_dimensions)
-
- self.api_key = api_key
- self.embedding_cache = embedding_cache
-
- async def __call__(
- self,
- inputs: list[TextBlock | DataBlock],
- **kwargs: Any,
- ) -> EmbeddingResponse:
- """Call the DashScope multimodal embedding API, which accepts text,
- image, and video data.
-
- Args:
- inputs (`list[TextBlock | DataBlock]`):
- The input data to be embedded. It can be a list of text,
- image, and video blocks.
-
- Returns:
- `EmbeddingResponse`:
- The embedding response object, which contains the embeddings
- and usage information.
- """
- # check data type
- formatted_data = []
- for _ in inputs:
- if (
- not isinstance(_, dict)
- or "type" not in _
- or _["type"]
- not in [
- "text",
- "image",
- "video",
- ]
- ):
- raise ValueError(
- f"Invalid data : {_}. It should be a list of "
- "TextBlock, ImageBlock, or VideoBlock.",
- )
- if (
- _["type"] == "video"
- and _.get("source", {}).get("type") != "url"
- ):
- raise ValueError(
- f"The multimodal embedding API only supports URL input "
- f"for video data, but got {_}.",
- )
-
- if _["type"] == "text":
- assert "text" in _, (
- f"Invalid text block: {_}. It should contain a "
- f"'text' field.",
- )
- formatted_data.append({"text": _["text"]})
-
- elif _["type"] == "video":
- formatted_data.append({"video": _["source"]["url"]})
-
- elif (
- _["type"] == "image"
- and "source" in _
- and _["source"].get("type") in ["base64", "url"]
- ):
- typ = _["source"]["type"]
- if typ == "base64":
- formatted_data.append(
- {
- "image": f'data:{_["source"]["media_type"]};'
- f'base64,{_["source"]["data"]}',
- },
- )
- elif typ == "url":
- formatted_data.append(
- {"image": _["source"]["url"]},
- )
- else:
- raise ValueError(
- f"Invalid block {_}. It should be a valid TextBlock, "
- f"ImageBlock, or VideoBlock.",
- )
-
- # Handle the batch size limit of the DashScope multimodal embedding API
- collected_embeddings = []
- collected_time = 0.0
- collected_tokens = 0
- collected_source: Literal["cache", "api"] = "cache"
- for _ in range(0, len(formatted_data), self.batch_size_limit):
- batch_data = formatted_data[_ : _ + self.batch_size_limit]
- batch_kwargs = {
- "input": batch_data,
- "model": self.model_name,
- **kwargs,
- }
- res = await self._call_api(batch_kwargs)
-
- collected_embeddings.extend(res.embeddings)
- collected_time += res.usage.time
- if res.usage.tokens:
- collected_tokens += res.usage.tokens
- if res.source == "api":
- collected_source = "api"
-
- return EmbeddingResponse(
- embeddings=collected_embeddings,
- usage=EmbeddingUsage(
- tokens=collected_tokens,
- time=collected_time,
- ),
- source=collected_source,
- )
-
- async def _call_api(self, kwargs: dict[str, Any]) -> EmbeddingResponse:
- """
- Call the DashScope multimodal embedding API by the given arguments.
- """
- # Search in cache first
- if self.embedding_cache:
- cached_embeddings = await self.embedding_cache.retrieve(
- identifier=kwargs,
- )
- if cached_embeddings:
- return EmbeddingResponse(
- embeddings=cached_embeddings,
- usage=EmbeddingUsage(
- tokens=0,
- time=0,
- ),
- source="cache",
- )
-
- import dashscope
-
- kwargs["api_key"] = self.api_key
-
- start_time = datetime.now()
- res = dashscope.MultiModalEmbedding.call(**kwargs)
- time = (datetime.now() - start_time).total_seconds()
-
- if res.status_code != 200:
- raise RuntimeError(
- f"Failed to get embedding from DashScope API: {res}",
- )
-
- return EmbeddingResponse(
- embeddings=[_["embedding"] for _ in res.output["embeddings"]],
- usage=EmbeddingUsage(
- tokens=res.usage.get(
- "image_tokens",
- 0,
- )
- + res.usage.get(
- "input_tokens",
- 0,
- ),
- time=time,
- ),
- source="api",
- )
diff --git a/src/agentscope/embedding/_embedding_base.py b/src/agentscope/embedding/_embedding_base.py
index 0ee31e0a8..747861e51 100644
--- a/src/agentscope/embedding/_embedding_base.py
+++ b/src/agentscope/embedding/_embedding_base.py
@@ -1,45 +1,374 @@
# -*- coding: utf-8 -*-
"""The embedding model base class."""
-from typing import Any
+from __future__ import annotations
+import asyncio
+import inspect
+from abc import abstractmethod
+from pathlib import Path
+from typing import Any, Generic, TypeVar, Type, Union
+
+from pydantic import BaseModel, Field
+
+from ._embedding_model_card import EmbeddingModelCard
from ._embedding_response import EmbeddingResponse
+from ._embedding_usage import EmbeddingUsage
+from .._logging import logger
+from ..credential import CredentialBase
+from ..message import DataBlock
+
+#: Type variable for embedding input elements.
+#:
+#: - Text-only models bind this to ``str``.
+#: - Multimodal models bind this to ``str | DataBlock``.
+#:
+#: The IDE resolves the concrete type from each subclass's
+#: ``class Foo(EmbeddingModelBase[str]): ...`` declaration, so
+#: callers get accurate completion and type-checking.
+InputT = TypeVar("InputT", str, Union[str, DataBlock])
+
+
+class EmbeddingModelBase(Generic[InputT]):
+ """Base class for embedding models.
+
+ Generic over :data:`InputT` so that text-only subclasses
+ (``EmbeddingModelBase[str]``) and multimodal subclasses
+ (``EmbeddingModelBase[str | DataBlock]``) expose the correct
+ ``inputs`` type to the IDE.
+
+ Follows the same pattern as :class:`~agentscope.model.ChatModelBase`:
+
+ - ``__call__`` splits inputs into batches of size
+ :attr:`batch_size`, calls :meth:`_call_api` for each batch
+ **concurrently** via :func:`asyncio.gather`, and merges the
+ results. Each batch call is wrapped with retry logic.
+ - Subclasses only implement :meth:`_call_api` for a **single
+ batch** — no batching or retry code needed.
+ - Each subclass may override :meth:`_get_retryable_exceptions` to
+ declare provider-specific retriable errors.
+ """
+
+ class Parameters(BaseModel):
+ """Base parameters for embedding models.
+ Contains ``dimensions`` — the single parameter that every
+ embedding model needs. Subclasses may extend this class to
+ add provider-specific parameters.
+ """
-class EmbeddingModelBase:
- """Base class for embedding models."""
+ dimensions: int = Field(
+ default=512,
+ title="Dimensions",
+ description="The output embedding vector dimensions.",
+ gt=0,
+ )
- model_name: str
- """The embedding model name"""
+ credential: CredentialBase
+ """The API credential."""
- supported_modalities: list[str]
- """The supported data modalities, e.g. "text", "image", "video"."""
+ model: str
+ """The embedding model name."""
dimensions: int
- """The dimensions of the embedding vector."""
+ """The dimensions of the embedding vector.
+
+ Shortcut for ``self.parameters.dimensions``, set during ``__init__``.
+ """
+
+ context_size: int
+ """Maximum input length (in tokens) per single input item."""
+
+ batch_size: int
+ """Maximum number of input items per API call."""
+
+ max_retries: int
+ """The maximum number of retries for the underlying API."""
+
+ retry_delay: float
+ """Seconds to sleep between retry attempts."""
def __init__(
self,
- model_name: str,
- dimensions: int,
+ credential: CredentialBase,
+ model: str,
+ parameters: BaseModel | None,
+ context_size: int,
+ batch_size: int,
+ max_retries: int,
+ retry_delay: float,
) -> None:
"""Initialize the embedding model base class.
Args:
- model_name (`str`):
+ credential (`CredentialBase`):
+ The API credential used for authentication.
+ model (`str`):
The name of the embedding model.
- dimensions (`int`):
- The dimension of the embedding vector.
+ parameters (`BaseModel | None`):
+ Provider-specific parameters (including ``dimensions``).
+ When ``None``, the default ``Parameters()`` is used.
+ context_size (`int`):
+ Maximum input length (in tokens) per single input item.
+ batch_size (`int`):
+ Maximum number of input items per API call. When
+ ``__call__`` receives more items, it splits them into
+ batches and calls :meth:`_call_api` concurrently.
+ max_retries (`int`):
+ The maximum number of retries for each batch API call.
+ Only exceptions listed in
+ :meth:`_get_retryable_exceptions` count against this
+ budget.
+ retry_delay (`float`):
+ Seconds to sleep between retry attempts.
+ """
+ self.credential = credential
+ self.model = model
+ self.parameters = parameters or self.Parameters()
+ self.dimensions = self.parameters.dimensions
+ self.context_size = context_size
+ self.batch_size = batch_size
+ self.max_retries = max_retries
+ self.retry_delay = retry_delay
+
+ @classmethod
+ def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+ """Return exception types that should trigger a retry.
+
+ Defaults to an empty tuple (no retries). Subclasses can
+ override to declare provider-specific retryable exceptions.
"""
- self.model_name = model_name
- self.dimensions = dimensions
+ return ()
+
+ # ------------------------------------------------------------------
+ # Public API — batching + concurrent retry
+ # ------------------------------------------------------------------
async def __call__(
self,
- *args: Any,
+ inputs: list[InputT],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Embed a list of inputs with automatic batching and retry.
+
+ The inputs are split into chunks of :attr:`batch_size`. All
+ chunks are dispatched **concurrently** via
+ :func:`asyncio.gather`. Each chunk is individually retried up
+ to ``max_retries`` times on retryable errors. Results are
+ merged into a single :class:`EmbeddingResponse` preserving the
+ original input order.
+
+ Args:
+ inputs (`list[InputT]`):
+ The input data to embed. For text-only models this is
+ ``list[str]``; for multimodal models it is
+ ``list[str | DataBlock]``.
+ **kwargs:
+ Additional keyword arguments forwarded to
+ :meth:`_call_api`.
+
+ Returns:
+ `EmbeddingResponse`:
+ A merged response containing embeddings for all inputs.
+ """
+ if not inputs:
+ return EmbeddingResponse(
+ embeddings=[],
+ usage=EmbeddingUsage(tokens=0, time=0),
+ )
+
+ # Split into batches.
+ batches = [
+ inputs[i : i + self.batch_size]
+ for i in range(0, len(inputs), self.batch_size)
+ ]
+
+ if len(batches) > 1:
+ logger.info(
+ "Embedding %d inputs in %d batches (batch_size=%d) "
+ "for model %s.",
+ len(inputs),
+ len(batches),
+ self.batch_size,
+ self.model,
+ )
+
+ # Dispatch all batches concurrently, each with retry.
+ results: list[EmbeddingResponse] = await asyncio.gather(
+ *(self._call_with_retry(batch, **kwargs) for batch in batches),
+ )
+
+ return self._merge_responses(results)
+
+ # ------------------------------------------------------------------
+ # Internal — merge multiple batch responses
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ def _merge_responses(
+ responses: list[EmbeddingResponse],
+ ) -> EmbeddingResponse:
+ """Merge multiple batch :class:`EmbeddingResponse` objects into
+ one, preserving input order.
+
+ Args:
+ responses (`list[EmbeddingResponse]`):
+ Batch responses to merge.
+
+ Returns:
+ `EmbeddingResponse`: The merged response.
+ """
+ if len(responses) == 1:
+ return responses[0]
+
+ all_embeddings: list = []
+ total_tokens = 0
+ total_time = 0.0
+
+ for resp in responses:
+ all_embeddings.extend(resp.embeddings)
+ if resp.usage:
+ total_time += resp.usage.time
+ if resp.usage.tokens:
+ total_tokens += resp.usage.tokens
+
+ return EmbeddingResponse(
+ embeddings=all_embeddings,
+ usage=EmbeddingUsage(
+ tokens=total_tokens,
+ time=total_time,
+ ),
+ source="api",
+ )
+
+ # ------------------------------------------------------------------
+ # Internal — retry wrapper for a single batch
+ # ------------------------------------------------------------------
+
+ async def _call_with_retry(
+ self,
+ inputs: list[InputT],
**kwargs: Any,
) -> EmbeddingResponse:
- """Call the embedding API with the given arguments."""
- raise NotImplementedError(
- f"The {self.__class__.__name__} class does not implement "
- f"the __call__ method.",
+ """Call :meth:`_call_api` with retry logic for a single batch.
+
+ Args:
+ inputs (`list[InputT]`):
+ A single batch of inputs (size ≤ ``batch_size``).
+ **kwargs:
+ Forwarded to :meth:`_call_api`.
+ """
+ retryable = tuple(self._get_retryable_exceptions())
+ last_error: Exception | None = None
+
+ for attempt in range(self.max_retries + 1):
+ try:
+ return await self._call_api(inputs, **kwargs)
+ except Exception as e:
+ if not isinstance(e, retryable):
+ raise
+ last_error = e
+ if attempt < self.max_retries:
+ logger.warning(
+ "Batch attempt %d failed for embedding model "
+ "%s: %s. Retrying in %.1fs...",
+ attempt + 1,
+ self.model,
+ str(e),
+ self.retry_delay,
+ )
+ await asyncio.sleep(self.retry_delay)
+ else:
+ logger.warning(
+ "All %d attempt(s) failed for a batch of "
+ "embedding model %s.",
+ self.max_retries + 1,
+ self.model,
+ )
+
+ if last_error is not None:
+ raise last_error
+ raise RuntimeError(
+ f"Failed to call embedding model {self.model} after "
+ f"{self.max_retries + 1} retries.",
)
+
+ # ------------------------------------------------------------------
+ # Abstract — subclasses implement this for a single batch
+ # ------------------------------------------------------------------
+
+ @abstractmethod
+ async def _call_api(
+ self,
+ inputs: list[InputT],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the underlying embedding API for a **single batch**.
+
+ Subclasses must implement this method. The batch splitting,
+ concurrency, and retry logic are handled by :meth:`__call__`
+ — this method only needs to handle one API call.
+
+ Args:
+ inputs (`list[InputT]`):
+ A batch of inputs (guaranteed ``len(inputs) <=
+ self.batch_size``).
+ **kwargs:
+ Additional keyword arguments.
+
+ Returns:
+ `EmbeddingResponse`:
+ The embedding response for this batch.
+ """
+
+ # ------------------------------------------------------------------
+ # Model card discovery
+ # ------------------------------------------------------------------
+
+ @classmethod
+ def list_models(
+ cls,
+ custom_yaml_dir: str | None = None,
+ ) -> list[EmbeddingModelCard]:
+ """List candidate embedding models from YAML files.
+
+ Each concrete subclass should live in its own provider
+ subdirectory (e.g. ``embedding/_openai/_model.py``) with a
+ sibling ``_models/`` directory containing YAML files — identical
+ to the layout used by :class:`~agentscope.model.ChatModelBase`.
+
+ Args:
+ custom_yaml_dir (`str | None`):
+ Override the YAML directory.
+
+ Returns:
+ `list[EmbeddingModelCard]`:
+ A list of embedding model cards.
+ """
+ if custom_yaml_dir is None:
+ subclass_file = Path(inspect.getfile(cls))
+ yaml_dir = subclass_file.parent / "_models"
+ else:
+ yaml_dir = Path(custom_yaml_dir)
+
+ if not yaml_dir.is_dir():
+ return []
+
+ yaml_files = list(yaml_dir.glob("*.yaml"))
+
+ model_cards = []
+ for yaml_file in yaml_files:
+ try:
+ card = EmbeddingModelCard.from_yaml(
+ yaml_path=str(yaml_file),
+ parameter_class=cls.Parameters,
+ )
+ model_cards.append(card)
+ except Exception as e:
+ logger.warning(
+ "Failed to load embedding model card %s: %s",
+ yaml_file,
+ str(e),
+ )
+ continue
+
+ return model_cards
diff --git a/src/agentscope/embedding/_embedding_model_card.py b/src/agentscope/embedding/_embedding_model_card.py
new file mode 100644
index 000000000..7e307bee9
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_model_card.py
@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""The embedding model card class."""
+from __future__ import annotations
+
+import copy
+from typing import Literal, Self, Type
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class EmbeddingModelCard(BaseModel):
+ """A card describing an embedding model's capabilities.
+
+ Mirrors :class:`~agentscope.model.ModelCard` but tailored for
+ embedding models. Uses ``input_types`` / ``output_types`` to
+ describe model capabilities, and ``parameter_schema`` (built from
+ the embedding class's ``Parameters`` + YAML ``parameter_overrides``)
+ to tell the frontend which knobs the user can adjust.
+
+ The output type ``application/x-embedding`` indicates that the
+ model produces dense vector embeddings.
+ """
+
+ type: Literal["embedding_model"] = "embedding_model"
+ """The card type, always ``"embedding_model"``."""
+
+ name: str = Field(description="The model name used in API calls.")
+ """The model name (e.g. ``"text-embedding-3-small"``)."""
+
+ label: str = Field(description="Human-readable label for the frontend.")
+ """Display label (e.g. ``"Text Embedding 3 Small"``)."""
+
+ status: Literal["active", "deprecated", "sunset"] = Field(
+ default="active",
+ description="The model lifecycle status.",
+ )
+ """The model status."""
+
+ input_types: list[str] = Field(
+ default=["text/plain"],
+ description="Supported input media types.",
+ )
+ """Supported input types (e.g. ``["text/plain"]``,
+ ``["text/plain", "image/jpeg", "image/png"]``)."""
+
+ output_types: list[str] = Field(
+ default=["application/x-embedding"],
+ description="Supported output media types.",
+ )
+ """Output types. ``application/x-embedding`` for vector output."""
+
+ context_size: int | None = Field(
+ default=None,
+ description="Maximum input length (in tokens) per request.",
+ gt=0,
+ )
+ """Maximum input context size, if known."""
+
+ parameter_schema: dict = Field(
+ default_factory=dict,
+ description=(
+ "JSON Schema for user-configurable parameters "
+ "(built from the Parameters class + YAML overrides)."
+ ),
+ )
+ """The parameter schema sent to the frontend for form rendering.
+ Empty ``properties`` means nothing to configure (e.g. fixed
+ dimensions)."""
+
+ parameter_overrides: dict[str, dict] = Field(
+ default_factory=dict,
+ description="Raw parameter overrides from the YAML file.",
+ )
+ """The raw parameter overrides, preserved for reference."""
+
+ @classmethod
+ def from_yaml(
+ cls,
+ yaml_path: str,
+ parameter_class: Type[BaseModel],
+ ) -> Self:
+ """Load an embedding model card from a YAML file.
+
+ Merges the base ``parameter_class`` JSON Schema with
+ ``parameter_overrides`` from the YAML — identical to the
+ approach used by :meth:`~agentscope.model.ModelCard.from_yaml`.
+
+ Args:
+ yaml_path (`str`):
+ Path to the YAML file.
+ parameter_class (`Type[BaseModel]`):
+ The ``Parameters`` class from the embedding model subclass.
+
+ Returns:
+ `EmbeddingModelCard`: The loaded model card.
+ """
+ with open(yaml_path, "r", encoding="utf-8") as f:
+ config = yaml.safe_load(f)
+
+ # Build parameter schema from the Parameters class
+ base_schema = parameter_class.model_json_schema()
+ properties = copy.deepcopy(base_schema.get("properties", {}))
+
+ # Apply parameter_overrides (same logic as ModelCard.from_yaml)
+ overrides = config.get("parameter_overrides", {})
+ for param_name, override in overrides.items():
+ if override is None:
+ # null means remove
+ properties.pop(param_name, None)
+ continue
+
+ if isinstance(override, dict):
+ if override.get("hidden"):
+ properties.pop(param_name, None)
+ continue
+
+ # Simple dict merge
+ if param_name in properties:
+ properties[param_name] = {
+ **properties[param_name],
+ **override,
+ }
+
+ final_schema = {
+ "type": "object",
+ "properties": properties,
+ "required": base_schema.get("required", []),
+ }
+
+ return cls(
+ name=config["name"],
+ label=config["label"],
+ status=config.get("status", "active"),
+ input_types=config.get("input_types", ["text/plain"]),
+ output_types=config.get(
+ "output_types",
+ ["application/x-embedding"],
+ ),
+ context_size=config.get("context_size"),
+ parameter_schema=final_schema,
+ parameter_overrides=overrides,
+ )
diff --git a/src/agentscope/embedding/_gemini/__init__.py b/src/agentscope/embedding/_gemini/__init__.py
new file mode 100644
index 000000000..e0cf50bf7
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The Gemini embedding API modules."""
+
+from ._model import GeminiEmbeddingModel
+
+__all__ = [
+ "GeminiEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_gemini/_model.py b/src/agentscope/embedding/_gemini/_model.py
new file mode 100644
index 000000000..7827dc32a
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/_model.py
@@ -0,0 +1,463 @@
+# -*- coding: utf-8 -*-
+"""The Google Gemini embedding model.
+
+Handles both text-only and multimodal models under a single class.
+``gemini-embedding-001`` accepts ``list[str]`` only.
+``gemini-embedding-2`` additionally accepts
+:class:`~agentscope.message.DataBlock` (images, video, audio, PDF).
+The model name determines the API call style.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._embedding_base import EmbeddingModelBase
+from ..._logging import logger
+from ...credential import CredentialBase
+from ...message import DataBlock
+
+#: Model name prefixes that use the multimodal API path.
+_MULTIMODAL_PREFIXES = ("gemini-embedding-2",)
+
+
+@dataclass
+class _MultimodalLimits:
+ """Per-request constraints for Gemini multimodal embedding."""
+
+ max_elements: int = 20
+ """Maximum total content elements per API call."""
+
+ max_images: int = 6
+ """Maximum image elements per API call."""
+
+ max_videos: int = 1
+ """Maximum video elements per API call."""
+
+ max_audios: int = 1
+ """Maximum audio elements per API call."""
+
+ max_pdfs: int = 1
+ """Maximum PDF documents per API call."""
+
+
+_MODEL_LIMITS: dict[str, _MultimodalLimits] = {
+ "gemini-embedding-2": _MultimodalLimits(
+ max_elements=20,
+ max_images=6,
+ max_videos=1,
+ max_audios=1,
+ max_pdfs=1,
+ ),
+}
+
+_DEFAULT_LIMITS = _MultimodalLimits()
+
+
+class GeminiEmbeddingModel(EmbeddingModelBase[str | DataBlock]):
+ """Unified Google Gemini embedding model.
+
+ Routes to the text-only or multimodal Gemini API based on the
+ model name.
+
+ - **Text mode** (``gemini-embedding-001``): uses the base class's
+ simple batch splitting + concurrent retry. The Gemini API
+ accepts a list of strings and returns individual embeddings.
+ - **Multimodal mode** (``gemini-embedding-2``): overrides
+ ``__call__`` with content-aware batching (respecting per-model
+ limits on images, videos, audios, PDFs). Each input is wrapped
+ in a ``Content`` object so the API returns separate embeddings.
+
+ Key API differences from other providers:
+
+ - Dimensions are controlled via ``output_dimensionality`` in the
+ ``config`` parameter (not a top-level ``dimensions`` field).
+ - ``gemini-embedding-001`` supports ``task_type`` in config;
+ ``gemini-embedding-2`` uses prompt prefixes instead.
+ """
+
+ #: Text-mode batch size. Gemini docs don't specify an explicit
+ #: limit; we use a conservative default.
+ _TEXT_BATCH_SIZE: int = 100
+
+ def __init__(
+ self,
+ credential: CredentialBase,
+ model: str,
+ parameters: "GeminiEmbeddingModel.Parameters | None" = None,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ context_size: int = 8192,
+ max_retries: int = 3,
+ retry_delay: float = 1.0,
+ ) -> None:
+ """Initialize the Gemini embedding model.
+
+ Args:
+ credential (`CredentialBase`):
+ A :class:`~agentscope.credential.GeminiCredential`
+ instance providing the API key.
+ model (`str`):
+ The embedding model name (e.g.
+ ``"gemini-embedding-001"`` or
+ ``"gemini-embedding-2"``).
+ parameters (`GeminiEmbeddingModel.Parameters | None`, \
+ defaults to ``None``):
+ User-configurable parameters (currently only
+ ``dimensions``).
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+ ``None``):
+ Optional embedding cache.
+ context_size (`int`, defaults to ``8192``):
+ Maximum input tokens. 2048 for ``gemini-embedding-001``,
+ 8192 for ``gemini-embedding-2``.
+ max_retries (`int`, defaults to ``3``):
+ Number of retries on transient failures.
+ retry_delay (`float`, defaults to ``1.0``):
+ Seconds between retry attempts.
+ """
+ from google import genai
+
+ self._is_multimodal: bool = model.startswith(_MULTIMODAL_PREFIXES)
+
+ super().__init__(
+ credential=credential,
+ model=model,
+ parameters=parameters,
+ context_size=context_size,
+ batch_size=self._TEXT_BATCH_SIZE,
+ max_retries=max_retries,
+ retry_delay=retry_delay,
+ )
+
+ self.client: genai.Client = genai.Client(
+ api_key=credential.api_key.get_secret_value(),
+ )
+ self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+ if self._is_multimodal:
+ self._limits = _MODEL_LIMITS.get(model, _DEFAULT_LIMITS)
+
+ # ------------------------------------------------------------------
+ # __call__ — override for multimodal content-aware batching
+ # ------------------------------------------------------------------
+
+ async def __call__(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Embed inputs with batching and retry.
+
+ For text models, delegates to the base class. For multimodal
+ models, performs content-aware batching that respects per-model
+ limits on images, videos, audios, and PDFs.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ The input data to embed.
+ **kwargs:
+ Forwarded to the Gemini API config.
+
+ Returns:
+ `EmbeddingResponse`: Merged response for all inputs.
+ """
+ if not self._is_multimodal:
+ return await super().__call__(inputs, **kwargs)
+
+ batches = self._split_multimodal_batches(inputs)
+
+ if len(batches) > 1:
+ logger.info(
+ "Embedding %d multimodal inputs in %d batches "
+ "for model %s.",
+ len(inputs),
+ len(batches),
+ self.model,
+ )
+
+ results: list[EmbeddingResponse] = await asyncio.gather(
+ *(self._call_with_retry(batch, **kwargs) for batch in batches),
+ )
+
+ return self._merge_responses(results)
+
+ def _split_multimodal_batches(
+ self,
+ inputs: list[str | DataBlock],
+ ) -> list[list[str | DataBlock]]:
+ """Split inputs into batches respecting Gemini multimodal limits.
+
+ Greedy: keep adding items until any constraint would be
+ violated, then start a new batch.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ All inputs to split.
+
+ Returns:
+ `list[list[str | DataBlock]]`: List of batches.
+ """
+ limits = self._limits
+ batches: list[list[str | DataBlock]] = []
+ current: list[str | DataBlock] = []
+ n_elem = 0
+ n_img = 0
+ n_vid = 0
+ n_aud = 0
+ n_pdf = 0
+
+ for item in inputs:
+ is_img = is_vid = is_aud = is_pdf = False
+ if isinstance(item, DataBlock):
+ mt = item.source.media_type
+ is_img = mt.startswith("image/")
+ is_vid = mt.startswith("video/")
+ is_aud = mt.startswith("audio/")
+ is_pdf = mt == "application/pdf"
+
+ would_exceed = (
+ n_elem + 1 > limits.max_elements
+ or (is_img and n_img + 1 > limits.max_images)
+ or (is_vid and n_vid + 1 > limits.max_videos)
+ or (is_aud and n_aud + 1 > limits.max_audios)
+ or (is_pdf and n_pdf + 1 > limits.max_pdfs)
+ )
+
+ if would_exceed and current:
+ batches.append(current)
+ current = []
+ n_elem = n_img = n_vid = n_aud = n_pdf = 0
+
+ current.append(item)
+ n_elem += 1
+ n_img += is_img
+ n_vid += is_vid
+ n_aud += is_aud
+ n_pdf += is_pdf
+
+ if current:
+ batches.append(current)
+
+ return batches
+
+ # ------------------------------------------------------------------
+ # _call_api — single batch
+ # ------------------------------------------------------------------
+
+ async def _call_api(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Route to text or multimodal Gemini API for a single batch.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ A single batch of inputs.
+ **kwargs:
+ Extra keyword arguments merged into the Gemini
+ ``EmbedContentConfig``.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ if self._is_multimodal:
+ return await self._call_multimodal(inputs, **kwargs)
+ return await self._call_text(inputs, **kwargs)
+
+ # ------------------------------------------------------------------
+ # Text API (gemini-embedding-001)
+ # ------------------------------------------------------------------
+
+ async def _call_text(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the Gemini text embedding API for a single batch.
+
+ Passes the list of strings directly to ``embed_content``,
+ which returns one embedding per string.
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ Must all be ``str``; raises ``ValueError`` otherwise.
+ **kwargs:
+ Merged into ``EmbedContentConfig`` (e.g.
+ ``task_type``).
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ from google.genai import types
+
+ texts: list[str] = []
+ for item in inputs:
+ if not isinstance(item, str):
+ raise ValueError(
+ f"Text embedding model {self.model!r} only accepts "
+ f"str inputs, got {type(item).__name__}.",
+ )
+ texts.append(item)
+
+ config = types.EmbedContentConfig(
+ output_dimensionality=self.dimensions,
+ **kwargs,
+ )
+
+ cache_key = {
+ "model": self.model,
+ "contents": texts,
+ "output_dimensionality": self.dimensions,
+ **kwargs,
+ }
+
+ if self.embedding_cache:
+ cached = await self.embedding_cache.retrieve(
+ identifier=cache_key,
+ )
+ if cached:
+ return EmbeddingResponse(
+ embeddings=cached,
+ usage=EmbeddingUsage(tokens=0, time=0),
+ source="cache",
+ )
+
+ start_time = datetime.now()
+ response = self.client.models.embed_content(
+ model=self.model,
+ contents=texts,
+ config=config,
+ )
+ time = (datetime.now() - start_time).total_seconds()
+
+ embeddings = [item.values for item in response.embeddings]
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=cache_key,
+ embeddings=embeddings,
+ )
+
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(time=time),
+ )
+
+ # ------------------------------------------------------------------
+ # Multimodal API (gemini-embedding-2)
+ # ------------------------------------------------------------------
+
+ async def _call_multimodal(
+ self,
+ inputs: list[str | DataBlock],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the Gemini multimodal embedding API for a single batch.
+
+ Each input is wrapped in a separate ``Content`` object so the
+ API returns one embedding per input (not one aggregated
+ embedding).
+
+ Args:
+ inputs (`list[str | DataBlock]`):
+ ``str`` for text, ``DataBlock`` for images / video /
+ audio / PDF.
+ **kwargs:
+ Merged into ``EmbedContentConfig``.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ from google.genai import types
+
+ contents: list[types.Content] = []
+ for item in inputs:
+ if isinstance(item, str):
+ contents.append(
+ types.Content(
+ parts=[types.Part.from_text(text=item)],
+ ),
+ )
+ elif isinstance(item, DataBlock):
+ contents.append(
+ types.Content(
+ parts=[self._data_block_to_part(item)],
+ ),
+ )
+ else:
+ raise ValueError(
+ f"Invalid input: {item!r}. Expected str or DataBlock.",
+ )
+
+ config = types.EmbedContentConfig(
+ output_dimensionality=self.dimensions,
+ **kwargs,
+ )
+
+ start_time = datetime.now()
+ response = self.client.models.embed_content(
+ model=self.model,
+ contents=contents,
+ config=config,
+ )
+ time = (datetime.now() - start_time).total_seconds()
+
+ embeddings = [item.values for item in response.embeddings]
+
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(time=time),
+ )
+
+ # ------------------------------------------------------------------
+ # Helpers
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ def _data_block_to_part(block: DataBlock) -> Any:
+ """Convert a :class:`~agentscope.message.DataBlock` to a Gemini
+ ``Part`` object.
+
+ Args:
+ block (`DataBlock`):
+ A data block with ``Base64Source`` or ``URLSource``.
+
+ Returns:
+ A ``google.genai.types.Part`` instance.
+
+ Raises:
+ `ValueError`: If the source type is unsupported.
+ """
+ from google.genai import types
+ from ...message import Base64Source, URLSource
+
+ source = block.source
+
+ if isinstance(source, Base64Source):
+ import base64
+
+ return types.Part.from_bytes(
+ data=base64.b64decode(source.data),
+ mime_type=source.media_type,
+ )
+
+ if isinstance(source, URLSource):
+ # Gemini SDK doesn't have a direct from_url for
+ # embed_content; download or use File API.
+ # For now, raise — callers should use Base64Source.
+ raise ValueError(
+ "Gemini embedding API requires inline data "
+ "(Base64Source). URLSource is not directly supported "
+ f"for embedding. Got URL: {source.url}",
+ )
+
+ raise ValueError(
+ f"Unsupported source type {type(source).__name__} "
+ f"in DataBlock.",
+ )
diff --git a/src/agentscope/embedding/_gemini/_models/gemini-embedding-001.yaml b/src/agentscope/embedding/_gemini/_models/gemini-embedding-001.yaml
new file mode 100644
index 000000000..40c44e35f
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/_models/gemini-embedding-001.yaml
@@ -0,0 +1,16 @@
+name: gemini-embedding-001
+label: Gemini Embedding 001
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - application/x-embedding
+
+context_size: 2048
+
+parameter_overrides:
+ dimensions:
+ default: 3072
+ enum: [3072, 1536, 768, 512, 256, 128]
diff --git a/src/agentscope/embedding/_gemini/_models/gemini-embedding-2.yaml b/src/agentscope/embedding/_gemini/_models/gemini-embedding-2.yaml
new file mode 100644
index 000000000..47d874e29
--- /dev/null
+++ b/src/agentscope/embedding/_gemini/_models/gemini-embedding-2.yaml
@@ -0,0 +1,22 @@
+name: gemini-embedding-2
+label: Gemini Embedding 2
+status: active
+
+input_types:
+ - text/plain
+ - image/png
+ - image/jpeg
+ - video/mp4
+ - audio/mpeg
+ - audio/wav
+ - application/pdf
+
+output_types:
+ - application/x-embedding
+
+context_size: 8192
+
+parameter_overrides:
+ dimensions:
+ default: 3072
+ enum: [3072, 1536, 768]
diff --git a/src/agentscope/embedding/_gemini_embedding.py b/src/agentscope/embedding/_gemini_embedding.py
deleted file mode 100644
index 8f0c06898..000000000
--- a/src/agentscope/embedding/_gemini_embedding.py
+++ /dev/null
@@ -1,109 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The gemini text embedding model class."""
-from datetime import datetime
-from typing import Any, List
-
-from ._embedding_response import EmbeddingResponse
-from ._embedding_usage import EmbeddingUsage
-from ._cache_base import EmbeddingCacheBase
-from ._embedding_base import EmbeddingModelBase
-from ..message import TextBlock
-
-
-class GeminiTextEmbedding(EmbeddingModelBase):
- """The Gemini text embedding model."""
-
- supported_modalities: list[str] = ["text"]
- """This class only supports text input."""
-
- def __init__(
- self,
- api_key: str,
- model_name: str,
- dimensions: int = 3072,
- embedding_cache: EmbeddingCacheBase | None = None,
- **kwargs: Any,
- ) -> None:
- """Initialize the Gemini text embedding model class.
-
- Args:
- api_key (`str`):
- The Gemini API key.
- model_name (`str`):
- The name of the embedding model.
- dimensions (`int`, defaults to 3072):
- The dimension of the embedding vector, refer to the
- `official documentation
- <https://ai.google.dev/gemini-api/docs/embeddings?hl=zh-cn#control-embedding-size>`_
- for more details.
- embedding_cache (`EmbeddingCacheBase | None`, defaults to `None`):
- The embedding cache class instance, used to cache the
- embedding results to avoid repeated API calls.
- """
- from google import genai
-
- super().__init__(model_name, dimensions)
-
- self.client = genai.Client(api_key=api_key, **kwargs)
- self.embedding_cache = embedding_cache
-
- async def __call__(
- self,
- text: List[str | TextBlock],
- **kwargs: Any,
- ) -> EmbeddingResponse:
- """The Gemini embedding API call.
-
- Args:
- text (`List[str | TextBlock]`):
- The input text to be embedded. It can be a list of strings.
-
- # TODO: handle the batch size limit
- """
- gather_text = []
- for _ in text:
- if isinstance(_, dict) and "text" in _:
- gather_text.append(_["text"])
- elif isinstance(_, str):
- gather_text.append(_)
- else:
- raise ValueError(
- "Input text must be a list of strings or TextBlock dicts.",
- )
-
- kwargs = {
- "model": self.model_name,
- "contents": gather_text,
- "config": kwargs,
- }
-
- if self.embedding_cache:
- cached_embeddings = await self.embedding_cache.retrieve(
- identifier=kwargs,
- )
- if cached_embeddings:
- return EmbeddingResponse(
- embeddings=cached_embeddings,
- usage=EmbeddingUsage(
- tokens=0,
- time=0,
- ),
- source="cache",
- )
-
- start_time = datetime.now()
- response = self.client.models.embed_content(**kwargs)
- time = (datetime.now() - start_time).total_seconds()
-
- if self.embedding_cache:
- await self.embedding_cache.store(
- identifier=kwargs,
- embeddings=[_.values for _ in response.embeddings],
- )
-
- return EmbeddingResponse(
- embeddings=[_.values for _ in response.embeddings],
- usage=EmbeddingUsage(
- time=time,
- ),
- )
diff --git a/src/agentscope/embedding/_ollama/__init__.py b/src/agentscope/embedding/_ollama/__init__.py
new file mode 100644
index 000000000..efd4c8d22
--- /dev/null
+++ b/src/agentscope/embedding/_ollama/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The Ollama embedding API modules."""
+
+from ._model import OllamaEmbeddingModel
+
+__all__ = [
+ "OllamaEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_ollama/_model.py b/src/agentscope/embedding/_ollama/_model.py
new file mode 100644
index 000000000..5fce28803
--- /dev/null
+++ b/src/agentscope/embedding/_ollama/_model.py
@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""The Ollama embedding model."""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_base import EmbeddingModelBase
+from ...credential import CredentialBase
+
+
+class OllamaEmbeddingModel(EmbeddingModelBase[str]):
+ """Ollama text embedding model.
+
+ Wraps locally-hosted embedding models served by Ollama (e.g.
+ ``nomic-embed-text``, ``mxbai-embed-large``). Inherits batching
+ and retry logic from :class:`EmbeddingModelBase`.
+ """
+
+ _TEXT_BATCH_SIZE: int = 512
+
+ def __init__(
+ self,
+ credential: CredentialBase,
+ model: str,
+ parameters: "OllamaEmbeddingModel.Parameters | None" = None,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ context_size: int = 8192,
+ max_retries: int = 3,
+ retry_delay: float = 1.0,
+ ) -> None:
+ """Initialize the Ollama embedding model.
+
+ Args:
+ credential (`CredentialBase`):
+ An :class:`~agentscope.credential.OllamaCredential`
+ instance providing the host URL.
+ model (`str`):
+ The embedding model name (e.g.
+ ``"nomic-embed-text"``).
+ parameters (`OllamaEmbeddingModel.Parameters | None`, \
+ defaults to ``None``):
+ User-configurable parameters (currently only
+ ``dimensions``).
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+ ``None``):
+ Optional embedding cache.
+ context_size (`int`, defaults to ``8192``):
+ Maximum input tokens per text.
+ max_retries (`int`, defaults to ``3``):
+ Number of retries on transient failures.
+ retry_delay (`float`, defaults to ``1.0``):
+ Seconds between retry attempts.
+ """
+ super().__init__(
+ credential=credential,
+ model=model,
+ parameters=parameters,
+ context_size=context_size,
+ batch_size=self._TEXT_BATCH_SIZE,
+ max_retries=max_retries,
+ retry_delay=retry_delay,
+ )
+ self.host: str | None = getattr(credential, "host", None)
+ self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+ async def _call_api(
+ self,
+ inputs: list[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the Ollama embedding API for a single batch.
+
+ Args:
+ inputs (`list[str]`):
+ A batch of texts to embed.
+ **kwargs:
+ Extra keyword arguments forwarded to the Ollama API.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ api_kwargs: dict[str, Any] = {
+ "input": inputs,
+ "model": self.model,
+ "dimensions": self.dimensions,
+ **kwargs,
+ }
+
+ if self.embedding_cache:
+ cached = await self.embedding_cache.retrieve(
+ identifier=api_kwargs,
+ )
+ if cached:
+ return EmbeddingResponse(
+ embeddings=cached,
+ usage=EmbeddingUsage(tokens=0, time=0),
+ source="cache",
+ )
+
+ import ollama
+
+ client = ollama.AsyncClient(host=self.host)
+
+ start_time = datetime.now()
+ response = await client.embed(**api_kwargs)
+ time = (datetime.now() - start_time).total_seconds()
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=api_kwargs,
+ embeddings=response.embeddings,
+ )
+
+ return EmbeddingResponse(
+ embeddings=response.embeddings,
+ usage=EmbeddingUsage(time=time),
+ )
diff --git a/src/agentscope/embedding/_ollama_embedding.py b/src/agentscope/embedding/_ollama_embedding.py
deleted file mode 100644
index fbc080185..000000000
--- a/src/agentscope/embedding/_ollama_embedding.py
+++ /dev/null
@@ -1,112 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The ollama text embedding model class."""
-from datetime import datetime
-from typing import List, Any
-
-from ._embedding_response import EmbeddingResponse
-from ._embedding_usage import EmbeddingUsage
-from ._cache_base import EmbeddingCacheBase
-from ..embedding import EmbeddingModelBase
-from ..message import TextBlock
-
-
-class OllamaTextEmbedding(EmbeddingModelBase):
- """The Ollama embedding model."""
-
- supported_modalities: list[str] = ["text"]
- """This class only supports text input."""
-
- def __init__(
- self,
- model_name: str,
- dimensions: int,
- host: str | None = None,
- embedding_cache: EmbeddingCacheBase | None = None,
- **kwargs: Any,
- ) -> None:
- """Initialize the Ollama text embedding model class.
-
- Args:
- model_name (`str`):
- The name of the embedding model.
- dimensions (`int`):
- The dimension of the embedding vector, the parameter should be
- provided according to the model used.
- host (`str | None`, defaults to `None`):
- The host URL for the Ollama API.
- embedding_cache (`EmbeddingCacheBase | None`, defaults to `None`):
- The embedding cache class instance, used to cache the
- embedding results to avoid repeated API calls.
- """
- super().__init__(model_name, dimensions)
-
- self.host = host
- self.client_kwargs = kwargs
- self.embedding_cache = embedding_cache
-
- async def __call__(
- self,
- text: List[str | TextBlock],
- **kwargs: Any,
- ) -> EmbeddingResponse:
- """Call the Ollama embedding API.
-
- Args:
- text (`List[str | TextBlock]`):
- The input text to be embedded. It can be a list of strings.
- """
- gather_text = []
- for _ in text:
- if isinstance(_, dict) and "text" in _:
- gather_text.append(_["text"])
- elif isinstance(_, str):
- gather_text.append(_)
- else:
- raise ValueError(
- "Input text must be a list of strings or TextBlock dicts.",
- )
-
- kwargs = {
- "input": gather_text,
- "model": self.model_name,
- "dimensions": self.dimensions,
- **kwargs,
- }
-
- if self.embedding_cache:
- cached_embeddings = await self.embedding_cache.retrieve(
- identifier=kwargs,
- )
- if cached_embeddings:
- return EmbeddingResponse(
- embeddings=cached_embeddings,
- usage=EmbeddingUsage(
- tokens=0,
- time=0,
- ),
- source="cache",
- )
-
- import ollama
-
- client = ollama.AsyncClient(
- host=self.host,
- **self.client_kwargs,
- )
-
- start_time = datetime.now()
- response = await client.embed(**kwargs)
- time = (datetime.now() - start_time).total_seconds()
-
- if self.embedding_cache:
- await self.embedding_cache.store(
- identifier=kwargs,
- embeddings=response.embeddings,
- )
-
- return EmbeddingResponse(
- embeddings=response.embeddings,
- usage=EmbeddingUsage(
- time=time,
- ),
- )
diff --git a/src/agentscope/embedding/_openai/__init__.py b/src/agentscope/embedding/_openai/__init__.py
new file mode 100644
index 000000000..0a460ba4f
--- /dev/null
+++ b/src/agentscope/embedding/_openai/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI embedding API modules."""
+
+from ._model import OpenAIEmbeddingModel
+
+__all__ = [
+ "OpenAIEmbeddingModel",
+]
diff --git a/src/agentscope/embedding/_openai/_model.py b/src/agentscope/embedding/_openai/_model.py
new file mode 100644
index 000000000..10fb61566
--- /dev/null
+++ b/src/agentscope/embedding/_openai/_model.py
@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI embedding model."""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Type
+
+from .._embedding_response import EmbeddingResponse
+from .._embedding_usage import EmbeddingUsage
+from .._cache_base import EmbeddingCacheBase
+from .._embedding_base import EmbeddingModelBase
+from ...credential import CredentialBase
+
+
+class OpenAIEmbeddingModel(EmbeddingModelBase[str]):
+ """OpenAI text embedding model.
+
+ Supports ``text-embedding-3-small``, ``text-embedding-3-large``,
+ and other OpenAI-compatible embedding models. Inherits batching
+ and retry logic from :class:`EmbeddingModelBase`.
+ """
+
+ #: OpenAI does not document an explicit per-request item limit;
+ #: the constraint is on total tokens. We use a conservative
+ #: default that works well in practice.
+ _TEXT_BATCH_SIZE: int = 2048
+
+ def __init__(
+ self,
+ credential: CredentialBase,
+ model: str,
+ parameters: "OpenAIEmbeddingModel.Parameters | None" = None,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ context_size: int = 8191,
+ max_retries: int = 3,
+ retry_delay: float = 1.0,
+ ) -> None:
+ """Initialize the OpenAI embedding model.
+
+ Args:
+ credential (`CredentialBase`):
+ An :class:`~agentscope.credential.OpenAICredential`
+ instance providing the API key and optional base URL /
+ organization.
+ model (`str`):
+ The embedding model name (e.g.
+ ``"text-embedding-3-small"``).
+ parameters (`OpenAIEmbeddingModel.Parameters | None`, \
+ defaults to ``None``):
+ User-configurable parameters (currently only
+ ``dimensions``).
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to \
+ ``None``):
+ Optional embedding cache.
+ context_size (`int`, defaults to ``8191``):
+ Maximum input tokens per text.
+ max_retries (`int`, defaults to ``3``):
+ Number of retries on transient failures.
+ retry_delay (`float`, defaults to ``1.0``):
+ Seconds between retry attempts.
+ """
+ import openai
+
+ super().__init__(
+ credential=credential,
+ model=model,
+ parameters=parameters,
+ context_size=context_size,
+ batch_size=self._TEXT_BATCH_SIZE,
+ max_retries=max_retries,
+ retry_delay=retry_delay,
+ )
+
+ client_kwargs: dict[str, Any] = {}
+ if getattr(credential, "base_url", None) is not None:
+ client_kwargs["base_url"] = credential.base_url
+ if getattr(credential, "organization", None) is not None:
+ client_kwargs["organization"] = credential.organization
+
+ self.client: openai.AsyncClient = openai.AsyncClient(
+ api_key=credential.api_key.get_secret_value(),
+ **client_kwargs,
+ )
+ self.embedding_cache: EmbeddingCacheBase | None = embedding_cache
+
+ @classmethod
+ def _get_retryable_exceptions(cls) -> tuple[Type[Exception], ...]:
+ """Return OpenAI exceptions that warrant a retry."""
+ import openai
+
+ return (
+ openai.APIConnectionError,
+ openai.APITimeoutError,
+ openai.RateLimitError,
+ openai.InternalServerError,
+ )
+
+ async def _call_api(
+ self,
+ inputs: list[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the OpenAI embedding API for a single batch.
+
+ Args:
+ inputs (`list[str]`):
+ A batch of texts to embed.
+ **kwargs:
+ Extra keyword arguments forwarded to the OpenAI API.
+
+ Returns:
+ `EmbeddingResponse`: Embedding vectors and usage info.
+ """
+ api_kwargs: dict[str, Any] = {
+ "input": inputs,
+ "model": self.model,
+ "dimensions": self.dimensions,
+ "encoding_format": "float",
+ **kwargs,
+ }
+
+ if self.embedding_cache:
+ cached = await self.embedding_cache.retrieve(
+ identifier=api_kwargs,
+ )
+ if cached:
+ return EmbeddingResponse(
+ embeddings=cached,
+ usage=EmbeddingUsage(tokens=0, time=0),
+ source="cache",
+ )
+
+ start_time = datetime.now()
+ response = await self.client.embeddings.create(**api_kwargs)
+ time = (datetime.now() - start_time).total_seconds()
+
+ embeddings = [item.embedding for item in response.data]
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=api_kwargs,
+ embeddings=embeddings,
+ )
+
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(
+ tokens=response.usage.total_tokens,
+ time=time,
+ ),
+ )
diff --git a/src/agentscope/embedding/_openai/_models/text-embedding-3-large.yaml b/src/agentscope/embedding/_openai/_models/text-embedding-3-large.yaml
new file mode 100644
index 000000000..448e019e6
--- /dev/null
+++ b/src/agentscope/embedding/_openai/_models/text-embedding-3-large.yaml
@@ -0,0 +1,16 @@
+name: text-embedding-3-large
+label: Text Embedding 3 Large
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - application/x-embedding
+
+context_size: 8191
+
+parameter_overrides:
+ dimensions:
+ default: 3072
+ enum: [3072, 1536, 1024, 768, 512, 256]
diff --git a/src/agentscope/embedding/_openai/_models/text-embedding-3-small.yaml b/src/agentscope/embedding/_openai/_models/text-embedding-3-small.yaml
new file mode 100644
index 000000000..7f9a307e5
--- /dev/null
+++ b/src/agentscope/embedding/_openai/_models/text-embedding-3-small.yaml
@@ -0,0 +1,16 @@
+name: text-embedding-3-small
+label: Text Embedding 3 Small
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - application/x-embedding
+
+context_size: 8191
+
+parameter_overrides:
+ dimensions:
+ default: 1536
+ enum: [1536, 1024, 768, 512, 256]
diff --git a/src/agentscope/embedding/_openai_embedding.py b/src/agentscope/embedding/_openai_embedding.py
deleted file mode 100644
index 88b2e1eb0..000000000
--- a/src/agentscope/embedding/_openai_embedding.py
+++ /dev/null
@@ -1,109 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The OpenAI text embedding model class."""
-from datetime import datetime
-from typing import Any, List
-
-from ._embedding_response import EmbeddingResponse
-from ._embedding_usage import EmbeddingUsage
-from ._cache_base import EmbeddingCacheBase
-from ._embedding_base import EmbeddingModelBase
-from ..message import TextBlock
-
-
-class OpenAITextEmbedding(EmbeddingModelBase):
- """OpenAI text embedding model class."""
-
- supported_modalities: list[str] = ["text"]
- """This class only supports text input."""
-
- def __init__(
- self,
- api_key: str,
- model_name: str,
- dimensions: int = 1024,
- embedding_cache: EmbeddingCacheBase | None = None,
- **kwargs: Any,
- ) -> None:
- """Initialize the OpenAI text embedding model class.
-
- Args:
- api_key (`str`):
- The OpenAI API key.
- model_name (`str`):
- The name of the embedding model.
- dimensions (`int`, defaults to 1024):
- The dimension of the embedding vector.
- embedding_cache (`EmbeddingCacheBase | None`, defaults to `None`):
- The embedding cache class instance, used to cache the
- embedding results to avoid repeated API calls.
-
- # TODO: handle batch size limit and token limit
- """
- import openai
-
- super().__init__(model_name, dimensions)
-
- self.client = openai.AsyncClient(api_key=api_key, **kwargs)
- self.embedding_cache = embedding_cache
-
- async def __call__(
- self,
- text: List[str | TextBlock],
- **kwargs: Any,
- ) -> EmbeddingResponse:
- """Call the OpenAI embedding API.
-
- Args:
- text (`List[str | TextBlock]`):
- The input text to be embedded. It can be a list of strings.
- """
- gather_text = []
- for _ in text:
- if isinstance(_, dict) and "text" in _:
- gather_text.append(_["text"])
- elif isinstance(_, str):
- gather_text.append(_)
- else:
- raise ValueError(
- "Input text must be a list of strings or TextBlock dicts.",
- )
-
- kwargs = {
- "input": gather_text,
- "model": self.model_name,
- "dimensions": self.dimensions,
- "encoding_format": "float",
- **kwargs,
- }
-
- if self.embedding_cache:
- cached_embeddings = await self.embedding_cache.retrieve(
- identifier=kwargs,
- )
- if cached_embeddings:
- return EmbeddingResponse(
- embeddings=cached_embeddings,
- usage=EmbeddingUsage(
- tokens=0,
- time=0,
- ),
- source="cache",
- )
-
- start_time = datetime.now()
- response = await self.client.embeddings.create(**kwargs)
- time = (datetime.now() - start_time).total_seconds()
-
- if self.embedding_cache:
- await self.embedding_cache.store(
- identifier=kwargs,
- embeddings=[_.embedding for _ in response.data],
- )
-
- return EmbeddingResponse(
- embeddings=[_.embedding for _ in response.data],
- usage=EmbeddingUsage(
- tokens=response.usage.total_tokens,
- time=time,
- ),
- )
diff --git a/tests/embedding_dashscope_test.py b/tests/embedding_dashscope_test.py
new file mode 100644
index 000000000..b1e4c1e96
--- /dev/null
+++ b/tests/embedding_dashscope_test.py
@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access,unused-argument
+"""Unit tests for DashScopeEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyValue
+
+from agentscope.credential import DashScopeCredential
+from agentscope.embedding import (
+ DashScopeEmbeddingModel,
+ EmbeddingResponse,
+ EmbeddingUsage,
+)
+from agentscope.message import DataBlock, Base64Source, URLSource
+
+A = AnyValue()
+
+
+def _text_resp(
+ embeddings: list[list[float]],
+ total_tokens: int = 10,
+ status_code: int = 200,
+) -> MagicMock:
+ """Build a mock DashScope text embedding response."""
+ resp = MagicMock()
+ resp.status_code = status_code
+ resp.output = {"embeddings": [{"embedding": e} for e in embeddings]}
+ resp.usage = {"total_tokens": total_tokens}
+ return resp
+
+
+def _cred() -> DashScopeCredential:
+ """Create a test credential."""
+ return DashScopeCredential(api_key="k")
+
+
+def _img() -> DataBlock:
+ """Create a test image DataBlock."""
+ return DataBlock(
+ source=Base64Source(data="aWltYWdl", media_type="image/png"),
+ )
+
+
+def _vid() -> DataBlock:
+ """Create a test video DataBlock."""
+ return DataBlock(
+ source=URLSource(url="https://x.com/v.mp4", media_type="video/mp4"),
+ )
+
+
+def _mock_resp(embeddings: list[list[float]]) -> EmbeddingResponse:
+ """Create a mock EmbeddingResponse."""
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(tokens=len(embeddings), time=0.01),
+ )
+
+
+class DashScopeListModelsTest(IsolatedAsyncioTestCase):
+ """Test list_models for DashScope."""
+
+ async def test_list_models(self) -> None:
+ """Should list 7 models (text + multimodal)."""
+ cards = DashScopeEmbeddingModel.list_models()
+ names = sorted(c.name for c in cards)
+ self.assertEqual(len(cards), 7)
+ self.assertIn("text-embedding-v4", names)
+ self.assertIn("qwen3-vl-embedding", names)
+ self.assertIn("multimodal-embedding-v1", names)
+
+ async def test_hidden_dimensions(self) -> None:
+ """multimodal-embedding-v1 has hidden dimensions."""
+ cards = DashScopeEmbeddingModel.list_models()
+ v1 = next(c for c in cards if c.name == "multimodal-embedding-v1")
+ self.assertDictEqual(
+ v1.model_dump(),
+ {
+ "type": "embedding_model",
+ "name": "multimodal-embedding-v1",
+ "label": "Multimodal Embedding v1",
+ "status": "active",
+ "input_types": [
+ "text/plain",
+ "image/jpeg",
+ "image/png",
+ "image/bmp",
+ ],
+ "output_types": ["application/x-embedding"],
+ "context_size": 512,
+ "parameter_schema": {
+ "type": "object",
+ "properties": {},
+ "required": [],
+ },
+ "parameter_overrides": {
+ "dimensions": {"hidden": True, "default": 1024},
+ },
+ },
+ )
+
+ async def test_visible_dimensions(self) -> None:
+ """qwen3-vl-embedding exposes dimension choices."""
+ cards = DashScopeEmbeddingModel.list_models()
+ qwen = next(c for c in cards if c.name == "qwen3-vl-embedding")
+ dims = qwen.parameter_schema["properties"]["dimensions"]
+ self.assertDictEqual(
+ dims,
+ {
+ "default": 2560,
+ "description": "The output embedding vector dimensions.",
+ "enum": [2560, 2048, 1536, 1024, 768, 512, 256],
+ "exclusiveMinimum": 0,
+ "title": "Dimensions",
+ "type": "integer",
+ },
+ )
+
+
+class DashScopeTextCallTest(IsolatedAsyncioTestCase):
+ """Test DashScope text embedding API calls."""
+
+ @patch("dashscope.embeddings.TextEmbedding.call")
+ async def test_text_call(self, mock_api: Any) -> None:
+ """Text mode returns correct embeddings."""
+ mock_api.return_value = _text_resp([[0.1, 0.2], [0.3, 0.4]], 12)
+ model = DashScopeEmbeddingModel(
+ credential=_cred(),
+ model="text-embedding-v4",
+ parameters=DashScopeEmbeddingModel.Parameters(dimensions=2),
+ )
+ result = await model(["hello", "world"])
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 12, "time": A, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ @patch("dashscope.embeddings.TextEmbedding.call")
+ async def test_text_rejects_datablock(self, mock_api: Any) -> None:
+ """Text mode rejects DataBlock inputs."""
+ model = DashScopeEmbeddingModel(
+ credential=_cred(),
+ model="text-embedding-v4",
+ )
+ with self.assertRaises(ValueError):
+ await model([_img()])
+
+ @patch("dashscope.embeddings.TextEmbedding.call")
+ async def test_text_api_error_raises(self, mock_api: Any) -> None:
+ """Non-200 status code raises RuntimeError after retries."""
+ mock_api.return_value = _text_resp([], status_code=400)
+ model = DashScopeEmbeddingModel(
+ credential=_cred(),
+ model="text-embedding-v4",
+ retry_delay=0.0,
+ )
+ with self.assertRaises(RuntimeError):
+ await model(["hello"])
+
+
+class DashScopeMultimodalCallTest(IsolatedAsyncioTestCase):
+ """Test DashScope multimodal embedding via mocked _call_multimodal."""
+
+ async def test_multimodal_text_and_image(self) -> None:
+ """Multimodal call with text + image."""
+ model = DashScopeEmbeddingModel(
+ credential=_cred(),
+ model="qwen3-vl-embedding",
+ parameters=DashScopeEmbeddingModel.Parameters(dimensions=2),
+ )
+ model._call_multimodal = AsyncMock(
+ return_value=_mock_resp([[0.1, 0.2], [0.3, 0.4]]),
+ )
+ result = await model(["describe this", _img()])
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ async def test_multimodal_batching_by_image_limit(self) -> None:
+ """8 images with max_images=5 produces 2 batches (5+3)."""
+ model = DashScopeEmbeddingModel(
+ credential=_cred(),
+ model="qwen3-vl-embedding",
+ parameters=DashScopeEmbeddingModel.Parameters(dimensions=1),
+ )
+ call_count = 0
+
+ async def _mock(inputs: list, **_kw: Any) -> EmbeddingResponse:
+ nonlocal call_count
+ call_count += 1
+ return _mock_resp([[0.1]] * len(inputs))
+
+ model._call_multimodal = _mock # type: ignore[assignment]
+ result = await model([_img() for _ in range(8)])
+ self.assertEqual(result["embeddings"], [[0.1]] * 8)
+ self.assertEqual(call_count, 2)
+
+ async def test_multimodal_batching_by_video_limit(self) -> None:
+ """3 videos with max_videos=1 produces 3 batches."""
+ model = DashScopeEmbeddingModel(
+ credential=_cred(),
+ model="qwen3-vl-embedding",
+ parameters=DashScopeEmbeddingModel.Parameters(dimensions=1),
+ )
+ call_count = 0
+
+ async def _mock(inputs: list, **_kw: Any) -> EmbeddingResponse:
+ nonlocal call_count
+ call_count += 1
+ return _mock_resp([[0.1]] * len(inputs))
+
+ model._call_multimodal = _mock # type: ignore[assignment]
+ result = await model([_vid(), _vid(), _vid()])
+ self.assertEqual(result["embeddings"], [[0.1]] * 3)
+ self.assertEqual(call_count, 3)
+
+ async def test_video_base64_rejected(self) -> None:
+ """Video with Base64Source raises ValueError."""
+ bad = DataBlock(source=Base64Source(data="x", media_type="video/mp4"))
+ with self.assertRaises(ValueError):
+ DashScopeEmbeddingModel._format_data_block(bad)
diff --git a/tests/embedding_gemini_test.py b/tests/embedding_gemini_test.py
new file mode 100644
index 000000000..868f67201
--- /dev/null
+++ b/tests/embedding_gemini_test.py
@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for GeminiEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock
+
+from utils import AnyValue
+
+from agentscope.embedding import (
+ GeminiEmbeddingModel,
+ EmbeddingResponse,
+ EmbeddingUsage,
+)
+from agentscope.message import DataBlock, Base64Source
+
+A = AnyValue()
+
+
+def _mock_resp(embeddings: list[list[float]]) -> EmbeddingResponse:
+ """Create a mock EmbeddingResponse."""
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(tokens=len(embeddings), time=0.01),
+ )
+
+
+def _img() -> DataBlock:
+ """Create a test image DataBlock."""
+ return DataBlock(
+ source=Base64Source(data="aWltYWdl", media_type="image/png"),
+ )
+
+
+class GeminiListModelsTest(IsolatedAsyncioTestCase):
+ """Test list_models for Gemini."""
+
+ async def test_list_models(self) -> None:
+ """Should list 2 models."""
+ cards = GeminiEmbeddingModel.list_models()
+ names = sorted(c.name for c in cards)
+ self.assertEqual(names, ["gemini-embedding-001", "gemini-embedding-2"])
+
+ async def test_text_model_card(self) -> None:
+ """gemini-embedding-001 is text-only with 2048 context."""
+ cards = GeminiEmbeddingModel.list_models()
+ card = next(c for c in cards if c.name == "gemini-embedding-001")
+ self.assertDictEqual(
+ card.model_dump(),
+ {
+ "type": "embedding_model",
+ "name": "gemini-embedding-001",
+ "label": "Gemini Embedding 001",
+ "status": "active",
+ "input_types": ["text/plain"],
+ "output_types": ["application/x-embedding"],
+ "context_size": 2048,
+ "parameter_schema": {
+ "type": "object",
+ "properties": {
+ "dimensions": {
+ "default": 3072,
+ "description": (
+ "The output embedding vector dimensions."
+ ),
+ "enum": [3072, 1536, 768, 512, 256, 128],
+ "exclusiveMinimum": 0,
+ "title": "Dimensions",
+ "type": "integer",
+ },
+ },
+ "required": [],
+ },
+ "parameter_overrides": {
+ "dimensions": {
+ "default": 3072,
+ "enum": [3072, 1536, 768, 512, 256, 128],
+ },
+ },
+ },
+ )
+
+ async def test_multimodal_model_card(self) -> None:
+ """gemini-embedding-2 is multimodal with 8192 context."""
+ cards = GeminiEmbeddingModel.list_models()
+ card = next(c for c in cards if c.name == "gemini-embedding-2")
+ self.assertIn("image/png", card.input_types)
+ self.assertIn("application/pdf", card.input_types)
+ self.assertEqual(card.context_size, 8192)
+ self.assertEqual(
+ card.parameter_schema["properties"]["dimensions"]["enum"],
+ [3072, 1536, 768],
+ )
+
+
+class GeminiTextCallTest(IsolatedAsyncioTestCase):
+ """Test Gemini text embedding via mocked _call_text."""
+
+ def _make_text_model(self) -> GeminiEmbeddingModel:
+ """Create a text-mode model bypassing __init__ (no genai)."""
+ model = GeminiEmbeddingModel.__new__(GeminiEmbeddingModel)
+ model.model = "gemini-embedding-001"
+ model.dimensions = 2
+ model.context_size = 2048
+ model.batch_size = 100
+ model.max_retries = 3
+ model.retry_delay = 1.0
+ model._is_multimodal = False
+ model.embedding_cache = None
+ return model
+
+ async def test_text_call(self) -> None:
+ """Text mode delegates to _call_text."""
+ model = self._make_text_model()
+ model._call_text = AsyncMock(
+ return_value=_mock_resp([[0.1, 0.2], [0.3, 0.4]]),
+ )
+ result = await model(["hello", "world"])
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ async def test_text_rejects_datablock(self) -> None:
+ """Text mode rejects DataBlock inputs."""
+ model = self._make_text_model()
+ with self.assertRaises(ValueError):
+ await GeminiEmbeddingModel._call_text(model, [_img()])
+
+
+class GeminiMultimodalCallTest(IsolatedAsyncioTestCase):
+ """Test Gemini multimodal embedding via mocked _call_multimodal."""
+
+ def _make_multimodal_model(self) -> GeminiEmbeddingModel:
+ """Create a multimodal-mode model bypassing __init__."""
+ model = GeminiEmbeddingModel.__new__(GeminiEmbeddingModel)
+ model.model = "gemini-embedding-2"
+ model.dimensions = 1
+ model.context_size = 8192
+ model.batch_size = 100
+ model.max_retries = 3
+ model.retry_delay = 1.0
+ model._is_multimodal = True
+ model.embedding_cache = None
+ from agentscope.embedding._gemini._model import _MultimodalLimits
+
+ model._limits = _MultimodalLimits(
+ max_elements=20,
+ max_images=6,
+ max_videos=1,
+ max_audios=1,
+ max_pdfs=1,
+ )
+ return model
+
+ async def test_multimodal_delegates(self) -> None:
+ """Multimodal mode delegates to _call_multimodal."""
+ model = self._make_multimodal_model()
+ model._call_multimodal = AsyncMock(
+ return_value=_mock_resp([[0.1], [0.2]]),
+ )
+ result = await model(["hello", "world"])
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1], [0.2]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ async def test_multimodal_batching_by_image_limit(self) -> None:
+ """8 images with max_images=6 produces 2 batches (6+2)."""
+ model = self._make_multimodal_model()
+ call_count = 0
+
+ async def _mock(inputs: list, **_kw: Any) -> EmbeddingResponse:
+ nonlocal call_count
+ call_count += 1
+ return _mock_resp([[0.1]] * len(inputs))
+
+ model._call_multimodal = _mock # type: ignore[assignment]
+ result = await model([_img() for _ in range(8)])
+ self.assertEqual(result["embeddings"], [[0.1]] * 8)
+ self.assertEqual(call_count, 2)
diff --git a/tests/embedding_ollama_test.py b/tests/embedding_ollama_test.py
new file mode 100644
index 000000000..16d268c61
--- /dev/null
+++ b/tests/embedding_ollama_test.py
@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OllamaEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock
+
+from utils import AnyValue
+
+from agentscope.credential import OllamaCredential
+from agentscope.embedding import (
+ OllamaEmbeddingModel,
+ EmbeddingResponse,
+ EmbeddingUsage,
+)
+
+A = AnyValue()
+
+
+def _cred() -> OllamaCredential:
+ """Create a test credential."""
+ return OllamaCredential(host="http://localhost:11434")
+
+
+def _mock_resp(embeddings: list[list[float]]) -> EmbeddingResponse:
+ """Create a mock EmbeddingResponse."""
+ return EmbeddingResponse(
+ embeddings=embeddings,
+ usage=EmbeddingUsage(tokens=len(embeddings), time=0.01),
+ )
+
+
+class OllamaListModelsTest(IsolatedAsyncioTestCase):
+ """Test list_models for Ollama."""
+
+ async def test_list_models_empty(self) -> None:
+ """Ollama has no pre-defined YAMLs, returns empty list."""
+ self.assertEqual(OllamaEmbeddingModel.list_models(), [])
+
+
+class OllamaEmbeddingCallTest(IsolatedAsyncioTestCase):
+ """Test Ollama embedding via mocked _call_api."""
+
+ async def test_basic_call(self) -> None:
+ """Basic call returns correct embeddings."""
+ model = OllamaEmbeddingModel(
+ credential=_cred(),
+ model="nomic-embed-text",
+ parameters=OllamaEmbeddingModel.Parameters(dimensions=2),
+ )
+ model._call_api = AsyncMock(
+ return_value=_mock_resp([[0.1, 0.2], [0.3, 0.4]]),
+ )
+ result = await model(["hello", "world"])
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 2, "time": 0.01, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ async def test_dimensions_and_host(self) -> None:
+ """Dimensions and host are set correctly from constructor."""
+ model = OllamaEmbeddingModel(
+ credential=OllamaCredential(host="http://gpu:11434"),
+ model="test",
+ parameters=OllamaEmbeddingModel.Parameters(dimensions=768),
+ )
+ self.assertEqual(model.dimensions, 768)
+ self.assertEqual(model.host, "http://gpu:11434")
+
+ async def test_multi_batch(self) -> None:
+ """Batching splits inputs correctly."""
+ model = OllamaEmbeddingModel(
+ credential=_cred(),
+ model="test",
+ parameters=OllamaEmbeddingModel.Parameters(dimensions=1),
+ )
+ model.batch_size = 2
+ call_count = 0
+
+ async def _mock(inputs: list[str], **_kw: Any) -> EmbeddingResponse:
+ nonlocal call_count
+ call_count += 1
+ return _mock_resp([[0.1]] * len(inputs))
+
+ model._call_api = _mock # type: ignore[assignment]
+ result = await model(["a", "b", "c"])
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1], [0.1], [0.1]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": A, "time": A, "type": "embedding"},
+ "source": "api",
+ },
+ )
+ self.assertEqual(call_count, 2)
diff --git a/tests/embedding_openai_test.py b/tests/embedding_openai_test.py
new file mode 100644
index 000000000..00fddae1a
--- /dev/null
+++ b/tests/embedding_openai_test.py
@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for OpenAIEmbeddingModel."""
+from dataclasses import asdict
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from utils import AnyValue
+
+from agentscope.credential import OpenAICredential
+from agentscope.embedding import OpenAIEmbeddingModel
+
+A = AnyValue()
+
+
+def _make_response(
+ embeddings: list[list[float]],
+ total_tokens: int = 10,
+) -> MagicMock:
+ """Build a mock ``openai.embeddings.create`` response."""
+ resp = MagicMock()
+ resp.data = [MagicMock(embedding=e) for e in embeddings]
+ resp.usage = MagicMock(total_tokens=total_tokens)
+ return resp
+
+
+class OpenAIListModelsTest(IsolatedAsyncioTestCase):
+ """Test ``list_models()`` for OpenAI."""
+
+ async def test_list_models(self) -> None:
+ """Should list 2 models with correct parameter_schema."""
+ cards = OpenAIEmbeddingModel.list_models()
+ names = sorted(c.name for c in cards)
+ self.assertEqual(
+ names,
+ ["text-embedding-3-large", "text-embedding-3-small"],
+ )
+
+ card = next(c for c in cards if c.name == "text-embedding-3-small")
+ self.assertDictEqual(
+ card.model_dump(),
+ {
+ "type": "embedding_model",
+ "name": "text-embedding-3-small",
+ "label": "Text Embedding 3 Small",
+ "status": "active",
+ "input_types": ["text/plain"],
+ "output_types": ["application/x-embedding"],
+ "context_size": 8191,
+ "parameter_schema": {
+ "type": "object",
+ "properties": {
+ "dimensions": {
+ "default": 1536,
+ "description": (
+ "The output embedding vector dimensions."
+ ),
+ "enum": [1536, 1024, 768, 512, 256],
+ "exclusiveMinimum": 0,
+ "title": "Dimensions",
+ "type": "integer",
+ },
+ },
+ "required": [],
+ },
+ "parameter_overrides": {
+ "dimensions": {
+ "default": 1536,
+ "enum": [1536, 1024, 768, 512, 256],
+ },
+ },
+ },
+ )
+
+
+class OpenAIEmbeddingCallTest(IsolatedAsyncioTestCase):
+ """Test OpenAI embedding API calls with mocked responses."""
+
+ @patch("openai.AsyncClient")
+ async def test_single_batch(self, mock_client_cls: Any) -> None:
+ """Single batch call returns correct embeddings."""
+ mock_client = MagicMock()
+ mock_client.embeddings.create = AsyncMock(
+ return_value=_make_response([[0.1, 0.2], [0.3, 0.4]], 8),
+ )
+ mock_client_cls.return_value = mock_client
+
+ model = OpenAIEmbeddingModel(
+ credential=OpenAICredential(api_key="k"),
+ model="text-embedding-3-small",
+ parameters=OpenAIEmbeddingModel.Parameters(dimensions=2),
+ )
+ result = await model(["hello", "world"])
+
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 8, "time": A, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ @patch("openai.AsyncClient")
+ async def test_multi_batch(self, mock_client_cls: Any) -> None:
+ """Inputs exceeding batch_size are split and merged."""
+ mock_client = MagicMock()
+ mock_client.embeddings.create = AsyncMock(
+ side_effect=[
+ _make_response([[0.1], [0.2]], 4),
+ _make_response([[0.3]], 2),
+ ],
+ )
+ mock_client_cls.return_value = mock_client
+
+ model = OpenAIEmbeddingModel(
+ credential=OpenAICredential(api_key="k"),
+ model="text-embedding-3-small",
+ parameters=OpenAIEmbeddingModel.Parameters(dimensions=1),
+ )
+ model.batch_size = 2
+
+ result = await model(["a", "b", "c"])
+
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [[0.1], [0.2], [0.3]],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 6, "time": A, "type": "embedding"},
+ "source": "api",
+ },
+ )
+
+ @patch("openai.AsyncClient")
+ async def test_empty_input(self, mock_client_cls: Any) -> None:
+ """Empty input returns empty response without API call."""
+ mock_client = MagicMock()
+ mock_client_cls.return_value = mock_client
+
+ model = OpenAIEmbeddingModel(
+ credential=OpenAICredential(api_key="k"),
+ model="text-embedding-3-small",
+ )
+ result = await model([])
+
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "embeddings": [],
+ "id": A,
+ "created_at": A,
+ "type": "embedding",
+ "usage": {"tokens": 0, "time": 0, "type": "embedding"},
+ "source": "api",
+ },
+ )
+ mock_client.embeddings.create.assert_not_called()
+
+ @patch("openai.AsyncClient")
+ async def test_retry_on_transient_error(
+ self,
+ mock_client_cls: Any,
+ ) -> None:
+ """Retryable OpenAI errors are retried."""
+ import openai
+
+ mock_client = MagicMock()
+ mock_client.embeddings.create = AsyncMock(
+ side_effect=[
+ openai.RateLimitError(
+ message="rate limit",
+ response=MagicMock(status_code=429),
+ body=None,
+ ),
+ _make_response([[0.1]], 1),
+ ],
+ )
+ mock_client_cls.return_value = mock_client
+
+ model = OpenAIEmbeddingModel(
+ credential=OpenAICredential(api_key="k"),
+ model="text-embedding-3-small",
+ parameters=OpenAIEmbeddingModel.Parameters(dimensions=1),
+ retry_delay=0.0,
+ )
+ result = await model(["hello"])
+
+ self.assertEqual(result["embeddings"], [[0.1]])
+ self.assertEqual(mock_client.embeddings.create.await_count, 2)
diff --git a/tests/utils.py b/tests/utils.py
index 010ca3c08..1a2835767 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -22,6 +22,20 @@ class AnyString(str):
return "<AnyString>"
+class AnyValue:
+ """A helper class for asserting any value (str, int, float, etc.)
+ in unit tests. Useful for dynamic fields like timestamps, tokens,
+ or durations where the exact value is unpredictable."""
+
+ def __eq__(self, other: object) -> bool:
+ """Override equality check to match any value."""
+ return True
+
+ def __repr__(self) -> str:
+ """Return a string representation for debugging purposes."""
+ return "<AnyValue>"
+
+
class MockCredential(CredentialBase):
"""The mock credential class."""