npm package: @hamaster/dashscope-embedding-server
Description: DashScope Embedding MCP Server - 提供文本/图片向量化工具，调用阿里百练平台API
Latest version: 1.0.1

# DashScope Embedding Server

一个用于调用阿里百练平台API实现文本/图片向量化的Model Context Protocol (MCP)服务器。

## 功能特性

- 自动识别输入类型：URL（http/https开头）进行图片向量化，其他文本进行文本向量化
- 调用阿里百练平台多模态向量化API
- 返回完整的向量数据和元信息
- 支持文本和图片的统一向量化接口

## 安装

### 全局安装（推荐）

```bash
npm install -g dashscope-embedding-server
```

### 本地安装

```bash
cd dashscope-embedding-server
npm install
```

## 配置

创建 `.env` 文件并配置阿里百练平台API Key：

```bash
cp .env.example .env
```

编辑 `.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运行

```bash
npx -y dashscope-embedding-server
```

### 在MCP Hub中配置

在MCP Hub的配置文件中添加以下配置：

```json
{
  "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`

### 本地运行

```bash
npm start
```

## 可用工具

### dashscope_embedding
调用阿里百练平台API实现文本/图片向量化。自动识别输入类型并返回相应的向量数据。

**参数：**
- `input` (string, 必填): 输入内容
  - 如果以 `http://` 或 `https://` 开头，则认为是图片URL，进行图片向量化
  - 否则认为是文本，进行文本向量化

**文本向量化示例：**
```json
{
  "input": "这是一个测试文本"
}
```

**图片向量化示例：**
```json
{
  "input": "https://example.com/image.jpg"
}
```

**文本向量化返回示例：**
```json
{
  "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"
}
```

**图片向量化返回示例：**
```json
{
  "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
```

### 请求格式
```json
{
  "model": "multimodal-embedding-v1",
  "parameters": {
    "text_type": "document",
    "dimensions": 1024
  },
  "input": {
    "contents": [
      {"text": "文本内容"},
      {"image": "图片URL"}
    ]
  }
}
```

### 响应格式
```json
{
  "output": {
    "embeddings": [
      {
        "index": 0,
        "embedding": [向量数据],
        "type": "text/image/video"
      }
    ]
  },
  "usage": {
    "input_tokens": 10,
    "image_tokens": 896
  },
  "request_id": "请求ID"
}
```

## 使用场景

### 1. 文本相似度计算
```javascript
// 获取两个文本的向量
const vector1 = await dashscope_embedding({ input: "苹果" });
const vector2 = await dashscope_embedding({ input: "水果" });

// 计算余弦相似度
const similarity = cosineSimilarity(vector1.embedding, vector2.embedding);
```

### 2. 图片相似度搜索
```javascript
// 获取查询图片的向量
const queryVector = await dashscope_embedding({ 
  input: "https://example.com/query.jpg" 
});

// 与数据库中的图片向量比较
// ... 相似度搜索逻辑
```

### 3. 图文检索
```javascript
// 使用文本查询图片
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服务是否正常
   ```

### 错误响应格式
```json
{
  "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

## 相关链接

- [阿里百练平台文档](https://help.aliyun.com/zh/dashscope/)
- [多模态向量化API文档](https://help.aliyun.com/zh/dashscope/developer-reference/multimodal-embedding-api)
- [API Key管理](https://dashscope.console.aliyun.com/apiKey)