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

本文是本仓库的 CN-CLIP 运行手册与约束说明。主流程仍是 embedding 服务（6005）；当 embeddings/config.py 中 USE_CLIP_AS_SERVICE=true 时，embedding 会调用本 gRPC 服务（默认 grpc://127.0.0.1:51000）生成图片向量。

1. 设计目标与官方对齐

• 采用 clip-as-service 的标准拆分：clip-server（服务端）与 clip-client（客户端）可独立安装。
• 服务协议使用 gRPC，符合官方推荐与本项目现有调用链。
• 保持“主项目环境”和“CN-CLIP 专用环境”解耦，避免 grpcio/jina/docarray 与主项目依赖互相污染。

官方仓库（安装方式、server/client 分离、基本使用示例）： jina-ai/clip-as-service

2. 当前架构（本仓库）

• 服务启动脚本：scripts/start_cnclip_service.sh
• 服务停止脚本：scripts/stop_cnclip_service.sh
• 环境初始化脚本：scripts/setup_cnclip_venv.sh
• 统一编排入口：scripts/service_ctl.sh（restart.sh 调用它）
• 默认端口：51000
• 默认模型：CN-CLIP/ViT-H-14
• 默认协议：gRPC

3. 环境准备策略（推荐做法）

3.1 推荐：专用 venv（.venv-cnclip）

./scripts/setup_cnclip_venv.sh

脚本会创建 .venv-cnclip，并处理已知兼容性问题（grpcio、jina、docarray、pkg_resources 等），避免在主 .venv 中反复冲突。

3.2 启动时的环境策略（严格）

start_cnclip_service.sh 只允许使用 .venv-cnclip。
若 .venv-cnclip 不存在，脚本会直接失败并提示先执行 ./scripts/setup_cnclip_venv.sh。

4. 服务管理方式（推荐）

4.1 单独启动/停止

./scripts/start_cnclip_service.sh --device cuda
./scripts/stop_cnclip_service.sh

4.2 统一编排（推荐日常用法）

./scripts/service_ctl.sh restart
# 或
./restart.sh

service_ctl.sh 在启动 cnclip 时默认注入 CNCLIP_DEVICE=cuda。
若机器无 GPU 或希望改用 CPU，可在 .env 设置：

CNCLIP_DEVICE=cpu

5. GPU 使用与验证

5.1 必须点

• 启动日志显示 device: cuda 仅代表配置传入成功；
• 只有在首次编码请求触发模型加载后，nvidia-smi 才一定能看到显存占用。

5.2 推荐验证步骤

1) 启动服务：

./scripts/start_cnclip_service.sh --port 51000 --device cuda

2) 发送一次请求（触发模型加载）：

PYTHONPATH="third-party/clip-as-service/client:${PYTHONPATH}" NO_VERSION_CHECK=1 .venv-cnclip/bin/python -c "
from clip_client import Client
c = Client('grpc://localhost:51000')
r = c.encode(['测试'])
print('shape:', r.shape)
"

3) 观察 GPU：

nvidia-smi

预期：

• shape 为 (1, 1024)；
• nvidia-smi 出现对应 python/clip_server 进程并有显存占用。

6. 使用方式（客户端）

6.1 在本仓库中（推荐）

• 服务消费者一般是 embedding 服务，不建议业务侧直接连 cnclip。
• 若需手动调试，请使用隔离环境（推荐 .venv-embedding 或 .venv-cnclip），不要在主 .venv 安装旧依赖。

示例：

from clip_client import Client

c = Client("grpc://127.0.0.1:51000")
vec = c.encode(["https://example.com/a.jpg", "测试文本"])
print(vec.shape)  # (2, 1024)

6.2 常见误区

• ❌ 用 http://localhost:51000 当成 HTTP 服务访问；
• ❌ 只看“启动成功”就判断已用 GPU，不发请求不看 nvidia-smi；
• ❌ 在主 .venv 直接安装 server 依赖导致依赖树污染。

7. 已知兼容性说明（关键信息）

• clip-as-service 在本项目场景下依赖链较老，grpcio/jina/docarray 组合在 Python 3.12 上易触发源码构建问题。
• setuptools>=82 移除了 pkg_resources；而部分依赖链仍会导入它，因此专用脚本固定了兼容范围。
• setup_cnclip_venv.sh 中存在“为可运行性而做的约束收敛”，这是有意行为，不建议手动放开。

8. 排障速查

8.1 启动失败

• 查看日志：tail -f logs/cnclip_service.log
• 检查端口占用：lsof -i :51000
• 重新构建环境：rm -rf .venv-cnclip && ./scripts/setup_cnclip_venv.sh

8.2 连接失败

• 确认客户端使用 grpc:// 协议；
• 确认端口与服务端一致（默认 51000）。

8.3 看不到 GPU 进程

• 先发一次编码请求，再看 nvidia-smi；
• 确认启动参数或环境变量为 cuda（--device cuda 或 CNCLIP_DEVICE=cuda）；
• 确认日志中无模型加载异常。

9. 与其他文档的关系

• 开发总览：docs/QUICKSTART.md
• 系统架构：docs/DEVELOPER_GUIDE.md
• 向量服务说明：embeddings/README.md

本文件聚焦 CN-CLIP（clip-as-service）专项，不重复解释项目通用内容。