# 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
  ```
  
  需要我帮你修改启动脚本以支持副本数参数吗？