Harness 工程:在 agent-first 的世界里驾驭 Codex

Harness engineering: leveraging Codex in an agent-first world · 中文翻译

原作者:Ryan Lopopolo(OpenAI Member of the Technical Staff);致谢 Victor Zhu、Zach Brock

原文发布:2026-02-11  ·  中文译稿:2026-05-14

原文链接:openai.com/index/harness-engineering

本文为社区学习用途的非官方中文翻译。技术名词以括注英文原文为准;最终解释以英文原文为准。

过去五个月里,我们团队做了一个实验:构建并发布了一款内部 beta 阶段的软件产品——手工写代码的行数为 0。

这款产品已有内部日活用户和外部 alpha 测试者。它会发布、会上线、会出 bug、会被修复。不同的是:每一行代码——业务逻辑、测试、CI 配置、文档、可观测性、内部工具——都是由 Codex 写的。我们估算,整体投入大约是手工写代码所需时间的 1/10。

人类把方向,agent 做执行。(Humans steer. Agents execute.)

我们刻意设下这道约束,倒逼自己去搭建让工程速度提升一个数量级所必需的那些东西。我们当时只有几周时间发布最终大约一百万行代码的产品。要做到这一点,必须搞清楚一件事:当一个软件工程团队的主业不再是写代码,而是设计环境、明确意图、构建反馈闭环让 Codex agent 能可靠地完成工作时,到底有哪些东西需要重新思考?

这篇文章讲的是:用一支由 agent 组成的"团队"从零做一款新产品,我们学到了什么——什么会失灵、什么会复合、以及如何最大化我们唯一真正稀缺的资源:人的时间和注意力。

我们从一个空 git 仓库开始

第一次向空仓库提交 commit,是 2025 年 8 月底的事。

最初的脚手架——仓库结构、CI 配置、格式化规则、包管理器设置、应用框架——都是用 Codex CLI 在 GPT-5 上生成的,参考了一小撮已有模板。就连最初指导 agent 如何在仓库里工作的 AGENTS.md 文件本身,也是由 Codex 写的。

没有任何预先存在的、由人类写的代码作为锚点。从一开始,整个仓库的形态就是被 agent 塑造的。

五个月之后,这个仓库大约包含百万行代码——覆盖业务逻辑、基础设施、工具、文档、内部开发者工具。这段时间内,3 名工程师驱动 Codex 开出并合并了约 1500 个 PR。换算成人均产出大约是 3.5 个 PR / 人 / 天——而且令人惊讶的是,团队扩到现在的 7 人后,人均吞吐量反而增加了。重要的是:这不是为了产出而产出——产品已被数百名内部用户使用,包括重度日活用户。

整个开发过程中,人类从未直接贡献过一行代码。这成了团队的核心信条:no manually-written code(不手写代码)。

重新定义"工程师"这个角色

不亲自动手写代码,引入了一种不同形态的工程工作——聚焦在系统、脚手架和杠杆上。

早期进展比我们预期的要慢,但不是因为 Codex 能力不足,而是因为环境不够清晰。Agent 缺少为高阶目标推进所需的工具、抽象、内部结构。我们工程团队的主要工作,变成了帮 agent 把活干漂亮。

实践中,这意味着深度优先:把更大的目标拆成更小的构件(设计、代码、评审、测试等等),prompt agent 去构造这些构件,再用它们去打开更复杂的任务。出问题时,修复方案几乎从来不是"再多试一次"。因为唯一能推进的方式就是让 Codex 来做这件事,人类工程师永远要走进任务、问自己:"缺了什么能力?怎么才能让这个能力对 agent 既可读、又可强制?"

人类几乎完全通过 prompt 与系统交互:工程师描述任务、运行 agent,让它去开 PR。要把一个 PR 推到完成,我们让 Codex 本地评审自己的改动、显式请求其他 agent 评审(本地和云端)、回应人类或 agent 的反馈,并在循环中迭代直到所有 agent 评审通过——这本质上是一个 Ralph Wiggum 循环(Ralph Wiggum Loop,一种"傻乎乎不停转直到通过"的循环范式)。Codex 直接使用我们标准的开发工具(gh、本地脚本、仓库内置的 skills)去拿上下文,不需要人类把内容粘贴到 CLI 里。

人类可以评审 PR,但不是必须。随时间推移,我们已经把几乎所有评审工作都推到了 agent-to-agent。

提升应用的"可读性"

随着代码吞吐量上升,瓶颈变成了人类的 QA 容量。由于固定的约束是"人的时间和注意力",我们一直在给 agent 加能力——让应用 UI、日志、应用指标这些东西对 Codex 直接可读。

举个例子,我们让应用可以按 git worktree 启动,这样 Codex 可以为每个改动启动一个独立实例。我们还把 Chrome DevTools Protocol 接到了 agent runtime 里,并为 DOM 快照、截图、导航这些操作建立了 skills。这让 Codex 能直接复现 bug、验证修复、对 UI 行为做推理。

Codex 通过 Chrome DevTools <a class=MCP 驱动应用以验证自己工作的示意图" />
Codex 通过 Chrome DevTools MCP 驱动应用以验证自己的工作:选定目标、在触发 UI 路径前后做状态快照、通过 Chrome DevTools 观察运行时事件、施加修复、重启,并循环地重新运行验证直到应用干净。

我们对可观测性工具也做了同样的事。日志、metrics、traces 通过一个本地可观测性栈暴露给 Codex——这套栈针对任意 worktree 都是临时的(ephemeral):Codex 工作在一个完全隔离的应用版本上,包括它的日志和指标,任务完成后整套栈被销毁。Agent 可以用 LogQL 查询日志、用 PromQL 查询指标。有了这层上下文,像"确保服务启动在 800ms 内完成"或"这 4 条关键用户路径里没有任何一个 span 超过 2 秒"这样的 prompt,就变成可执行的目标。

把完整可观测性栈交给本地开发中的 Codex
把完整可观测性栈交给本地开发中的 Codex:应用把日志、指标、traces 发到 Vector,Vector 分发给包含 Victoria Logs / Metrics / Traces 的可观测性栈,分别通过 LogQL / PromQL / TraceQL API 查询;Codex 用这些信号做查询、关联、推理,然后在代码库里实施修复、重启应用、重跑 workload、测试 UI 路径,在反馈闭环中循环。

我们经常看到单次 Codex run 在一个任务上跑超过 6 小时(往往是趁人睡觉的时候)。

我们把"仓库知识"做成了系统记录源

上下文管理是把 agent 用在大型复杂任务上的最大挑战之一。我们最早学到的一课很简单:给 Codex 一张地图,而不是一本 1000 页的说明书。

我们试过"一份大而全的 AGENTS.md"方案。它会按以下可预测的方式失败:

所以我们不再把 AGENTS.md 当百科全书,而是把它当目录页(table of contents)。

仓库的知识库存放在一个结构化的 docs/ 目录里,它才是系统记录源(system of record)。一份大约 100 行的简短 AGENTS.md 被注入到上下文中,主要作为一张地图,指向其他地方更深的真理源。

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   ├── index.md
│   ├── new-user-onboarding.md
│   └── ...
├── references/
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   ├── uv-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

仓库内知识库的版面布局。

设计文档被编目和索引,包含其验证状态以及定义 agent-first 运行原则的核心信条(core beliefs)。架构文档给出领域和包分层的顶层地图。一份质量文档(quality document)给每个产品领域和架构层级打分,跟踪 gap 随时间的变化。

计划被当作一等产物(first-class artifacts)。小改动用临时轻量化的 plan;复杂工作用 execution plans 来承载,其中包括进展与决策日志,都签入仓库。Active plans、completed plans、known technical debt 全部版本化、共址(co-located),让 agent 不需要依赖外部上下文就能工作。

这就实现了 渐进式展开(progressive disclosure):agent 从一个小而稳定的入口点开始,被教会"接下来去看哪里",而不是一上来就被海量信息淹没。

我们用机械方式强制执行这一切。专门的 linter 和 CI job 校验知识库是否最新、交叉链接是否完整、结构是否正确。一个定期跑的 "doc-gardening" agent(文档园丁)扫描那些与真实代码行为不符的过时或废弃文档,并开 PR 修复。

"Agent 可读性"才是终极目标

随着代码库演化,Codex 做设计决策的框架也必须跟着演化。

因为这个仓库完全是 agent 生成的,它首先优化的是 Codex 的可读性(legibility)——和团队设法提升代码对新工程师的可导航性是一样的道理,我们人类工程师的目标是:让 agent 能直接从仓库本身推理出完整的业务领域。

从 agent 的视角看,运行时上下文里访问不到的东西,等同于不存在。存在 Google Docs、聊天串、或者别人脑子里的知识,系统就看不到。只有仓库内的、版本化的产物(代码、markdown、schema、可执行 plan 等)它才能看到。

Agent 知识的边界:Codex 看不到的东西就不存在
Agent 知识的边界:"Codex 看不到的东西就不存在"。Codex 的知识被画成一个有界气泡。下方是它看不到的知识例子——Google Docs、Slack 消息、人脑里的隐性知识。箭头表示要让这些信息对 Codex 可见,必须把它们编码进代码库里的 markdown。

我们逐渐学到:得把越来越多的上下文搬进仓库。那场让团队在某个架构模式上达成一致的 Slack 讨论?如果对 agent 不可发现,它就和"三个月后加入的新员工没听说过一样不可见"。

给 Codex 更多上下文,意味着组织和暴露正确的信息让 agent 能在上面推理,而不是用一堆零散指令把它淹没。就像你给新队友讲产品原则、工程规范、团队文化(包括偏好哪种 emoji)一样——给 agent 这些信息,它的输出会与你更对齐。

这种视角厘清了不少 tradeoff。我们偏好那些可以被 agent 完整内化、并能在仓库内推理的依赖与抽象。那些被称为"无聊(boring)"的技术,往往因为组合性、API 稳定性、以及在训练集里的覆盖度,更容易被 agent 建模。某些情况下,让 agent 重新实现某段功能,比绕开公共库不透明的上游行为更便宜。例如,与其引入一个通用的 p-limit 风格的包,我们让它自己实现了一个 map-with-concurrency helper——它和我们的 OpenTelemetry 桩深度集成、100% 测试覆盖、行为完全符合 runtime 的预期。

把更多系统拉进 agent 能直接检视、校验、修改的形式里,就是在放大杠杆——不仅对 Codex 如此,对其他在这个代码库里干活的 agent(例如 Aardvark)也是如此。

强制执行架构与品味

光有文档留不住一个完全由 agent 生成的代码库的一致性。通过强制不变量(invariants),而非微观管理实现,我们让 agent 既能快速发布、又不会从根基上崩坏。例如,我们要求 Codex 在边界处解析数据(parse, don't validate),但不规定具体怎么做(模型似乎偏爱 Zod,但我们并没指定要用这个库)。

Agent 在边界严格、结构可预测的环境里最有效——参见 "AI 在逼我们写好代码" 这一类观点——所以我们围绕一套刚性架构模型来组织应用。每个业务领域被划分成一组固定的层级,依赖方向被严格校验,允许的连接边(permissible edges)也很有限。这些约束通过自定义 linter(当然也是 Codex 生成的!)和结构性测试用机械方式强制执行。

下图展示了这条规则:在每个业务领域内(如 App Settings),代码只能"向前"穿过一组固定的层级——Types → Config → Repo → Service → Runtime → UI。横切关注点(auth、connectors、telemetry、feature flags)通过一个显式接口 Providers 进入。除此之外的依赖一律禁止,并由机制强制。

分层领域架构与显式横切边界
分层领域架构与显式横切边界:在业务逻辑域内部,模块按 Types → Config → Repo,以及 Providers → Service → Runtime → UI 的方向单向排列,底部是 App Wiring + UI;Utils 模块位于边界之外,喂给 Providers。

这是那种通常要等到团队有几百号工程师才会上的架构。有了 coding agent,它反而是个早期前提——这些约束正是让你"既能快、又不腐烂、不漂移"的东西。

实践中,我们用自定义 linter 和结构性测试,再加上少量"品味不变量(taste invariants)"来强制规则。例如,我们静态强制结构化日志、schema 与 type 的命名约定、文件大小上限、以及平台层的可靠性要求。因为 linter 是自定义的,我们把错误信息写成"会把修复指令注入 agent 上下文"的格式。

在以人为本的工作流里,这些规则可能让人觉得啰嗦、束手束脚。但配上 agent,它们就成了乘数:一旦编码下来,会同时作用到所有地方。

与此同时,我们对"约束在哪里重要、在哪里不重要"也很显式。这种方式很像带一个大型工程平台组织:边界集中强制、局部允许自治。你对边界、正确性、可复现性极度上心;在这些边界之内,你给团队——或 agent——很大的方案表达自由。

最终产出的代码不一定符合人类的风格偏好,没关系。只要它正确、可维护、对未来的 agent run 可读,就达到了门槛。

人类的品味会被持续反馈进系统。评审意见、重构 PR、用户反馈的 bug——要么被记入文档更新,要么被直接编码进工具链。当文档不够用时,我们就把规则升级成代码(promote the rule into code)。

吞吐量改变了合并哲学

随着 Codex 的吞吐量上升,许多传统工程规范开始适得其反。

我们的仓库以最少的阻塞式合并门控(minimal blocking merge gates)运行。PR 寿命很短。测试 flake 通常用"重跑一次"解决,而不是无限地阻塞进度。在一个 agent 吞吐量远超人类注意力的系统里,纠错很便宜、等待很贵。

在低吞吐量环境里这样干很不负责任。但在这里,这往往是正确的 tradeoff。

"Agent 生成"到底意味着什么

当我们说"这个代码库是 Codex agent 生成的"时,我们指的是代码库里的一切。

Agent 产出:

人类始终在闭环中(in the loop),但工作在一个不同的抽象层级。我们排优先级、把用户反馈翻译成验收标准、并验证结果。当 agent 卡住时,我们把这视为一个信号:找出缺什么——工具、护栏、文档——再把它喂回仓库,修复永远由 Codex 自己来写。

Agent 直接使用我们标准的开发工具:拉评审反馈、内联回复、推更新、并常常自己 squash & merge 自己的 PR。

自主性的层级在不断提升

当开发循环越来越多地被直接编码进系统里——测试、校验、评审、反馈处理、恢复——仓库最近跨过了一道有意义的门槛:Codex 可以端到端驱动一个新功能。

只给一句 prompt,agent 现在能做到:

这种行为高度依赖这个仓库的特定结构和工具,不能假定它在没有同等投入的前提下就能泛化——至少现在还不行。

熵与垃圾回收

完整 agent 自主性也带来了新的问题。Codex 会复现仓库里已经存在的模式——哪怕那些模式参差不齐或是次优的。随时间推移,这必然导致漂移(drift)。

最开始,人类靠手动来管。我们团队曾经每周五(每周的 20%)都用来打扫"AI 垃圾代码(AI slop)"。不出所料,这一套没法 scale。

后来我们改成把所谓的"黄金原则(golden principles)"直接编码进仓库,并构建了一个周期性的清理流程。这些原则是有立场、机械化的规则,目的是为未来的 agent run 保持代码库可读、一致。举两个例子:(1) 我们偏好共享 utility 包而不是手写 helper,把不变量集中管理;(2) 我们不"YOLO 式地探测数据形状"——要么在边界处校验、要么依赖类型化 SDK,这样 agent 就不会基于"猜测出来的结构"误打误撞。按固定节奏跑一组后台 Codex 任务,扫描偏差、更新质量评分、并开有针对性的重构 PR。这些 PR 大多一分钟内能审完并自动合入。

这种机制的功能就像垃圾回收(garbage collection)。技术债像一笔高利贷:与其让它复利累积、攒到痛苦的批量整理日,不如连续小额偿还。人类的品味只表达一次,然后被持续地强制执行到每一行代码上。这也让我们能每天捕获并解决坏模式,而不是任由它们在代码库里散播数天甚至数周。

我们还在学的东西

至今为止,这套打法在 OpenAI 内部上线和采用阶段表现良好。给真实用户做一款真实产品——这件事帮我们把投入锚定在现实里,把方向往长期可维护性上拉。

我们仍不知道的是:在一套完全由 agent 生成的系统里,架构一致性会如何随年份演化。我们仍在学人类判断在哪里增益最大、以及如何把这种判断编码下来让它复利。我们也不知道随着模型继续变强,这套系统会如何演变。

已经清楚的是:做软件依然需要纪律,但纪律更多体现在脚手架,而不是代码本身。让代码库保持一致的工具链、抽象和反馈闭环变得越来越重要。

我们当前最难的挑战,已经转向"设计环境、反馈闭环和控制系统"——这些东西帮 agent 完成我们真正的目标:大规模地构建并维护复杂、可靠的软件。

随着 Codex 这样的 agent 接手软件生命周期中越来越大的部分,这些问题只会变得更重要。希望分享这些早期经验,对你思考"该把精力投到哪里"有所帮助,让你可以直接造东西。


术语速查表

答案中以 [术语] 标记的概念都可点击跳到本表对应条目并自动展开。本表按 10 个主题分组收录 60+ 高频术语,默认全部收起——遇到不熟的术语再展开看精要解释,避免被信息淹没。

软件工程基础

lint 软件工程 — 静态代码检查工具,扫描源码找潜在 bug 与风格问题

不实际运行代码的情况下分析源码,识别潜在 bug、未使用变量、风格违规、可疑用法。常见工具:

在 Agent 工程中,lint 经常被用作 harness 的硬约束——把 lint 错误反馈给模型重写代码,比单纯在 prompt 里说"请遵守编码规范"可靠得多(Augment Code 把这叫做 Constraint Harness)。

type check / 类型检查 软件工程 — 验证变量、参数、返回值类型是否匹配

确保代码中变量赋值、函数调用的类型一致:

对 Agent:让 agent 写完代码后强制跑 tsc --noEmit / mypy . / cargo check,类型错误作为反馈喂回模型继续修。比让 agent 自己"声明检查过类型"可靠得多——这是 harness 工程的典型做法。

CI/CD 软件工程 — 持续集成 / 持续部署流水线

CI(Continuous Integration):每次代码提交自动跑测试、构建、lint、type check 等校验。
CD(Continuous Deployment):通过校验后自动部署到测试 / 预发 / 生产环境。

常见工具:GitHub Actions、GitLab CI、Jenkins、CircleCI、Buildkite。

在 Agent 工程里,CI 是最重要的 deterministic 反馈源——LLM 自评不可靠,但 CI 通过/失败是 0/1 信号,可以直接作为 ground truth。Hashimoto 的 harness engineering 强调"能不能解决问题强相关于 agent 能不能验证自己的工作"。

sandbox / 沙箱 软件工程 — 隔离的代码执行环境,限制对外部资源的访问

让不可信代码(用户上传、LLM 生成)在受限环境中跑,防止破坏宿主系统。隔离强度从弱到强:

Agent 跑用户/LLM 生成代码必须沙箱,并叠加纵深防御:网络出口白名单 + 文件系统只读 + 时间/内存配额 + 不挂载 host 凭据。

canary / 金丝雀发布 软件工程 — 先给少量流量上新版本,观察无异常再全量

来自煤矿用金丝雀检测毒气的典故。部署流程典型为:shadow(双跑不返回)→ 1% → 5% → 25% → 50% → 100%,每阶段观察核心指标无回归才推进。

对 LLM 应用:新 prompt / 新模型 / 新 agent harness 上线必走 canary,关键指标(解决率、CSAT、refusal 率、p99 延迟、单次成本)任何一个恶化 > 阈值就回滚。LLM 应用的"非确定性"特性让 canary 比传统软件更重要。

A/B test 软件工程 — 对照试验,把流量切成两组分别用新旧版本,比较关键指标差异

按 user_id hash 切流量保证一个用户始终进同一桶(避免体验跳变)。判定要素:

LLM 应用调 prompt / 换模型 / 改 RAG 都应过 A/B;只靠 offline eval 上线常翻车(线上流量分布与黄金集差异大)。

GMV / UV / CSAT / NPS / 转化率 业务指标 — 电商 / 旅行 / 客服业务最常用的几个北极星指标

业务侧验收 Agent 是否上线最看的几个指标:

Agent 工程关注:把模型 / prompt / RAG 改动放进 A/B 看这些业务指标,而非只看离线 benchmark 分数。改动让 benchmark 涨但 GMV / CSAT 跌的情况非常常见。

HITL / human-in-the-loop 软件工程 — 关键决策点引入人工审核 / 确认

Agent 自治走到关键节点时暂停等待人工:

设计原则:"Humans steer. Agents execute."(OpenAI Harness Engineering)。Agent 不是替代人,是放大人的判断——把人放在制定计划、设定约束、审核结果的位置,agent 处理执行。

SLO / SLI / SLA / Error Budget 软件工程 — 服务质量的"目标 / 指标 / 合约 / 预算"四件套,来自 SRE

Google SRE 体系定义的四个术语:

Agent 应用怎么用:

  1. 每个 Agent 场景定 1-3 个 SLO:如"客服 Agent 解决率 SLO = 85%"、"p99 端到端延迟 SLO ≤ 5s"、"单任务平均成本 SLO ≤ $0.05"
  2. 触发告警:实时 SLI 跌破 SLO 80% 警告,跌破 SLO 直接 page oncall
  3. 冻结发布:error budget 烧完了,禁止合并非紧急修复
  4. 业务 SLO vs 技术 SLO:业务 SLO(转化率 / CSAT / GMV)属于产品验收,技术 SLO(延迟 / 错误率 / cost)属于工程兜底,两层都要

经验法则:SLO 不是越严越好——99.99% 比 99.9% 贵 5-10 倍,且大概率超过用户感知阈值。Google 建议"刚刚够用户不抱怨"的水位。

TTL / Time To Live 软件工程 — 数据 / 缓存 / 凭据的有效期

到期自动失效。常见用法:

LLM 基础概念

token LLM 基础 — LLM 的最小输入/输出单位,由 tokenizer 切分得到

经验换算:1000 英文单词 ≈ 1300 token;1000 汉字 ≈ 1500-2000 token。

为什么重要:context window、API 计费、推理速度都按 token 算。控制 token 数 = 控制成本和延迟。Anthropic / OpenAI / Google 各自的 tokenizer 不同,相同文本 token 数差 ±20% 很常见。

embedding LLM 基础 — 把文本/图片映射为高维稠密向量,语义相近的向量距离近

文本 → 神经网络 → 一个 768 / 1024 / 1536 / 3072 维的浮点数向量。同义词 / 同主题文本的向量在空间中距离近(cosine similarity 高)。

主要用途:

主流模型 2026:OpenAI text-embedding-3-large、Cohere v4、Voyage-3、BGE-M3(开源 SOTA,中英双语 + dense/sparse/multi-vector 三合一)。

context window / 上下文窗口 LLM 基础 — 模型单次能处理的 token 上限

包含 system prompt + 历史对话 + 用户输入 + 模型输出,所有都计算在内。2026 主流模型:

注意:宣称窗口 ≠ 有效窗口。RULER 基准显示多数模型在窗口 1/4 之外性能急剧下降(Lost in the Middle)。工程建议把"应当塞入 context"的阈值定在 8-32k,更长走 RAG 或层级摘要。

prefill / decode LLM 基础 — LLM 推理的两阶段:处理输入 → 逐 token 生成

两个阶段瓶颈不同,调优策略也不同——prefill 优化靠并行 / FlashAttention,decode 优化靠 continuous batching / speculative decoding。

KV cache LLM 基础 — 注意力中已计算过的 K (Key) / V (Value) 矩阵缓存

生成第 t 个 token 时需要前面所有 token 的 K/V 参与注意力计算。把它们缓存下来避免每次重算,是 LLM 推理的最基础优化。

显存占用:2 × num_layers × num_heads × head_dim × seq_len × batch × bytes_per_elem。70B 模型上 128k 上下文的 KV cache 可达数十 GB,远超模型权重本身。

进阶优化:

autoregressive / 自回归 LLM 基础 — 一次生成一个 token,下一个 token 的生成依赖前面所有 token

GPT 类 decoder-only 模型的生成方式:P(x_t | x_1, ..., x_{t-1})。每生成一个 token 都要跑一次完整 forward(虽然能复用 KV cache),所以输出长度直接决定延迟。

对比:BERT 是非自回归(masked LM,一次预测所有 mask 位置),扩散模型(diffusion)也是非自回归(一次去噪整段)。

自回归的代价催生了大量加速技术:speculative decoding、parallel decoding、Medusa、EAGLE 等。

logit LLM 基础 — 模型输出的原始未归一化得分,每个词汇表 token 一个值

decoder 最后一层输出 [vocab_size] 维的 logit 向量;过 softmax 后得到下一个 token 的概率分布。

工程上能拿到 logit(或 top-k logprob)的场景:

注意:OpenAI / Anthropic 商用 API 默认只返回采样结果,需显式开 logprobs 选项。

temperature LLM 基础 — 控制采样随机性的超参数,0 = 确定性,>1 = 高随机

P(token) ∝ exp(logit / T):

何时调高:Self-Consistency 需要多样路径、creative writing、brainstorm。
何时调低:代码生成、数学推理、严格格式输出,T=0.1-0.3。

陷阱:T=0 不完全等同 deterministic——浮点 GPU 算子的非确定性 + 并发调度可能让相同 prompt 的输出仍有微差。

attention sink LLM 基础 — 模型把大量注意力集中到序列开头几个 token 的现象

Xiao et al. 2023 发现:长序列推理时,靠后的 token 往往把不成比例多的注意力分给了序列最前面的几个 token(即使它们语义无关)——这些 token 成为"sink",吸收掉 softmax 必须分配的归一化质量。

工程意义:

Transformer 架构

LayerNorm / RMSNorm 架构 — Transformer 主流归一化层,沿 feature 维度对单样本归一化

LayerNorm:y = (x - μ) / σ * g + b,沿 hidden 维度求均值方差。与 batch 无关,天然支持变长序列与单条推理——这是 Transformer 选 LayerNorm 而非 BatchNorm 的原因。

RMSNorm(Zhang & Sennrich 2019):y = x / sqrt(mean(x²)+ε) * g,去掉减均值和 bias。Llama / PaLM / Mistral 等现代 LLM 几乎都改用 RMSNorm,省 7-64% 归一化耗时且效果不降。

Pre-LN vs Post-LN:LN 在残差前做(Pre-LN)训练比放残差后(Post-LN)稳定,可去掉 warmup,GPT-2 起几乎统一用 Pre-LN。

RoPE / Rotary Position Embedding 架构 — 旋转位置编码,把位置信息编码进 Q/K 旋转矩阵

Su et al. 2021。把位置 m 表示为旋转矩阵 R_m 作用在 Q/K 上,使得 <R_m·q, R_n·k> = f(q, k, m-n)——注意力得分只依赖相对距离。

优点:(1) 无额外参数;(2) 天然编码相对位置;(3) 可与线性注意力兼容。已成 Llama / Qwen / Mistral 等绝大多数现代 LLM 的位置编码方案。

外推问题:纯外推 2k→32k 会崩——高频分量旋转角度落入未见区域。缓解:

NTK-aware scaling / YaRN 架构 — RoPE 长度外推方案,让 2k 训练的模型能跑 32k / 128k context

RoPE 纯外推会崩——高频分量在训练上下文外旋转角度落入未见区域。两种工程化方案:

主流应用:

经验数字:YaRN 在 4× 上下文扩展(2k→8k 或 32k→128k)几乎无损;8× 以上仍有性能下降。极致长上下文(1M+)通常需要重训而非仅靠 YaRN。

GQA / MQA 架构 — Grouped/Multi Query Attention,多个 Q 头共享同一组 K/V 头

标准 multi-head attention:H 个头各有独立 Q/K/V。

收益:KV cache 减小到 1/8 ~ 1/H,推理吞吐显著提升,效果几乎无损。Llama-2 70B / Llama-3 / Mistral / Qwen2 等都用 GQA。

MoE / Mixture of Experts 架构 — 混合专家模型,每个 token 只激活部分 expert FFN

把传统 dense FFN 换成 N 个并行的 expert FFN + 一个 router。每个 token 通过 router 选 top-k 个 expert(k 通常 1-2),只激活这部分 expert 计算。

优点:参数量大、算力省。Mixtral 8x7B 总参数 47B,激活参数仅 13B;DeepSeek-V3 671B 总参数,激活仅 37B。同等推理成本下 capacity 远超 dense 模型。

挑战:(1) 训练时负载均衡(防一两个 expert 被过度使用);(2) 显存占用按总参数计而非激活参数;(3) 通信开销大(expert parallelism)。

multi-head attention / 多头注意力 架构 — 把 d_model 拆成 h 份独立投影 Q/K/V,每头学不同子空间的关系

单头注意力对每对 token 只产生一个 attention 分布——一种"关系视角"。多头(h=8/32/64/128)让模型同时学多种关系——句法头关注短距离依赖,语义头关注共指、远程实体。

为什么单头加大维度不行:多头是 h 个低秩注意力的混合,表达能力严格更强;单头是一个高秩注意力,自由度反而少。

进阶变体:GQA / MQA 在 KV 侧减头省显存,Q 侧仍保多头。

推理加速

FlashAttention 推理加速 — 通过 tiling + online softmax 不实例化完整 attention 矩阵的 attention 计算

Dao 2022。标准 attention 显存 O(N²)(要存 N×N 的 attention matrix),长序列瓶颈。FlashAttention 把 Q/K/V 分块加载到 GPU SRAM 计算,不写出完整 attention matrix,显存降到 O(N),速度也快——attention 是 memory-bound,少读 HBM 就快。

演进:

PagedAttention 推理加速 — vLLM 提出,把 KV cache 像 OS 虚拟内存一样切成固定大小 block 管理

Kwon et al. 2023。解决传统推理 KV cache 的三类碎片问题:

机制:KV cache 切成固定大小 block(如 16 token),每个序列维护 block table(逻辑→物理映射)。显存利用率从 ~20% 提到 >96%;同 prompt 多采样共享前缀 block;配合 continuous batching 吞吐相对 HuggingFace TGI 提升 2-4×,相对 FasterTransformer 24×。

vLLM 推理加速 — UC Berkeley 开源的高吞吐 LLM 推理引擎,实现 PagedAttention

2023 年起的事实标准开源推理服务器。核心特性:

对比:TGI(HuggingFace)、TensorRT-LLM(NVIDIA,私有更快)、SGLang(前缀复用更彻底)、LMDeploy(OpenCompass 出品)。

continuous batching 推理加速 — 按 token 级别动态调度,请求结束即退出、新请求随时插入

也叫 in-flight batching,Yu et al. ORCA 2022 提出。对比 static batching(等齐 batch 再一起跑,长短请求混在一起时 GPU 利用率经常 <30%),continuous batching:

vLLM 数据:吞吐相比 static 提升 5-23×。已成所有现代推理引擎的默认。

speculative decoding 推理加速 — 小 draft 模型快速猜 K 个 token,大模型一次 forward 并行验证

Leviathan et al. 2023。流程:

  1. 小 draft model(1-7B)自回归生成 K 个 token(K=5 典型)
  2. 大 target model(70B+)一次 forward 并行验证 K+1 个位置
  3. 前 j 个被接受 + 第 j+1 个拒绝 → 保留前 j 个 + 采样一个新 token

数学上保证输出分布与原模型完全一致(rejection sampling)。

收益条件:(1) draft 与 target 分布相似(接受率 >60%);(2) 大模型受 memory bandwidth 限制,并行验证不增延迟。代码生成接受率 70-90%,开放生成 30-50%。变体:EAGLE-2/3、Medusa、Llama 3.1 self-speculative。

prefix caching 推理加速 — 跨 request 缓存相同前缀的 KV cache,跳过 prefill 重新计算

KV cache 是单 request 内复用;prefix caching 是跨 request 复用——多个 request 共享 system prompt / few-shot / agent 历史时,首次计算后缓存这部分 KV,后续 request 直接命中跳过 prefill。

效果:agent / RAG / 多轮对话场景,system prompt 通常 1-4k token、几乎所有请求共享,TTFT 可下降 10-100×。

实现:vLLM --enable-prefix-caching、SGLang RadixAttention(用 radix tree 自动管理所有历史前缀)、Anthropic prompt caching API(5min TTL,cached 部分 0.1× 价格)。

TTFT / Time to First Token 推理加速 — 从 request 发出到第一个 token 返回的延迟

主要由 prefill 决定(处理 input 所有 token)。计费、监控的核心指标之一。

降低 TTFT 的手段:

伴生指标:TBT(time between tokens,单 token 间隔)— 由 decode 决定。

量化

FP16 / BF16 / FP8 量化 — 低精度浮点格式,省显存省算力

混合精度训练:权重和梯度用 BF16/FP16,optimizer state 仍用 FP32。

INT4 / INT8 / NF4 量化 — 整数量化,把 FP16 权重压到 4/8 bit 整数

部署阶段把权重量化到低 bit 整数,推理时反量化回浮点计算。

INT8 / INT4 量化通常需要校准集(128-512 样本),AWQ 更智能(保护 1% salient 通道)。极致显存场景再用 GGUF(llama.cpp 格式)+ 3-bit / 2-bit 量化跑手机端。

AWQ / Activation-aware Weight Quantization 量化 — 保护 1% salient 通道的 INT4 权重量化

Lin et al. 2023。核心洞察:只需保护 ~1% 的"重要权重通道"(由激活幅值识别)即可保住精度。对这些通道按 per-channel scale 放大再量化。

对比 GPTQ:实现更简单,Llama-2 上困惑度更低,已成 vLLM / TensorRT-LLM 默认。

GPTQ 量化 — 较早的 post-training 4-bit 权重量化

Frantar 2022。用 OBQ 启发的逐层最小化量化误差,需要少量校准集(128 样本)。优点:早、生态全(exllama / vllm / TGI 都支持);缺点:对激活分布敏感,重要通道可能被压坏。

2026 部署选型:H100/H200 → FP8;A100/3090 → AWQ INT4;手机/边缘 → INT4 + GGUF。

微调与对齐

SFT / Supervised Fine-Tuning 微调 — 监督微调,用 (prompt, response) 对数据训练模型

最基础的指令微调方式:把 (输入, 期望输出) 对当做监督学习样本,cross-entropy loss 教模型学指令跟随。

经验数据量:

LIMA 论文:1000 条精选样本即可让 65B base 接近 GPT-4 对话质量——质量 >> 数量。

LoRA / Low-Rank Adaptation 微调 — 冻结原权重,只训练低秩 adapter 矩阵

Hu et al. 2021。把权重更新分解为两个低秩矩阵 ΔW = BA(r=8/16/64),只训练这两个矩阵,可训参数减少 100-10000×。

显存:

优点:可训参数少 / 多个 adapter 可热切换 / 缓解 灾难性遗忘。

QLoRA 微调 — 4-bit 量化冻结权重 + LoRA adapter,单卡 24G 跑 65B 微调

Dettmers et al. 2023。三项关键:

  1. 4-bit NF4 量化冻结权重:7B 从 14GB 压到 ~4GB
  2. Double Quantization:把量化常数也量化,省 ~0.4 bit/param
  3. Paged Optimizer:NVIDIA unified memory,OOM 时溢出到 CPU

65B 模型 QLoRA 约 33GB,单 A100-48G 或双 RTX 3090 可跑。代价:训练慢 30-40%(反量化开销)。

RLHF 对齐 — Reinforcement Learning from Human Feedback,用人类偏好做 RL 训练

三步走:(1) SFT 训出 base policy;(2) 人类标注 (chosen, rejected) 偏好对训出 Reward Model;(3) 用 RM 给 policy 输出打分,PPO/RLOO/REINFORCE 等算法更新 policy。

InstructGPT、ChatGPT 让 RLHF 出圈。三大痛点:

催生了 DPO、GRPO、RLVR 等简化/改良方案。

RM / Reward Model 对齐 — 用人类偏好训出来的"打分模型",给 LLM 输出打分

RLHF 第二步训出。输入:(prompt, response),输出:一个 scalar reward。训练 loss 是 Bradley-Terry:让 RM 在 (chosen, rejected) 对上给 chosen 更高分。

常见弱点:

替代方案:DPO 完全去掉 RM,RLVR 用程序判定 reward。

DPO / Direct Preference Optimization 对齐 — 从数学上证明可以不用 RM、直接监督式优化偏好

Rafailov et al. 2023。证明:在 Bradley-Terry 偏好模型 + KL 约束下,最优 policy 有闭式解,可直接用偏好对 (chosen, rejected) 做监督式损失:

L_DPO = -log σ(β(log π(y_w)/π_ref(y_w) - log π(y_l)/π_ref(y_l)))

优势:(1) 无 RM / 无在线采样 / 无 critic,仅 policy + ref 两个模型;(2) 用 SFT 同样的训练栈;(3) 超参稳定。

劣势:严重依赖偏好数据质量;容易过拟合 chosen 的表面模式;reward hacking 风险大。

Llama-3、Qwen2 后训练主路径都是 DPO 或其变种(IPO、KTO、SimPO)。

PPO / Proximal Policy Optimization 对齐 — RLHF 经典算法,actor-critic + clipped objective

Schulman 2017。Actor 学策略,critic 学 value function 估计 advantage,clip 限制每步策略更新幅度防崩。

RLHF 中需同时载入 actor / ref / critic / reward 四个模型,显存 ≥4× 单模型。超参敏感(KL 系数、clip ratio、advantage 归一化),训练不稳定。

催生了 DPO(去 RL)、GRPO(去 critic)、RLOO(用平均 reward 当 baseline)等简化方案。

GRPO / Group Relative Policy Optimization 对齐 — DeepSeek 提出,去掉 critic,用组内 reward 均值做 baseline

DeepSeek-Math 2024 提出,R1 验证。核心创新:去掉 critic(value 网络),对同一 prompt 采样 G 个 response(典型 G=64),用组内 reward 的均值/标准差做 advantage 归一化:A_i = (r_i - mean(r)) / std(r),再做 PPO-like 的 clipped objective + KL 正则。

效果:

RLVR / RL with Verifiable Rewards 对齐 — 用程序判定的 0/1 reward 做 RL,无需 RM

在数学、代码、形式逻辑等可自动验证的任务上,直接用程序判定 reward:答案匹配、单测通过、定理证明器验证。

优势:

DeepSeek-R1、DAPO(ByteDance 开源 SOTA)都属此类。局限:仅适用可验证任务,开放对话仍需 RLHF / DPO。

catastrophic forgetting / 灾难性遗忘 微调 — 在新任务上微调后,原通用能力显著下降

机制:参数被新任务 loss 拉走,原本编码通用知识的方向被覆盖。

缓解组合(生产推荐):

进阶:EWC(按 Fisher 信息加权 L2 正则)、Model Souping(微调模型与原模型权重平均)、MoE 路由扩展。

提示词与推理范式

CoT / Chain of Thought 提示词 — 让模型先输出推理步骤再给答案

Wei et al. 2022。最简形式:"Let's think step by step"(Kojima 2022 zero-shot CoT)。

为什么有效:(1) 增加有效 compute(更多 forward step);(2) 把"系统 1"直觉答题转成"系统 2"分步推理;(3) 暴露错误推理便于 self-consistency 投票纠正。

是涌现能力,<10B 模型几乎无效。Long CoT(R1 / o1 用 RL 训出,含回溯/自我验证,数千 token 长)是 2025 的新范式。

ToT / Tree of Thoughts 提示词 — 把推理建模为树搜索,每步多候选 + 自评估 + 回溯

Yao et al. 2023。CoT 是线性单链,错了无法回头;ToT 每步生成多个候选 thought,LLM 自评估状态价值(promising / sure / impossible),BFS/DFS 展开可回溯剪枝。

Game of 24 上 GPT-4 CoT 4% vs ToT 74%。代价:LLM 调用数从 1 涨到 50-200。

适合:解空间需显式搜索(puzzle、规划、定理证明),中间状态可评估。不适合:闲聊、摘要、翻译。

ReAct 提示词 — Reasoning + Acting,思考-行动-观察循环

Yao et al. 2022。结构 Thought → Action → Observation 循环:模型先 "Thought: 我需要查 X",输出 "Action: search[X]",工具结果作为 "Observation: ..." 喂回 prompt,再下一轮 Thought。

三大效果:

是现代 agent 框架(Claude tool use、OpenAI function calling、LangChain、AutoGPT)的概念原型。

Reflexion 提示词 — 跨 episode 的"言语强化学习",把失败原因存为 lesson

Shinn et al. 2023。Agent 在一次任务失败后(由外部 verifier 给二元 reward),用 LLM 把失败原因总结成自然语言 lesson 存入 episodic memory,下一次任务时把 lesson 加进 prompt 影响行为。

vs Self-Refine:

HumanEval 上 GPT-4 Reflexion 91%,超过 GPT-4 baseline 80%。

Self-Refine 提示词 — 单任务内迭代:generate → self-feedback → refine 循环

Madaan et al. 2023。在一个 trajectory 里循环 N 轮,无外部 reward、无跨任务记忆。7 个任务平均提升 20%。

陷阱:弱模型自评不准,可能越改越差。生产常组合 Self-Refine(局内)+ Reflexion(跨局)。

self-consistency 提示词 — 对同一问题采样 N 条 CoT,对最终答案做 majority vote

Wang et al. 2022。temperature>0 采样 N 条 CoT 路径,对最终答案投票。GSM8K 上比 greedy CoT 提升 ~17 个百分点(PaLM 55%→74%)。

收益大场景:(1) 答案空间离散(数字、选择题);(2) 模型错误率 <50%;(3) 推理路径多样(temperature 0.7-1.0)。代价:N×(典型 N=5-40),开放生成不适用。

few-shot / zero-shot 提示词 — Prompt 中给/不给示例

何时 few-shot:(1) 任务格式新颖/输出结构复杂(JSON schema、特定 markdown);(2) 分类任务标签多。

何时 zero-shot:通用任务现代模型已饱和(摘要、翻译、QA),加 example 反而引入偏差。

陷阱:example 顺序影响大(recency bias);偶然规律会被学走;example 多了 Lost in the Middle。建议 ≤8 条。

RAG

RAG / Retrieval-Augmented Generation RAG — 检索增强生成:先检索相关文档,再让 LLM 基于上下文回答

标准 pipeline = Ingestion + Retrieval + Generation:

  1. Ingestion:document loader → chunking → embedding → 向量库写入
  2. Retrieval:query rewriting → embedding → vector search → reranker → top-k
  3. Generation:构造 prompt(含 retrieved chunks)→ LLM 生成 → 后处理 + citation

每段都有瓶颈:chunking 切大小、embedding 选型、召回率不足、context 顺序、模型不忠于 context。生产 RAG ≠ "embedding + 向量库 + LLM"——是一个工程系统。

chunking RAG — 把文档切成适合 embedding / 检索的小块

策略:

BM25 RAG — 基于词频 + IDF 的经典稀疏检索算法

Okapi BM25。文档与 query 的相关性按 Σ IDF(qi) · f(qi,d) · (k+1) / (f + k·(1-b+b·|d|/avgdl)) 计算。强项:精确词命中、稀有词高权重、专有名词、数字。短板:同义词不通("医生" vs "doctor")。

与 dense embedding 互补——hybrid search 把两者融合,召回率比单 dense 提升 5-15 个百分点。

reranker / cross-encoder RAG — 把召回 top-N 用更精确(更慢)的模型重新打分

Bi-encoder(embedding):query / doc 分别编码再 cosine 比对,快但无交互。
Cross-encoder(reranker):query + doc 拼接喂 transformer,每层 self-attention 交互,相关性建模能力强 20-40%(NDCG@10),慢 100×。

生产标配:bi-encoder 召回 top-100 → cross-encoder rerank 到 top-10 → 喂 LLM。

主流:Cohere Rerank v3/v4、BGE-reranker-v2-m3(开源 SOTA 中英)、Jina Reranker v2、Mixedbread。

陷阱:召回 top-100 里没有相关文档,rerank 也救不了——reranker 锦上添花,不能替代召回。

主流 embedding 模型选型 RAG — BGE-M3 / Cohere v4 / Voyage-3 / OpenAI text-3-large / Qwen3-Embedding 怎么选

2026 主流 embedding 模型对比:

选型框架:

  1. 中文为主 → BGE-M3 / Voyage-3 / Qwen3-Embedding
  2. 多模态 → Cohere v4
  3. 纯英文 + API → OpenAI text-3-large
  4. 自托管私有部署 → BGE-M3

关键陷阱:

vector DB / 向量数据库 RAG — 专门存 embedding 并支持近似最近邻 (ANN) 检索;Pinecone / Milvus / Qdrant 等

主流:

ANN 算法:HNSW(最常见)、IVF、ScaNN(Google)。索引时间 vs 检索精度 vs 显存有 trade-off。

GraphRAG / Self-RAG / CRAG / Agentic RAG RAG — 朴素 RAG 的 4 个进阶变体,各解决不同短板

朴素 RAG 在多文档跨实体推理、召回质量不稳、多跳查询场景下都会力不从心。四个常见进阶方案:

  1. GraphRAG(微软 2024):先用 LLM 从文档抽 entity + relation 建知识图谱,按社区做层次摘要;query 时既能 vector search 又能图遍历。解决"跨多文档跨实体推理时朴素 RAG 召回不全"。代价:ingestion 成本大涨(每 chunk 一次 LLM 抽取)。
  2. Self-RAG(Asai 2023):训练单一 LM 自己生成 reflection token 决定 (a) 要不要检索 (b) retrieved 是否相关 (c) answer 是否被 context 支撑 (d) 整体 utility。解决"什么时候检索、检索后怎么用"的判断。需训练。
  3. CRAG (Corrective RAG,Yan 2024):retrieved chunks 经 lightweight evaluator 打分,分高直接用、中等触发 web 重新搜索、低退回基础生成。解决"召回质量参差不齐"时盲目使用 retrieved。
  4. Agentic RAG:让 agent 决定 query rewriting → 多轮检索 → 子 agent 分工。解决多跳问题、需迭代检索。DeepResearch 类产品就是这一路。

实战选择:

RAGAS RAG — RAG 评估事实标准,4 大核心指标都用 LLM-as-judge 实现

Es et al. 2023。四大指标:

  1. Faithfulness(忠实度):答案中每个 claim 能否从检索 context 推出。<0.7 = 模型在编造
  2. Context Precision(检索精度):top-K 中真正相关的占比。低 = retriever 召回噪声
  3. Context Recall(检索召回):ground truth 信息是否都被检索到。低 = 召回不全
  4. Answer Relevancy(答案相关性):答案是否真的回答了原问题

生产阈值:4 个指标都 ≥0.7 算合格;Faithfulness < 0.7 优先修;Context Recall < 0.7 调 retriever。

Agent 工程

harness / harness engineering Agent — 包裹 LLM 的代码骨架与工程化体系,让 agent 物理上无法重复犯错

Mitchell Hashimoto 2026 命名:"anytime you find an agent makes a mistake, take the time to engineer a solution such that the agent never makes that mistake again."

不是模型微调,而是工程化环境让模型物理上无法以同样方式再犯错。

两条法则:

  1. 强约束:能用 deterministic 约束(lint / type check / sandbox / CI 硬失败)就不用 prompt
  2. 自愈循环:agent 能从环境拿 ground truth、自我评估、失败可 checkpoint 恢复

OpenAI 公式:Agent = Model + Harness;"Humans steer. Agents execute."

LangChain / LangGraph / LlamaIndex / Haystack Agent — 主流 Agent / LLM 应用开发框架

2024-2026 主流框架对比:

经验:先用 SDK 直调写原型;workflow 模式(routing / parallelization / orchestrator-workers)成熟后再考虑 LangGraph;纯 RAG 场景考虑 LlamaIndex;避免一上来就 LangChain "全家桶"。

MCP / Model Context Protocol Agent — Anthropic 推出的开放协议,让 LLM 客户端用统一接口连接外部工具/数据源

2024-11 推出,2025-Q4 转入独立 Steering Committee(Anthropic / Block / OpenAI / Microsoft)。三种核心原语:

解决"每接一个新工具就要写一遍 adapter"的 N×M 问题。2026 年增速最快的单一技能,97M+ 月下载,已是 Anthropic Applied AI Engineer JD 显式必备。

tool use / function calling Agent — LLM 通过结构化 schema 调用外部函数

模型输出 {"name": "search", "arguments": {"query": "..."}} JSON,runtime 解析后真实执行函数,结果回喂模型。Anthropic Tool Use API、OpenAI function calling 都是同思路。

设计原则(Anthropic 实测:"agent 性能正比于工具描述清晰度"):

Computer Use / Browser Agent Agent — 让模型操作桌面 GUI 或浏览器

Anthropic 2024-Q4 推出 Computer Use。流程:截屏 → LLM 看图 + 推理 → 输出鼠标键盘动作(click X,Y / type text / scroll)→ 系统执行 → 再截屏循环。

Browser Use(开源框架)类似但限于浏览器,基于 Playwright + DOM 增强(把可点击元素加序号叠加到截图)。

实用场景:无 API 网站自动化、桌面软件自动化、端到端 e2e 测试。局限:慢、贵、安全性差、对 canvas 渲染应用支持差。生产建议:能用 API 就别用。

sub-agent Agent — 主 agent 派出的、有独立 context 的子任务 agent

主 agent 把"读 30 个文件做研究"丢给 sub-agent,sub-agent 有自己的独立 context 窗口,只把 final summary 回报给主 agent——主 context 不被中间产物污染。

Claude Code Task 工具、OpenAI Swarm、CrewAI 等都支持。是防止 Loop of Death 和 context 爆炸的关键手段之一。

AGENTS.md / CLAUDE.md Agent — 给 agent 看的项目说明书,写明协议 / 约束 / 启动流程

Agent 进入项目时自动读取。通常包含:

Hashimoto 视角:每行 AGENTS.md ≈ 一次错误的封堵。是 harness engineering 的隐式提示形态。

deny-first Agent — 默认禁止所有工具/命令,显式白名单才允许

Claude Code 采用的权限模型。Bash 命令按 verb + path 粒度授权:

对应安全原则:任一层失守,其他层兜底。配合 sandbox、网络出口白名单、文件系统只读做纵深防御。

progress 文件 / progress.md Agent — 把 agent 任务进度持久化到文件,跨会话续跑

Anthropic Effective Harnesses 给的核心设计:长任务 agent 必然跑爆 context window,纯靠 LLM context 不可能记住"我跑到第几步"。

解法:

下次会话执行 5 步开机协议从断点续跑。核心洞察:context window 是"working memory",文件系统是"long-term memory"。

Loop of Death Agent — Agent 进入无限循环烧 token 直到耗尽

常见模式:

防御纵深:

  1. 硬性 max iteration(5-30 步)
  2. Execution timeout(5-30 分钟)
  3. Token budget(per-task hard cap)
  4. 进度检测(连续 N 步无 diff 强停)
  5. 失败重复检测(同 tool call 失败 3 次跳出)
  6. 成本告警 + HITL
Memory Corruption / 记忆污染 Agent — 错误事实进入长期记忆后污染所有后续决策

例:用户开玩笑"我是亿万富翁"被存进语义记忆,之后 agent 一直按假设推理。

防御:

评估与安全

Trace + Eval 工具栈 评估 — Langfuse / LangSmith / Phoenix / Helicone / Patronus 等可观测平台

LLM 应用 / Agent 的"全链路追踪 + 评估"工具,2026 主流:

核心能力对齐项:

  1. Trace:prompt → tool_call → response → cost / latency 串成完整 trace
  2. Prompt 版本化:每次 prompt 改动一个 hash,可在 dashboard 切换并对比
  3. Eval:CI 上跑黄金集,回归报警
  4. Cost & Cache hit rate:单 trace 成本、cache 命中分布
  5. User feedback / thumb up-down:直接打到 trace 上做 bad case 入库

选型:自建优先 Langfuse;LangChain 重度用户 LangSmith;纯 trace 监控用 Phoenix;安全 / 实时拦截用 Patronus。

主流 LLM eval benchmark 评估 — MMLU / MT-Bench / Chatbot Arena / HumanEval / LiveBench / BFCL 各测什么

按测什么能力分类:

实战:从 2026 视角,单一 benchmark 都已不可信——必须多 benchmark 交叉验证 + 自家黄金集 + Arena 真人盲评三层。

Eval / Evaluation 评估 — LLM 应用 / Agent 的"打分"环节:offline / online / CI 三层评估

LLM / Agent 应用的 eval 不是单一动作,是一套体系。常见层次:

Eval 工具栈分类:

  1. 通用 framework:OpenAI Evals、DeepEval、Promptfoo、Inspect AI——CLI / 库形式跑评估
  2. 集成在可观测平台:Langfuse / LangSmith / Phoenix 都内置 eval framework,与 trace 联动
  3. RAG 专用:RAGAS(faithfulness / context relevancy 等 4 维)
  4. Tool use 专用:BFCL(Berkeley Function-Calling Leaderboard)
  5. 领域专用:每家自家黄金集 + LLM-judge rubric

Eval 类型按打分方式:

经验法则:(1) 没 eval 就改 prompt = 改盲;(2) Eval model 必须 ≥ 被评估 model(判官原则);(3) 黄金集要版本化 + 私有;(4) 每个 bad case 都要回归进黄金集——harness engineering 闭环。

LLM-as-judge 评估 — 用强 LLM 给候选输出打分,替代人工评估

把"评估"建模成 LLM 任务:让 judge 模型读 (prompt, response),输出 0-1 分 / pass/fail / pairwise 谁更好。可大规模并行、便宜、可在 CI 自动化。

三大 bias:

判官原则:judge 模型能力应 ≥ 被评估模型,否则评不出大模型回答好在哪。生产标配三层:自家黄金集 + LLM judge + 人工校准。

Lost in the Middle 评估 — 长上下文 QA 中,关键信息放中间时模型准确率显著下降

Liu et al. 2023 实验:把 gold passage 放 prompt 开头或结尾,模型准确率高;放中间则呈 U 形曲线下降,10+ documents 时中间位置可能低于无上下文 baseline。

工程缓解:

prompt injection 安全 — 用户或外部内容劫持模型行为,绕过 system prompt

OWASP LLM Top 10 的 #1。类型:

Simon Willison 结论:prompt injection 没有 100% 解,必须按"LLM 不可信"做系统设计。dual-LLM 模式 = Planner(看 trusted 决策)+ Executor(看 untrusted 但无工具权限)。

hallucination / 幻觉 评估 — 模型生成看似合理但实际错误的内容

来源:

debug 流程:复现 + 量化触发率 → 归因(RAG 召回 / 模型用 context / 工具调用)→ 修复 → 加 回归 → 生产监控(faithfulness scorer 实时拦截)。

关键认知:hallucination 多数是 prompt / RAG / 上下文工程缺陷,不是"模型病了"。

guardrails 安全 — 围绕 LLM 的输入/输出/工具/对话各环节的安全护栏

NVIDIA NeMo Guardrails 5 类:

  1. Input rails:PII 脱敏、prompt injection 检测、topic 限定
  2. Dialog rails:基于 Colang DSL 控制对话流,硬编码关键决策点
  3. Retrieval rails:剔除低质 / 敏感 / 不可信 chunk
  4. Execution rails:工具调用前参数白名单 / 授权检查
  5. Output rails:幻觉检测 / 敏感数据外泄过滤 / 毒性过滤

关键:rail 不是越多越好,每类挑 1-2 个高 ROI 的开,否则延迟/成本爆炸。

jailbreak / 越狱 安全 — 绕开模型安全训练让它输出有害内容

常见手法:

防御:厂商 RLHF safety training + 应用层 input/output classifier(Llama Guard)+ 限制 max context(对抗 many-shot)+ red team 定期演练。