docs/CNCLIP_SERVICE.md

# CN-CLIP 编码服务使用指南
## 简介
本服务基于 [clip-as-service](https://github.com/jina-ai/clip-as-service) 提供 CN-CLIP 模型的文本和图像编码功能。
## 启动服务
```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-H-14）
- `--replicas NUM`: 副本数（默认：1）
### 示例
```bash
# 使用默认配置启动
./scripts/start_cnclip_service.sh
# 指定端口和设备
./scripts/start_cnclip_service.sh --port 52000 --device cpu
# 调整批处理大小
./scripts/start_cnclip_service.sh --batch-size 16 --dtype float32
```
## 停止服务
```bash
./scripts/stop_cnclip_service.sh
```
## 使用 API
### 编码文本
```bash
curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d '{
       "data": [
         {"text": "这是一个测试文本"},
         {"text": "另一个文本"}
       ],
       "execEndpoint": "/"
     }'
```
### 编码图像（远程 URL）
```bash
curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d '{
       "data": [
         {"uri": "https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"}
       ],
       "execEndpoint": "/"
     }'
```
### 编码图像（本地文件，base64）
```bash
curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d "{
       \"data\": [
         {\"blob\": \"$(base64 -w 0 /path/to/image.jpg)\"}
       ],
       \"execEndpoint\": \"/\"
     }"
```
### 混合编码（文本和图像）
```bash
curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d '{
       "data": [
         {"text": "这是一段文本"},
         {"uri": "https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"}
       ],
       "execEndpoint": "/"
     }'
```
## 响应格式
响应为 JSON 格式，编码结果在 `data[].embedding` 字段中：
```json
{
  "header": {...},
  "data": [
    {
      "id": "...",
      "text": "这是一个测试文本",
      "embedding": [0.123, -0.456, ...]
    }
  ]
}
```
### 提取 embedding
使用 `jq` 提取 embedding：
```bash
curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d '{"data":[{"text": "测试"}], "execEndpoint":"/"}' | \
     jq -c '.data[] | .embedding'
```
## Python 客户端示例
**重要**：如果服务配置了 `protocol: http`，客户端必须使用 `http://` 而不是 `grpc://`。
```python
from clip_client import Client
# 创建客户端（注意：使用 http:// 而不是 grpc://）
c = Client('http://localhost:51000')
# 编码文本
result = c.encode(['这是测试文本', '另一个文本'])
print(result.shape)  # [2, 768] 或其他维度
# 编码图像
result = c.encode(['https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg'])
print(result.shape)  # [1, 768]
# 混合编码
result = c.encode([
    '这是文本',
    'https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg'
])
print(result.shape)  # [2, 768]
```
## 支持的模型
- `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
tail -f /data/tw/SearchEngine/logs/cnclip_service.log
```
## 常见问题
### 服务启动失败
1. 检查端口是否被占用：`lsof -i :51000`
2. 检查 conda 环境是否正确激活
3. 查看日志文件获取详细错误信息
### 编码失败
1. 确保请求格式正确，使用 `/post` 端点
2. 确保 `execEndpoint` 设置为 `"/"`
3. 检查图像 URL 是否可访问
4. 查看服务日志排查错误
### 协议不匹配
如果服务配置了 `protocol: http`，客户端必须使用 `http://` 而不是 `grpc://`：
```python
# 正确
c = Client('http://localhost:51000')
# 错误（会导致连接失败）
c = Client('grpc://localhost:51000')
```
### 图像编码问题
CN-CLIP 模型的图像编码可能存在兼容性问题。如果遇到 `AttributeError: 'str' object has no attribute 'to'` 错误，这可能是 clip-as-service 对 CN-CLIP 图像预处理的支持问题。建议：
1. 检查 clip-as-service 和 cn-clip 的版本兼容性
2. 尝试使用本地图像文件而不是远程 URL
3. 查看 [clip-as-service 的 GitHub Issues](https://github.com/jina-ai/clip-as-service/issues) 是否有相关报告