vLLM 生产级部署实战：一条命令把开源大模型变成 OpenAI 兼容 API 服务

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

from vllm import LLM, SamplingParams

prompts = [
    "Hello, my name is",
    "The future of AI is",
    "上海的简称是",   # 中文也可以
]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

llm = LLM(model="facebook/opt-125m")   # 125M 参数的小模型，秒下载秒跑，用于验证

outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    print(output.outputs[0].text)

vllm serve Qwen/Qwen2.5-1.5B-Instruct

curl http://localhost:8000/v1/models

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",        # 本地服务默认不校验 Key
)

resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[{"role": "user", "content": "你好！你是谁？"}],
)
print(resp.choices[0].message.content)

export VLLM_USE_MODELSCOPE=True
vllm serve Qwen/Qwen2.5-1.5B-Instruct

#!/usr/bin/env bash
set -u
# ============================================================
#  vLLM 生产级部署 一键脚本（macOS / Linux / WSL）
#  公开源码，欢迎审查 —— 不放心可先复制给 AI 判断
#  前置：NVIDIA GPU + CUDA（无 GPU 也可装，CPU 推理较慢）
#  国内自动开启 ModelScope 模型源
# ============================================================

GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; CYAN='\033[0;36m'; NC='\033[0m'
info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }
step()  { echo -e "${CYAN}[STEP]${NC} $1"; }

detect_network() {
  step "检测网络环境（国内 / 国外）..."
  if curl -fsI --max-time 5 "https://claude.ai" >/dev/null 2>&1; then
    info "可直连 claude.ai，判定为海外网络"
    echo "overseas"
  else
    warn "无法直连 claude.ai，判定为国内网络环境（将自动切换国内镜像 + ModelScope 模型源）"
    echo "domestic"
  fi
}

check_gpu() {
  step "检查 GPU 环境..."
  if command -v nvidia-smi >/dev/null 2>&1 && nvidia-smi -L >/dev/null 2>&1; then
    info "检测到 NVIDIA GPU："
    nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null | head -3
    return 0
  fi
  warn "未检测到 NVIDIA GPU（nvidia-smi 不可用）。vLLM 仍可安装，但推理走 CPU 会明显更慢。"
  echo "  · 有独显的笔记本/服务器请先装好 NVIDIA 驱动（命令 nvidia-smi 能输出即 OK）"
  echo "  · Windows 用户请在 WSL 中运行本脚本（NVIDIA 官方支持 WSL CUDA）"
  echo "  · 没有 GPU 也可以继续（CPU 模式），或考虑用云端 API 更快"
  return 1
}

check_python312() {
  step "检查 Python 3.12..."
  local found=""
  for p in python3.12 python3 python3.13; do
    if command -v "$p" >/dev/null 2>&1 && "$p" --version 2>&1 | grep -qE "3\.(12|13)"; then
      found="$p"; break
    fi
  done
  if [ -n "$found" ]; then
    PY="$found"; info "使用 $PY：$($PY --version 2>&1)"; return 0
  fi
  error "需要 Python 3.12+。请先安装（https://www.python.org/downloads/ 或 distro 包管理器）。"
  return 1
}

setup_and_install() {
  local net="$1"
  step "创建虚拟环境并安装 vLLM（依赖较大，可能耗时 5-15 分钟，可耐心等或先干别的）..."
  mkdir -p vllm-serve && cd vllm-serve || return 1
  $PY -m venv .venv 2>/dev/null || { error "创建虚拟环境失败"; return 1; }
  # shellcheck disable=SC1091
  source .venv/bin/activate || { warn "激活虚拟环境失败，继续使用系统环境"; }

  local pypi="https://pypi.org/simple"
  if [ "$net" = "domestic" ]; then
    pypi="https://pypi.tuna.tsinghua.edu.cn/simple"
  fi

  step "安装 vllm（清华镜像优先，失败回退官方源）..."
  if pip install "vllm" -i "$pypi" --timeout 120 >/dev/null 2>&1; then
    info "vLLM 安装成功"
    return 0
  fi
  warn "镜像源安装失败，改用官方源重试（依赖较多请耐心）..."
  if pip install "vllm" --timeout 120 >/dev/null 2>&1; then
    info "vLLM 安装成功（官方源）"
    return 0
  fi
  error "vLLM 安装失败。常见原因与处理："
  echo "  1. 内存不足：vLLM + PyTorch 安装需要 8GB+ 内存，请关掉其他程序"
  echo "  2. Python 版本不匹配：要求 3.12+（当前 $($PY --version 2>&1)）"
  echo "  3. 网络问题：手动执行 python3 -m pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple"
  return 1
}

start_service() {
  step "生成启动脚本与用法说明（模型下载走 ModelScope 可选）..."
  cat > start.sh <<'SHEOF'
#!/usr/bin/env bash
# vLLM 启动示例（模型按需改）：
#   国内（ModelScope 源）：VLLM_USE_MODELSCOPE=True ./start.sh
#   海外（Hugging Face 源）：./start.sh
set -e
cd "$(dirname "$0")"
if [ -f .venv/bin/activate ]; then source .venv/bin/activate; fi
export VLLM_USE_MODELSCOPE=${VLLM_USE_MODELSCOPE:-False}
# 首个模型可换成任意 HF/ModelScope 模型名，如 Qwen/Qwen2.5-1.5B-Instruct、deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B
vllm serve Qwen/Qwen2.5-1.5B-Instruct --port 8000
SHEOF
  chmod +x start.sh

  cat > test_client.py <<'PYEOF'
"""调用本地 vLLM 服务的 OpenAI 兼容客户端（和服务起好后另开终端运行）"""
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[{"role": "user", "content": "你好！用一句话介绍你自己。"}],
)
print(resp.choices[0].message.content)
PYEOF

  info "已生成 vllm-serve/start.sh 与 vllm-serve/test_client.py"
}

main() {
  echo "============================================"
  echo "  vLLM 生产级部署 一键脚本"
  echo "  适用于 macOS / Linux / WSL"
  echo "============================================"
  echo ""

  local NET
  NET=$(detect_network)

  if [ "$NET" = "domestic" ]; then
    export VLLM_USE_MODELSCOPE=True
    info "已启用 ModelScope 模型源（VLLM_USE_MODELSCOPE=True），国内下载模型快"
  fi

  check_gpu || warn "继续安装（CPU 模式可跑但慢；想省事可在文末考虑云端 API 路线）"
  if ! check_python312; then exit 1; fi
  if ! setup_and_install "$NET"; then
    error "环境准备失败，脚本终止。请按上方提示手动处理后重跑。"
    exit 1
  fi

  start_service

  echo ""
  echo "============================================"
  info "全部完成！"
  echo "  启动服务：  cd vllm-serve && VLLM_USE_MODELSCOPE=True ./start.sh"
  echo "  验证服务：  curl http://localhost:8000/v1/models"
  echo "  测试调用：  另开终端 cd vllm-serve && source .venv/bin/activate && python test_client.py"
  echo "  换模型：    编辑 start.sh 里 vllm serve 的模型名"
  echo ""
  echo "  想省 GPU/精力：云端 OpenAI 兼容 API（如 https://cloudzone-api.cyou/，90+ 模型按量计费）"
  echo "============================================"
}

main "$@"

# ============================================================
#  vLLM 生产级部署 一键脚本（Windows PowerShell 引导器）
#  公开源码，欢迎审查 -- 不放心可先复制给 AI 判断
#  说明：vLLM 官方不支持 Windows 原生运行，本脚本检测 WSL，
#        并把 Linux 安装脚本送入 WSL 内执行（一站式完成）。
# ============================================================
$ErrorActionPreference = "Stop"

function Write-Info  { Write-Host "[INFO] $args" -ForegroundColor Green }
function Write-Warn  { Write-Host "[WARN] $args" -ForegroundColor Yellow }
function Write-Err   { Write-Host "[ERROR] $args" -ForegroundColor Red }
function Write-Step  { Write-Host "[STEP] $args" -ForegroundColor Cyan }

# 1. 检测 WSL
Write-Step "检查 WSL 环境..."
if (-not (Get-Command wsl -ErrorAction SilentlyContinue)) {
    Write-Err "未找到 wsl 命令。请先安装 WSL："
    Write-Host "  PowerShell（管理员）执行：wsl --install"
    Write-Host "  重启后安装 Ubuntu 发行版，再运行本脚本。"
    exit 1
}

try {
    $wslHome = (wsl -e sh -c 'echo $HOME' 2>$null).Trim()
} catch {
    $wslHome = "/root"
}
if ([string]::IsNullOrWhiteSpace($wslHome)) { $wslHome = "/root" }
Write-Info "WSL 主目录：$wslHome"
Write-Host "如下载到安装包请放在 Windows 侧，通过 /mnt/c/ 路径访问。"

# 2. 询问是否继续（vLLM 依赖 NVIDIA GPU）
Write-Host ""
Write-Host "vLLM 需要 NVIDIA GPU（在 WSL 里沿用 Windows 驱动，开箱即用）。"
Write-Host "没有 GPU 也可以装（CPU 模式慢），或用云端 OpenAI 兼容 API（如 https://cloudzone-api.cyou/）更省事。"
$continue = Read-Host "继续安装 vLLM？[Y/N]"
if ($continue -ne "Y" -and $continue -ne "y") {
    Write-Info "已选择跳过。需要时重新运行本脚本即可。"
    exit 0
}

# 3. 把 Linux 脚本注入 WSL 并执行
Write-Step "将安装脚本注入 WSL 并执行（首次执行会在 WSL 内安装 Python 3.12 依赖，耗时较长）..."

$scriptPath = Join-Path $env:TEMP "install-vllm-wsl.sh"
if (-not (Test-Path $scriptPath)) {
    Write-Warn "未找到同目录的 install-vllm.sh，请将本 .ps1 与 install-vllm.sh 放在同一目录后重跑。"
    Write-Host "（或者手动在 WSL 中执行：curl -fsSL https://cleanresolver.com/scripts/install-vllm.sh -o /tmp/install-vllm.sh && bash /tmp/install-vllm.sh）"
    exit 1
}

$remotePath = "/tmp/install-vllm.sh"
# 经 /mnt/c 路径传入 WSL（%TEMP% → C:\Users\...\AppData\Local\Temp）
$tempWindows = [System.IO.Path]::GetFullPath($env:TEMP)
$mntPath = "/mnt/c" + $tempWindows -replace '^C:', '' -replace '\\', '/'
try {
    wsl -e cp "$mntPath/install-vllm-wsl.sh" $remotePath
    Write-Info "脚本已传入 WSL：$remotePath"
} catch {
    Write-Err "传入 WSL 失败：$_"
    Write-Host "请手动在 WSL 中执行：bash <(curl -fsSL https://cleanresolver.com/scripts/install-vllm.sh)"
    exit 1
}

Write-Host ""
Write-Host "正在 WSL 内执行安装（日志将直接输出）……"
Write-Host "============================================"
wsl -e bash $remotePath
$code = $LASTEXITCODE
Write-Host "============================================"

if ($code -ne 0) {
    Write-Err "WSL 内安装失败（退出码 $code）。请对照上方报错处理，或手动在 WSL 中重试。"
    exit 1
}

Write-Host ""
Write-Host "============================================"
Write-Info "全部完成！接下来在 WSL 终端里："
Write-Host "    cd ~/vllm-serve && VLLM_USE_MODELSCOPE=True ./start.sh"
Write-Host "    curl http://localhost:8000/v1/models"
Write-Host "Windows 浏览器可直接访问 http://localhost:8000"
Write-Host "============================================"