12-Factor Agents：构建生产级 LLM 软件的 12 条原则

原文来源：12-Factor Agents GitHub — 构建生产级 LLM 驱动软件的方法论，19.7k Stars，1.5k Forks，273 次提交，借鉴经典 12-Factor App 理念。

12-Factor Agents 是一套为 LLM 驱动软件设计的方法论，灵感来自 Heroku 在 2011 年提出的经典 12-Factor App。它回答了一个关键问题：当我们把 LLM 放进生产环境时，什么样的原则能让系统真正可靠、可维护、可扩展？

项目由 HumanLayer 维护，GitHub 上已获得近 2 万 Stars，是 AI 工程方法论领域最受关注的开源项目之一。

背景：为什么需要 12-Factor Agents

传统的 12-Factor App 解决了云原生应用的设计问题：配置管理、进程模型、日志处理等。但 LLM 驱动的软件带来了全新挑战：

• 非确定性：同样的输入可能产生不同输出，这让传统的单元测试和集成测试方法失效
• 幻觉：模型可能生成看似合理但实际错误的内容，在医疗、金融等场景下后果严重
• 上下文窗口限制：无法一次性加载所有相关信息，需要精心设计信息筛选策略
• 延迟与成本：每次调用都有时间和金钱成本，不加控制的调用会导致账单爆炸
• 安全与合规：模型可能泄露敏感信息或执行有害操作，传统安全模型无法直接套用

这些挑战不是边缘情况，而是 LLM 系统的固有特性。12-Factor Agents 就是为这些挑战而生的设计原则，每一条都对应生产环境中的真实痛点。

为什么经典方法论需要扩展

Heroku 的 12-Factor App 在 2011 年提出时，解决了从本地开发到云端部署的过渡问题。当时的核心挑战是环境一致性、配置管理和进程模型。十多年后的今天，云原生已经成为默认，新的挑战来自 AI 的不确定性。

LLM 应用与传统应用的根本区别在于行为不可完全预测。你不能像测试传统函数那样给一组输入就期望固定输出。这意味着需要全新的设计原则来管理不确定性、保证可靠性、控制成本。

12 条原则概览

I. 以代码为唯一可信源（Code as the Source of Truth）

LLM 的输出是建议，不是事实。系统的核心逻辑、业务规则、数据验证必须以代码形式明确表达，不能依赖模型"理解"后正确执行。

这条原则的本质是不信任模型的判断。模型可以建议、可以生成、可以辅助，但最终的决策权必须交给确定性的代码。比如转账金额的计算、权限校验、数据格式验证，这些都不能交给模型处理。模型可能"理解"了业务规则，也可能只是碰巧生成了看起来正确的输出。代码是确定的、可测试的、可审计的，这是生产系统的底线。

II. 显式上下文管理（Explicit Context Management）

不要假设模型能自动获取所需信息。开发者必须显式决定：

• 什么信息进入上下文
• 信息的优先级和顺序
• 上下文截断时的处理策略

上下文窗口是有限的资源，就像 CPU 内存一样需要管理。很多开发者犯的错误是把所有相关信息都塞进提示词， hoping 模型能自己筛选。更好的做法是主动设计上下文策略：核心信息优先放入，辅助信息按需加载，冗余信息主动剔除。当上下文接近上限时，要有明确的截断规则，而不是让模型自己"看着办"。

III. 工具即契约（Tools as Contracts）

模型调用的每个工具都必须有明确的输入输出契约。包括：

• 参数类型和验证规则
• 返回值结构
• 错误处理模式
• 副作用声明

工具是模型与外部世界交互的边界。没有契约的工具就像没有 API 文档的接口，模型只能猜测怎么调用、期望什么返回。契约让工具调用从"猜测游戏"变成"确定性协议"。特别是副作用声明——模型需要知道调用这个工具会不会修改数据、发送邮件、扣款，才能做出负责任的决策。

IV. 人机协作设计（Human-in-the-Loop by Design）

不要把 LLM 当作全自动黑箱。系统设计必须包含人工审查点，特别是在：

• 高风险操作（资金转移、数据删除）
• 低置信度输出
• 首次执行的新工作流

人机协作不是"模型不行就找人兜底"，而是系统设计的核心组成部分。好的设计会明确标注哪些决策需要人类参与，并提供清晰的上下文帮助人类快速判断。比如在医疗诊断系统中，模型可以生成初步诊断建议，但最终诊断必须由医生确认，且系统要展示模型做出这个建议的依据。

V. 渐进式自治（Progressive Autonomy）

系统应该从"完全人工审核"开始，逐步扩展到"完全自主"。每个阶段的过渡都需要：

• 明确的置信度阈值
• 完整的审计日志
• 快速回滚机制

渐进式自治是风险管理的核心策略。新上线的 Agent 不应该第一天就全自动运行，而是先在人工监督下收集表现数据，确认可靠性后再逐步放开。置信度阈值要基于实际数据设定，而不是拍脑袋决定。审计日志让每次自治决策都可追溯，出了问题能快速定位。回滚机制确保当自治表现不佳时，可以立即切回人工模式。

VI. 确定性回退（Deterministic Fallbacks）

当 LLM 失败时，系统必须有确定性的回退路径。不能出现"模型不响应就卡住"的情况。

回退策略需要分层设计。第一层是重试，模型调用失败时自动重试几次。第二层是降级，切换到更简单的模型或规则引擎。第三层是人工接管，通知运维人员介入。每一层回退都要有明确的触发条件和执行逻辑，不能依赖模型"自我修复"。

VII. 输出验证（Output Validation）

所有 LLM 输出都必须经过验证才能进入下游系统。验证包括：

• 格式校验（JSON Schema、类型检查）
• 业务规则检查
• 安全扫描（PII、注入攻击）

输出验证是防止模型幻觉的最后一道防线。即使模型生成了看起来合理的输出，也可能包含格式错误、违反业务规则或泄露敏感信息。验证层应该是强制性的、自动化的，不能因为是"AI 生成的"就跳过检查。

VIII. 成本与延迟预算（Cost and Latency Budgets）

为每个 LLM 调用设定明确的成本和延迟上限。系统必须能：

• 监控实际消耗
• 在接近上限时降级
• 提供成本透明的计费

LLM 调用是按量计费的，没有预算控制的系统就像没有限速的高速公路。成本预算防止账单失控，延迟预算保证用户体验。当接近上限时，系统应该自动降级——比如切换到更便宜的模型、减少上下文长度、启用缓存结果。

IX. 可观测性（Observability）

LLM 系统的可观测性比传统系统更重要。必须记录：

• 完整的输入输出
• 上下文组成
• 工具调用链
• 模型版本和参数

当 LLM 系统出问题，"它刚才做了什么"是最难回答的问题。因为每次调用的输入输出都可能不同，没有完整日志就无法复现和调试。可观测性不仅是运维需要，也是合规要求——很多行业需要证明 AI 系统的决策过程是可审计的。

X. 版本化提示（Versioned Prompts）

提示词是代码，必须版本化管理。包括：

• Git 版本控制
• A/B 测试支持
• 回滚能力
• 变更影响分析

提示词的变化会直接影响模型行为，一次"小优化"可能导致系统表现大幅下降。版本化管理让提示词变更像代码变更一样可追溯、可回滚、可测试。A/B 测试支持让你可以科学评估提示词修改的效果，而不是凭感觉判断。

XI. 安全沙箱（Security Sandboxing）

LLM 调用的工具必须在受限环境中执行。假设模型可能被攻击者操控，工具必须具备：

• 最小权限原则
• 输入消毒
• 执行超时
• 资源限制

安全沙箱的核心假设是模型不可信。攻击者可能通过精心构造的输入让模型执行恶意操作，比如删除数据、泄露信息、发起网络攻击。沙箱限制工具的执行权限，即使模型被操控，造成的损害也被控制在最小范围。

XII. 持续评估（Continuous Evaluation）

建立持续评估流水线，定期测试系统在生产数据上的表现。不是一次性测试，而是持续监控模型漂移、性能退化和安全漏洞。

模型性能会随时间变化，即使模型版本没变，输入数据的分布变化也可能导致表现下降。持续评估让团队能及时发现这些问题，而不是等到用户投诉才意识到。评估应该覆盖准确性、延迟、成本、安全性多个维度，形成完整的健康度仪表盘。

实践意义

12-Factor Agents 不是教条，而是经过生产验证的经验总结。它的价值在于：

• 降低风险：明确的原则帮助团队避免常见陷阱
• 提高可维护性：结构化的设计让系统更容易理解和修改
• 促进协作：共同的方法论让团队成员能快速对齐
• 支持审计：清晰的设计决策便于合规审查

与经典 12-Factor 的关系

适用人群

• 正在将 LLM 应用投入生产的工程团队
• 需要建立 AI 系统设计规范的架构师
• 追求可维护性和可靠性的技术负责人
• 需要向非技术利益相关者解释 AI 系统风险的决策者

12-Factor Agents 代表了 AI 工程从"实验"走向"工程化"的标志性转变。当 LLM 从演示变成基础设施时，我们需要的不只是更好的模型，而是更好的工程原则。