# CN-CLIP 服务副本数配置指南

## 📊 副本数（Replicas）详解

### 什么是副本？

**副本（Replicas）** 是指同时运行的模型实例数量。每个副本都是独立的进程，可以：
- 并行处理多个请求
- 提高服务吞吐量
- 充分利用多核 CPU 或多 GPU

**关键点**：
- ✅ 每个副本加载一份完整的模型到内存/显存
- ✅ 副本间共享网络端口（通过负载均衡）
- ✅ 多副本**不会**自动分配到不同 GPU（需手动配置）

---

## 💾 显存占用分析

### 问题：2个副本会比1个副本多一倍显存吗？

**答案：是的！基本成倍增加。**

| 副本数 | 模型显存 | 峰值显存 | 总显存占用 |
|--------|---------|---------|-----------|
| 1副本 | ~2-3 GB | ~4-5 GB | **~4-5 GB** |
| 2副本 | ~4-6 GB | ~8-10 GB | **~8-10 GB** |
| 3副本 | ~6-9 GB | ~12-15 GB | **~12-15 GB** |
| 4副本 | ~8-12 GB | ~16-20 GB | **~16-20 GB** |

**说明**：
- **模型显存**：模型权重（固定部分）
- **峰值显存**：模型 + 激活值 + 中间结果（批处理时）
- **CN-CLIP/ViT-H-14**：约 2-3 GB 模型权重

### 你的 GPU 情况

```
GPU: Tesla T4
总显存: 16384 MiB (16 GB)
当前空闲: ~2 GB
```

**推荐配置**：
- **1副本**：最安全，适合当前场景
- **2副本**：需要先停止其他占用显存的程序
- **3+副本**：不建议（显存不足）

---

## ⚙️ 配置副本数

### 方法 1：修改配置文件（推荐）

编辑 `third-party/clip-as-service/server/clip_server/torch-flow.yml`：

```yaml
jtype: Flow
version: '1'
with:
  port: 51000
executors:
  - name: clip_t
    uses:
      jtype: CLIPEncoder
      with:
        name: 'CN-CLIP/ViT-H-14'
        device: 'cuda'              # 设备
        minibatch_size: 32          # 批处理大小
        num_worker_preprocess: 4    # 预处理线程
        dtype: 'float16'            # 数据类型
      metas:
        py_modules:
          - clip_server.executors.clip_torch
    timeout_ready: 3000000
    replicas: 2                    # ← 修改这里（1, 2, 3...）
```

### 方法 2：命令行参数

```bash
# 启动时指定副本数（需要修改启动脚本）
python -m clip_server \
    --name 'CN-CLIP/ViT-H-14' \
    --replicas 2 \
    --port 51000
```

### 方法 3：使用改进的启动脚本

我会在下面提供一个支持副本数的启动脚本。

---

## 📈 性能对比

### 吞吐量测试（理论值）

**配置**：CN-CLIP/ViT-H-14, Tesla T4, batch_size=32

| 副本数 | QPS (请求/秒) | 显存占用 | 推荐场景 |
|--------|--------------|---------|---------|
| 1 | ~80-100 | ~4-5 GB | 开发测试、低并发 |
| 2 | ~150-180 | ~8-10 GB | 生产环境、中等并发 |
| 3 | ~220-260 | ~12-15 GB | 高并发（需24GB+显存）|
| 4 | ~300-350 | ~16-20 GB | 极高并发（需A100等）|

**注意**：
- 实际性能取决于批处理大小、请求类型（文本/图像）
- 并发请求少时，多副本提升不明显
- 并发请求多时，多副本显著提升吞吐量

### 延迟对比

| 副本数 | 单请求延迟 | P99 延迟 | 说明 |
|--------|-----------|---------|------|
| 1 | ~50ms | ~200ms | 无等待，直接处理 |
| 2 | ~50ms | ~150ms | 有等待，但处理快 |
| 4 | ~50ms | ~100ms | 等待少，处理很快 |

**结论**：
- ✅ 多副本**不降低**单请求延迟
- ✅ 多副本**显著降低** P99 延迟（高并发时）
- ✅ 多副本**显著提升**吞吐量

---

## 🎯 配置建议

### 场景 1：开发/测试（推荐）

```yaml
replicas: 1
minibatch_size: 32
device: cuda  # 或 cpu
```

**特点**：
- ✅ 显存占用低（~5GB）
- ✅ 足够测试使用
- ✅ 启动快

### 场景 2：生产环境（中等并发）

```yaml
replicas: 2
minibatch_size: 32
device: cuda
```

**前提条件**：
- ✅ GPU 显存 ≥ 12GB
- ✅ 没有其他显存占用程序
- ✅ 需要 ~10GB 显存

**特点**：
- ✅ 吞吐量翻倍（~150-180 QPS）
- ✅ 处理并发请求能力强
- ⚠️ 需要确保显存充足

### 场景 3：生产环境（高并发）

```yaml
replicas: 2
minibatch_size: 64
device: cuda
```

**优化点**：
- ✅ 增大批处理（利用多副本优势）
- ✅ 吞吐量进一步提升
- ⚠️ 需要更多显存（~12-15GB）

### 场景 4：多 GPU 服务器

如果你有多块 GPU：

```yaml
executors:
  - name: clip_t_gpu0
    uses:
      jtype: CLIPEncoder
      with:
        device: 'cuda:0'
        replicas: 2
    uses:
      jtype: CLIPEncoder
      with:
        device: 'cuda:1'
        replicas: 2
```

**说明**：
- 2块GPU，每块2个副本 = 共4个副本
- 总吞吐量 ~300+ QPS
- 每块GPU占用 ~8-10GB

---

## 🔍 监控和调试

### 查看显存占用

```bash
# 实时监控
watch -n 1 nvidia-smi

# 查看详细信息
nvidia-smi --query-gpu=timestamp,name,memory.used,memory.free,utilization.gpu --format=csv

# 持续监控（每秒刷新，共100次）
nvidia-smi dmon -s u -c 100
```

### 查看副本进程

```bash
# 查看所有 clip_server 进程
ps aux | grep clip_server

# 应该看到：
# root  12345  clip_server (main)
# root  12346  clip_server (replica 1)
# root  12347  clip_server (replica 2)
# ...

# 查看进程数
ps aux | grep clip_server | wc -l

# 应该 = replicas + 1
```

### 测试吞吐量

```bash
# 使用测试脚本
python scripts/test_cnclip_service.py --batch-size 100

# 观察日志
tail -f logs/cnclip_service.log | grep "encoded"
```

---

## ⚠️ 常见问题

### Q1: 设置2副本后显存不足 (OOM)

**错误信息**：
```
RuntimeError: CUDA out of memory. Tried to allocate XXX MiB
```

**解决方案**：

**方案 A**：减小批处理大小
```yaml
replicas: 2
minibatch_size: 16  # 从32减到16
```

**方案 B**：使用更小的模型
```yaml
name: 'CN-CLIP/ViT-L-14'  # 从 H-14 改为 L-14
replicas: 2
```

**方案 C**：减少副本数
```yaml
replicas: 1  # 回退到单副本
```

### Q2: 多副本反而性能下降

**原因**：
- GPU 资源竞争（显存带宽、计算单元）
- 批处理太小（未充分利用并行）
- CPU 预处理成为瓶颈

**解决方案**：
```yaml
# 增大批处理
minibatch_size: 64

# 增加预处理线程
num_worker_preprocess: 8

# 或减少副本
replicas: 1
```

### Q3: 如何知道最佳副本数？

**实验方法**：

```bash
# 测试脚本
for replicas in 1 2 3; do
  echo "Testing $replicas replicas..."

  # 修改配置
  sed -i "s/replicas: .*/replicas: $replicas/" torch-flow.yml

  # 重启服务
  ./scripts/stop_cnclip_service.sh
  ./scripts/start_cnclip_service.sh

  # 等待启动
  sleep 30

  # 运行测试
  python scripts/test_cnclip_service.py --batch-size 100
done

# 对比结果，选择最优配置
```

**推荐配置**：
- **Tesla T4 (16GB)**: 1-2 副本
- **RTX 3090 (24GB)**: 2-3 副本
- **A100 (40GB)**: 3-4 副本

---

## 📝 快速配置参考

### 修改启动脚本支持副本数

编辑 `scripts/start_cnclip_service.sh`，添加参数：

```bash
# 在参数解析部分添加
--replicas)
    REPLICAS="$2"
    shift 2
    ;;

# 在启动命令中使用
nohup python -m clip_server \
    --name "${MODEL_NAME}" \
    --replicas ${REPLICAS:-1} \    # ← 添加这一行
    --port ${PORT} \
    ...
```

### 当前最佳实践（Tesla T4）

**保守配置**（推荐）：
```yaml
replicas: 1
minibatch_size: 32
dtype: float16
```
- 显存：~5GB
- QPS：~80-100
- 适合：开发、测试、小规模应用

**激进配置**（需测试）：
```yaml
replicas: 2
minibatch_size: 32
dtype: float16
```
- 显存：~10GB
- QPS：~150-180
- 适合：生产环境、中等并发
- 前提：清理其他显存占用

---

## 🎉 总结

### 关键要点

1. **显存占用**：副本数 × 单副本显存（基本线性增长）
2. **性能提升**：吞吐量接近线性增长，但不完美
3. **推荐配置**：
   - Tesla T4 (16GB): **1-2 副本**
   - 确保显存充足 + 预留 20% 余量
4. **优化建议**：
   - 从小副本开始测试
   - 根据实际负载调整
   - 监控显存和性能指标

### 你的情况

**当前配置**：
```yaml
replicas: 1  # 当前配置
```

**建议**：
- ✅ 先保持 `replicas: 1`，测试性能
- ✅ 如果吞吐量不够，再尝试 `replicas: 2`
- ⚠️ 确保显存充足（当前空闲2GB可能不够2副本）
- 💡 考虑先清理其他显存占用

**快速测试**：
```bash
# 1. 查看当前显存占用
nvidia-smi

# 2. 启动1副本，观察显存
./scripts/start_cnclip_service.sh
nvidia-smi  # 应该增加 ~5GB

# 3. 如果还有空间，尝试2副本
./scripts/stop_cnclip_service.sh
# 修改 torch-flow.yml 中的 replicas: 2
./scripts/start_cnclip_service.sh
nvidia-smi  # 应该再增加 ~5GB
```

需要我帮你修改启动脚本以支持副本数参数吗？