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

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

  ## 1. 作用与边界

  - `cnclip` 是独立 gRPC 服务（默认 `grpc://127.0.0.1:51000`），底层为 **Chinese-CLIP**：**图像与文本在同一向量空间**（图文可互检）。
  - 图片 embedding 服务（默认 `6008`）在 `image_backend: clip_as_service` 时通过 gRPC 调用它完成：
    - `POST /embed/image`：图片 URL / 本地路径 → 图向量；
    - `POST /embed/clip_text`：**自然语言短语** → 文本塔向量（与上图向量同空间，用于 `image_embedding` 检索、以文搜图等）。
  - **语义检索用的文本向量**（`title_embedding`、query 语义召回）仍由 **TEI（8080）+ `POST /embed/text`（6005）** 负责，与 CN-CLIP 不是同一模型、不是同一向量空间；请勿混淆。

  ## 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 模型配置与覆盖
  
  - 仓库默认模型取自 `embeddings/config.py` 的 `CLIP_AS_SERVICE_MODEL_NAME`。
  - `scripts/start_cnclip_service.sh` 会自动读取这个配置，因此修改默认模型时不需要再去脚本里找硬编码。
  - 覆盖优先级：`--model-name` > `CNCLIP_MODEL_NAME` > `CLIP_AS_SERVICE_MODEL_NAME` / `embeddings/config.py`。
  
  查看当前默认模型：
  
  ```bash
  python3 -c "from embeddings.config import CONFIG; print(CONFIG.CLIP_AS_SERVICE_MODEL_NAME)"
  ```
  
  临时覆盖模型：
  
  ```bash

  ./scripts/start_cnclip_service.sh --model-name CN-CLIP/ViT-L-14   # 768 维，需与索引 dims 一致
  CNCLIP_MODEL_NAME=CN-CLIP/ViT-H-14 ./scripts/service_ctl.sh start cnclip   # 默认 1024 维（与 mappings 中 image_embedding 一致）

  ```
  
  ### 5.4 停止服务

  
  ```bash

  ./scripts/stop_cnclip_service.sh

  ```
  

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

  
  ```bash

  ./scripts/service_ctl.sh start cnclip

  # 或一次启动可选能力：./scripts/service_ctl.sh start embedding embedding-image tei 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'`

  - 模型名：`name: '<当前实际模型名>'`

  ### 7.2.1 日志与 PID 文件
  
  - 日志：`logs/cnclip.log`
  - PID：`logs/cnclip.pid`
  

  ### 7.3 发送一次编码请求（触发模型加载）

  **gRPC 直连（文本或图片 URL 混传时由 client 自动区分）：**
  

  ```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)`。
  

  **HTTP（推荐业务侧）：图片走 6008 `/embed/image`，纯文本走 `/embed/clip_text`（勿把 `http://` 图 URL 发到 `clip_text`）：**
  
  ```bash
  curl -sS -X POST "http://127.0.0.1:6008/embed/clip_text?normalize=true&priority=1" \
    -H "Content-Type: application/json" \
    -d '["纯棉T恤", "芭比娃娃"]'
  ```
  

  ### 7.4 GPU 验证

  ```bash
  nvidia-smi

  ```

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

  ### 7.5 与 embedding 服务联调

  ```bash

  ./scripts/start_embedding_image_service.sh

  curl -sS -X POST "http://127.0.0.1:6008/embed/image" \

    -H "Content-Type: application/json" \
    -d '["https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"]'
  ```

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

  ## 8. 相关文档

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

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