罗罗编程学习记录
本页内容 展开查看

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 分钟内定位

自测题(先自己想,再看要点):

  1. LangGraph 状态图的节点、边、检查点分别对应手写 ReAct 的什么?
    • 要点:节点=调模型/工具的函数,边=条件转移(有 tool_calls 去工具节点),检查点=自动保存状态支持中断恢复。
  2. AI 接口为什么要异步和流式?
    • 要点:异步支撑高并发避免阻塞;流式让用户逐字看到回答、降低首字延迟。
  3. trace 记录哪些内容?为什么重要?
    • 要点:输入 messages、每步节点(模型/工具)、工具入参出参、输出、token、延迟;没有 trace 线上问题无法回放。
  4. 怎么降低 AI 应用成本?
    • 要点:语义缓存、模型分级简单任务走小模型、prompt 缓存、控制 max_tokens、非实时走批量。
  5. 模型 API 抖动时怎么保证服务可用?
    • 要点:超时、限流、降级三件套;模型不可用返回缓存或转人工,长任务用消息队列削峰。
  6. 为什么业务逻辑不要全写在 Prompt 里?
    • 要点:确定性规则(权限、校验、路由)放代码可测试,Prompt 只管生成;全写在 Prompt 里无法回归测试。
  7. 新 Prompt 怎么安全上线?
    • 要点:灰度小流量分流,对比正确率/成本/延迟指标,没问题再全量,下降立刻回滚上一版本。