从能跑到能观察——AI 服务的工程化分层与日志
前几篇我们把 Agent 包成了 FastAPI 接口(第 4 篇),加了字段校验、接了错误处理。功能都齐了。但有两个问题一直卡着我: **一是看不清。** 有一次模型调用失败,前端只返回一句"模型调用失败",我盯着屏幕却不知道:请求到底进没进来?Service 执行到哪一步?具体炸在哪一行?服务能跑,但看不清它怎么跑。 **二是改不动。** 想给分析加个缓存,发现 Agent 调用、错误处理、日志全挤在一块,只能往 `routers.py` 里硬塞。能跑,但不等于好维护。 所以这一篇同时解决这两件事:把项目分层,再加日志。 > **能跑只是 Demo,能分层、能观察,才开始像可维护的服务。** --- ## 一、项目现在的分层结构 分层之后,目录是这样: ``` app/ ├── main.py 应用入口 ├── routers.py API 接口层 ├── schemas.py 请求和响应模型 └── services.py 业务服务层 resume_analyzer/ ├── agent.py PydanticAI Agent 调用 ├── models.py Agent 输出结构 └── tools.py Agent 工具函数 ``` `app/` 管 Web 服务和接口,`resume_analyzer/` 管 AI 能力本身。两条线分开,后面换模型、加工具都不动接口层。 --- ## 二、每一层分别管什么 ### 1. `main.py` —— 启动器 不碰业务。只做:创建 FastAPI app、挂载 router、配全局日志、提供 health check。 ### 2. `routers.py` —— 接口层 只关心 HTTP:地址是什么、请求/响应模型是什么、异常返回什么状态码。不该知道 Agent 内部细节。 ### 3. `schemas.py` —— 契约层 放 `AnalyzeRequest` / `AnalyzeResponse`。它告诉调用方:该传什么、会返回什么。前端对接就靠它。 ### 4. `services.py` —— 业务层 负责业务编排:调 Agent、记日志,以后还能加缓存、重试、数据库、权限。 ### 5. `agent.py` —— AI 能力层 只管 PydanticAI:定义 Agent、调模型、回结构化结果。 **一句话类比**:`main` 是门面,`routers` 是前台,`schemas` 是表单,`services` 是后台办事员,`agent` 是里面真正干活的专家。各司其职,谁也别越界。 --- ## 三、最该理解的一层:services.py 它可能现在只是这样: ``` def analyze_resume_service(resume_text: str) -> ResumeAnalysis: return analyze_resume(resume_text) ``` 看着只是"包了一层",没干啥。但它的价值不在今天,在以后: ``` 日志 → 放这 缓存 → 放这 重试 → 放这 数据库保存 → 放这 权限判断 → 放这 调用耗时 → 放这 ``` 它的存在,让 `routers.py` 永远只说"收到请求、返回结果",不用面对复杂业务。 --- ## 四、为什么需要日志 解决了分层,还得能看清服务内部。AI 服务跑起来后,出问题的地方比普通接口多: - API Key 没配置 - 模型调用失败 - 网络超时 - Agent 输出异常 - 用户输入异常 没有日志时,用户只看到: ``` { "detail": { "code": "MODEL_CALL_FAILED", "message": "模型调用失败" } } ``` 这对用户友好,对开发者不够。开发者还需要知道:哪一次请求失败了、失败前执行到了哪、具体异常堆栈是什么。日志就是干这个的。 > **API 返回给用户看,日志留给开发者看。** 两者面对的人不同,该说的内容也不同。 --- ## 五、main 定规则,services 记业务 ### 1. `app/main.py` —— 定规则,不写日志 `main.py` 是入口,在这里配置全局日志格式: ``` import logging logging.basicConfig( level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s - %(message)s", ) ``` 它规定的格式是:**时间 等级 模块名 - 内容**。比如一次真实运行: ``` 2026-08-14 10:20:01 INFO app.services - 开始分析简历，文本长度=61 ``` ### 2. `app/services.py` —— 记业务,才真正写日志 业务层拿到 logger 后,按执行过程记录: ``` import logging logger = logging.getLogger(__name__) ``` ``` logger.info("开始分析简历，文本长度=%s", len(resume_text)) # ... 调用 Agent ... logger.info("简历分析成功") ``` 失败处: ``` logger.exception("简历分析失败") ``` 这里有个容易混的点。`main.py` 的 `basicConfig(...)` **不是在写日志,是在定规则**——它告诉整个项目显示什么等级、长什么样、带不带模块名。而 `services.py` 的 `logger.info(...)` 才记录具体的事。 ``` main.py 配置日志规则（全局一次） services.py 记录业务日志（每次执行） ``` 这是 Python 服务端最常见的组织方式:规则集中定,业务分散记。 --- ## 六、别再用 print() 调试 `print()` 是临时调试,能看但不适合长期维护: ``` print("开始分析") ``` `logging` 是正式记录,优势是结构化的: ``` logger.info("开始分析简历，文本长度=%s", len(resume_text)) ``` 它有四样 `print` 没有的东西: - 日志等级(INFO/WARNING/ERROR) - 时间戳 - 模块名(知道谁打的) - 能记异常堆栈,以后可落文件或接日志平台 服务端项目里,优先用 `logging`。 --- ## 七、logger.exception() 是排查利器 这个方法必须放在 `except` 里: ``` try: result = analyze_resume(resume_text) except Exception: logger.exception("简历分析失败") raise ``` 它的特别之处:不仅记错误信息,还**自动带上 traceback**。逻辑是——先把详细错误写进日志,再把异常继续抛给上层。`routers.py` 再把它转成结构化的 API 错误。 一句记住:**`logger.exception**`** = 记错误 + 记堆栈 + 重新抛出。** --- ## 八、错误响应和日志的分工 今天最重要的理解就一句: ``` 错误响应：给用户 / 前端看 日志记录：给开发者看 ``` 模型调用失败时,前端看到的是干净的: ``` { "detail": { "code": "MODEL_CALL_FAILED", "message": "模型调用失败", "hint": "请检查 API Key、模型名称、网络连接或上游模型服务状态" } } ``` 开发者在终端看到的是原始的: ``` ERROR app.services - 简历分析失败 Traceback (most recent call last): ... ``` 这就是分工的价值:用户体验不破,排查线索不丢。 --- ## 九、今天的核心收获 > **一个 AI 服务不能只会调模型,还要有清晰的分层、稳定的错误边界、能观察运行过程的日志。** 回顾这 5 篇走过的路,项目已经具备: ``` 结构化输出 (1) output_type 字段校验 (2) field_validator 工具调用 (2) Tool Schema/Evidence (3) API 封装 (4) FastAPI 错误处理 (4) HTTPException 工程分层 (5) services.py 日志记录 (5) logging ``` 这已经是一个小型 AI 后端项目的雏形。
