资讯详情

第 8 课：工程化——让系统可靠、可观测、可测试

8.1 你的目标

给 Agent 系统加上生产级能力：

• 错误处理：不同异常返回不同的 HTTP 状态码
• 日志：每个 Agent 的执行耗时、异常记录
• 测试：mock LLM，不依赖真实 API Key 也能跑

8.2 错误处理

反例：所有错误返回 500

try:result = agent_graph.invoke(state)
except Exception as e:raise HTTPException(500, f"处理失败: {e}")

这样做的问题：

实际发生的错误	返回的 HTTP 状态码	用户看到的
LLM API 超时	500	"处理失败"
LLM 返回格式不对	500	"处理失败"
用户输入太短	500	"处理失败"
数据库连不上	500	"处理失败"

运维完全不知道哪里出了问题。

正解：分层异常

class LLMTimeoutError(Exception):"""LLM 请求超时"""passclass LLMFormatError(Exception):"""LLM 返回格式不符合预期"""pass

然后在 API 层区分处理：

@app.post("/api/chat")
async def chat(req: ChatRequest):try:result = agent_graph.invoke(state)return resultexcept LLMTimeoutError:# 503 = 服务暂时不可用，客户端可以重试raise HTTPException(503, "AI 服务暂时不可用，请稍后重试")except LLMFormatError:# 502 = 上游服务（LLM）返回异常raise HTTPException(502, "AI 返回格式异常")except ValidationError:# 400 = 客户端请求有问题raise HTTPException(400, "请求参数不合法")except Exception:# 500 = 服务器内部错误logger.exception("未预期的错误")raise HTTPException(500, "系统内部错误")

为什么异常分层很重要？

给不同的人看不同的信息：

• 用户看到友好的"服务暂时不可用"
• 前端看到明确的 HTTP 状态码（503 触发自动重试，400 不做重试）
• 运维从日志看到详细的 stack trace
• 开发者从"502"知道是 LLM 格式问题，去调整 prompt

重试机制

LLM API 经常因为网络波动或限流而失败。一次失败就抛异常太脆弱：

def call_llm(messages, max_retries=3):for attempt in range(max_retries):try:resp = session.post(url, json=body, timeout=60)return resp.json()["choices"][0]["message"]except requests.exceptions.Timeout:if attempt == max_retries - 1:raise LLMTimeoutError("请求超时")time.sleep(2 ** attempt)  # 1s → 2s → 4s

为什么是指数退避？ 第一次失败可能是网络抖动，第二次可能是瞬时负载高，第三次如果还失败说明真的出了问题。每次重试等待时间加倍，避免对已过载的服务造成更大压力。

8.3 可观测性

节点耗时追踪

import timedef timed_node(name):def decorator(node_func):def wrapper(state):start = time.perf_counter()try:result = node_func(state)elapsed = time.perf_counter() - startlogger.info(f"[{name}] 完成，耗时 {elapsed:.2f}s")return resultexcept Exception:elapsed = time.perf_counter() - startlogger.exception(f"[{name}] 在 {elapsed:.2f}s 后失败")raisereturn wrapperreturn decorator

这样每次请求都会记录：

2026-07-31 10:23:45 [INFO] [router] 完成，耗时 0.32s
2026-07-31 10:23:46 [INFO] [tool] 完成，耗时 1.87s
2026-07-31 10:23:46 [INFO] [summary] 完成，耗时 0.41s

从日志中你能看到什么？

• Tool Agent 最慢（1.87s）——因为它调了两次 LLM
• 如果某天 Tool Agent 突然变成 5s，说明 LLM API 变慢了
• 如果 Router 经常失败，说明 prompt 可能有问题

8.4 测试

为什么测试 Agent 很困难？

Agent 依赖 LLM，而 LLM 调用需要 API Key、需要网络、需要花钱。

解法：Mock LLM

# conftest.py
def mock_call_llm(messages, **kwargs):"""不调真实 LLM，根据 prompt 关键词返回固定 JSON"""combined = " ".join(m.get("content", "") or "" for m in messages)if "意图分类" in combined:# 根据最后一条 user 消息判断返回什么意图last_user = [m["content"] for m in messages if m["role"] == "user"]text = last_user[-1] if last_user else ""if "投诉" in text:return {"content": '{"intent": "complaint", "reason": "mock"}'}elif "订单" in text or "物流" in text:return {"content": '{"intent": "order_query", "reason": "mock"}'}else:return {"content": '{"intent": "general", "reason": "mock"}'}return {"content": "mock 回复"}

这样测试有什么用？

不需要 API Key、不需要网络、测试秒级完成。测试的是 Agent 的逻辑（"意图为 complaint 时是否生成了工单"），而不是 LLM 的分类能力。

def test_complaint_creates_ticket():result = agent_graph.invoke({"user_message": "我要投诉", ...})assert result["escalation_ticket"] is not Noneassert "ticket_id" in result["escalation_ticket"]

那 LLM 的分类能力怎么测？

这是两个不同的问题：

1. Agent 的逻辑是否正确 → 用 mock 测试（本课的内容）
2. LLM 的分类能力是否满足需求 → 用评测集测试（不在本课范围内）

8.5 从第 1 课到第 8 课

第 1 课: 30 行 — 一个能聊天的终端程序
第 2 课: 80 行 — 加上意图分类和路由
第 3 课: 150 行 — 加上 Chroma 向量检索 RAG
第 4 课: 250 行 — 加上 Function Calling
第 5 课: 400 行 — 拆成 LangGraph 多 Agent
第 6 课: 500 行 — 加上会话管理
第 7 课: 600 行 — 加上可插拔数据源
第 8 课: 800 行 — 加上错误处理、日志、测试

每一步增加的代码都对应一个真实遇到的问题。 不是预先设计了一个大架构，而是问题驱动架构演进。

本课知识点

概念	你做了什么	为什么
分层异常	LLMTimeoutError / LLMFormatError	不同问题返回不同 HTTP 状态码
指数退避	失败后等 1s/2s/4s	避免对已过载的服务造成更大压力
Mock 测试	固定 JSON 替换真实 LLM	不消耗 API Key，离线可跑
节点耗时	timed_node 装饰器	性能瓶颈一目了然

课后作业

1. 给 knowledge_agent.py 也加上 try/except，当 Chroma 查询失败时返回降级回复
2. 在 conftest.py 中加一个 fixture，模拟 Chroma 查询失败的情况

面试可能会问

"Agent 系统的测试和传统 Web 系统的测试有什么不同？"
传统 Web 测试依赖数据库/API，Agent 测试依赖 LLM。LLM 不可控、不可重复，所以需要 mock。难点在于 mock 的返回值要"像真的"——否则测不出逻辑缺陷。

"为什么节点耗时日志对 Agent 系统特别重要？"
Agent 系统比传统 Web 系统多了一层不确定性（LLM 响应时间波动大）。如果 Router 突然从 0.3s 变成 3s，不一定是你代码有问题，可能是 LLM API 变慢了。没有耗时日志，你无法区分"代码 bug"和"上游变慢"。