魔珐星云开发社区

目录

• LiteLLM & vLLM 服务管理系统
  • 1. 脚本概览
  • 2. 环境要求
  • 3. 配置文件说明
    • 3.1 vLLM 配置文件 (vllm_config.yaml)
    • 3.2 LiteLLM 配置文件 (litellm_config.yaml)
  • 4. 使用指南
    • 4.1 一键启动 (推荐)
    • 4.2 停止服务
    • 4.3 单独使用子脚本 (高级用法)
  • 5. 日志管理
  • 6. 故障排查
  • 7. 目录结构建议

LiteLLM & vLLM 服务管理系统

这是一个基于 Shell 的自动化工具流，用于一键部署和管理 LiteLLM Proxy(作为统一网关)和 vLLM(作为推理后端)。支持多 GPU、多实例部署，并包含自动健康检查和日志管理功能。

1. 脚本概览

项目包含以下四个核心脚本：

脚本名	作用	说明
start-all.sh	主入口脚本	负责环境检查、停止旧服务、依次启动 vLLM 和 LiteLLM，并输出服务地址。
stop_all.sh	停止服务	查找并终止所有相关进程，支持交互式强制关闭。
start_litellm.sh	启动 LiteLLM	独立启动 Proxy，支持开发模式(development)和生产模式(production)。
start_vllm_instances.sh	启动 vLLM	根据配置文件并行启动多个 vLLM 实例，并等待端口就绪。

2. 环境要求

在运行脚本之前，请确保服务器满足以下要求：

• 操作系统: Linux (Bash shell)
• Python 环境: 建议使用 Conda 或 venv
• 依赖工具:
  • litellm: pip install litellm
  • vllm: pip install vllm (如果启用 vLLM)
  • yq: 必须安装，用于解析 YAML 配置文件
  • curl: 用于健康检查
  • NVIDIA Drivers & nvidia-smi (如果启用 vLLM)

3. 配置文件说明

脚本强依赖 YAML 配置文件。以下是配置文件的结构示例。

3.1 vLLM 配置文件 (vllm_config.yaml)

如果需要启动 vLLM 后端，你需要按照以下格式编写配置：

settings:
  log_dir: "./logs/vllm"  # vLLM 日志存放路径

instances:
  - id: 1
    model_name: "/path/to/model-A"
    served_model_name: "model-a" # 可选，默认为 model_name，用于litellm路由的名字
    gpus: "0,1"                  # 指定 CUDA_VISIBLE_DEVICES，即这个实例可见的GPU
    port: 8000
    tensor_parallel_size: 2      # 张量并行数，需要为矩阵的约数，并且尽量与GPU个数相同
	# vllm也支持数据并行和流水线并行，但是在单节点多GPU的时候没必要流水线并行
    max_model_len: 8192          # 一次请求可处理的最大上下文长度
    gpu_memory_utilization: 0.90 # 控制vLLM实例可用的GPU显存比例，决定模型权重和KV cache等分配的总显存上限
    max_num_seqs: 256            # 可选，默认 256
    enable_chunked_prefill: true # 可选，默认 false
    disable_log_requests: false  # 可选，默认 false

  - id: 2
    model_name: "/path/to/model-B"
    gpus: "2"
    port: 8001
    tensor_parallel_size: 1

3.2 LiteLLM 配置文件 (litellm_config.yaml)

标准的 LiteLLM 配置文件，需要将 api_base 指向 vLLM 的端口。详见官方文档。具体的调度机制见grok的回答

model_list:

  - model_name: llm-judge-1
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3-0.6B   # 替换为你的模型名称(served_model_name)
      api_base: http://localhost:8001/v1
      max_parallel_requests: 200        # 👈 关键：每后端最大并发
      rpm: 10000                        # 每分钟请求限制(设高一点)
      tpm: 10000000                     # 每分钟 token 限制
      timeout: 300                      # 请求超时 (秒)
      stream_timeout: 60                # 流式响应超时 (秒)
    model_info:
      id: "llm_judge-instance-1"

  - model_name: llm-judge-2
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3-0.6B
      api_base: http://localhost:8002/v1
      max_parallel_requests: 200
      rpm: 10000
      tpm: 10000000
      timeout: 300
      stream_timeout: 60
    model_info:
      id: "llm_judge-instance-2"

# ============================================================
# LiteLLM 核心设置
# ============================================================
litellm_settings:
  drop_params: true                     # 自动移除不支持的参数
  num_retries: 3                        # 失败重试次数
  request_timeout: 600                  # 全局请求超时(根据https://github.com/BerriAI/litellm/discussions/9206，会覆盖每个后端的timeout)
  set_verbose: true                    # 调试时设为 true

# ============================================================
# 路由器设置 (负载均衡)
# ============================================================
router_settings:
  # ---- 路由策略选择 ----
  # simple-shuffle: 随机负载均衡(推荐，同质化部署)
  # least-busy: 选择最空闲的实例(流式请求多时使用)
  # usage-based-routing-v2: 基于 TPM/RPM 使用量(有配额限制时)
  # latency-based-routing: 选择延迟最低的(延迟敏感场景)
  routing_strategy: least-busy
  
  # ---- 并发控制 ----
  default_max_parallel_requests: 200  # 每个后端默认最大并发
  
  # ---- 重试与超时 ----
  enable_pre_call_checks: true        # 预调用检查
  num_retries: 3                      # 路由重试次数
  timeout: 30                         # 路由超时
  retry_after: 5                      # 重试间隔(秒)
  
  # ---- Redis 配置(多 LiteLLM 实例时需要)----
  # redis_host: localhost
  # redis_port: 6379
  # redis_password: ""

# ============================================================
# 通用设置
# ============================================================
# general_settings:
#   master_key: sk-your-secret-key-1234   # API 认证密钥 (生产环境请更换)
  # database_url: postgresql://user:password@localhost:5432/litellm  # 可选数据库
  # store_model_in_db: true

4. 使用指南

4.1 一键启动 (推荐)

使用 start-all.sh 可以处理所有流程。

仅启动 LiteLLM (连接已有后端):

./start-all.sh --litellm-config ./config/litellm_config.yaml

启动 vLLM + LiteLLM (完整链路):

./start-all.sh \
    --vllm-config ./config/vllm_config.yaml \
    --litellm-config ./config/litellm_config.yaml

保留当前运行的服务 (跳过停止步骤):

./start-all.sh \
    --skip-stop \
    --litellm-config ./config/litellm_config.yaml

4.2 停止服务

使用 stop_all.sh 清理进程。脚本会检查残留进程，如果正常关闭失败，会询问是否强制 kill -9。

./stop_all.sh

4.3 单独使用子脚本 (高级用法)

如果你需要调试或单独管理某个组件，可以直接调用子脚本。

单独启动 vLLM 实例组:

# 这将根据配置启动所有定义的实例并在后台运行
./start_vllm_instances.sh --config ./config/vllm_config.yaml

单独启动 LiteLLM:

# 开发模式 (单进程，详细 Debug 日志)
./start_litellm.sh -c ./config/litellm_config.yaml -p 4000 -m development

# 生产模式 (Gunicorn 多 Worker)
./start_litellm.sh -c ./config/litellm_config.yaml -p 4000 -m production -w 8

5. 日志管理

• LiteLLM 日志: 可以在start_litellm.sh的开头直接配置，也可以在start_all.sh调用start_litellm.sh的时候传递参数
• vLLM 日志: 位于 vllm_config.yaml 中配置的路径(例如 ./logs/vllm_instance_{ID}.log)。

6. 故障排查

1. 脚本提示 yq: command not found:
   • 脚本依赖 yq 解析 YAML。请参考环境要求部分进行安装。
2. vLLM 启动超时:
   • 检查日志文件。常见原因是显存不足 (OOM) 或模型路径错误。
   • 如果是大模型，加载时间较长，脚本默认等待 300秒。
3. LiteLLM 健康检查失败:
   • 检查端口是否被占用。
   • 查看 litellm_logs 下的日志，确认配置文件语法是否正确。
4. 端口冲突:
   • 确保配置文件中指定的端口(如 8000, 8001, 4000)未被其他服务占用。

7. 目录结构建议

为了让脚本正常工作，建议的项目结构如下：

.
├── scripts/
├   ├── start-all.sh
├   ├── stop_all.sh
├   ├── start_litellm.sh
├   ├── start_vllm_instances.sh
├── config/
│   ├── litellm_config.yaml
│   └── vllm_config.yaml
├── vllm_logs/           # 自动生成
└── litellm_logs/   # 自动生成