参考资料

• Hugging Face PEFT
• vLLM 文档

模型工程（03） - 模型部署与本地调用

读完后，你应能完成以下任务：

• 绘制“模型工程（04） - 模型部署与本地调用 / 三种用法的取舍”的关键对象与数据流，解释“选型主线很清楚：起步和验证用云端 API，数据合规或量大了转自部署，本地开发和离线场景用 Ollama。”，并用源码位置、日志或 Trace 标注证据。
• 为“模型工程（04） - 模型部署与本地调用 / OpenAI 兼容接口：业界的通用插座”设计正常与异常输入，验证“「OpenAI 兼容」指一个模型服务暴露的接口，长得和 OpenAI 的 POST /v1/chat/completions 一模一样——请求体、响应体结构都对齐。”，输出首个偏差位置与回归测试结果。
• 实现“模型工程（04） - 模型部署与本地调用 / 客户端代码：换 base_url 就够了”的最小代码或配置，检验“这就是接口标准化的威力。”，输出命令、结果与 Diff，并说明不适用边界。

一、与进阶篇的分工

本篇保留为本地模型调用和部署入门。进阶模型原理与生命周期请读 89《图解 Transformer 架构》和 90《大模型训练、推理全流程详细图解》，它们会解释 token、attention、训练、微调和推理优化的边界。

二、模型部署与本地调用的真实应用场景

你的 AI 应用一直调 OpenAI。某天合规同学说："客户数据不能出公司，模型得部署在我们自己服务器上。"

你慌了一下：是不是要把所有调模型的代码重写一遍？打开代码一看——只要把 base_url 从 OpenAI 改成自部署服务的地址，api_key 换一下，其余一行不用动。因为你自部署用的 vLLM 暴露的也是「OpenAI 兼容接口」。

这就是这一篇的核心：模型在哪、是谁的，对客户端代码是透明的，只要大家都遵守 OpenAI 那套接口约定。 搞懂这一点，模型部署的选型就清晰了。

三、三种用法的取舍

方式	怎么用	适合	代价
云端 API	直接调 OpenAI/通义/智谱	快速起步、不想管运维	数据出公司、按量付费、有网络依赖
自部署	vLLM/TGI 把开源模型部署到自己服务器	数据合规、量大省成本、要定制	要 GPU、要运维、要会调优
本地模型	Ollama/LMStudio 在本机跑小模型	开发调试、离线、隐私	受本机算力限制，大模型跑不动

选型主线很清楚：起步和验证用云端 API，数据合规或量大了转自部署，本地开发和离线场景用 Ollama。 而它们能平滑切换的前提，是下面这个接口约定。

四、OpenAI 兼容接口：业界的通用插座

「OpenAI 兼容」指一个模型服务暴露的接口，长得和 OpenAI 的 POST /v1/chat/completions 一模一样——请求体、响应体结构都对齐。

请求体长这样（关键是 messages 多轮对话数组）：

{
  "model": "任意模型名",
  "messages": [{"role": "user", "content": "你好"}]
}

响应体长这样（关键是 choices[0].message.content 和 usage）：

{
  "choices": [{"message": {"role": "assistant", "content": "你好，我是..."}}],
  "usage": {"prompt_tokens": 2, "completion_tokens": 32, "total_tokens": 34}
}

只要服务端按这个结构来，客户端就能用同一套解析代码。Ollama、vLLM、智谱、通义、DeepSeek 全都提供 OpenAI 兼容接口，正是为了让你无痛切换。它像电源的标准插座：插头一样，背后是火电还是水电不影响你用。

五、客户端代码：换 base_url 就够了

通用客户端的核心就是构造标准请求、解析标准响应：

切换模型只改 BASE_URL：

本地 mock   → http://localhost:8039
Ollama      → http://localhost:11434/v1
真实 OpenAI → https://api.openai.com/v1  + 真实 key
vLLM 自部署 → http://你的服务器:8000/v1

chat 函数对这四种全通用。这就是接口标准化的威力。

六、工程上真正会踩的坑

• 以为切模型要改一堆代码。只要都走 OpenAI 兼容接口，改 base_url 和 key 就行。要是发现切个模型要大改，说明客户端代码没抽象好。
• 本地模型当生产用。Ollama 在笔记本上跑 7B 模型做开发很爽，但并发能力、响应速度撑不住生产流量。本地模型主要用于开发、调试、离线。
• 自部署忽略显存和并发。vLLM 部署不是起个服务就完事，模型多大、显存够不够、并发量多少、要不要量化，每个都影响能不能扛住。
• token 用量不监控。OpenAI 响应里的 usage 是成本的直接来源，不记录就不知道钱花哪了。每次调用都该把 usage 落日志（这是下一篇和生产工程（10）《成本控制与缓存》的事）。

七、一句话面试答法

模型部署你怎么选，切换模型成本高吗？ 起步和快速验证用云端 API；数据不能出公司或调用量大了，用 vLLM 自部署开源模型；本地开发和离线场景用 Ollama。它们之间切换成本很低，因为大家都提供「OpenAI 兼容接口」——请求和响应结构都对齐 /v1/chat/completions，我的客户端代码只要换 base_url 和 key，逻辑一行不改。所以我写调用代码时会把 base_url 做成配置，方便随时切。

八、动手实践：39 模型部署与本地调用

一个兼容 OpenAI 接口格式的 mock 本地模型服务（标准库 http.server），加一段对「mock / 真实 OpenAI / Ollama」通用的客户端代码。一条命令自动起服务 + 调用 + 打印结果。

8.1 运行

python3 main.py

零依赖，纯标准库，离线可跑。自动起 mock 模型服务、用客户端调两次、打印结果后自动关闭。

8.2 预期输出

mock 模型服务已启动：http://localhost:8039/v1/chat/completions

请求：你好
回答：你好，我是本地 mock 模型，接口和 OpenAI 完全兼容。
用量：{'prompt_tokens': 2, 'completion_tokens': 32, 'total_tokens': 34}

请求：请帮我总结一下 RAG 是什么
回答：我收到了你的问题：「请帮我总结一下 RAG 是什么」。这是 mock 模型的回答。
用量：{'prompt_tokens': 15, 'completion_tokens': 41, 'total_tokens': 56}

8.3 代码 ↔ 概念对应

概念	在 main.py 哪里
OpenAI 兼容接口路径	MockModelHandler.do_POST 里 /v1/chat/completions
OpenAI 请求结构（model + messages）	chat 里构造的 req_body
OpenAI 响应结构（choices/message/usage）	服务端返回的 response
模型推理（真实模型在这做）	_fake_infer
通用客户端（换 BASE_URL 即可切换）	chat
token 用量统计	response["usage"]

8.4 核心认知

无论模型是 OpenAI 云端、还是你用 vLLM / Ollama / LMStudio 自部署在本地，只要都暴露「OpenAI 兼容接口」（POST /v1/chat/completions，请求/响应结构一致），客户端代码一行不改就能切换。

本地 mock     → BASE_URL = http://localhost:8039
Ollama 本地   → BASE_URL = http://localhost:11434/v1
真实 OpenAI   → BASE_URL = https://api.openai.com/v1  + 真实 API Key
vLLM 自部署   → BASE_URL = http://你的服务器:8000/v1

chat 函数对这四种情况通用。这就是为什么业界都往「OpenAI 兼容」上靠。

8.5 动手改

• 把 _fake_infer 改聪明一点，加更多规则回答。
• 装了 Ollama 的话，把 BASE_URL 改成 http://localhost:11434/v1、model 改成 llama3，chat 函数直接能调真实本地模型。
• 给服务加一个 /v1/models 接口（OpenAI 也有），返回可用模型列表。

九、总结

• 与进阶篇的分工：进阶模型原理与生命周期请读 89《图解 Transformer 架构》和 90《大模型训练、推理全流程详细图解》，它们会解释 token、attention、训练、微调和推理优化的边界。
• 三种用法的取舍：选型主线很清楚：起步和验证用云端 API，数据合规或量大了转自部署，本地开发和离线场景用 Ollama。
• OpenAI 兼容接口：业界的通用插座：「OpenAI 兼容」指一个模型服务暴露的接口，长得和 OpenAI 的 POST /v1/chat/completions 一模一样——请求体、响应体结构都对齐。
• 工程上真正会踩的坑：要是发现切个模型要大改，说明客户端代码没抽象好。
• 一句话面试答法：起步和快速验证用云端 API；

9.1 实现源码与运行边界

main.py