Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
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__.pyindex 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_modelfrom ._model import get_modelfrom ._session import SessionServicefrom ._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.pynew file mode 100644index 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__.pyindex 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__.pyindex 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.pyindex 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.pyindex 2bcd918b3..72f89940f 100644--- a/src/agentscope/credential/_base.py+++ b/src/agentscope/credential/_base.py@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Typefrom pydantic import BaseModel, Fieldif TYPE_CHECKING:+ from ..embedding import EmbeddingModelBasefrom ..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 Nonediff --git a/src/agentscope/credential/_dashscope.py b/src/agentscope/credential/_dashscope.pyindex 1289acd41..8e9a85666 100644--- a/src/agentscope/credential/_dashscope.py+++ b/src/agentscope/credential/_dashscope.py@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field, SecretStrfrom ._base import CredentialBaseif TYPE_CHECKING:+ from ..embedding import EmbeddingModelBasefrom ..model import ChatModelBase_DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"@@ -41,3 +42,10 @@ class DashScopeCredential(CredentialBase):from ..model import DashScopeChatModelreturn DashScopeChatModel++ @classmethod+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:+ """Return the DashScopeEmbeddingModel class."""+ from ..embedding import DashScopeEmbeddingModel++ return DashScopeEmbeddingModeldiff --git a/src/agentscope/credential/_gemini.py b/src/agentscope/credential/_gemini.pyindex 67bd65656..43775cc82 100644--- a/src/agentscope/credential/_gemini.py+++ b/src/agentscope/credential/_gemini.py@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field, SecretStrfrom ._base import CredentialBaseif TYPE_CHECKING:+ from ..embedding import EmbeddingModelBasefrom ..model import ChatModelBase@@ -31,3 +32,10 @@ class GeminiCredential(CredentialBase):from ..model import GeminiChatModelreturn GeminiChatModel++ @classmethod+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:+ """Return the GeminiEmbeddingModel class."""+ from ..embedding import GeminiEmbeddingModel++ return GeminiEmbeddingModeldiff --git a/src/agentscope/credential/_ollama.py b/src/agentscope/credential/_ollama.pyindex 84bdee4f1..c2c27f93c 100644--- a/src/agentscope/credential/_ollama.py+++ b/src/agentscope/credential/_ollama.py@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Fieldfrom ._base import CredentialBaseif TYPE_CHECKING:+ from ..embedding import EmbeddingModelBasefrom ..model import ChatModelBase@@ -35,3 +36,10 @@ class OllamaCredential(CredentialBase):from ..model import OllamaChatModelreturn OllamaChatModel++ @classmethod+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:+ """Return the OllamaEmbeddingModel class."""+ from ..embedding import OllamaEmbeddingModel++ return OllamaEmbeddingModeldiff --git a/src/agentscope/credential/_openai.py b/src/agentscope/credential/_openai.pyindex a855ee66a..6cc132e7b 100644--- a/src/agentscope/credential/_openai.py+++ b/src/agentscope/credential/_openai.py@@ -7,6 +7,7 @@ from pydantic import ConfigDict, Field, SecretStrfrom ._base import CredentialBaseif TYPE_CHECKING:+ from ..embedding import EmbeddingModelBasefrom ..model import ChatModelBase@@ -46,3 +47,10 @@ class OpenAICredential(CredentialBase):from ..model import OpenAIChatModelreturn OpenAIChatModel++ @classmethod+ def get_embedding_model_class(cls) -> Type["EmbeddingModelBase"]:+ """Return the OpenAIEmbeddingModel class."""+ from ..embedding import OpenAIEmbeddingModel++ return OpenAIEmbeddingModeldiff --git a/src/agentscope/embedding/__init__.py b/src/agentscope/embedding/__init__.pyindex 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 EmbeddingModelCardfrom ._embedding_usage import EmbeddingUsagefrom ._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 OllamaEmbeddingModelfrom ._cache_base import EmbeddingCacheBasefrom ._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__.pynew file mode 100644index 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.pynew file mode 100644index 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.yamlnew file mode 100644index 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: 1024diff --git a/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yaml b/src/agentscope/embedding/_dashscope/_models/qwen2.5-vl-embedding.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pyindex 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 EmbeddingModelCardfrom ._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_cardsdiff --git a/src/agentscope/embedding/_embedding_model_card.py b/src/agentscope/embedding/_embedding_model_card.pynew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.pydeleted file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pydeleted file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.pydeleted file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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."""