# CN-CLIP 服务（Legacy）

  > **注意**：当前主流程使用 embedding 服务（端口 6005），见 `docs/QUICKSTART.md` 3.3。本文档为 legacy gRPC 服务说明。
  
  ---
  
  # 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://43.166.252.75: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
  ```

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