Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(embedder): add DashScope embedding provider (#1535)

A0nameless0man147f1e3bd3ff
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 87fafd224..efe70200b 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -300,6 +300,52 @@ Recommended dimensions: `768`, `1536`, or `3072` (default: `3072`).
Get your API key at https://aistudio.google.com/apikey
+**DashScope (Alibaba Tongyi) provider:**
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "dashscope",
+ "api_key": "${DASHSCOPE_API_KEY}",
+ "model": "text-embedding-v4",
+ "dimension": 1024
+ }
+ }
+}
+```
+
+**Available DashScope models:**
+
+| Model | Dimension | Input Type | Notes |
+|-------|-----------|------------|-------|
+| `text-embedding-v3` | 1024 | text | Optimized for Chinese |
+| `text-embedding-v4` | 1024 | text | Optimized for Chinese |
+| `tongyi-embedding-vision-plus` | 1152 | multimodal | Supports fusion via `enable_fusion` |
+| `tongyi-embedding-vision-flash` | 768 | multimodal | Faster, lower cost |
+| `qwen3-vl-embedding` | 2560 | multimodal | Text + image + video |
+| `qwen2.5-vl-embedding` | 1024 | multimodal | Text + image + video |
+
+**Multimodal parameters** (text+image/video models only):
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `input_type` | str | `"multimodal"` or `"text"` | Embedding mode (default: `"multimodal"`) |
+| `enable_fusion` | bool | `false` | Enable fusion vectors for `tongyi-embedding-vision-*` models |
+| `res_level` | int | `2` | Image resolution level (1=high, 2=medium, 3=low) |
+| `max_video_frames` | int | `16` | Maximum video frames to embed |
+
+**Endpoint selection** — DashScope provides `api_base` defaults for China (`cn`) and international (`intl`) regions:
+
+| Region | `api_base` | Notes |
+|--------|-----------|-------|
+| China | `https://dashscope.aliyuncs.com` (default) | Recommended for users in mainland China |
+| International | `https://dashscope-intl.aliyuncs.com` | For users outside China |
+
+Custom endpoint URLs are also supported by setting a full URL.
+
+Get your API key at https://dashscope.console.aliyun.com/api-key
+
**Non-symmetric retrieval** (different task types for indexing vs. query):
```json
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 5080fde0e..13b48c6cc 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -121,7 +121,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
|------|------|------|
| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`) |
| `max_retries` | int | Embedding provider 瞬时错误的最大重试次数(`embedding.max_retries`,默认:`3`;`0` 表示禁用重试) |
-| `provider` | str | `"volcengine"`、`"openai"`、`"vikingdb"`、`"jina"`、`"voyage"`、`"minimax"` 或 `"gemini"` |
+| `provider` | str | `"volcengine"`、`"openai"`、`"vikingdb"`、`"jina"`、`"voyage"`、`"minimax"`、`"dashscope"` 或 `"gemini"` |
| `api_key` | str | API Key |
| `model` | str | 模型名称 |
| `dimension` | int | 向量维度 |
@@ -169,6 +169,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
- `voyage`: Voyage AI Embedding API
- `minimax`: MiniMax Embedding API
- `gemini`: Google Gemini Embedding API(仅文本;需安装 `google-genai>=1.0.0`)
+- `dashscope`: DashScope(阿里通义)Embedding API
**minimax provider 配置示例:**
@@ -270,6 +271,52 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
获取 API Key: https://aistudio.google.com/apikey
+**DashScope(阿里通义)provider 配置示例:**
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "dashscope",
+ "api_key": "${DASHSCOPE_API_KEY}",
+ "model": "text-embedding-v4",
+ "dimension": 1024
+ }
+ }
+}
+```
+
+**可用 DashScope 模型:**
+
+| 模型 | 维度 | 输入类型 | 说明 |
+|------|------|----------|------|
+| `text-embedding-v3` | 1024 | text | 针对中文优化 |
+| `text-embedding-v4` | 1024 | text | 针对中文优化 |
+| `tongyi-embedding-vision-plus` | 1152 | multimodal | 支持通过 `enable_fusion` 启用融合向量 |
+| `tongyi-embedding-vision-flash` | 768 | multimodal | 更快,成本更低 |
+| `qwen3-vl-embedding` | 2560 | multimodal | 文本 + 图像 + 视频 |
+| `qwen2.5-vl-embedding` | 1024 | multimodal | 文本 + 图像 + 视频 |
+
+**多模态参数**(仅文本+图像/视频模型支持):
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `input_type` | str | `"multimodal"` 或 `"text"` | 嵌入模式(默认: `"multimodal"`) |
+| `enable_fusion` | bool | `false` | 为 `tongyi-embedding-vision-*` 模型启用融合向量 |
+| `res_level` | int | `2` | 图像分辨率级别(1=高,2=中,3=低) |
+| `max_video_frames` | int | `16` | 视频最大嵌入帧数 |
+
+**端点选择** — DashScope 为中国区(`cn`)和国际区(`intl`)提供 `api_base` 默认值:
+
+| 区域 | `api_base` | 说明 |
+|------|-----------|------|
+| 中国 | `https://dashscope.aliyuncs.com`(默认) | 推荐中国大陆用户使用 |
+| 国际 | `https://dashscope-intl.aliyuncs.com` | 推荐中国境外用户使用 |
+
+也支持设置完整 URL 来自定义端点地址。
+
+获取 API Key: https://dashscope.console.aliyun.com/api-key
+
**非对称检索**(索引和查询使用不同的 task type):
```json
diff --git a/openviking/models/embedder/__init__.py b/openviking/models/embedder/__init__.py
index bdad90d71..8aae64390 100644
--- a/openviking/models/embedder/__init__.py
+++ b/openviking/models/embedder/__init__.py
@@ -27,6 +27,7 @@ from openviking.models.embedder.base import (
SparseEmbedderBase,
)
from openviking.models.embedder.cohere_embedders import CohereDenseEmbedder
+from openviking.models.embedder.dashscope_embedders import DashScopeDenseEmbedder
try:
from openviking.models.embedder.gemini_embedders import GeminiDenseEmbedder
@@ -56,6 +57,8 @@ from openviking.models.embedder.voyage_embedders import VoyageDenseEmbedder
__all__ = [
# Cohere implementations
"CohereDenseEmbedder",
+ # DashScope implementations
+ "DashScopeDenseEmbedder",
# Base classes
"EmbedResult",
"EmbedderBase",
diff --git a/openviking/models/embedder/dashscope_embedders.py b/openviking/models/embedder/dashscope_embedders.py
new file mode 100644
index 000000000..2ad109939
--- /dev/null
+++ b/openviking/models/embedder/dashscope_embedders.py
@@ -0,0 +1,434 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""DashScope Embedder Implementation
+
+Supports both text (via OpenAI-compatible endpoint) and multimodal (via native
+DashScope REST API) embedding modes.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+import openai
+
+from openviking.models.embedder.base import (
+ DenseEmbedderBase,
+ EmbedResult,
+ truncate_and_normalize,
+)
+from openviking.telemetry import get_current_telemetry
+from openviking_cli.utils.logger import default_logger as logger
+
+_DASHSCOPE_DIMENSIONS: Dict[str, int] = {
+ "text-embedding-v3": 1024,
+ "text-embedding-v4": 1024,
+ "qwen3-vl-embedding": 2560,
+ "qwen2.5-vl-embedding": 1024,
+}
+
+_DASHSCOPE_PREFIX_DIMENSIONS: Dict[str, int] = {
+ "tongyi-embedding-vision-plus": 1152,
+ "tongyi-embedding-vision-flash": 768,
+}
+
+
+def get_dashscope_model_default_dimension(model_name: str) -> int:
+ """Return default embedding dimension for a DashScope model.
+
+ Lookup order:
+ 1. Exact match in _DASHSCOPE_DIMENSIONS
+ 2. Prefix match in _DASHSCOPE_PREFIX_DIMENSIONS
+ 3. Fallback: 1024
+ """
+ if model_name in _DASHSCOPE_DIMENSIONS:
+ return _DASHSCOPE_DIMENSIONS[model_name]
+ for prefix, dim in _DASHSCOPE_PREFIX_DIMENSIONS.items():
+ if model_name.startswith(prefix):
+ return dim
+ return 1024
+
+
+class DashScopeDenseEmbedder(DenseEmbedderBase):
+ """DashScope Dense Embedder — dual-mode (text / multimodal).
+
+ Text mode uses the OpenAI-compatible endpoint; multimodal mode uses the
+ native DashScope REST API.
+ """
+
+ def __init__(
+ self,
+ model_name: str,
+ api_key: Optional[str] = None,
+ api_base: Optional[str] = None,
+ dimension: Optional[int] = None,
+ input_type: str = "multimodal",
+ enable_fusion: Optional[bool] = None,
+ res_level: Optional[int] = None,
+ max_video_frames: Optional[int] = None,
+ config: Optional[Dict[str, Any]] = None,
+ ):
+ super().__init__(model_name, config)
+ self.provider = "dashscope"
+
+ self.api_key = api_key
+ self.api_base = (api_base or "https://dashscope.aliyuncs.com").rstrip("/")
+ self._input_type = input_type
+ self.enable_fusion = enable_fusion
+ self.res_level = res_level
+ self.max_video_frames = max_video_frames
+
+ if not self.api_key:
+ raise ValueError("api_key is required")
+
+ self._dimension = dimension or get_dashscope_model_default_dimension(model_name)
+
+ # --- sync clients ---
+ # Text mode: OpenAI-compatible
+ self._openai_client = openai.OpenAI(
+ api_key=self.api_key,
+ base_url=f"{self.api_base}/compatible-mode/v1",
+ )
+ # Multimodal mode: httpx
+ self._httpx_client = httpx.Client(
+ headers={"Authorization": f"Bearer {self.api_key}"},
+ timeout=60.0,
+ )
+ self._multimodal_url = (
+ f"{self.api_base}/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding"
+ )
+
+ # --- async clients (lazy) ---
+ self._async_openai_client: Optional[openai.AsyncOpenAI] = None
+ self._async_httpx_client: Optional[httpx.AsyncClient] = None
+
+ # ------------------------------------------------------------------
+ # Token telemetry
+ # ------------------------------------------------------------------
+
+ def _update_telemetry_token_usage(self, response) -> None:
+ """Track token usage from either an OpenAI SDK response or an httpx response."""
+ usage = None
+
+ # OpenAI SDK response object
+ if hasattr(response, "usage"):
+ usage = response.usage
+ # httpx response — parse JSON body
+ elif hasattr(response, "json"):
+ try:
+ body: Dict[str, Any] = response.json() if callable(response.json) else response.json
+ usage = body.get("usage")
+ except Exception:
+ return
+
+ if not usage:
+ return
+
+ def _val(key: str, default: int = 0) -> int:
+ if isinstance(usage, dict):
+ return int(usage.get(key, default) or default)
+ return int(getattr(usage, key, default) or default)
+
+ prompt_tokens = _val("prompt_tokens") or _val("input_tokens", 0)
+ total_tokens = _val("total_tokens", prompt_tokens)
+ completion_tokens = max(total_tokens - prompt_tokens, 0)
+
+ get_current_telemetry().add_token_usage_by_source(
+ "embedding", prompt_tokens, completion_tokens
+ )
+ self.update_token_usage(
+ model_name=self.model_name,
+ provider="dashscope",
+ prompt_tokens=prompt_tokens,
+ completion_tokens=completion_tokens,
+ )
+
+ # ------------------------------------------------------------------
+ # Multimodal helpers
+ # ------------------------------------------------------------------
+
+ def _multimodal_params(self) -> Dict[str, Any]:
+ """Build parameters dict for multimodal requests, excluding None values."""
+ return {
+ k: v
+ for k, v in {
+ "dimension": self._dimension,
+ "enable_fusion": self.enable_fusion,
+ "res_level": self.res_level,
+ "max_video_frames": self.max_video_frames,
+ }.items()
+ if v is not None
+ }
+
+ def _multimodal_body(self, text: str) -> Dict[str, Any]:
+ body: Dict[str, Any] = {
+ "model": self.model_name,
+ "input": {"contents": [{"text": text}]},
+ }
+ params = self._multimodal_params()
+ if params:
+ body["parameters"] = params
+ return body
+
+ # ------------------------------------------------------------------
+ # Lazy async clients
+ # ------------------------------------------------------------------
+
+ def _get_async_openai_client(self) -> openai.AsyncOpenAI:
+ if self._async_openai_client is None:
+ self._async_openai_client = openai.AsyncOpenAI(
+ api_key=self.api_key,
+ base_url=f"{self.api_base}/compatible-mode/v1",
+ )
+ return self._async_openai_client
+
+ def _get_async_httpx_client(self) -> httpx.AsyncClient:
+ if self._async_httpx_client is None:
+ self._async_httpx_client = httpx.AsyncClient(
+ headers={"Authorization": f"Bearer {self.api_key}"},
+ timeout=60.0,
+ )
+ return self._async_httpx_client
+
+ # ------------------------------------------------------------------
+ # embed
+ # ------------------------------------------------------------------
+
+ def embed(self, text: str, is_query: bool = False) -> EmbedResult:
+ def _call() -> EmbedResult:
+ if self._input_type == "text":
+ response = self._openai_client.embeddings.create(
+ input=text, model=self.model_name, dimensions=self._dimension
+ )
+ self._update_telemetry_token_usage(response)
+ vector = response.data[0].embedding
+ else:
+ resp = self._httpx_client.post(
+ self._multimodal_url, json=self._multimodal_body(text)
+ )
+ resp.raise_for_status()
+ self._update_telemetry_token_usage(resp)
+ vector = resp.json()["output"]["embeddings"][0]["embedding"]
+
+ return EmbedResult(dense_vector=truncate_and_normalize(vector, self._dimension))
+
+ try:
+ return self._run_with_retry(_call, logger=logger, operation_name="DashScope embedding")
+ except Exception as e:
+ raise RuntimeError(f"DashScope embedding failed: {e}") from e
+
+ # ------------------------------------------------------------------
+ # embed_async
+ # ------------------------------------------------------------------
+
+ async def embed_async(self, text: str, is_query: bool = False) -> EmbedResult:
+ async def _call() -> EmbedResult:
+ if self._input_type == "text":
+ client = self._get_async_openai_client()
+ response = await client.embeddings.create(
+ input=text, model=self.model_name, dimensions=self._dimension
+ )
+ self._update_telemetry_token_usage(response)
+ vector = response.data[0].embedding
+ else:
+ client = self._get_async_httpx_client()
+ resp = await client.post(self._multimodal_url, json=self._multimodal_body(text))
+ resp.raise_for_status()
+ self._update_telemetry_token_usage(resp)
+ vector = resp.json()["output"]["embeddings"][0]["embedding"]
+
+ return EmbedResult(dense_vector=truncate_and_normalize(vector, self._dimension))
+
+ try:
+ return await self._run_with_async_retry(
+ _call, logger=logger, operation_name="DashScope async embedding"
+ )
+ except Exception as e:
+ raise RuntimeError(f"DashScope embedding failed: {e}") from e
+
+ # ------------------------------------------------------------------
+ # embed_batch — text mode chunks by 10 (DashScope text API limit)
+ # ------------------------------------------------------------------
+
+ def embed_batch(self, texts: List[str], is_query: bool = False) -> List[EmbedResult]:
+ if not texts:
+ return []
+
+ def _call() -> List[EmbedResult]:
+ results: List[EmbedResult] = []
+ if self._input_type == "text":
+ for i in range(0, len(texts), 10):
+ batch = texts[i : i + 10]
+ response = self._openai_client.embeddings.create(
+ input=batch, model=self.model_name, dimensions=self._dimension
+ )
+ self._update_telemetry_token_usage(response)
+ for item in response.data:
+ results.append(
+ EmbedResult(
+ dense_vector=truncate_and_normalize(item.embedding, self._dimension)
+ )
+ )
+ else:
+ for text in texts:
+ resp = self._httpx_client.post(
+ self._multimodal_url, json=self._multimodal_body(text)
+ )
+ resp.raise_for_status()
+ self._update_telemetry_token_usage(resp)
+ vector = resp.json()["output"]["embeddings"][0]["embedding"]
+ results.append(
+ EmbedResult(dense_vector=truncate_and_normalize(vector, self._dimension))
+ )
+ return results
+
+ try:
+ return self._run_with_retry(
+ _call, logger=logger, operation_name="DashScope batch embedding"
+ )
+ except Exception as e:
+ logger.error(
+ f"DashScope batch embedding failed, texts length: {len(texts)}, "
+ f"input_type: {self._input_type}, model_name: {self.model_name}"
+ )
+ raise RuntimeError(f"DashScope batch embedding failed: {e}") from e
+
+ # ------------------------------------------------------------------
+ # embed_batch_async
+ # ------------------------------------------------------------------
+
+ async def embed_batch_async(
+ self, texts: List[str], is_query: bool = False
+ ) -> List[EmbedResult]:
+ if not texts:
+ return []
+
+ async def _call() -> List[EmbedResult]:
+ results: List[EmbedResult] = []
+ if self._input_type == "text":
+ client = self._get_async_openai_client()
+ for i in range(0, len(texts), 10):
+ batch = texts[i : i + 10]
+ response = await client.embeddings.create(
+ input=batch, model=self.model_name, dimensions=self._dimension
+ )
+ self._update_telemetry_token_usage(response)
+ for item in response.data:
+ results.append(
+ EmbedResult(
+ dense_vector=truncate_and_normalize(item.embedding, self._dimension)
+ )
+ )
+ else:
+ client = self._get_async_httpx_client()
+ for text in texts:
+ resp = await client.post(self._multimodal_url, json=self._multimodal_body(text))
+ resp.raise_for_status()
+ self._update_telemetry_token_usage(resp)
+ vector = resp.json()["output"]["embeddings"][0]["embedding"]
+ results.append(
+ EmbedResult(dense_vector=truncate_and_normalize(vector, self._dimension))
+ )
+ return results
+
+ try:
+ return await self._run_with_async_retry(
+ _call, logger=logger, operation_name="DashScope async batch embedding"
+ )
+ except Exception as e:
+ logger.error(
+ f"DashScope async batch embedding failed, texts length: {len(texts)}, "
+ f"input_type: {self._input_type}, model_name: {self.model_name}"
+ )
+ raise RuntimeError(f"DashScope batch embedding failed: {e}") from e
+
+ # ------------------------------------------------------------------
+ # embed_content — multimodal content (text + image URLs)
+ # ------------------------------------------------------------------
+
+ def embed_content(self, contents: List[Dict[str, str]]) -> EmbedResult:
+ """Embed multimodal content (text + image URLs) via native DashScope API.
+
+ Args:
+ contents: List of content dicts, e.g. [{"text": "描述"}, {"image": "https://..."}]
+
+ Returns:
+ EmbedResult with dense_vector
+ """
+
+ def _call() -> EmbedResult:
+ body: Dict[str, Any] = {
+ "model": self.model_name,
+ "input": {"contents": contents},
+ }
+ params = self._multimodal_params()
+ if params:
+ body["parameters"] = params
+ resp = self._httpx_client.post(self._multimodal_url, json=body)
+ resp.raise_for_status()
+ self._update_telemetry_token_usage(resp)
+ vector = resp.json()["output"]["embeddings"][0]["embedding"]
+ return EmbedResult(dense_vector=truncate_and_normalize(vector, self._dimension))
+
+ try:
+ return self._run_with_retry(
+ _call, logger=logger, operation_name="DashScope content embedding"
+ )
+ except Exception as e:
+ raise RuntimeError(f"DashScope content embedding failed: {e}") from e
+
+ async def embed_content_async(self, contents: List[Dict[str, str]]) -> EmbedResult:
+ """Async version of embed_content."""
+
+ client = self._get_async_httpx_client()
+
+ async def _call() -> EmbedResult:
+ body: Dict[str, Any] = {
+ "model": self.model_name,
+ "input": {"contents": contents},
+ }
+ params = self._multimodal_params()
+ if params:
+ body["parameters"] = params
+ resp = await client.post(self._multimodal_url, json=body)
+ resp.raise_for_status()
+ self._update_telemetry_token_usage(resp)
+ vector = resp.json()["output"]["embeddings"][0]["embedding"]
+ return EmbedResult(dense_vector=truncate_and_normalize(vector, self._dimension))
+
+ try:
+ return await self._run_with_async_retry(
+ _call, logger=logger, operation_name="DashScope async content embedding"
+ )
+ except Exception as e:
+ raise RuntimeError(f"DashScope content embedding failed: {e}") from e
+
+ # ------------------------------------------------------------------
+ # Lifecycle
+ # ------------------------------------------------------------------
+
+ def get_dimension(self) -> int:
+ return self._dimension
+
+ def close(self):
+ # --- sync clients ---
+ if self._openai_client is not None:
+ self._openai_client.close()
+ if self._httpx_client is not None:
+ self._httpx_client.close()
+ # --- async clients (event-loop-aware cleanup) ---
+ import asyncio
+
+ async def _close_async_clients() -> None:
+ if self._async_openai_client is not None:
+ await self._async_openai_client.close()
+ if self._async_httpx_client is not None:
+ await self._async_httpx_client.aclose()
+
+ try:
+ loop = asyncio.get_running_loop()
+ except RuntimeError:
+ loop = None
+ if loop and loop.is_running():
+ loop.create_task(_close_async_clients())
+ else:
+ asyncio.run(_close_async_clients())
diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.py
index b9626cb23..d490f1619 100644
--- a/openviking_cli/utils/config/embedding_config.py
+++ b/openviking_cli/utils/config/embedding_config.py
@@ -37,7 +37,7 @@ class EmbeddingModelConfig(BaseModel):
provider: Optional[str] = Field(
default="volcengine",
description=(
- "Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama', 'gemini', 'voyage', 'litellm', 'local'. "
+ "Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama', 'gemini', 'voyage', 'dashscope', 'minimax', 'cohere', 'litellm', 'local'. "
"For OpenRouter or other OpenAI-compatible providers, use 'litellm' with "
"api_base and api_key, or 'openai' with api_base and extra_headers."
),
@@ -71,6 +71,18 @@ class EmbeddingModelConfig(BaseModel):
default=None,
description="Local model cache directory for provider='local'.",
)
+ enable_fusion: Optional[bool] = Field(
+ default=None,
+ description="Enable multimodal fusion for DashScope provider (multimodal models only).",
+ )
+ res_level: Optional[int] = Field(
+ default=None,
+ description="Resolution level for DashScope multimodal models (multimodal models only).",
+ )
+ max_video_frames: Optional[int] = Field(
+ default=None,
+ description="Maximum video frames for DashScope multimodal models (multimodal models only).",
+ )
model_config = {"extra": "forbid"}
@@ -110,6 +122,7 @@ class EmbeddingModelConfig(BaseModel):
"ollama",
"gemini",
"voyage",
+ "dashscope",
"minimax",
"cohere",
"litellm",
@@ -117,7 +130,7 @@ class EmbeddingModelConfig(BaseModel):
]:
raise ValueError(
f"Invalid embedding provider: '{self.provider}'. Must be one of: "
- "'openai', 'azure', 'volcengine', 'vikingdb', 'jina', 'ollama', 'gemini', 'voyage', 'minimax', 'cohere', 'litellm', 'local'"
+ "'openai', 'azure', 'volcengine', 'vikingdb', 'jina', 'ollama', 'gemini', 'voyage', 'dashscope', 'minimax', 'cohere', 'litellm', 'local'"
)
# Provider-specific validation
@@ -193,6 +206,18 @@ class EmbeddingModelConfig(BaseModel):
if not self.api_key:
raise ValueError("Cohere provider requires 'api_key' to be set")
+ elif self.provider == "dashscope":
+ if not self.api_key:
+ raise ValueError("DashScope provider requires 'api_key' to be set")
+ if self.input == "text" and (
+ self.enable_fusion is not None
+ or self.res_level is not None
+ or self.max_video_frames is not None
+ ):
+ raise ValueError(
+ "Parameters enable_fusion, res_level, and max_video_frames only apply to multimodal input mode"
+ )
+
elif self.provider == "litellm":
# litellm handles auth via env vars or explicit api_key; no strict requirement
if not self.dimension:
@@ -268,6 +293,17 @@ class EmbeddingModelConfig(BaseModel):
return get_local_model_default_dimension(self.model)
+ if provider == "dashscope":
+ try:
+ from openviking.models.embedder.dashscope_embedders import (
+ get_dashscope_model_default_dimension,
+ )
+
+ return get_dashscope_model_default_dimension(self.model)
+ except ImportError:
+ # Fallback dimension if dashscope_embedders module doesn't exist yet
+ return 1024
+
return 2048
@@ -383,6 +419,7 @@ class EmbeddingConfig(BaseModel):
"""
from openviking.models.embedder import (
CohereDenseEmbedder,
+ DashScopeDenseEmbedder,
GeminiDenseEmbedder,
JinaDenseEmbedder,
LiteLLMDenseEmbedder,
@@ -575,6 +612,28 @@ class EmbeddingConfig(BaseModel):
**({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),
},
),
+ ("dashscope", "dense"): (
+ DashScopeDenseEmbedder,
+ lambda cfg: {
+ "model_name": cfg.model,
+ "api_key": cfg.api_key,
+ "api_base": cfg.api_base,
+ "dimension": cfg.dimension,
+ "input_type": cfg.input,
+ "config": dict(runtime_config),
+ **(
+ {"enable_fusion": cfg.enable_fusion}
+ if cfg.enable_fusion is not None
+ else {}
+ ),
+ **({"res_level": cfg.res_level} if cfg.res_level is not None else {}),
+ **(
+ {"max_video_frames": cfg.max_video_frames}
+ if cfg.max_video_frames is not None
+ else {}
+ ),
+ },
+ ),
("cohere", "dense"): (
CohereDenseEmbedder,
lambda cfg: {
diff --git a/tests/integration/test_dashscope_embedding_it.py b/tests/integration/test_dashscope_embedding_it.py
new file mode 100644
index 000000000..8b43492ae
--- /dev/null
+++ b/tests/integration/test_dashscope_embedding_it.py
@@ -0,0 +1,160 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Integration tests for DashScopeDenseEmbedder — require real DASHSCOPE_API_KEY.
+Run: DASHSCOPE_API_KEY=<key> pytest tests/integration/test_dashscope_embedding_it.py -v
+Auto-skipped when DASHSCOPE_API_KEY is not set. No mocking — real API calls.
+"""
+
+import os
+
+import pytest
+
+from tests.integration.conftest import l2_norm
+
+DASHSCOPE_API_KEY = os.environ.get("DASHSCOPE_API_KEY", "")
+requires_dashscope = pytest.mark.skipif(not DASHSCOPE_API_KEY, reason="DASHSCOPE_API_KEY not set")
+
+pytestmark = [requires_dashscope]
+
+# ── Model constants ───────────────────────────────────────────────────────────
+DASHSCOPE_TEXT_MODEL = "text-embedding-v4"
+DASHSCOPE_TEXT_DIM = 1024
+DASHSCOPE_MULTIMODAL_MODEL = "tongyi-embedding-vision-flash"
+DASHSCOPE_MULTIMODAL_DIM = 768
+
+
+# ── Fixtures (module-local, not in conftest) ──────────────────────────────────
+
+
[email protected](scope="session")
+def dashscope_text_embedder():
+ """Session-scoped DashScope text-mode embedder."""
+ from openviking.models.embedder.dashscope_embedders import DashScopeDenseEmbedder
+
+ e = DashScopeDenseEmbedder(DASHSCOPE_TEXT_MODEL, api_key=DASHSCOPE_API_KEY, input_type="text")
+ yield e
+ e.close()
+
+
[email protected](scope="session")
+def dashscope_multimodal_embedder():
+ """Session-scoped DashScope multimodal-mode embedder."""
+ from openviking.models.embedder.dashscope_embedders import DashScopeDenseEmbedder
+
+ e = DashScopeDenseEmbedder(
+ DASHSCOPE_MULTIMODAL_MODEL, api_key=DASHSCOPE_API_KEY, input_type="multimodal"
+ )
+ yield e
+ e.close()
+
+
+# ── Text embedding tests ─────────────────────────────────────────────────────
+
+
+def test_text_embedding_basic(dashscope_text_embedder):
+ """Single Chinese text returns a non-zero vector of correct dimension."""
+ r = dashscope_text_embedder.embed("你好世界")
+ assert r.dense_vector and len(r.dense_vector) == DASHSCOPE_TEXT_DIM
+ assert any(v != 0.0 for v in r.dense_vector)
+ assert 0.99 < l2_norm(r.dense_vector) < 1.01
+
+
+def test_text_embedding_dimension(dashscope_text_embedder):
+ """Embedding with a custom dimension=512 produces a 512-dim vector."""
+ from openviking.models.embedder.dashscope_embedders import DashScopeDenseEmbedder
+
+ e = DashScopeDenseEmbedder(
+ DASHSCOPE_TEXT_MODEL,
+ api_key=DASHSCOPE_API_KEY,
+ input_type="text",
+ dimension=512,
+ )
+ try:
+ r = e.embed("What is machine learning?")
+ assert r.dense_vector and len(r.dense_vector) == 512
+ assert 0.99 < l2_norm(r.dense_vector) < 1.01
+ finally:
+ e.close()
+
+
+def test_text_embedding_batch(dashscope_text_embedder):
+ """Batch of 3 texts returns 3 results, all correct dimension."""
+ texts = ["苹果是水果", "香蕉也是水果", "樱桃很好吃"]
+ results = dashscope_text_embedder.embed_batch(texts)
+ assert len(results) == 3
+ for r in results:
+ assert r.dense_vector and len(r.dense_vector) == DASHSCOPE_TEXT_DIM
+
+
+# ── Multimodal embedding tests ───────────────────────────────────────────────
+
+
+def test_multimodal_text_only(dashscope_multimodal_embedder):
+ """Multimodal API with text-only input returns correct dimension vector."""
+ r = dashscope_multimodal_embedder.embed("这是一段测试文本")
+ assert r.dense_vector and len(r.dense_vector) == DASHSCOPE_MULTIMODAL_DIM
+ assert 0.99 < l2_norm(r.dense_vector) < 1.01
+
+
+# ── Error handling ───────────────────────────────────────────────────────────
+
+
+def test_error_invalid_api_key():
+ """Invalid API key must raise RuntimeError."""
+ from openviking.models.embedder.dashscope_embedders import DashScopeDenseEmbedder
+
+ bad = DashScopeDenseEmbedder(
+ DASHSCOPE_TEXT_MODEL, api_key="INVALID_KEY_XYZ_123", input_type="text"
+ )
+ with pytest.raises(RuntimeError, match="DashScope embedding failed"):
+ bad.embed("hello")
+
+
+# ── Image + multimodal content tests ─────────────────────────────────────────
+
+IMAGE_URL = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"
+
+
+def test_multimodal_with_image_url(dashscope_multimodal_embedder):
+ """Multimodal API with text + image URL returns correct dimension vector."""
+ r = dashscope_multimodal_embedder.embed_content(
+ [
+ {"text": "一只可爱的猫咪"},
+ {"image": IMAGE_URL},
+ ]
+ )
+ assert r.dense_vector and len(r.dense_vector) == DASHSCOPE_MULTIMODAL_DIM
+ assert 0.99 < l2_norm(r.dense_vector) < 1.01
+
+
+def test_multimodal_image_only(dashscope_multimodal_embedder):
+ """Multimodal API with image-only input returns a vector."""
+ r = dashscope_multimodal_embedder.embed_content(
+ [
+ {"image": IMAGE_URL},
+ ]
+ )
+ assert r.dense_vector and len(r.dense_vector) == DASHSCOPE_MULTIMODAL_DIM
+
+
+def test_multimodal_with_fusion(dashscope_multimodal_embedder):
+ """Fused embedding with enable_fusion=True returns a vector."""
+ from openviking.models.embedder.dashscope_embedders import DashScopeDenseEmbedder
+
+ e = DashScopeDenseEmbedder(
+ DASHSCOPE_MULTIMODAL_MODEL,
+ api_key=DASHSCOPE_API_KEY,
+ input_type="multimodal",
+ enable_fusion=True,
+ )
+ try:
+ r = e.embed_content(
+ [
+ {"text": "描述这张图片的内容"},
+ {"image": IMAGE_URL},
+ ]
+ )
+ assert r.dense_vector and len(r.dense_vector) == DASHSCOPE_MULTIMODAL_DIM
+ finally:
+ e.close()
diff --git a/tests/unit/test_dashscope_embedder.py b/tests/unit/test_dashscope_embedder.py
new file mode 100644
index 000000000..d89f6dcf9
--- /dev/null
+++ b/tests/unit/test_dashscope_embedder.py
@@ -0,0 +1,698 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Tests for DashScopeDenseEmbedder.
+Pattern: patch at module import path, use MagicMock, never make real API calls.
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from openviking.models.embedder.dashscope_embedders import (
+ DashScopeDenseEmbedder,
+ get_dashscope_model_default_dimension,
+)
+
+# ---------------------------------------------------------------------------
+# Dimension helper
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeDimensionHelper:
+ """Test get_dashscope_model_default_dimension() for all known models."""
+
+ def test_text_embedding_v3(self):
+ assert get_dashscope_model_default_dimension("text-embedding-v3") == 1024
+
+ def test_text_embedding_v4(self):
+ assert get_dashscope_model_default_dimension("text-embedding-v4") == 1024
+
+ def test_tongyi_vision_plus(self):
+ assert get_dashscope_model_default_dimension("tongyi-embedding-vision-plus") == 1152
+
+ def test_tongyi_vision_flash(self):
+ assert get_dashscope_model_default_dimension("tongyi-embedding-vision-flash") == 768
+
+ def test_qwen3_vl_embedding(self):
+ assert get_dashscope_model_default_dimension("qwen3-vl-embedding") == 2560
+
+ def test_qwen2_5_vl_embedding(self):
+ assert get_dashscope_model_default_dimension("qwen2.5-vl-embedding") == 1024
+
+ def test_unknown_model_fallback(self):
+ assert get_dashscope_model_default_dimension("some-unknown-model") == 1024
+
+ def test_prefix_match_tongyi_vision_plus_variant(self):
+ # Prefix match: starts with "tongyi-embedding-vision-plus"
+ assert get_dashscope_model_default_dimension("tongyi-embedding-vision-plus-v2") == 1152
+
+ def test_prefix_match_tongyi_vision_flash_variant(self):
+ assert get_dashscope_model_default_dimension("tongyi-embedding-vision-flash-2025") == 768
+
+
+# ---------------------------------------------------------------------------
+# Init
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeInit:
+ """Test DashScopeDenseEmbedder initialization."""
+
+ def test_requires_api_key(self):
+ with pytest.raises(ValueError, match="api_key is required"):
+ DashScopeDenseEmbedder(model_name="text-embedding-v4", api_key=None)
+
+ def test_requires_api_key_empty_string(self):
+ with pytest.raises(ValueError, match="api_key is required"):
+ DashScopeDenseEmbedder(model_name="text-embedding-v4", api_key="")
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_stores_text_mode_params(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ input_type="text",
+ )
+ assert embedder._input_type == "text"
+ assert embedder.api_key == "sk-test"
+ assert embedder.api_base == "https://dashscope.aliyuncs.com"
+ assert embedder.provider == "dashscope"
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_stores_multimodal_params(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ enable_fusion=True,
+ res_level=2,
+ max_video_frames=16,
+ )
+ assert embedder._input_type == "multimodal"
+ assert embedder.enable_fusion is True
+ assert embedder.res_level == 2
+ assert embedder.max_video_frames == 16
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_default_dimension_from_helper(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ )
+ assert embedder.get_dimension() == 1024
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_custom_dimension_overrides_helper(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ dimension=512,
+ )
+ assert embedder.get_dimension() == 512
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_custom_api_base(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ api_base="https://custom-endpoint.com",
+ )
+ assert embedder.api_base == "https://custom-endpoint.com"
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_api_base_trailing_slash_stripped(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ api_base="https://custom-endpoint.com/",
+ )
+ assert embedder.api_base == "https://custom-endpoint.com"
+
+
+# ---------------------------------------------------------------------------
+# Text mode embed
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeTextEmbed:
+ """Test text mode embed with mocked openai.OpenAI."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_returns_correct_vector(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ mock_embedding = MagicMock()
+ mock_embedding.embedding = [0.1] * 1024
+ mock_response = MagicMock()
+ mock_response.data = [mock_embedding]
+ mock_response.usage = MagicMock(prompt_tokens=10, total_tokens=10)
+ mock_client.embeddings.create.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ result = embedder.embed("hello world")
+ assert result.dense_vector == [0.1] * 1024
+ assert result.is_dense
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_sends_dimensions_param(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ mock_embedding = MagicMock()
+ mock_embedding.embedding = [0.1] * 512
+ mock_response = MagicMock()
+ mock_response.data = [mock_embedding]
+ mock_response.usage = MagicMock(prompt_tokens=5, total_tokens=5)
+ mock_client.embeddings.create.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ input_type="text",
+ dimension=512,
+ )
+ embedder.embed("hello")
+
+ call_kwargs = mock_client.embeddings.create.call_args[1]
+ assert call_kwargs["dimensions"] == 512
+ assert call_kwargs["model"] == "text-embedding-v4"
+ assert call_kwargs["input"] == "hello"
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_api_error_raises_runtime_error(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+ mock_client.embeddings.create.side_effect = Exception("API error")
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ with pytest.raises(RuntimeError, match="DashScope embedding failed"):
+ embedder.embed("hello")
+
+
+# ---------------------------------------------------------------------------
+# Text batch embed
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeTextBatch:
+ """Test text mode batch embedding."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_batch_splits_into_chunks_of_10(self, mock_httpx, mock_openai_class):
+ """15 texts should produce 2 API calls (10 + 5)."""
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ # First call: 10 items, second call: 5 items
+ mock_response_1 = MagicMock()
+ mock_response_1.data = [MagicMock(embedding=[0.1 * (i + 1)] * 1024) for i in range(10)]
+ mock_response_1.usage = MagicMock(prompt_tokens=100, total_tokens=100)
+
+ mock_response_2 = MagicMock()
+ mock_response_2.data = [MagicMock(embedding=[0.2 * (i + 1)] * 1024) for i in range(5)]
+ mock_response_2.usage = MagicMock(prompt_tokens=50, total_tokens=50)
+
+ mock_client.embeddings.create.side_effect = [mock_response_1, mock_response_2]
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ results = embedder.embed_batch([f"text-{i}" for i in range(15)])
+
+ assert len(results) == 15
+ assert mock_client.embeddings.create.call_count == 2
+ # Verify first call had 10 texts, second had 5
+ first_call_input = mock_client.embeddings.create.call_args_list[0][1]["input"]
+ assert len(first_call_input) == 10
+ second_call_input = mock_client.embeddings.create.call_args_list[1][1]["input"]
+ assert len(second_call_input) == 5
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_batch_empty_returns_empty(self, mock_httpx, mock_openai_class):
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ results = embedder.embed_batch([])
+ assert results == []
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_batch_single_item(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+
+ mock_embedding = MagicMock()
+ mock_embedding.embedding = [0.5] * 1024
+ mock_response = MagicMock()
+ mock_response.data = [mock_embedding]
+ mock_response.usage = MagicMock(prompt_tokens=3, total_tokens=3)
+ mock_client.embeddings.create.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ results = embedder.embed_batch(["hello"])
+ assert len(results) == 1
+ assert results[0].dense_vector == [0.5] * 1024
+ mock_client.embeddings.create.assert_called_once()
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_batch_error_raises_runtime_error(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+ mock_client.embeddings.create.side_effect = Exception("batch fail")
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ with pytest.raises(RuntimeError, match="DashScope batch embedding failed"):
+ embedder.embed_batch(["a", "b"])
+
+
+# ---------------------------------------------------------------------------
+# Multimodal embed
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeMultimodalEmbed:
+ """Test multimodal mode embed with mocked httpx.Client."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_returns_correct_vector(self, mock_httpx_class, mock_openai):
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "output": {"embeddings": [{"embedding": [0.1] * 768}]},
+ "usage": {"total_tokens": 10, "input_tokens": 10},
+ }
+ mock_client.post.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ result = embedder.embed("hello world")
+ assert result.dense_vector == [0.1] * 768
+ assert result.is_dense
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_sends_multimodal_params(self, mock_httpx_class, mock_openai):
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "output": {"embeddings": [{"embedding": [0.1] * 768}]},
+ "usage": {"total_tokens": 10, "input_tokens": 10},
+ }
+ mock_client.post.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ enable_fusion=True,
+ res_level=2,
+ max_video_frames=16,
+ )
+ embedder.embed("test text")
+
+ call_kwargs = mock_client.post.call_args[1]
+ body = call_kwargs["json"]
+ assert body["model"] == "tongyi-embedding-vision-flash"
+ assert body["input"]["contents"] == [{"text": "test text"}]
+ assert body["parameters"]["enable_fusion"] is True
+ assert body["parameters"]["res_level"] == 2
+ assert body["parameters"]["max_video_frames"] == 16
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_without_optional_params(self, mock_httpx_class, mock_openai):
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "output": {"embeddings": [{"embedding": [0.1] * 768}]},
+ "usage": {"total_tokens": 5, "input_tokens": 5},
+ }
+ mock_client.post.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ embedder.embed("hello")
+
+ call_kwargs = mock_client.post.call_args[1]
+ body = call_kwargs["json"]
+ # dimension is always set (from model default), but optional params should be absent
+ assert "dimension" in body.get("parameters", {})
+ assert "enable_fusion" not in body.get("parameters", {})
+ assert "res_level" not in body.get("parameters", {})
+ assert "max_video_frames" not in body.get("parameters", {})
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_api_error_raises_runtime_error(self, mock_httpx_class, mock_openai):
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+ mock_response = MagicMock()
+ mock_response.raise_for_status.side_effect = Exception("HTTP 500")
+ mock_client.post.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ with pytest.raises(RuntimeError, match="DashScope embedding failed"):
+ embedder.embed("hello")
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_multimodal_url_uses_correct_endpoint(self, mock_httpx_class, mock_openai):
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "output": {"embeddings": [{"embedding": [0.1] * 768}]},
+ "usage": {"total_tokens": 5, "input_tokens": 5},
+ }
+ mock_client.post.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ embedder.embed("test")
+
+ call_args = mock_client.post.call_args
+ url = call_args[0][0] if call_args[0] else call_args[1].get("url")
+ assert "multimodal-embedding" in url
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeAsync:
+ """Test async methods with mocked async clients."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ @patch("openviking.models.embedder.dashscope_embedders.openai.AsyncOpenAI")
+ @pytest.mark.anyio
+ async def test_embed_async_text_mode(self, mock_async_openai_class, mock_httpx, mock_openai):
+ mock_async_client = MagicMock()
+ mock_async_openai_class.return_value = mock_async_client
+
+ mock_embedding = MagicMock()
+ mock_embedding.embedding = [0.3] * 1024
+ mock_response = MagicMock()
+ mock_response.data = [mock_embedding]
+ mock_response.usage = MagicMock(prompt_tokens=8, total_tokens=8)
+ mock_async_client.embeddings.create = AsyncMock(return_value=mock_response)
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ result = await embedder.embed_async("hello async")
+ assert result.dense_vector == [0.3] * 1024
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.AsyncClient")
+ @pytest.mark.anyio
+ async def test_embed_async_multimodal_mode(
+ self, mock_async_httpx_class, mock_httpx, mock_openai
+ ):
+ mock_async_client = MagicMock()
+ mock_async_httpx_class.return_value = mock_async_client
+
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "output": {"embeddings": [{"embedding": [0.4] * 768}]},
+ "usage": {"total_tokens": 12, "input_tokens": 12},
+ }
+ mock_async_client.post = AsyncMock(return_value=mock_response)
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ result = await embedder.embed_async("hello multimodal async")
+ assert result.dense_vector == [0.4] * 768
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ @patch("openviking.models.embedder.dashscope_embedders.openai.AsyncOpenAI")
+ @pytest.mark.anyio
+ async def test_embed_async_text_error_raises_runtime_error(
+ self, mock_async_openai_class, mock_httpx, mock_openai
+ ):
+ mock_async_client = MagicMock()
+ mock_async_openai_class.return_value = mock_async_client
+ mock_async_client.embeddings.create = AsyncMock(side_effect=Exception("async fail"))
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ with pytest.raises(RuntimeError, match="DashScope embedding failed"):
+ await embedder.embed_async("fail text")
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ @patch("openviking.models.embedder.dashscope_embedders.openai.AsyncOpenAI")
+ @pytest.mark.anyio
+ async def test_embed_batch_async_text_mode(
+ self, mock_async_openai_class, mock_httpx, mock_openai
+ ):
+ mock_async_client = MagicMock()
+ mock_async_openai_class.return_value = mock_async_client
+
+ mock_response = MagicMock()
+ mock_response.data = [
+ MagicMock(embedding=[0.1] * 1024),
+ MagicMock(embedding=[0.2] * 1024),
+ ]
+ mock_response.usage = MagicMock(prompt_tokens=20, total_tokens=20)
+ mock_async_client.embeddings.create = AsyncMock(return_value=mock_response)
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ results = await embedder.embed_batch_async(["a", "b"])
+ assert len(results) == 2
+ assert results[0].dense_vector == [0.1] * 1024
+ assert results[1].dense_vector == [0.2] * 1024
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeErrors:
+ """Test error handling across modes."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_text_api_error(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+ mock_client.embeddings.create.side_effect = Exception("connection refused")
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ with pytest.raises(RuntimeError, match="DashScope embedding failed") as exc_info:
+ embedder.embed("hello")
+ assert "connection refused" in str(exc_info.value.__cause__)
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_multimodal_api_error(self, mock_httpx_class, mock_openai):
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+ mock_response = MagicMock()
+ mock_response.raise_for_status.side_effect = Exception("HTTP 503 Service Unavailable")
+ mock_client.post.return_value = mock_response
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ with pytest.raises(RuntimeError, match="DashScope embedding failed") as exc_info:
+ embedder.embed("hello")
+ assert "503" in str(exc_info.value.__cause__)
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_embed_batch_error(self, mock_httpx, mock_openai_class):
+ mock_client = MagicMock()
+ mock_openai_class.return_value = mock_client
+ mock_client.embeddings.create.side_effect = Exception("timeout")
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4", api_key="sk-test", input_type="text"
+ )
+ with pytest.raises(RuntimeError, match="DashScope batch embedding failed"):
+ embedder.embed_batch(["text1", "text2"])
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_multimodal_batch_sends_one_at_a_time(self, mock_httpx_class, mock_openai):
+ """Multimodal batch sends requests one text at a time (no chunking)."""
+ mock_client = MagicMock()
+ mock_httpx_class.return_value = mock_client
+
+ # Each call returns a single embedding
+ responses = []
+ for i in range(3):
+ resp = MagicMock()
+ resp.json.return_value = {
+ "output": {"embeddings": [{"embedding": [float(i)] * 768}]},
+ "usage": {"total_tokens": 5, "input_tokens": 5},
+ }
+ responses.append(resp)
+ mock_client.post.side_effect = responses
+
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ results = embedder.embed_batch(["a", "b", "c"])
+ assert len(results) == 3
+ assert mock_client.post.call_count == 3
+ assert results[0].dense_vector == [0.0] * 768
+ assert results[1].dense_vector == [1.0] * 768
+ assert results[2].dense_vector == [2.0] * 768
+
+
+# ---------------------------------------------------------------------------
+# Multimodal params builder
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeMultimodalParams:
+ """Test _multimodal_params and _multimodal_body helpers."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_params_excludes_none_values(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ params = embedder._multimodal_params()
+ assert "dimension" in params # always set from model default
+ assert "enable_fusion" not in params
+ assert "res_level" not in params
+ assert "max_video_frames" not in params
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_params_includes_all_set_values(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ enable_fusion=True,
+ res_level=3,
+ max_video_frames=8,
+ )
+ params = embedder._multimodal_params()
+ assert params["dimension"] == 768 # default for flash
+ assert params["enable_fusion"] is True
+ assert params["res_level"] == 3
+ assert params["max_video_frames"] == 8
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_body_structure(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="tongyi-embedding-vision-flash",
+ api_key="sk-test",
+ input_type="multimodal",
+ )
+ body = embedder._multimodal_body("some text")
+ assert body["model"] == "tongyi-embedding-vision-flash"
+ assert body["input"]["contents"] == [{"text": "some text"}]
+ assert "parameters" in body
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_body_no_params_when_all_none_except_dimension(self, mock_httpx, mock_openai):
+ """When only dimension is set (from default), parameters dict still exists."""
+ embedder = DashScopeDenseEmbedder(
+ model_name="text-embedding-v4",
+ api_key="sk-test",
+ input_type="multimodal",
+ enable_fusion=None,
+ res_level=None,
+ max_video_frames=None,
+ )
+ body = embedder._multimodal_body("hello")
+ # dimension is always set, so parameters should exist
+ assert "parameters" in body
+ assert body["parameters"]["dimension"] == 1024
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TestDashScopeLifecycle:
+ """Test lifecycle methods."""
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_close_calls_httpx_client_close(self, mock_httpx_class, mock_openai):
+ mock_httpx_client = MagicMock()
+ mock_httpx_class.return_value = mock_httpx_client
+
+ embedder = DashScopeDenseEmbedder(model_name="text-embedding-v4", api_key="sk-test")
+ embedder.close()
+ mock_httpx_client.close.assert_called_once()
+
+ @patch("openviking.models.embedder.dashscope_embedders.openai.OpenAI")
+ @patch("openviking.models.embedder.dashscope_embedders.httpx.Client")
+ def test_get_dimension(self, mock_httpx, mock_openai):
+ embedder = DashScopeDenseEmbedder(
+ model_name="qwen3-vl-embedding",
+ api_key="sk-test",
+ )
+ assert embedder.get_dimension() == 2560