简单项目,简单拆解:一个「会分诊」的 AI 客服
不是高深架构,就是把「该谁干」这件事分清楚——然后让它在线上别崩......
| 项目 | 内容 |
|---|---|
| 🧰 技术栈 | FastAPI · LangGraph · SQLAlchemy 2.0 · PostgreSQL · Milvus · SSE |
| 📖 难度 | 会写 FastAPI 就能跟;LangGraph 从零讲 |
| ⏱ 阅读 | 约 12 分钟,代码可直接抄 |
| 🎯 适合谁 | 准备做第一个 AI 项目、或正被「万能 Agent」折磨的后端同学 |
封面:一条消息要走完的六步,全在这张图里
🧭 导读:这篇会带你走完什么
本节解决:先知道这篇文章能给你什么,再决定要不要往下读。
| 你会看到 | 一句话剧透 |
|---|---|
| 为什么要分诊 | 一个万能 Agent,等于让一个人兼任前台、部门经理和心理医生 |
| 架构长什么样 | 主图路由 + 子图执行,Command 决定下一站 |
| 最容易踩的坑 | 子图里加的字段,一回主图就「消失」 |
| 名词 | 人话解释 |
|---|---|
| Agent | 会自己安排工作的实习生:给目标,自己决定调什么工具、调几次 |
| LangGraph | 给实习生画的流程看板:走到哪、下一步去哪、要记什么 |
| RAG | 先翻资料再回答,而不是凭记忆瞎编 |
| 状态机 | 一张写清「现在在哪、能去哪、要带什么」的表 |
💡 核心提示:AI 客服拼的不是模型多强,而是「谁该干这件事」的调度有多清楚。调度一乱,再贵的模型也只是更贵的混乱。
🚩 一、先认识四个词(以及一个被高估的词)
本节解决:把 Agent / LangGraph / RAG / 状态机 这四个词,翻译成你不查资料也能懂的话。
网上讲 Agent 的文章,十个里有八个先甩一堆英文缩写。我们先花 30 秒对齐一下——不是因为我严谨,是因为我当年也是被这些词劝退的那一批人。
| 名词 | 人话解释 | 在这个项目里干啥 |
|---|---|---|
| Agent | 会自己安排工作的实习生:给目标,自己决定调什么工具 | 用户问「怎么办」,它自己去查库、查文档 |
| LangGraph | 给实习生画的流程看板:走到哪、下一步去哪、要记什么 | 主图分诊,子图干活 |
| RAG | 先翻资料再回答,而不是凭记忆瞎编 | 问到细节,先检索原文再答 |
| 状态机 | 一张写清「现在在哪、能去哪、要带什么」的表 | 决定这轮进哪个子图、下轮还记不记得 |
状态机这词听着吓人,其实它就是一张表。你写 if/else 的时候其实也在做状态机,只是没画出来而已。
而被高估的那个词是 Prompt。它决定「话说得好不好听」, 但决定不了「该谁去说、说完记不记得」——那是架构的事。
📌 本节小结
- Agent 是「会自己选工具」的调用;
- LangGraph 是「把流程画出来」的框架;
- RAG 是「先查再答」;
- 状态机是「记着走到哪」的表。
🚨 二、需求拆解:先分诊,再干活
本节解决:为什么「一个万能 Agent」一定会失败,以及分诊制怎么救它。
最大的坑,是一上来就想「做一个万能 Agent」。
我试过:一段超长 Prompt,把所有规则写进去,让模型自己判断该干嘛。结果是——
- Prompt 越写越长,改一句影响三句;
- 意图互相串味,问资料的回答成了推荐;
- 最要命的是出错了,完全不知道错在哪一步。
⚠️ 踩坑记录:那次失败的本质,是我把一个架构问题,写成了一个 Prompt 问题。Prompt 治不了架构病。
后来改成分诊制:一个轻量路由器判断意图,判断完把活儿交给对应的子流程。
| 窗口 | 干什么 | 特点 |
|---|---|---|
| 🔎 查资料 | 先检索知识库,再组织语言 | 依赖 RAG,答错代价高 |
| 🧾 办业务 | 流程固定、步骤明确 | 中途可能还要查用户信息 |
| 💬 闲聊 | 纯聊天,不挂工具 | 要能自然把话题引回业务 |
好处很直接:每个子流程能单独调试、单独改 Prompt、单独上线;路由错了也只是「进错窗口」,不会整个系统一起崩。
📌 本节小结 分诊制买到的不是「更聪明」,而是可调试性:错了知道错在哪一段。
🏗️ 三、骨架:三层结构 + 一个状态机
本节解决:代码该往哪放,资源该在哪初始化。
项目目录大概长这样:
app/
├── main.py # 应用装配:启动、路由注册、异常处理
├── agents/ # 状态机与工具
│ ├── orchestrator.py # 主图:分诊 + 挂载子图
│ ├── router.py # 意图识别(规则 + 模型)
│ ├── tools.py # Agent 能调用的工具
│ ├── schemas.py # 状态定义
│ └── *_agent.py # 三个子流程
├── modules/ # 业务模块:router / service / repository / schemas
├── rag/ # 文档切分、入库、检索
└── infra/ # 数据库会话、记忆存储
一句话分工:modules 管「数据怎么写」,agents 管「话怎么说」。两者之间只通过工具(Tool)这层耦合——哪天你想换一套意图识别方案,业务代码一行都不用动。
🧩 3.1 依赖注入:别自己 new 对象
这一节解决:为什么你的 session 和 graph 不该在函数里现造。
FastAPI 的 Depends 说白了就一句话:你不要自己创建对象,告诉框架你需要什么,它递给你。
像不像入职第一天?你以为电脑要自己配,结果 IT 早就放桌上了,只是没人告诉你线插哪。数据库会话和那张编译好的图,就是那台电脑——请求来了发一台,用完还回去。
from fastapi import APIRouter, Depends, Request
from sqlalchemy.ext.asyncio import AsyncSession
router = APIRouter(prefix="/api/v1/chat", tags=["聊天模块"])
def get_service(
request: Request,
session: AsyncSession = Depends(get_session), # 每个请求一个数据库会话
):
return ChatService(session, request.app.state.agent) # 整个应用共用一个编译好的图
@router.post("", response_class=EventSourceResponse)
async def chat(
request: ChatRequest,
user_id: Annotated[int, Header(alias="X-User-Id")],
service: ChatService = Depends(get_service),
):
...
这里的两个设计点,都是被现实拷打出来的:
- 数据库会话是「请求级」的。
get_session大概是async with AsyncSessionFactory() as session: yield session——yield的意思是「用完请还我」,请求结束自动归还连接。Service 里永远不出现「新开一个 session」。 - 图是「应用级」的。整个服务只编译一次,挂在
app.state.agent上。为什么不写成模块级全局变量?因为测试时你没法替换它,关停时你也没法释放它,而app.state是跟着应用生命周期走的。
💡 核心提示:判断一个后端写得好不好,看两点——资源从哪来、什么时候还。AI 项目也一样,只是多了几个「会喘气的资源」。
🚀 3.2 启动阶段:资源只留一个入口
这一节解决:启动顺序错了,报错会指向一个完全无关的地方。
@asynccontextmanager
async def life_span(app: FastAPI):
await check_database() # 1. 数据库探活
checkpointer = await init_checkpointer() # 2. 记忆存储:连池 + 建表
app.state.agent = init_chat_graph(checkpointer) # 3. 编译一次主图
yield
await close_database() # 4. 逆序释放
await close_checkpointer()
顺序有讲究:数据库不通就别去建记忆表;记忆存储没就绪,图也编译不完整(编译时会把存储绑上去)。
AI 应用的启动阶段比传统后端重得多:连接池、模型客户端、向量库客户端、图编译,全在这一步。把它收成一个入口,比散落在各个 import 里安全一万倍。
📌 本节小结 资源只留一个入口:
lifespan里按「数据库 → 存储 → 编译图」排,关停时逆序释放。
🚦 四、LangGraph:主图分工,子图干活
本节解决:一张图怎么变成「五个窗口」,以及节点怎么自己决定下一站。
整个过程画出来是这样:
图 1 · 主图分诊 + 五个出口,其中三个是子图
同一张图,用 Mermaid 表达是:
graph TD
S([用户消息]) --> R[route 意图路由]
R -->|consult| A[查资料子流程]
R -->|service| B[办业务子流程]
R -->|chitchat| C[闲聊子流程]
R -->|human_handoff| D[转人工]
R -->|fallback| E[兜底]
A --> F([回复用户])
B --> F
C --> F
D --> F
E --> F
🧠 4.1 意图识别:先规则,再模型
这一节解决:哪些消息不该浪费一次模型调用。
最容易犯的错是「什么都交给模型」。像「你好」「谢谢」「再见」这种,正则匹配又快又免费,真没必要为它付一次模型调用。
def match_social_intent(message: str) -> str | None:
normalized = normalize_message(message) # 去标点、转小写
for intent, patterns in SOCIAL_PATTERNS.items():
if any(re.fullmatch(p, normalized) for p in patterns):
return intent
return None
规则没命中的,再交给模型,而且要求它按结构返回,别返一段散文:
class RouteResult(BaseModel):
intent: Intent # 固定几个取值之一
reason: str # 为什么这么判断,方便排查
self.model = init_chat_model(...).with_structured_output(schema=RouteResult)
with_structured_output 的价值:后面拿到的就是对象,直接 .intent 用;要是让模型自由发挥,你就得写一堆字符串清洗,还得处理它偶尔「贴心地」加个句号。
💡 核心提示:能用
if解决的,别开模型。模型是按次计费的,你写代码的时间也是。
🎫 4.2 Command:节点自己买票去下一站
这一节解决:为什么不用条件边,而让节点直接返回 Command。
传统写法是「节点返回状态 → 条件边决定去哪」。LangGraph 还给了另一种写法:节点直接返回一个 Command,里面既有状态更新,也写明下一站。
async def route_node(state: ChatState):
query = state["messages"][-1].content
previous = state.get("active_workflow", "")
result: RouteResult | str = await intent_router.route(query, f"上一轮流程:{previous}")
if isinstance(result, str): # 闲聊规则命中,直接给回复并结束
return Command(
update={"messages": [AIMessage(content=result)], "active_workflow": "chitchat"},
goto=END,
)
return Command(
update={"active_workflow": result.intent, "previous_workflow": previous},
goto=result.intent, # 跳转到同名节点
)
有一个必须死守的约定:goto 的值和 add_node 注册的名字要一字不差。所以我把意图取值写成了 Literal[...],让「意图」和「节点名」共用一套词汇表。
⚠️ 踩坑记录:这类错误的特点是——编译器不管,运行时教你做人。名字少个字母,图照样编译,跑到那一步才炸。
路由的五个出口,状态转移长这样:
graph TD
%% 定义节点样式:浅紫色底色,深色边框
classDef default fill:#eef0ff,stroke:#d3d8ff,stroke-width:2px,color:#333;
Start(( )) --> R[意图识别]
R -->|consult| A[查资料子图]
R -->|service| B[办业务子图]
R -->|chitchat| C[闲聊子图]
R -->|human_handoff| D[转人工]
R -->|fallback| E[兜底回复]
A --> End((( )))
B --> End
C --> End
D --> End
E --> End
🧱 4.3 主图装配
这一节解决:怎么把子图当积木插进主图。
def init_graph(checkpointer):
builder = StateGraph(ChatState)
builder.add_node("route", route_node)
builder.add_node("consult", init_consult_agent()) # 子图当节点用
builder.add_node("service", init_service_agent()) # 子图当节点用
builder.add_node("chitchat", init_chitchat_agent()) # 子图当节点用
builder.add_node("human_handoff", handoff_node) # 普通函数
builder.add_node("fallback", fallback_node)
builder.add_edge(START, "route")
for node in ("consult", "service", "chitchat", "human_handoff", "fallback"):
builder.add_edge(node, END)
return builder.compile(checkpointer=checkpointer)
「子图也能当节点」 是这套架构最省事的地方:子图编译出来的东西,直接 add_node 挂上去,主图不用管它内部转了几圈。
三种子流程写法对比,新手照着选:
| 形态 | 用在哪 | 什么时候用 |
|---|---|---|
| 现成 Agent | 查资料 | 标准「思考-调工具-再回答」 |
手搓 StateGraph | 办业务 | 中间要插自己的逻辑 |
| 普通函数节点 | 兜底 | 确定性逻辑,不需要模型 |
选的标准很简单:能用现成就不手搓,需要干预就手搓,真不需要模型就别硬塞模型。
📌 本节小结 主图只做「分诊 + 收口」,具体活交给子图;子图编译产物直接当节点挂。
🗃️ 五、状态:AI 应用的隐形数据库
本节解决:为什么你的数据「明明写了却没生效」。
🧾 5.1 状态就是一个 TypedDict
这一节解决:messages 为什么是追加,其他字段为什么是覆盖。
class ChatState(MessagesState):
"""主图状态"""
previous_workflow: str
active_workflow: str
MessagesState 是框架自带的,等于提前声明了 messages 字段。我第一次见它的时候以为是什么高科技,其实就是一个自带「消息列表」的 TypedDict(带类型的字典)。
但它有个不起眼的细节:messages 挂了一个叫 add_messages 的归约函数(reducer) 。意思是你往 messages 里写东西时,是追加,不是覆盖。
# messages:追加(有 reducer 管着)
return {"messages": [AIMessage(content=answer)]}
# 其他普通字段:直接覆盖(默认语义)
return {"active_workflow": "service"}
所以状态里每个字段都要问自己一句:这个字段被写的时候,是覆盖还是追加? 想追加就得显式声明 reducer,默认都是覆盖。
🕳️ 5.2 子图里加的字段,为什么会「消失」
这一节是全文最值钱的一段:一个不报错、只丢数据的坑。
这个坑我卡了半天,值得单独说。
闲聊子图想做个限制:连续闲聊超过 3 次就提醒用户回业务。于是我在子图状态里加了个计数:
class ChitchatState(ChatState):
chitchat_count: int # 子图内部计数
结果:子图里明明能读到、能自增,一回到主图就没了,下一轮又从 0 开始。
最气的是它不报错,只是默默忘记。
原因其实不玄乎:子图执行完,输出要投影回主图,而投影只认主图状态里声明过的字段。父图压根不认识 chitchat_count,它就被丢掉了。
⚠️ 踩坑记录:想跨轮次活下来的数据,必须声明在父图状态里;子图只放「本次流程内的临时变量」。
顺便说一个同源的问题:节点返回值必须是 dict。习惯了 Pydantic 的话很容易直接 return 某个对象,框架会报状态更新错误——要么返回 dict,要么先 .model_dump()。
🧵 5.3 多轮记忆,其实只有一行代码
这一节解决:为什么「换个会话就失忆」。
config = {"configurable": {"thread_id": str(request.thread_id)}}
async for event in self.agent.astream_events(
{"messages": [HumanMessage(content=request.message)]}, config
):
...
thread_id 一样,就是同一个会话的记忆;配上 PostgreSQL 版的存储(AsyncPostgresSaver),每一步状态都落库。
我们让业务表的主键直接当 thread_id,于是两件事分开管:
- 用户隔离用 SQL 做(
WHERE user_id = ?); - 记忆隔离用
thread_id做(框架负责)。
分工清楚了,代码就清爽了。
📌 本节小结
- 跨轮数据必须在父图声明;
- 节点返回
dict,不是对象;- 记忆隔离靠
thread_id,一行配置。
🔍 六、RAG:把「查资料」做成一个工具
本节解决:RAG 该写进流程,还是该交给模型自己决定什么时候查。
对新手来说,RAG 最反直觉的一点是:它不该是流程里固定的一步,而应该是 Agent 手里的一个工具。
区别在哪?流程固定的话,无论用户问什么都要先检索一遍,浪费钱也浪费时间;做成工具之后,什么时候查、查几次、要不要换个关键词再查,交给模型判断。
📚 6.1 父块 + 子块
这一节解决:文档切小了没上下文、切大了搜不准,怎么办。
一份业务文档动辄几十页。切小块,检索准但上下文碎;切大块,上下文全但检索不准。解法是切两层:
- 父块:按 Markdown 标题层级切,保留完整章节,存关系库;
- 子块:父块再按 500 字递归切,带上
parent_id,存向量库。
检索时先命中子块,再顺着 parent_id 批量取回父块——小块负责找准,大块负责讲全。
🎯 6.2 混合检索:向量 + 关键词
这一节解决:为什么只上向量还不够。
vector_store = Milvus(
embeddings, # 稠密向量
collection_name="docs_v1",
builtin_function=BM25BuiltInFunction(
analyzer_params={"type": "chinese"}, # 中文分词的稀疏检索
),
vector_field=["dense", "sparse"], # 两路一起召回
auto_id=True,
)
为啥要两路?向量擅长「意思相近」,但用户问「第三点第二条写的啥」这种精确表述时,关键词检索反而更稳。两路召回后再上一道精排(rerank),把真正相关的段落顶到前面。
💡 核心提示:检索质量决定回答质量的上限,Prompt 只能决定下限。别指望用提示词治好检索的病。
🛡️ 6.3 工具 + 防幻觉提示词
这一节解决:怎么让模型「只照着资料说」。
@tool
async def query_knowledge(doc_id: str, query: str):
"""根据文档 ID 和问题,取回相关章节原文"""
chunks = await retriever.retrieve(doc_id, query, 5)
return "\n\n".join(
f"章节:{'>'.join(c.section_path)}\n内容:{c.content}" for c in chunks
)
再配合系统提示词里写死的约束:
- 回答具体细节前,必须先调用 query_knowledge,再根据检索结果回答。
- 只能基于检索到的内容回答,不要编造;没查到就如实告知。
工具负责「拿得到」,Prompt 负责「用得上」。 只写 Prompt 不给工具,模型只能编;只给工具不写约束,模型可能懒得查。
📌 本节小结 RAG 是「止疼药」不是「万能药」:能缓解幻觉,治不了胡说。
⌨️ 七、流式:把打字机体验还给用户
本节解决:为什么用户宁愿等 3 秒看字一个个出来,也不愿等 3 秒看一次全屏刷新。
聊天界面要是等整段生成完再一次性吐出来,体验会很难受。SSE(Server-Sent Events)就是干这个的:一个连接,服务器单向往外推,浏览器原生支持。
一次请求从头到尾长这样:
sequenceDiagram
autonumber
participant B as 浏览器
participant F as FastAPI
participant L as LangGraph
participant M as 模型
B->>F: POST /api/v1/chat (X-User-Id)
Note right of F: 校验会话归属
F->>L: astream_events (thread_id)
Note right of L: route 判断意图
L->>M: 发起生成
M-->>L: token 流
L-->>F: on_chat_model_stream
F-->>B: SSE data: token
F-->>B: SSE event: done
先看接口这一层,只做一件事:把 Service 的流透传出去。
@router.post("", response_class=EventSourceResponse)
async def chat(request: ChatRequest, service: ChatService = Depends(get_service)):
async for event in service.chat_stream(request):
yield event
Service 里只挑「模型正在吐字」的事件往外发:
async def chat_stream(self, request: ChatRequest):
config = {"configurable": {"thread_id": request.thread_id}}
async for event in self.agent.astream_events(
{"messages": [HumanMessage(content=request.message)]},
config,
version="v2",
):
if event["event"] != "on_chat_model_stream":
continue
chunk = event["data"].get("chunk")
text = getattr(chunk, "content", "")
if text:
yield ServerSentEvent(data=text, event="message")
yield ServerSentEvent(data="", event="done") # 明确收尾
三条经验:
astream_events是异步生成器,不能await。写成await agent.astream_events(...)会直接报TypeError,正确姿势是async for。- 只转发
on_chat_model_stream。框架事件流很丰富(节点开始、工具调用、结束……),全转发等于把内部实现暴露给前端。 - 发一个
done事件。前端收到就关掉「正在输入」,比靠连接断开去猜靠谱。
📌 本节小结 用户不关心你的架构,只关心字出没出来。
🚧 八、新手最容易踩的几个坑
本节解决:把别人的跟头,变成你的检查清单。
下面六条,我中过四条。剩下两条没中,纯粹是运气。
| 坑 | 现象 | 怎么解 |
|---|---|---|
| 子图字段不持久 | 计数下一轮归零 | 声明在父图状态里 |
| 节点返回对象 | 状态更新报错 | 返回 dict / .model_dump() |
astream_events 被 await | TypeError: async_generator | 改用 async for |
| 异常处理器一把抓 | 404 也变 500 | 每类异常单独注册 |
| router 注册两次 | 文档里重复接口 | include_router 只调一次 |
| Prompt 要求不存在的工具 | 模型空转、编造工具名 | 对照工具列表检查 |
最后一条最容易被忽视:提示词和工具集是同一个接口的两面。你删了个工具却没改 Prompt,模型就会一本正经地「调用」一个不存在的函数,然后你盯着日志怀疑人生。
🌙 九、写在最后
本节解决:把前面八节压缩成三句话,方便你带走。
做完这个项目,有三句话我比较确定:
- Agentic 开发的核心不是 Prompt,是状态机。 Prompt 决定「说什么」,状态决定「记什么、去哪、能不能回来」。路由错了,Prompt 写得再花也白搭。
- 检索应该是个工具,不是一段流程。 什么时候查、查几次,交给模型判断,比在代码里写死
if灵活得多。 - 传统后端的基本功一个都没浪费。 依赖注入、连接池、事务边界、异常分层、日志上下文——AI 应用不是新物种,它只是多了一个「不确定的调用」。
最后附一张对照表,方便你把自己的项目往上套:
| 步骤 | 比喻 | 代码对象 |
|---|---|---|
| ① 接单 | 服务员 | POST /api/v1/chat · ChatService |
| ② 认桌号 | 桌号 | thread_id = chat_threads.id · query_owned() |
| ③ 分单 | 分单员 | route_node · Command(goto) |
| ④ 下灶取料 | 灶台 + 仓库 | 子图 · @tool · BM25BuiltInFunction |
| ⑤ 端菜 | 一道一道上 | astream_events · done |
| ⑥ 落账本 | 桌号小本子 | AsyncPostgresSaver |
🌙 最后一句:大模型负责让产品有想象力,状态机负责让你别被这份想象力弄死。
说句实在话,这个项目里最花时间的不是调模型,而是调那条「流程走不通」的路:状态对不上、字段被投影丢掉、事件类型猜错。模型反而是最好相处的那个——它不懂就问你要,流程不会。
📚 参考资料
- LangGraph 官方文档:子图、
Command、checkpointer 的权威说明 - FastAPI 依赖注入:
Depends与yield依赖的生命周期 - SQLAlchemy 2.0 异步:
AsyncSession与事务边界 - MDN · Server-Sent Events:SSE 的浏览器行为与重连语义
如果你也在做类似的项目,欢迎在评论区说说你踩的是哪一个坑🧐。