ai-saas / saas-search

CNCLIP_SERVICE说明文档.md 4.56 KB

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

检查命令：

nvidia-smi

4. 环境安装（可复现）

在仓库根目录执行：

cd /data/saas-search
./scripts/setup_cnclip_venv.sh

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

5. 启动与停止

5.1 GPU 模式（推荐）

./scripts/start_cnclip_service.sh --device cuda

5.2 CPU 模式（显式）

./scripts/start_cnclip_service.sh --device cpu

5.3 停止服务

./scripts/stop_cnclip_service.sh

6. service_ctl 的行为与约定

6.1 通过统一编排启动

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 时，以该值为准：
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 基础状态

./scripts/service_ctl.sh status cnclip

7.2 核对运行配置

cat third-party/clip-as-service/server/torch-flow-temp.yml

应看到：

  • GPU 模式：device: 'cuda'
  • CPU 模式：device: 'cpu'

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

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 验证

nvidia-smi

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

7.5 与 embedding 服务联调

./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？”

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

CNCLIP_DEVICE=cpu ...

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

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

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

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