本地部署 LLM 服务：从硬件到后端的完整基建指南#

1. GPU / 算力#

• 核心瓶颈：显存（VRAM）决定能跑多大的模型、多大的并发。
• 显存估算：参数量 × 精度字节数 ≈ 权重占用。
  • 7B 模型 FP16 ≈ 14GB，INT8 ≈ 7GB，INT4 ≈ 3.5GB。
  • 70B 模型 FP16 ≈ 140GB，需多卡（如 4×A100 80G）。
• 常见卡型：
  • 消费级：RTX 4090（24GB）、RTX 5090（32GB）——适合小模型/实验。
  • 专业级：A100/H100（80GB）、L40S（48GB）、H20——适合正式服务。
  • 国产替代：昇腾 910B、寒武纪、沐曦等（需适配国产软件栈）。
• KV Cache 也要占显存，长上下文 + 高并发会显著抬高需求。

2. 主机与扩展#

• CPU：多核（≥16 核）用于数据预处理、调度、tokenizer。
• 内存：≥ 256GB 起步，用于加载权重到 CPU、KV cache 溢出、数据集。
• 存储：NVMe SSD（Gen4/Gen5），模型加载和权重读取速度关键。
• 扩展能力：选购带 8×PCIe 或 NVLink 的服务器，便于多卡改造。

3. 网络#

• 多卡互联：NVLink / PCIe 直连，跨卡张量并行时带宽决定性能。
• 机房网络：万兆网卡，服务对外吞吐、集群通信。
• 对外：负载均衡、CDN、带宽按需求估算。

4. 机房与供配电#

• 散热：GPU 发热量大，需液冷或高功率风冷。
• 供电：单卡 350–700W，多卡需 UPS + 冗余电源。
• 机架、制冷、消防、监控。

1. 推理引擎（核心）#

• vLLM：业界主流，PagedAttention 高吞吐，支持连续批处理。
• TGI（Hugging Face Text Generation Inference）：工业级，功能全。
• SGLang：RadixAttention，长上下文/多轮对话性能好。
• TensorRT-LLM：NVIDIA，性能极致但部署复杂。
• llama.cpp：CPU/边缘端轻量，适合小模型。
• Ollama / LM Studio：快速上手，适合测试，生产慎用。

2. 量化与优化#

• 工具：GPTQ、AWQ、GGUF（llama.cpp）、bitsandbytes。
• 目的：降显存、提吞吐，代价是精度损失。

3. 服务框架#

• API 层：OpenAI 兼容接口（vLLM/TGI 原生支持）。
• 网关：Nginx / Kong / Envoy 做反向代理、限流、负载均衡。
• 编排：Docker / Kubernetes（K8s + GPU 插件 nvidia-device-plugin）。

4. 模型获取与存储#

• 模型来源：Hugging Face、ModelScope（国内镜像）、本地私有化权重。
• 管理：Model Registry、版本管理。

5. 前后端应用层#

• 框架：FastAPI / LangChain / LlamaIndex。
• RAG：向量数据库（Milvus、Qdrant、pgvector）+ Embedding 模型。
• 前端：Web UI（如 Open WebUI、Gradio）。

6. 监控与日志#

• 观测：Prometheus + Grafana、MLflow。
• 指标：吞吐（tokens/s）、延迟（TTFT、TPOT）、GPU 利用率、显存占用。

推荐配置（生产主力，INT8 权重 + FP8 KV）#

假设：8K 上下文、峰值 20 并发、连续批处理（vLLM 平均实际占用远低于保守值）。

为什么不用 H100/A100 80G：能吃下，但 80G 单卡跑 27B+20 并发比较紧，H20 96G 或双 L40S（96G 合计）更从容，且性价比高。

软件栈#

• 推理引擎：vLLM（开放 Discourse，高吞吐，原生 OpenAI 兼容接口）
• 重量级可选：SGLang（长上下文/多轮更优）
• 量化：FP8/INT8 权重 + FP8 KV cache（vLLM 内置，几乎无损）
• 部署：Docker + Nginx（限流/负载均衡），不需要上 K8s（单实例规模）
• 监控：Prometheus + Grafana（vLLM 暴露 tokens/s、TTFT、TPOT、GPU 利用率）
• 模型：从 ModelScope 拉取（国内快）或 Hugging Face

预算配置（INT4 权重，单卡）#

假设：缩短上下文到 4K、峰值并发降到 15。

这档适合内部测试 / 低并发原型，不建议作为正式对外服务。

成本估算（人民币，含整机）#

云上（阿里云/火山/华为云 GPU 实例）按需租用 H20 或 A10 即可，月租约 ¥1.5–3 万，适合先验证再自购。

显存重算（以 Qwen2.5-27B 为例）#

27B 模型是 GQA 架构（64 层、4 个 KV 头），KV Cache 每 token 约 128KB（FP16）：

结论：10 并发 × 8K 时 KV 只占 5–10GB，权重成了唯一大头 → 单卡路线成立。

推荐配置（生产，FP8 权重）#

预算配置（INT4 AWQ，单卡 4090）#

成本估算（人民币）#

vLLM 启动命令（参数已定死，直接可用）#

生产方案（FP8）：

1
vllm serve Qwen/Qwen2.5-27B-Instruct-FP8 \
2
  --max-model-len 8192 \
3
  --max-num-seqs 10 \
4
  --kv-cache-dtype fp8_e5m2 \
5
  --gpu-memory-utilization 0.9 \
6
  --port 8000 \
7
  --served-model-name qwen27b

预算方案（INT4 AWQ）：

1
vllm serve Qwen/Qwen2.5-27B-Instruct-AWQ \
2
  --max-model-len 8192 \
3
  --max-num-seqs 10 \
4
  --kv-cache-dtype fp8_e5m2 \
5
  --gpu-memory-utilization 0.95 \
6
  --port 8000 \
7
  --served-model-name qwen27b

模型从 ModelScope 拉取更快：modelscope download --model Qwen/Qwen2.5-27B-Instruct，本地路径替换仓库名即可。

推理引擎选型#

结论：vLLM，理由：单卡吞吐够、原生 OpenAI 接口、量化支持好、监控指标齐全。

服务架构（单机版）#

1
客户端
2
  │  HTTPS
3
  ▼
4
Nginx (反向代理 + 限流 + TLS 终结)
5
  │
6
  ▼
7
vLLM (OpenAI 兼容 :8000)  ──►  Prometheus 指标 /metrics
8
  │
9
  ├── 模型权重(Qwen2.5-27B FP8/AWQ)
10
  └── 可选: RAG 侧车(Milvus/Qdrant + Embedding)

三层：

1. 网关层（Nginx）：对外统一入口，隐藏内部端口；TLS 证书 + 限流（limit_req，防止打爆）；按路径路由到推理服务。
2. 推理层（vLLM）：核心服务，OpenAI 兼容 /v1/chat/completions、/v1/completions；暴露 /metrics 给监控。
3. 可选应用层：RAG（外接知识库时加向量库）与业务代码（FastAPI 做业务封装、鉴权、多租户）。

一键部署（Docker Compose）#

这是最省心的方案，不需要 K8s（单实例规模）。

docker-compose.yml：

1
services:
2
  vllm:
3
    image: vllm/vllm-openai:latest
4
    entrypoint: ["python", "-m", "vllm.entrypoints.openai.api_server"]
5
    command:
6
      - --model=/models/Qwen2.5-27B-Instruct
7
      - --max-model-len=8192
8
      - --max-num-seqs=10
9
      - --kv-cache-dtype=fp8_e5m2
10
      - --gpu-memory-utilization=0.9
11
      - --served-model-name=qwen27b
12
      - --port=8000
13
    volumes:
14
      - /data/models:/models:ro
15
    deploy:
16
      resources:
17
        reservations:
18
          devices:
19
            - driver: nvidia
20
              count: all
21
              capabilities: [gpu]
22
    ports:
23
      - "127.0.0.1:8000:8000"   # 只暴露内网，对外走 Nginx
24

25
  nginx:
26
    image: nginx:alpine
27
    volumes:
28
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
29
    ports:
30
      - "443:443"
31
    depends_on:
32
      - vllm
33

34
  prometheus:
35
    image: prom/prometheus
36
    volumes:
37
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
38
      - prom-data:/prometheus
39
    ports:
40
      - "9090:9090"
41

42
  grafana:
43
    image: grafana/grafana
44
    ports:
45
      - "3000:3000"
46
    environment:
47
      - GF_SECURITY_ADMIN_PASSWORD=<PASSWORD>
48
    volumes:
49
      - grafana-data:/var/lib/grafana
50

51
volumes:
52
  prom-data:
53
  grafana-data:

nginx.conf（限流 + 反代）：

1
worker_processes auto;
2
events { worker_connections 1024; }
3

4
http {
5
  limit_req_zone $binary_remote_addr zone=llm:10m rate=20r/s;
6

7
  upstream vllm {
8
    server vllm:8000;
9
    keepalive 32;
10
  }
11

12
  server {
13
    listen 443 ssl;
14
    # ssl_certificate /etc/nginx/ssl/server.crt;
15
    # ssl_certificate_key /etc/nginx/ssl/server.key;
16

17
    location /v1/ {
18
      limit_req zone=llm burst=20 nodelay;
19
      proxy_pass http://vllm;
20
      proxy_http_version 1.1;
21
      proxy_set_header Connection "";
22
      proxy_read_timeout 300s;   # 长生成需放宽
23
    }
24
  }
25
}

部署要点#

验证与上线路径#

1. 本地冒烟：curl http://127.0.0.1:8000/v1/chat/completions 发一条测试消息。
2. 压测：用小工具打 10 并发，看 TTFT / TPOT / 显存（vLLM 指标里都有）。
3. 调整：显存紧张就降 --gpu-memory-utilization 或 --max-num-seqs。
4. 上线：Nginx 挂 TLS + API Key，Prometheus/Grafana 看板挂好。

分层架构#

1
客户端/前端
2
   │  HTTPS
3
   ▼
4
┌─────────────────────────────┐
5
│  BFF / 业务服务 (FastAPI)     │  ← 后端开发的主战场
6
│  鉴权 · 租户 · 限流 · 计费 ·    │
7
│  编排 · 缓存 · 路由 · 重试      │
8
└──────────────┬──────────────┘
9
               │  internal HTTP (OpenAI 兼容)
10
               ▼
11
┌─────────────────────────────┐
12
│  vLLM 推理服务 (单实例)        │  ← 基础设施，屏蔽细节
13
└─────────────────────────────┘

核心原则：业务服务是「唯一入口」，vLLM 是「可替换的推理后端」。这样以后换引擎（SGLang/TensorRT）、换模型、加 GPU，前端和业务代码都不用动。

统一 API 层（对外契约）#

对外暴露你自己的接口，而不是直接把 vLLM 的 OpenAI 接口透传出去——这样你可以控制协议、加字段、做版本管理。

1
# 请求体设计
2
class ChatRequest(BaseModel):
3
    messages: list[Message]      # 对话历史
4
    temperature: float = 0.7     # 白名单参数，别让用户传任意值
5
    max_tokens: int = 2048       # 有上限，防烧钱
6
    user_id: str                 # 租户/用户标识（计费、限流用）
7
    stream: bool = False         # 是否流式
8

9
# 响应体
10
class ChatResponse(BaseModel):
11
    id: str
12
    reply: str
13
    usage: Usage                 # token 数，用于计费/审计
14
    latency_ms: int

设计要点：

• 参数白名单化：只暴露 Temperature / Top_P / Max_Tokens 等几个，不暴露 --gpu-memory-utilization 这类基础设施参数。
• 统一 Trace ID：每个请求带 x-request-id，贯穿业务服务 → vLLM → 日志 → 监控，排查问题全靠它。

流式与协议处理#

• 流式：stream=True 时用 SSE（Server-Sent Events）转发 vLLM 的 token 流，逐 token 吐给前端，改善首字延迟体感。
• 非流式：等 vLLM 完整返回再回包。
• 超时控制：vLLM 单请求可能生成很久，业务层要设超时（如 120s）和取消传播（asyncio 取消请求时同步取消上游 fetch）。

鉴权与多租户#

• API Key 鉴权：业务层先校验 Key → 映射到租户/用户 → 生成请求上下文。
• 租户隔离：不同租户的 QPS、并发、token 配额分开限制（concurrency 按租户切分，防止一个租户打满 10 并发饿死别人）。
• 配额/计费：按 usage.total_tokens 记 Mock 计费，写审计日志。

限流与并发控制（关键！）#

vLLM 只有 10 并发，这是全系统最硬的约束，业务层必须做并发闸门：

1
# 轻量信号量做并发闸门，超过即排队或返回 429
2
semaphore = asyncio.Semaphore(10)
3

4
async def chat(req):
5
    if semaphore.locked():
6
        # 超额定，返回 429 + Retry-After，或进队列
7
        raise HTTPException(429, "server busy")
8
    async with semaphore:
9
        return await engine_call(req)

• 队列 vs 拒绝：10 并发满时，选「排队（带超时）」还是「直接 429」？建议：短请求排队、长请求 429，避免队头阻塞。
• 区分层：业务层限流（限业务量）+ vLLM 内部 --max-num-seqs（兜底），两层叠闸。

缓存层#

• 精确命中缓存：相同 prompt 的重复请求（如常见 QA）直接返回缓存，不进推理，省 GPU 又降延迟。
• 语义缓存（可选）：RAG 场景做 embedding 相似度去重，能大幅降负载。
• 会话管理：多轮对话的历史存 Redis，别每次全量重传。

错误处理与重试#

• vLLM 侧错误：区分「可重试」（超时、503 瞬时）和「不可重试」（400 参数错误、模型加载失败）。
• 重试策略：指数退避 + 抖动，但要小心——生成到一半的重试会浪费 token，只对「未开始生成」的请求重试。
• 降级：vLLM 挂了时，返回友好错误或降级到小模型/规则回复，别让用户看到 500 裸奔。

数据流与状态管理#

1
业务请求 → 校验 → 限流 → 并发闸门 → 拼 prompt → 调 vLLM → 解析 → 校验输出 → 缓存 → 落库 → 返回

• 无状态业务服务：业务服务本身无状态（可水平扩展多个副本），有状态的部分（会话、缓存、配额）全部放 Redis/DB。
• 单点瓶颈：vLLM 是唯一有状态单点。如果未来要扩并发，要么加 GPU 做多实例 + 负载均衡，要么上 vLLM 的分布式（PVC/DeepSeek 风格），但 10 并发阶段不需要。

后端工程化要点#

目录结构（可直接落地的骨架）#

1
app/
2
├── main.py              # FastAPI 入口
3
├── config.py            # 配置（pydantic-settings）
4
├── api/
5
│   ├── chat.py          # 对话路由
6
│   └── health.py        # 健康检查
7
├── core/
8
│   ├── auth.py          # API Key 鉴权
9
│   ├── ratelimit.py     # 限流
10
│   ├── concurrency.py   # 并发闸门
11
│   └── tracing.py       # trace_id 注入
12
├── services/
13
│   ├── llm_client.py    # vLLM 客户端（OpenAI 兼容）
14
│   ├── cache.py         # 缓存
15
│   └── quota.py         # 配额/计费
16
├── models/
17
│   └── schemas.py       # Pydantic 模型
18
├── tests/
19
│   ├── docker-compose.yml
20
│   └── nginx.conf