01 模型部署实战指南

学习理念：开发环境的模型是本地加载的，生产环境必须拆成独立服务。本章讲的就是怎么把 Ch19 掌柜智库中用到的三个模型（LLM + Embedding + Reranker）从本地调用改为远程 HTTP 服务，部署到独立的 GPU 服务器上。

---

📖 阅读优先级

等级	章节	说明
🔴 值得跑通	vLLM 部署 LLM	Agent 部署必用工具
🟡 理解即可	BGE + Reranker 服务化	用到时再回来看
🟢 了解即可	多服务器架构	知道架构思路就行

---

一、最终架构

┌──────────────────────────────────────────────────────┐
│ 模型服务器 A：Embedding / Rerank                     │
│   - BGE-M3:       :8101 /v1/embeddings               │
│   - bge-reranker: :8102 /v1/rerank                   │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│ 模型服务器 B：LLM                                     │
│   - Qwen3-8B vLLM: :8100 /v1/chat/completions         │
└──────────────────────────────────────────────────────┘

业务服务器：
  shopkeeper_brain（MinerU / Milvus / Neo4j / MongoDB / MinIO）

核心原则：模型服务与业务服务分离。业务服务器只运行业务代码，模型推理交给专门的 GPU 服务器。

---

二、vLLM 部署 LLM

🔴【值得跑通】 vLLM 是 LLM 推理部署的事实标准，和之前 Ch21 讲的 Continuous Batching 原理对应。

2.1 启动 vLLM 服务

# 部署 Qwen3-8B（需要 1 张 24GB 以上显卡）
python -m vllm.entrypoints.openai.api_server \
    --model /data/models/Qwen3-8B \
    --host 0.0.0.0 \
    --port 8100 \
    --dtype bfloat16 \
    --gpu-memory-utilization 0.9 \
    --max-model-len 4096

参数	作用
--model	模型路径（本地路径或 HuggingFace 模型名）
--dtype bfloat16	半精度加载，省一半显存
--gpu-memory-utilization 0.9	显存利用率，留 10% 给其他进程
--max-model-len 4096	最大上下文长度

2.2 验证 vLLM 服务

# 测试 OpenAI 兼容接口
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/data/models/Qwen3-8B",
    "messages": [{"role": "user", "content": "你好"}]
  }'

2.3 修改业务代码调用远端 LLM

# 原：本地直接加载模型
llm = ChatOpenAI(api_key="...", base_url="...")

# 改：调用远端 vLLM 服务
from openai import OpenAI
client = OpenAI(
    base_url="http://192.168.11.122:8100/v1",
    api_key="not-needed"  # vLLM 默认不校验 key
)

---

三、部署 BGE-M3 Embedding 服务

🟡【理解即可】 把 Embedding 模型从本地 pymilvus.model.hybrid.BGEM3EmbeddingFunction 改为 HTTP 服务。

3.1 启动 BGE-M3 服务

BGE-M3 需要自己写一个简单的 FastAPI 包装（伪代码）：

# model_server/bge_m3_service.py
from fastapi import FastAPI
from pymilvus.model.hybrid import BGEM3EmbeddingFunction

app = FastAPI()
model = BGEM3EmbeddingFunction(
    model_name="/data/models/bge-m3",
    device="cuda"
)

@app.post("/v1/embeddings")
async def embed(request: EmbeddingRequest):
    dense = model.encode_documents(request.input)
    sparse = model.encode_documents_sparse(request.input)
    return {
        "dense": dense.tolist(),
        "sparse": sparse,
    }

# 启动
uvicorn bge_m3_service:app --host 0.0.0.0 --port 8101

3.2 修改业务代码调用远端 Embedding

# 原：本地加载模型
bge_m3 = BGEM3EmbeddingFunction(model_name="/data/models/bge-m3", device="cuda")

# 改：调用远端服务
import requests
response = requests.post(
    "http://192.168.11.121:8101/v1/embeddings",
    json={"input": texts}
)

---

四、部署 Reranker 服务

🟡【理解即可】 和 BGE-M3 类似，把本地 FlagReranker 改为 HTTP 服务。

4.1 启动 Reranker 服务

# model_server/reranker_service.py
from fastapi import FastAPI
from FlagEmbedding import FlagReranker

app = FastAPI()
model = FlagReranker("/data/models/bge-reranker-large", use_fp16=True)

@app.post("/v1/rerank")
async def rerank(request: RerankRequest):
    scores = model.compute_score(
        [(request.query, doc) for doc in request.documents]
    )
    return {"scores": scores}

# 启动
uvicorn reranker_service:app --host 0.0.0.0 --port 8102

---

五、部署后调用关系总图

用户请求 → shopkeeper_brain 业务服务
                ↓
       ├─ LLM 调用 → vLLM (Qwen3-8B)        :8100
       ├─ Embedding → BGE-M3 FastAPI         :8101
       └─ Reranker → Reranker FastAPI        :8102

关键改动清单

项目	开发环境	生产环境
LLM	ChatOpenAI 本地加载	vLLM 远程 API
BGE-M3	pymilvus 本地模型	FastAPI 远程服务
Reranker	FlagReranker 本地模型	FastAPI 远程服务
服务器	单台	分离 2-3 台

---

六、本阶段文件索引

优先级	文件	路径
🔥 P0	GPU模型部署.md	应用模型部署/课件/GPU模型部署.md
🟡 P1	生产环境服务部署.md	应用模型部署/课件/生产环境服务部署.md