# 云端向量化模块 - 更新说明

## 📝 概述

本次更新为 SearchEngine 项目添加了基于阿里云 DashScope API 的云端文本向量化功能，使用 `text-embedding-v4` 模型。

## 🎯 主要功能

1. **CloudTextEncoder** - 云端文本向量化编码器
   - 单例模式，线程安全
   - 支持单个/批量文本向量化
   - 自动错误处理和降级
   - 生成 1024 维向量

2. **测试脚本** - 使用 queries.txt 测试向量化
   - 读取前 100 条查询
   - 记录每次请求的时间和耗时
   - 统计成功率和性能指标

3. **示例代码** - 展示如何使用模块
   - 单个文本向量化
   - 批量处理
   - 相似度计算

## 📁 文件结构

```
SearchEngine/
├── embeddings/
│   ├── cloud_text_encoder.py          # 云端向量化编码器（新增）
│   ├── text_encoder.py                # 本地编码器（现有）
│   └── ...
├── scripts/
│   ├── test_cloud_embedding.py        # 测试脚本（新增）
│   └── ...
├── examples/
│   └── cloud_embedding_example.py     # 示例代码（新增）
├── docs/
│   ├── cloud_embedding_usage.md       # 详细文档（新增）
│   └── cloud_embedding_quickstart.md  # 快速入门（新增）
├── data_crawling/
│   └── queries.txt                    # 测试数据
├── requirements.txt                    # 已添加 openai>=1.0.0
└── CLOUD_EMBEDDING_README.md          # 本文档（新增）
```

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install openai
```

或使用项目 requirements：
```bash
pip install -r requirements.txt
```

### 2. 设置 API Key

```bash
export DASHSCOPE_API_KEY="sk-your-api-key-here"
```

获取 API Key：https://help.aliyun.com/zh/model-studio/get-api-key

### 3. 运行测试

```bash
# 测试向量化（使用 queries.txt 前 100 条）
python scripts/test_cloud_embedding.py

# 运行示例代码
python examples/cloud_embedding_example.py
```

## 📖 使用方法

### 基础使用

```python
from embeddings.cloud_text_encoder import CloudTextEncoder

# 初始化编码器
encoder = CloudTextEncoder()

# 单个文本向量化
embedding = encoder.encode("衣服的质量杠杠的")
print(embedding.shape)  # (1, 1024)

# 批量向量化
embeddings = encoder.encode(["文本1", "文本2", "文本3"])
print(embeddings.shape)  # (3, 1024)
```

### 批量处理

```python
# 大批量自动分批处理
texts = [f"商品 {i}" for i in range(1000)]
embeddings = encoder.encode_batch(texts, batch_size=32)
```

## 🧪 测试脚本

测试脚本 `scripts/test_cloud_embedding.py` 功能：

✅ 读取 `data_crawling/queries.txt` 前 100 条查询  
✅ 逐条发送向量化请求  
✅ 记录每次请求的发送时间、接收时间、耗时  
✅ 输出向量维度和内容  
✅ 统计成功率、平均耗时、吞吐量  

### 测试输出示例

```
================================================================================
Cloud Text Embedding Test - Aliyun DashScope API
================================================================================

[  1/100] ✓ SUCCESS
  Query: Bohemian Maxi Dress
  Send Time:    2025-12-05 10:30:45.123
  Receive Time: 2025-12-05 10:30:45.456
  Duration:     0.333s
  Embedding Shape: (1, 1024)

...

================================================================================
Test Summary
================================================================================
Total Queries:     100
Successful:        100
Failed:            0
Success Rate:      100.0%
Total Time:        35.123s
Total API Time:    32.456s
Average Duration:  0.325s per query
Throughput:        2.85 queries/second
================================================================================
```

## 📊 性能特点

- **向量维度**：1024
- **平均延迟**：300-400ms/请求
- **吞吐量**：~2-3 queries/秒（单线程）
- **错误处理**：自动降级到零向量
- **批处理**：支持自动分批和速率控制

## 🔧 接口说明

### CloudTextEncoder API

#### 初始化

```python
CloudTextEncoder(api_key=None, base_url=None)
```

参数：
- `api_key` (str, optional): API Key，默认从环境变量读取
- `base_url` (str, optional): API 端点，默认北京地域

#### encode()

```python
encode(sentences, normalize_embeddings=True, device='cpu', batch_size=32)
```

参数：
- `sentences` (str or List[str]): 单个文本或文本列表
- `normalize_embeddings` (bool): 是否归一化（API 自动处理）
- `device` (str): 设备参数（兼容性参数，云端 API 忽略）
- `batch_size` (int): 批处理大小

返回：
- `np.ndarray`: 形状为 (n, 1024) 的 numpy 数组

#### encode_batch()

```python
encode_batch(texts, batch_size=32, device='cpu')
```

参数：
- `texts` (List[str]): 文本列表
- `batch_size` (int): 批处理大小
- `device` (str): 设备参数（兼容性参数）

返回：
- `np.ndarray`: 向量矩阵

## 📚 文档

- **快速入门**：`docs/cloud_embedding_quickstart.md`
- **详细文档**：`docs/cloud_embedding_usage.md`
- **示例代码**：`examples/cloud_embedding_example.py`

## ⚠️ 注意事项

1. **API Key 管理**：妥善保管 API Key，不要提交到代码仓库
2. **成本控制**：云端 API 按使用量计费，注意控制调用次数
3. **速率限制**：注意 API 速率限制，测试脚本已添加延迟
4. **网络依赖**：需要稳定的网络连接
5. **错误处理**：API 失败时会返回零向量，请检查日志

## 🆚 对比本地编码器

| 特性 | CloudTextEncoder | BgeEncoder (本地) |
|------|------------------|-------------------|
| 部署方式 | 云端 API | 本地服务 |
| 初始成本 | 低 | 高（GPU/CPU） |
| 运行成本 | 按使用付费 | 固定 |
| 延迟 | ~300-400ms | <100ms |
| 离线使用 | ❌ | ✅ |
| 维护成本 | 低 | 需要维护 |
| 扩展性 | 自动扩展 | 手动扩展 |

## 🔄 集成建议

### 选择使用场景

**使用 CloudTextEncoder（云端）：**
- 初期开发和测试
- 查询量不大的应用
- 不需要离线支持
- 希望降低运维成本

**使用 BgeEncoder（本地）：**
- 大规模生产环境
- 需要低延迟
- 离线使用场景
- 查询量非常大

### 混合使用

```python
# 配置文件中选择编码器类型
ENCODER_TYPE = os.getenv("ENCODER_TYPE", "local")  # local or cloud

if ENCODER_TYPE == "cloud":
    from embeddings.cloud_text_encoder import CloudTextEncoder
    encoder = CloudTextEncoder()
else:
    from embeddings.text_encoder import BgeEncoder
    encoder = BgeEncoder()

# 使用统一接口
embeddings = encoder.encode(texts)
```

## 🐛 故障排查

### 问题 1：API Key 未设置
```bash
export DASHSCOPE_API_KEY="sk-your-key"
```

### 问题 2：网络连接失败
- 检查网络连接
- 验证 base_url 是否正确
- 确认防火墙设置

### 问题 3：速率限制
- 减小 batch_size
- 增加请求间隔
- 升级 API 套餐

### 问题 4：返回零向量
- 检查日志中的错误信息
- 验证 API Key 是否有效
- 确认账户余额

## 🎓 示例代码

查看 `examples/cloud_embedding_example.py` 了解完整示例：
- 单个/批量文本向量化
- 相似度计算
- 错误处理

## 📞 支持

- 项目文档：`docs/` 目录
- 阿里云文档：https://help.aliyun.com/zh/model-studio/
- API 文档：https://help.aliyun.com/zh/model-studio/getting-started/models

## ✅ 验证清单

完成以下步骤确认模块正常工作：

- [ ] 安装了 openai 包
- [ ] 设置了 DASHSCOPE_API_KEY 环境变量
- [ ] 运行测试脚本成功
- [ ] 查看了示例代码
- [ ] 阅读了文档

## 📅 更新日期

2025-12-05

## 👨‍💻 维护

如有问题或建议，请联系项目维护者。