随着开源大模型的爆发式增长，在本地与服务端部署 AI 大模型已成为开发者的核心技能。本文将从本地运行、API 服务化、Docker 容器封装三个维度，给出完整的生产级部署方案。
一、整体架构概览
| 阶段 | 内容 |
|---|---|
| 开发调试 | 模型选择与下载、本地直接运行 |
| 团队协作 | API 服务化 |
| 生产交付 | Docker 容器封装 |
| 技术栈 | llama.cpp / vLLM / Ollama, FastAPI + vLLM / TGI, Dockerfile + docker-compose |
| 运维 | 性能调优、监控与运维 |
二、模型选型与技术栈（2026 主流方案）
| 维度 | 推荐方案 | 适用场景 |
|---|---|---|
| 本地推理 | llama.cpp / Ollama | 个人开发、低资源环境 |
| GPU 推理 | vLLM / TGI | 高并发、低延迟 |
| API 框架 | FastAPI | 轻量、高性能 |
| 容器化 | Docker + NVIDIA Container Toolkit | 标准化部署 |
| 编排 | docker-compose / K8s | 多服务协同 |
2026 年主流推理引擎市场份额估算：vLLM, Ollama, llama.cpp, TGI, TensorRT-LLM 等。
三、方案一：本地运行大模型
3.1 环境准备
# 创建独立虚拟环境
python -m venv llm-env
source llm-env/bin/activate # Linux/macOS
# llm-env\Scripts\activate # Windows
# 安装核心依赖
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install transformers accelerate sentencepiece
3.2 使用 transformers 加载模型
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
model_id = "Qwen/Qwen2.5-72B-Instruct-GPTQ-Int4"
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
model_id,
device_map="auto", # 自动分配 GPU/CPU
torch_dtype=torch.float16,
trust_remote_code=True,
)
def chat(prompt: str, max_new_tokens: int = 512) -> str:
messages = [{"role": "user", "content": prompt}]
input_ids = tokenizer.apply_chat_template(
messages, return_tensors="pt"
).to(model.device)
with torch.no_grad():
outputs = model.generate(
input_ids,
max_new_tokens=max_new_tokens,
temperature=0.7,
top_p=0.9,
do_sample=True,
)
response = tokenizer.decode(
outputs[0][input_ids.shape[-1]:], skip_special_tokens=True
)
return response
if __name__ == "__main__":
result = chat("用 Python 写一个快速排序算法，并解释其时间复杂度。")
print(result)
3.3 使用 llama.cpp 进行 CPU/GPU 推理
# 安装 llama-cpp-python（带 CUDA 支持）
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
# 下载 GGUF 格式模型
huggingface-cli download \
Qwen/Qwen2.5-7B-Instruct-GGUF \
qwen2.5-7b-instruct-q4_k_m.gguf \
--localdir ./models
from llama_cpp import Llama
llm = Llama(
model_path="./models/qwen2.5-7b-instruct-q4_k_m.gguf",
n_ctx=4096,
n_gpu_layers=-1, # 全部卸载到 GPU
verbose=False,
)
response = llm.create_chat_completion(
messages=[{"role": "user", "content": "解释 Transformer 的自注意力机制"}],
temperature=0.7,
max_tokens=1024,
)
print(response["choices"][0]["message"]["content"])
四、方案二：API 服务化
4.1 架构流程
客户端 → Nginx 反向代理 → FastAPI 服务 → vLLM 推理引擎 → GPU / 模型权重 Redis 队列用于缓冲请求。
4.2 使用 vLLM 启动高性能推理服务
# 直接以 OpenAI 兼容模式启动
python -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen2.5-72B-Instruct-GPTQ-Int4 \
--served-model-name qwen-72b \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 4096 \
--gpu-memory-utilization 0.90 \
--tensor-parallel-size 2
客户端调用示例：
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="not-needed", # 本地部署无需密钥
)
response = client.chat.completions.create(
model="qwen-72b",
messages=[
{"role": "system", "content": "你是一位资深 Python 工程师。"},
{"role": "user", "content": "如何优化 asyncio 的并发性能？"},
],
temperature=0.7,
max_tokens=2048,
)
print(response.choices[0].message.content)
4.3 使用 FastAPI 自建 API 服务
# api_server.py
import uuid
import time
from contextlib import asynccontextmanager
import torch
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from transformers import AutoModelForCausalLM, AutoTokenizer
# ---------- 全局模型 ----------
model = None
tokenizer = None
@asynccontextmanager
async def lifespan(app: FastAPI):
"""应用生命周期：启动时加载模型，关闭时释放资源。"""
global model, tokenizer
model_id = "Qwen/Qwen2.5-14B-Instruct-GPTQ-Int4"
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
model_id,
device_map="auto",
torch_dtype=torch.float16,
trust_remote_code=True,
)
yield
del model, tokenizer
torch.cuda.empty_cache()
app = FastAPI(title="LLM API Service", lifespan=lifespan)
# ---------- 请求/响应模型 ----------
class ChatRequest(BaseModel):
prompt: str = Field(..., min_length=1, max_length=8192)
max_tokens: int = Field(default=1024, ge=1, le=4096)
temperature: float = Field(default=0.7, ge=0.0, le=2.0)
class ChatResponse(BaseModel):
id: str
response: str
usage_tokens: int
latency_ms: float
# ---------- 推理接口 ----------
@app.post("/v1/chat", response_model=ChatResponse)
async def chat_completion(req: ChatRequest):
if model is None:
raise HTTPException(status_code=503, detail="模型尚未加载完成")
start = time.perf_counter()
input_ids = tokenizer.apply_chat_template(
[{"role": "user", "content": req.prompt}],
return_tensors="pt",
).to(model.device)
with torch.no_grad():
outputs = model.generate(
input_ids,
max_new_tokens=req.max_tokens,
temperature=req.temperature,
top_p=0.9,
do_sample=True,
)
generated = outputs[0][input_ids.shape[-1]:]
text = tokenizer.decode(generated, skip_special_tokens=True)
latency = (time.perf_counter() - start) * 1000
return ChatResponse(
id=str(uuid.uuid4()),
response=text,
usage_tokens=len(generated),
latency_ms=round(latency, 2),
)
# ---------- 健康检查 ----------
@app.get("/health")
async def health():
return {
"status": "ok",
"model_loaded": model is not None,
"gpu_available": torch.cuda.is_available(),
}
启动服务：
uvicorn api_server:app --host 0.0.0.0 --port 8000 --workers 1
五、方案三：Docker 容器封装
5.1 Dockerfile
# ---------- 构建阶段 ----------
FROM nvidia/cuda:12.4.1-devel-ubuntu22.04 AS builder
ENV DEBIAN_FRONTEND=noninteractive \
PYTHONUNBUFFERED=1
RUN apt-get update && apt-get install -y --no-install-recommends \
python3.11 python3.11-venv python3-pip \
&& rm -rf /var/lib/apt/lists/*
RUN python3.11 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt /tmp/requirements.txt
RUN pip install --no-cache-dir -r /tmp/requirements.txt
# ---------- 运行阶段 ----------
FROM nvidia/cuda:12.4.1-runtime-ubuntu22.04
RUN apt-get update && apt-get install -y --no-install-recommends \
python3.11 \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY api_server.py .
EXPOSE 8000
CMD ["uvicorn", "api_server:app", "--host", "0.0.0.0", "--port", "8000"]
5.2 docker-compose.yml
version: "3.9"
services:
llm-api:
build:
context: .
dockerfile: Dockerfile
container_name: llm-api-server
ports:
- "8000:8000"
volumes:
- ~/.cache/huggingface:/root/.cache/huggingface # 模型缓存持久化
environment:
- NVIDIA_VISIBLE_DEVICES=all
- MODEL_ID=Qwen/Qwen2.5-14B-Instruct-GPTQ-Int4
- MAX_MODEL_LEN=4096
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
redis:
image: redis:7-alpine
container_name: llm-redis
ports:
- "6379:6379"
restart: unless-stopped
5.3 构建与运行
# 构建镜像
docker-compose build
# 启动服务（后台运行）
docker-compose up -d
# 查看日志
docker-compose logs -f llm-api
# 测试接口
curl -X POST http://localhost:8000/v1/chat \
-H "Content-Type: application/json" \
-d '{"prompt": "解释 Docker 的多阶段构建", "max_tokens": 512}'
六、性能调优要点
GPU 显存占用分布（典型 72B Int4 模型）：模型权重、KV Cache、激活值、框架开销及可用余量。
关键调优参数
| 参数 | 说明 | 推荐值 |
|---|---|---|
gpu_memory_utilization | GPU 显存使用率上限 | 0.85 ~ 0.95 |
max_model_len | 最大上下文长度 | 按需设置，影响 KV Cache |
tensor_parallel_size | 张量并行 GPU 数 | 匹配物理 GPU 数 |
quantization | 量化方法 | GPTQ-Int4 / AWQ |
enforce_eager | 禁用 CUDA Graph（调试用） | 生产环境关闭 |
# 性能基准测试脚本
import time
import statistics
import requests
API_URL = "http://localhost:8000/v1/chat"
PROMPT = "请用 200 字介绍 Python 的 GIL 机制。"
NUM_REQUESTS = 50
latencies = []
for i in range(NUM_REQUESTS):
start = time.perf_counter()
resp = requests.post(API_URL, json={"prompt": PROMPT, "max_tokens": 256})
latencies.append((time.perf_counter() - start) * 1000)
print(f"请求次数：{NUM_REQUESTS}")
print(f"平均延迟：{statistics.mean(latencies):.1f} ms")
print(f"P50 延迟：{statistics.median(latencies):.1f} ms")
print(f"P95 延迟：{sorted(latencies)[int(len(latencies)*0.95)]:.1f} ms")
print(f"吞吐量：{NUM_REQUESTS /(sum(latencies)/1000):.1f} req/s")
七、生产部署检查清单
| 检查项 | 工具/方案 |
|---|---|
| GPU 监控 | nvidia-smi dmon、Prometheus DCGM Exporter |
| API 指标 | Prometheus + Grafana |
| 日志 | Loki / ELK Stack |
| 限流 | FastAPI slowapi 或 Nginx limit_req |
| 模型版本 | MLflow / DVC |
| 安全 | API Key 鉴权 + 输入长度/内容过滤 |
八、总结
本文覆盖了 Python AI 大模型部署的三大核心路径：
- 本地运行 — 适合开发调试，使用
transformers或llama.cpp快速启动 - API 服务化 — 使用 vLLM 或 FastAPI 提供 OpenAI 兼容接口，支持高并发推理
- Docker 封装 — 标准化交付，配合
docker-compose实现一键部署
生产环境中建议以 vLLM + Docker + Nginx + Prometheus 为基础技术栈，并根据实际 QPS 和模型规模水平扩展 GPU 节点。
参考资源： vLLM 官方文档：https://docs.vllm.ai llama.cpp 仓库：https://github.com/ggerganov/llama.cpp Hugging Face Transformers：https://huggingface.co/docs/transformers
