一个可维护的 AI 应用应该是什么样？从 Demo 到生产系统
码海寻道 · 大模型、智能体与 RAG 工程组件系列第 60 篇
Demo 的目标是证明“能跑通”，生产系统的目标是“长期可控”。一个可维护的 AI 应用，不是组件越多越高级，而是边界清楚、行为可解释、失败可恢复、成本可管理、版本可回滚。
一、Demo 和生产的差异
| 维度 | Demo | 生产系统 |
|---|---|---|
| 数据 | 少量固定样本 | 持续变化、分租户、有权限 |
| 流程 | 同步串联 | 异步、可重试、可恢复 |
| 模型 | 一个默认模型 | 版本、路由、降级和成本 |
| 检索 | 只看相似度 | 过滤、版本、混合检索和评估 |
| 失败 | 报错即可 | 状态、补偿、告警和回滚 |
| 安全 | Prompt 提醒 | 最小权限、隔离、审计和审批 |
二、清晰的组件边界
API：请求、鉴权、响应 业务服务：规则、事务和状态 Worker：长任务和异步处理 PostgreSQL：业务事实 向量库：检索索引 对象存储：原始文件 Redis：缓存和短期状态 观测平台：Trace、指标、评估和审计组件可以替换，但职责不能混乱。例如 Redis 不是最终事实来源，模型也不是权限决策器。
三、可测试的 RAG 链路
把流程拆成可独立测试的函数和服务：
parse → split → embed → index → retrieve → rerank → generate每一步都可以有固定输入、输出 Schema 和失败测试。这样 Embedding 模型升级时，可以知道是检索退化还是生成退化。
四、版本化是生产能力
至少版本化：
- API 和数据库 Schema；
- Prompt；
- Embedding 模型；
- Chunk 策略；
- 向量索引；
- Agent 工具协议；
- 评估集和阈值；
- 配置与发布包。
版本化不是为了记录历史，而是为了灰度、比较和回滚。
版本对象要能关联到实际运行：API、数据库 Schema、Prompt、模型、Embedding、Chunk 策略、索引、权限策略、配置和评测集都应有版本号。发布记录还要保存负责人、时间、变更原因、灰度范围和回滚条件。
五、失败应该是状态，而不是日志
document: index_pending / ready / failed job: queued / running / retrying / dead run: running / completed / cancelled / failed用户需要知道任务状态，运维需要知道失败原因，恢复程序需要知道从哪里继续。只写一行“ERROR”不能支撑生产恢复。
失败状态应包含可重试性、当前阶段、输入版本、尝试次数、租约、最后心跳、错误分类和补偿动作。恢复程序要以幂等键或 Checkpoint 继续执行，不能简单地把所有失败任务从头重跑。
六、安全是架构的一部分
身份认证 → 资源授权 → 数据过滤 → 工具白名单 → 输出校验 → 审计与告警提示词注入、越权检索、敏感信息泄露和过度 Agent 权限，必须通过服务端和基础设施边界控制。
七、质量、成本和体验要一起优化
质量：Recall、忠实度、引用准确率 体验：TTFT、P95、流式、取消和重试 成本：Token、Embedding、存储、并发和重试只降低成本可能损失质量，只追求质量可能无法承受账单，只优化平均延迟可能忽略长尾用户。
八、发布前的最小门槛
- 固定评测集通过；
- 权限和越权测试通过；
- 关键接口有超时和限流；
- 任务可重试、可取消、可恢复；
- 数据库、对象和向量索引有备份；
- Trace、指标、日志和审计可查询；
- 模型、Prompt 和配置可回滚；
- 运行成本有预算和告警。
九、从 Demo 演进的推荐路线
单进程原型 ↓ 模块化服务 + PostgreSQL ↓ 异步队列 + 对象存储 + 缓存 ↓ 向量检索独立扩展 ↓ 权限、评估、观测和审计 ↓ 容器化、灰度和自动恢复每一步都由实际瓶颈和风险驱动，不要一开始就引入所有复杂基础设施。
十、给团队的最终检查表
数据
- 原始文件可恢复；
- 文档版本和 Chunk 可追踪；
- 删除和租户注销有补偿。
代码
- 外部调用有超时和重试分类；
- 工具和 SQL 有白名单；
- 关键流程有自动化测试。
运行
- 有健康检查、限流和告警；
- 有成本、延迟和质量指标；
- 有发布、回滚和故障演练。
治理
- 有权限、脱敏和审计；
- 有模型和 Prompt 版本；
- 有数据保留和合规策略。
结语：可维护比“看起来聪明”更重要
一个成熟的 AI 应用，不是让模型拥有无限自主权，而是让模型能力嵌入一套有边界的工程系统：数据可追踪，流程可恢复，权限可验证，质量可评估，成本可观察，版本可回滚。
最终验收也应包括故障演练：模型超时、队列重复、缓存失效、向量索引不可用、权限回收、租户删除、SSE 断线和数据库恢复。只有演练结果能被记录、告警并触发明确的止损或回滚动作，系统才算真正具备生产可维护性。
至此，“大模型、智能体与 RAG 工程组件系列”60 篇文章全部完成。后续可以基于本系列继续展开代码实战、源码分析、故障排查和行业方案专题。
参考资料
- Docker 官方文档
- Kubernetes 官方文档
- OpenTelemetry 官方文档
- OWASP GenAI Security Project
本文为“码海寻道”原创技术文章。生产架构应结合实际数据、流量、团队能力和合规要求持续演进。
