阶段4(下):LangChain 1.x、提示词与注入防护、模型侧(路由/vLLM/LoRA)、AI 编程工具与验证、Dify/Coze 专题

This commit is contained in:
Shikui Wang committed 2026-10-23 16:15:33 +08:00
1 parent caaec830b3
commit 7a32d2c9a6
38 files changed
+3059 -67

No files matched your search

@@ -0,0 +1,113 @@
---
id: ai.llm-serving.routing-vllm-lora
title: 模型侧基础:多模型接入和路由、vLLM 部署、LoRA / QLoRA 概念
type: lesson
domain: ai
stack: [llm-serving]
tags: [多模型路由, OpenAI 兼容接口, 降级, 熔断, vLLM, 量化, LoRA, QLoRA, 微调]
level: intermediate
prerequisites: [python.asyncio.concurrency-control]
est_hours: 3
related: [ai.agent-ops.observability-cost, ai.llm-serving.scenario.multi-provider-gateway, ai.llm-serving.interview]
week: [10, 13]
order: 1
---
# 模型侧基础:多模型接入和路由、vLLM 部署、LoRA / QLoRA 概念
> 本课定位是**了解级**:应用开发岗位面试会问到“模型怎么接、怎么部署、什么时候微调”,能讲清楚原理和取舍即可,不要求会训练模型。vLLM 等工具参数变化快,以官方文档为准:https://docs.vllm.ai/
## 解释说明
### 1. 多模型接入和路由
企业里通常同时使用多个模型:不同厂商的大模型、便宜的小模型、自部署的开源模型。**统一接入层**(自建网关或 LiteLLM 这类开源网关)负责:
| 功能 | 说明 |
| --- | --- |
| 统一接口 | 大多数厂商和 vLLM 都提供 **OpenAI 兼容接口**,业务代码用同一套 SDK,只换 `base_url` 和模型名 |
| 按任务路由 | 分类、改写用小模型;复杂推理用大模型;敏感数据只走自部署模型 |
| 超时、重试 | 限流(429)退避后重试;故障 / 超时换下一个提供方 |
| 熔断 | 某个提供方连续失败时暂时跳过,冷却后试探 |
| 降级 | 主模型不可用时切备用;都不可用时返回友好提示 |
| 配额和成本 | 按业务方 / 用户限额;记录每次调用的 token 和成本 |
| 密钥管理 | 业务方不直接持有厂商密钥 |
### 2. vLLM 部署基础
vLLM 是常用的开源大模型推理服务框架:
- 核心技术:**PagedAttention**(像操作系统分页一样管理 KV 缓存,减少显存浪费)和**连续批处理**(请求随到随加入批次),吞吐量高。
- 启动:`vllm serve <模型名或路径>`,默认在 8000 端口提供 OpenAI 兼容接口(`/v1/chat/completions`)。
- 常用参数:`--tensor-parallel-size`(多卡切分)、`--max-model-len`(最大上下文,影响显存)、`--gpu-memory-utilization`(显存占用比例)、`--quantization`(量化)。
- 显存粗估:参数量 × 每个参数的字节数(FP16 为 2 字节),7B 模型权重约 14GB,另外还需要 KV 缓存空间;量化到 4 bit 后权重约 4GB 左右。
- 同类工具:SGLang、TGI、Ollama(本地体验)、llama.cpp。
自部署的理由:数据不能出内网、调用量很大时成本更低、需要定制模型。代价:GPU 成本、运维、模型效果通常不如顶级商用模型。
### 3. 微调和 LoRA / QLoRA(概念)
| 方法 | 说明 |
| --- | --- |
| 全量微调 | 更新全部参数,效果上限高,显存和数据要求高 |
| **LoRA** | 冻结原模型,只训练插在部分层上的低秩矩阵(W + BA,A、B 很小),可训练参数通常不到 1%;训练好的“适配器”文件很小,可以一个底座挂多个适配器 |
| **QLoRA** | 把底座模型量化到 4 bit 再做 LoRA 训练,进一步降低显存,单张消费级显卡也能微调中等规模模型 |
**什么时候需要微调?** 先用提示词 + RAG;当需要固定的输出风格 / 格式、特定领域的表达、用小模型替代大模型降低成本,并且**有足够的高质量标注数据和评测集**时,才考虑微调。知识更新类需求用 RAG,不用微调。
## 案例
公司客服系统:意图分类走便宜的小模型;答案生成走商用大模型,备用另一家厂商;涉及员工身份证、薪资的问题只走内网 vLLM 部署的开源模型。一次主厂商故障,网关在 3 次失败后熔断,自动切到备用厂商,用户基本无感;事后看台账,降级期间成本上升了,但服务没有中断。
## 代码示例
路由、重试、熔断、降级、成本台账(完整版本 [examples/model-router/router.py](examples/model-router/router.py),只用标准库):
```python
async def chat(self, task, messages):
errors = []
for name in self.routes[task]: # 按优先级尝试提供方
p, br = self.providers[name], self.breakers.setdefault(name, Breaker())
if not br.allow():
continue # 熔断中,跳过
for attempt in range(self.max_retries + 1):
try:
r = await p.call(messages, self.timeout)
except RateLimited:
await asyncio.sleep(0.01 * 2 ** attempt) # 限流:退避后重试同一个
continue
except (ProviderDown, asyncio.TimeoutError):
br.record(False)
break # 故障 / 超时:换下一个
br.record(True)
return r
raise RuntimeError("所有模型都不可用")
```
调用自部署的 vLLM(OpenAI 兼容接口,示意):
```python
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="token-local") # vLLM 可用 --api-key 设置
resp = client.chat.completions.create(
model="Qwen/Qwen2.5-7B-Instruct",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```
## 易错点
- 业务代码直接依赖某个厂商的 SDK 特有功能,换模型时大面积修改。
- 所有错误都重试:参数错误、内容审核拒绝重试也没用。
- 降级到备用模型后不记录、不告警,效果下降没人知道。
- 自部署模型的成本只算 token 为 0,忘了 GPU 和运维成本。
- `--max-model-len` 设得过大导致显存不足启动失败,或者并发能力很低。
- 把微调当成“让模型学会公司知识”的方法:知识更新用 RAG。
## 面试常问
- 怎么同时接入多家模型?怎么做降级?
- vLLM 为什么快?
- LoRA 是什么?什么时候需要微调?
@@ -0,0 +1,145 @@
# 只用标准库
"""多模型路由:按任务选模型、超时、限流重试、熔断、备用模型降级、成本统计。
提供方用假实现模拟(延迟、限流、故障),接口形状对应 OpenAI 兼容的 chat 接口;
真实项目中 call() 内部换成 openai SDK(base_url 指向各提供方或自部署的 vLLM)。
运行:python router.py
"""
from __future__ import annotations
import asyncio
import random
import time
from dataclasses import dataclass, field
class RateLimited(Exception):
pass
class ProviderDown(Exception):
pass
@dataclass
class Provider:
name: str
model: str
price_in: float # 元 / 千 token(示例数字,按实际价格配置)
price_out: float
latency: float # 模拟延迟(秒)
fail_mode: str = "ok" # ok / rate_limit_once / down / slow
calls: int = 0
async def call(self, messages: list[dict], timeout: float) -> dict:
self.calls += 1
if self.fail_mode == "down":
raise ProviderDown(f"{self.name} 503")
if self.fail_mode == "rate_limit_once" and self.calls == 1:
raise RateLimited(f"{self.name} 429")
delay = self.latency * (20 if self.fail_mode == "slow" else 1)
await asyncio.wait_for(asyncio.sleep(delay), timeout)
text = f"[{self.model}] 已处理:{messages[-1]['content'][:10]}"
return {"text": text, "tokens_in": 200, "tokens_out": 50}
@dataclass
class Breaker:
"""连续失败 N 次后打开,冷却时间内直接跳过该提供方;冷却后放行一次试探(半开)。"""
threshold: int = 3
cooldown: float = 30.0
failures: int = 0
opened_at: float | None = None
def allow(self) -> bool:
if self.opened_at is None:
return True
return time.monotonic() - self.opened_at >= self.cooldown
def record(self, ok: bool) -> None:
if ok:
self.failures, self.opened_at = 0, None
else:
self.failures += 1
if self.failures >= self.threshold:
self.opened_at = time.monotonic()
@dataclass
class Router:
providers: dict[str, Provider]
routes: dict[str, list[str]] # 任务类型 -> 按优先级排列的提供方
timeout: float = 1.0
max_retries: int = 2
breakers: dict[str, Breaker] = field(default_factory=dict)
ledger: list[dict] = field(default_factory=list)
async def chat(self, task: str, messages: list[dict]) -> dict:
errors = []
for name in self.routes[task]:
p, br = self.providers[name], self.breakers.setdefault(name, Breaker())
if not br.allow():
errors.append(f"{name}: 熔断中,跳过")
continue
for attempt in range(self.max_retries + 1):
t0 = time.perf_counter()
try:
r = await p.call(messages, self.timeout)
except RateLimited as e: # 限流:退避后重试同一个提供方
errors.append(str(e))
await asyncio.sleep(0.01 * 2 ** attempt + random.random() * 0.01)
continue
except (ProviderDown, asyncio.TimeoutError) as e: # 故障 / 超时:换下一个提供方
br.record(False)
errors.append(f"{name}: {type(e).__name__} {e}")
break
br.record(True)
cost = r["tokens_in"] / 1000 * p.price_in + r["tokens_out"] / 1000 * p.price_out
rec = {"task": task, "provider": name, "model": p.model, "ms": round((time.perf_counter() - t0) * 1000),
"cost": round(cost, 5), "fallback": name != self.routes[task][0], "errors": errors}
self.ledger.append(rec)
return {**r, **rec}
raise RuntimeError("所有模型都不可用:" + ";".join(errors))
def build(fail_main: str = "ok") -> Router:
providers = {
"main-large": Provider("main-large", "large-v1", 0.004, 0.016, 0.02, fail_main),
"main-small": Provider("main-small", "small-v1", 0.0005, 0.002, 0.01),
"backup-large": Provider("backup-large", "other-large", 0.006, 0.02, 0.03),
"self-hosted": Provider("self-hosted", "qwen-vllm", 0.0, 0.0, 0.02),
}
routes = {
"classify": ["main-small", "self-hosted"], # 简单任务:小模型
"answer": ["main-large", "backup-large", "self-hosted"], # 复杂任务:大模型 + 备用
"sensitive": ["self-hosted"], # 敏感数据只走自部署模型
}
return Router(providers, routes, timeout=0.2)
async def main() -> None:
r = build()
print(await r.chat("classify", [{"role": "user", "content": "我要退款"}]))
print(await r.chat("sensitive", [{"role": "user", "content": "员工身份证号查询"}]))
r = build(fail_main="rate_limit_once")
out = await r.chat("answer", [{"role": "user", "content": "解释退款政策"}])
print("限流后重试:", out["provider"], out["errors"])
assert out["provider"] == "main-large" and not out["fallback"]
r = build(fail_main="slow")
out = await r.chat("answer", [{"role": "user", "content": "解释退款政策"}])
print("主模型超时后降级:", out["provider"], out["errors"])
assert out["provider"] == "backup-large" and out["fallback"]
r = build(fail_main="down")
for _ in range(4):
await r.chat("answer", [{"role": "user", "content": "q"}])
print("熔断后主模型实际调用次数:", r.providers["main-large"].calls, "(第 4 次直接跳过)")
assert r.providers["main-large"].calls == 3
total = sum(x["cost"] for x in r.ledger)
print(f"成本台账:{len(r.ledger)} 次调用,共 {total:.4f} 元")
if __name__ == "__main__":
asyncio.run(main())
+34 -5
View File
@@ -1,15 +1,44 @@
---
id: ai.llm-serving.index
title: 模型接入与部署(了解级)
title: 模型侧基础(了解级)
type: index
domain: ai
stack: [llm-serving]
tags: []
tags: [多模型路由, vLLM, LoRA, 微调, 模型网关]
week: [10, 13]
---
# 模型接入与部署(了解级)
# 模型侧基础(了解级)
多模型 API 路由与降级、vLLM 部署基础、LoRA / QLoRA 概念。
BOSS直聘 2026-10-23 的调研中约 7 个岗位提到 LoRA / 微调,也有岗位要求多模型接入和 vLLM 部署。本专题定位**了解级**:会多模型接入和降级(这是应用开发每天要做的),能讲清楚 vLLM 和 LoRA 的原理与取舍,不展开模型训练,避免偏离主线。
> 本专题建设中:课程、企业场景、面试题和示例代码会陆续补充。
## 学习路线
| 顺序 | 课程 | 级别 | 预计 |
| --- | --- | --- | --- |
| 1 | [模型侧基础:多模型接入和路由、vLLM 部署、LoRA / QLoRA 概念](01-routing-vllm-lora.md) | 进阶 | 3 小时 |
## 企业场景
- [公司级大模型网关:多厂商路由、配额、敏感数据走内网模型](scenarios/multi-provider-gateway.md)
## 面试题
- [模型侧面试题(了解级)](interview.md)
## 示例代码
- [examples/model-router](examples/model-router/):按任务路由、限流退避重试、超时切换、熔断、备用模型降级、成本台账(只用标准库)
## 在 16 周计划中
- [第 10 周](../../../plan/week10-agent-m1-tools-mcp.md)、[第 13 周](../../../plan/week13-agent-m4-eval-lowcode.md)
## 官方资料
以官方文档为准:
- vLLM:https://docs.vllm.ai/
- LoRA 论文:https://arxiv.org/abs/2106.09685 ;QLoRA 论文:https://arxiv.org/abs/2305.14314
- Hugging Face PEFT:https://huggingface.co/docs/peft
- LiteLLM:https://docs.litellm.ai/
+67
View File
@@ -0,0 +1,67 @@
---
id: ai.llm-serving.interview
title: 模型侧面试题(了解级)
type: interview
domain: ai
stack: [llm-serving]
tags: [模型路由, vLLM, LoRA, 微调, 面试]
level: intermediate
related: [ai.llm-serving.routing-vllm-lora]
week: [13, 16]
---
# 模型侧面试题(了解级)
## 基础
### 【基础】什么是 OpenAI 兼容接口?有什么好处?
**参考答案**:按 OpenAI Chat Completions 的请求和响应格式提供的接口。很多厂商和 vLLM 等推理框架都支持,业务代码用同一个 SDK,只改 `base_url`、密钥和模型名就能切换,降低厂商绑定。
**追问**:兼容就完全一样吗?→ 不是,工具调用、结构化输出、流式细节等可能有差异,切换前要用评测集验证。
### 【基础】token 是什么?成本怎么算?
**参考答案**:模型处理文本的基本单位,由模型的分词器决定,中文和英文的换算比例不同。成本一般 = 输入 token × 输入单价 + 输出 token × 输出单价,输出通常更贵;部分厂商对缓存命中的输入有折扣。
**追问**:怎么在调用前估算 token?→ 用对应模型的分词器计算,或者用经验系数粗估,并在响应中读取实际用量。
### 【基础】什么时候需要微调?
**参考答案**:需要稳定的输出风格 / 格式、特定领域表达、用小模型替代大模型降成本,并且有足够的高质量数据和评测集时。知识更新用 RAG,行为调整先尝试提示词。
**追问**:微调的数据要多少?→ 取决于任务,LoRA 做格式 / 风格调整几百到几千条高质量样本就可能有效;质量比数量重要,必须有评测集验证。
## 进阶
### 【进阶】LoRA 和 QLoRA 的原理?
**参考答案**:LoRA 冻结原模型权重,在部分层旁加两个低秩矩阵(A、B),只训练它们,权重变化表示为 BA,可训练参数很少,适配器文件小,可以一个底座挂多个适配器。QLoRA 把底座量化为 4 bit(NF4)后再做 LoRA,显存需求更低。
**追问**:LoRA 的 rank 怎么选?→ 常见 8~64,任务越复杂可以越大;用评测结果决定,不是越大越好。
### 【进阶】vLLM 为什么吞吐高?
**参考答案**:PagedAttention 用分页方式管理 KV 缓存,减少显存碎片和浪费,同时能服务更多并发请求;连续批处理让新请求随时加入正在运行的批次,GPU 利用率更高。
**追问**:显存不够怎么办?→ 量化(AWQ / GPTQ / FP8 等)、减小 `--max-model-len`、多卡张量并行、换更小的模型。
### 【进阶】多模型降级要注意什么?
**参考答案**:区分可重试错误(限流、超时)和不可重试错误(参数错误、内容拒绝);熔断避免持续打到故障的提供方;备用模型要经过评测;记录降级比例并告警;流式请求在开始输出后失败时不能简单切换(用户已经看到部分内容),要有提示或重新生成的机制。
**追问**:怎么避免降级时成本失控?→ 备用模型也走配额;降级期间对非关键业务限流。
## 场景题
### 【场景题】公司多个业务都要用大模型,怎么统一管理?
**参考答案**:统一网关:OpenAI 兼容接口、业务令牌、逻辑模型名映射到具体厂商、主备和熔断、Redis 配额、调用台账和成本报表、敏感数据走内网模型。详见[模型网关场景](scenarios/multi-provider-gateway.md)。
**追问**:网关自己挂了怎么办?→ 多实例无状态部署,前面有负载均衡;关键业务可以配置直连备用方案(受控的应急开关)。
### 【场景题】业务要求数据不出内网,但开源模型效果不如商用模型,怎么办?
**参考答案**:按数据敏感程度分级:敏感数据走内网模型,非敏感部分可以用商用模型;对内网模型用 RAG 补充知识、优化提示词,必要时用 LoRA 针对具体任务微调;用评测集量化差距,和业务方确认可接受的效果;或者使用云厂商的私有化 / 专属部署方案。
**追问**:内网模型选多大的?→ 根据评测效果、并发需求和 GPU 预算权衡,先用小规模测试确定吞吐和延迟。
@@ -0,0 +1,77 @@
---
id: ai.llm-serving.scenario.multi-provider-gateway
title: 公司级大模型网关:多厂商路由、配额、敏感数据走内网模型
type: scenario
domain: ai
stack: [llm-serving, fastapi, redis]
tags: [模型网关, 多模型路由, 配额, 熔断, 降级, 敏感数据, 成本分摊]
level: advanced
prerequisites: [ai.llm-serving.routing-vllm-lora]
est_hours: 3
related: [ai.llm-serving.interview, python.fastapi.index, backend.redis.lock-ratelimit]
week: [13, 14]
---
# 公司级大模型网关:多厂商路由、配额、敏感数据走内网模型
## 业务背景与问题
公司有十几个业务在用大模型,各自申请厂商账号、各自写调用代码,出现:
1. 某个业务的密钥被写进了前端代码;
2. 一次厂商故障,所有业务同时不可用;
3. 月底账单超预算,不知道是哪个业务用的;
4. HR 系统把员工身份证号发给了外部模型。
## 约束
- 业务方改造成本要低。
- 敏感数据不能出内网。
## 方案设计
1. **统一网关**:提供 OpenAI 兼容接口,业务方只需要改 `base_url` 和使用网关分配的业务令牌;厂商密钥只存在网关。
2. **路由策略**:业务方指定“逻辑模型名”(`chat-large`、`chat-small`、`chat-private`),网关映射到具体的厂商和模型,可以随时调整而不改业务代码。
3. **可用性**:每个逻辑模型配置主备提供方;限流重试、超时切换、熔断;所有提供方都不可用时返回明确的错误码。
4. **配额和成本**:Redis 记录每个业务每分钟请求数和每日 token 数,超限返回 429;调用台账按业务汇总成本,每天推送报表。
5. **敏感数据**:`chat-private` 只路由到内网 vLLM;网关对发往外部的请求做敏感信息检测(身份证号、手机号等),命中时拒绝或脱敏,并告警。
6. **可观测性**:记录每次调用的业务、逻辑模型、实际模型、token、耗时、是否降级;不默认记录完整内容(按需开启并脱敏)。
## 关键代码
网关入口(FastAPI,示意):
```python
@app.post("/v1/chat/completions")
async def chat(req: ChatRequest, app_id: str = Depends(auth_app)):
await quota.check(app_id, tokens_estimate=estimate(req.messages)) # Redis 计数,超限 429
route = ROUTES[req.model] # 逻辑模型名 -> 提供方列表
if not route.private and contains_sensitive(req.messages):
raise HTTPException(400, "请求包含敏感信息,请使用 chat-private 模型")
result = await router.chat(route, req.messages, stream=req.stream)
await ledger.record(app_id=app_id, logical=req.model, provider=result.provider,
tokens_in=result.tokens_in, tokens_out=result.tokens_out, fallback=result.fallback)
return result.response
```
路由、熔断、降级的可运行示例:[examples/model-router](../examples/model-router/)。
## 取舍
| 选择 | 优点 | 缺点 |
| --- | --- | --- |
| **自建网关(本方案)** | 完全可控,能接入公司的鉴权和审计 | 要开发和维护 |
| 开源网关(如 LiteLLM) | 功能现成 | 定制和二次开发有学习成本 |
| 云厂商的模型网关服务 | 免运维 | 绑定云厂商;内网模型接入受限 |
| 各业务自己调用 | 灵活 | 本场景中的所有问题 |
## 易错点
- 网关成为单点:多实例部署、无状态,配额放 Redis。
- 流式响应经过网关时被缓冲(Nginx、中间件),首字延迟变长。
- 敏感信息检测只用简单正则,误报漏报多:结合业务分级,最可靠的是让敏感业务只能用内网模型。
- 降级到备用模型后,输出格式差异导致业务解析失败:备用模型也要在业务评测集上验证。
## 面试怎么讲
> “我们做了一个公司级的模型网关,提供 OpenAI 兼容接口,业务方只换 base_url 和令牌,厂商密钥只在网关里。业务用逻辑模型名,网关映射到具体厂商,主备切换、限流重试、熔断都在网关做。配额用 Redis 计数,台账按业务出成本报表。敏感业务只能用路由到内网 vLLM 的 private 模型,发往外部的请求做敏感信息检测。”