Agent on 方糖猫Blog

本体数据（Ontology Data）核心概念与组成要素：从本体构建到智能体落地的实施路径

Wed, 02 Sep 2026 10:00:00 +0800

本体数据（Ontology Data）核心概念与组成要素：从本体构建到智能体落地的实施路径

过去两年，一个"老词"重新热了起来：本体（Ontology）。

它上一次被大规模讨论还是二十年前语义网（Semantic Web）的年代。这一次把它重新推上舞台中央的，是大模型和智能体（Agent）。原因很朴素：当 AI 从"聊天"走向"办事"，它需要的不再只是文本语料，而是对企业业务的结构化理解——客户是什么、订单是什么、什么状态能退款、哪个字段对应哪个口径。这些东西散落在各个系统的表结构、接口文档和老员工的脑子里，LLM 猜不到，RAG 检索回来的也只是只言片语。

Palantir 把 Ontology 做成了 AIP 的基石并在资本市场讲出了漂亮的故事；微软在 2025 年底 Ignite 大会发布 Fabric IQ、把 Ontology 塞进自家数据平台；中国信通院在 2026 年 7 月发布了《本体智能研究报告（1.0）》。本体，正从学术概念变成智能体落地的"语义底座"。

这篇文章做两件事：

把本体数据的核心概念与组成要素一次梳理清楚；
给出一条从本体构建到智能体落地的、可操作的实施路径，并配上实战事例。

一、什么是本体数据：概念演化与边界

1.1 从哲学到工程：本体的四次演化

“本体"这个词的履历相当丰富，理解它的演化路径，有助于我们明白今天工程语境下它到底指什么：

timeline
    title 本体概念的演化路径
    古希腊~近代哲学 : 哲学本体论（Ontology）
                      : 研究"存在"本身——世界由什么构成
    1990s 人工智能 : 形式化本体
                   : Gruber 定义——"对概念化的显式规范"
                   : 让机器能共享和复用领域知识
    2000s 语义网 : OWL / RDF / SPARQL 标准体系
                 : W3C 语义网技术栈成型
                 : 本体语言具备形式化推理能力
    2012~ 知识图谱 : Google Knowledge Graph 引爆
                   : 本体作为图谱的 Schema 层
                   : 大规模实例数据 + 图存储
    2024~ 本体智能 : 大模型 + Agent 时代
                   : 本体成为智能体的语义基座
                   : 从"查询与推理"走向"决策与行动"

工程界最常被引用的定义来自 Tom Gruber（1993）：“本体是对概念化的显式规范”（An ontology is an explicit specification of a conceptualization）。翻译成大白话：把一群人脑子里对某个业务领域的共识，用机器可读的、形式化的方式写下来——有哪些概念、概念之间什么关系、遵守什么规则。

中国信通院在《本体智能研究报告（1.0）》中追溯了"哲学本体论 → 形式化本体 → 知识图谱 → 本体智能"的完整脉络，并将本体智能界定为：以形式化本体为语义基座，融合语义推理与知识计算，实现信息系统深层理解、逻辑推理与自动化执行的新范式（详见安全内参报道）。这个"从理解到执行"的落脚点变化，正是本轮本体复兴与二十年前语义网运动的本质区别。

1.2 本体 vs 知识图谱 vs 语义层 vs 数据模型

这几个概念经常被混用，但它们的职责边界其实很清晰：

概念	回答的问题	类比	典型载体
数据模型（Schema）	数据怎么存	仓库的货架设计图	ER 图、DDL、数据表
语义层（Semantic Layer）	指标和业务术语怎么算、怎么叫	全公司统一的度量衡手册	指标平台、Cube、dbt metrics
本体（Ontology）	业务世界里有什么、什么关系、什么规则	业务的"词典 + 语法书 + 法规汇编”	OWL、RDF Schema、Palantir Ontology
知识图谱（Knowledge Graph）	具体的人和事是什么样	装满货物、贴了统一标签的仓库	Neo4j、图数据库中的实例数据

用 Jessica Talisman 的一句广为流传的话概括："语义层用于查找，本体用于上下文和推理。"（参考OceanBase 团队的对比分析）

一个直观的例子：你问"上个月哪个渠道贡献了最高 GMV"，语义层能给你一个口径统一的精确数字；但你接着问"为什么这个渠道掉了、该不该追加预算"，语义层就哑火了——它不知道"渠道"和"预算策略"、“市场活动”、“竞品动作"之间的关系与规则。而这正是本体的领地。

再说本体和知识图谱的关系，一句话：本体是知识图谱的 Schema，知识图谱是本体的实例化。 就像面向对象里"类"与"对象"的关系——本体定义了"设备"“工单"这些类以及它们的属性和关系，知识图谱里则躺着三万条具体的设备记录和十万条工单。

1.3 为什么 Agent 时代需要本体

不妨先看一个真实行业中反复上演的窘境（OceanBase DataPilot 团队观察）：同一个"收入"指标，财务说是 1020 万，市场说是 1040 万，Slack 里的 AI 助手说是 980 万。三个数字，没有共识。

以前这是人的问题，开个十分钟的会就能对齐。但Agent 不会发消息问同事"这个指标怎么算”。当它面对一个叫 rev_ttm_adj_v2 的列名时，要么编造答案，要么随手捡起它找到的第一个定义。行业实践证明，把建模过的领域知识注入检索路径，幻觉率可以降低约 40%——前提是这些知识确实被结构化地沉淀下来了。

大模型时代本体的价值，可以归纳为三点：

对齐语义：给 LLM 一份"业务词典”，消除同名异义、异名同义，让 Agent 说"行话"；
约束行为：用公理和规则圈出 Agent 能做什么、不能做什么（什么订单能退款、谁能审批），把"幻觉"关进笼子；
支撑推理与行动：让 Agent 不只检索片段文本，而是沿关系推理（设备→部件→供应商→库存），最终落到可执行的动作（创建工单、锁定库存）。

二、本体数据的核心组成要素

2.1 六大基本要素

一个完整的本体，通常由以下要素组成。这里用制造业"设备运维"域来举例说明：

要素	英文	含义	设备运维域的例子
类 / 概念	Class / Concept	领域内事物的类型，可继承	`设备`，其子类：`泵`、`电机`、`压缩机`
实例 / 个体	Instance / Individual	类的具体对象	“3 号车间的 P-102 号离心泵”
属性	Property	实例的特征（数据属性）或实例间的关系（对象属性）	数据属性：`额定功率=75kW`；对象属性：`P-102 安装在 3号车间`
关系	Relation	类与类之间的语义关联	`设备包含部件`、`工单处理故障`
公理 / 约束	Axiom / Constraint	永远为真的规则，用于推理和校验	“额定功率 > 100kW 的设备必须每季度点检”
动作 / 函数	Action / Function	本体驱动的可执行操作（Palantir 风格的本体扩展）	`创建维修工单(设备, 故障类型)`

classDiagram
    class 设备 {
        +设备编号: string
        +额定功率: float
        +投运日期: date
    }
    class 泵
    class 电机
    class 部件 {
        +部件编号: string
        +材质: string
    }
    class 故障 {
        +故障码: string
        +发生时间: datetime
        +严重等级: int
    }
    class 维修工单 {
        +工单号: string
        +状态: enum
    }
    class 供应商 {
        +名称: string
        +备件库存: int
    }

    设备 <|-- 泵 : 继承(is-a)
    设备 <|-- 电机 : 继承(is-a)
    设备 "1" *-- "多" 部件 : 包含(has-part)
    设备 "1" --> "多" 故障 : 发生(has-fault)
    故障 "1" --> "0..1" 维修工单 : 触发(triggers)
    部件 "多" --> "1" 供应商 : 采购自(supplied-by)

    note for 设备 "公理：额定功率>100kW ⇒ 强制季度点检\n动作：创建维修工单(设备, 故障)"

2.2 属性的两种类型与语义三元组

在传统本体语言（RDF/OWL）里，所有知识最终都会落到**三元组（Triple）**上：(主语, 谓语, 宾语)。谓语分两类：

数据属性（Data Property）：宾语是字面量，如 (P-102, 额定功率, 75)；
对象属性（Object Property）：宾语是另一个实例，如 (P-102, 位于, 三号车间)——这是"图"的边。

对象属性还可以带语义特征，这些特征是自动推理的燃料：

属性特征	含义	例子
传递性（Transitive）	A→B 且 B→C 则 A→C	`部件属于部件`：轴承属于转子，转子属于泵 ⇒ 轴承属于泵
对称性（Symmetric）	A→B 则 B→A	`与……同轴安装`
互逆性（Inverse）	A→B 等价于 B→A⁻¹	`包含部件` 与 `属于设备` 互逆
函数性（Functional）	一个主语最多一个宾语	`设备拥有唯一资产编号`

2.3 用 OWL/Turtle 写一个最小本体

让概念落地，下面是一段真实可用的 Turtle 语法（OWL 的文本序列化格式），描述上面设备域的一个切片：

@prefix : <http://example.com/factory#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

# 类与继承
:设备   a owl:Class .
:泵     a owl:Class ; owl:subClassOf :设备 .
:部件   a owl:Class .
:故障   a owl:Class .

# 对象属性（带传递性）
:包含部件  a owl:ObjectProperty , owl:TransitiveProperty ;
           owl:domain :设备 ; owl:range :部件 .
:发生故障  a owl:ObjectProperty ;
           owl:domain :设备 ; owl:range :故障 .

# 数据属性（带函数性约束）
:额定功率  a owl:DatatypeProperty , owl:FunctionalProperty ;
           owl:domain :设备 ; owl:range xsd:float .

# 实例
:P-102  a :泵 ;
        :额定功率 75.0 ;
        :包含部件 :P-102-转子 ;
        :发生故障 :F-2026-0817 .

有了这段形式化描述，推理机（Reasoner）就能自动回答：“P-102 属于设备吗？"（是，因为 泵 是 设备 的子类）、“它有哪些部件？"（沿传递关系展开）——这些答案不是你写进去的，是推出来的。这正是本体区别于普通数据库视图的硬核能力。

2.4 工程扩展：从"静态知识"到"可行动的本体”

传统本体止步于"描述世界”。而 Palantir 开创并影响了整个行业的工程实践是：把动作（Action）、权限（Security）、业务逻辑（Function）也装进本体。于是本体不再只是"业务的词典"，还是"业务的操作界面"：

Agent 查"哪些设备高风险"——沿本体关系和公理推理；
Agent 决定"该停机检修"——调用本体上注册的 创建维修工单 Action；
谁能调用这个 Action、能操作哪些车间的数据——由本体层统一做行级/列级权限控制。

这就是"本体是智能体的语义底座"这句话的完整含义：知识、规则、行动、权限，四位一体。

三、本体构建方法论

3.1 三种构建路线

路线	做法	优点	缺点	适用场景
自顶向下	先由领域专家定义概念体系，再填充实例	体系严谨、语义一致	周期长、依赖稀缺专家	强监管、高严谨场景（医疗、金融合规）
自底向上	从现有数据（表结构、文档）抽取概念，归纳出本体	起步快、贴地气	容易变成"表结构的镜像"，缺乏业务抽象	数据基础好、快速验证场景
混合式（推荐）	专家定骨架 + LLM 辅助从数据/文档中抽取血肉	兼顾质量与效率	需要人机协同流程设计	绝大多数企业落地场景

值得强调的是 LLM 给本体构建带来的范式变化：过去本体工程最大的瓶颈是人工成本（专家访谈、概念梳理动辄数月），现在可以让 LLM 从制度文档、接口文档、表注释里抽取候选概念和关系，专家只做审核和裁决。信通院报告也指出，当前本体工程化最成熟的起点仍是结构化数据；面对文本、表格等非结构化信息，可以结合大模型完成语义抽取与对齐后，再进入统一的本体语义体系（参考与非网对本体产业的解读）。

3.2 Stanford 七步法：经典构建流程

本体工程领域最经典的方法论是斯坦福大学提出的"七步法"（Ontology Development 101）。结合 LLM 辅助，完整的构建流程如下：

flowchart TD
    A[1. 确定范围与目的<br/>本体服务哪个业务域？回答什么问题？] --> B[2. 调研复用<br/>是否有现成上位本体/行业标准可继承？]
    B --> C[3. 枚举核心术语<br/>领域专家 + LLM 从文档/表结构抽取候选概念]
    C --> D[4. 定义类与层级<br/>确定 is-a 继承树，区分上位/下位概念]
    D --> E[5. 定义属性与关系<br/>数据属性、对象属性、属性特征]
    E --> F[6. 定义约束与公理<br/>基数约束、值域约束、业务规则]
    F --> G[7. 填充实例并验证<br/>推理机一致性检查 + 胜任问题测试]
    G -->|发现缺口/冲突| C
    G --> H[发布上线，进入版本化治理]

两个容易被忽视但极其关键的环节：

胜任问题（Competency Questions）：在建模之前，先写下"这个本体必须能回答的 20 个问题"（如"某供应商断供时，影响哪些在产设备？"）。它是本体范围的验收标准，能有效防止建模发散。
复用优于自建：医疗有 SNOMED CT、金融有 FIBO、通用领域有 Schema.org。直接继承成熟上位本体，比从零造轮子靠谱得多。

3.3 工具链速览

层级	开源工具	商业产品
本体建模	Protégé、TopBraid Composer（社区版）	Palantir Foundry Ontology、PoolParty
存储与查询	Apache Jena（RDF/SPARQL）、Neo4j（属性图/Cypher）、RDFLib	Stardog、GraphDB、Amazon Neptune
推理机	HermiT、Pellet、Openllet	Stardog 推理引擎
LLM 抽取/对齐	LangChain + Pydantic 结构化抽取、GraphRAG 管道	Palantir AIP、微软 Fabric IQ
Agent 接入	MCP Server 自研、LangGraph 工具封装	Palantir AIP Logic、Salesforce Agentforce

四、实施路径：从本体构建到智能体落地

这是本文的重点。把前面所有概念串成一条可执行的路径，共六个阶段：

flowchart LR
    subgraph 一["阶段一：业务域盘点（1~2 周）"]
        A1[选定高价值场景] --> A2[盘点数据源与利益方] --> A3[写下胜任问题清单]
    end
    subgraph 二["阶段二：本体建模（2~4 周）"]
        B1[专家定概念骨架] --> B2[LLM 辅助抽取候选概念/关系] --> B3[定义公理与动作]
    end
    subgraph 三["阶段三：数据映射与实例化（2~4 周）"]
        C1[表/接口 → 本体映射] --> C2[ETL 实例化] --> C3[质量校验与消歧]
    end
    subgraph 四["阶段四：语义服务化（1~2 周）"]
        D1[封装查询 API/SPARQL/Cypher] --> D2[封装 Action 接口] --> D3[权限与审计]
    end
    subgraph 五["阶段五：Agent 接入（2~3 周）"]
        E1[工具注册 / MCP Server] --> E2[Prompt 注入领域语义] --> E3[编排推理与行动链]
    end
    subgraph 六["阶段六：评估与治理迭代（持续）"]
        F1[胜任问题回归测试] --> F2[幻觉率/准确率评估] --> F3[本体版本演进]
    end
    一 --> 二 --> 三 --> 四 --> 五 --> 六
    六 -.反馈.-> 二

4.1 阶段一：业务域盘点——别上来就建模

最常见的失败模式是：IT 团队热血沸腾地建了一个覆盖全公司的"企业级本体"，半年后无人问津。正确的姿势是场景驱动：

选一个痛且高频的场景：比如"设备故障诊断与维修调度"——每天发生、跨系统（MES + ERP + 库存）、出错代价高；
盘点数据源：这个场景涉及哪些系统的哪些表、哪些文档（SOP、维修手册）；
写胜任问题清单：和业务方一起写下 Agent 必须能回答/执行的事，作为本体的验收标准。

感悟：本体不是数据架构的目标，而是业务问题的副产品。 没有胜任问题清单的本体项目，九成活不过一年。

4.2 阶段二：本体建模——人机协同

领域专家定义概念骨架（设备、部件、故障、工单、供应商五大类及继承关系）；
LLM 从维修手册、点检 SOP、表注释中抽取候选属性与关系，专家审核入库；
定义公理（“功率>100kW 必须季度点检”）和动作（创建工单、锁定备件）。

反模式提醒：不要照搬数据库表结构。表是"怎么存"，本体是"怎么理解"。比如 ERP 里 MATERIAL、BOM_ITEM、SPARE_PART 三张表，在本体里可能统一为部件一个概念加几个关系——本体建模的过程，本身就是一次业务概念对齐。

4.3 阶段三：数据映射与实例化

把存量数据灌进图谱，技术上是 ETL，难点在实体消歧与对齐：

同一个供应商，ERP 里叫"上海精工机电有限公司"，MES 里叫"精工机电"——需要基于规则 + LLM 的实体对齐；
保留溯源信息：每个实例记录它来自哪个系统的哪条记录，这是后续可信审计的根基。

4.4 阶段四：语义服务化

本体不能直接丢给 Agent 裸查，要封装成稳定的语义服务：

flowchart TD
    subgraph 语义服务层
        Q[查询服务<br/>SPARQL / Cypher / REST] 
        Act[动作服务<br/>创建工单 / 锁库存 / 派工]
        S[权限与审计<br/>行级权限 + 操作留痕]
    end
    KG[(知识图谱<br/>Neo4j / RDF Store)]
    ERP[(ERP)] 
    MES[(MES)]
    WMS[(库存系统)]
    
    ERP -->|ETL 映射| KG
    MES -->|ETL 映射| KG
    WMS -->|ETL 映射| KG
    KG --> Q
    Q --> Act
    Act -->|回写| MES
    S -.管控.-> Q
    S -.管控.-> Act

这一层的意义：Agent 永远通过受控接口访问世界，而不是直接操作数据库。权限收敛在一处，审计留痕在一处。

4.5 阶段五：Agent 接入

当前主流有两种接入方式：

工具封装：把语义服务包成 Agent 框架的 Tool（LangChain/LangGraph/AgentScope 都支持），在工具描述里写清楚本体语义；
MCP（Model Context Protocol）：把语义服务做成 MCP Server，让任何兼容 Agent 即插即用——这是 2025 年后快速成为事实标准的路线。

一次典型的 Agent 调用时序如下：

sequenceDiagram
    participant U as 值班工程师
    participant AG as 运维 Agent (LLM)
    participant MCP as 本体 MCP Server
    participant KG as 知识图谱
    participant MES as MES 系统

    U->>AG: P-102 振动超标，怎么办？
    AG->>MCP: query(设备 P-102 的档案/历史故障/部件清单)
    MCP->>KG: Cypher 查询
    KG-->>MCP: 设备档案 + 3 次历史故障(均为轴承磨损) + 部件: 转子/轴承
    MCP-->>AG: 结构化结果
    AG->>MCP: query(轴承备件库存与供应商)
    MCP->>KG: 沿 部件→供应商 关系查询
    KG-->>MCP: 库存 2 件, 供应商交期 3 天
    MCP-->>AG: 结构化结果
    Note over AG: 推理：大概率轴承磨损<br/>备件充足，建议立即更换
    AG->>MCP: action: 创建维修工单(P-102, 更换轴承)
    MCP->>MES: 回写工单（含权限校验+审计）
    MES-->>MCP: 工单 WO-2026-3312
    MCP-->>AG: 成功
    AG-->>U: 建议立即停机更换轴承（备件在库），已创建工单 WO-2026-3312，依据：近半年 3 次同型故障…

注意最后一轮回复的形态：结论 + 已执行动作 + 推理依据。这就是本体给 Agent 带来的质变——它不再"复述检索到的文档片段"，而是在一个结构化的业务世界里推理和行动，并且每一步都有据可查。

4.6 阶段六：评估与治理迭代

回归测试：每次本体变更后，用胜任问题清单跑回归——这 20 个问题还能答对吗？
效果评估：幻觉率、答案准确率、Action 执行成功率，对比接入本体前后的基线；
版本治理：本体是活资产，业务变了本体就要演进。建立变更评审机制，防止"语义漂移"。

4.7 三个落地案例速览

行业	本体核心概念	Agent 能力	价值点
制造业	设备、部件、故障、工单、供应商	故障诊断 + 自动派单	平均故障响应时间从小时级降到分钟级
金融	客户、账户、交易、产品、监管规则	合规审查 Agent：沿"账户→交易→规则"推理风险敞口	审查口径统一，漏报率下降
医疗	疾病、症状、药品、检查、禁忌（复用 SNOMED CT）	辅助诊断 Agent：校验用药禁忌与检查互斥	用公理兜底 LLM 的危险建议

五、2026 年行业最新动态

本体赛道在过去一年明显升温，几条值得关注的线索：

Palantir：Ontology 成为 AIP 的灵魂。Palantir 把 Ontology 从数据建模层升级为"企业操作系统"的概念核心——知识、动作、安全三合一，Agent 在 Ontology 之上编排业务操作。2026 年 4 月，Palantir 将 AIP Agent Studio 更名为 AIP Chatbot Studio，进一步明确对话式 Agent 产品定位；AIP Analyst 也于 2026 年 4 月 GA，支持对话式查询 Ontology 数据、生成可视化并执行动作（参考Palantir 发布解读与 Towards AI 深度解析）。美国陆军 TITAN、Maven 等大额合同持续验证这套打法（Kalkine 分析）。
微软：Fabric IQ 把 Ontology 搬进数据平台。Fabric IQ 于 2025 年 11 月 Ignite 大会发布、2026 年 6 月 Build 大会正式 GA，通过 Ontology 和 Power BI 语义模型把 OneLake 中的数据提升为"业务级语义"，与 Work IQ、Foundry IQ、Web IQ 共同构成微软的企业语义智能层（参考语义工程系列分析）。数据平台厂商集体下场做本体，是本轮最重要的信号。
中国信通院发布《本体智能研究报告（1.0）》（2026 年 7 月，智能原生大会）：首次系统界定"本体智能"内涵，梳理从哲学本体论到本体智能的演化脉络，提出以形式化本体为智能体可信语义底座的产业范式（安全内参、墨天轮）。
语义层与知识图谱全面复兴。腾讯云的行业观察指出，2026 年 AI 模型对"正确数据"的需求推动语义层和知识图谱崛起，SAP、Salesforce 等应用巨头纷纷把语义层作为 Agent 战略的前置投入（腾讯云开发者社区）。企业智能问数也已分化出 RAG 召回、NL2SQL、指标平台增强、本体语义四大技术路线（路线对比分析）。
GraphRAG 成为本体价值的最快验证点。微软开源的 GraphRAG 路线（从文档抽取实体关系构建图谱，再做社区摘要与图增强检索）让"结构化知识增强生成"从理念变成 pip install 级的实践，很多企业正是从 GraphRAG 尝到甜头后，才开始认真考虑更完整的本体工程。

一句话总结行业共识：大模型的军备竞赛告一段落，竞争的下半场是"语义基建"——谁家的 Agent 更懂业务，谁就赢。

六、思考与感悟

写完这条路径，分享几点踩坑后的真实感受：

1. 本体的价值不在"建"，在"对齐"。 本体建模最有产出的时刻，往往不是画类图的时候，而是业务、数据、IT 三方为了"‘客户’到底包不包括潜在客户"吵一下午的时候。那个争吵的过程，就是组织知识显式化的过程。建出来的图谱可能三年就换代了，但吵出来的共识会留在组织里。

2. 谨防"本体过度工程"。 见过太多团队一上来追求形式化完美——全套 OWL 公理、严密的上位本体继承——结果六个月没见到一个能跑的 Agent。务实的顺序是：先让 Agent 用上粗糙的本体跑起来，再在使用中打磨语义。胜任问题答得对，比逻辑上自洽重要。

3. 本体是 Agent 的"宪法"，不是"百科全书"。 不要指望本体装下所有知识——非结构化的经验、文档、案例，交给 RAG；本体负责的是不容含糊的那部分：核心概念、口径、规则、权限边界。一个好的心智模型是：RAG 给 Agent “见识”，本体给 Agent “常识与纪律”。

4. 行动能力（Action）是这轮本体复兴的灵魂。 二十年前的语义网止步于"让机器理解数据"，失败了；今天的本体因为绑定了 Agent 的行动闭环而重生。如果你的本体里没有定义任何 Action，那它大概率只是一张漂亮但寂寞的图。

5. 对个体工程师的启示。 本体工程是少有的"越老越吃香"的 AI 技能——模型会迭代，框架会更替，但对一个行业业务概念体系的深刻理解，沉淀的是复利。选一个你熟悉的垂直领域，亲手建一个小本体、接一个 Agent 跑通闭环，是 2026 年性价比极高的技术投资。

参考资料

中国信通院《本体智能研究报告（1.0）》发布解读 - 安全内参
本体论 vs. 语义层 - OceanBase/Hubwiz
本体产业深度解读：语义层重构智能体数据底座 - 与非网
AI 数据新纪元：语义层与知识图谱的崛起 - 腾讯云
微软语义层：从 Schema 到本体的演进 - CSDN 语义工程系列
Inside Palantir AIP: How the Platform Actually Works - Towards AI
本体工程：从知识图谱到企业智能体的语义基石 - jimo.studio
Noy & McGuinness, Ontology Development 101: A Guide to Creating Your First Ontology, Stanford University

Agent-Chat：基于 AgentScope 2.0 + Mem0 的多 Agent 群聊陪伴系统

Tue, 04 Aug 2026 12:00:00 +0800

Agent-Chat：基于 AgentScope 2.0 + Mem0 的多 Agent 群聊陪伴系统

开源地址：https://gitee.com/soulnew/agent-chat

你有没有想过，把一群性格各异的 AI 拉进同一个微信群，他们会怎么聊天？

不是那种一问一答的客服机器人，而是会主动接梗、会吃醋、会安慰人、会记住你上周说过喜欢喝燕麦拿铁的“AI 朋友”。我开发的Agent-Chat 就是想做这件事：一个支持多角色、多记忆、可配置人格的群聊多 Agent 陪伴系统。

下图是一个实际运行中的群聊界面：用户 @王姐 让她描述下自己，王姐和海公公两个 Agent 基于长期记忆给出了个性化的用户画像回应。

一、为什么需要这个工具？

1.1 单 Agent 聊天 vs. 多 Agent 群聊

维度	单 Agent 聊天（如 ChatGPT 网页版）	多 Agent 群聊（Agent-Chat）
交互形态	1 对 1 问答	1 个用户 + N 个 Agent 同时在线
角色多样性	只有一个固定角色	可配置多个性格、职业、说话风格各异的角色
社交氛围	像咨询顾问	像朋友群，Agent 之间会互动、接话、调侃
记忆隔离	全局统一记忆	支持“Agent 对用户的私有记忆”+“公共记忆”
发言调度	用户问一句答一句	Agent 自主决定是否发言、@谁、说什么

单 Agent 适合办事，多 Agent 适合陪伴。当你只是想找人闲聊、吐槽、或者看几个“朋友”互相斗嘴时，一个群比私聊更自然。

1.2 直接用 LLM API vs. 用 Agent-Chat

很多开发者可能会想：我直接调 DeepSeek API，自己写个循环不就行了？理论上可以，但落到工程上会碰到一堆问题：

问题	自己调 API	Agent-Chat 的做法
多 Agent 并发管理	自己维护 N 个对话上下文，容易串台	AgentScope 2.0 统一运行时 + Redis 短期记忆
谁该说话	每次用户发言都让所有 Agent 回复，刷屏严重	`Orchestrator` 调度器：置信度排序、并发上限、冷却时间、@触发
长期记忆	自己拼 prompt，历史越长越贵	Mem0 自动事实提取、去重、语义检索
记忆隔离	所有 Agent 共享同一份历史	按 `user_id` + `agent_id` 分层作用域
人格配置	写死 prompt	运营后台可配置 Agent 人格、版本、关系、禁忌话题
实时通信	自己搭 WebSocket	FastAPI 原生 WebSocket + 简单 Web UI

Agent-Chat 并不是为了替代 ChatGPT，而是把“多 Agent 群聊”这个场景的工程骨架搭好，让你能专注在角色设计、记忆策略和交互体验上。

1.3 现有群聊机器人 vs. Agent-Chat

市面上也有不少群聊机器人，但大多数是：

规则触发：关键字回复，缺乏上下文理解；
单轮回复：不会主动参与话题；
无记忆：每次重启都是陌生人；
人格单一：无法运营多个差异化角色。

Agent-Chat 的核心差异是：把每个 Agent 当成有记忆、有情绪、有关系的虚拟人，而不是一个只会响应命令的工具。

二、技术栈

层级	选型	说明
后端框架	FastAPI	高性能异步 Web 框架，原生支持 WebSocket
多 Agent 框架	AgentScope 2.0	支持 Agent 生命周期、消息总线、工具调用、ReAct、Middleware
主力 LLM	DeepSeek	OpenAI 兼容接口，通过 `DeepSeekChatModel` 统一调用
长期记忆	Mem0 (self-hosted)	自动事实提取、去重、合并，支持按用户/Agent 作用域隔离
向量数据库	Qdrant	Mem0 推荐的向量后端，轻量高性能
嵌入模型	BGE 系列（BGE-small-zh-v1.5 / BGE-M3 可配置）	本地加载，中文语义召回效果好
短期记忆	Redis	房间消息滑动窗口、会话摘要、在线状态
关系数据	MySQL 8.0+	用户、Agent、房间、消息、关系、事件
前端	简单 Web UI (HTML + JS)	第一阶段提供基础群聊界面
部署	Docker Compose	MySQL + Redis + Qdrant 一键拉起

注：项目中默认使用 BGE-small-zh-v1.5（512 维），但架构上模型路径与维度均可通过环境变量配置，可平滑替换为 BGE-M3 等更强的多语言嵌入模型。

三、系统架构

graph TB
    subgraph Client["客户端"]
        UI["简单 Web UI<br/>HTML + WebSocket"]
    end

    subgraph Backend["后端服务"]
        FastAPI["FastAPI Chat Service<br/>REST API + WebSocket"]
        RoomManager["RoomManager / RoomRuntime"]
        Orchestrator["Orchestrator 调度器"]
    end

    subgraph AgentRuntime["AgentScope 2.0 运行时"]
        AgentInstance["AgentInstance<br/>每个房间每个 Agent 一个实例"]
        Agent["agentscope.agent.Agent"]
        Toolkit["Toolkit + FunctionTool<br/>时间 / 天气 / 搜索 / 抓取"]
        Middleware["GroupChatMem0Middleware<br/>per-user 记忆读写"]
    end

    subgraph Memory["记忆层"]
        Redis[(Redis<br/>短期记忆 / 会话摘要 / 在线状态)]
        Mem0[Mem0 AsyncMemory<br/>长期记忆 / 事实提取 / 语义检索]
        Qdrant[(Qdrant<br/>向量存储)]
        BGE["BGE Embedding<br/>bge-small-zh-v1.5 / BGE-M3"]
    end

    subgraph Data["关系数据"]
        MySQL[(MySQL 8.0<br/>users / agents / rooms / messages / relationships / events)]
    end

    subgraph LLM["大模型"]
        DeepSeek["DeepSeek Chat API<br/>OpenAI 兼容"]
    end

    UI -->|WebSocket / HTTP| FastAPI
    FastAPI --> RoomManager
    RoomManager --> Orchestrator
    RoomManager --> AgentInstance
    AgentInstance --> Agent
    Agent --> Toolkit
    Agent --> Middleware
    Middleware --> Mem0
    Mem0 --> Qdrant
    Mem0 --> BGE
    Agent --> DeepSeek
    RoomManager --> Redis
    FastAPI --> MySQL
    Mem0 --> DeepSeek

四、核心设计

4.1 Agent 生命周期

Agent 不是临时对象，而是运营预先配置的“角色模板”。一个 Agent 可以被添加到多个房间，在每个房间内有独立的运行实例和记忆空间。

flowchart LR
    A[运营后台创建 Agent] --> B[写入 agents 表]
    B --> C[生成 persona_summary<br/>可选 DeepSeek 质量检查]
    C --> D[Agent 状态 active]
    D --> E[将 Agent 加入房间]
    E --> F[RoomRuntime 实例化 AgentInstance]
    F --> G[注册到 MsgHub]
    G --> H[参与群聊]
    H --> I[用户退出或移除 Agent]
    I --> J[保留历史与记忆]

每个 Agent 可配置：昵称、年龄、职业、性格标签、兴趣、说话风格、语气、回复概率、最大回复长度、禁忌话题等。

Agent 人格的核心是 system_prompt，但为了让模型稳定地“扮演”一个角色，系统会把这些字段组合成一段结构化的基础人设：

你是 {name}，{age} 岁，职业是 {job}。性格：{traits}。说话风格：{speaking_style}。语气：{voice_tone}。

{system_prompt}

重要规则：
- 你只输出你要说的话，不要加自己的名字前缀。
- 保持自然、像真人一样，不要太长（不超过 {max_reply_length} 字）。
- 你是 AI，不是真人。不要诱导用户泄露隐私或进行危险行为。

为了让同一 Agent 能在不同房间里保持一致的“人格”，但又能感知到不同的房间成员和关系，系统把 prompt 拆成两部分：

静态人设（_base_system_prompt）：在 AgentInstance 初始化时构建，只与 Agent 自身属性有关；
动态上下文（_full_system_prompt）：每次生成回复前拼接，包含当前房间名、成员列表、关系、用户画像、近期摘要、检索记忆等。

这种“静态人格 + 动态上下文”的分离，让人格稳定、上下文新鲜，也便于缓存和版本管理。

4.2 记忆分层

记忆是陪伴系统的灵魂。Agent-Chat 把记忆分成三层：

类型	范围	存储	更新频率	用途
瞬时记忆	当前请求	Prompt 上下文	每次请求	保证即时上下文连贯
短期记忆	当前会话	Redis	实时	维护会话历史窗口与摘要
长期记忆	跨会话	Mem0 + Qdrant	实时/异步	用户画像、关系、事件、偏好

flowchart TB
    subgraph Instant["瞬时记忆"]
        P[Prompt 注入:<br/>当前消息 + 近期历史 + 检索记忆]
    end

    subgraph ShortTerm["短期记忆 Redis"]
        R1["room:{room_id}:messages"]
        R2["room:{room_id}:summary"]
    end

    subgraph LongTerm["长期记忆 Mem0 + Qdrant"]
        M1["Agent ↔ 用户 私有记忆"]
        M2["用户公共记忆"]
        M3["Agent 公共记忆"]
        M4["全局公共记忆"]
    end

    User[用户发言] --> FastAPI
    FastAPI --> R1
    FastAPI -->|异步| M2
    FastAPI -->|达到阈值| R2
    R1 --> P
    R2 --> P
    M1 --> P
    M2 --> P
    M3 --> P
    M4 --> P
    P --> DeepSeek[DeepSeek 生成回复]

4.2.1 短期记忆：Redis 滑动窗口 + 增量摘要

短期记忆负责“当前这次聊天不冷场”。实现上，每个房间在 Redis 中有两个 key：

room:{room_id}:messages  ->  List<Message JSON>
room:{room_id}:summary   ->  String<Summary JSON>

messages 保存最近 N 条消息（默认约 30 条）；
超过窗口后，对早期消息做增量摘要，生成 session_summary；
请求 LLM 时，prompt 中注入：会话摘要 + 最近 K 条完整消息 + 当前用户消息。

摘要策略：每新增 10 条消息触发一次增量摘要，由 DeepSeek 生成，保留关键事实、用户情绪、未决话题。摘要本身也作为长期记忆写入 Mem0。

4.2.2 长期记忆：Mem0 + Qdrant + BGE

长期记忆解决“跨会话还记得你”的问题。我们选用 Mem0 作为记忆层，原因有三：

专为 LLM/Agent 设计：自动完成事实提取、去重、合并，不用自己写召回逻辑；
支持 user_id 与 agent_id 双重作用域：天然适合“每个 Agent 对用户有独立记忆”的群聊场景；
可 self-hosted：向量后端用 Qdrant，数据自主可控。

Mem0 的记忆作用域设计非常关键：

user_id	agent_id	含义
有	有	该 Agent 对该用户的私有记忆
有	无	用户的公共记忆，所有 Agent 可读
无	有	该 Agent 的公共记忆
无	无	全局公共记忆（房间摘要、事件）

这意味着：所有 Agent 都知道“用户喜欢猫”，但只有 Agent A 记得“用户昨天跟 Agent A 吐槽了老板”。Agent B 可以假装不知道，让 Agent A 去安慰用户，更像真人社交。

4.2.3 长期记忆写入流程

每次群聊产生一条真实消息后，由 Memory Service 统一写入 Mem0，写入是异步的，不阻塞消息返回。

flowchart LR
    A[用户/Agent 发言] --> B[保存到 MySQL messages]
    B --> C[写入 Redis 短期记忆]
    C --> D{发送者类型}
    D -->|user| E[user_id=用户ID<br/>agent_id=None<br/>公共记忆]
    D -->|agent 回复用户| F[user_id=用户ID<br/>agent_id=AgentID<br/>私有记忆]
    D -->|agent 主动发言| G[user_id=None<br/>agent_id=AgentID<br/>Agent 公共记忆]
    D -->|系统摘要| H[user_id=None<br/>agent_id=None<br/>run_id=房间ID]
    E --> I[Mem0.add 异步写入]
    F --> I
    G --> I
    H --> I
    I --> J[Mem0 自动事实提取 / 去重 / 合并]
    J --> K[Qdrant 向量存储]

写入时根据场景选择作用域：

场景	写入内容	user_id	agent_id
用户发言	用户说的话、情绪、偏好	用户 ID	为空（公共记忆）
Agent 回复用户	Agent 与用户的完整对话轮次	用户 ID	当前 Agent ID
Agent 之间互动	Agent A 对 Agent B 的回复	为空	Agent A ID
会话摘要生成	摘要内容作为长期事实	为空	为空 / run_id=room_id

4.2.4 长期记忆读取流程

Agent 生成回复前，Memory Service 会按优先级分层检索相关记忆：

flowchart TB
    A[当前消息] --> B[检索 Agent ↔ 当前用户 私有记忆]
    B --> C[检索 用户公共记忆]
    C --> D[检索 该 Agent 公共记忆]
    D --> E[检索 全局公共记忆]
    E --> F[按相关度 + 时间排序]
    F --> G[去重]
    G --> H[注入 Prompt]

检索优先级：

Agent 对当前用户的私有记忆（user_id=user_id, agent_id=agent_id）
用户的公共记忆（user_id=user_id, agent_id=None）
该 Agent 的公共记忆（user_id=None, agent_id=agent_id）
全局公共记忆（user_id=None, agent_id=None，如房间摘要、重要事件）

注入 Prompt 时，记忆会被格式化为：

### 关于 {target_user_name} 的记忆
- 阿杰记得 {target_user_name} 上周说很喜欢吃火锅。
- {target_user_name} 提到过自己是程序员，工作压力比较大。

### 关于你自己的记忆
- 你之前答应过 {target_user_name} 要推荐科幻电影。

### 群聊公共记忆
- 这个群经常深夜聊天，氛围比较轻松。

4.2.5 记忆与结构化表的联动

Mem0 负责“自动提取和检索事实”，但一些业务逻辑仍需要显式的关系型数据，因此会同步到 MySQL：

关系变化：当 Mem0 提取到“用户和 Agent 关系变好/变差”时，更新 relationships 表的 intimacy 字段；
重要事件：当提取到“用户生日”“吵架”“约定”等事件时，写入 events 表，便于按时间线展示；
用户画像摘要：定期从 Mem0 导出用户画像，更新 user_profiles.summary。

实现方式：后台 Worker 定期扫描 Mem0 新增记忆，用 LLM 判断是否需要更新结构化表。

async def sync_structured_memory(user_id: str, agent_id: str):
    recent_memories = memory.get_all(user_id=user_id, agent_id=agent_id, limit=50, after=timestamp_24h_ago)
    result = await llm.analyze_memory_changes(recent_memories)
    if result["relationship_change"]:
        await update_relationship(...)
    if result["new_events"]:
        await create_events(...)
    if result["profile_update"]:
        await update_user_profile(...)

4.3 消息流与调度

sequenceDiagram
    autonumber
    participant U as 用户
    participant F as FastAPI / WebSocket
    participant R as Redis 短期记忆
    participant M as Mem0 长期记忆
    participant O as Orchestrator 调度器
    participant A as AgentInstance
    participant D as DeepSeek

    U->>F: 发送消息
    F->>MySQL: 保存消息
    F->>U: 广播用户消息
    F->>R: 写入短期记忆
    F->>M: 异步写入长期记忆
    F->>O: 触发 Agent 回复决策
    loop 对每个 Agent
        O->>A: should_reply(query, recent, memories)
        A->>M: 检索相关记忆
        A->>D: 判断是否回复、回复对象、意图
        D-->>A: JSON 决策
    end
    O->>O: 按置信度排序，限制并发数
    loop 被选中的 Agent
        O->>A: generate_reply(...)
        A->>R: 读取近期消息
        A->>M: Middleware 注入记忆
        A->>D: 生成回复
        D-->>A: 文本回复
        A-->>O: 回复内容
    end
    O->>F: 逐个保存并广播 Agent 回复
    F->>R: 更新短期记忆
    F->>M: Middleware 写入对话记忆

调度策略包括：

最大同时响应数：默认限制并发 Agent 回复数，避免刷屏；
冷却时间：同一 Agent 两次发言间隔不少于 N 秒；
相关性过滤：消息与 Agent 兴趣/角色相关才参与；
@ 触发：被 @ 的 Agent 优先响应；
情绪/氛围：根据聊天氛围调整不同类型 Agent 的发言权重。

4.4 工具与 ReAct

AgentScope 2.0 的 Agent 内置 ReAct 循环，可自动调用工具。当前支持的工具包括：

time：获取当前时间；
weather：查询天气；
location_by_ip：IP 定位；
web_search：网络搜索（DuckDuckGo 或 Serper）；
fetch_url：抓取网页内容。

工具通过 FunctionTool 注册到 Toolkit，Agent 自己决定什么时候调用。

4.5 人格画像与关系设计

4.5.1 Agent 人格模型

Agent 的人格不仅是 prompt，而是一套可运营、可迭代的配置。核心表结构如下：

CREATE TABLE agents (
    id CHAR(36) PRIMARY KEY DEFAULT (UUID()),
    name VARCHAR(64) NOT NULL UNIQUE,       -- 昵称，全局唯一
    avatar_url VARCHAR(255),
    age INT,
    job VARCHAR(64),
    traits JSON,                            -- 性格标签，如 ["乐观", "毒舌"]
    interests JSON,                         -- 兴趣话题，如 ["电影", "旅行"]
    speaking_style TEXT NOT NULL,           -- 说话风格描述
    system_prompt TEXT NOT NULL,            -- 核心系统提示词
    voice_tone VARCHAR(32),                 -- 语气基调
    default_reply_probability DECIMAL(3,2) DEFAULT 0.5,
    max_reply_length INT DEFAULT 200,
    forbidden_topics JSON,                  -- 禁忌话题
    persona_summary TEXT,                   -- 一句话人设（可自动生成）
    status VARCHAR(16) DEFAULT 'active',    -- active | disabled | archived
    current_version INT DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

关键设计：

name 全局唯一，作为 Agent 在群聊中的显示名；
traits / interests 用 JSON 数组，便于后续做相关性过滤和标签检索；
persona_summary 由系统根据 traits + speaking_style + interests 自动生成，用于 should_reply 等轻量决策；
status 支持 active / disabled / archived，便于灰度和下线；
current_version 指向 agent_versions 表的最新版本，支持人格迭代。

Agent 配置示例：

{
  "name": "阿杰",
  "age": 28,
  "job": "程序员",
  "traits": ["幽默", "直率", "有点宅"],
  "interests": ["游戏", "科幻电影", "电子产品"],
  "speaking_style": "说话直接，喜欢用网络梗，偶尔会吐槽",
  "voice_tone": "轻松调侃",
  "system_prompt": "你是阿杰，28岁程序员。你性格幽默直率，说话喜欢用网络梗。你正在一个群聊里和朋友聊天。请记住：你是 AI，不是真人。不要诱导用户泄露隐私或进行危险行为。",
  "default_reply_probability": 0.6,
  "max_reply_length": 150,
  "forbidden_topics": ["政治", "暴力", "色情"]
}

4.5.2 用户画像模型

用户画像是 Agent“懂用户”的基础，与 Mem0 形成互补：

CREATE TABLE user_profiles (
    user_id CHAR(36) PRIMARY KEY,
    summary TEXT,                 -- 一句话画像（可由 Mem0 导出）
    attributes JSON,              -- 稳定属性，如 {"city": "杭州", "job": "设计师"}
    preferences JSON,             -- 喜欢/讨厌的话题
    updated_at DATETIME
);

summary：由 LLM 定期从 Mem0 记忆中提炼；
attributes：用户明确告诉系统的稳定属性；
preferences：喜欢/讨厌的话题，用于过滤和个性化推荐。

用户画像会作为动态上下文注入 Agent 的 system prompt：

关于 {target_user_name} 的重要记忆：
- 他是程序员，工作压力大。
- 他喜欢猫，讨厌下雨天。
- 他上周提到最近在追《三体》。

实际效果如下图所示：用户问王姐“你对我的画像是什么”，王姐基于长期记忆中积累的事实，总结出了“好奇心强、有点迷糊、爱玩爱闹、可能搞技术”等画像特征，并用了符合其“王姐”人设的俏皮语气表达。

4.5.3 关系模型

关系表维护 Agent-用户、Agent-Agent 之间的亲密度和关系类型：

CREATE TABLE relationships (
    id CHAR(36) PRIMARY KEY DEFAULT (UUID()),
    room_id CHAR(36) NOT NULL,
    source_id CHAR(36) NOT NULL,         -- Agent 或 User ID
    target_id CHAR(36) NOT NULL,
    relation_type VARCHAR(32),           -- 'friend' | 'colleague' | 'rival' | 'intimate'
    intimacy INT CHECK (intimacy BETWEEN 0 AND 100),
    notes TEXT,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

关系会影响：

发言决策：关系亲密的 Agent 更可能主动接话；
语气风格：对亲密的人更随意，对陌生的人更礼貌；
话题选择：知道用户和 Agent A 吵过架，Agent B 可能会岔开话题。

关系文本会注入 prompt：

你与其他人的关系：
- 与 阿杰：friend，亲密度 80/100。经常一起打游戏。
- 与 小明：colleague，亲密度 50/100。普通朋友。

4.5.4 事件模型

重要事件（生日、约定、吵架、里程碑）单独记录，便于按时间线回溯：

CREATE TABLE events (
    id CHAR(36) PRIMARY KEY DEFAULT (UUID()),
    room_id CHAR(36) NOT NULL,
    user_id CHAR(36),
    agent_id CHAR(36),
    event_summary TEXT NOT NULL,
    emotion_tag VARCHAR(32),             -- happy | sad | angry | excited
    happened_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

事件可以由 Mem0 自动提取后同步写入，也可以由运营/用户手动维护。Agent 在合适时机引用事件，会让陪伴感更强：

群聊公共记忆：
- 上周大家一起为 {user} 庆祝了生日，氛围很开心。
- {user} 和 阿杰 约定这周末一起联机《黑神话：悟空》。

4.6 安全与治理

陪伴类系统对安全和边界的要求很高，Agent-Chat 从几个层面做了约束：

人格边界：Agent 的 system_prompt 必须包含“你是 AI，不是真人”的声明；
内容审核：LLM 输出先经过敏感词/有害内容检测，必要时拦截并重写；
频率限制：单个用户/Agent 的消息频率限制，防止刷屏；
隐私隔离：长期记忆按房间/用户隔离，支持用户删除自己的记忆；
审计日志：所有 LLM 调用记录模型、Prompt、Token 消耗、耗时；
禁忌话题：每个 Agent 可配置 forbidden_topics，遇到相关话题主动回避。

五、快速上手

5.1 安装依赖

# 使用 Poetry
poetry install

# 或使用 pip
pip install -r requirements.txt

5.2 配置环境变量

复制 .env.example 为 .env：

cp .env.example .env

关键配置：

DEEPSEEK_API_KEY=your_deepseek_key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

MYSQL_URL=mysql+aiomysql://root:password@localhost:3306/agentscope_chat?charset=utf8mb4
REDIS_URL=redis://localhost:6379/0
QDRANT_URL=http://localhost:6333

EMBEDDING_MODEL_PATH=/path/to/bge-small-zh-v1.5
EMBEDDING_MODEL_DIMS=512

5.3 启动服务

# 一键启动依赖（MySQL + Redis + Qdrant）
docker-compose up -d

# 运行数据库迁移
poetry run alembic upgrade head

# 启动应用
poetry run uvicorn app.main:app --reload --port 8020

5.4 访问

Web UI：http://localhost:8020/chat
Admin 后台：http://localhost:8020/admin
API 文档：http://localhost:8020/docs

六、项目结构

app/
├── main.py              # FastAPI 入口
├── config.py            # 配置管理
├── api/                 # REST API 路由
├── websocket/           # WebSocket 处理
├── agents/              # AgentScope Agent 定义与管理
│   ├── instance.py      # AgentInstance 包装 AgentScope Agent
│   ├── runtime.py       # RoomRuntime / RoomManager
│   ├── scope_models.py  # DeepSeekChatModel 单例
│   ├── tools.py         # FunctionTool 工具集
│   └── group_chat_mem0_middleware.py  # 自定义记忆 Middleware
├── memory/              # 短期/长期记忆服务
│   ├── short_term.py    # Redis 短期记忆
│   └── long_term.py     # Mem0 长期记忆封装
├── models/              # SQLAlchemy 数据模型
├── schemas/             # Pydantic 模型
├── services/            # 业务服务
└── static/              # Web UI 静态文件

七、典型应用场景

AI 陪伴社群：运营一批有固定人设的 Agent，让用户感觉像加了一个兴趣群；
角色扮演游戏：每个 Agent 扮演不同 NPC，用户参与剧情；
情感支持/树洞：Agent 记住用户情绪历史，提供持续性心理陪伴；
语言练习：多个 Agent 分别扮演不同口音/性格的语伴；
产品原型验证：快速验证多 Agent 交互体验，再决定是否自研更底层框架。

八、写在最后

Agent-Chat 的初心不是做一个“更聪明的聊天机器人”，而是做一个有温度、有记忆、有社交感的多 Agent 群聊底座。它把 FastAPI 的实时能力、AgentScope 2.0 的 Agent 运行时、DeepSeek 的对话能力、Mem0 的长期记忆能力拼在一起，让开发者可以用配置文件“捏”出一群性格各异的朋友。

项目还在持续迭代中，欢迎试用、提 issue、一起完善。

开源地址：https://gitee.com/soulnew/agent-chat

如果你也在做多 Agent 陪伴系统，欢迎在评论区交流：你觉得“记忆隔离”和“发言调度”哪个更难做好？

Netflix 的因果推断 Agent 工作流：没有标准答案时，怎么审计一个 AI

Mon, 08 Jun 2026 10:00:00 +0800

Netflix 的因果推断 Agent 工作流：没有标准答案时，怎么审计一个 AI

原文：A Human-Augmenting Agentic Workflow for Causal Inference 目标读者：在做 AI Agent 落地的工程师、数据科学家，以及所有想过「这个 agent 给的数到底能不能信」的人。阅读目标：搞清楚 Netflix 怎么把一个「没有标准答案、错不自知」的分析任务工程化成 agent 工作流，以及这套思路对普通后端和 AI 工程的迁移价值。

〇、先拆一个直觉：agent 给了答案，你敢用吗

先想一个场景：你让一个数据分析 agent 回答「看某部爆款剧对会员长期留存有没有因果效应」。它查了数、跑了回归、自信满满地返回一个数。你该信多少？它有没有处理掉那些隐蔽的偏差——比如把狂热粉丝当成普通观众？没有深厚的方法论功底，你甚至看不出它错没错。

这就是观测性因果推断（Observational Causal Inference，OCI）的特殊处境。一般的 agent 评估套路是拿输出和 ground truth 程序化对比——但观测数据里根本没有 ground truth。不是数据不够，是这个问题在本质上没有标准答案可比对。Netflix 这篇文章的核心贡献，就是正面回答了「评估对象不存在时怎么办」：评估不了结果，就审计过程。

整个工作流立在他们 AI 时代之前就建好的 OCI 工具箱上，指导思想是「目标试验模拟」（target trial emulation）：拿到一个时点型因果问题，先问「回答这个问题的理想 A/B 实验长什么样？」这个实验可能太贵、太慢甚至不可行，但这个思想实验能逼你把假设钉死。

一、四个设计诊断：工具箱里真正的硬货

为了让「目标试验」这个类比可操作，工具箱内置了四个设计诊断，专门检查处理组和对照组的比较是否公平：

协变量平衡：加权之后，处理组和对照组在处理前协变量上的标准化均差应小于 0.2。
重叠性（overlap）：接受处理的概率（倾向得分）应该落在 0.1 到 0.9 之间——太接近 0 或 1 的样本，处理与否基本是注定的，不存在「可比的对照」。
安慰剂结局：在处理发生之前测量的变量上，「处理效应」应该和零没有显著差异。处理还没发生就有效应，说明两组人本来就不同。
对隐藏混杂的敏感性：结论要放在「假设存在一个同时影响处理和结局的遗漏变量」的语境下重新考量。

这四条没有什么 AI 含量，全是统计学的老手艺。但这正是文章的潜台词：agent 工作流的可靠性不来自模型更聪明，来自把纪律焊死在流程里。

二、三个角色：Principal、Actor、Critic

工作流有三个角色，后两个由软件扮演，跑成一个 actor-critic 循环：

flowchart TD
    P["Principal 人类<br/>写初始分析计划<br/>交代混杂因素与业务背景<br/>指定可用工具和数据集"] --> A["Actor 软件<br/>把计划细化为分析 spec<br/>只用被允许的工具执行<br/>跑核心分析和四个设计诊断"]
    A --> ART["工件<br/>plan 和 spec<br/>图表 报告 可复现 notebook"]
    A --> C["Critic 软件<br/>找计划盲区 查计划与执行的一致性<br/>给结果定可信度等级<br/>对照理想 RCT 找差距"]
    C -->|"诊断失败或发现盲区<br/>触发补救或下一轮迭代"| A
    ART -->|"过程审计<br/>人类可下载重跑"| P
    style P fill:#fff3cd
    style ART fill:#e8f5e9

Critic 的职责清单值得细看，它不只是「再看看对不对」：检查 Principal 计划里没提到的混杂因素；核对计划、spec、实际执行三者是否对齐；看完诊断后给结果定可信度等级；明确说明估计量是否偏离了 ATE（比如因为倾向得分裁剪）；把实际分析和理想 RCT 做对照；还要至少给出一种替代测量方案（比如激励式 RCT）。

人类这边的配套是一个模板化 notebook，底层用经过验证的（非 agent 的）OCI 工具箱，效应估计用 doubly robust learning。agent 产出的报告有版本控制，执行过的 notebook 上传到文件存储，Principal 可以下载下来亲自重跑。人不用亲自干苦活，但每一步都留了可以让人验算的凭据——这就是标题里 “human-augmenting” 的实际含义：不是替代人，是把人的精力从重复劳动（反复检查协变量平衡、跑敏感性分析、管理迭代版本）挪到只有人能做的事上（框定问题、审视假设、判断结果）。

三、案例：新娱乐类型的留存影响，估计值缩水到四分之一

Netflix 近年加了不少视频之外的新娱乐类型，自然要问：这些东西对会员满意度和续订有什么影响？他们拿其中一个类型（文中叫 Type X）做了对照实验：

处理：Type X 的使用天数
结局：两个月留存
潜在混杂：包括处理前的 Type X 使用天数

基线：把这份分析计划不加任何脚手架直接喂给 Claude Sonnet 4.6。模型选了一个说得过去的策略——用留存对使用天数加控制变量做线性回归——输出干净漂亮。

paved path（铺好的路）：同一份计划、同一个模型，走他们的工具箱加 agentic 工作流，产出的估计值只有基线的 25%。

差异的根源是早期采用者偏差（early adopter bias）：新功能的第一批用户和一般人群系统性不同——他们可能是 Netflix 重度用户，或者是相关 IP 的死忠粉。这个偏差在数据里表现为重叠性崩塌：绝大多数观测的 Type X 参与概率估值都极小（功能还太新）。critic 在报告里抓住了这个问题，还标记了安慰剂检验失败：早期采用者在处理发生之前测量的重要协变量上就和非采用者有显著差异——两组人本来就不是一路人。

补救手段来自工作流内置的 playbook：重叠性差就用 Crump 式裁剪，估计因果效应前先把倾向得分落在 0.1 到 0.9 之外的样本裁掉。代价是结论的适用范围缩水——估计的 ATE 只适用于「参与与否不是注定」的那部分人群，critic 必须在报告里把这个注意事项写明。但换来的是可信度的质变：裁剪后的估计只依赖「处理近似随机」的子人群，和目标试验的精神一致；而基线那个数靠的是对低概率人群的外推，外推出来的数字没有扎实数据支撑，还很可能被早期采用者偏差污染。

flowchart LR
    PLAN["同一份分析计划<br/>同一个 Sonnet 4.6"] --> BASE["裸调 one-shot<br/>线性回归 不加诊断"]
    PLAN --> PP["paved path<br/>脚手架加诊断加 critic"]
    BASE --> B1["结果干净漂亮<br/>但依赖外推<br/>被早期采用者偏差污染"]
    PP --> D1["重叠性诊断失败<br/>安慰剂检验失败"]
    D1 --> D2["Crump 裁剪<br/>只保留倾向得分 0.1 到 0.9 的人群"]
    D2 --> B2["估计值只有基线的 25%<br/>适用范围缩水但可信"]
    style B1 fill:#ffcccc
    style B2 fill:#e8f5e9

这个案例最扎心的地方在于：基线的产出是「defensible」的——策略挑不出大毛病，呈现也很专业。如果你不是 OCI 从业者，你大概率就收下了。

四、编排后续分析：agent 真正省力的部分

分析做完还有两类自然后续，都是「同一分析跑 N 个变体」的脏活：

敏感性分析：换不同的裁剪阈值重做分析。他们让 agent 把裁剪界从 0 到 1（不裁剪）一路变到 0.15 到 0.85，结论是重叠人群上的 ATE 估计在 0.005 到 0.995 的界内对阈值选择稳健。
时间序列：把同一分析在十个不同的日期分区上重跑，看效应随时间的演变。这里有个微妙的坑：跨时间比较必须协调各次分析的人群——如果某次为了可信度裁掉了一批用户，其他几次也得裁同一批。跑出来的结果显示季节性：冬季日期的处理效应强于夏季。

这两类活的技术含量为零，出错概率不低（参数改一个忘一个、人群没对齐），正是 agent 该吃的苦。

五、开源与评测：critic 真的能区分好坏估计

Netflix 开源了一个独立版 oci-agent，附带两个基于 ACIC 2016（大西洋因果推断会议竞赛）公开数据集的评测，以及一个只用开源软件（EconML）的轻量因果机器学习 notebook。

评测一：对 77 个数据生成过程（DGP）各随机抽 3 个数据集，共 231 个估计，让 critic 依据诊断把它们分成 satisfactory 和 unsatisfactory。结果：192 个 satisfactory、39 个 unsatisfactory。对照竞赛里 44 个参赛方法，他们的统计方法本身就有竞争力——RMSE 足够低，95% 置信区间的覆盖率约 95%（校准良好）。但重点在这：satisfactory 那组的 RMSE 显著更低、区间校准更好，unsatisfactory 那组明显更差——诊断套件加 critic 确实能把可信的估计和不可信的估计分开。

评测二：同一份分析计划，带脚手架 vs 裸调（one-shot prompting）。随机抽十个 ACIC 数据集，带脚手架的 LLM 复原了九个的真值，且估计与真值高度相关；裸调 Sonnet 4.6 则一致地错，和真值基本不相关。

作者也坦白了局限：合成数据集压测不了 agent 对真实业务场景的语义理解。但仓库演示了两条核心原则——用足量脚手架让 agent 按设计遵守最佳实践；要求可检查的工件，让人类能审计 agent 的过程而不只是结果。

工程实践联想

没有 ground truth 的领域，把 eval 拆成「结果评估」和「过程审计」两层。 推荐、增长、风控策略、A/B 之外的分析场景，大量任务都没有可比对的标准答案。Netflix 的答案是：结果层用代理指标（ACIC 合成数据上的 RMSE），过程层靠工件留痕（plan、spec、notebook、版本化报告）让人审。我们写 agent 时也该问一句：这个 agent 的产出，三个月后另一个工程师能不能重建它的推理链？
脚手架比模型重要。 同一个 Sonnet 4.6，裸调和走 paved path 的估计差了 4 倍——而且错的是看起来更漂亮的那个。「换更强的模型」解决的是能力问题，「模板、诊断、playbook、强制的 critic 环节」解决的是纪律问题。分析类任务里，纪律缺口比能力缺口大得多。
actor-critic 结构的关键是 critic 有独立的、可操作的责任清单。 Netflix 的 critic 不是泛泛地「你再检查一遍」，而是有具体义务：找计划盲区、核对三层一致性、定可信度等级、对照理想 RCT、给替代方案。critic 的职责越具体，漏检越少。这和 code review 清单化是同一个道理。
诊断失败要有 playbook，而不是一句「请注意」。 重叠性差对应 Crump 裁剪，裁剪导致估计量偏离 ATE 就要求 critic 在报告里标注适用范围。诊断、补救、注意事项三条线绑在一起，流程才是闭环的。我们系统里的告警如果只报不处理，和人肉运维没区别。
把人放在「审」的位置，而不是「干」的位置。 人的精力留给框定问题、审视假设、判断结果；重复执行、版本管理、批量变体交给 agent。这个分工原则对任何「专业判断密集 + 重复劳动密集」的工作流都成立，不止因果推断。

本篇小结

问题：观测性因果推断没有 ground truth，agent 给的因果答案无法拿结果对错来评估，错了也很难被发现。
解法：Principal-Actor-Critic 三角色工作流。人类写计划和背景，actor 按模板执行分析并跑四个设计诊断（协变量平衡 SMD ＜ 0.2、倾向得分落在 0.1 到 0.9、安慰剂结局、敏感性分析），critic 有明确清单地挑毛病并定可信度。
人的位置：human-augmenting 的落点是工件——版本化报告、可下载重跑的 notebook——用过程审计代替结果评估。
案例：新娱乐类型的留存效应，裸调 Sonnet 4.6 给出漂亮但依赖外推的回归结果；走工作流后诊断抓住早期采用者偏差，Crump 裁剪后估计值只有基线的 25%。
评测：ACIC 2016 上 231 个估计，critic 判定的 192 个 satisfactory 估计质量显著优于 39 个 unsatisfactory；带脚手架 10 个数据集复原 9 个真值，裸调全军覆没。
私货：这篇文章真正的主题不是因果推断，是「如何工程化地使用一个你信不过的聪明组件」——脚手架定纪律、critic 做对抗、工件留凭据、人类审过程。这套四件套放在任何高风险 agent 场景都成立。

参考资料

原文：Winston Chou 等，A Human-Augmenting Agentic Workflow for Causal Inference，Netflix Technology Blog，2026-06-08。
开源仓库：Netflix 的独立版 oci-agent（原文有链接，基于 EconML）。
2016 Atlantic Causal Inference Conference（ACIC）数据分析竞赛数据集（评测所用的 77 个 DGP 来源）。
Crump 等人的倾向得分裁剪方法（重叠性诊断失败的补救手段，原文引用的 playbook 条目）。

LLM 输出 JSON 不稳定：Schema + 重试的实战方案

Thu, 02 Apr 2026 15:00:00 +0800

LLM 输出 JSON 不稳定：Schema + 重试的实战方案

做 AI Agent 或 LLM 应用时，一个高频需求是让模型输出结构化数据。比如 Agent 需要 LLM 决定调用哪个 Tool、视觉规划需要输出 JSON 数组、代码生成需要返回固定格式的片段。但 LLM 输出 JSON 很容易出问题：格式错乱、字段缺失、类型不对、多了句废话。这篇文章分享我们是如何把结构化输出成功率从 75% 左右提升到 98% 以上的。

一、问题的普遍性

我们先看几个真实遇到的 LLM 输出：

场景 1：Agent 决定调用 Tool

期望输出：

{
  "tool": "RetrieveMaterials",
  "params": {"query": "海边日落"}
}

实际输出：

我决定调用 RetrieveMaterials 工具，参数是 {"query": "海边日落"}。

场景 2：视觉规划输出 JSON 数组

期望输出：

[{"element_type": "TitleCard", "content": "AI 剪辑实战"}]

实际输出：

{
  "result": [{"element_type": "TitleCard", "content": "AI 剪辑实战"}]
}

场景 3：字段类型错误

{
  "duration": "30秒"
}

期望是数字：30。

这些输出人都看得懂，但程序解析不了。不解决的话，LLM 应用根本跑不稳。

二、常见的四层解决方案

我们实践下来，可靠的方案是四层防护：

flowchart TD
    A["第一层：Prompt 设计（明确格式 + Few-shot）"] --> B["第二层：JSON Schema / Function Calling 约束"]
    B --> C["第三层：后端 Pydantic 校验"]
    C --> D["第四层：自动重试 + 降级"]

单层都不够，必须组合使用。

三、第一层：Prompt 设计

3.1 明确输出格式

Prompt 里必须清楚说明输出格式，不要含糊：

请直接输出 JSON，不要包含任何解释性文字。
JSON 格式如下：
{
  "tool": "工具名称",
  "params": {
    "参数名": "参数值"
  }
}

3.2 Few-shot 示例

在 Prompt 里给 2-3 个正确示例，效果提升明显：

示例 1：
输入：用户想要一个海边日落视频
输出：{"tool": "RetrieveMaterials", "params": {"query": "海边日落"}}

示例 2：
输入：用户想要删除视频中的语气词
输出：{"tool": "RemoveFillers", "params": {"aggressive": false}}

3.3 限制输出长度

对于简单任务，明确要求 LLM 不要展开：

输出必须严格符合上述 JSON 格式，总长度不超过 200 个字符。

四、第二层：JSON Schema 约束

4.1 什么是 JSON Schema

JSON Schema 是一种描述 JSON 数据结构的规范。你可以把它传给 LLM，让模型按这个结构输出。

DeepSeek、GPT-4、Claude 3 都支持 JSON Schema 或 Function Calling。

4.2 我们的 Schema 示例

visual_plan_schema = {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "sentence_index": {"type": "integer"},
            "element_type": {
                "type": "string",
                "enum": ["TitleCard", "BRoll", "QuoteCard", "CodeBlock", "ListCard", "TalkingHead"]
            },
            "reason": {"type": "string"},
            "suggested_content": {"type": "string"}
        },
        "required": ["sentence_index", "element_type", "reason"]
    }
}

4.3 DeepSeek 调用示例

import openai

client = openai.OpenAI(
    api_key="your-api-key",
    base_url="https://api.deepseek.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个专业的视频剪辑规划助手。"},
        {"role": "user", "content": prompt}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "visual_plan",
            "schema": visual_plan_schema
        }
    },
    temperature=0.2
)

result = json.loads(response.choices[0].message.content)

4.4 Function Calling

Function Calling 本质上也是让 LLM 输出结构化的函数调用参数：

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": prompt}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "plan_visual_elements",
                "description": "为口播视频规划视觉元素",
                "parameters": visual_plan_schema
            }
        }
    ],
    tool_choice={"type": "function", "function": {"name": "plan_visual_elements"}}
)

tool_call = response.choices[0].message.tool_calls[0]
result = json.loads(tool_call.function.arguments)

Function Calling 的好处是模型更清楚自己在做什么，输出稳定性通常更好。

五、第三层：Pydantic 后端校验

即使 LLM 支持 Schema，也不能 100% 保证输出合法。后端必须用 Pydantic 做严格校验。

5.1 模型定义

from pydantic import BaseModel, Field, field_validator
from typing import Literal

class VisualElement(BaseModel):
    sentence_index: int = Field(ge=0)
    element_type: Literal["TitleCard", "BRoll", "QuoteCard", "CodeBlock", "ListCard", "TalkingHead"]
    reason: str = Field(min_length=5, max_length=200)
    suggested_content: str = ""

    @field_validator('suggested_content')
    @classmethod
    def validate_content(cls, v, info):
        element_type = info.data.get('element_type')
        if element_type == "TitleCard" and len(v) < 2:
            raise ValueError("TitleCard 必须有标题内容")
        return v

class VisualPlan(BaseModel):
    elements: list[VisualElement]

5.2 校验与错误收集

def parse_visual_plan(raw_output: str) -> VisualPlan:
    try:
        data = json.loads(raw_output)
    except json.JSONDecodeError as e:
        raise ValueError(f"JSON 解析失败: {e}")

    # 兼容 LLM 外层多套一层 result 的情况
    if isinstance(data, dict) and "result" in data and isinstance(data["result"], list):
        data = data["result"]

    return VisualPlan(elements=data)

5.3 常见兼容处理

实际生产中会见到各种「不标准」的输出，我们做了几个兼容：

去掉 Markdown 代码块标记 json ...
去掉多余的前缀说明文字
兼容外层多套一层 {"result": [...]} 的情况
兼容中文字段名（如果 Prompt 不小心用了中文）

六、第四层：自动重试 + 降级

6.1 重试策略

当校验失败时，不要直接报错，而是把错误信息回传给 LLM，让它重新生成。

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=1, max=5),
    retry=retry_if_exception_type(ValueError)
)
def generate_with_retry(prompt: str, schema: dict) -> dict:
    raw = llm.generate(prompt, response_format=schema)

    try:
        return parse_visual_plan(raw)
    except ValueError as e:
        # 把错误信息加入 Prompt，重新生成
        prompt += f"\n\n注意：你之前的输出校验失败，错误是：{e}\n请严格按照 JSON Schema 输出。"
        raise

6.2 温度参数调整

重试时降低 temperature，让输出更稳定：

temperature_schedule = [0.2, 0.1, 0.0]

6.3 降级方案

如果 3 次重试都失败，不能卡住，要有降级：

def safe_generate_visual_plan(script: str) -> VisualPlan:
    try:
        return generate_with_retry(script)
    except Exception:
        # 降级：所有句子保持 TalkingHead
        return VisualPlan(elements=[
            VisualElement(
                sentence_index=i,
                element_type="TalkingHead",
                reason="LLM 规划失败，降级为默认方案"
            )
            for i in range(len(script.split('。')))
        ])

这样至少能保证系统不崩，用户可以拿到一个基础版本的视频。

七、完整代码示例

import json
from pydantic import BaseModel, Field
from typing import Literal

class VisualElement(BaseModel):
    sentence_index: int = Field(ge=0)
    element_type: Literal["TitleCard", "BRoll", "QuoteCard", "CodeBlock", "ListCard", "TalkingHead"]
    reason: str = Field(min_length=5, max_length=200)
    suggested_content: str = ""

def clean_llm_output(raw: str) -> str:
    """清理 LLM 可能产生的多余格式"""
    raw = raw.strip()
    if raw.startswith("```"):
        raw = raw.strip("`")
        if raw.startswith("json"):
            raw = raw[4:].strip()
    return raw

def robust_parse(raw: str) -> list[VisualElement]:
    raw = clean_llm_output(raw)

    try:
        data = json.loads(raw)
    except json.JSONDecodeError:
        # 尝试找到第一个 [ 和最后一个 ]
        start = raw.find("[")
        end = raw.rfind("]")
        if start != -1 and end != -1:
            data = json.loads(raw[start:end+1])
        else:
            raise

    # 兼容外层嵌套
    if isinstance(data, dict):
        for key in ["result", "data", "elements"]:
            if key in data and isinstance(data[key], list):
                data = data[key]
                break

    if not isinstance(data, list):
        raise ValueError(f"期望数组，实际得到 {type(data)}")

    return [VisualElement(**item) for item in data]

八、效果数据

在我们实际使用中，这套四层方案的效果如下：

方案	解析成功率
纯 Prompt 约束	约 75%
+ JSON Schema	约 90%
+ Pydantic 校验 + 重试	约 98%
+ 降级方案	系统可用性 99.9%+

（待补充真实数据）

九、踩过的坑

9.1 Schema 太复杂导致模型懵

早期的 Schema 有 20 多个字段，模型输出经常漏字段。

解决：Schema 只保留必要字段，非必要字段放 metadata 或后续步骤再补。

9.2 中文标点导致 JSON 解析失败

LLM 输出中文引号或中文逗号，导致 JSON 解析失败。

解决：在 Prompt 里明确说明用英文标点，后端做字符替换兼容。

9.3 模型输出超长

复杂任务下，LLM 输出解释性文字 + JSON，超出 Schema 控制。

解决：

明确要求「只输出 JSON，不要解释」
设置 max_tokens 上限
后端做截断和清洗

9.4 不同模型 Schema 支持不一致

DeepSeek、GPT、Claude 对 JSON Schema 的支持细节不同。

解决：

统一封装 LLM 调用层
对不同模型做适配
尽量使用 Function Calling，兼容性更好

十、总结

LLM 输出结构化数据不稳定，不是模型不行，而是提示、约束、校验、重试四个环节必须闭环。我们的经验是：

Prompt 要明确要求格式，别指望模型自己猜
JSON Schema / Function Calling 是第二层保险
后端 Pydantic 校验必不可少，不要信任模型输出
重试 + 降级保证系统可用性，而不是一失败就抛异常
对模型差异做抽象封装，方便切换和升级

这套方案不只适用于视频生成，几乎所有 LLM Agent 应用都需要。

如果你在 LLM 结构化输出方面也踩过坑，欢迎在评论区分享。

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

Fri, 09 Jan 2026 10:00:00 +0800

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

参考：shareAI-lab/learn-claude-code

你有没有想过，为什么你跟 Claude Code 说“帮我改一下这个网页”，它就能自己打开文件、修改代码、运行测试，然后告诉你结果？

它看起来好聪明，像人一样会“动手”。但其实，它背后的原理并不神秘，甚至可以用几十行简单的代码讲清楚。

这篇文章是给新手的。不管你有没有学过编程，我都会尽量用生活中的例子来解释。读完之后，你会明白：

Claude Code 最核心的部分是什么；
它是怎么“看懂”文件、“动手”改代码的；
它为什么能记住很多事情、做错事能重来；
以及如果你想自己做一个类似的 AI 助手，应该从哪里开始。

一、一句话讲清楚 Claude Code

如果把 Claude Code 拆开，你会发现它只有三个东西：

一个循环 + 一张工具表 + 一个会说话的 AI

部件	作用	生活里的比喻
会说话的 AI（大语言模型）	思考、理解你说的话、决定下一步做什么	一个超级聪明的大脑
工具表	让 AI 能读写文件、运行命令、搜索代码	给大脑装上双手和眼睛
循环	不断重复“思考 → 行动 → 看结果 → 再思考”	机器人一直干活，直到做完

这个“循环”非常重要。没有它，AI 就只能说一次话，没法连续做很多事。

flowchart LR
    subgraph 工具箱["🧰 工具箱（Harness）"]
        读文件["读文件"]
        写文件["写文件"]
        执行命令["执行命令"]
        搜索["搜索代码"]
        权限["权限检查"]
    end

    大脑["🧠 AI 大脑<br/>会思考、会推理"]
    电脑["💻 你的电脑"]

    大脑 -->|我想读文件| 读文件
    读文件 -->|文件内容| 大脑
    大脑 -->|我想运行测试| 执行命令
    执行命令 --> 电脑
    电脑 -->|测试结果| 大脑
    权限 -->|这个能做吗？| 执行命令

二、最核心的 30 行代码

Claude Code 的心脏，是一段很简单的代码。你可以把它理解成“机器人干活的主流程”：

def agent_loop(query):
    # 1. 先把用户的问题记下来
    messages = [{"role": "user", "content": query}]

    while True:
        # 2. 把对话历史发给 AI，告诉它有哪些工具可以用
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,
            messages=messages,
            tools=TOOLS,
            max_tokens=8000,
        )

        # 3. 把 AI 的回复存进历史
        messages.append({"role": "assistant", "content": response.content})

        # 4. 如果 AI 不再调用工具，就说明它说完了，结束循环
        if response.stop_reason != "tool_use":
            return

        # 5. 执行 AI 要求的工具，并把结果告诉它
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

人话解释

你问了一个问题 → 比如“帮我修一下这个 bug”。
AI 看历史和工具表 → 它想：“我需要先读一下代码文件。”
AI 说“我要用读文件工具” → 程序真的去打开文件。
把文件内容还给 AI → AI 再看，决定下一步。
一直重复，直到 AI 说“我搞定了”。

flowchart TD
    开始([你输入任务]) --> 发给AI[把任务+历史发给 AI]
    发给AI --> AI思考[AI 思考]
    AI思考 --> 判断{AI 想调用工具吗？}
    判断 -->|想| 执行工具[程序执行工具]
    判断 -->|不想| 输出答案[输出最终答案]
    执行工具 --> 返回结果[把结果返回给 AI]
    返回结果 --> 发给AI
    输出答案 --> 结束([结束])

三、20 节课都在讲什么？一张总图看懂

Claude Code 的学习资料里有 20 节课，每节课加一个新能力。它们不是乱排的，而是像打游戏升级一样，一步一步变强。

flowchart LR
    subgraph 第一阶段["🌱 第一阶段：让 AI 动起来"]
        s01["s01 循环"]
        s02["s02 工具"]
        s03["s03 权限"]
        s04["s04 钩子"]
    end

    subgraph 第二阶段["🛠️ 第二阶段：做复杂任务"]
        s05["s05 计划"]
        s06["s06 子代理"]
        s07["s07 技能"]
        s08["s08 压缩记忆"]
    end

    subgraph 第三阶段["🧠 第三阶段：记得住、错得了"]
        s09["s09 记忆"]
        s10["s10 系统提示"]
        s11["s11 错误恢复"]
    end

    subgraph 第四阶段["⏳ 第四阶段：长时间运行"]
        s12["s12 任务图"]
        s13["s13 后台任务"]
        s14["s14 定时任务"]
    end

    subgraph 第五阶段["👥 第五阶段：团队协作"]
        s15["s15 队友"]
        s16["s16 团队协议"]
        s17["s17 自治"]
        s18["s18 目录隔离"]
    end

    subgraph 第六阶段["🔌 第六阶段：扩展组装"]
        s19["s19 MCP 插件"]
        s20["s20 完整系统"]
    end

    第一阶段 --> 第二阶段 --> 第三阶段 --> 第四阶段 --> 第五阶段 --> 第六阶段

下面拆解核心部分。

四、第一阶段：让 AI 动起来

s01 Agent Loop：一个循环就够了

这是所有东西的基础。就像你骑自行车，核心是“踩踏板 → 车轮转 → 车前进”这个循环。Claude Code 的核心就是：

AI 思考 → 调用工具 → 看结果 → 再思考 → 再调用工具 → …… → 完成

没有循环，AI 只能说一句话。有了循环，它就能连续做很多步。

s02 Tool Use：从一把螺丝刀到整套工具箱

最早的 AI 只有一个工具：执行终端命令（bash）。但这样很不方便，就像你修自行车只能用一个螺丝刀。

后来 Claude Code 给 AI 配了一整套工具：

read_file：读文件
write_file：写文件
edit_file：改文件中的一部分
glob：按名字找文件
grep：在文件里搜索文字

这些工具是“分发表”管理的。程序不用写一堆 if/else，而是查一个字典：

TOOL_HANDLERS = {
    "read_file":  read_file_function,
    "write_file": write_file_function,
    "edit_file":  edit_file_function,
}

# AI 说想用 read_file，就找到对应的函数执行
handler = TOOL_HANDLERS["read_file"]
result = handler(path="main.py")

好处：加新工具就像往工具箱里多放一把扳手，不用改主流程。

s03 Permission：先问能不能做，再让它做

这是 Claude Code 很重要的一课：自由要有边界。

AI 能力很强，但它不能想删啥就删啥、想改啥就改啥。权限系统就像家长给孩子定规矩：

读文件可以；
修改重要文件要问一下；
删除整个文件夹？不行。

flowchart TD
    AI想做事[AI 想执行命令] --> 查权限{权限系统检查}
    查权限 -->|允许| 直接执行
    查权限 -->|需要确认| 问用户[弹窗问用户]
    查权限 -->|禁止| 拒绝[拒绝执行]
    问用户 -->|同意| 直接执行
    问用户 -->|不同意| 拒绝

这教会我们一个工程原则：先设边界，再给自由。

s04 Hooks：在循环边上挂“挂钩”

Hook 中文叫“钩子”。想象你在书包上挂很多小挂件：钥匙扣、饭卡、耳机。主书包不变，但你可以加东西。

Claude Code 的 Hook 系统也是这样：

工具执行前，可以检查一下（PreToolUse）；
工具执行后，可以记录日志（PostToolUse）；
会话开始/结束时，可以做初始化或清理。

flowchart LR
    AI决定[AI 决定调用工具] --> 前钩子["PreToolUse 钩子<br/>检查/拦截"]
    前钩子 --> 执行工具
    执行工具 --> 后钩子["PostToolUse 钩子<br/>记录/通知"]
    后钩子 --> 返回AI

核心思想：主循环不要改来改去，把扩展功能挂到钩子上。

五、第二阶段：做复杂任务

s05 TodoWrite：先做计划，再动手

如果你要写一篇大作文，你会先列提纲，对吧？Claude Code 也是这样。

做复杂任务前，AI 会先写一个待办清单（Todo）：

1. 读 README 了解项目      [待做]
2. 找到 bug 所在的文件     [进行中]
3. 修改代码                [待做]
4. 运行测试确认修好        [待做]

每完成一步，就更新状态。如果 AI 太久没更新，系统还会“唠叨”它：“喂，你忘了更新待办清单啦！”

这个机制让 AI 不容易“跑偏”。

s06 Subagent：雇一个小助手

有时候一个任务需要查很多东西。比如“这个项目的测试框架是什么？”AI 可能要读 10 个文件才能确定答案是 pytest。

如果让主 AI 自己读 10 个文件，它的“脑子”会塞满东西，又慢又贵。

解决办法是：雇一个临时小助手（子代理）。小助手用全新的对话去读那 10 个文件，最后只把答案“pytest”告诉主 AI。

flowchart LR
    主AI["主 AI"] -->|派任务| 子AI["子 AI<br/>新开一个对话"]
    子AI -->|读10个文件| 文件["项目文件"]
    文件 -->|内容| 子AI
    子AI -->|只返回结论：pytest| 主AI

主 AI 的脑子很干净，只记住了最重要的结论。

s07 Skill Loading：需要哪本字典，就翻哪本

想象你要学数学、物理、化学三科。你不会每次上课都把三本书全背上，而是上什么课带什么书。

Claude Code 也是这样。它有很多“技能书”（比如 git 用法、测试规范、API 文档），但不会一次性全塞给 AI。

它是两层加载：

先给目录：告诉 AI 有哪些技能书；
需要时再翻开：AI 说“我要查 git 那本书”，系统才把完整内容给它。

这样就省了很多“脑容量”。

s08 Context Compact：脑子塞不下时怎么办？

AI 一次能看的文字是有限的，就像你的作业本只有那么多页。如果写得太多，就要翻页或者撕掉旧的。

Claude Code 有三种“翻页”方法：

micro_compact：把很久以前的工具结果换成一句话摘要，比如“之前用过 read_file”；
auto_compact：当文字太多时，自动让 AI 写个总结，用总结替换原来的长对话；
compact 工具：AI 自己决定什么时候该“翻页”。

flowchart TD
    subgraph 第一层["第一层：micro_compact"]
        旧结果["旧工具结果"] --> 占位符["换成占位符<br/>[之前读过 main.py]"]
    end

    subgraph 第二层["第二层：auto_compact"]
        太多文字["对话太长"] --> 写总结["AI 写摘要"] --> 替换历史["用摘要替换历史"]
    end

    subgraph 第三层["第三层：compact 工具"]
        AI判断["AI 觉得该压缩了"] --> 手动触发["调用 compact 工具"]
    end

    第一层 --> 第二层 --> 第三层

六、第三阶段：记得住、错得了

s09 Memory：AI 也要记笔记

AI 没有真正的记忆。每次对话结束，它就忘了。如果想让它长期记住东西（比如你喜欢什么代码风格、项目有什么规矩），就需要一个“记忆系统”。

记忆系统通常分三步：

选择：哪些东西值得记住？
提取：把重要信息摘出来；
固化：存到文件或数据库里，下次对话再读出来。

flowchart LR
    对话["一段对话"] --> 选择["选择重要信息"]
    选择 --> 提取["提取关键事实"]
    提取 --> 存储["存到记忆文件"]
    存储 --> 下次对话["下次启动时读取"]

比如 AI 记住了：“这个用户喜欢用 2 个空格缩进。”下次写代码时它就会自动用 2 个空格。

s10 System Prompt：提示词不是写死的

System Prompt 就是告诉 AI“你是谁、该怎么做事”的那段话。

Claude Code 的 System Prompt 不是一次性写死的，而是运行时拼接的：

基础身份部分；
当前项目规则；
加载的技能书；
用户的偏好记忆。

就像你写作文时，老师给的题目要求 + 你自己的提纲 + 参考资料，组合在一起。

s11 Error Recovery：做错事能重来

AI 也会犯错。比如它调用了一个不存在的文件，或者写的代码运行报错。这时候怎么办？

Claude Code 有几种“重来”策略：

重试：可能是网络抖动，再试一次就好了；
换条路：这个方法不行，换另一个工具试试；
清理空间：上下文太满导致看不清，先压缩一下再试；
换个小模型/大模型：简单任务用小模型省钱，复杂任务换大模型。

flowchart TD
    出错[工具执行出错] --> 重试{重试有用吗？}
    重试 -->|有用| 再试一次
    重试 -->|没用| 换方法[换工具/换思路]
    换方法 -->|还不行| 清空间[压缩上下文]
    清空间 -->|再试| 再试一次

重要道理：错误不是终点，而是调整的起点。

七、第四阶段：长时间运行

s12 Task System：把大目标拆成小任务

复杂项目不能靠一个简单的 Todo 清单。任务之间有依赖关系：

A 做完了，B 才能开始；
C 和 D 可以同时进行；
E 要等 C 和 D 都做完。

Claude Code 用任务图来管理。每个任务存成一个文件，记录自己的状态、依赖谁、被谁依赖。

flowchart LR
    A["设计登录页面"] --> B["写前端代码"]
    A --> C["写后端接口"]
    B --> D["联调测试"]
    C --> D

s13 Background Tasks：慢活放后台

有些命令要跑很久，比如 npm install 可能要几分钟。如果 AI 停下来等，就太浪费了。

Claude Code 会开一个新的后台线程去跑这些慢命令，主 AI 继续思考别的事。等后台跑完了，再通知 AI。

s14 Cron Scheduler：定时任务

Cron 就是“定时器”。比如你可以让 AI 每天早上 8 点检查一遍代码仓库，看看有没有需要更新的依赖。

“到点了就干活，不用人喊。”

flowchart LR
    时间到[时间到了] --> Cron[Cron 触发器]
    Cron --> 任务[执行预设任务]
    任务 --> 结果[把结果发给 AI]

八、第五阶段：团队协作

s15 Agent Teams：多个 AI 一起干活

一个 AI 干不完的大项目，可以叫一群 AI 一起干。每个 AI 有自己的身份和“收件箱”（mailbox）。

它们通过 JSONL 文件收发消息：

{"from": "leader", "to": "alice", "content": "你去写登录页面"}
{"from": "alice", "to": "leader", "content": "我做好了"}

每行一条消息，追加写入，像写日记一样简单。

s16 Team Protocols：队友之间要讲规矩

多人协作不能乱说话。Claude Code 的团队协议规定：

每个重要请求都要带一个 request_id（像快递单号）；
回复时要引用同一个 request_id；
请求状态是 pending（等待中）、approved（同意）或 rejected（拒绝）。

这样就不会搞混谁同意了什么。

s17 Autonomous Agents：AI 自己会找活干

更高级的团队里，AI 不需要等领导分配任务。它会自己去看任务板，认领还没人做的、并且前置条件满足的任务。

如果 60 秒没活干，它就自动“下班关机”。

s18 Worktree Isolation：各干各的，不打架

两个 AI 同时改同一个文件，会互相覆盖。Claude Code 用 git worktree 给每个任务一个独立目录和独立分支：

任务 A → 目录 auth-refactor/ → 分支 wt/auth-refactor
任务 B → 目录 ui-login/     → 分支 wt/ui-login

大家互不干扰，最后再把代码合并。

九、第六阶段：扩展组装

s19 MCP Plugin：不够用时，插更多工具

MCP 是“模型上下文协议”。你可以把它理解成“USB 接口”：

Claude Code 本身带了一些工具；
如果你需要连数据库、查浏览器、操作 Slack，可以通过 MCP 插进来；
这些外部工具和自带工具一样，AI 都能调用。

flowchart LR
    Claude["Claude Code"] --> MCP["MCP 接口"]
    MCP --> 数据库["数据库工具"]
    MCP --> 浏览器["浏览器工具"]
    MCP --> Slack["Slack 工具"]
    数据库 -->|结果| Claude
    浏览器 -->|结果| Claude
    Slack -->|结果| Claude

s20 Comprehensive Agent：把所有东西拼起来

最后一节课，就是把前面 19 节课的所有机制都装进同一个循环里：

一个循环 + 工具 + 权限 + 钩子 + 计划 + 子代理 + 技能 + 记忆 + 压缩 + 任务图 + 后台任务 + Cron + 团队 + 自治 + Worktree + MCP = 完整的 Claude Code

听起来很多，但你已经一个个看过了。它们都是围绕最初那个简单循环加上的“配件”。

十、给新手的 5 个开发小技巧

这些技巧来自 Claude Code 的源码，平时写程序也能用到。

1. 用“查表”代替一堆 if/else

# 不推荐
if name == "read": read_file()
elif name == "write": write_file()

# 推荐
HANDLERS = {"read": read_file, "write": write_file}
HANDLERS[name]()

加新功能只要加一行。

2. 修改列表要小心

如果你想在一个函数里修改外面的列表，要用切片赋值：

messages[:] = new_list  # 正确：改原来的列表
# messages = new_list   # 错误：只是让局部变量指向新列表

3. 用 `**kwargs` 接受任意参数

def handler(**kw):
    print(kw["path"])

handler(path="main.py", limit=10)

(**kw) 表示“不管什么参数名，都装进字典 kw 里”。

4. 守护线程做后台任务

import threading

t = threading.Thread(target=download_file, daemon=True)
t.start()

主程序退出时，守护线程会自动结束，不会卡住。

5. JSONL 比 JSON 更适合追加写入

# 写：每行一条
with open("inbox.jsonl", "a") as f:
    f.write(json.dumps(msg) + "\n")

# 读：逐行解析
for line in open("inbox.jsonl"):
    msg = json.loads(line)

追加写入很安全，不会因为同时写入而损坏文件。

十一、总结

Claude Code 看起来很厉害，但它的核心其实非常朴素：

一个 while 循环 + 一张工具表 + 一个会说话的 AI。

真正让它变强的，是围绕这个循环一层层加上的“配件”：权限、计划、子代理、技能、记忆、压缩、任务图、后台任务、团队、自治、目录隔离、MCP……

这些配件都是为了解决一个核心问题：

怎么让一个只会说话的 AI，真正能在现实世界里连续、安全、高效地干活。

理解了这个骨架之后，你再回头看 Claude Code，就不会觉得它是黑魔法了。它就是一个被精心设计的“机器人工作台”，而我们看到的聪明，来自那个会思考的大脑，加上一套会执行的 harness。

大脑负责想，工作台负责做。把工作台造好，大脑就能发挥全部实力。

本文是学习 shareAI-lab/learn-claude-code 的笔记整理。如果你想动手，可以从 s01_agent_loop/code.py 开始，一课一课跟着做。

《AI 工程》学习笔记（下）：RAG、Agent、微调、推理优化与应用架构

Sat, 13 Dec 2025 14:00:00 +0800

《AI 工程》学习笔记（下）：RAG、Agent、微调、推理优化与应用架构

这是 Chip Huyen《AI 工程》读书笔记的下篇，覆盖第 6-10 章。上篇讲了基础模型、评估和提示工程（见《AI 工程》学习笔记（上）），这篇进入"重型"话题：RAG、Agent、微调、数据工程、推理优化，最后收拢到完整的应用架构。

如果说上篇的主题是"怎么知道模型干得好不好"，下篇的主题就是"怎么让它在真实世界里又快又稳地干活"。

一、RAG：先检索，后生成

1.1 为什么 RAG 是第一个要掌握的模式

模型的知识有两个硬限制：上下文窗口装不下（整个代码库、几百本书），以及训练截止后的事情不知道。RAG（检索增强生成）用"开卷考试"的思路同时解决两个问题：

flowchart LR
    subgraph 离线["离线索引（写路径）"]
        DOC[文档库] --> CHUNK[切分 Chunking]
        CHUNK --> EMB[Embedding 向量化]
        EMB --> VDB[(向量数据库<br/>+ BM25 倒排索引)]
    end
    subgraph 在线["在线查询（读路径）"]
        Q[用户问题] --> QE[查询向量化]
        QE --> RET[检索<br/>top-k 相关片段]
        RET --> RER[可选: 重排序 Rerank]
        RER --> GEN["LLM 生成<br/>问题 + 检索片段 → 回答"]
    end
    VDB --> RET

作者的一个重要判断：RAG 系统的成败在检索器，不在生成器。检索不到正确材料，生成模型只能"基于错误的证据一本正经地编"。上篇那个合同审查案例就是活例子。

1.2 两派检索算法

	词项检索（BM25/Elasticsearch）	向量检索（Embedding）
原理	词面匹配 + 词频统计	语义相似度
强项	精确词命中（型号、ID、专有名词）、轻量、可解释	同义改写、跨语言、模糊查询
弱项	“汽车"搜不到"轿车”	精确 ID 反而可能搜偏
成本	极低	索引/查询都要算 embedding

实战结论是混合检索（hybrid search）：BM25 和向量检索各跑一遍，按 RRF（Reciprocal Rank Fusion）之类的方法融合排序。词项检索是非常强的 baseline，书里的建议是先用 BM25 起步，验证检索确实是瓶颈后再上向量检索，而不是反过来。

1.3 踩坑记录

踩坑 1：chunk 一刀切。 按固定 500 token 切分，把表格拦腰切断、把"问题"和"答案"切进不同 chunk，检索回来全是语义残缺的碎片。改法：按文档结构切（标题层级、段落边界），代码按函数/类边界切，表格整存。chunk 之间留 10%-20% 重叠（overlap），缓解边界处上下文丢失。

踩坑 2：只评估端到端，不看召回率。 RAG 至少要分开盯两个指标：检索的 top-k 召回率（正确片段在不在结果里）和生成的忠实度（回答有没有超出检索内容瞎编）。前者低改检索，后者低改 prompt 或模型——混为一谈就会像无头苍蝇。

踩坑 3：元数据过滤用晚了。 知识库里混着 2020 年和 2025 年的制度文档，用户问"年假几天"，检索回来旧制度。给 chunk 打上时间、部门、文档类型等元数据，检索时先过滤再排序，比换更大的 embedding 模型有效得多。

成功案例：我们给一个内部知识库做问答，初期纯向量检索，员工搜报销系统名称"易快报"时召回很差（专有名词语义模糊）。加上 BM25 混合检索后这类 query 的召回率从 61% 提到 93%，整体满意度显著提升。教训：语义检索不是万能升级，词面匹配在专有名词场景不可替代。

二、Agent：让模型当规划者

2.1 从 RAG 到 Agent：一脉相承

书里有个很妙的视角：RAG 是 Agent 的特例——检索器只是模型可用的一件工具。推而广之，给模型配上更多工具（搜索、计算器、数据库、代码执行、API），让它自己规划"先做什么、再做什么"，就成了 Agent。

flowchart TB
    GOAL[任务目标] --> PLAN["规划 Planning<br/>模型分解任务、生成步骤"]
    PLAN --> ACT["执行 Action<br/>调用工具"]
    ACT --> OBS["观察 Observation<br/>读取工具返回"]
    OBS --> REFLECT{"反思 Reflection<br/>结果对吗？目标达成了吗？"}
    REFLECT -- 继续 --> PLAN
    REFLECT -- 完成 --> OUT[最终输出]
    subgraph MEM["记忆系统 Memory"]
        M1[短期: 对话/执行历史]
        M2[长期: 向量库/知识库]
    end
    PLAN -.读取/写入.-> MEM

Agent 由三要素定义：环境（它感知和操作的世界）、工具（它能调用的动作集）、规划能力（模型分析任务、选路径的脑力）。规划是瓶颈——复杂任务需要多步推理，模型的规划能力决定了 Agent 的上限，所以 Agent 类应用对模型能力最敏感。

2.2 失败模式与工程约束

书里对 Agent 的警告很直接：自动化程度越高，失败越灾难性。典型失败模式：

规划错误：任务分解就错了，后面越努力越离谱；
工具调用错误：参数编错、调错工具、幻觉出不存在的 API；
循环失控：反复重试同一个失败动作，token 烧光任务没进展；
复合错误：单步准确率 95% 看着不错，10 步下来整体成功率只有 0.95¹⁰ ≈ 60%。

对应的工程约束（都是血泪换来的常识）：

# 1. 硬性步数上限，防止失控循环
MAX_STEPS = 15

# 2. 每次循环检查预算（步数/token/钱）
for step in range(MAX_STEPS):
    if budget.exceeded():
        return fallback_answer("任务超出预算，转人工处理")
    action = plan_next(state)
    result = execute(action)
    state.update(action, result)

# 3. 不可逆操作（发邮件、删数据、支付）必须人工确认
if action.risk_level == "high":
    require_human_approval(action)

失败案例：某团队的客服 Agent 有"查询订单"和"退款"两个工具。一次上游 LLM 提供商抖动了几次超时，Agent 把超时误判为"查询失败"，触发了它的兜底逻辑——居然直接走了"退款"流程安抚用户。一晚上误退几十单。教训有三：工具的失败语义要精确（超时 ≠ 业务失败）、写操作必须和读操作分级管理、Agent 的所有写操作要留可审计日志。

感悟：Agent 的工程本质是"给概率系统装刹车"。演示 Demo 里 Agent 行云流水，是因为 Demo 只跑了成功路径。生产化的工作量 80% 在失败路径上。

三、微调：什么时候才轮到你上场

3.1 微调 vs RAG：决策树

这是被问得最多的问题，书里给的思路可以画成决策树：

flowchart TB
    Q1{"模型缺的是<br/>知识还是行为？"}
    Q1 -- "缺知识<br/>（不知道你公司的产品、最新政策）" --> RAG["选 RAG<br/>知识更新快、可溯源"]
    Q1 -- "缺行为<br/>（知识够，但格式/风格/领域表达不对）" --> Q2{"提示工程 + few-shot<br/>能教会吗？"}
    Q2 -- 能 --> PE["停在提示工程<br/>最便宜、迭代最快"]
    Q2 -- 不能 --> FT["微调 Finetuning"]
    Q1 -- "都缺" --> BOTH["RAG + 微调组合<br/>常见的企业方案"]

一句话记忆：RAG 给模型"资料"，微调教模型"习惯"。需要频繁更新的知识走 RAG（改数据库就行）；稳定的领域行为（医疗报告的书写规范、固定输出格式）走微调。

不微调的理由同样重要：微调需要高质量标注数据（最难的部分）、引入模型管理复杂度、基础模型升级后可能要重训、还可能损害模型的通用能力（灾难性遗忘）。

3.2 PEFT 与 LoRA：微调的平民化

全参数微调动辄几百 GB 显存，普通团队玩不起。于是有了一类叫 PEFT（Parameter-Efficient Fine-Tuning，参数高效微调） 的技术：共同思路是冻结绝大部分原模型权重，只训练一小撮新增或挑选出来的参数。家族成员包括 Adapter（在层间插小模块）、Prefix/Prompt Tuning（只学一段可训练的"软提示"向量）等，其中目前最主流、事实标准的是 LoRA。

LoRA（Low-Rank Adaptation）的思路是：冻结原模型权重，只训练一对低秩矩阵来近似权重的变化量 ΔW ≈ A·B：

flowchart LR
    X[输入 x] --> W["原始权重 W<br/>（冻结，不训练）"]
    X --> A["低秩矩阵 A<br/>（可训练）"]
    A --> B["低秩矩阵 B<br/>（可训练）"]
    W --> SUM((+))
    B --> SUM
    SUM --> Y[输出 y = Wx + BAx]

好处实打实：

可训练参数量降到 0.1%-1%，显存需求砍掉一个数量级；
模块化：一个基础模型可以挂多个 LoRA"插件"——客服一个、营销一个，推理时按需加载，不用每个场景部署一份完整模型；
推理时可以把 LoRA 权重合并回主干，零额外延迟。

踩坑 4：LoRA rank 不是越大越好。 新手直觉是 rank 越大容量越大，但数据量撑不住时，大 rank 只会过拟合得更快。常见起点是 rank=8-16，配合几百到几千条高质量数据，往往比 rank=128 + 脏数据强。微调的效果上限在数据质量，不在参数量——这直接引出了下一章。

3.3 LoRA 的数学原理：手算一遍就懂了

① 前向传播的公式。 设原始权重 $W \in \mathbb{R}^{d \times d}$（冻结），LoRA 用一对小矩阵乘积来近似权重的变化量：

$$ \Delta W = BA, \quad B \in \mathbb{R}^{d \times r},\ A \in \mathbb{R}^{r \times d},\ r \ll d $$

前向计算变成：

$$ y = Wx + BAx = (W + BA)x $$

参数量对比一目了然：全参数微调要学 $d^2$ 个数（$d=4096$ 时约 1677 万）；LoRA 只学 $2dr$ 个（$d=4096, r=16$ 时约 13.1 万，占 0.8%）。省显存的真正大头其实不在参数本身，而在优化器状态：冻结的 $W$ 没有梯度，Adam 也就不必为它存两份和权重一样大的动量张量——全参数微调时那才是真正吃显存的部分。

② 为什么"低秩"够用。 直觉是：预训练已经把模型放在了一个很好的解附近，微调只需要在少数几个方向上做修正，而不是对 $d^2$ 维空间做任意改动。LoRA 论文的实验支持这一点——权重增量的内在秩（intrinsic rank）很低，rank 取 1、2 在很多任务上就能接近全参数微调的效果。$r$ 就是"允许修改的子空间维数"：$r=1$ 时 $\Delta W$ 的所有列都是 $B$ 的倍数，只能表达"沿一个方向拉伸"；$r$ 越大，能表达的修正模式越丰富。

两个工程细节：初始化时 $A$ 用随机高斯、$B$ 全零，这样训练起点 $BA=0$，模型行为和原模型完全一致；实际实现里增量还会乘缩放系数 $\alpha/r$（$\alpha$ 是超参），让换 rank 时不用重调学习率。

③ 手算：一个 $2 \times 2$ 的完整训练步。 取 $d=2, r=1$，冻结权重设为单位阵，输入 $x = [1, 2]^T$，目标输出 $y^* = [0, 0]^T$。假设 $A = [1, 1]$（$1 \times 2$）、$B = [1, 1]^T$（$2 \times 1$），都只有 2 个可训练参数：

$$ W = \begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}, \quad A = \begin{bmatrix} 1 & 1 \end{bmatrix}, \quad B = \begin{bmatrix} 1 \\ 1 \end{bmatrix} $$

前向：先算 $A$ 再算 $B$（注意顺序，别先乘出 $\Delta W$，那是 $d \times d$ 的大矩阵，先算 $Ax$ 只需 $O(dr)$）：

$$ Ax = 1 \times 1 + 1 \times 2 = 3, \quad BAx = B \cdot 3 = \begin{bmatrix} 3 \\ 3 \end{bmatrix}, \quad y = Wx + BAx = \begin{bmatrix} 1 \\ 2 \end{bmatrix} + \begin{bmatrix} 3 \\ 3 \end{bmatrix} = \begin{bmatrix} 4 \\ 5 \end{bmatrix} $$

损失：$L = \frac{1}{2} |y - y^*|^2 = \frac{1}{2}(4^2 + 5^2) = 20.5$。

反向：令 $g = y - y^* = [4, 5]^T$，即 $\partial L / \partial y$。梯度沿链路只流向 $A$ 和 $B$，$W$ 不参与：

$$ \frac{\partial L}{\partial A} = B^T g \cdot x^T = \big([1,1] \cdot [4,5]^T\big) \cdot [1,2] = 9 \times [1, 2] = \begin{bmatrix} 9 & 18 \end{bmatrix} $$

$$ \frac{\partial L}{\partial B} = g \cdot (Ax) = \begin{bmatrix} 4 \\ 5 \end{bmatrix} \times 3 = \begin{bmatrix} 12 \\ 15 \end{bmatrix} $$

更新（学习率 $\eta = 0.1$）：

$$ A_{\text{new}} = \begin{bmatrix} 1 & 1 \end{bmatrix} - 0.1 \begin{bmatrix} 9 & 18 \end{bmatrix} = \begin{bmatrix} 0.1 & -0.8 \end{bmatrix}, \quad B_{\text{new}} = \begin{bmatrix} 1 \\ 1 \end{bmatrix} - 0.1 \begin{bmatrix} 12 \\ 15 \end{bmatrix} = \begin{bmatrix} -0.2 \\ -0.5 \end{bmatrix} $$

再走一遍前向验证：

$$ A_{\text{new}}x = 0.1 \times 1 + (-0.8) \times 2 = -1.5, \quad B_{\text{new}}A_{\text{new}}x = \begin{bmatrix} -0.2 \\ -0.5 \end{bmatrix} \times (-1.5) = \begin{bmatrix} 0.3 \\ 0.75 \end{bmatrix}, \quad y_{\text{new}} = \begin{bmatrix} 1.3 \\ 2.75 \end{bmatrix} $$

新损失 $L_{\text{new}} = \frac{1}{2}(1.3^2 + 2.75^2) \approx 4.63$。一步梯度下降，损失从 20.5 降到 4.63，全程没碰过 $W$ 的一个元素——这就是 LoRA 训练的全部。

④ 推理时合并。 部署时把增量并回主干：

$$ \Delta W = B_{\text{new}}A_{\text{new}} = \begin{bmatrix} -0.2 \\ -0.5 \end{bmatrix} \begin{bmatrix} 0.1 & -0.8 \end{bmatrix} = \begin{bmatrix} -0.02 & 0.16 \\ -0.05 & 0.4 \end{bmatrix}, \quad W_{\text{merged}} = W + \Delta W = \begin{bmatrix} 0.98 & 0.16 \\ -0.05 & 1.4 \end{bmatrix} $$

验证：$W_{\text{merged}} x = [0.98 + 0.32,\ -0.05 + 2.8]^T = [1.3,\ 2.75]^T$，和上面分开算的结果完全一致。合并后就是一个普通矩阵乘法，零额外推理延迟就是这么来的。

（这个玩具例子里 LoRA 是 4 个参数、全参数也是 4 个，省不了——节省只在 $r \ll d$ 的大矩阵上出现。）

四、数据工程：质量、覆盖、数量

第 8 章是全书最"脏活累活"的一章，也是我最推荐反复读的一章。数据集设计三准则：

flowchart TB
    D[数据集三准则] --> Q["质量 Quality<br/>标注准确、格式一致、无噪声"]
    D --> C["覆盖 Coverage<br/>覆盖真实场景的多样性<br/>含边界情况和失败样例"]
    D --> N["数量 Quantity<br/>够用即可，边际收益递减"]
    Q -.->|"少量高质量 > 大量噪声"| LESSON["核心教训"]
    C -.-> LESSON
    N -.-> LESSON

几个反直觉的要点：

少量高质量数据胜过大量噪声数据。LIMA 等研究表明，1000 条精心策划的指令数据可以让模型行为对齐得相当好；
合成数据是主力补给，但必须评估。用大模型生成训练数据已经是标准操作（比如用 GPT-4 造指令数据微调小模型，即蒸馏），但"AI 生成的数据"和"AI 生成的内容"一样需要评估把关。人们更倾向于使用自己能可靠评估的合成数据；
最难的不是标注，是写标注规范。“什么叫好答案"没想清楚的团队，标注出来的数据就是标注员个人偏好的大杂烩。

踩坑 5：合成数据近亲繁殖。 用模型 A 生成数据训练模型 B，再用 B 生成数据训练 C…… 几轮下来多样性塌陷，模型只会说"AI 腔”。书外研究（model collapse）也印证了这点。对策：合成数据里持续掺真实数据、定期用多样性指标（如 n-gram 去重率）体检。

成功案例：一个做 SQL 生成的朋友团队，微调数据从"网上爬的 5 万条 SQL 问答"换成"自己业务库表结构 + 人工审核的 3000 条"，效果反而大幅提升。爬虫数据里大量通用示例和他们的业务 schema 无关甚至冲突。覆盖你的真实分布，比堆量重要得多。

五、推理优化：先懂指标，再谈优化

5.1 延迟的两段式结构

自回归生成决定了延迟不是单一数字：

sequenceDiagram
    participant U as 用户
    participant S as 推理服务
    U->>S: 发送 prompt
    S->>S: Prefill 预填充阶段<br/>并行处理全部输入 token
    S-->>U: 第一个 token (TTFT)
    loop Decode 解码阶段（逐 token 串行）
        S-->>U: 第 2, 3, ... N 个 token (间隔 = TPOT)
    end

TTFT（Time To First Token）：首 token 延迟，由 prefill 阶段决定。长 prompt 的应用（塞了一大段检索内容的 RAG）TTFT 高；
TPOT（Time Per Output Token）：每个输出 token 的间隔，由 decode 阶段决定。长输出的应用（写报告）对 TPOT 敏感；
吞吐量和延迟存在权衡：batch 开大吞吐高、单价低，但单请求延迟上升。

实战含义：流式输出（streaming）是最便宜的"延迟优化"——总时长没变，但用户感知延迟从"整个生成时间"变成了 TTFT。聊天场景不流式输出基本不可接受。

5.2 优化手段地图

flowchart TB
    OPT[推理优化] --> MO["模型级优化<br/>（会改变模型本身）"]
    OPT --> SO["服务级优化<br/>（模型不动，改服务方式）"]
    MO --> Q[量化 Quantization<br/>FP16→INT8/INT4，省显存提速]
    MO --> D[蒸馏 Distillation<br/>大模型教小模型]
    MO --> KV[KV Cache 管理<br/>注意力机制优化]
    SO --> B[连续批处理<br/>Continuous Batching]
    SO --> PC[Prompt 缓存<br/>相同前缀不重算]
    SO --> P[并行策略<br/>张量并行 / 副本并行]
    SO --> PD[Prefill/Decode 分离部署]

对应用开发者（主要用 API 的人）最相关的两条：

① Prompt 缓存（prompt caching）。多轮对话或固定长 system prompt 的场景，重复的前缀不用重复算，省钱省延迟。Anthropic/OpenAI 的 API 都已支持，但要注意缓存按前缀匹配——把变化的内容（时间戳、用户问题）放在 prompt 尾部，稳定内容放头部，否则缓存命中率是零。

踩坑 6：我们就犯过这个错——system prompt 开头嵌了当前时间，每请求都变，prompt cache 从没命中过。把动态部分挪到末尾后，长 system prompt 场景的成本降了约 40%。

② 量化是性价比之王。书里总结"跨场景最有效的技术通常是量化"——INT8 几乎无损，INT4 轻微掉点但显存减半以上。自托管时先用上量化再谈别的。

六、收拢：完整的 AI 应用架构

第 10 章把前面所有技术拼成一张图。一个生产级生成式 AI 应用的典型架构：

flowchart TB
    U[用户] --> GW["模型网关 Model Gateway<br/>认证 / 限流 / 路由 / 审计"]
    GW --> GR1["输入护栏<br/>注入检测 / 敏感词 / PII 脱敏"]
    GR1 --> CTX["上下文增强<br/>RAG 检索 / 记忆 / 用户画像"]
    CTX --> CACHE{"缓存命中？"}
    CACHE -- 是 --> RESP
    CACHE -- 否 --> ROUTER["模型路由<br/>简单问题→小模型<br/>复杂问题→大模型"]
    ROUTER --> LLM[基础模型<br/>+ LoRA 插件]
    LLM --> GR2["输出护栏<br/>事实核查 / 格式校验 / 安全过滤"]
    GR2 --> RESP[响应]
    RESP --> FB["用户反馈采集<br/>点赞/点踩/会话信号"]
    FB --> OBS["可观测平台<br/>指标 / 告警 / 追溯"]
    OBS -.数据飞轮.-> CTX

这张图是按"增量搭建"的顺序理解的——作者的 step-by-step 思路非常实用：

先增强上下文（RAG/记忆），解决"模型不知道"；
加护栏，解决"模型乱说"，护栏可以在输入侧、输出侧，或独立服务；
加网关和路由，解决"多模型管理"：简单 query 走便宜小模型，复杂的走大模型，省钱；
加缓存降延迟降成本；
最后才加 Agent 模式，解决"模型不会做"——这是复杂度最高的一步，放最后。

6.1 可观测性与用户反馈

可观测性的核心问题是"理解系统怎么失败的"。LLM 应用的新失败模式（幻觉、注入、格式漂移）要求新指标：除了传统的延迟/错误率，还要跟踪忠实度评分、护栏拦截率、judge 分数趋势、token 成本曲线。日志里要存完整的 prompt 和上下文，否则 bad case 根本无法复盘。

用户反馈是被工程师系统性低估的金矿。点赞点踩、追问、复制回答、重新生成……这些会话信号是迭代评估集和微调数据的免费来源——这就是数据飞轮：

flowchart LR
    P[产品上线] --> U[用户使用]
    U --> F[反馈信号采集]
    F --> E[回流评估集<br/>发现 bad case]
    E --> I[迭代 prompt/检索/模型]
    I --> P

作者因此说"AI 工程比 ML 工程离产品更近"——反馈机制设计传统上是产品的事，但它是模型改进的数据源头，工程师必须介入。

感悟：这张图最值得记住的不是组件本身，而是搭建顺序。见过太多项目第一天就上 Agent + 多模型路由，结果复杂度爆炸、没人知道错误来自哪一层。每加一个组件，系统能力 +1，但失败模式 +N。够用就好，是 AI 架构的第一美德。

七、思考与感悟（下篇）

检索、工具、微调，本质都是"上下文管理"。 RAG 是把外部知识塞进上下文，工具是把能力塞进上下文，微调是把行为烙进权重。选哪种取决于：变化的频率（天天变→RAG，稳定→微调）、成本（上下文 token 费 vs 训练费）、可靠性要求。
复杂度是敌人，按失败模式的"价格"出牌。 每章读完都有一个共同感受：作者永远在问"这个技术的失败模式是什么"。RAG 的失败在检索，Agent 的失败在规划复合错误，微调的失败在数据，judge 的失败在漂移。工程技术选型 = 选择你承受得起的那种失败。
数据飞轮是唯一持久的护城河。 模型会商品化，框架会趋同，但"真实用户反馈 → 评估集 → 迭代"这个循环积累下来的数据和评估体系，别人抄不走。
先把指标立住，再谈优化。 TTFT/TPOT/召回率/忠实度这些指标的意义在于：它们把"感觉变慢了"“感觉变笨了"变成可以定位、可以回归的数字。没有指标体系的优化都是玄学。

八、面试高频题（下篇）

Q1：RAG 和微调怎么选？ 看缺什么：缺知识选 RAG（更新快、可溯源、成本低）；缺行为/格式/风格选微调；都缺就组合。实践顺序：先提示工程，再 RAG，最后微调——按投入产出排序。补充：微调需要高质量标注数据，且可能损害通用能力。

Q2：RAG 效果差，你的排查顺序是什么？ 组件级评估：① 单独测检索召回率——正确片段在不在 top-k；不在则查 chunking、混合检索、元数据过滤、查询改写；② 召回没问题再测生成忠实度——回答是否忠于检索内容；不忠实则改 prompt、加引用约束或换模型。③ 全程保留 bad case 进评估集。

Q3：词项检索和向量检索各自的适用场景？ 词项检索（BM25）：精确匹配强（ID、型号、专有名词）、轻量可解释，但不理解语义；向量检索：同义改写、模糊查询强，但精确词可能搜偏、成本高。生产上常用混合检索 + 融合排序。

Q4：Agent 的单步准确率 95%，为什么 20 步任务成功率不到 40%？怎么改进？ 错误复合：0.95²⁰ ≈ 36%。改进：缩短链路（任务分解更粗粒度）、加反思与自我纠错、关键步骤验证后再继续、步数/预算上限、高风险动作人工确认、提升单步可靠性（更好的工具描述与参数校验）。

Q5：LoRA 的原理是什么？为什么受欢迎？ 冻结原权重，用低秩分解 ΔW≈A·B 学习权重增量，可训练参数降到 1% 量级。优点：显存省一个数量级；数据效率高；模块化——一个基座挂多个 LoRA 插件按需加载；可合并回主干零额外推理开销。

Q6：TTFT 和 TPOT 的区别？各自受什么影响？怎么优化？ TTFT 由 prefill 决定，受 prompt 长度影响——优化：prompt 缓存、压缩上下文、流式输出改善感知；TPOT 由 decode 决定，逐 token 串行——优化：连续批处理、量化、投机解码、更好的硬件利用率。两者存在吞吐-延迟权衡。

Q7：怎么设计一个 AI 应用的护栏体系？ 分层：输入护栏（注入检测、PII 脱敏、话题边界）、生成约束（结构化输出、引用检索内容）、输出护栏（事实核查、安全过滤、格式校验）、动作护栏（工具最小权限、高危操作人工确认）。护栏可放在网关、推理服务或独立组件，关键指标是拦截率和误杀率。

Q8：模型网关（Model Gateway）解决什么问题？ 统一入口做认证、限流、审计、多模型路由（简单问题走小模型省钱）、故障转移（provider 挂了就切换）、缓存。类比微服务里的 API Gateway——当系统里有多个模型、多个 provider 时，它把横切关注点从业务代码里收走。

全书写在最后

把两篇笔记浓缩成一句话：AI 工程 = 用评估驾驭概率，用上下文注入知识，用架构吸收失败。

这本书值得放在手边反复翻。技术细节会过时（明年 Agent 框架肯定又换了一轮），但书里那些思维框架——组件级评估、失败模式分析、先简单后复杂的搭建顺序、数据飞轮——是长期有效的工程直觉。

LangChain 入门笔记：AI 视频生成实战

Fri, 28 Nov 2025 11:00:00 +0800

LangChain 入门笔记：AI 视频生成实战

最近重新刷了吴恩达和 Harrison Chase 主讲的《LangChain for LLM Application Development》。这门课不长，但把 LangChain 的"为什么存在"讲得很透：它不是让你写更多胶水代码，而是把 LLM 调用、提示工程、上下文管理、工具调用这些重复模式抽象成可组合的组件。这篇文章整理课程里的核心原理，并落到我们最熟悉的 AI 视频生成场景，给出可直接跑的 Demo。

一、LangChain 解决什么问题？

在直接调用 OpenAI / Claude / 国产大模型 API 时，我们通常会写出这样的代码：

import openai

messages = [
    {"role": "system", "content": "你是一位短视频脚本专家。"},
    {"role": "user", "content": "主题是'如何用 LangChain 生成视频脚本'，风格轻松，30 秒左右。"}
]
resp = openai.chat.completions.create(model="gpt-4o", messages=messages)
script = resp.choices[0].message.content

这段代码能跑，但问题很明显：

提示词散落在各处，难以复用和版本管理；
输出是字符串，需要手写解析逻辑；
多轮对话、上下文记忆要自己拼 messages；
一旦涉及"检索素材 → 生成脚本 → 检查合规 → 输出结构化数据"，代码就会迅速膨胀成面条。

LangChain 的核心思想：把 LLM 应用里的常见模式抽象成标准组件，让你像搭积木一样拼装工作流。

可以把它理解成：

LangChain = 模型接口统一层 + 提示模板 + 输出解析 + 记忆 + 链式调用 + 工具/Agent 编排

二、课程核心内容回顾

吴恩达这门课围绕 6 个模块展开，也是 LangChain 最基础的 6 个能力：

模块	作用	视频生成场景映射
Models	统一不同 LLM 的调用接口	切换 GPT-4o / Claude / 国产模型时无需改业务代码
Prompts	模板化管理提示词	脚本生成、分镜描述、标题优化的模板复用
Output Parsers	把自然语言输出转成结构化数据	解析 JSON 分镜、时间轴、素材清单
Memory	维护多轮对话状态	用户反复修改脚本时保留上下文
Chains	把多个 LLM/工具步骤串成链	“主题 → 大纲 → 脚本 → 分镜 → 渲染参数"流水线
Agents	让 LLM 决定调用哪些工具	Agent 自主判断需要检索素材还是生成画面描述

下面逐一看原理和代码。

三、核心组件原理与示例

3.1 Models & Prompts：统一接口与模板复用

LangChain 用 ChatOpenAI、ChatAnthropic 等类封装模型，并用 ChatPromptTemplate 管理提示词模板。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一位短视频脚本专家，擅长把技术概念写成{style}风格的口播脚本。"),
    ("human", "主题是：{topic}，时长控制在{duration}秒，需要{scene_count}个分镜。")
])

messages = prompt.invoke({
    "style": "轻松幽默",
    "topic": "LangChain 如何自动生成视频脚本",
    "duration": 30,
    "scene_count": 3
})

response = llm.invoke(messages)
print(response.content)

好处：

提示词与业务数据解耦，模板可复用、可版本化；
切换模型只需改一行 ChatOpenAI → ChatAnthropic；
支持批量 batch、流式 stream、异步 ainvoke 等高级调用方式。

3.2 Output Parsers：从文本到结构化数据

视频生成流程需要结构化输出，例如：

{
  "scenes": [
    {"time": "0-10s", "narration": "...", "visual": "...", "bgm": "..."}
  ],
  "title": "...",
  "tags": ["..."]
}

LangChain 提供 PydanticOutputParser，让模型按指定 Schema 输出。

from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import PromptTemplate

class Scene(BaseModel):
    time_range: str = Field(description="时间区间，如 0-10s")
    narration: str = Field(description="口播文案")
    visual: str = Field(description="画面描述，用于后续生成图片/视频")
    bgm_mood: str = Field(description="背景音乐情绪")

class VideoScript(BaseModel):
    title: str
    scenes: list[Scene]
    tags: list[str]

parser = PydanticOutputParser(pydantic_object=VideoScript)

prompt = PromptTemplate(
    template="根据主题生成短视频脚本。\n{format_instructions}\n主题：{topic}\n时长：{duration}秒\n",
    input_variables=["topic", "duration"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

chain = prompt | llm | parser
result = chain.invoke({"topic": "LangChain 自动生成短视频", "duration": 30})
print(result.model_dump_json(indent=2))

注意：LLM 不一定 100% 返回合法 JSON，生产环境建议加 RetryOutputParser 或兜底解析。

3.3 Memory：多轮修改不再"失忆”

做视频脚本时，用户常会说：“前面不错，但把第二段改得更口语化一点”。没有记忆，LLM 会从头生成，丢失已确认的片段。

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

memory = ConversationBufferMemory()
conversation = ConversationChain(llm=llm, memory=memory)

conversation.predict(input="帮我写一个 30 秒的 LangChain 短视频脚本")
conversation.predict(input="第二段太正式了，改成口语化一些")
print(memory.load_memory_variables({}))

LangChain 还提供 ConversationBufferWindowMemory（只保留最近 N 轮）、ConversationSummaryMemory（摘要历史）等，适用于长会话场景。

3.4 Chains：把多个步骤串成流水线

视频生成的一个典型链：

主题 → 生成标题 → 生成脚本 → 生成分镜 → 输出结构化渲染参数

用 LCEL（LangChain Expression Language）可以非常直观地表达：

from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 子链 1：生成标题
title_prompt = ChatPromptTemplate.from_template("为'{topic}'写一个 20 字以内的爆款标题")
title_chain = title_prompt | llm | StrOutputParser()

# 子链 2：根据标题和主题生成脚本
script_prompt = ChatPromptTemplate.from_template(
    "标题：{title}\n主题：{topic}\n时长：{duration}秒\n请生成 3 个分镜的脚本。"
)
script_chain = script_prompt | llm | StrOutputParser()

# 组合
full_chain = (
    {"topic": RunnablePassthrough(), "duration": RunnablePassthrough()}
    | RunnablePassthrough.assign(title=title_chain)
    | RunnablePassthrough.assign(script=script_chain)
)

result = full_chain.invoke({"topic": "LangChain 视频生成", "duration": 30})
print(result)

LCEL 的 | 运算符让数据流像 Unix 管道一样清晰，这也是 LangChain 从 0.1 到 0.2/0.3 版本最重要的设计演进。

3.5 RAG：用本地素材库增强脚本生成

做批量短视频时，通常有沉淀的素材库（文案库、分镜库、音乐库）。LangChain 的 RAG 组件可以让模型先检索再生成：

from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain.chains.combine_documents import create_stuff_documents_chain

# 1. 构建向量库
embeddings = OpenAIEmbeddings()
vectorstore = FAISS.from_texts(
    ["分镜案例 1：开头用悬念钩子...", "爆款标题公式：数字+痛点+解决方案..."],
    embedding=embeddings
)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

# 2. 构建 RAG Chain
prompt = ChatPromptTemplate.from_messages([
    ("system", "参考以下素材生成脚本：\n\n{context}"),
    ("human", "主题：{topic}，时长：{duration}秒")
])

rag_chain = create_stuff_documents_chain(llm, prompt) | {
    "topic": lambda x: x["topic"],
    "context": retriever
}

# 实际调用时先检索文档，再塞入 prompt

在方糖猫 AI 短视频平台的工程实现中，我们会把 RAG 检索结果和 LangGraph 状态机结合，实现"检索 → 生成 → 人工审核 → 渲染"的完整闭环。

3.6 Agents：让 LLM 自己决定下一步

当流程不是固定流水线，而是需要动态决策时，Agent 更有优势。例如：

判断用户输入是否需要检索素材库；
根据脚本内容决定调用文生图还是文生视频工具；
调用外部 API 查询热点话题。

from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.tools import tool

@tool
def generate_image(description: str) -> str:
    """根据画面描述生成一张图片，返回图片 URL。"""
    # 实际接入 DALL·E / Midjourney / Stable Diffusion
    return f"https://fake-img.example.com?prompt={description}"

@tool
def generate_video_clip(description: str, duration: int) -> str:
    """根据画面描述生成一段视频片段，返回视频 URL。"""
    return f"https://fake-video.example.com?prompt={description}&duration={duration}"

tools = [generate_image, generate_video_clip]

agent_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一位 AI 视频导演，能调用工具生成图片或视频。"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}")
])

agent = create_openai_tools_agent(llm, tools, agent_prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

agent_executor.invoke({
    "input": "我要一个 30 秒关于 LangChain 的短视频，先出 3 张分镜图，再合成视频。"
})

四、Demo：一个可扩展的"AI 视频脚本生成器"

下面把上面所有组件串起来，做一个最小的可运行 Demo。它的输出是一份结构化脚本，后续可以无缝接到 Remotion、FFmpeg 或视频生成 API。

import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.runnables import RunnablePassthrough
from pydantic import BaseModel, Field

os.environ["OPENAI_API_KEY"] = "your-api-key"

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)

class Scene(BaseModel):
    time_range: str
    narration: str
    visual: str
    tool: str = Field(description="生成该分镜所需工具：image 或 video")

class VideoProject(BaseModel):
    title: str
    target_platform: str
    scenes: list[Scene]

parser = PydanticOutputParser(pydantic_object=VideoProject)

title_chain = (
    ChatPromptTemplate.from_template("为'{topic}'写一个适合{platform}的爆款标题")
    | llm
    | StrOutputParser()
)

script_prompt = ChatPromptTemplate.from_template(
    """为平台"{target_platform}"生成短视频脚本。
{format_instructions}
标题：{title}
主题：{topic}
时长：{duration}秒
要求：每个分镜标注用 image（图片）还是 video（视频片段）生成。
"""
)

script_chain = (
    RunnablePassthrough.assign(title=title_chain)
    | script_prompt.partial(format_instructions=parser.get_format_instructions())
    | llm
    | parser
)

project = script_chain.invoke({
    "topic": "LangChain 如何帮助 AI 视频创作",
    "platform": "抖音",
    "target_platform": "抖音",
    "duration": 30
})

print(project.model_dump_json(indent=2, ensure_ascii=False))

下一步可以扩展的方向：

把 Scene.visual 传给 DALL·E / Stable Diffusion / 可灵 / Pika 生成画面；
用 pydub + gTTS 合成配音，或用 CosyVoice 克隆音色；
用 Remotion 或 MoviePy 把图片、视频、字幕、BGM 合成为成片；
接入 LangGraph 做状态持久化和人工审核节点（参考我之前写的 LangGraph 入门笔记）。

五、分布式场景下的运行方案

当 LangChain 应用从本地脚本走向生产环境，单进程运行肯定不够。AI 视频生成是典型的长链路任务：脚本生成、素材检索、文生图、文生视频、配音、渲染，每一步都可能耗时数秒到数分钟。分布式架构的关键是：让 LangChain 推理层保持无状态，把状态交给任务队列和持久化存储。

关键设计点

LangChain 服务无状态化 不保存用户会话到本地内存，所有上下文通过 state 参数或 Redis 传入。这样任意 Worker 都可以处理任意任务，方便水平扩展。
任务队列解耦 用 Celery、RQ 或自研 Worker 消费 RocketMQ/Redis Stream。一个任务对应一次视频生成链路，失败可以重试，不会阻塞 API 网关。
持久化中间状态 把每个阶段的结果（脚本 JSON、分镜图 URL、视频片段 URL）写入数据库。如果 Worker 崩溃，可以从上一个阶段恢复，而不是从头执行。
LangGraph 的分布式友好性 LangGraph 的 State 天然适合持久化。可以配置 checkpointer 把状态快照到 Redis/Postgres，实现断点续跑：

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

builder = StateGraph(VideoGenState)
# ... 添加节点和边 ...
graph = builder.compile(checkpointer=MemorySaver())

生产环境建议把 MemorySaver 替换为 PostgresSaver 或 RedisSaver，让不同 Worker 共享状态。

六、服务器异常恢复方案

AI 视频生成链路长、依赖多（LLM API、素材库、视频生成服务、对象存储），任何一环抖动都会导致失败。异常恢复不是简单 try/except，而是要从架构层面保证可观测、可重试、可续跑。

1. 分级重试策略

异常类型	处理方式	示例
LLM API 限流 / 超时	指数退避重试 3 次	`tenacity` 或 LangChain 内置 `max_retries`
第三方服务不可用	降级或转人工审核	视频生成失败时返回占位图 + 提示
Worker 进程崩溃	队列自动重发，幂等消费	Celery `acks_late=True`
数据格式错误	进入死信队列，人工处理	JSON 解析失败

LangChain 调用模型时建议统一封装：

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
def invoke_with_retry(chain, inputs):
    return chain.invoke(inputs)

2. 幂等性设计

同一个视频生成任务可能因为网络超时被重复投递。给每个任务分配唯一 task_id，在数据库里记录 PENDING → PROCESSING → SUCCESS/FAILURE 状态。Worker 消费前先看状态，避免重复执行。

def process_video_task(task_id: str, inputs: dict):
    if db.get_status(task_id) in ("SUCCESS", "PROCESSING"):
        return db.get_result(task_id)

    db.set_status(task_id, "PROCESSING")
    try:
        result = video_chain.invoke(inputs)
        db.set_status(task_id, "SUCCESS", result=result)
        return result
    except Exception as e:
        db.set_status(task_id, "FAILURE", error=str(e))
        raise

3. 死信队列（DLQ）

重试仍然失败的任务进入死信队列，由告警系统通知运维或产品人员处理。DLQ 里的任务可以手动重跑、补数据或退款。

4. 状态快照与断点续跑

结合 LangGraph 的 checkpointer，每个节点执行完后自动保存状态。Worker 重启后，可以根据 thread_id 恢复到最近的 checkpoint：

config = {"configurable": {"thread_id": task_id}}
# 首次执行
graph.invoke(initial_state, config=config)

# Worker 重启后继续执行
state = graph.get_state(config)
graph.invoke(None, config=config)  # 从 checkpoint 继续

七、如何实现高并发

AI 视频生成场景的高并发，核心矛盾是：LLM API 调用有速率限制，但用户请求可能突增。不能简单堆机器，需要把 IO 等待和计算分离。

1. 异步调用释放线程

LangChain 支持 ainvoke、abatch、astream，配合 asyncio 可以大幅提升吞吐：

import asyncio

async def batch_generate(tasks):
    results = await script_chain.abatch(tasks)
    return results

# 并发处理 20 个脚本生成请求
tasks = [{"topic": t, "duration": 30} for t in topic_list]
results = asyncio.run(batch_generate(tasks))

注意：底层 HTTP 客户端（如 httpx）需要配置连接池，避免每次请求新建连接。

2. 流式响应降低首字节延迟

对于长文本生成，使用 astream 把结果逐步返回给用户，避免长时间阻塞：

async for chunk in chain.astream({"topic": "LangChain 高并发"}):
    print(chunk, end="", flush=True)

3. 限流与背压

模型侧限流：根据 OpenAI/Claude 的 RPM/TPM 限制，用令牌桶算法控制请求速率。
队列侧背压：当队列堆积超过阈值时，API 网关返回 429 Too Many Requests，保护下游 Worker。

import asyncio
from asyncio import Semaphore

sem = Semaphore(10)  # 同时最多 10 个 LLM 调用

async def limited_invoke(inputs):
    async with sem:
        return await chain.ainvoke(inputs)

4. 缓存常用结果

很多提示词是重复的（比如热门模板、常见分镜描述）。可以用 Redis 缓存 prompt_hash → result，命中时直接返回，不走 LLM：

import hashlib

def get_cache_key(inputs: dict) -> str:
    return hashlib.sha256(json.dumps(inputs, sort_keys=True).encode()).hexdigest()

key = get_cache_key(inputs)
if cached := redis.get(key):
    return json.loads(cached)

result = chain.invoke(inputs)
redis.setex(key, 3600, json.dumps(result))

5. 水平扩展与资源隔离

CPU 密集型步骤（如 FFmpeg 渲染、图片后处理）放到独立 Worker 池，避免阻塞 LLM 推理线程。
GPU 密集型步骤（如文生视频）单独部署 GPU 节点，通过队列按需调度。
API 网关层用 Nginx/Envoy 做负载均衡，无状态 LangChain 服务可以快速扩容。

八、学完这门课的几点体会

不要神化 LangChain：它本质是高阶胶水，帮你少写重复代码，但不会让模型变得更聪明。复杂的业务逻辑仍然需要自己设计。
优先用 LCEL：新项目中尽量用 Runnable + | 组合链，比旧的 LLMChain、SequentialChain 更灵活、更易调试。
结构化输出是工程关键：视频、电商、客服等场景都需要把 LLM 输出转成 JSON，PydanticOutputParser 是必备技能。
Agent 不是银弹：固定流程用 Chain，动态决策才用 Agent。Agent 调试成本高，要配合观察日志和工具描述优化。

九、参考资源

吴恩达 & Harrison Chase 官方课程：LangChain for LLM Application Development
中文笔记与代码：awesome-LangChain-for-LLM-Application-Development
我之前的相关笔记：LangGraph 入门：给传统工程师的 Agent 状态与编排指南

这篇文章把吴恩达课程的核心内容和我自己在 AI 视频生成项目里的经验做了结合。如果你也在用 LangChain 做视频、口播剪辑或 Agent 工作流，欢迎留言交流。

生成式AI原理与实战（Part 2）学习笔记：提示工程、Agent 与 RAG 的通俗理解

Sat, 08 Nov 2025 15:24:25 +0800

生成式AI原理与实战（Part 2）学习笔记：提示工程、Agent 与 RAG 的通俗理解

这是《生成式AI原理与实战》学习笔记的第二篇。Part 1 聊了 Transformer、Token、Embedding、Attention、KV Cache 这些“底层零件”；Part 2 则进入“怎么用”的层面：怎么写提示词、怎么让模型完成复杂任务、怎么给模型外挂知识库。目标读者仍然是刚接触 AI 的初中级开发者——读完之后，你不需要会训模型，但应该能清楚地说出提示工程、Agent、RAG 这几个热门词到底在解决什么问题。

写在前面：从“调用 API”到“搭一个系统”

如果你只调过 ChatGPT API，可能会觉得大模型就是一个“输入问题、返回答案”的黑盒。但实际做项目时，很快会遇到这些问题：

同样的 prompt，为什么每次回答不一样？
模型怎么老是“一本正经地胡说八道”？
想让模型输出 JSON，它却总带多余解释。
对话轮数多了，模型就忘了用户是谁。
公司私有文档模型不知道，怎么办？

Part 2 的内容，本质上就是回答这些问题。我会把它们分成三块：提示工程（怎么写好 prompt）、Agent（怎么让模型动起来）、RAG（怎么给模型外挂知识）。

一、提示工程：不是写文案，而是设计接口

很多人把提示工程当成“怎么哄 AI 开心”。其实对开发者来说，prompt 更像一个函数签名：输入清楚、输出可控、边界明确。

1.1 两个旋钮：temperature 与 top_p

大模型生成下一个词时，不是“选择概率最高的词”就完事了。它有两个常用的“随机性旋钮”：

temperature：控制采样的“大胆程度”。值越低越保守，接近“只选概率最高的词”；值越高越有创意，容易跳出常规。
top_p（nucleus sampling）：只从累计概率达到一定比例的候选词里挑。比如 top_p=0.9，就只在概率最高的那一小撮词里采样。

flowchart LR
    A[模型输出概率分布] --> B{采样策略}
    B -->|temperature 低| C[集中在高概率词<br/>输出稳定]
    B -->|temperature 高| D[概率被拉平<br/>输出更多样]
    B -->|top_p 小| E[候选池小<br/>更聚焦]
    B -->|top_p 大| F[候选池大<br/>更发散]

不同任务推荐参数如下：

任务类型	temperature	top_p	原因
翻译、摘要、代码	0.2 - 0.5	0.8 - 1.0	需要准确、可重复
创意写作	0.7 - 1.0	0.9 - 1.0	需要多样性和想象力
头脑风暴	0.8 - 1.2	0.9 - 1.0	越跳出常规越好

验证参数好坏的方法：人工看多轮输出是否稳定/有趣；对翻译用 BLEU/ROUGE；对创意任务用 distinct-n 看词汇多样性。

小知识：有些模型 temperature=0 时输出仍不稳定，可能是因为用了**推测解码（Speculative Decoding）**等加速技术，候选生成阶段仍带随机性。

1.2 一个专业提示词长什么样？

把 prompt 当成接口文档来设计，通常包含以下模块：

flowchart TD
    A[角色定义] --> B[任务目标]
    B --> C[输入信息/上下文]
    C --> D[输出格式]
    D --> E[约束条件]
    E --> F[示例]
    F --> G[模型输出]

模块	作用	例子
角色定义	限定语气、专业范围	“你是一位严谨的学术助手。”
任务目标	消除歧义	“请把下面这段话翻译成英文。”
输入信息	限制回答依据	“仅根据以下材料回答。”
输出格式	便于解析	“输出 JSON，包含结论和依据。”
约束条件	降低风险	“不要编造，不知道就说不知道。”
示例	快速对齐预期	给 1-2 个输入输出样例

为什么角色定义很重要？ 大模型在训练时见过无数种文体和身份。明确角色，相当于激活了模型内部对应的知识路径和语气风格，也能让它更谨慎，减少胡说八道的概率。

1.3 怎么减少模型“幻觉”？

幻觉（Hallucination）就是模型一本正经地编造不存在的信息。常用防御手段：

限定信息源：只根据给定材料回答。
强化真实性要求：明确说“不知道就说不知道”。
要求引用依据：让模型说明答案出处。
限制输出格式：用 JSON、表格等结构化输出，减少自由发挥。
低 temperature：减少随机编造。

1.4 怎么防止提示词注入攻击？

提示词注入是指：用户输入里夹带“忽略前面指令、现在执行我的命令”这类内容，试图绕过系统限制。防御思路：

flowchart LR
    A[用户输入] --> B[结构化隔离<br/>JSON/YAML/字段分离]
    B --> C[系统层过滤<br/>正则/规则/小模型守门]
    C --> D[明确指令优先级<br/>禁止修改角色与规则]
    D --> E[函数调用输出<br/>固定 schema]

结构化输入：不要把用户输入直接拼进自然语言 prompt，用 JSON 等格式隔离。
明确边界：系统提示里写明“不可改变角色”。
函数调用：让模型按固定 schema 输出，减少被操控空间。
系统层检测：用规则或小模型识别异常输入（如突然要求“忽略之前指令”）。

1.5 让模型“先思考再回答”：CoT、Self-Consistency、ToT

复杂任务（数学、逻辑、规划）直接要答案，模型容易错。可以先让它把推理过程写出来。

flowchart TD
    subgraph 思维链 CoT
        Q1[问题] --> R1[一步一步推理] --> A1[答案]
    end

    subgraph 自洽性 Self-Consistency
        Q2[问题] --> R2a[采样推理 1]
        Q2 --> R2b[采样推理 2]
        Q2 --> R2c[采样推理 N]
        R2a --> V[投票/多数共识]
        R2b --> V
        R2c --> V
        V --> A2[最终答案]
    end

    subgraph 思维树 ToT
        Q3[问题] --> B1[分支 1]
        Q3 --> B2[分支 2]
        Q3 --> B3[分支 3]
        B1 --> E[评估/回溯]
        B2 --> E
        B3 --> E
        E --> A3[最优答案]
    end

方法	优点	缺点	适用场景
CoT	简单有效，兼容多数模型	可能产生幻觉推理步骤	数学、逻辑题
Self-Consistency	稳定，减少随机波动	计算开销大	精度要求高
ToT	多路径探索，适合长规划	实现复杂	解谜、策略任务
反思 Reflection	可自我纠错	依赖初始回答质量	代码调试、文本润色

1.6 怎么保证输出格式？

明确格式要求：在 prompt 里清楚说明想要的结构。
给 few-shot 示例：1-2 个例子比千言万语管用。
限制随机性：JSON 输出常用 temperature=0。
使用 API 的 JSON Mode / Function Calling：从接口层面约束输出。
后处理校验：用 json.loads() 等工具兜底。

1.7 分类任务怎么保证只输出指定类别？

提示词里写明“只能输出以下类别之一”。
用 API 的 logit_bias 强行禁止非法 token。
Function Calling 限定返回枚举值。

二、Agent：让大模型从“回答问题”到“完成任务”

提示工程解决的是“单次问答怎么做好”；Agent 解决的是“怎么让模型自主完成一个多步骤任务”。

2.1 Agent 的工作循环

一个典型的 Agent 长这样：

flowchart LR
    A[用户任务] --> B[思考 Thought]
    B --> C[行动 Action]
    C --> D[调用工具/搜索/查库]
    D --> E[观察 Observation]
    E --> F{任务完成了吗？}
    F -->|否| B
    F -->|是| G[输出最终答案]

这就是 ReAct 模式的核心：想一步、做一步、看结果、再决定下一步。比如你要做一个“调研 GPT-5 最新消息”的 Agent，它的循环可能是：

分析目标 → 提取关键词。
生成搜索关键词。
调用搜索引擎。
浏览网页，抽取信息。
更新记忆，避免重复搜索。
判断是否需要继续，直到满意。

2.2 多 Agent 协作：一个复杂任务拆给多个“专员”

当任务复杂、提示词过长时，可以把一个 Agent 拆成多个子 Agent：

flowchart LR
    U[用户请求] --> R[Router Agent<br/>识别意图]
    R --> F[航班 Agent]
    R --> H[酒店 Agent]
    R --> I[行程 Agent]
    F --> P[Planner Agent<br/>整合结果]
    H --> P
    I --> P
    P --> O[返回用户]

Router Agent：根据用户意图决定调用谁。
子 Agent：各自处理专业领域。
Planner Agent：汇总输出，生成统一回复。

子 Agent 之间通过共享上下文对象、向量数据库等方式传递信息。

2.3 记忆：模型不会自动记住你

大模型本身没有长期记忆。对话轮数多了，它会“忘”掉 earlier 的关键信息。解决办法：

flowchart TD
    A[历史对话] --> B[滑动窗口<br/>保留最近 N 轮]
    B --> C[摘要压缩<br/>生成关键状态]
    C --> D[外部记忆存储<br/>Redis/向量库]
    D --> E[需要时检索注入 Prompt]

显式重复：把关键信息重新塞进 prompt。
摘要压缩：每 N 轮生成一次对话摘要。
外部存储：用 Redis、向量数据库保存用户画像和历史事件。
KV 缓存持久化：把历史对话的 Key-Value 缓存存起来，下一轮直接复用，减少重复计算和延迟。

2.4 异步工具调用：别让一个慢工具卡住整个对话

如果某个工具（比如查航班 API）要几秒才返回，Agent 不应该傻等。可以：

把工具调用做成异步任务。
给用户一个中间状态回复：“正在查询，请稍等。”
同时处理其他事情，工具返回后再继续。
用请求 ID 追踪每个调用，确保结果能匹配回上下文。

三、RAG：给大模型外接一个“知识库”

大模型训练数据有截止日期，也不会包含你的私有文档。RAG（Retrieval-Augmented Generation，检索增强生成）的思路是：在生成答案前，先从外部知识库检索相关内容，把检索结果作为上下文喂给模型。

3.1 RAG 的基本流程

flowchart LR
    Q[用户问题] --> R[检索模块]
    D[文档库] --> C[文档分块]
    C --> V[向量数据库]
    V --> R
    R --> M[Top-k 相关片段]
    M --> L[大模型]
    Q --> L
    L --> A[带依据的答案]

3.2 为什么要把文档切成块？

直接拿整篇文档做向量，效果不好，原因：

检索精度低：用户只关心其中一两段，整篇文档的向量会被不相关部分稀释。
嵌入模型有长度限制：BERT、MiniLM 等通常只能处理 512 token 左右。
细粒度匹配更好：小片段更容易和查询语义对齐。

但切块也会带来上下文缺失的问题。常用补救方法：

方法	思路	优点	缺点
滑动窗口 + 重叠	相邻块有重叠区域	保留局部上下文	存储冗余
带标题分块	每个块附带章节标题	增强结构感	对无结构文档效果有限
检索时扩展	召回相邻块一起送给模型	上下文完整	需要系统支持
多粒度索引	同时建“摘要级”和“原文级”索引	兼顾梗概与细节	实现复杂

3.3 向量检索不够，还要混合检索和重排序

向量检索擅长“语义相似”，但不擅长“精确关键词匹配”；传统关键词检索（如 BM25）正好反过来。所以生产环境常用混合检索：

flowchart LR
    Q[用户查询] --> A[向量检索<br/>Dense Retrieval]
    Q --> B[关键词检索<br/>BM25/TF-IDF]
    A --> F[候选结果]
    B --> F
    F --> R[Rerank<br/>Cross-Encoder]
    R --> K[Top-k 最相关片段]
    K --> L[大模型生成]

向量检索：找语义相近的文档。
关键词检索：补全精确匹配能力。
Rerank（重排序）：用更强的 Cross-Encoder 模型对召回结果精排。

3.4 为什么查询要改写？

用户提问往往口语化、不完整，直接拿去检索效果差。Query Rewriting 的目标是把问题改写成“更适合嵌入模型的语义表达”。

比如：

原问题：“他出生在哪？”
改写后：“Barack Obama was born in ?”

方法包括：LLM 改写、同义词扩展、模板化改写、指令式嵌入（如 E5 模型的 query: 前缀）。

3.5 检索到冲突或过时的信息怎么办？

检索前：做数据源筛选、时效性过滤。
检索中：多阶段 reranking，提升相关性。
生成前：在 prompt 里加防御性约束，比如“如果来源冲突，请说明”。
生成时：要求模型标注来源，输出可信度分数。
生成后：用一致性校验或外部验证器判断答案是否忠实于来源。

3.6 RAG 的可解释性

想让用户信任答案，最好告诉它“这个答案来自哪”。做法：

保留文档 ID、URL、时间戳。
做生成-来源对齐（Attribution），把生成内容逐句回溯到文档片段。
输出置信度分数：检索相似度、生成概率、验证器分数等。

3.7 多模态 RAG 与长期记忆

RAG 不限于文本。可以扩展到图像、视频：

用 CLIP 等模型把图像、文本映射到统一向量空间。
文档里的图表提取为图像块，保留位置信息。
视频按时间分段，提取关键帧 + ASR 文本。

AI 伴侣、企业知识库这类长期记忆场景，则需要：每日摘要、事件图谱、多层次召回、时间感知检索、经验版本控制（避免新经验覆盖旧经验）。

四、从面试题到工程实践：给初级开发者的建议

先跑通端到端，再优化局部。不要一上来就追求最先进的 reranker 或 Agent 框架，先用最简单的方式验证需求是否成立。
把 prompt 当代码管。纳入 Git，做版本控制，写回归测试。
评估比调参更重要。没有指标，就不知道改进是否有效。
上下文质量 > 上下文长度。塞太多无关信息，反而让模型抓不到重点。
有结构地失败。模型总会出错，关键是在出错时有兜底、有日志、能回滚。

结语

Part 2 的内容从“怎么写 prompt”一路延伸到“怎么搭 Agent、做 RAG”。对初级开发者来说，最重要的不是记住每个参数的具体数值，而是理解这些技术背后的工程思想：

提示工程 = 设计人与模型的接口协议；
Agent = 把单次调用扩展成有状态、有工具、有记忆的循环；
RAG = 用外部知识库补齐模型能力的缺口。

掌握这三块，你就已经能从“会调 API”进阶到“能搭 AI 应用”了。

参考：《生成式AI原理与实战 —— Part 2》