DashScope Embedding Server

一个用于调用阿里百练平台API实现文本/图片向量化的Model Context Protocol (MCP)服务器。

功能特性

• 自动识别输入类型：URL（http/https开头）进行图片向量化，其他文本进行文本向量化
• 调用阿里百练平台多模态向量化API
• 返回完整的向量数据和元信息
• 支持文本和图片的统一向量化接口

安装

全局安装（推荐）

npm install -g dashscope-embedding-server

本地安装

cd dashscope-embedding-server
npm install

配置

创建 .env 文件并配置阿里百练平台API Key：

cp .env.example .env

编辑 .env 文件：

DASHSCOPE_API_KEY=your_api_key_here

# 可选：指定使用的模型（默认：multimodal-embedding-v1）
# 可选值：multimodal-embedding-v1, tongyi-embedding-vision-plus 等
DASHSCOPE_MODEL=multimodal-embedding-v1

# 可选：指定输出向量维度（默认：1024）
# multimodal-embedding-v1 支持：[1024, 768]
# tongyi-embedding-vision-plus 支持：[1024, 1536]
DASHSCOPE_DIMENSIONS=1024

多API Key支持：

• 支持配置多个API Key，使用逗号分隔
• 服务器会自动轮询使用不同的API Key
• 示例：DASHSCOPE_API_KEY=key1,key2,key3
• 每次API调用时会按顺序使用下一个API Key，实现负载均衡

获取API Key

1. 访问阿里百练平台：https://dashscope.console.aliyun.com/apiKey
2. 登录阿里云账号
3. 创建API Key
4. 复制API Key到 .env 文件

使用方法

通过npx运行

npx -y dashscope-embedding-server

在MCP Hub中配置

在MCP Hub的配置文件中添加以下配置：

{
  "mcpServers": {
    "dashscope_embedding": {
      "command": "npx",
      "args": ["-y", "dashscope-embedding-server"],
      "env": {
        "DASHSCOPE_API_KEY": "your_api_key_here",
        "DASHSCOPE_MODEL": "multimodal-embedding-v1",
        "DASHSCOPE_DIMENSIONS": "1024"
      }
    }
  }
}

配置说明：

• DASHSCOPE_API_KEY：必填，阿里百练平台API Key
• DASHSCOPE_MODEL：可选，使用的模型名称，默认为 multimodal-embedding-v1
• DASHSCOPE_DIMENSIONS：可选，输出向量维度，默认为 1024

本地运行

npm start

可用工具

dashscope_embedding

调用阿里百练平台API实现文本/图片向量化。自动识别输入类型并返回相应的向量数据。

参数：

• input (string, 必填): 输入内容
  • 如果以 http:// 或 https:// 开头，则认为是图片URL，进行图片向量化
  • 否则认为是文本，进行文本向量化

文本向量化示例：

{
  "input": "这是一个测试文本"
}

图片向量化示例：

{
  "input": "https://example.com/image.jpg"
}

文本向量化返回示例：

{
  "success": true,
  "type": "text",
  "embedding_type": "text",
  "embedding": [-0.026611328125, -0.016571044921875, -0.02227783203125, ...],
  "dimensions": 1024,
  "input": "这是一个测试文本",
  "usage": {
    "input_tokens": 10
  },
  "request_id": "1fff9502-a6c5-9472-9ee1-73930fdd04c5"
}

图片向量化返回示例：

{
  "success": true,
  "type": "image"
  "embedding_type": "image",
  "embedding": [0.051544189453125, 0.007717132568359375, 0.026611328125, ...],
  "dimensions": 1024,
  "input": "https://example.com/image.jpg",
  "usage": {
    "input_tokens": 0,
    "image_tokens": 896
  },
  "request_id": "2abc1234-d5e6-7890-1fg2-84841gee05d6"
}

API详情

模型信息

服务器支持通过环境变量配置不同的嵌入模型，默认使用 multimodal-embedding-v1。

可用的模型：

• multimodal-embedding-v1（默认）
  • 向量维度：1024 或 768
  • 支持类型：文本、图片、视频、多图片
• tongyi-embedding-vision-plus
  • 向量维度：1024 或 1536
  • 支持类型：文本、图片、视频、多图片

API端点

https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

请求格式

{
  "model": "multimodal-embedding-v1",
  "parameters": {
    "text_type": "document",
    "dimensions": 1024
  },
  "input": {
    "contents": [
      {"text": "文本内容"},
      {"image": "图片URL"}
    ]
  }
}

响应格式

{
  "output": {
    "embeddings": [
      {
        "index": 0,
        "embedding": [向量数据],
        "type": "text/image/video"
      }
    ]
  },
  "usage": {
    "input_tokens": 10,
    "image_tokens": 896
  },
  "request_id": "请求ID"
}

使用场景

1. 文本相似度计算

// 获取两个文本的向量
const vector1 = await dashscope_embedding({ input: "苹果" });
const vector2 = await dashscope_embedding({ input: "水果" });

// 计算余弦相似度
const similarity = cosineSimilarity(vector1.embedding, vector2.embedding);

2. 图片相似度搜索

// 获取查询图片的向量
const queryVector = await dashscope_embedding({ 
  input: "https://example.com/query.jpg" 
});

// 与数据库中的图片向量比较
// ... 相似度搜索逻辑

3. 图文检索

// 使用文本查询图片
const textVector = await dashscope_embedding({ 
  input: "一只猫的照片" 
});

// 搜索相似的图片
// ... 向量数据库查询

技术栈

• Node.js >= 18.0.0
• @modelcontextprotocol/sdk ^1.25.2
• axios ^1.6.7

错误处理

常见错误

1. API Key未配置

   错误: DASHSCOPE_API_KEY environment variable is not set
   解决: 在环境变量或MCP Hub配置中设置DASHSCOPE_API_KEY

2. API Key无效

   错误: DashScope API error: 401
   解决: 检查API Key是否正确，是否有访问权限

3. 图片URL无效

   错误: DashScope API error: 400
   解决: 检查图片URL是否可访问，格式是否正确

4. 网络超时

   错误: No response from DashScope API
   解决: 检查网络连接，确认API服务是否正常

错误响应格式

{
  "success": false,
  "error": "错误信息",
  "details": {
    // 详细错误信息
  }
}

注意事项

1. API Key安全

   • 不要将API Key提交到版本控制系统
   • 在生产环境使用环境变量或密钥管理服务
   • 定期轮换API Key

2. 使用限制

   • 遵守阿里百练平台的使用配额
   • 注意API调用频率限制
   • 监控使用量和费用

3. 图片要求

   • 支持常见图片格式（JPG、PNG、GIF等）
   • 图片URL必须公开可访问
   • 注意图片大小限制

4. 向量使用

   • 返回的向量可用于相似度计算、聚类、分类等任务
   • 建议使用余弦相似度计算文本/图片相似度
   • 可以将向量存储到向量数据库（如Milvus、Pinecone等）

性能优化

1. 批量处理

   • 当前版本每次处理单个输入
   • 如需批量处理，可循环调用并考虑添加缓存

2. 缓存策略

   • 对于相同的输入，考虑缓存向量结果
   • 可以使用Redis等缓存服务

3. 异步处理

   • MCP服务器本身支持异步调用
   • 可以在应用层实现批量异步处理

许可证

MIT

相关链接

• 阿里百练平台文档
• 多模态向量化API文档
• API Key管理