litellm 使用教程

LiteLLM & vLLM 服务管理系统

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

1. 脚本概览

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

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/ # 自动生成