docs/CNCLIP_SERVICE%E8%AF%B4%E6%98%8E%E6%96%87%E6%A1%A3.md

# 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](https://github.com/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`）
```bash
./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 单独启动/停止
```bash
./scripts/start_cnclip_service.sh --device cuda
./scripts/stop_cnclip_service.sh
```
### 4.2 统一编排（推荐日常用法）
```bash
./scripts/service_ctl.sh restart
# 或
./restart.sh
```
`service_ctl.sh` 在启动 `cnclip` 时默认注入 `CNCLIP_DEVICE=cuda`。  
若机器无 GPU 或希望改用 CPU，可在 `.env` 设置：
```bash
CNCLIP_DEVICE=cpu
```
## 5. GPU 使用与验证
### 5.1 必须点
- 启动日志显示 `device: cuda` 仅代表配置传入成功；
- 只有在**首次编码请求触发模型加载后**，`nvidia-smi` 才一定能看到显存占用。
### 5.2 推荐验证步骤
1) 启动服务：
```bash
./scripts/start_cnclip_service.sh --port 51000 --device cuda
```
2) 发送一次请求（触发模型加载）：
```bash
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：
```bash
nvidia-smi
```
预期：
- `shape` 为 `(1, 1024)`；
- `nvidia-smi` 出现对应 `python`/`clip_server` 进程并有显存占用。
## 6. 使用方式（客户端）
### 6.1 在本仓库中（推荐）
- 服务消费者一般是 `embedding` 服务，不建议业务侧直接连 `cnclip`。
- 若需手动调试，请使用隔离环境（推荐 `.venv-embedding` 或 `.venv-cnclip`），不要在主 `.venv` 安装旧依赖。
示例：
```python
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）专项，不重复解释项目通用内容。