# 向量化模块和API说明文档

本文档详细说明saas-search项目中的向量化模块架构、API接口、配置方法和使用指南。

## 目录

1. [概述](#概述)
   - 1.1 [向量化模块简介](#11-向量化模块简介)
   - 1.2 [技术选型](#12-技术选型)
   - 1.3 [应用场景](#13-应用场景)

2. [向量化服务架构](#向量化服务架构)
   - 2.1 [本地向量化服务](#21-本地向量化服务)
   - 2.2 [云端向量化服务](#22-云端向量化服务)
   - 2.3 [架构对比](#23-架构对比)

3. [本地向量化服务](#本地向量化服务)
   - 3.1 [服务启动](#31-服务启动)
   - 3.2 [服务配置](#32-服务配置)
   - 3.3 [模型说明](#33-模型说明)

4. [云端向量化服务](#云端向量化服务)
   - 4.1 [阿里云DashScope](#41-阿里云dashscope)
   - 4.2 [API Key配置](#42-api-key配置)
   - 4.3 [使用方式](#43-使用方式)

5. [Embedding API详细说明](#embedding-api详细说明)
   - 5.1 [API概览](#51-api概览)
   - 5.2 [健康检查接口](#52-健康检查接口)
   - 5.3 [文本向量化接口](#53-文本向量化接口)
   - 5.4 [图片向量化接口](#54-图片向量化接口)
   - 5.5 [错误处理](#55-错误处理)

6. [配置说明](#配置说明)
   - 6.1 [服务配置](#61-服务配置)
   - 6.2 [模型配置](#62-模型配置)
   - 6.3 [批处理配置](#63-批处理配置)

7. [客户端集成示例](#客户端集成示例)
   - 7.1 [Python客户端](#71-python客户端)
   - 7.2 [Java客户端](#72-java客户端)
   - 7.3 [cURL示例](#73-curl示例)

8. [性能对比与优化](#性能对比与优化)
   - 8.1 [性能对比](#81-性能对比)
   - 8.2 [成本对比](#82-成本对比)
   - 8.3 [优化建议](#83-优化建议)

9. [故障排查](#故障排查)
   - 9.1 [常见问题](#91-常见问题)
   - 9.2 [日志查看](#92-日志查看)
   - 9.3 [性能调优](#93-性能调优)

10. [附录](#附录)
    - 10.1 [向量维度说明](#101-向量维度说明)
    - 10.2 [模型版本信息](#102-模型版本信息)
    - 10.3 [相关文档](#103-相关文档)

---

## 概述

### 1.1 向量化模块简介

saas-search项目实现了完整的文本和图片向量化能力，支持两种部署方式：

1. **本地向量化服务**：独立部署的微服务，基于本地GPU/CPU运行BGE-M3和CN-CLIP模型
2. **云端向量化服务**：集成阿里云DashScope API，按使用量付费

向量化模块是搜索引擎的核心组件，为语义搜索、图片搜索提供AI驱动的相似度计算能力。

### 1.2 技术选型

| 功能 | 本地服务 | 云端服务 |
|------|---------|---------|
| **文本模型** | BGE-M3 (Xorbits/bge-m3) | text-embedding-v4 |
| **图片模型** | CN-CLIP (ViT-H-14) | - |
| **向量维度** | 1024 | 1024 |
| **服务框架** | FastAPI | 阿里云API |
| **部署方式** | Docker/本地 | 云端API |

### 1.3 应用场景

- **语义搜索**：查询文本向量化，与商品向量计算相似度
- **图片搜索**：商品图片向量化，支持以图搜图
- **混合检索**：BM25 + 向量相似度组合排序
- **多语言搜索**：中英文跨语言语义理解

---

## 向量化服务架构

### 2.1 本地向量化服务

```
┌─────────────────────────────────────────┐
│  Embedding Microservice (FastAPI)       │
│  Port: 6005, Workers: 1                 │
└──────────────┬──────────────────────────┘
               │
       ┌───────┴───────┐
       │               │
┌──────▼──────┐  ┌────▼─────┐
│ BGE-M3      │  │ CN-CLIP  │
│ Text Model  │  │ Image    │
│ (CUDA/CPU)  │  │ Model    │
└─────────────┘  └──────────┘
```

**核心特性**：
- 独立部署，可横向扩展
- GPU加速支持
- 线程安全设计
- 启动时预加载模型

### 2.2 云端向量化服务

```
┌─────────────────────────────────────┐
│  saas-search Main Service          │
│  (uses CloudTextEncoder)            │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  Aliyun DashScope API               │
│  text-embedding-v4                  │
│  (HTTP/REST)                        │
└─────────────────────────────────────┘
```

**核心特性**：
- 无需GPU资源
- 按使用量计费
- 自动扩展
- 低运维成本

### 2.3 架构对比

| 维度 | 本地服务 | 云端服务 |
|------|---------|---------|
| **初始成本** | 高（GPU服务器） | 低（按需付费） |
| **运行成本** | 固定 | 变动（按调用量） |
| **延迟** | <100ms | 300-400ms |
| **吞吐量** | 高（~32 qps） | 中（~2-3 qps） |
| **离线支持** | ✅ | ❌ |
| **维护成本** | 高 | 低 |
| **扩展性** | 手动扩展 | 自动扩展 |
| **适用场景** | 大规模生产环境 | 初期开发/小规模应用 |

---

## 本地向量化服务

### 3.1 服务启动

#### 方式1：使用脚本启动（推荐）

```bash
# 启动向量化服务
./scripts/start_embedding_service.sh
```

脚本特性：
- 自动激活conda环境
- 读取配置文件获取端口
- 单worker模式启动服务

#### 方式2：手动启动

```bash
# 激活环境（推荐使用项目根目录 activate.sh；新机器按需 export CONDA_ROOT）
# 例如你的 conda 是 ~/anaconda3/bin/conda，则 export CONDA_ROOT=$HOME/anaconda3
cd /data/saas-search
source activate.sh

# 启动服务
python -m uvicorn embeddings.server:app \
  --host 0.0.0.0 \
  --port 6005 \
  --workers 1
```

#### 方式3：Docker部署（生产环境）

```bash
# 构建镜像
docker build -t searchengine-embedding:latest .

# 启动容器
docker run -d \
  --name embedding-service \
  --gpus all \
  -p 6005:6005 \
  searchengine-embedding:latest
```

### 3.2 服务配置

配置文件：`embeddings/config.py`

```python
class EmbeddingConfig:
    # 服务配置
    HOST = "0.0.0.0"      # 监听地址
    PORT = 6005           # 监听端口

    # 文本模型 (BGE-M3)
    TEXT_MODEL_DIR = "Xorbits/bge-m3"  # 模型路径/HuggingFace ID
    TEXT_DEVICE = "cuda"               # 设备: "cuda" 或 "cpu"
    TEXT_BATCH_SIZE = 32               # 批处理大小

    # 图片模型 (CN-CLIP)
    IMAGE_MODEL_NAME = "ViT-H-14"      # 模型名称
    IMAGE_DEVICE = None                # None=自动, "cuda", "cpu"
    IMAGE_BATCH_SIZE = 8               # 批处理大小
```

### 3.3 模型说明

#### BGE-M3 文本模型

- **模型ID**: `Xorbits/bge-m3`
- **向量维度**: 1024
- **支持语言**: 中文、英文、多语言（100+）
- **特性**: 强大的语义理解能力，支持长文本
- **部署**: 自动从HuggingFace下载

#### CN-CLIP 图片模型

- **模型**: ViT-H-14 (Chinese CLIP)
- **向量维度**: 1024
- **输入**: 图片URL或本地路径
- **特性**: 中文图文理解，适合电商场景
- **预处理**: 自动下载、缩放、归一化

---

## 云端向量化服务

### 4.1 阿里云DashScope

**服务地址**：
- 北京地域：`https://dashscope.aliyuncs.com/compatible-mode/v1`
- 新加坡地域：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`

**模型信息**：
- **模型名**: `text-embedding-v4`
- **向量维度**: 1024
- **输入限制**: 单次最多2048个文本，每个文本最大8192 token
- **速率限制**: 根据API套餐不同而不同

### 4.2 API Key配置

#### 方式1：环境变量（推荐）

```bash
# 临时设置
export DASHSCOPE_API_KEY="sk-your-api-key-here"

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export DASHSCOPE_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

#### 方式2：.env文件

在项目根目录创建`.env`文件：

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

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

### 4.3 使用方式

```python
from embeddings.cloud_text_encoder import CloudTextEncoder

# 初始化编码器（自动从环境变量读取API Key）
encoder = CloudTextEncoder()

# 单个文本向量化
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 = [f"商品 {i}" for i in range(1000)]
embeddings = encoder.encode_batch(large_texts, batch_size=32)
```

**自定义配置**：

```python
# 使用新加坡地域
encoder = CloudTextEncoder(
    api_key="sk-xxx",
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
)
```

---

## Embedding API详细说明

### 5.1 API概览

本地向量化服务提供RESTful API接口：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/embed/text` | POST | 文本向量化 |
| `/embed/image` | POST | 图片向量化 |

**服务地址**：
- 默认：`http://localhost:6005`
- 生产：`http://<your-server>:6005`

### 5.2 健康检查接口

```http
GET /health
```

**响应示例**：
```json
{
  "status": "ok",
  "text_model_loaded": true,
  "image_model_loaded": true
}
```

**字段说明**：
- `status`: 服务状态，"ok"表示正常
- `text_model_loaded`: 文本模型是否加载成功
- `image_model_loaded`: 图片模型是否加载成功

**cURL示例**：
```bash
curl http://localhost:6005/health
```

### 5.3 文本向量化接口

```http
POST /embed/text
Content-Type: application/json
```

#### 请求格式

**请求体**（JSON数组）：
```json
[
  "衣服的质量杠杠的",
  "Bohemian Maxi Dress",
  "Vintage Denim Jacket"
]
```

**参数说明**：
- 类型：`List[str]`
- 长度：建议≤100（避免超时）
- 单个文本：建议≤512个字符

#### 响应格式

**成功响应**（200 OK）：
```json
[
  [0.1234, -0.5678, 0.9012, ..., 0.3456],  // 1024维向量
  [0.2345, 0.6789, -0.1234, ..., 0.4567],  // 1024维向量
  [0.3456, -0.7890, 0.2345, ..., 0.5678]   // 1024维向量
]
```

**字段说明**：
- 类型：`List[List[float]]`
- 每个向量：1024个浮点数
- 对齐原则：输出数组与输入数组按索引一一对应
- 失败项：返回`null`

**错误示例**：
```json
[
  [0.1234, -0.5678, ...],  // 成功
  null,                     // 失败（空文本或其他错误）
  [0.3456, 0.7890, ...]     // 成功
]
```

#### cURL示例

```bash
# 单个文本
curl -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["测试查询文本"]'

# 批量文本
curl -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["红色连衣裙", "blue jeans", "vintage dress"]'
```

#### Python示例

```python
import requests
import numpy as np

def embed_texts(texts):
    """文本向量化"""
    response = requests.post(
        "http://localhost:6005/embed/text",
        json=texts,
        timeout=30
    )
    response.raise_for_status()
    embeddings = response.json()

    # 转换为numpy数组
    valid_embeddings = [e for e in embeddings if e is not None]
    return np.array(valid_embeddings)

# 使用
texts = ["红色连衣裙", "blue jeans"]
embeddings = embed_texts(texts)
print(f"Shape: {embeddings.shape}")  # (2, 1024)

# 计算相似度
similarity = np.dot(embeddings[0], embeddings[1])
print(f"Similarity: {similarity}")
```

### 5.4 图片向量化接口

```http
POST /embed/image
Content-Type: application/json
```

#### 请求格式

**请求体**（JSON数组）：
```json
[
  "https://example.com/product1.jpg",
  "https://example.com/product2.png",
  "/local/path/to/product3.jpg"
]
```

**参数说明**：
- 类型：`List[str]`
- 支持：HTTP URL或本地文件路径
- 格式：JPG、PNG等常见图片格式
- 长度：建议≤10（图片处理较慢）

#### 响应格式

**成功响应**（200 OK）：
```json
[
  [0.1234, 0.5678, 0.9012, ..., 0.3456],  // 1024维向量
  null,                                   // 失败（图片无效或下载失败）
  [0.3456, 0.7890, 0.2345, ..., 0.5678]   // 1024维向量
]
```

**特性**：
- 自动下载：HTTP URL自动下载图片
- 逐个处理：串行处理（带锁保证线程安全）
- 容错：单个失败不影响其他图片

#### cURL示例

```bash
# 单个图片（URL）
curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/product.jpg"]'

# 多个图片（混合URL和本地路径）
curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/img1.jpg", "/data/images/img2.png"]'
```

#### Python示例

```python
import requests
import numpy as np

def embed_images(image_urls):
    """图片向量化"""
    response = requests.post(
        "http://localhost:6005/embed/image",
        json=image_urls,
        timeout=120  # 图片处理较慢，设置更长超时
    )
    response.raise_for_status()
    embeddings = response.json()

    # 过滤成功的向量化结果
    valid_embeddings = [(url, emb) for url, emb in zip(image_urls, embeddings) if emb is not None]
    return valid_embeddings

# 使用
image_urls = [
    "https://example.com/dress1.jpg",
    "https://example.com/dress2.jpg"
]

results = embed_images(image_urls)
for url, embedding in results:
    print(f"{url}: {len(embedding)} dimensions")
```

### 5.5 错误处理

#### HTTP状态码

| 状态码 | 含义 | 处理方式 |
|--------|------|---------|
| 200 | 成功 | 正常处理响应 |
| 500 | 服务器错误 | 检查服务日志 |
| 503 | 服务不可用 | 模型未加载，检查启动日志 |

#### 常见错误场景

1. **模型未加载**
```json
{
  "detail": "Runtime Error: Text model not loaded"
}
```
**解决**：检查服务启动日志，确认模型加载成功

2. **无效输入**
```json
[null, null]
```
**原因**：输入包含空字符串或None

3. **图片下载失败**
```json
[
  [0.123, ...],
  null  // URL无效或网络问题
]
```
**解决**：检查URL是否可访问

---

## 配置说明

### 6.1 服务配置

编辑 `embeddings/config.py` 修改服务配置：

```python
class EmbeddingConfig:
    # ========== 服务配置 ==========
    HOST = "0.0.0.0"    # 监听所有网卡
    PORT = 6005         # 默认端口
```

**生产环境建议**：
- 使用反向代理（Nginx）处理SSL
- 配置防火墙规则限制访问
- 使用Docker容器隔离

### 6.2 模型配置

#### 文本模型配置

```python
# ========== BGE-M3 文本模型 ==========
TEXT_MODEL_DIR = "Xorbits/bge-m3"  # HuggingFace模型ID
TEXT_DEVICE = "cuda"               # 设备选择
TEXT_BATCH_SIZE = 32               # 批处理大小
```

**DEVICE选择**：
- `"cuda"`: GPU加速（推荐，需要CUDA）
- `"cpu"`: CPU模式（较慢，但兼容性好）

**批处理大小建议**：
- GPU（16GB显存）：32-64
- GPU（8GB显存）：16-32
- CPU：8-16

#### 图片模型配置

```python
# ========== CN-CLIP 图片模型 ==========
IMAGE_MODEL_NAME = "ViT-H-14"      # 模型名称
IMAGE_DEVICE = None                # None=自动检测
IMAGE_BATCH_SIZE = 8               # 批处理大小
```

**IMAGE_DEVICE选择**：
- `None`: 自动检测（推荐）
- `"cuda"`: 强制使用GPU
- `"cpu"`: 强制使用CPU

### 6.3 批处理配置

**批处理大小调优**：

| 场景 | 文本Batch Size | 图片Batch Size | 说明 |
|------|---------------|---------------|------|
| 开发测试 | 16 | 1 | 快速响应 |
| 生产环境（GPU） | 32-64 | 4-8 | 平衡性能 |
| 生产环境（CPU） | 8-16 | 1-2 | 避免内存溢出 |
| 离线批处理 | 128+ | 16+ | 最大化吞吐 |

**批处理建议**：
1. 监控GPU内存使用：`nvidia-smi`
2. 逐步增加batch_size直到OOM
3. 预留20%内存余量

---

## 客户端集成示例

### 7.1 Python客户端

#### 基础客户端类

```python
import requests
from typing import List, Optional
import numpy as np

class EmbeddingServiceClient:
    """向量化服务客户端"""

    def __init__(self, base_url: str = "http://localhost:6005"):
        self.base_url = base_url.rstrip('/')
        self.timeout = 30

    def health_check(self) -> dict:
        """健康检查"""
        response = requests.get(f"{self.base_url}/health", timeout=5)
        response.raise_for_status()
        return response.json()

    def embed_text(self, text: str) -> Optional[List[float]]:
        """单个文本向量化"""
        result = self.embed_texts([text])
        return result[0] if result else None

    def embed_texts(self, texts: List[str]) -> List[Optional[List[float]]]:
        """批量文本向量化"""
        if not texts:
            return []

        response = requests.post(
            f"{self.base_url}/embed/text",
            json=texts,
            timeout=self.timeout
        )
        response.raise_for_status()
        return response.json()

    def embed_image(self, image_url: str) -> Optional[List[float]]:
        """单个图片向量化"""
        result = self.embed_images([image_url])
        return result[0] if result else None

    def embed_images(self, image_urls: List[str]) -> List[Optional[List[float]]]:
        """批量图片向量化"""
        if not image_urls:
            return []

        response = requests.post(
            f"{self.base_url}/embed/image",
            json=image_urls,
            timeout=120  # 图片处理需要更长时间
        )
        response.raise_for_status()
        return response.json()

    def embed_texts_to_numpy(self, texts: List[str]) -> Optional[np.ndarray]:
        """批量文本向量化，返回numpy数组"""
        embeddings = self.embed_texts(texts)
        valid_embeddings = [e for e in embeddings if e is not None]
        if not valid_embeddings:
            return None
        return np.array(valid_embeddings, dtype=np.float32)

# 使用示例
if __name__ == "__main__":
    client = EmbeddingServiceClient()

    # 健康检查
    health = client.health_check()
    print(f"Service status: {health}")

    # 文本向量化
    texts = ["红色连衣裙", "blue jeans", "vintage dress"]
    embeddings = client.embed_texts_to_numpy(texts)
    print(f"Embeddings shape: {embeddings.shape}")

    # 计算相似度
    from sklearn.metrics.pairwise import cosine_similarity
    similarities = cosine_similarity(embeddings)
    print(f"Similarity matrix:\n{similarities}")
```

#### 高级用法：异步客户端

```python
import aiohttp
import asyncio
from typing import List, Optional

class AsyncEmbeddingClient:
    """异步向量化服务客户端"""

    def __init__(self, base_url: str = "http://localhost:6005"):
        self.base_url = base_url.rstrip('/')
        self.session: Optional[aiohttp.ClientSession] = None

    async def __aenter__(self):
        self.session = aiohttp.ClientSession()
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        if self.session:
            await self.session.close()

    async def embed_texts(self, texts: List[str]) -> List[Optional[List[float]]]:
        """异步批量文本向量化"""
        if not texts:
            return []

        if not self.session:
            raise RuntimeError("Client not initialized. Use 'async with'.")

        async with self.session.post(
            f"{self.base_url}/embed/text",
            json=texts,
            timeout=aiohttp.ClientTimeout(total=30)
        ) as response:
            response.raise_for_status()
            return await response.json()

# 使用示例
async def main():
    async with AsyncEmbeddingClient() as client:
        texts = ["text1", "text2", "text3"]
        embeddings = await client.embed_texts(texts)
        print(f"Got {len(embeddings)} embeddings")

asyncio.run(main())
```

### 7.2 Java客户端

#### 基础客户端类

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ArrayNode;

public class EmbeddingServiceClient {
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private final String baseUrl;

    public EmbeddingServiceClient(String baseUrl) {
        this.baseUrl = baseUrl.replaceAll("/$", "");
        this.httpClient = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
        this.objectMapper = new ObjectMapper();
    }

    /**
     * 健康检查
     */
    public HealthStatus healthCheck() throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/health"))
            .timeout(Duration.ofSeconds(5))
            .GET()
            .build();

        HttpResponse<String> response = httpClient.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        JsonNode json = objectMapper.readTree(response.body());
        return new HealthStatus(
            json.get("status").asText(),
            json.get("text_model_loaded").asBoolean(),
            json.get("image_model_loaded").asBoolean()
        );
    }

    /**
     * 批量文本向量化
     */
    public List<float[]> embedTexts(List<String> texts) throws Exception {
        // 构建请求体
        ArrayNode requestBody = objectMapper.createArrayNode();
        for (String text : texts) {
            requestBody.add(text);
        }

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/embed/text"))
            .header("Content-Type", "application/json")
            .timeout(Duration.ofSeconds(30))
            .POST(HttpRequest.BodyPublishers.ofString(
                objectMapper.writeValueAsString(requestBody)
            ))
            .build();

        HttpResponse<String> response = httpClient.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() != 200) {
            throw new RuntimeException("API error: " + response.body());
        }

        // 解析响应
        JsonNode root = objectMapper.readTree(response.body());
        List<float[]> embeddings = new java.util.ArrayList<>();

        for (JsonNode item : root) {
            if (item.isNull()) {
                embeddings.add(null);
            } else {
                float[] vector = objectMapper.treeToValue(item, float[].class);
                embeddings.add(vector);
            }
        }

        return embeddings;
    }

    /**
     * 计算余弦相似度
     */
    public static float cosineSimilarity(float[] v1, float[] v2) {
        if (v1.length != v2.length) {
            throw new IllegalArgumentException("Vectors must be same length");
        }

        float dotProduct = 0.0f;
        float norm1 = 0.0f;
        float norm2 = 0.0f;

        for (int i = 0; i < v1.length; i++) {
            dotProduct += v1[i] * v2[i];
            norm1 += v1[i] * v1[i];
            norm2 += v2[i] * v2[i];
        }

        return (float) (dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2)));
    }

    // 健康状态数据类
    public static class HealthStatus {
        public final String status;
        public final boolean textModelLoaded;
        public final boolean imageModelLoaded;

        public HealthStatus(String status, boolean textModelLoaded, boolean imageModelLoaded) {
            this.status = status;
            this.textModelLoaded = textModelLoaded;
            this.imageModelLoaded = imageModelLoaded;
        }

        @Override
        public String toString() {
            return String.format("HealthStatus{status='%s', textModelLoaded=%b, imageModelLoaded=%b}",
                status, textModelLoaded, imageModelLoaded);
        }
    }

    // 使用示例
    public static void main(String[] args) throws Exception {
        EmbeddingServiceClient client = new EmbeddingServiceClient("http://localhost:6005");

        // 健康检查
        HealthStatus health = client.healthCheck();
        System.out.println("Health: " + health);

        // 文本向量化
        List<String> texts = List.of("红色连衣裙", "blue jeans", "vintage dress");
        List<float[]> embeddings = client.embedTexts(texts);

        System.out.println("Got " + embeddings.size() + " embeddings");
        for (int i = 0; i < embeddings.size(); i++) {
            System.out.println("Embedding " + i + " dimensions: " +
                (embeddings.get(i) != null ? embeddings.get(i).length : "null"));
        }

        // 计算相似度
        if (embeddings.get(0) != null && embeddings.get(1) != null) {
            float similarity = cosineSimilarity(embeddings.get(0), embeddings.get(1));
            System.out.println("Similarity between text 0 and 1: " + similarity);
        }
    }
}
```

**Maven依赖**（`pom.xml`）：

```xml
<dependencies>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.15.2</version>
    </dependency>
</dependencies>
```

### 7.3 cURL示例

#### 健康检查

```bash
curl http://localhost:6005/health
```

#### 文本向量化

```bash
# 单个文本
curl -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["衣服的质量杠杠的"]' \
  | jq '.[0][0:10]'  # 打印前10维

# 批量文本
curl -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["红色连衣裙", "blue jeans", "vintage dress"]' \
  | jq '. | length'  # 检查返回数量
```

#### 图片向量化

```bash
# URL图片
curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/product.jpg"]' \
  | jq '.[0][0:5]'

# 本地图片
curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["/data/images/product.jpg"]'
```

#### 错误处理示例

```bash
# 检查服务状态
if ! curl -f http://localhost:6005/health > /dev/null 2>&1; then
    echo "Embedding service is not healthy!"
    exit 1
fi

# 调用API并检查错误
response=$(curl -s -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["test query"]')

if echo "$response" | jq -e '.[0] == null' > /dev/null; then
    echo "Embedding failed!"
    echo "$response"
    exit 1
fi

echo "Embedding succeeded!"
```

---

## 性能对比与优化

### 8.1 性能对比

#### 本地服务性能

| 操作 | 硬件配置 | 延迟 | 吞吐量 |
|------|---------|------|--------|
| 文本向量化（单个） | GPU (RTX 3090) | ~80ms | ~12 qps |
| 文本向量化（批量32） | GPU (RTX 3090) | ~2.5s | ~256 qps |
| 文本向量化（单个） | CPU (16核) | ~500ms | ~2 qps |
| 图片向量化（单个） | GPU (RTX 3090) | ~150ms | ~6 qps |
| 图片向量化（批量4） | GPU (RTX 3090) | ~600ms | ~6 qps |

#### 云端服务性能

| 操作 | 指标 | 值 |
|------|------|-----|
| 文本向量化（单个） | 延迟 | 300-400ms |
| 文本向量化（批量） | 吞吐量 | ~2-3 qps |
| API限制 | 速率限制 | 取决于套餐 |
| 可用性 | SLA | 99.9% |

### 8.2 成本对比

#### 本地服务成本

| 配置 | 硬件成本（月） | 电费（月） | 总成本（月） |
|------|--------------|-----------|------------|
| GPU服务器 (RTX 3090) | ¥3000 | ¥500 | ¥3500 |
| GPU服务器 (A100) | ¥8000 | ¥800 | ¥8800 |
| CPU服务器（16核） | ¥800 | ¥200 | ¥1000 |

#### 云端服务成本

阿里云DashScope定价（参考）：

| 套餐 | 价格 | 调用量 | 适用场景 |
|------|------|--------|---------|
| 按量付费 | ¥0.0007/1K tokens | 无限制 | 测试/小规模 |
| 基础版 | ¥100/月 | 1M tokens | 小规模应用 |
| 专业版 | ¥500/月 | 10M tokens | 中等规模 |
| 企业版 | 定制 | 无限制 | 大规模 |

**成本计算示例**：

假设每天10万次搜索，每次查询平均10个token：
- 日调用量：1M tokens
- 月调用量：30M tokens
- 月成本：30 × 0.7 = ¥21（按量付费）

### 8.3 优化建议

#### 本地服务优化

1. **GPU利用率优化**
```python
# 增加批处理大小
TEXT_BATCH_SIZE = 64  # 从32增加到64
```

2. **模型量化**
```python
# 使用半精度浮点数（节省显存）
import torch
model = model.half()  # FP16
```

3. **预热模型**
```python
# 服务启动后预热
@app.on_event("startup")
async def warmup():
    _text_model.encode(["warmup"], device="cuda")
```

4. **连接池优化**
```python
# uvicorn配置
--workers 1 \           # 单worker（GPU模型限制）
--backlog 2048 \        # 增加连接队列
--limit-concurrency 32  # 限制并发数
```

#### 云端服务优化

1. **批量合并**
```python
# 累积多个请求后批量调用
class BatchEncoder:
    def __init__(self, batch_size=32, timeout=0.1):
        self.batch_size = batch_size
        self.timeout = timeout
        self.queue = []

    async def encode(self, text: str):
        # 等待批量积累
        future = asyncio.Future()
        self.queue.append((text, future))

        if len(self.queue) >= self.batch_size:
            self._flush()

        return await future
```

2. **本地缓存**
```python
import hashlib
import pickle

class CachedEncoder:
    def __init__(self, cache_file="embedding_cache.pkl"):
        self.cache = self._load_cache(cache_file)

    def encode(self, text: str):
        key = hashlib.md5(text.encode()).hexdigest()
        if key in self.cache:
            return self.cache[key]

        embedding = self._call_api(text)
        self.cache[key] = embedding
        return embedding
```

3. **降级策略**
```python
class HybridEncoder:
    def __init__(self):
        self.cloud_encoder = CloudTextEncoder()
        self.local_encoder = None  # 按需加载

    def encode(self, text: str):
        try:
            return self.cloud_encoder.encode(text)
        except Exception as e:
            logger.warning(f"Cloud API failed: {e}, falling back to local")
            if not self.local_encoder:
                self.local_encoder = BgeEncoder()
            return self.local_encoder.encode(text)
```

---

## 故障排查

### 9.1 常见问题

#### 问题1：服务无法启动

**症状**：
```bash
$ ./scripts/start_embedding_service.sh
Error: Port 6005 already in use
```

**解决**：
```bash
# 检查端口占用
lsof -i :6005

# 杀死占用进程
kill -9 <PID>

# 或者修改配置文件中的端口
# embeddings/config.py: PORT = 6006
```

#### 问题2：CUDA Out of Memory

**症状**：
```
RuntimeError: CUDA out of memory. Tried to allocate 2.00 GiB
```

**解决**：
```python
# 减小批处理大小
TEXT_BATCH_SIZE = 16  # 从32减少到16

# 或者使用CPU模式
TEXT_DEVICE = "cpu"
```

#### 问题3：模型下载失败

**症状**：
```
OSError: Can't load tokenizer for 'Xorbits/bge-m3'
```

**解决**：
```bash
# 手动下载模型
huggingface-cli download Xorbits/bge-m3

# 或使用镜像
export HF_ENDPOINT=https://hf-mirror.com
```

#### 问题4：云端API Key无效

**症状**：
```
ERROR: DASHSCOPE_API_KEY environment variable is not set!
```

**解决**：
```bash
# 设置环境变量
export DASHSCOPE_API_KEY="sk-your-key"

# 验证
echo $DASHSCOPE_API_KEY
```

#### 问题5：API速率限制

**症状**：
```
Rate limit exceeded. Please try again later.
```

**解决**：
```python
# 添加延迟
import time
for batch in batches:
    embeddings = encoder.encode_batch(batch)
    time.sleep(0.1)  # 每批之间延迟100ms
```

### 9.2 日志查看

#### 服务日志

```bash
# 查看实时日志
./scripts/start_embedding_service.sh 2>&1 | tee embedding.log

# 或使用systemd（如果配置了服务）
journalctl -u embedding-service -f
```

#### Python应用日志

```python
import logging

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

# 使用
logger.info("Encoding texts...")
logger.error("Encoding failed: %s", str(e))
```

#### GPU监控

```bash
# 实时监控GPU使用
watch -n 1 nvidia-smi

# 查看详细信息
nvidia-smi --query-gpu=timestamp,name,temperature.gpu,utilization.gpu,utilization.memory,memory.total,memory.used,memory.free --format=csv
```

### 9.3 性能调优

#### 性能分析

```python
import time
import numpy as np

def benchmark_encoder(encoder, texts, iterations=100):
    """性能基准测试"""
    times = []

    for i in range(iterations):
        start = time.time()
        embeddings = encoder.encode(texts)
        end = time.time()
        times.append(end - start)

    times = np.array(times)
    print(f"Mean: {times.mean():.3f}s")
    print(f"Std:  {times.std():.3f}s")
    print(f"Min:  {times.min():.3f}s")
    print(f"Max:  {times.max():.3f}s")
    print(f"QPS:  {len(texts) / times.mean():.2f}")

# 使用
benchmark_encoder(encoder, texts=["test"] * 32, iterations=100)
```

#### 内存分析

```bash
# Python内存分析
pip install memory_profiler

# 在代码中添加
from memory_profiler import profile

@profile
def encode_batch(texts):
    return encoder.encode(texts)

# 运行
python -m memory_profiler script.py
```

---

## 附录

### 10.1 向量维度说明

#### 为什么是1024维？

1. **表达能力**：1024维可以捕捉丰富的语义信息
2. **计算效率**：维度适中，计算速度快
3. **存储平衡**：向量大小合理（每个向量约4KB）
4. **模型选择**：BGE-M3和text-embedding-v4都使用1024维

#### 向量存储计算

```
单个向量大小 = 1024 × 4字节（FP32） = 4KB
100万向量大小 = 4KB × 1,000,000 = 4GB
1000万向量大小 = 4KB × 10,000,000 = 40GB
```

### 10.2 模型版本信息

#### BGE-M3

- **HuggingFace ID**: `Xorbits/bge-m3`
- **论文**: [BGE-M3: Multi-Functionality, Multi-Linguality, Multi-Granularity Text Embeddings Through Self-Knowledge Distillation](https://arxiv.org/abs/2402.03616)
- **GitHub**: https://github.com/FlagOpen/FlagEmbedding
- **特性**：
  - 支持100+种语言
  - 最大支持8192 token长度
  - 丰富的语义表达能力

#### CN-CLIP

- **模型**: ViT-H-14
- **论文**: [Chinese CLIP: Contrastive Language-Image Pretraining in Chinese](https://arxiv.org/abs/2211.01935)
- **GitHub**: https://github.com/OFA-Sys/Chinese-CLIP
- **特性**：
  - 中文图文理解
  - 支持图片检索和文本检索
  - 适合电商场景

#### Aliyun text-embedding-v4

- **提供商**: 阿里云DashScope
- **文档**: https://help.aliyun.com/zh/model-studio/getting-started/models
- **特性**：
  - 云端API，无需部署
  - 高可用性（99.9% SLA）
  - 自动扩展

### 10.3 相关文档

#### 项目文档

- **搜索API对接指南**: `docs/搜索API对接指南.md`
- **索引字段说明**: `docs/索引字段说明v2.md`
- **系统设计文档**: `docs/系统设计文档.md`
- **CLAUDE项目指南**: `CLAUDE.md`

#### 外部参考

- **BGE-M3官方文档**: https://github.com/FlagOpen/FlagEmbedding/tree/master/BGE_M3
- **阿里云DashScope**: https://help.aliyun.com/zh/model-studio/
- **Elasticsearch向量搜索**: https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html
- **FastAPI文档**: https://fastapi.tiangolo.com/

#### 测试脚本

```bash
# 本地向量化服务测试
./scripts/test_embedding_service.sh

# 云端向量化服务测试
python scripts/test_cloud_embedding.py

# 性能基准测试
python scripts/benchmark_embeddings.py
```

---

## 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|---------|
| v1.0 | 2025-12-23 | 初始版本，完整的向量化模块文档 |

---

## 联系方式

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

**项目仓库**: `/data/saas-search`

**相关文档目录**: `docs/`