---
title: 生产化清单
url: https://doc.liz6.com/ai/03-applications-and-production/05-production-checklist
locale: zh
area: ai
tags:
- ai
- 应用与生产
date: 2026-06-30
modified: 2026-07-16
description: 把前面所有篇章拧成一条上线生命周期:从"先有评估集"到"灰度发布",再到"线上每翻一次车就加一道回归"。这是 ai 板块的终点页,也是一张随手能查的核对表。
---
# 生产化清单
> 把前面所有篇章拧成一条上线生命周期:从"先有评估集"到"灰度发布",再到"线上每翻一次车就加一道回归"。这是 ai 板块的终点页,也是一张随手能查的核对表。
## 概述
前面十几篇拆开讲了模型、上下文、agent、应用模式。这一篇反过来——**把它们按一个 LLM/agent 应用上线的时间顺序串成一条线**,既做收尾综合,也做可勾选的核对表。
核心信念两条,贯穿始终:
- **没有评估就没有迭代。** 改了 prompt、换了模型、加了工具,凭什么说"变好了"?——靠 eval,不靠手感(见 [评估与可观测](/ai/02-Agent/05-evaluation-and-observability.md))。
- **先确认要不要上,再谈怎么上。** 能用 [workflow](/ai/02-Agent/01-the-agent-loop-and-tool-use.md) 写死的别上 agent,能 [单 agent](/ai/02-Agent/04-multi-agent-orchestration.md) 的别上多体——最稳的系统是最简单那个。
## 上线生命周期
```mermaid
flowchart TD
A["① 选层
workflow? agent? 多体?"] --> B["② 建 eval 集
小而真实, 含边界"]
B --> C["③ 调 prompt/模型/effort
对着 eval 调"]
C --> D["④ 装防护
沙箱/权限/注入/secret"]
D --> E["⑤ 接可观测
trace + usage + stop_reason"]
E --> F["⑥ 灰度发布
小流量, 可回滚"]
F --> G["⑦ 线上翻车
固化成回归 eval"]
G --> C
```
下面逐档给核对项,每项都指回它详细展开的那一篇。
## ① 选对层级:别急着上 agent
上 agent 前过 [四道关](/ai/02-Agent/01-the-agent-loop-and-tool-use.md)(任一为否就退回更简单的层):
- [ ] **复杂度**:任务多步且无法预先完全规定?(能写死流程 → 用 workflow)
- [ ] **价值**:结果值得更高的成本与延迟?
- [ ] **可行性**:模型确实擅长这类任务?
- [ ] **错误代价**:错了能被发现和回滚?(有测试/审查/回退)
多 agent 再加一问:**单 agent + 好工具解决不了,才上多体**(见 [多 Agent 编排](/ai/02-Agent/04-multi-agent-orchestration.md))——多体引入协调开销、上下文同步、调试复杂度。
## ② 先有评估集,再开始调
**最重要的一条实践:先有一个小而真实的 eval 集再动手。** 哪怕 20 条代表性任务(含已知失败/边界,不只 happy path),也远胜凭单条手感(见 [评估与可观测](/ai/02-Agent/05-evaluation-and-observability.md))。
- [ ] eval 集含**失败/边界用例**,不只顺路场景。
- [ ] 打分按可靠性从高到低:**可编程校验** > LLM-as-judge > outcome 评分。能 `assert` 的别请裁判——[结构化输出](/ai/03-applications-and-production/02-prompt-engineering-and-structured-output.md) 让这类校验稳定可做。
- [ ] LLM 裁判**与被测分离**(别自评自背书),给**可独立判定**的 rubric。
## ③ 对着 eval 调,别凭感觉
- [ ] **prompt**:写"何时/边界"而非堆"必须",正例优于反例(见 [提示工程](/ai/03-applications-and-production/02-prompt-engineering-and-structured-output.md))。
- [ ] **effort**:起步 `high`,在 eval 集上扫 `medium`/`high`/`xhigh` 再定——关系非单调(见 [推理与 thinking](/ai/01-models-and-context/04-reasoning-and-thinking.md))。
- [ ] **采样参数**:新模型上已移除,旧代码的 `temperature` 删掉、转译成 prompt + effort。
- [ ] **输出形状**:要喂下游就上 `output_config.format` / `strict`,别靠"请返回 JSON"。
- [ ] **知识**:私有/实时知识走 [RAG](/ai/03-applications-and-production/01-rag-and-retrieval-augmented-generation.md),先把 recall@k 顶上去再调生成。
- [ ] **上下文预算**:稳定前缀焊死保 [缓存](/ai/01-models-and-context/01-context-engineering.md),动态内容后置,长对话用 compaction / context editing。
## ④ 装防护:模型输出都不可信
上线前把 [安全与防护](/ai/03-applications-and-production/04-security-and-protection.md) 的闸都装上:
- [ ] **bash/工具**:隔离环境 + 白名单 + 超时 + 日志;命令是不可信输出。
- [ ] **路径**:规范化 + 边界校验,拒绝 `..`/符号链接/URL 编码遍历。
- [ ] **危险动作**:不可逆操作 human-in-the-loop,按可逆性分级,最小权限。
- [ ] **注入**:工具输出当数据不当指令;操作员指令走 `role:system` 可信通道。
- [ ] **secret/PII**:绝不进上下文/记忆/prompt;凭据走代理注入;多租户隔离。
- [ ] **输出侧**:读 `content` 前查 `stop_reason`(处理 refusal);输出进 SQL/HTML/shell 前转义参数化。
## ⑤ 接可观测:能回答"哪步出了问题"
上线即盲飞=灾难。接上 [评估与可观测](/ai/02-Agent/05-evaluation-and-observability.md):
- [ ] **trace/span**:每个 `tool_use`/`tool_result`/模型调用一个 span,能逐步归因延迟与成本(本站点构建时就初始化了 OTel)。
- [ ] **usage**:盯 `input/output_tokens`、`cache_read_input_tokens`(长期为 0 = 缓存静默失效)、`cache_creation_input_tokens`——总量 = 三者之和,别只看一个字段。
- [ ] **stop_reason 分布**:`max_tokens` 偏高=输出被截断;`refusal` 异常升高=prompt 触发拒绝;`pause_turn` 多=服务端工具循环在续。
- [ ] **成本/限流**:缓存命中率、429 频率上仪表盘(见 [成本、性能与可靠性](/ai/03-applications-and-production/03-cost-performance-and-reliability.md))。
## ⑥ 灰度发布:可控、可回滚
- [ ] **流式**:长输入/输出一律流式,避开非流式 HTTP 超时。
- [ ] **重试/幂等**:只重试 429/5xx;有副作用的动作带幂等键 + 人工确认。
- [ ] **归因**:并发/Batches 结果按 `custom_id`/trace id 对号,绝不靠顺序。
- [ ] **小流量先行**:新 prompt/模型先灰度一小部分,对比 eval 与线上指标,再放量;留回滚路径。
- [ ] **换模型注意缓存**:换模型作废整段缓存、要重新基线 token;别在主循环里中途切(见 [多 Agent 编排](/ai/02-Agent/04-multi-agent-orchestration.md))。
## ⑦ 回归:每翻一次车,加一道防线
- [ ] 线上每发现一个失败,**固化成一条 eval case**——这是 eval 集随时间变强的方式(见 [评估与可观测](/ai/02-Agent/05-evaluation-and-observability.md))。
- [ ] 回到 ③ 重调,跑全量 eval 确认不退化,再上。
## 最佳实践(全板块浓缩)
- **先 eval,后迭代。** 小而真实的评估集是一切改动的裁判;没有它,所有"优化"都是赌。
- **能简单就别复杂。** workflow > 单 agent > 多 agent;每升一级都要新增的协调成本配得上收益。
- **把窗口当预算经营。** 缓存焊前缀、检索优于硬塞、effort 调深浅——三件事管住成本与质量。
- **模型输出全不可信。** 安全边界在宿主执行侧:沙箱、路径校验、危险动作审批、secret 不进上下文。
- **量化每一步。** trace + usage + stop_reason 让"哪步错了"可见;缺可观测就是盲改。
- **编写与审查分两条 lane。** 执行的 agent 不自审,另起 reviewer/verifier 在独立上下文评(见 [多 Agent 编排](/ai/02-Agent/04-multi-agent-orchestration.md))。
- **线上翻车 → 离线回归。** 每个事故变一条 eval,防线只增不减。
## 权衡与失败模式
- **没 eval 就调**:凭手感改,分不清"变好"还是"换了个错法" → 先建 20 条真实 eval。
- **反射式上 agent/多体**:协调开销 > 收益、还更难调 → 过四关,能 workflow 就别 agent。
- **上线无可观测**:出问题不知道哪步、烧了多少 token → trace + usage + stop_reason 先接上。
- **缓存命中率不监控**:成本悄悄翻几倍才发现 → `cache_read_input_tokens` 进面板。
- **只测 happy path**:线上一遇边界就崩 → eval 含边界,并随事故增长。
- **执行 agent 自评**:自背书 → 评审另起独立 lane。
- **直接全量上新 prompt/模型**:回归无从对比、出事难回滚 → 灰度 + 留回滚 + 跑全量 eval。
## 参考
- **Anthropic 官方文档**: Building Effective Agents、Building Evals、Observability、Handling Stop Reasons(platform.claude.com,实现前以官方为准)
- **全板块回链**: [上下文工程](/ai/01-models-and-context/01-context-engineering.md)、[Token 与采样](/ai/01-models-and-context/02-tokens-and-sampling.md)、[模型架构](/ai/01-models-and-context/03-model-architecture-dense-vs-moe.md)、[推理与 thinking](/ai/01-models-and-context/04-reasoning-and-thinking.md)、[Agent 循环与工具](/ai/02-Agent/01-the-agent-loop-and-tool-use.md)、[MCP 与 Skills](/ai/02-Agent/02-mcp-and-skills.md)、[记忆与状态](/ai/02-Agent/03-memory-and-state.md)、[多 Agent 编排](/ai/02-Agent/04-multi-agent-orchestration.md)、[评估与可观测](/ai/02-Agent/05-evaluation-and-observability.md)、[RAG 与检索增强](/ai/03-applications-and-production/01-rag-and-retrieval-augmented-generation.md)、[提示工程与结构化输出](/ai/03-applications-and-production/02-prompt-engineering-and-structured-output.md)、[成本、性能与可靠性](/ai/03-applications-and-production/03-cost-performance-and-reliability.md)、[安全与防护](/ai/03-applications-and-production/04-security-and-protection.md)
*Keywords: 生产化, production checklist, 上线生命周期, eval-first, workflow vs agent, 灰度发布, canary, 回滚, rollback, regression, 回归, observability, trace, span, OTel, usage, stop_reason 分布, prompt caching, RAG, 结构化输出, 防护, 沙箱, secret, human-in-the-loop, 幂等, authoring vs review lane, 核对表*