06.7 阶段 6:工程化框架与服务化
所属:全栈开发面试题库 / 学习路径 / 06 AI Agent
本页目录
一、阶段定位
前面你手写的 ReAct 循环能跑通,但那是原型。本阶段解决:把原型做成可对外提供服务的应用——异步 HTTP 接口、流式返回、可观测、可降级、成本可控。这是从"能跑"到"能上线"的关键一跃。
为什么这是阶段 6:手写循环里,业务逻辑散落在 Prompt 和代码里,线上问题没法回放,所有请求都调最贵模型成本失控,模型一抖整个接口就挂。工程化就是用框架把状态图、检查点、trace、缓存、限流、降级补全,让 Agent 像一个正常后端服务一样可观测、可回滚、可灰度。
与前后阶段的衔接:往上接 阶段 5 Agent 编排,那时你手写的循环在框架里变成状态图的节点和边;往下接 阶段 7 安全、评测与生产落地,那时你会在这个服务上加安全边界和评测闭环。跳过本阶段直接上线,常见后果是:业务逻辑散在 Prompt 里、线上问题无法回放、所有请求调旗舰模型成本爆炸、模型抖动时接口整体不可用。
本阶段的卡点(判断依据):
- 把编排框架当银弹,业务逻辑散落在 Prompt 里:现象是换框架后发现业务规则全写在提示词里,无法测试。判断标准:你能否说清哪些逻辑该在代码里、哪些该在 Prompt 里。
- 只在本地跑通原型,没有服务化结构:现象是没有 HTTP 接口、没有异步、没有流式。判断标准:能否用 curl 调一个异步接口并看到 SSE 流式返回。
- 线上问题无法回放,缺 trace:现象是用户说"刚才那次回答错了",你拿不到当时的完整请求与决策过程。判断标准:每次调用是否记录了完整 trace(输入、每步工具、输出、token)。
- 所有请求都调最贵模型,成本失控:现象是简单分类也走旗舰模型。判断标准:能否说出模型分级与语义缓存的作用。
- 不做超时与降级,模型抖动时接口整体不可用:现象是模型 API 慢时你的接口挂起。判断标准:能否说清超时、限流、降级兜底路径。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能把 Agent 封装为异步 HTTP 服务并支持 SSE 流式 | curl 调用看到文字逐块返回 |
| 能说清状态图(节点、边、检查点)对应手写循环的哪部分 | 在框架里复现 ReAct 循环 |
| 关键链路有 trace 可回放 | 能查到一次调用的完整输入/工具/输出 |
| 接入语义缓存与模型分级 | 简单任务走小模型,重复问命中缓存 |
| 有超时、限流与降级路径 | 模型超时时返回兜底而非挂起 |
| Prompt 与模型版本可独立回滚 | 改 Prompt 不发版代码即可回滚 |
建议学时:
- 全职(每天 4–6 小时):2 周,约 50 小时。其中框架与状态图 14 小时、FastAPI 与 SSE 12 小时、trace 与可观测 10 小时、缓存与模型分级 8 小时、限流降级灰度 6 小时。
- 在职(每天 2 小时、周末补 4 小时):4–5 周,约 55 小时。SSE 与 trace 要动手接。
学时分配:框架状态图 25%、服务化 SSE 22%、可观测 trace 18%、成本优化 18%、限流降级灰度 17%。服务化与可观测是重点。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| 手写 Agent 循环 | 能跑通多步 ReAct | 06.6 阶段 5 |
| HTTP 与异步 | 知道 GET/POST、状态码、SSE | 01.2 计算机网络 |
| 后端工程基础 | 知道接口设计、鉴权、配置管理 | 06.1 通用后端工程 |
| 成本结构 | 知道输入输出分别计价 | 06.2 阶段 1 |
经验判断:写过传统后端的人,服务化、限流、灰度这些能力可以直接迁移;需要补的是 LLM 特有的 trace、流式与缓存。
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| 编排框架 | LangGraph 状态图、节点/边/检查点、LlamaIndex、Agents SDK | 会用 | 10.5 LLM 工程化 |
| 服务化 | FastAPI 异步、SSE 流式、接口设计 | 会用 | 06.1 通用后端工程 |
| 可观测 | trace、数据集、LangSmith/Langfuse | 会用 | 10.5 LLM 工程化 |
| 成本优化 | 语义缓存、模型分级、首字延迟 | 会用 | 09.3 缓存体系 |
| 降级限流 | 超时、限流、降级、消息队列削峰 | 会用 | 09.4 消息队列 |
| 版本与灰度 | Prompt 版本、模型版本、灰度发布 | 会用 | 10.5 LLM 工程化 |
进度管理建议:把阶段 5 的手写 Agent 用框架重写一遍,对比两者差异。《知识点全清单》给全量条目;术语查《术语表》。
五、分模块精讲
5.1 编排框架:状态图、节点、边、检查点
为什么需要它:手写 ReAct 循环里,状态(messages、步数、已完成步骤)散落在代码里,难测试、难恢复。编排框架(LangGraph 为代表)把 Agent 抽象成状态图:节点是动作(调模型、调工具),边是条件转移,状态在节点间流动,检查点自动保存。
核心机制:
- 状态图(state graph):定义一个状态对象(如 messages、step、results);节点是函数,接收状态、返回状态更新;边定义下一步去哪个节点。
- 节点(node):调用模型、执行工具、调用子图。
- 边(edge):普通边固定转移;条件边根据状态决定去哪(如模型返回 tool_calls 就去工具节点,否则去结束)。
- 检查点(checkpoint):每步自动保存状态到存储,支持中断恢复、时间旅行调试。
- 其他框架:LlamaIndex 偏 RAG 数据框架;AutoGen 偏多智能体对话;OpenAI Agents SDK 偏轻量编排。Dify/Coze 是可视化平台,适合快速原型,复杂定制会受限。
最小可运行示例:
# langgraph_concept.py:状态图概念示意(对应手写 ReAct)
from typing import TypedDict, Annotated
import operator
class AgentState(TypedDict):
messages: Annotated[list, operator.add] # 消息累加
step: int
def call_model(state: AgentState) -> dict:
# 节点:调模型,返回 messages 增量
return {"messages": [model_decision(state["messages"])], "step": state["step"] + 1}
def call_tools(state: AgentState) -> dict:
# 节点:执行工具,回填结果
return {"messages": execute_pending_tools(state["messages"])}
def should_continue(state: AgentState) -> str:
# 条件边:有 tool_calls 去工具节点,否则结束
last = state["messages"][-1]
return "tools" if last.get("tool_calls") else "end"
# 图结构:模型节点 -> 条件边 -> 工具节点 -> 回到模型节点
# 检查点:每步自动存 state,支持恢复
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 业务规则全在 Prompt 里 | 框架当银弹 | 确定性逻辑放代码节点,Prompt 只管生成 |
| 状态难恢复 | 没用检查点 | 开启 checkpoint 持久化 |
| 可视化平台做到后面改不动 | Dify/Coze 复杂定制受限 | 原型验证后迁到代码框架 |
面试考法:问"LangGraph 的状态图和手写 ReAct 循环是什么关系"。要点:节点=调模型/调工具的函数,边=条件转移,状态在节点间流动;检查点自动保存让中断恢复和调试变容易。追问常问"为什么业务逻辑不要全写在 Prompt 里",答到"确定性规则(权限、校验、路由)放代码可测试,Prompt 只管生成"。
5.2 服务化:FastAPI 异步与 SSE 流式
为什么需要它:手写脚本不能直接对外服务。要把 Agent 暴露成 HTTP 接口,支持并发请求、流式返回(阶段 0 的 SSE),让前端逐字看到回答。
核心机制:
- FastAPI 异步:用
async def接口,httpx.AsyncClient调模型,避免阻塞事件循环。 - SSE 流式:接口返回
EventSourceResponse,模型流式 chunk 逐个 yield 给客户端。 - 接口结构:
POST /chat接收 question,返回流式;会话 ID 标识多轮对话。 - 流式首字延迟(TTFT):用户最关心的指标,越快越好,不要等全部生成完。
最小可运行示例:
# server.py:FastAPI 异步 + SSE
from fastapi import FastAPI
from sse_starlette.sse import EventSourceResponse
import httpx
app = FastAPI()
@app.post("/chat")
async def chat(question: str):
async def event_stream():
async with httpx.AsyncClient() as client:
async with client.stream("POST", f"{BASE_URL}/chat/completions",
headers=auth_header(),
json={"model": MODEL, "messages": [
{"role": "user", "content": question}],
"stream": True},
timeout=60.0) as resp:
async for line in resp.aiter_lines():
if line.startswith("data: ") and line != "data: [DONE]":
yield {"data": line[6:]} # 逐块推给前端
return EventSourceResponse(event_stream())
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 接口并发上不去 | 用了同步 httpx | 改 AsyncClient 与 async def |
| 前端看不到流式逐字 | 网关/Nginx 缓冲了响应 | 关反向代理缓冲,X-Accel-Buffering: no |
| 首字延迟很高 | 等全部生成完才返回 | 逐 chunk yield |
面试考法:问"AI 接口为什么要异步和流式"。要点:异步支撑高并发,流式让用户逐字看到回答、降低首字延迟;同步阻塞会让一个慢请求拖垮整个服务。
5.3 可观测:trace 与数据集
为什么需要它:线上用户说"刚才回答错了",你必须能拿到当时的完整请求、每步工具调用、模型输出、token 用量,才能定位。trace 就是把一次 Agent 运行的全过程记录下来。
核心机制:
- trace 记录:每次调用记录输入 messages、每步节点(模型/工具)、工具入参出参、最终输出、token 用量、延迟。
- 数据集(dataset):把线上 trace 里的 bad case 沉淀成评测集,回归用(阶段 7)。
- 工具:LangSmith、Langfuse 提供 trace 面板,可按会话回放、按 token 成本聚合。
- 日志级别:关键链路全 trace,不要只打错误。
最小可运行示例:
# trace.py:记录一次调用的关键事件
import time, json
class Tracer:
def __init__(self):
self.events = []
def log(self, node: str, payload: dict):
self.events.append({"node": node, "ts": time.time(), "payload": payload})
def dump(self):
return json.dumps(self.events, ensure_ascii=False)
tracer = Tracer()
tracer.log("model_call", {"messages": [...], "usage": {...}})
tracer.log("tool_call", {"name": "get_weather", "args": {...}, "result": {...}})
# 存入数据库或上报到 Langfuse
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 用户反馈错了但查不到当时的输入 | 没记 trace | 关键链路全记录 |
| bad case 没法回归 | 没沉淀成数据集 | trace 里的失败样本入库 |
面试考法:问"线上 AI 应用怎么排查问题"。要点:全链路 trace(输入、每步工具、输出、token、延迟),bad case 沉淀成评测集回归;没有 trace 等于盲人摸象。
5.4 成本与延迟优化:语义缓存、模型分级
为什么需要它:所有请求都调旗舰模型,成本爆炸;重复问题每次都重新生成,浪费钱又慢。
核心机制:
- 语义缓存:把相似问题的回答缓存起来,新问题与缓存里的历史算向量相似度,命中就直接返回(见 09.3 缓存体系)。
- 模型分级:简单任务(分类、抽取、短改写)走小模型,复杂任务走旗舰;按路由规则分发。
- prompt 缓存:重复前缀输入命中厂商缓存(阶段 1)。
- 流式首字延迟:流式本身降 TTFT;小模型首字更快。
最小可运行示例:
# cache_route.py:语义缓存 + 模型分级
def answer(question: str) -> str:
# 1. 先查语义缓存
hit = semantic_cache_lookup(question)
if hit:
return hit
# 2. 按复杂度选模型
model = pick_model(question) # 简单->小模型,复杂->旗舰
result = call_model(question, model=model)
semantic_cache_set(question, result)
return result
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 简单分类也走旗舰模型 | 没分级 | 按任务路由到小模型 |
| 重复问每次都重新生成 | 没语义缓存 | 相似问题命中缓存 |
| 缓存命中了过期答案 | 文档更新后缓存失效 | 缓存设 TTL,文档更新时失效 |
面试考法:问"怎么降低 AI 应用成本"。要点:语义缓存命中相似问题、模型分级简单任务走小模型、prompt 缓存命中重复前缀、非实时走批量、控制 max_tokens。
5.5 降级、限流与超时
为什么需要它:模型 API 会抖动、会限流、会挂。你的服务不能跟着挂,要像正常后端一样有超时、限流、降级兜底。
核心机制:
- 超时:连接超时短(5s),读取超时按任务设;模型超时后返回兜底(如"系统繁忙,请稍后重试")。
- 限流:按用户/IP 限制请求频率,防止滥用;模型返回 429 时退避。
- 降级:模型不可用时,返回缓存的常见答案或转人工,而不是整个接口报错。
- 异步削峰:长任务用消息队列(见 09.4 消息队列),先受理再异步处理。
最小可运行示例:
# degrade.py:超时与降级
@app.post("/chat")
async def chat(question: str):
try:
result = await asyncio.wait_for(call_agent(question), timeout=30.0)
return {"answer": result}
except asyncio.TimeoutError:
# 降级:返回兜底而非挂起
return {"answer": "系统繁忙,请稍后重试", "degraded": True}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 模型慢时接口挂起 | 没设超时 | asyncio.wait_for 包超时 |
| 429 时全部失败 | 没退避 | 指数退避 + 限流 |
| 模型挂了整个服务不可用 | 没降级 | 返回兜底答案或转人工 |
面试考法:问"模型 API 抖动时你的服务怎么保证可用"。要点:超时、限流、降级三件套;模型不可用时返回缓存或转人工,长任务用消息队列削峰。
5.6 版本管理与灰度
为什么需要它:Prompt 和模型都是会改的。改坏了要能回滚,新功能要先小流量验证。
核心机制:
- Prompt 版本化:模板文件带版本号(阶段 2),运行时按配置加载,不发版代码即可切换。
- 模型版本:配置里指定模型名,切换走配置,不改业务代码。
- 灰度:新 Prompt/模型先对 5% 流量开放,对比指标(正确率、成本、延迟),没问题再全量。
- 回滚:指标下降立刻切回上一版本。
最小可运行示例:
# version_route.py:按灰度比例分流
def get_prompt_version(user_id: str) -> str:
# 5% 用户用新版本,其余用稳定版
if hash(user_id) % 100 < 5:
return "order_extract.v3"
return "order_extract.v2"
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 改 Prompt 要发版代码 | Prompt 写死在代码里 | 模板独立版本化 |
| 新 Prompt 全量上线后变差 | 没灰度 | 先小流量灰度,对比指标再全量 |
面试考法:问"Prompt 和模型版本怎么管理"。要点:模板与配置独立版本化,灰度分流小流量验证,指标下降立刻回滚。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 把 Agent 封装成 FastAPI 接口 | 异步 POST 接口 | curl 能调通 | 3 小时 |
| 加 SSE 流式 | 逐块返回 | 前端逐字看到 | 2.5 小时 |
| 接 trace | 记录每次调用的输入/输出/工具 | 能回放一次调用 | 3 小时 |
| 加超时 | 模型超时时返回兜底 | 不挂起 | 1.5 小时 |
| 模型分级 | 简单任务走小模型 | 日志显示走了小模型 | 2 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 同步接口改异步 | 给定同步 httpx | 并发能力提升 | 2.5 小时 |
| 加语义缓存 | 相似问题命中缓存 | 第二次不调模型 | 3 小时 |
| 加限流 | 按用户限频 | 超限返回 429 | 2 小时 |
| Prompt 版本化 | 模板带版本号 | 切换不发版代码 | 2 小时 |
| 灰度分流 | 5% 流量用新版 | 可按 user_id 分流 | 2 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| Agent 服务化完整链路 | FastAPI + SSE + trace + 降级 | 有超时、限流、降级路径 | 8 小时 |
| 成本看板 | 统计日 token 量、缓存命中率、模型分布 | 能看到成本构成 | 5 小时 |
| 灰度发布流程 | 新版本小流量→对比指标→全量/回滚 | 有明确回滚阈值 | 4 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| 并发上不去 | 用了同步 httpx | 看接口是否 async | 改 AsyncClient |
| 前端看不到流式逐字 | 网关缓冲 | 直连测试是否流式 | 关反向代理缓冲 |
| 线上错了查不到原因 | 没记 trace | 看日志 | 关键链路全 trace |
| 简单任务成本高 | 没模型分级 | 看调用模型名 | 简单任务路由小模型 |
| 重复问题重新生成 | 没语义缓存 | 看是否命中缓存 | 加相似问题缓存 |
| 模型慢时接口挂起 | 没超时 | 看请求 hang 多久 | asyncio.wait_for 超时 |
| 模型挂了服务不可用 | 没降级 | 看错误是否透出 | 返回兜底或转人工 |
| 改 Prompt 要发版代码 | 模板写死 | 看 Prompt 是否在代码里 | 模板独立版本化 |
八、出口条件
全部勾选后再进入 阶段 7 安全、评测体系与生产落地。
- [ ] 能把 Agent 封装为异步 HTTP 接口并支持 SSE 流式
- [ ] 能说清状态图的节点/边/检查点对应手写循环的哪部分
- [ ] 关键链路有 trace 可回放,bad case 能沉淀成数据集
- [ ] 接入语义缓存与模型分级,简单任务走小模型
- [ ] 有超时、限流、降级路径,模型抖动时不挂起
- [ ] Prompt 与模型版本可独立回滚,支持灰度
- [ ] 排障表随机抽三个现象能在 5 分钟内定位
自测题(先自己想,再看要点):
- LangGraph 状态图的节点、边、检查点分别对应手写 ReAct 的什么?
- 要点:节点=调模型/工具的函数,边=条件转移(有 tool_calls 去工具节点),检查点=自动保存状态支持中断恢复。
- AI 接口为什么要异步和流式?
- 要点:异步支撑高并发避免阻塞;流式让用户逐字看到回答、降低首字延迟。
- trace 记录哪些内容?为什么重要?
- 要点:输入 messages、每步节点(模型/工具)、工具入参出参、输出、token、延迟;没有 trace 线上问题无法回放。
- 怎么降低 AI 应用成本?
- 要点:语义缓存、模型分级简单任务走小模型、prompt 缓存、控制 max_tokens、非实时走批量。
- 模型 API 抖动时怎么保证服务可用?
- 要点:超时、限流、降级三件套;模型不可用返回缓存或转人工,长任务用消息队列削峰。
- 为什么业务逻辑不要全写在 Prompt 里?
- 要点:确定性规则(权限、校验、路由)放代码可测试,Prompt 只管生成;全写在 Prompt 里无法回归测试。
- 新 Prompt 怎么安全上线?
- 要点:灰度小流量分流,对比正确率/成本/延迟指标,没问题再全量,下降立刻回滚上一版本。