# 云端向量化模块使用说明
  
  ## 概述
  
  本项目新增了基于阿里云 DashScope API 的文本向量化模块，使用 `text-embedding-v4` 模型生成文本向量。
  
  ## 模块说明
  
  ### 1. CloudTextEncoder (`embeddings/cloud_text_encoder.py`)
  
  云端文本向量化编码器，使用阿里云 DashScope API。
  
  **特性：**
  - 单例模式，线程安全
  - 支持单个或批量文本向量化
  - 自动处理 API 调用和错误处理
  - 生成 1024 维向量
  - 支持批处理以避免 API 速率限制
  
  **初始化：**
  ```python
  from embeddings.cloud_text_encoder import CloudTextEncoder
  
  # 方式1：从环境变量读取 API Key
  encoder = CloudTextEncoder()
  
  # 方式2：显式传入 API Key
  encoder = CloudTextEncoder(api_key="sk-xxx")
  
  # 方式3：使用新加坡地域
  encoder = CloudTextEncoder(
      api_key="sk-xxx",
      base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
  )
  ```
  
  **使用示例：**
  ```python
  # 单个文本向量化
  text = "衣服的质量杠杠的"
  embedding = encoder.encode(text)
  print(embedding.shape)  # (1, 1024)
  
  # 批量文本向量化
  texts = ["文本1", "文本2", "文本3"]
  embeddings = encoder.encode(texts)
  print(embeddings.shape)  # (3, 1024)
  
  # 大批量处理（自动分批）
  large_texts = ["文本" + str(i) for i in range(1000)]
  embeddings = encoder.encode_batch(large_texts, batch_size=32)
  print(embeddings.shape)  # (1000, 1024)
  ```
  
  ### 2. 测试脚本 (`scripts/test_cloud_embedding.py`)
  
  测试云端向量化功能，读取 `queries.txt` 前100条数据进行测试。
  
  **功能：**
  - 读取查询文件
  - 逐条发送向量化请求
  - 记录每次请求的发送时间、接收时间和耗时
  - 统计成功率和平均耗时
  
  ## 使用步骤
  
  ### 1. 设置 API Key
  
  首先需要获取阿里云 DashScope API Key：
  - 北京地域：https://help.aliyun.com/zh/model-studio/get-api-key
  - 新加坡地域：使用不同的 API Key
  
  设置环境变量：
  ```bash
  export DASHSCOPE_API_KEY="your-api-key-here"
  ```
  
  或者在项目根目录的 `.env` 文件中添加：
  ```
  DASHSCOPE_API_KEY=your-api-key-here
  ```
  
  ### 2. 安装依赖
  
  确保已安装 OpenAI Python SDK：
  ```bash
  pip install openai
  ```
  
  或者使用项目的 requirements.txt：
  ```bash
  pip install -r requirements.txt
  ```
  
  ### 3. 运行测试脚本
  
  ```bash
  # 在项目根目录下运行
  python scripts/test_cloud_embedding.py
  ```
  
  ### 4. 查看测试结果
  
  测试脚本会输出以下信息：
  ```
  ================================================================================
  Cloud Text Embedding Test - Aliyun DashScope API
  ================================================================================
  
  API Key: sk-xxxxxx...xxxx
  
  Reading queries from: /path/to/queries.txt
  Successfully read 100 queries
  
  Initializing CloudTextEncoder...
  CloudTextEncoder initialized successfully
  
  ================================================================================
  Testing 100 queries (one by one)
  ================================================================================
  
  [  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)
  
  [  2/100] ✓ SUCCESS
    Query: Vintage Denim Jacket
    Send Time:    2025-12-05 10:30:45.789
    Receive Time: 2025-12-05 10:30:46.012
    Duration:     0.223s
    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
  ================================================================================
  ```
  
  ## 注意事项
  
  1. **API 限制**：阿里云 DashScope API 有速率限制，测试脚本在批处理时会添加小延迟以避免触发限制。
  
  2. **成本**：使用云端 API 会产生费用，请注意控制调用量。
  
  3. **网络要求**：需要稳定的网络连接访问阿里云服务。
  
  4. **错误处理**：如果 API 调用失败，编码器会返回零向量作为降级处理，并记录错误日志。
  
  5. **向量维度**：`text-embedding-v4` 模型生成 1024 维向量，如果需要不同维度，请考虑使用其他模型。
  
  ## 地域选择
  
  - **北京地域**（默认）：`https://dashscope.aliyuncs.com/compatible-mode/v1`
  - **新加坡地域**：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
  
  不同地域使用不同的 API Key，请确保匹配。
  
  ## 集成到项目
  
  在项目中使用云端向量化：
  
  ```python
  from embeddings.cloud_text_encoder import CloudTextEncoder
  
  # 初始化编码器（全局单例）
  encoder = CloudTextEncoder()
  
  # 在搜索、索引等模块中使用
  def process_text(text: str):
      embedding = encoder.encode(text)
      # 使用 embedding 进行后续处理
      return embedding
  ```
  
  ## 对比本地编码器
  
  | 特性 | CloudTextEncoder | BgeEncoder (本地) |
  |------|------------------|-------------------|
  | 部署方式 | 云端 API | 本地服务 |
  | 初始成本 | 低（按使用付费） | 高（GPU/CPU 资源） |
  | 运行成本 | 按调用量计费 | 固定资源成本 |
  | 延迟 | 较高（网络往返） | 低（本地处理） |
  | 吞吐量 | 受 API 限制 | 受硬件限制 |
  | 离线使用 | 不支持 | 支持 |
  | 维护成本 | 低 | 需要维护服务 |
  
  ## 故障排除
  
  ### 问题：API Key 未设置
  ```
  ERROR: DASHSCOPE_API_KEY environment variable is not set!
  ```
  **解决**：设置 `DASHSCOPE_API_KEY` 环境变量。
  
  ### 问题：API 调用失败
  ```
  Failed to encode texts via DashScope API: ...
  ```
  **解决**：
  1. 检查网络连接
  2. 验证 API Key 是否正确
  3. 确认 base_url 与 API Key 地域匹配
  4. 检查账户余额
  
  ### 问题：速率限制
  ```
  Rate limit exceeded
  ```
  **解决**：
  1. 增加批处理之间的延迟
  2. 减小 batch_size
  3. 升级 API 套餐
  
  ## 更多信息
  
  - [阿里云模型服务灵积文档](https://help.aliyun.com/zh/model-studio/)
  - [text-embedding-v4 模型说明](https://help.aliyun.com/zh/model-studio/getting-started/models)