# CN-CLIP 服务（clip-as-service）说明

  > 本文是本仓库 CN-CLIP（图片向量）专项运行手册。目标是让新同事在新机器上独立完成环境准备、部署、验收与排障。

  ## 1. 作用与边界

  - `cnclip` 是独立 gRPC 服务（默认 `grpc://127.0.0.1:51000`）。
  - `embedding` 服务（6005）在 `USE_CLIP_AS_SERVICE=true` 时调用它完成 `/embed/image`。
  - `cnclip` 不负责文本向量；文本向量由 TEI（8080）负责。

  ## 2. 代码与脚本入口

  - 环境初始化：`scripts/setup_cnclip_venv.sh`
  - 启动：`scripts/start_cnclip_service.sh`
  - 停止：`scripts/stop_cnclip_service.sh`
  - 统一编排：`scripts/service_ctl.sh`

  ## 3. 前置条件

  ### 3.1 必需软件

  - Python 3.12（由仓库脚本创建虚拟环境）
  - 可访问模型下载源（Hugging Face / 镜像源）
  
  ### 3.2 GPU 模式额外要求
  
  - NVIDIA 驱动可用（`nvidia-smi` 可执行）
  - `cnclip` 设备设为 `cuda`
  
  检查命令：

  ```bash

  nvidia-smi

  ```

  ## 4. 环境安装（可复现）

  在仓库根目录执行：
  
  ```bash
  cd /data/saas-search
  ./scripts/setup_cnclip_venv.sh
  ```

  脚本会创建 `.venv-cnclip`，并安装 `clip-as-service` 服务端所需依赖。  
  `start_cnclip_service.sh` 只使用这个专用环境，不会污染主 `.venv`。

  ## 5. 启动与停止

  ### 5.1 GPU 模式（推荐）

  ```bash

  ./scripts/start_cnclip_service.sh --device cuda

  ```
  
  ### 5.2 CPU 模式（显式）
  
  ```bash
  ./scripts/start_cnclip_service.sh --device cpu
  ```
  
  ### 5.3 停止服务
  
  ```bash

  ./scripts/stop_cnclip_service.sh

  ```
  

  ## 6. service_ctl 的行为与约定
  
  ### 6.1 通过统一编排启动

  
  ```bash

  START_EMBEDDING=1 START_TEI=1 ./scripts/service_ctl.sh start

  ```
  

  当 `USE_CLIP_AS_SERVICE=true` 且 `START_EMBEDDING=1` 时，`service_ctl` 会自动拉起 `cnclip`。
  
  ### 6.2 设备选择优先级
  
  - 显式传入 `CNCLIP_DEVICE` 时，以该值为准：

  
  ```bash

  CNCLIP_DEVICE=cuda ./scripts/service_ctl.sh start cnclip
  CNCLIP_DEVICE=cpu  ./scripts/service_ctl.sh start cnclip

  ```
  

  - 不传 `CNCLIP_DEVICE` 时，默认 `cuda`。
  
  ### 6.3 运行中模式校验（重要）

  `service_ctl` 会在“已运行”场景下检查当前 `cnclip` 的 device 与期望是否一致。  
  若不一致会直接报错，防止“服务已启动但模式错了”的静默问题。

  例如：当前运行是 CPU，但你期望 CUDA，会提示先 stop 再按 CUDA 重启。

  ## 7. 验收步骤（必须做）

  ### 7.1 基础状态

  ```bash

  ./scripts/service_ctl.sh status cnclip

  ```

  ### 7.2 核对运行配置
  
  ```bash
  cat third-party/clip-as-service/server/torch-flow-temp.yml
  ```
  
  应看到：
  
  - GPU 模式：`device: 'cuda'`
  - CPU 模式：`device: 'cpu'`
  
  ### 7.3 发送一次编码请求（触发模型加载）

  ```bash

  PYTHONPATH="third-party/clip-as-service/client:${PYTHONPATH}" \
  NO_VERSION_CHECK=1 \
  .venv-cnclip/bin/python - <<'PY'

  from clip_client import Client

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

  r = c.encode(['测试'])
  print('shape:', r.shape)

  PY

  ```
  

  预期 `shape` 为 `(1, 1024)`。
  
  ### 7.4 GPU 验证

  ```bash
  nvidia-smi

  ```

  GPU 模式下应出现 `clip_server` 相关 `python` 进程及显存占用。

  ### 7.5 与 embedding 服务联调

  ```bash
  ./scripts/start_embedding_service.sh

  curl -sS -X POST "http://127.0.0.1:6005/embed/image" \
    -H "Content-Type: application/json" \
    -d '["https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"]'
  ```

  返回应为向量数组（非空）。

  ## 8. 常见问题与排障

  ### 8.1 “为什么 cnclip 没用 GPU？”

  先看启动命令是否显式写了：

  ```bash
  CNCLIP_DEVICE=cpu ...
  ```

  如果是，这就是预期行为，会强制 CPU。

  ### 8.2 “我要求 cuda，但 service_ctl 说 mode mismatch”

  说明当前已有 CPU 模式实例在跑。按提示重启：

  ```bash
  ./scripts/service_ctl.sh stop cnclip
  CNCLIP_DEVICE=cuda ./scripts/service_ctl.sh start cnclip
  ```

  ### 8.3 进程被 `Killed`

  常见于资源竞争（尤其单卡同时运行 TEI/reranker/cnclip 时的启动峰值）。建议：

  1. 先起 `tei` 与 `cnclip`，确认稳定后再起 `reranker`。
  2. 适当下调 `reranker` 显存预算（`config/config.yaml` 的 `gpu_memory_utilization`）。
  3. 必要时将 CN-CLIP 模型从 `ViT-H-14` 调整到更小规模。

  ### 8.4 gRPC 连接失败（`Connection refused`）

  - 检查端口：`lsof -i :51000`
  - 看服务日志：`tail -f logs/cnclip_service.log`
  - 确认客户端使用 `grpc://` 协议而非 `http://`

  ## 9. 相关文档

  - 开发总览：`docs/QUICKSTART.md`

  - TEI 专项：`docs/TEI_SERVICE说明文档.md`
  - 体系规范：`docs/DEVELOPER_GUIDE.md`
  - embedding 模块：`embeddings/README.md`