# TODO

现在，跟自己 cn_clip 预估的结果，有差别：
这个比较接近： 可能是预处理逻辑有些不一样。
https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg
normlize后的结果：
0.046295166015625,0.012847900390625,-0.0299530029296875,-0.01629638671875,0.01708984375,0.00487518310546875,0.01284027099609375,0.01348876953125,0.04617632180452347, 0.012860896065831184, -0.030133124440908432, -0.0162516962736845, 
0.04617632180452347, 0.012860896065831184, -0.030133124440908432, -0.0162516962736845, 0.01708567887544632, 0.005110889207571745

以下两个，差别非常大，感觉不是一个模型：
https://aisearch.cdn.bcebos.com/fileManager/GtB5doGAr1skTx38P7fb7Q/182.jpg?authorization=bce-auth-v1%2F7e22d8caf5af46cc9310f1e3021709f3%2F2025-12-30T04%3A45%3A38Z%2F86400%2Fhost%2Ffe222039926cb7ff593021af40268c782b8892598114e24773d0c1bfc976a8df
https://oss.essa.cn/2e353867-7496-4d4e-a7c8-0af50f49f6eb.jpg?x-oss-process=image/resize,m_lfit,w_2048,h_2048

curl -X POST "http://120.76.41.98:5000/embedding/generate_image_embeddings"      -H "Content-Type: application/json"      -d '[
         {
             "id": "test_1",
             "pic_url": "https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"
         }
     ]'
	 


# CN-CLIP 编码服务

## 模块说明

CN-CLIP 编码服务基于 [clip-as-service](https://github.com/jina-ai/clip-as-service) 提供中文 CLIP 模型的文本和图像编码功能。服务使用 gRPC 协议，支持批量编码，返回固定维度的向量表示。

### 功能特性

- 文本编码：将中文文本编码为向量
- 图像编码：将图像（本地文件或远程 URL）编码为向量
- 混合编码：同时编码文本和图像
- 批量处理：支持批量编码，提高效率

### 技术架构

- **框架**: clip-as-service (基于 Jina)
- **模型**: CN-CLIP/ViT-L-14-336（默认）
- **协议**: gRPC（默认，官方推荐）
- **运行时**: PyTorch

## 启动服务

### 基本用法

```bash
./scripts/start_cnclip_service.sh
```

### 启动参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--port PORT` | 服务端口 | 51000 |
| `--device DEVICE` | 设备类型：cuda 或 cpu | 自动检测 |
| `--batch-size SIZE` | 批处理大小 | 32 |
| `--num-workers NUM` | 预处理线程数 | 4 |
| `--dtype TYPE` | 数据类型：float16 或 float32 | float16 |
| `--model-name NAME` | 模型名称 | CN-CLIP/ViT-L-14-336 |
| `--replicas NUM` | 副本数 | 1 |

### 示例

```bash
# 使用默认配置启动
./scripts/start_cnclip_service.sh

# 指定端口和设备
./scripts/start_cnclip_service.sh --port 52000 --device cpu

# 使用其他模型
./scripts/start_cnclip_service.sh --model-name CN-CLIP/ViT-H-14
```

### 停止服务

```bash
./scripts/stop_cnclip_service.sh
```

## API 接口说明

### Python 客户端

服务使用 gRPC 协议，必须使用 Python 客户端：

```python
from clip_client import Client

# 创建客户端（使用 grpc:// 协议）
c = Client('grpc://localhost:51000')
```

### 编码接口

#### 1. 文本编码

```python
from clip_client import Client

c = Client('grpc://localhost:51000')

# 编码单个文本
result = c.encode(['这是测试文本'])
print(result.shape)  # (1, 1024)

# 编码多个文本
result = c.encode(['文本1', '文本2', '文本3'])
print(result.shape)  # (3, 1024)
```

#### 2. 图像编码

```python
# 编码远程图像 URL
result = c.encode(['https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg'])
print(result.shape)  # (1, 1024)

# 编码本地图像文件
result = c.encode(['/path/to/image.jpg'])
print(result.shape)  # (1, 1024)
```

#### 3. 混合编码

```python
# 同时编码文本和图像
result = c.encode([
    '这是文本',
    'https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg',
    '另一个文本'
])
print(result.shape)  # (3, 1024)
```

### 返回格式

- **类型**: `numpy.ndarray`
- **形状**: `(N, 1024)`，其中 N 是输入数量
- **数据类型**: `float32`
- **维度**: 1024（CN-CLIP 模型的 embedding 维度）

### 支持的模型

| 模型名称 | 说明 | 推荐场景 |
|---------|------|---------|
| `CN-CLIP/ViT-B-16` | 基础版本，速度快 | 对速度要求高的场景 |
| `CN-CLIP/ViT-L-14` | 平衡版本 | 通用场景 |
| `CN-CLIP/ViT-L-14-336` | 高分辨率版本（默认） | 需要处理高分辨率图像 |
| `CN-CLIP/ViT-H-14` | 大型版本，精度高 | 对精度要求高的场景 |
| `CN-CLIP/RN50` | ResNet-50 版本 | 兼容性场景 |

## 测试

运行测试脚本：

```bash
./scripts/test_cnclip_service.sh
```

测试脚本会验证：
- 文本编码功能
- 图像编码功能（远程 URL）
- 混合编码功能

每个测试会显示 embedding 的维度和前 20 个数字。

## 查看日志

```bash
tail -f /data/tw/saas-search/logs/cnclip_service.log
```

## 常见问题

### 1. 服务启动失败

- 检查端口是否被占用：`lsof -i :51000`
- 检查 conda 环境是否正确激活
- 查看日志文件获取详细错误信息

### 2. 客户端连接失败

确保使用正确的协议：

```python
# 正确：使用 grpc://
c = Client('grpc://localhost:51000')

# 错误：不要使用 http://
# c = Client('http://localhost:51000')  # 会失败
```

### 3. 编码失败

- 检查服务是否正常运行
- 检查输入格式是否正确
- 查看服务日志排查错误

### 4. 依赖安装

确保已安装必要的依赖：

```bash
pip install clip-client
```

服务端依赖会在启动脚本中自动检查。