# 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`