CN-CLIP 编码服务使用指南

简介

本服务基于 clip-as-service 提供 CN-CLIP 模型的文本和图像编码功能。

启动服务

./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）

示例

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

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

# 调整批处理大小
./scripts/start_cnclip_service.sh --batch-size 16 --dtype float32

停止服务

./scripts/stop_cnclip_service.sh

使用 API

编码文本

curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d '{
       "data": [
         {"text": "这是一个测试文本"},
         {"text": "另一个文本"}
       ],
       "execEndpoint": "/"
     }'

编码图像（远程 URL）

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）

curl -X POST http://localhost:51000/post \
     -H 'Content-Type: application/json' \
     -d "{
       \"data\": [
         {\"blob\": \"$(base64 -w 0 /path/to/image.jpg)\"}
       ],
       \"execEndpoint\": \"/\"
     }"

混合编码（文本和图像）

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 字段中：

{
  "header": {...},
  "data": [
    {
      "id": "...",
      "text": "这是一个测试文本",
      "embedding": [0.123, -0.456, ...]
    }
  ]
}

提取 embedding

使用 jq 提取 embedding：

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://。

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 版本

查看日志

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://：

# 正确
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 是否有相关报告