AI 工程 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

Netflix MAPS 笔记：让推荐模型「看见」素材，冷启动就不冷了

Fri, 28 Aug 2026 10:00:00 +0800

Netflix MAPS 笔记：让推荐模型「看见」素材，冷启动就不冷了

原文：MAPS: Netflix’s Multimodal Asset Personalization at Scale 目标读者：做推荐、搜推广或 AI 应用的工程师，尤其是被冷启动、离线线上不一致折磨过的人。阅读目标：搞清楚 Netflix 怎么用多模态向量把素材个性化的冷启动问题「绕」过去，以及那套消融实验和代理任务的方法论为什么值得抄。

〇、问题本身：素材是个不透明的 ID

Netflix 把海报、视频预览这些视觉线索统称为素材（asset），给每个会员挑哪张海报，本身就是一个个性化问题。老模型回答「老标题挑哪张图」回答得很好，但「新标题刚上线怎么办」回答得很差：模型只从历史交互里学习，每张素材在它眼里只是一个不透明的 ID，图里画了什么人、什么色调，它一概看不见。于是新剧上线时素材没有任何历史，只能加大探索流量去「刷数据」，其余时候退回人气启发式——完全不认你的口味。这就是教科书式的冷启动。

原文的解法一句话：让模型看见并听见它要推荐的东西。新素材一到手就有向量，而向量空间已经承载了会员对相似素材的偏好，所以个性化在接近上线的那一刻就能启动，不用等交互慢慢堆出来。

一、海报个性化：让模型看图

做法直接到近乎朴素：用预训练的 CLIP 把每张海报编码成一个 768 维向量，和素材原有的可学习 ID 向量拼接，作为素材的最终表示。就这一个改动。

效果的关键在于迁移：会员对「某位喜剧演员的脸」「某种配色」的偏好，本来写在图片向量空间里而不是绑死在素材 ID 上，所以新剧海报一编码完，这些偏好立刻生效——哪怕这张图从没给任何人展示过。冷启动从盲区变成了「向量空间对此早有意见」。

二、五个模型合成一个

第二个收益更工程化。同一部剧的海报要铺到五个画布上（billboard、vertical-box、horizontal-panel、short-panel、landscape-panel），裁剪比例各不相同。ID 时代的模型不知道这些裁剪图是同一幕戏，信号无法在画布之间流动，于是历史上每个画布各训一个模型，各自承受各自的冷启动。

CLIP 向量对裁剪、缩放、宽高比基本不变，同一幕戏的五个版本映射到几乎同一个向量——壁垒没了，五个模型合成一个，高流量画布学到的偏好立刻灌溉稀疏画布。收益最大的恰恰正是数据最少的画布。

合并带来一个新问题：五个画布的曝光量天差地别，直接按原始计数混训，高流量画布和高频交互类型会淹没一切，本想帮扶的稀疏画布反而最吃亏；手工调权重又换来一堆拍脑袋超参。Netflix 的做法是奖励加权：每条训练样本按其交互类型的长期奖励分（来自 Netflix 既有的长期奖励建模）加权。交互类型在各画布分布不均，按长期价值加权之后，画布配比自动重平衡——画布按「它驱动的交互的长期价值」贡献梯度，而不是按曝光量。没有手工权重，模型优化目标从「最高频的短期动作」换成了「长期会员满意度」。

flowchart TD
    IMG["新海报上线"] --> CLIP["CLIP 图像编码器<br/>输出 768 维向量"]
    ID["素材 ID 向量"] --> CONCAT["拼接成素材表示"]
    CLIP --> CONCAT
    CONCAT --> MODEL["统一模型<br/>五个画布共享"]
    HOT["高流量画布<br/>billboard 等"] -->|"交互信号沿向量空间迁移"| MODEL
    MODEL -->|"长期奖励加权混训"| SPARSE["稀疏画布直接受益<br/>short-panel 等"]
    style MODEL fill:#fff3cd
    style SPARSE fill:#e8f5e9

三、离线评估：IPS 与探索流量

这套结果能信，前提是评估干净。用当前线上策略的日志评估新模型是有偏的：线上策略偏爱某些素材，日志记录的是「策略选了什么」，不是「会员从全集里会选什么」。和线上策略意见不合的新模型会被冤枉——它会挑的曝光在日志里几乎不存在。

Netflix 用一小股随机探索流量做 IPS（逆倾向评分）：随机策略按已知分布在候选素材里采样，倾向分在服务时刻精确记录，而不是事后估计。每条观测按倾向分的倒数加权，被探索流量压稀的曝光得到相应抬升，得到候选策略的无偏奖励估计。原文有句话值得划线：倾向分由构造保证已知而非事后建模，是离线数字能跟踪线上结果的最大单一原因。 候选模型必须在 IPS（相对线上基线的比值）上先赢，才配拿 A/B 流量。

四、消融实验：两个成分缺一不可

「图片向量」和「模型合并」两个想法捆在一起，Netflix 分开消融，对照老的五模型系统：V1 只加图片向量（仍是五个画布模型），V2 只合并（统一模型但纯 ID），V3 两者都要。离线指标上 ±1% 以内不算显著，V1、V2 单独做基本都在噪声带里；线上全平台跑了至少四周的 A/B 给出更清楚的分界线：V1、V2 双双不显著，只有 V3 拿到统计显著的提升——V3 就是今天线上跑的版本。

原因也讲得透：V1 告诉单画布模型素材长什么样，但稀疏画布样本太少，教不会它怎么用这条信息；V2 数据够了，但全是 ID 信号，新素材没有。V3 两者兼有，成熟画布教会共享模型「CLIP 向量如何映射到会员偏好」，这个映射直接迁移到稀疏画布。效果是相乘不是相加——V3 在 short-panel 上的提升（5.691%）超过 V1 与 V2 之和。原文的教训写得很直白：下结论「内容特征没用」之前，先找第二个阻塞因子。

真实考验来自产品侧：Netflix 十年来最大的电视首页改版，让 short-panel 一夜之间成为主战场——即将吃下最多曝光的画布恰好历史数据最少。V3 赶在改版前上线，配合一个月的 holdback A/B，核心发现指标和播放时长双双显著增长，且增幅比稳态消融更大。

五、查询感知的海报排序

浏览时你的长期口味是对的信号，搜索时不是：搜某个演员时你要的是带他的海报，哪怕你的广义口味另有指向。搜索页的意图写在 query 里，海报应当响应它。

因为 CLIP 把文本和图像投进了同一个向量空间，这件事近乎白送：直接算 query 的文本向量与素材图像向量的余弦相似度，和原有个性化分数按权重 α（0 到 1，线上 A/B 调）混合。第一项是「我们认为你喜欢什么」，第二项是「你刚开口要什么」。没有任何额外建模——向量本来就在素材表示里，排序时加一个相似度项而已。

六、视频预览：MediaFM

视频预览比静态图难：吸引力来自运动、节奏、对白、配乐，单帧说不清。第一版内容感知方案 SeqCLIP 只取各帧的 CLIP 向量求平均——看得见长相，听不见声音，而对白和音乐恰恰扛着预览片的大半调性。

补全这块的是 MediaFM，Netflix 第一个自研多模态地基模型，在 8000 万个镜头（shot）上训练，每个镜头融合三路信号成一个向量：视觉走 SeqCLIP，音频走预训练语音音频编码器，文本是字幕经大规模文本模型编码。接入方式和 CLIP 一样：把向量拼进素材表示，不需要新基建。

离线 IPS 和五周全平台 A/B 给出一致的排序：MediaFM ＞ SeqCLIP ＞纯 ID，每加一层内容感知都有收益，TV 端收益最大。音频和定时文本是 SeqCLIP 这类纯视觉编码器够不到的，这部分增量是真的。MediaFM 已作为默认视频预览向量全平台上线。

flowchart LR
    subgraph FM["MediaFM 多模态地基模型<br/>8000 万镜头训练"]
        V["视觉<br/>SeqCLIP 帧向量平均"] --> FUSE["融合成镜头级向量"]
        A["音频<br/>预训练语音音频编码器"] --> FUSE
        T["文本<br/>字幕经大规模文本模型"] --> FUSE
    end
    FUSE --> STORE["Embedding Store<br/>训练与推理同源 无偏斜"]
    STORE --> PROBE["线性探针代理任务<br/>仅凭向量预测去偏人气赢家"]
    PROBE -->|"跑赢随机猜测才放行"| AB["离线 IPS + 线上 A/B<br/>MediaFM ＞ SeqCLIP ＞ 纯 ID"]
    style PROBE fill:#fff3cd

七、便宜地挑向量：线性探针

新向量层出不穷，端到端试验太贵——数据工程、重训、数周 A/B 流量，不可能每个候选都走全程。Netflix 用一个便宜问题把漏斗口收窄：仅凭内容向量，能不能预测一个朴素无个性化策略下哪张素材会赢？

做法：固定一批标题，用探索数据按倾向分去偏后找出每个标题的人气赢家，打成二值标签；然后只用一个线性探针从素材向量恢复这个标签（标准二值交叉熵），不带标题、演员等任何元数据。保持线性和纯向量是刻意的——它隔离出「人气驱动因子有多少真的编码进了向量」。向量若抓住了人气的语义驱动，线性分类器就该能认出赢家；抓不住，探针就和随机猜测一样，而后者正是它的及格线。

这个探针先把一大批候选剪到两个决赛选手（SeqCLIP 和最强 MediaFM 变体），再送全程评估。三条信号——探针准确率、离线 IPS、线上 A/B——对两个选手的排序完全一致，所以现在每个 MediaFM 新版本发布前都得先过探针这一关。

八、Embedding Store：让一切成立的地基

所有向量——CLIP、SeqCLIP、MediaFM——都活在 Netflix Embedding Store 里（Netflix AI Platform 的组件）。地基模型把原始素材编码成向量只做一次，Store 用同一接口喂给所有下游；关键性质是训练时和在线推理时服务的是完全相同的向量，模型学到的和线上见到的之间没有 skew。

另一个性质是解耦：新向量（或老向量的新版本）注册、回填、验证全部独立进行，不碰任何消费方的训练和推理代码，下游靠配置即可启用。CLIP 进海报模型、同一批向量撑起查询感知排序、MediaFM 滚进视频预览模型，各自是独立变更而不是跨团队迁移。下一步目标是把 Store 推向图文视频统一的语义空间，做跨模态检索和跨界面统一排序。

工程实践联想

冷启动的最优解常常是换表示，不是加探索。 探索流量和人气回退都是在「ID 无知」的框架里打补丁；一旦实体有了内容向量，偏好沿向量空间迁移，问题在表示层就消掉了。做实体冷启动（新商品、新文档、新用户）时先问：这个实体有没有一个下游模型读得懂的内容表示。
「特征没用」往往是因为别处先堵着。 V1 的失败不是图片向量没信息，是稀疏画布样本不够教模型用；V2 的失败不是合并不对，是 ID 信号对不上新素材。多因素实验里单变量不显著，先怀疑第二个阻塞因子，别急着枪毙特征。
评估体系的纯度比模型重要。 IPS 能跟踪线上结果，靠的是倾向分在服务时刻由构造已知——日志里事后估出来的倾向分自带一层建模误差。值得为评估专门留一股随机探索流量，这笔钱花在刀刃上。
用廉价代理任务给昂贵实验把关。 线性探针 + 随机基线，成本几乎为零，却和端到端 A/B 给出了一致排序。任何「候选方案多、全量验证贵」的场景（选向量、选特征、选模型结构）都该先架一道这样的探针。
向量服务要当成基础设施来建。 训练推理同源、版本注册回填独立、下游配置即用——这三条让「换向量」从跨团队项目降级为一次配置变更。Embedding Store 这类组件才是多模态落地真正的护城河，模型本身反而不是。

本篇小结

问题：素材个性化的冷启动——老模型把素材当不透明 ID，新素材只能靠探索流量和人气启发式硬扛。
海报：CLIP 768 维向量拼接 ID 向量，偏好沿向量空间即时迁移；五个画布模型合并为一个，混训按交互类型的长期奖励分加权，画布按长期价值而非曝光量贡献。
评估：专门探索流量 + IPS，倾向分服务时刻已知，离线数字才跟得上线上。
消融：V1（仅向量）、V2（仅合并）线上均不显著，V3（两者兼有）显著胜出，short-panel 提升 5.691% 且超过 V1+V2 之和；电视首页改版实战中 holdback A/B 证实收益更大。
搜索：query 文本向量与素材图像向量的余弦相似度，按 α 与个性化分数混合，零额外建模。
视频：MediaFM（8000 万镜头，视觉+音频+文本三模态）＞ SeqCLIP ＞纯 ID，TV 端收益最大，已全平台默认上线。
方法论：线性探针代理任务廉价筛选向量，三条信号排序一致后成为 MediaFM 发版门禁；Embedding Store 保证训练推理同源、解耦上下游。

参考资料

MAPS: Netflix’s Multimodal Asset Personalization at Scale（原文，Netflix TechBlog）。
Radford et al., “Learning Transferable Visual Models From Natural Language Supervision”（CLIP 原始论文，文中海报向量与图文共空间的来源）。
Netflix TechBlog 关于长期奖励建模（long-term reward modeling）与 Netflix AI Platform / Embedding Store 的相关文章（原文内引用，用于奖励加权与向量基础设施）。

LiveTalking 源码解剖：一个开源实时数字人是怎么跑起来的

Thu, 20 Aug 2026 17:30:00 +0800

LiveTalking 源码解剖：一个开源实时数字人是怎么跑起来的

上一篇《数字人链路从 0 到精通》画完了实时数字人的完整链路：耳朵（VAD+ASR）、眼睛（视觉感知）、大脑（LLM+RAG）、嘴巴（TTS）、脸（口型驱动）、神经（WebRTC）。概念图看完了，下一步自然的问题是：真实项目里这条链路长什么样？

这篇解剖 LiveTalking。选它的原因：它在实时数字人开源项目里 star 数排前列，架构足够典型——它把「输出侧」（TTS→口型驱动→WebRTC 推流）做到了工业级，而输入侧和智能侧保持着 demo 形态，正好当「链路完整但交互闭环不完整」的对照样本。读完你会知道一个能跑的数字人项目，哪些部分可以直接抄，哪些部分要自己做。

1. 项目定位与启动

一句话定位：纯 2D 真人克隆口型驱动 + 流式 TTS/LLM 的实时数字人服务端，前端是浏览器。

python app.py --transport webrtc --model wav2lip --avatar_id wav2lip256_avatar1

入口 app.py，HTTP 服务用 aiohttp，默认端口 8010。
配置三级覆盖：命令行 > config.yaml > 默认值（config.py），加上 .env 读密钥，配置管理做得比多数开源 demo 规范。
插件注册表 registry.py 是扩展点：stt / llm / tts / avatar / output 五类插件用装饰器注册，想换实现不用改主流程。
输出模式五种：--transport 可选 webrtc（浏览器 /offer 信令）、whep、rtcpush（WHIP 主动推流到 SRS）、rtmp、virtualcam（虚拟摄像头）。

顶层目录即架构：

flowchart TB
    WEB[web/ 浏览器前端] -->|HTTP /human /offer| SERVER[server/<br/>rtc_manager / session_manager / routes]
    SERVER --> AVATAR[avatars/<br/>base_avatar 渲染管线]
    SERVER --> LLM[llm.py<br/>qwen-plus 单轮对话]
    LLM -->|标点切句| TTS[tts/<br/>11 种 TTS 插件]
    TTS -->|20ms 音频帧| AVATAR
    AVATAR --> OUT[streamout/<br/>webrtc / rtcpush / rtmp / virtualcam]
    OUT --> USER([用户])

2. 输出侧精华一：三种形象驱动方案

概念篇讲过口型驱动有三条路线（3D Blendshape / 真人克隆 / Live2D），LiveTalking 全部押在真人克隆上，提供三个模型可切换，套路一致：离线预处理真人视频（抽帧 + s3fd 人脸检测 + 存坐标），运行时按音频特征只重绘嘴部区域，再贴回原始帧。

方案	音频特征	模型	参考性能
wav2lip	Mel 频谱	256×256	RTX3060 约 60fps
musetalk	Whisper encoder 特征（只提特征，不做识别）	VAE + UNet（fp16）	RTX3080Ti 约 42fps
ultralight	HuBERT 特征	160×160 轻量 UNet	最轻量

三个读源码时要注意的点：

avatars/audio_features/ 目录下的 mel/whisper/hubert 三个提取器名字叫 ASR，但不做语音识别，只是把音频变成模型能吃的特征向量——新人最容易在这里迷路。
帧率固定 25fps，音频 16kHz、每 20ms 一帧，这两个时钟是全管线的节拍器。
README 里提到的 ernerf（NeRF 路线）在当前代码库已移除，别再找它。

3. 输出侧精华二：渲染管线怎么省 GPU

核心在 avatars/base_avatar.py 的 render 循环：四条线程 + 三组队列的流水线。

flowchart LR
    TTS[TTS 线程<br/>合成 20ms 音频帧] --> AQ[音频队列]
    AQ --> FEAT[主循环<br/>提取音频特征]
    FEAT --> FQ[feat_queue]
    FEAT --> OQ[output_queue<br/>音频透传]
    FQ --> INF[inference 线程<br/>批量 GPU 推理]
    INF --> RQ[res_frame_queue]
    RQ --> PROC[process_frames 线程<br/>嘴部贴回原帧]
    OQ --> PROC
    PROC --> OUT[输出层推流]

两个值得抄的设计：

静音时不跑模型推理：检测到静音段直接循环播放原始视频帧，只有说话时才走 GPU。这一个开关把 GPU 占用降了一个量级，是低成本并发的关键。
背压降速：渲染循环检查输出缓冲区积压，积压多了就主动 sleep 降速，防止队列无限膨胀。

另外它还有 idle 待机动作编排：自定义 audiotype 对应预切好的图片序列 + 音频循环播放，沉默时数字人不会「死机」。说话到静音的过渡混合代码存在但默认关闭（enable_transition = False），追求自然度的可以自己打开调。

4. 输出侧精华三：TTS 插件与 RTC 推流

TTS 插件 11 种：edgetts、gpt-sovits、xtts、cosyvoice、fishtts、tencent、doubao、indextts2、azuretts、qwentts、omnitts。统一基类 tts/base_tts.py：队列收文本 → 合成 → 按 20ms chunk 推给渲染管线。注意两个坑：

流式程度不一：gpt-sovits 是真 HTTP 流式，edge-tts 是「流式下载、整句合完再切片下发」的伪流式——首音延迟差很多，选型时实测。
文本切分不在 TTS 层做，由上游 LLM 切好送进来。

RTC 输出用 aiortc 实现，自定义 PlayerStreamTrack 时钟（视频 40ms/90kHz、音频 20ms/16kHz），编解码偏好 H264 优先于 VP8，支持 STUN。五种输出模式覆盖浏览器播放、推 SRS、RTMP 直播、虚拟摄像头进会议软件，输出侧的场景覆盖度是项目最成熟的部分。

5. 耗时分析：从用户说完到数字人开口，时间花在哪

概念篇第 4 节说「每一环都要流式」。拿这个标准量 LiveTalking，结论先行：这是一条「半流式」管线——LLM、特征提取、推流是流式的，ASR 和口型推理是整段/攒批的，两个非流式环节贡献了大部分延迟。

逐环节拆解（耗时依据均来自代码常量与实现方式）：

环节	实现	流式？	耗时特征
ASR 语音识别	SenseVoice 整段识别（`asr_server.py:87-99`）	❌ 非流式	等客户端发「说完了」才把整段 PCM 一次性识别，耗时与音频时长成正比（恒定 RTF）；全局推理锁串行，并发用户互相排队
LLM 首 token	qwen-plus `stream=True`（`llm.py`）	✅ 流式	云 API 首 token 通常几百毫秒
LLM 切句	攒标点且超 10 字才送 TTS（`llm.py:44-49`）	⚠️ 半流式	短回复、无标点回复会憋到最后才出声
TTS 首包	11 种插件差异大	⚠️ 看插件	edge-tts 伪流式：整句合成完才切片下发，首音 ≈ 整句耗时；gpt-sovits/cosyvoice/doubao 真流式：首音 ≈ 首 chunk 到达
音频特征	mel/whisper/hubert 滑窗（`config.py:52-54`）	✅ 但有前瞻	右上下文 `r=10` 意味着必须多等 200ms「未来」音频；启动 warm_up 再加 200ms 相位偏移，合计约 400ms 结构性延迟
口型推理	GPU 批推理（`base_avatar.py:347`）	❌ 攒批	攒满 32 个 20ms chunk（640ms）才触发一次推理出 16 帧；一批推理约 267ms（wav2lip256 @ RTX3060 约 60fps 推算）
画面合成	process_frames 逐帧贴回	✅ 流式	毫秒级，可忽略
WebRTC 发送	aiortc 软件时钟 40ms/帧（`webrtc.py:69-109`）	✅ 流式	发送节奏与渲染解耦，无攒批；节拍 40ms + 网络传输

flowchart LR
    A[用户说完<br/>判停等待] --> B[ASR 整段识别<br/>非流式]
    B --> C[LLM 首 token<br/>流式]
    C --> D[攒句超 10 字<br/>半流式]
    D --> E[TTS 首包<br/>edge 最差]
    E --> F[特征右上下文<br/>+200ms 前瞻]
    F --> G[攒批 640ms<br/>非流式]
    G --> H[GPU 推理一批<br/>约 267ms]
    H --> I[RTC 节拍 40ms<br/>+ 网络传输]
    style B fill:#fee,stroke:#c00
    style G fill:#fee,stroke:#c00

数量级估算（默认组合 wav2lip + edge-tts）：

仅算「TTS 首段音频 → 口型首帧」：200ms 前瞻 + 最多 640ms 攒批 + 一批推理约 267ms + 40ms 发送节拍 ≈ 1.1 秒量级。这期间管线一直在播静音循环帧，用户看到的是「待机」而不是卡死。
再加上 ASR 整段识别（几秒的整段音频、全局锁排队）和 edge-tts 整句合成，端到端「用户说完 → 数字人开口」会到数秒级——这就是它演示效果还行、对话感弱的技术根源。

三个值得记住的点：

固定成本写死在常量里：640ms 攒批来自 batch_size=16（每批吃 32 个 chunk），200ms 前瞻来自 -r 10。做延迟优化最先动这两个数——但 batch_size 调小会降 GPU 吞吐，这是延迟与并发的权衡，不是免费午餐。
假流式要会分辨：edge-tts 的 stream() 是「流式下载、整句合成完才切片」；判断一个 TTS 插件是不是真流式，看首个音频 chunk 是否即时进队列——代码里 sovits/cosyvoice/doubao 都有 Time to first chunk 打点，edge 没有。
打点有但不成链：LLM 首 chunk、TTS 首包、推理 fps（每 100 帧打 actual avg infer fps）、推流 fps、ASR RTF 各有分散日志，但没有端到端统一 trace（无 request-id 串联）。想定位延迟瓶颈得自己加链路追踪，这也是第 8 节工程化缺口里的一项。

6. 输入侧与智能侧：demo 级，别照抄

对照概念篇的链路图，短板集中在上半场：

ASR（耳朵）：server/asr_server.py 用 FunASR 的 SenseVoiceSmall + fsmn-vad，但不是真流式——客户端按 60ms chunk 上行，服务端攒缓冲，收到停止信号才整段识别一次，没有增量 partial 输出。还有一条更糙的路：直接用浏览器 Web Speech API 按住说话。

LLM（大脑）：llm.py 单文件几十行，qwen-plus 流式调用，无多轮历史、无 RAG、无记忆、无工具调用——每次只发一条 user message。文本切句是最简版：扫标点攒够 10 字就 flush，没有概念篇 3.3.1 讲的首句激进策略、超时兜底、标点陷阱清洗。

打断（barge-in）：有 /interrupt_talk 接口，清空 TTS 队列 + 置暂停，但这是前端主动 HTTP 打断，不是 VAD 检测到用户插话自动触发——算半个 barge-in。

视觉感知（眼睛）：完全没有运行时摄像头输入。人脸检测只用于离线建 avatar 素材。

架构上的本质差异：它的 RTC 只发不收——用户音频根本不上行到服务端，ASR 走浏览器侧。这个设计 demo 友好，但意味着服务端做不了 AEC、做不了语义 VAD、打断链路不闭环，是「demo 架构」和「产品架构」的分水岭。

7. 跑通它的坑：安装、模型与素材

源码读得再明白，跑不起来都白搭。下面是从这个项目代码里逐条核实的坑，按严重程度分三级。

7.1 跑不起来级

依赖管理是半成品：

requirements.txt 里没有 torch——必须按 README 手动装指定版本（torch==2.9.1+cu128），直接 pip install -r requirements.txt 后启动必报 No module named 'torch'。
关键依赖（aiortc、librosa、transformers、edge_tts）全不锁版本。aiortc 历年 API 变动大，新环境装到不兼容版本是常见翻车点。
librosa 定时炸弹：avatars/wav2lip/audio.py:18 用了 librosa.output.write_wav，这个 API 在 librosa 0.10 已删除，新版环境下走到该路径直接 AttributeError。
Python 版本三个口径互不一致：README badge 写 3.10+，实测环境是 3.12 + CUDA 12.8，Dockerfile 里还是 3.10 + CUDA 11.3。
funasr/modelscope 在 requirements.txt 里被注释掉了，不手动装的话 /api/asr 静默不注册（只打一行 info 日志），新人会以为 ASR 功能坏了。

模型权重全靠网盘手动摆位，路径还硬编码：

模型	坑
wav2lip	路径硬编码 `./models/wav2lip.pth`（`app.py:148`），README 要求把下载的 `wav2lip256.pth` 手动改名，忘改直接报文件不存在
musetalk	四件套要全部就位：unet + sd-vae + HF transformers 格式的 whisper（不是 OpenAI 权重格式，放错 load 失败）+ face-parse 模型
ultralight	最深的坑：`from_pretrained` 传的是本地路径不会自动拉取；且每个 avatar 需要自己训练的 `ultralight.pth`——`genavatar.py` 末尾只是 `cp` 你在项目外训练好的 checkpoint，训练过程根本不在本仓库。新人选 ultralight 基本必卡
s3fd 人脸检测	首次使用从外网（adrianbulat.com）下载权重，国内/离线环境 genavatar 直接挂

另外默认 TTS 是 edge-tts，依赖微软在线服务，离线或被墙环境无声且无重试（只打日志）。

7.2 avatar 素材制作的坑（genavatar）

输入视频必须 25fps，但代码不校验（config.py:51 注释写着 “must be 25”）。喂 30fps 视频会口型节奏错位，且无任何报错。
人脸检测失败静默兜底：检测不到人脸时直接用整帧坐标（avatars/wav2lip/genavatar.py:107），产出垃圾素材也不报警，要等跑起来看到崩坏画面才知道。
全量帧读进内存：所有 PNG 帧一次性 load 进 RAM 且常驻（wav2lip_avatar.py:81-86），长视频直接撑爆内存，也没有时长上限引导。
抽帧逐帧写 PNG，几分钟 1080p 视频就是几千个文件，磁盘消耗无提示。

7.3 体验受损级（能跑但别扭）

DASHSCOPE_API_KEY 没配置时静默失败（llm.py 只 catch 打日志），前端表现是「数字人就是不说话」，没有任何错误提示。
getUserMedia 需要安全上下文：用 http://<局域网IP>:8010 访问时浏览器禁麦克风，语音功能无声失效，README 没提。
WebRTC 端口要求夸张：README 要求开放 UDP 全端口，且只配 STUN 不配 TURN，严格 NAT 下连接失败无引导。
LLM 切句粗糙：攒够标点且超 10 字才送 TTS，短回复、无标点回复会憋到最后才出声——概念篇 3.3.1 讲的超时兜底这里没有。
wav2lip 嘴部硬贴回：直接 cv2.resize 覆盖矩形区域，无边缘融合（musetalk 才有 mask blending）；说话/静音过渡混合代码存在但默认关闭，帧切换有跳变。

一句话避坑总结：按 README 跑 wav2lip + webrtc + edgetts 默认组合成功率最高；深坑集中在模型权重手动摆位、ultralight 需项目外自训、25fps 与人脸检测失败均无校验这三处。

8. 从 demo 到商业级产品，还差什么

flowchart LR
    subgraph 已有["LiveTalking 已覆盖（工业级）"]
        A1[形象驱动三方案]
        A2[渲染管线 + 省 GPU]
        A3[TTS 插件 + 克隆]
        A4[RTC 五种输出]
        A5[idle 待机]
    end

    subgraph 缺失["到产品还差（要自己造）"]
        B1[RTC 音频上行 + AEC]
        B2[真流式 ASR + 语义 VAD]
        B3[自动 barge-in]
        B4[RAG + 多轮 + 记忆]
        B5[视觉感知]
        B6[测试/CI/鉴权/部署]
    end

    已有 -->|补全后| P[商业级<br/>数字人]
    缺失 --> P

具体缺口清单，按补齐优先级排序：

交互闭环：用户语音走 RTC 上行 → 服务端 AEC + 流式 ASR + 语义 VAD → 自动 barge-in。这是从「能演示」到「能用」的第一刀。
智能：LLM 层接多轮历史 + RAG（概念篇 3.2 节的完整方案），llm.py 只有几十行，改造量小、收益最大。
视觉感知：按概念篇 3.1.3 的方案，端侧轻量模型起步。
工程化与安全：测试、CI、鉴权、部署——当前几乎是空白，见下面的上线隐患清单。

8.1 上线隐患级（想部署公网必须先补的课）

这些问题不影响跑 demo，但每一个都是生产事故的种子：

全无鉴权：/human、/interrupt_talk、/record、/api/admin/*、/sse 全部裸奔；admin 接口直接 vars(opt) 输出全量配置；CORS 是 * 全开。公网部署等于敞开大门。
录制功能用 os.system 拼 ffmpeg 命令（base_avatar.py:285），sessionid 来自外部传入，存在路径注入风险；临时文件落在工作目录，同名会话重录互相覆盖。
GPU 资源不释放：session_manager.remove_session 只 pop 字典，注释里自己留了一句「todo: 还可以主动调 avatar_session 释放」——avatar 素材常驻显存不回收，global_avatars 缓存永不淘汰，频繁换 avatar 会显存泄漏。
GPU 模型全局共享且无锁：每个 session 起独立 inference 线程并发调同一个模型，高并发同时说话时显存峰值不可控，没有任何排队或互斥防护。
线程泄漏风险：inference 线程里 output_queue.get() 无超时阻塞（base_avatar.py:348），TTS 断供时线程永远卡住，shutdown 的 join() 会挂起；LLM 调用走默认 executor 无线程池上限，刷接口可起大量线程。
队列清空不持锁：打断时直接 queue.queue.clear() 操作内部 deque（tts/base_tts.py:31），打断瞬间恰逢 put 有小概率竞态。
Dockerfile 是坏的：CUDA 11.6/torch 1.12 与 README 要求的 torch 2.9.1/cu128 矛盾，且 COPY 路径还是上个项目的名字 nerfstream——这个 Dockerfile 根本 build 不出当前项目。

8.2 文档与代码不一致（宣称 vs 实际）

读这个项目要建立「README 说的是理想、代码才是现实」的警觉：

README 宣称	代码实际
支持 ernerf（附演示视频链接）	ernerf 已移除，`app.py` 只注册 musetalk/wav2lip/ultralight
支持说话被打断	仅 HTTP 主动打断，无语音 barge-in（服务端不收上行音轨）
支持多并发	有限流，但模型共享无锁 + 资源不释放
requirements.txt 列了 Flask	实际用 aiohttp，`app.py` 里的 Flask 代码是死代码
admin API 文档暗示 fps 可配	`config.py` 写死 25，改了整条音视频时钟链都会错位
已在业内广泛商用	无鉴权/无测试/资源不释放，开源代码距离可商用部署有明显差距

9. 源码怎么读：推荐顺序

项目文件不少，按这个顺序读最省力：

app.py + config.py：看启动流程和配置体系，建立全局。
registry.py：十几行的装饰器注册表，理解插件机制后所有模块的可替换性就清楚了。
avatars/base_avatar.py：全文核心，渲染管线的四条线程、静音跳推理、idle 编排都在这。
tts/base_tts.py + 一个具体实现（如 tts/sovits.py）：理解真假流式的差别。
server/webrtc.py：看自定义时钟轨道怎么把音视频帧喂给 WebRTC。
最后回头看 llm.py 和 server/asr_server.py——看清 demo 级实现的边界在哪，正好是练手改造的切入点。

10. 总结

LiveTalking 的价值在于输出侧的真实工程参考：三种驱动方案的取舍、四线程渲染管线、静音跳推理省 GPU、插件化 TTS、五种 RTC 输出——这些在概念文章里只是一句话，在源码里是踩过坑的实现。它的边界也清晰：输入侧和智能侧保持 demo 形态，不是缺陷，是定位。

对学习者，正确的用法是概念篇当地图、这个项目当实地：先知道链路全貌，再在源码里逐个模块对号入座，最后从「补齐缺口清单」里挑一个动手改——比如给 llm.py 接上 RAG 和多轮历史，就是性价比最高的第一个实战任务。

数字人链路从 0 到精通：新人也能看懂的学习总结

Thu, 20 Aug 2026 16:30:00 +0800

数字人链路从 0 到精通：新人也能看懂的学习总结

写这篇文章的动机很实际：数字人（Digital Human）这个方向资料多但碎，新人很容易被各种名词（ASR、TTS、Viseme、Blendshape、WebRTC、中之人、MetaHuman）淹没，看了很多文章还是拼不出一张完整的图。

本文的目标：一篇文章讲清楚数字人是什么、整条技术链路怎么跑、每环有哪些坑、新人按什么顺序学。假设读者有基本编程能力，但不要求任何音视频或图形学背景。

1. 先搞清楚：数字人到底是什么

1.1 从元宇宙说起

2021 年「元宇宙（Metaverse）」概念爆火时，有一个被广泛引用的定义：元宇宙是一个持久在线的、可沉浸交互的虚拟世界。热闹过后概念降温，但它留下了几样真正落地的资产：

虚拟形象（Avatar）：人在虚拟世界里的「身体」，从游戏捏脸到 Meta 的虚拟人，再到苹果的 Persona。
数字身份（Digital Identity）：虚拟世界里的「你是谁」，关联账号、资产、社交关系。
实时渲染与交互引擎：Unity、Unreal（含 MetaHuman）、WebGL 这些让虚拟世界「看得见」的技术。
XR 入口：VR/AR 设备作为进入虚拟世界的「门」。

数字人就是元宇宙沉淀下来最值钱的那部分：一个「有形象、能说话、能交流」的虚拟实体。元宇宙讲的是一个世界，数字人是这个世界里最先实现商业闭环的单元——你不需要一整个虚拟世界，只需要一个能 7x24 小时直播带货、能接客服电话、能当虚拟偶像的数字人，就有客户愿意付钱。

1.2 数字人的三个分类维度

新人最容易混淆的是「数字人」一词涵盖了很多完全不同的技术路线。按三个维度拆开看：

flowchart TB
    DH[数字人] --> A[按形象分]
    DH --> B[按驱动方式分]
    DH --> C[按交互方式分]

    A --> A1[2D 卡通 / Live2D]
    A --> A2[3D 写实<br/>MetaHuman / 捏脸]
    A --> A3[真人形象克隆<br/>照片/视频驱动]

    B --> B1[真人驱动<br/>中之人 + 动捕]
    B --> B2[AI 驱动<br/>文本/语音全自动]
    B --> B3[混合驱动<br/>AI 为主 真人兜底]

    C --> C1[离线内容型<br/>录播视频/短视频]
    C --> C2[实时交互型<br/>对话/直播/客服]

形象维度：Live2D 成本最低（一张立绘就能动），3D 写实最重（建模 + 绑定 + 渲染），真人克隆最像真人（用真人的照片或视频训练）。
驱动维度：虚拟主播圈常说的「中之人」就是真人在幕后戴动捕设备驱动皮套；AI 驱动则是全自动化，这也是本文的重点。
交互维度：离线内容型（批量生成口播视频）对实时性没要求，工程难度低一个量级；实时交互型（你说一句它答一句）才是技术深水区。

典型应用场景对号入座：虚拟主播直播（实时 + 真人/AI 驱动）、AI 客服数字人（实时 + AI 驱动）、短视频口播矩阵（离线 + AI 驱动）、数字分身/数字永生（真人克隆 + 实时）、企业数字员工大屏（实时 + 3D）。

2. 一张图看懂整体链路

数字人系统本质上是把一个真人的沟通能力拆成流水线，每个环节用一个技术组件替代：

flowchart LR
    subgraph 感知["感知（耳朵 + 眼睛）"]
        MIC[麦克风] --> VAD[VAD 语音检测] --> ASR[ASR 语音识别]
        CAM[摄像头] --> VIS[视觉感知<br/>人脸/唇动/表情/手势]
    end

    subgraph 认知["认知（大脑）"]
        ASR --> LLM[LLM 对话引擎<br/>+ RAG + 记忆 + 工具]
        VIS -.情绪/注意力标签.-> LLM
    end

    subgraph 表达["表达（嘴巴 + 脸 + 身体）"]
        LLM --> TTS[TTS 语音合成]
        TTS --> DRIVE[驱动引擎<br/>口型/表情/动作]
        DRIVE --> RENDER[渲染引擎<br/>2D/3D 形象]
    end

    subgraph 传输["传输（神经）"]
        RENDER --> RTC[WebRTC 低延迟推流]
        RTC --> USER([用户屏幕/音箱])
    end

    USER -.用户说话.-> MIC
    USER -.用户在镜头前.-> CAM

记住这个拟人化口诀：耳朵（ASR）听清、眼睛（视觉感知）看懂 → 大脑（LLM）想好 → 嘴巴（TTS）说出 → 脸（口型驱动）对上 → 神经（WebRTC）送达。

整条链路分两大形态：

形态	特点	延迟要求	典型延迟预算
离线内容生产	批量生成视频，可反复重试	无	分钟级也无所谓
实时交互	一问一答，像打电话	端到端小于 1.5 秒才自然	每一环都要抠毫秒

离线形态是实时形态的子集（少了 ASR 和 RTC，渲染换成离线出片），所以下面重点拆实时链路。

3. 实时交互链路逐环拆解

先看一次完整对话的时序，建立整体感觉：

sequenceDiagram
    participant U as 用户
    participant E as 边缘采集端
    participant A as ASR 服务
    participant L as LLM 服务
    participant T as TTS 服务
    participant D as 驱动+渲染
    participant R as RTC 网络

    U->>E: 说话（语音流）
    E->>E: VAD 检测说话起止
    E->>A: 流式发送音频
    A-->>L: 边说边出识别文本
    L-->>T: 流式输出回答（按句切分）
    T-->>D: 流式合成音频（边收边播）
    D->>D: 音频驱动口型/表情
    D->>R: 音视频帧推流
    R-->>U: 看到听到数字人回答
    Note over U,R: 用户感知延迟 = 最后一个字说完到数字人开口的时间

关键设计原则：每一环都是流式（streaming）的。如果等 LLM 把整段话说完再送 TTS、等 TTS 合成完整段再播放，延迟会叠加到无法接受。流式的含义是「边产生边消费」，像水管一样一环接一环地流。

3.1 耳朵与眼睛：VAD + ASR + 视觉感知

VAD（Voice Activity Detection，语音活动检测）：判断用户什么时候开始说、什么时候说完了。它是交互节奏的总开关——判早了会把用户一句话切成两半，判晚了用户会觉得数字人反应迟钝。

ASR（Automatic Speech Recognition，语音识别）：把语音流实时转成文字。

3.1.1 VAD 到底怎么判断「开始说」和「说完了」

VAD 把音频切成 10-30ms 的小帧，对每一帧打一个「是语音的概率」，然后用状态机做判定：

stateDiagram-v2
    [*] --> 静音
    静音 --> 可能说话: 连续 N 帧概率超阈值
    可能说话 --> 说话中: 确认（防突发噪音）
    可能说话 --> 静音: 概率回落（是咳嗽/关门声）
    说话中 --> 可能结束: 出现连续静音帧
    可能结束 --> 说话中: 重新检测到语音（句中停顿）
    可能结束 --> 静音: 静音持续超 hangover 阈值

算法分三代，了解演进就知道怎么选：

能量 + 过零率：最原始的做法，能量突增判说话。安静机房能用，真实环境（空调声、键盘声）全是误判。
统计模型：代表作是 Google 的 WebRTC VAD（GMM 高斯混合模型），内置 0-3 四档灵敏度，免费、极快，至今仍是很多项目内置的默认项。
神经网络模型：工业主流。开源首选 Silero VAD（几 MB 的 ONNX 模型，CPU 上实时跑，自带 30ms 帧判定）；国内还有阿里的 FSMN-VAD（FunASR 自带）、TEN-VAD。抗噪能力比前代强一个量级。

三个必须知道的工程细节：

判起要有「提前量」：VAD 确认「开始说话」需要连续若干帧，如果确认后才把音频送 ASR，句首会被吃掉（「你好，数字人」变成「数字人」）。解法是预滚动缓冲（pre-roll buffer）：始终缓存最近 200-300ms 音频，VAD 触发时把缓冲一并送出。
判停（端点检测）是延迟与完整的权衡：静音持续多久算「说完了」，默认 500-800ms。设太短切断用户的长句停顿（「那个……我想问一下」被切成两段），设太长每轮对话白等几百毫秒。
语义 VAD 是高阶玩法：不只看静音时长，还结合 ASR 的中间识别结果判断语义是否完整——识别文本还没形成完整句子就延长等待。大模型语音产品（GPT-4o 类）和商用方案普遍在用，纯声学 VAD 容易被「思考停顿」骗过。

3.1.2 流式 ASR：现成 API 还是自己改 Whisper

先说结论：商用快速上线选云 API；数据敏感或量大图便宜选自部署开源方案；改造 Whisper 只适合练手和理解原理，别上生产。

现成 API（WebSocket 流式，接入即用）：

国内：阿里云实时语音识别、腾讯云 ASR、讯飞、火山引擎——中文效果好、热词支持完善、按量付费，首字延迟可做到 200-300ms。
海外：Deepgram、AssemblyAI、Azure Speech、OpenAI Realtime API。

自部署开源方案：

FunASR（阿里开源）：Paraformer 流式版，自带 VAD + 标点恢复，中文场景首选，社区活跃。
sherpa-onnx（k2 团队）：流式 Zipformer/Transducer 模型，跨平台，端侧（手机/嵌入式）都能跑。
SenseVoice（阿里）：多语言、低延迟，还带情感与事件检测。

Whisper 为什么难办：它原生是离线架构——encoder 要吃 30 秒的音频窗口，天然不是流式模型。三种常见改造路线：

路线	做法	问题
VAD 切段 + faster-whisper	VAD 检出完整一段话后送 faster-whisper（CTranslate2 加速版）	是「段级准实时」，不是真流式；每段延迟 1-3 秒，数字人场景偏慢
LocalAgreement 策略	whisper_streaming 项目的做法：滑动小窗反复识别，连续两次结果一致的前缀才确认输出	体验接近真流式，但同一段音频重复计算，GPU 成本高
换流式架构模型	承认 Whisper 不适合流式，直接用 Paraformer-streaming / Zipformer / SenseVoice	正解，但等于放弃了 Whisper

选型对照：

路线	首字延迟	中文效果	成本	适合谁
云 API	200-300ms	好（热词完善）	按量付费，量大贵	快速上线、没运维团队
FunASR / sherpa 自部署	200-500ms	好	自己的 GPU，量大便宜	数据敏感、有推理运维能力
Whisper 改造	1s 以上	好	重复计算，贵	学习、离线转写场景

新人要点：

选流式 ASR（边说边出字），不要选录音文件识别接口。
热词（hotword）功能必须用起来：业务专有名词（产品名、品牌名）通过热词表喂给 ASR，否则识别错误会一直污染下游 LLM。
AEC（回声消除）：如果数字人的声音从音箱播出来又进麦克风，ASR 会把数字人自己的话识别成用户输入，造成「自己跟自己对话」。用扬声器场景必须开 AEC（WebRTC 自带，自研采集端要接 Speex/WebRTC APM 这类模块）。

3.1.3 眼睛：视觉感知，数字人能不能「看到」用户

只有耳朵的数字人，相当于一个闭着眼打电话的人——能用，但离「像人」差一层。加上摄像头这条通道，感知层才完整。视觉信号在数字人里有六个典型用途：

视觉能力	干什么用	典型场景
存在检测	判断镜头前有没有人、有几个人，有人靠近才激活交互	大屏数字员工、门店导购，免唤醒词
视觉 VAD（唇动检测）	看着用户的嘴判断是否真在说话	嘈杂环境辅助音频 VAD，大幅降低误触发
表情/情绪识别	识别皱眉、笑、困惑，作为上下文注入 LLM	客服场景感知用户不满，共情回应
视线/注意力检测	用户是否在看屏幕	用户转头就走时数字人停止讲解，不自言自语
手势识别	挥手打招呼、举手打断、比划指令	展厅、车载等不方便说话的场景
人脸识别身份	认出是谁，关联记忆系统调出画像	VIP 客户识别、数字分身授权核验

工程实现分三层，按需取用：

端侧轻量模型：人脸检测、唇动、手势这类高频低算力任务放端侧跑（MediaPipe、YOLO 系列、厂商人脸 SDK），只把结论标签上传，不上传原始视频流——省带宽、降延迟、利隐私。
云端识别：情绪识别等重模型走云端，按帧抽样的低频调用即可，不要全帧率送云。
端到端多模态大模型：GPT-4o、Gemini Live 这类音视频直接进模型的路线，跳过「ASR 转文字」环节，能直接听懂语气、看到画面。这是趋势，但目前成本高、可控性弱（不好接 RAG 和业务约束），商用数字人中台主流仍是「ASR + LLM」模块化架构加视觉辅助信号。

视觉信号进大脑的正确姿势：视觉结果不作为对话内容，而是作为低优先级异步上下文标签注入 LLM——比如 [用户皱眉] [用户看向别处] [检测到 3 位观众]，让人格层决定如何反应（加快语速、主动询问、暂停讲解）。直接把视觉识别文本拼进用户输入会污染对话流，是新人常犯的错误。

合规红线：人脸信息在《个人信息保护法》里属于敏感个人信息，采集需单独同意、明示用途。门店大屏这类被动采集场景尤其要小心，能端侧处理就不要上传原图，能用人形检测就不要做人脸识别。

回答「数字人要不要眼睛」这道题的思路：不是必须，但它是从「语音机器人」到「数字人」的分水岭——语音通道解决「听懂」，视觉通道解决「看懂场合」，两者融合（多模态感知）才有真正的临场感。在技术评审或方案讨论中，能讲清视觉信号作为异步标签注入、端侧优先、隐私合规这三点，就说明理解到位了。

3.2 大脑：LLM 对话引擎

这一环是大家最熟悉的：把识别文本丢给大模型，拿回答。但在数字人场景有几个特殊要求：

System Prompt 分层：人格设定（你是谁、什么性格）、业务知识（RAG 注入）、表达约束（口语化、每句别太长）分三层管理，不要揉成一大段。人格一致性是「数字人」区别于「聊天框」的核心。
输出要为「说」优化：prompt 里明确要求口语化短句、不要 markdown、不要列表符号——TTS 会把「1.」「**」念出来。
长时记忆：多轮对话靠上下文窗口，跨会话的「记住用户」要靠记忆系统（如 Mem0 这类长时记忆中间件：向量检索 + 用户画像 + 摘要）。
Function Calling：查天气、下单、转人工这类动作走工具调用，返回结果再让 LLM 组织成口语。

3.2.1 RAG：给大脑喂业务知识的标准流程

数字人要回答企业业务问题，靠模型自身的知识不够，必须外挂知识库。RAG（Retrieval-Augmented Generation，检索增强生成）的标准流程新人必须掌握：

flowchart LR
    subgraph 离线建库["离线：建知识库"]
        DOC[业务文档] --> CHUNK[切分 Chunking] --> EMB[Embedding 向量化] --> VDB[(向量数据库<br/>Qdrant/Milvus/Chroma)]
    end

    subgraph 在线检索["在线：问答时"]
        Q[用户问题] --> REWRITE[Query 改写/补全] --> SEARCH[混合检索<br/>向量 + BM25 关键词]
        VDB -.相似度召回.-> SEARCH
        SEARCH --> RERANK[Rerank 重排序]
        RERANK --> PACK[拼装 Prompt<br/>system + 知识 + 历史 + 问题]
        PACK --> GEN[LLM 流式生成]
    end

核心要点（方案讨论和实战都绕不开）：

切分（Chunking）：按语义/段落切，块太大噪音多、块太小上下文断裂，常用 200-500 字加 10% 重叠。
Embedding 选型：中文场景主流 BGE 系列（BGE-M3 支持多语言与稠密稀疏混合），决定了召回质量的上限。
混合检索：纯向量检索对「型号、编号、专有名词」这类精确匹配很差，向量召回 + BM25 关键词召回合并是工业标配。
Rerank：召回 topK 比如 20 条，用 Rerank 模型（如 bge-reranker）精排取前 3-5 条进 prompt，显著降噪。
评估闭环：召回命中率、答案忠实度（有没有幻觉）要有评估集回归，改任何一环都跑一遍。

3.2.2 核心问题：首 token（TTFT）怎么做到最快

数字人场景里，LLM 是整个链路的延迟黑洞，而用户感知的快慢主要看 TTFT（Time To First Token，首 token 延迟）——因为输出是流式的，第一个 token 出来，后面的 TTS 就能开工。先把公式摆出来：

TTFT = 检索耗时 + 网络与排队耗时 + Prefill（预填充）耗时

理解三个组成部分，优化手段就是对号入座：

flowchart LR
    A[用户说完话] --> B[RAG 检索<br/>50-300ms]
    B --> C[网络 RTT + 排队<br/>50-500ms]
    C --> D[Prefill 预填充<br/>随 prompt 长度线性增长]
    D --> E[首 token 吐出]
    style D fill:#fee,stroke:#c00

第一路：让检索更快

向量库用 HNSW 这类内存索引，召回压到几十毫秒；向量检索和 BM25 关键词检索并行发，取并集。
Embedding 模型本地/就近部署，别为一次向量化跨地域调 API。
高频问题语义缓存：命中缓存直接跳过检索和生成（客服场景命中率可以做到很高），甚至直接返回预生成的音视频片段，TTFT 趋近于零。

第二路：让 prompt 更短（砍 Prefill）

Prefill 耗时随输入 token 数近似线性增长，prompt 每砍一半，这部分就快一半：

system prompt 精简，人格层/业务层/约束层按需加载，不要每次都全量带上。
RAG 注入的 chunk 控制在 3-5 条，靠 Rerank 保证质量而不是靠堆数量。
历史对话做摘要压缩，多轮后只带摘要 + 最近几轮原文。

第三路：让前缀可缓存（KV Cache / Prompt Caching）

把不变的内容放 prompt 最前面（人格设定、业务规则），变化的内容（检索结果、用户问题）放最后。主流推理框架（vLLM 的 Automatic Prefix Caching）和商用 API（Claude/DeepSeek 的 prompt cache）都能复用前缀的 KV Cache，命中后 Prefill 几乎免费。
反面教材：在 system prompt 里塞时间戳、随机 ID——前缀每次都变，缓存永远miss。

第四路：让引擎和部署更快

推理框架选 vLLM/SGLang 这类支持 continuous batching 的，吞吐和排队时间都受益。
模型分级：简单问答走小模型（几百毫秒出首 token），复杂问题再路由大模型；或对延迟敏感的数字人场景直接上中小尺寸模型。
就近部署 + 长连接连接池 + 定期预热，避免冷启动和跨地域 RTT。
进阶要点：投机采样（speculative decoding）加速的是解码阶段，对 TTFT 帮助不大——能分清「首 token 快」和「整体生成快」是两套优化，说明真懂推理过程。

第五路：感知层兜底

优化到头也压不进目标时，用填充音（「嗯，我想想」）先开口争取 500-800ms，用户感知立刻好转。
记住目标：流式架构下 TTFT 就是用户感知的全部，后续 token 只要比语速快（TTS 会按说话节奏消费），生成总时长不影响体验。

一句话总结：「TTFT 等于检索加排队加 Prefill。我的优化顺序是：语义缓存先拦截高频问题，RAG 检索并行化并本地部署 Embedding，prompt 精简加 Rerank 控量，稳定前缀前置吃满 KV Cache，小模型分级响应，最后填充音兜底感知。」

3.3 嘴巴：TTS 语音合成

TTS（Text To Speech） 决定数字人「听起来像不像人」。新人要点：

同样必须选流式 TTS，而且关注一个核心指标：首包延迟（TTFB，Time To First Byte）——从给文本到第一帧音频出来的时间，主流云服务在 200-400ms。
分句策略：LLM 流式输出的文本按标点切成短句送 TTS，句与句之间流水线并行。怎么切是个真问题，展开见 3.3.1。
音色克隆：商用数字人大多需要定制音色（克隆老板、克隆主播）。主流方案（火山、阿里 CosyVoice、GPT-SoVITS 开源）只需几分钟到几小时的样本。注意合规红线：音色克隆必须取得本人授权，国内已有相关判例和《生成式人工智能服务管理暂行办法》的约束。
韵律和情感：检查 TTS 是否支持 SSML 或情感标签，数字人「说话像念经」多半是没做韵律控制。

3.3.1 从首 token 到首包：LLM 和 TTS 怎么衔接

工程上绕不开的一道题：LLM 通过 SSE（Server-Sent Events）逐 token 往外吐，TTS 在另一头等着合成——中间这段，是攒够 N 个 token 就送一次 TTS，还是有更好的方案？

先纠正一个概念：SSE 只是传输管道，它决定的是「token 一个一个到达」这个事实，不包含任何切分策略。真正要做决策的是服务端的聚合层（aggregator）——它消费 SSE 流，决定什么时候把一段文本交给 TTS。

三种方案的对比：

方案	做法	评价
按 token 攒批	攒够 N 个 token 就送 TTS	差方案。token 边界和语言边界无关，会切在半个词、半个标点上；每次 TTS 请求有固定开销，请求过碎成本高；韵律上下文残缺，合成质量差
按句/子句切分	缓冲 token，命中边界标点且长度达标才 flush	工业标配。切点干净、韵律完整，首句策略可调
流式文本输入 TTS	TTS 本身支持边收文本边合成（WebSocket 双向流），把 SSE token 直接转发进去	更好但依赖厂商能力。切句职责交给最懂韵律的 TTS 引擎，首包最快。ElevenLabs、火山、CosyVoice 流式版都支持；自部署 GPT-SoVITS 需要自己做这层

按句切分（方案二）的工程细节，这是自建聚合层必须写对的：

flowchart TD
    T[SSE 收到一个 token] --> BUF[写入缓冲区]
    BUF --> C1{命中句末标点<br/>。！？ 且长度达标?}
    C1 -- 是 --> FLUSH[flush：送 TTS 队列]
    C1 -- 否 --> C2{缓冲长度超上限?}
    C2 -- 是 --> C3{回找最近的<br/>逗号/顿号}
    C3 -- 找到 --> FLUSH
    C3 -- 没有 --> WAIT[继续等<br/>到硬上限强切]
    C2 -- 否 --> C4{缓冲超时<br/>300-500ms?}
    C4 -- 是 --> FLUSH
    C4 -- 否 --> T
    WAIT --> T
    FLUSH --> NEXT[句子带序号进 TTS 队列<br/>并发合成 按序播放]

四条规则记牢：

首句激进，后续放宽：第一句是首音延迟的关键，切得短（命中第一个逗号、8-15 字就 flush，甚至 LLM prompt 里直接要求「第一句简短应答」）；后续句子放宽到 20-80 字保证韵律。首音快 200ms，用户感知就高一档。
切点优先级：句号/问号/叹号最优先，分号/冒号次之，逗号只在超长兜底时用。顿号不切。
标点陷阱：小数点（「3.5 秒」）、省略号、引号内标点、英文缩写（「e.g.」）都会造成误判，正则切分前先做这些特例清洗；markdown 符号（**、#、1.）在进缓冲前就要剥掉，否则 TTS 会念出来。
并发合成、按序播放：切出来的句子打上序号进队列，多个 TTS 请求可以并发，但播放端必须按序号拼接，乱序就出「先说第二句」的事故。

超时兜底为什么必须有：LLM 有时会输出不带句末标点的长句，如果没有 300-500ms 的缓冲超时强刷，用户会眼睁睁看着数字人「憋着不说话」。

一句话总结：「SSE 只负责把 token 送过来，切分在服务端聚合层做。不按 token 数攒批——按标点加长度双阈值切句，首句切得激进来压低首音时间，后续句放宽保韵律，再加超时兜底；如果 TTS 厂商支持流式文本输入，就直接把 token 流转发进去让引擎自己切，首包还能再快一截。」

3.4 脸：口型与表情驱动

这是数字人区别于「语音助手」的关键一环，也是新人知识盲区最大的一环。

核心技术概念：

Viseme（视素）：音素（phoneme）对应的口型。比如 /b/ /p/ /m/ 都对应「双唇闭合」这个口型。英文一般归并为十几个 viseme，中文可按韵母口型归类。
Blendshape（混合形状）：3D 模型的表情通过一组预定义变形（如 jawOpen、mouthSmile）按权重混合出来。音频 → 音素 → viseme → blendshape 权重，就是经典的口型驱动路径。
2D 真人形象驱动：wav2lip、SadTalker、MuseTalk 这类模型，输入音频 + 人脸视频/照片，直接生成口型对齐的人脸帧。

flowchart TB
    AUDIO[TTS 音频流] --> PATH{形象路线}
    PATH -->|3D 写实路线| P1[音频提取音素/声学特征]
    P1 --> P2[映射 Viseme / Blendshape 权重]
    P2 --> P3[Unity/UE 实时渲染]
    PATH -->|2D 真人克隆路线| Q1[wav2lip / MuseTalk 等<br/>音频到人脸帧模型]
    Q1 --> Q2[逐帧生成口型对齐画面]
    PATH -->|Live2D 路线| R1[音量/音素驱动<br/>参数开合]
    R1 --> R2[Live2D SDK 渲染]

    P3 --> OUT[合成视频帧推流]
    Q2 --> OUT
    R2 --> OUT

选型经验：

路线	效果	成本	适用
Live2D	二次元，口型精度要求低	极低（CPU 可跑）	虚拟主播、轻量客服
3D Blendshape	可控、风格化或写实	中（需要建模绑定 + GPU 渲染）	品牌 IP、大屏数字员工
真人克隆（wav2lip 类）	最像真人	高（每帧都要过模型，吃 GPU）	数字分身、口播视频

3.5 身体：动作与姿态

只有脸会动的数字人被称为「花瓶数字人」。完整的身体驱动包括：

待机动作（idle）：不说话时的呼吸、眨眼、微动作。没有 idle 的数字人在沉默时会「死机感」十足。
动作库触发：LLM 输出时打标签（如 [挥手]），引擎播放对应动画片段。
动作生成/动捕：高端场景用动作生成模型或真人动捕（光学动捕、惯性动捕、视觉动捕）。
视线与点头：根据对话状态做倾听点头、眼神接触，对「像人」的提升性价比极高。

3.6 渲染与呈现

客户端渲染：形象资源下发到 App/Web/小程序，本地用 Unity、WebGL（three.js）、Live2D SDK 渲染。好处是不耗服务端 GPU、画面清晰；代价是包体积和端上性能适配。
服务端渲染 + 推流：服务端用 UE/Unity 无头渲染成视频流推给端上。好处是端上零成本、形象保密；代价是每路并发一块 GPU，成本高。
像素流送（Pixel Streaming）：UE 官方的「服务端渲染 + WebRTC 推流」方案，超写实数字人大屏常用。

3.7 神经：WebRTC 低延迟传输

实时交互必须走 WebRTC（或声网 Agora、腾讯 TRTC、即构 ZEGO 这类商用 RTC SDK，底层同源）。不要用 HLS/RTMP 做交互——它们的延迟是秒级到十秒级，只能用于纯观看的直播场景。

WebRTC 给数字人的价值：

端到端延迟可压到 200-400ms；
自带弱网对抗（ jitter buffer、NACK、FEC）、AEC、降噪；
天然支持双向音视频（用户上行说话 + 数字人下行画面）。

工程上通常自建或租用 SFU（Selective Forwarding Unit）做转发，数字人服务端作为一个「虚拟参会者」接入 RTC 房间。

4. 延迟预算：实时数字人的生死线

交互自然度的经验值：用户说完话到数字人开口，超过 1.5 秒就会觉得「卡」，控制在 1 秒内算流畅，500ms 内接近真人。

逐环预算参考（单位毫秒）：

环节	典型耗时	优化手段
VAD 判停（说完话确认）	300-600	语义 VAD、动态超时
ASR 末字出结果	100-300	流式 + 就近节点
LLM 首 token	300-800	小模型前置、就近部署、prompt 精简
TTS 首包	200-400	流式、句级流水线
口型驱动 + 渲染首帧	50-200	预加载、模型量化
RTC 传输	100-300	就近接入、专线

flowchart LR
    A[VAD 判停<br/>300-600ms] --> B[ASR 出字<br/>100-300ms]
    B --> C[LLM 首 token<br/>300-800ms]
    C --> D[TTS 首包<br/>200-400ms]
    D --> E[驱动渲染<br/>50-200ms]
    E --> F[RTC 送达<br/>100-300ms]
    style C fill:#fee,stroke:#c00

注意 LLM 是最大的延迟黑洞，这也是为什么很多产品用「嗯、我想想」这类填充音（filler）先开口争取时间，以及用小参数模型做第一轮快速响应。

5. 离线内容生产链路

做口播短视频、课程录播的场景不需要实时，链路简化为：

flowchart LR
    S[文案脚本] --> T[TTS 合成配音]
    T --> D[wav2lip / 形象克隆<br/>生成画面]
    D --> E[FFmpeg 合成<br/>字幕/背景/BGM]
    E --> V[成品视频]

这条链路的工程重点是批量化和质量控制：文案队列、素材版本管理、抽帧质检（口型错位检测）、FFmpeg 自动化后期。它也是新人练手的最佳起点——没有实时性压力，每一步都可以慢慢调试。

6. 元宇宙视角下的数字人

虽然元宇宙概念已过炒作高峰，但它的知识框架对理解数字人很有帮助：

数字人是元宇宙的「界面」：元宇宙的愿景里，人通过 Avatar 进入虚拟世界，而 AI 数字人是这个世界里的 NPC、导游、店员。今天落地的数字人客服、数字人员工，可以看作「没有整个元宇宙、先把 NPC 做出来」的务实路线。
数字身份与数字资产：虚拟形象的版权归属、音色的人格权、数字分身的行为授权，都是元宇宙法律框架讨论的核心，做商用数字人绕不开。
XR 是下一级放大器：目前的数字人主要在手机屏和大屏上，VR/AR 设备普及后，「面对面」的沉浸交互会把实时渲染和低延迟的要求再推高一个量级。
技术栈高度重合：游戏引擎、实时渲染、Avatar 系统、RTC——元宇宙基建没浪费，全都迁移到了数字人赛道。

一句话总结两者的关系：元宇宙是「世界」，数字人是「人」；世界还在建，人已经开始打工了。

7. 避坑清单（新人最常踩的十个坑）

用 HTTP 轮询或 WebSocket 传实时音视频：WebSocket 传音频可以，但视频和双向通话必须 WebRTC。架构选错后面全是补丁。
等 LLM 全句生成完再送 TTS：首音延迟直接多出 1-3 秒。必须按句流式切分。
TTS 分句切在奇怪的位置：按标点切，且避免切出「的」「了」这种单字句，否则韵律全毁。
忽略 VAD 判停时间：默认 500-800ms 的静音判停在口语场景经常切断用户长句，要按场景调。反过来判起也有坑——不做 200-300ms 预滚动缓冲（pre-roll）会吃掉句首，「你好」变成「好」。
没做 AEC 就上扬声器场景：数字人听见自己说话，无限自答。音箱/大屏场景必查。
口型和音频各走各的时钟：音频流和视频帧必须共用时间戳对齐，否则网络抖动后口型越偏越远。
忽视打断（barge-in）：用户插话时数字人必须能立刻闭嘴并清空播放队列，这是「像人」的及格线，很多 Demo 死在这。
没有 idle 状态：沉默时形象完全静止，恐怖谷效应拉满。眨眼和呼吸是性价比最高的两个动作。
音色克隆不管授权：合规风险，商用前必须签授权。
并发成本没算清就接客：真人克隆路线每路并发都吃 GPU，一路成本可能是纯语音机器人的几十倍，报价前先压测。

8. 典型问题与解决方案

Q1：口型和声音对不上，越聊偏得越远。 音频帧和驱动帧的时间戳没有同源。方案：以音频流为主时钟，口型权重按音频时间戳生成，渲染帧消费时做对齐；网络侧开启 NACK 减少重传造成的画面跳变。

Q2：数字人响应慢，用户说完要等两三秒。 按第 4 节的预算表逐环打点定位。八成问题在 LLM 首 token 和 TTS 首包：LLM 换更快的模型或精简 prompt，TTS 确认开了流式，两句之间流水线并行。还不行就加填充音。

Q3：用户插话，数字人不理继续说完。 没有 barge-in 机制。方案：ASR 检测到新的用户语音起始 → 立即向 TTS/播放器发中断信号 → 清空待发队列 → LLM 侧中断当前生成（保留已说内容到上下文）。

Q4：声音机械、像念稿。 检查：文本是否带了 markdown 符号（TTS 会念出来）；是否用了支持韵律/情感的模型；分句是否过碎。可以在送 TTS 前加一道「口语化改写」。

Q5：回声、啸叫、把自己当用户。 AEC 没生效。WebRTC 场景确认 echoCancellation: true；自研管线接入 WebRTC APM；硬件上麦克风和扬声器做物理隔离。

Q6：大促/高峰期并发上不去，GPU 烧钱。 真人克隆路线把渲染挪到闲时（离线预生成常见回答视频片段，实时只做拼接）；或降级到 3D/Live2D 路线；LLM 层加意图缓存，高频问题直接命中预置音视频。

Q7：数字人前后人设不一致，聊着聊着「换人」了。 人格 prompt 没有和记忆系统打通。方案：人格定义放 system 层固定不动；用户画像和会话摘要由记忆系统（如 Mem0）注入；定期用人格一致性评估集回归测试。

9. 学习路径：从 0 到精通

flowchart TB
    subgraph S1["第一阶段：跑通（1-2 周）"]
        A1[调通云 ASR + LLM + TTS<br/>做一个语音对话命令行 Demo]
        A2[用 wav2lip 开源模型<br/>离线生成一个口播视频]
    end

    subgraph S2["第二阶段：像人（3-4 周）"]
        B1[全链路流式化改造<br/>打点测延迟]
        B2[实现 barge-in 打断]
        B3[接入一个 2D/3D 形象<br/>完成口型驱动]
    end

    subgraph S3["第三阶段：上线（4-8 周）"]
        C1[WebRTC 推拉流<br/>端到端联调]
        C2[记忆系统 + 人格 prompt 工程]
        C3[压测与成本核算<br/>弱网对抗]
    end

    subgraph S4["第四阶段：精通（持续）"]
        D1[自研/微调 TTS 与驱动模型]
        D2[情感计算与多模态交互]
        D3[中台化：多形象/多租户/编排]
    end

    S1 --> S2 --> S3 --> S4

练手项目建议（按递进排序）：

命令行语音助手：打通 ASR → LLM → TTS，全程流式。
离线口播视频生成器：文案进、成片出，加 FFmpeg 字幕。
网页实时数字人：Live2D 或 wav2lip 形象 + WebRTC，实现打断。
有记忆的数字人：接入长时记忆，连续聊三天还记得用户说过什么。

10. 总结

数字人链路说复杂也复杂，说简单就是一句话：把人的「听、想、说、动」拆成 ASR、LLM、TTS、驱动渲染、RTC 五个流式环节，再把总延迟压进 1 秒。新人入门的正确姿势不是啃论文，而是先跑通最小闭环，再逐环升级——每一环的坑本文都列了，剩下的就是动手。

概念地图有了，想看这条链路在真实开源项目里长什么样，接着读《LiveTalking 源码解剖：一个开源实时数字人是怎么跑起来的》——它把本文的输出侧（TTS、口型驱动、RTC 推流）做成了工业级实现，输入侧和智能侧留着 demo 形态，正好当对照样本。

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 陪伴系统，欢迎在评论区交流：你觉得“记忆隔离”和“发言调度”哪个更难做好？

GenRec 笔记：Netflix 怎么把推荐排序器做成 LLM 原生

Thu, 30 Jul 2026 10:00:00 +0800

GenRec 笔记：Netflix 怎么把推荐排序器做成 LLM 原生

原文：GenRec: Towards LLM-Native Recommendation at Netflix 目标读者：做推荐、搜索、排序的后端工程师，以及关心「LLM 怎么落地进成熟业务系统」的 AI 工程师。阅读目标：搞清楚 GenRec 的两阶段训练框架、目录感知打分头、prefill-only 推理这三个核心机制，以及它用远少于生产系统的标注数据追平甚至反超的原因。

一、问题：推荐栈的复杂度税

Netflix 现有生产排序器是多年演化的结果：数千个手工特征、专门的序列建模结构、特征交互结构、多任务目标，支撑电影、剧集、游戏、直播、播客等多种内容类型和多个产品界面。它能跑，但** onboarding 一个新场景（新内容类型、新界面）的成本极高**——特征工程、架构改动、基础设施、实验，一样都少不了。这是典型的复杂度税。

与此同时，LLM 圈已经在推荐方向有不少探索（原文点名 PLUM、GLIDE、OneRec-Think）。思路很诱人：把用户历史和物品元数据直接表示成文本，靠 LLM 的世界知识和语言理解在共享语义空间里抓关系，甚至用自然语言 prompt 去「引导」推荐。但现成 LLM 直接上岗是不合格的推荐器：偏向全局热门、幻觉出目录外的物品、无视业务约束、个性化弱。GenRec 要回答的问题就是：把 LLM 正经后训练成排序器，能不能打过一套调了多年的生产系统？

任务设定本身很标准：全目录排序（有候选集时是 top-K）。给定用户、交互历史、当前上下文（设备、界面、地区、时间），输出一个个性化排序，优化目标是长期会员效用（满意度和留存的代理），不是短期点击。

二、两阶段：先适配，再排序

GenRec 的训练分两阶段，分工明确：

Phase 1 —— Netflix 适配的基座 LLM：从开源 LLM 出发，在 Netflix 专有语料上继续训练，让它学会内容理解、会员行为与偏好模式，同时保住通用语言能力。更新频率低，作为多个应用共享的「Netflix-aware」基座。
Phase 2 —— GenRec 本体：在 Phase-1 基座上用排序数据和排序目标做后训练，专注排序质量与可控性，用奖励加权损失融入多种奖励信号；更新频率高，跟踪新内容和口味漂移；并且从设计上就在推理成本约束下优化。

flowchart TD
    OSS["开源 LLM"] -->|"Netflix 专有语料继续训练<br/>低频更新"| P1["Phase 1<br/>Netflix 适配基座 LLM<br/>多应用共享"]
    LOG["会员交互日志<br/>播放 时长 评分 弃看 等"] -->|"文本化为对话<br/>user 消息 上下文与历史<br/>assistant 消息 真实行为"| DATA["Phase 2 训练数据"]
    P1 --> DATA
    DATA -->|"排序目标 + 语言建模目标<br/>+ 奖励加权损失"| P2["Phase 2<br/>GenRec 排序模型<br/>高频更新 成本约束"]
    RM["独立奖励模型<br/>长期满意度代理<br/>行为再平衡"] -.->|"给每条样本一个标量权重"| P2
    style P1 fill:#fff3cd
    style P2 fill:#e8f5e9

这个两阶段划分是全文我觉得最值得抄的部分：基座慢迭代、排序快迭代。基座沉淀通用能力，排序层追内容新鲜度——后面消融实验会证明，Phase-1 越陈旧，Phase-2 的相对收益越大。

三、训练数据即对话，上下文即特征

Netflix 会员每天产生千亿级交互事件。GenRec 把日志转成单轮或多轮「对话」：user 消息是文本化的上下文、画像、历史、物品元数据和任务（比如「预测用户接下来会播放或点赞什么」），assistant 消息是会员的真实行为（播了什么、播了多久、给了什么反馈）。Phase-2 训练时，模型学的是 assistant 消息对 user 消息的条件依赖。

注意一个容易误读的点：对话格式只为训练服务。推理时不做自回归生成——把文本化的上下文喂进去，直接用打分头给候选物品算分。对话形式存在的原因是配合语言建模目标、保住模型对文本的理解能力。

文本化的瓶颈是 token 预算。把用户历史里每个事件都摊开写，成本在 Netflix 规模下不可接受。于是上下文窗口成了新的「特征预算」，GenRec 的做法是给上下文做工程：

完整保留：高信号事件（长播放、点赞），细节给足；
直接丢弃：低信号事件（极短播放、快速划过）；
摘要压缩：重复性行为（连续刷剧这类 binge 行为）；
选择性展开：重要或冷启动物品（比如新上线内容）。

固定预算内优先近期的、高信号的历史，老的压缩或丢掉。prompt 结构上还要最大化共享前缀，吃满 prefix caching。「prompt 就是新的特征向量」——这句话是全文的眼。

四、三个目标：排序、语言、奖励

GenRec 的损失是三件事的组合：

目录感知排序目标：用高价值行为（足够长的播放、强显式反馈）做正例，带阈值和去噪逻辑；在目录或候选集上做交叉熵，让正例得分更高。
语言建模目标：保留 LM 损失，防止模型在文本化输入上丢掉语言理解能力，也给「推荐理由解释」这类生成场景留门。
奖励加权对齐：只在原始行为序列上训练，模型会学出坏习惯——过度偏向刷剧、只推单一内容类型。解法是独立奖励模型给每条训练样本算一个标量权重：长期满意度代理（这次短期行为对回访、目录探索、持续活跃有多大贡献）加行为再平衡（跨内容类型、跨上线阶段调节）。高价值样本加权，低价值样本降权。原文特别说明：这比完整 RL 简单省钱，实践中对齐效果够用；GRPO 这类 RL 方法有额外收益但成本高，留给未来工作。

五、架构与 serving：打分头 + prefill-only

架构贴着基座走：decoder-only Transformer，加一个目录感知打分头，只对 Netflix 在库物品打分。推理管线三步：

flowchart LR
    V["Verbalizer<br/>历史 上下文 物品元数据<br/>序列化成单条文本"] --> LLM["LLM 前向一次<br/>取池化隐状态 h<br/>概括当前偏好与上下文"]
    LLM --> HEAD["打分头<br/>h 与物品嵌入做点积或小 MLP<br/>softmax 得到分布"]
    CAT["目录物品嵌入<br/>与主干联合训练"] --> HEAD
    HEAD --> RANK["排序输出<br/>天然不会幻觉出目录外物品"]
    style HEAD fill:#fff3cd
    style RANK fill:#e8f5e9

打分头这步设计得很实在：物品嵌入、打分头、主干联合训练；目录极大时用 sampled softmax 或候选集。由于分数只算在目录物品上，「幻觉出目录外内容」这个 LLM 推荐的老毛病在结构上就被掐死了——不需要后处理过滤。

Serving 在 Netflix 内部 LLM 栈上跑 vLLM。成本由三个因素驱动：模型大小、上下文长度、推理模式。对应三个手段：

小模型/蒸馏模型：用更小或蒸馏过的基座，配更大更针对性的数据，用更低的成本换大部分质量；
激进压缩上下文：就是第三节那套上下文工程；
prefill-only 推理：不对候选集做自回归解码（那在成本上是自杀），prompt 只消费一次，单次前向给整个候选集打完分。

第三条是整套方案能上线的关键。一个排序器如果按 LLM 聊天那种方式逐 token 生成推荐结果，账永远算不过来；把 LLM 当成「一次性编码器 + 打分头」，账就算过来了。

六、实验结果：少数据，反而赢

对照组是调了多年的生产排序器（数千个特征、定制架构）。结果分几层：

离线：用大约 40 分之一的 Phase-2 标注样本，MRR 反而高约 1.6%。继续加数据、加输入信号，指标继续涨。
线上 A/B：批量计算的推荐界面，约 10% 流量跑约 4 周，短期和长期指标均统计显著为正。
数据与模型 scaling：1B 和 10B 主干都随 Phase-2 数据量上涨，大模型绝对值更高、曲线形状相似；固定训练预算下，更大主干稳定更好——推荐也吃 scaling law。
Phase-1 vs 开源：用 Netflix 适配基座比直接用现成开源 LLM，离线指标高约 10%-20%。
Phase-2 vs Phase-1：在 Phase-1 刚训完的时间点，Phase-2 后训练带来 35%-50% 提升；Phase-1 越陈旧（新内容、口味漂移），Phase-2 相对收益越大，2 周后约 80%。这直接论证了两阶段划分的正确性。
数据效率：从强 Phase-1 出发，GenRec 用 10-40 倍更少的 Phase-2 标注样本追平或超过生产排序器——这点值钱在 Phase-2 更新频率高，标注效率直接决定迭代速度。
上下文压缩：清洗事件、找 MRR 对事件数的「肘点」、调措辞详略，三步下来 token 预算可以压到原来的三分之一左右，离线指标几乎不掉；serving 成本约与上下文长度成正比，所以成本也同比降。

七、更大的判断：从特征工程到上下文工程

原文最后一节不是在总结 GenRec，是在押注一个范式转移，四条：

特征工程 → 上下文工程：建模范畴从「设计特征」变成「决定哪些信号进上下文、回溯多久、怎么在 token 预算内压缩」。
定制架构 → 共享基座：双塔、DLRM、定制 attention 各立山头的时代，让位给「一个基座 + 数据与文本化策略 + 后训练目标 + 推理优化」的差异化。
Scaling law 成为设计指南：传统 RecSys 因为稀疏 ID、重工程、任务定制架构容易撞墙；LLM 化的推荐继承了清晰的数据和模型 scaling 行为，投入产出变得可规划。
RecSys 基建 → LLM 基建：GPU、vLLM/Triton、batching、caching——推荐 serving 越来越像通用 LLM serving。

工程实践联想

「prefill-only」是给 LLM 落地祛魅的一刀。 很多团队评估「LLM 进生产」时默认按生成式推理算账，结论当然是不划算。GenRec 的示范是：先问这个任务是不是真的需要逐 token 生成。排序、分类、匹配这类任务，LLM 的正确用法是当编码器，一次前向出全部结果——成本模型完全不同。
目录感知打分头是「防幻觉」的标准答案。 不要在生成端防幻觉再靠后处理拦截，把输出空间在结构上约束到合法集合（打分头、受限解码、枚举候选），比训一个「不幻觉的模型」可靠得多。这个模式放之四海皆准：凡是输出必须在闭集内的场景，都该这么干。
奖励加权是 RL 的穷人版，但可能够你用很久。 完整 RLHF/GRPO 的成本和组织复杂度劝退大多数团队；「独立奖励模型给样本算权重、乘进损失」用监督训练的工程成本拿到对齐收益的大部分。先把这条路走通，再谈要不要上 RL。
上下文工程是可以量化的工程，不是 prompt 玄学。 GenRec 把它做成了有肘点曲线、有详略实验、有三分之一预算硬指标的东西。做 RAG 的人应该直接抄这个流程：清洗事件 → 画「指标 vs 上下文量」曲线找肘点 → 在保留集合上调措辞密度。上下文不是越多越好，是有预算的。
「prompt 是新的特征向量」意味着你的特征基建要换。 特征平台管的是 Schema、版本、回填；上下文工程管的是文本化模板、压缩策略、共享前缀。如果你的推荐/排序团队还在纯特征工程范式里，GenRec 给出的信号是：下一个五年的技能树在后者。

本篇小结

GenRec 是什么：Netflix 的 LLM 排序器。文本化用户历史与上下文，在 Netflix 适配基座上做排序后训练，挂目录感知打分头，奖励加权对齐长期价值，prefill-only 推理控成本。
核心机制：两阶段（慢基座 + 快排序）、对话格式训练但非生成式推理、打分头把输出约束在目录内、奖励加权替代完整 RL。
关键数字：40 倍更少标注样本下 MRR +1.6%；Phase-1 基座 +10%-20%；Phase-2 +35%-50%（基座陈旧 2 周后 +80%）；上下文压到三分之一指标几乎不掉；10% 流量 4 周 A/B 短期长期均显著为正。
最大的启示：推荐的工程重心从特征工程转向上下文工程，「prompt 就是新的特征向量」；LLM 进排序系统的正确姿势是编码器 + 打分头，不是聊天生成。
保留意见：原文没给具体基座模型、参数量细节和线上指标绝对值，成本数字也只有相对比较；「match or exceed 生产系统」的结论目前只在批量计算界面上验证过，实时低延迟场景没提。

参考资料

原文：Ying Li, Arjun Rao, Shradha Sehgal, GenRec: Towards LLM-Native Recommendation at Netflix, Netflix TechBlog, 2026-07-30。
原文点名的相关 LLM 推荐工作：PLUM、GLIDE、OneRec-Think。
推理框架：vLLM（GenRec serving 所依赖）。
原文提及的 RL 方法：GRPO（Group Relative Policy Optimization，DeepSeekMath 论文提出）。

Netflix 自建 LLM 推理平台笔记：四个层层相扣的决策

Fri, 17 Jul 2026 10:00:00 +0800

Netflix 自建 LLM 推理平台笔记：四个层层相扣的决策

原文：In-House LLM Serving at Netflix（Netflix TechBlog，2026-07，AI Platform 的 Model Runtime 与 Inference 团队）目标读者：正在或准备自建 LLM 推理服务的工程师，尤其是要在"用托管 API"和"自己跑全栈"之间做取舍的团队。阅读目标：看清 Netflix 这套平台的四个核心决策（引擎、打包、API 面、发布）各自约束了什么，以及哪些坑是设计阶段想不到、只有生产流量能教会的。

〇、为什么不直接用托管 API

多数组织通过托管 API 消费 LLM，Netflix 选择在既有生产环境内跑全栈——从模型部署到推理，而不是另起一个 ML 孤岛。原文明确说：这篇文章只讲"曾经认真考虑过备选方案"的决策，而且重点是为什么这么选，以及生产暴露了哪些设计阶段没预料到的东西。这个姿态本身就值得学：决策文档的价值不在结论，在被否决的选项和事后才显形的代价。

一、架构总览：LLM 不是特例

Netflix 的会员规模 ML 由一个统一的 JVM serving 系统打头，负责路由、A/B 测试逻辑、候选生成、特征获取、推理、后处理和逐级日志，实时与离线批量缓存两条路径都支持。调用方到达推理有两条路：经 serving 系统的 gRPC 路径，以及新兴 LLM 应用用的直连 HTTP 路径。

推理在哪跑取决于模型大小：小的 CPU 模型直接在进程内跑，省掉远程调用开销；大模型需要 GPU，serving 系统本地做前后处理，把推理委托给远端服务 MSS（Model Scoring Service）。MSS 是共享推理后端，XGBoost、TensorFlow、PyTorch、LLM 全走同一套接口，底下是 NVIDIA Triton Inference Server 管模型加载、批处理和 GPU 调度。Triton 之上还有一个 Java 控制面，管部署、版本、健康检查、自动扩缩和多 region rollout——模型作者只管打包产物和配置，控制面负责 provisioning GPU 实例和零停机升级。

flowchart TD
    subgraph CALLER["调用方两条路径"]
        GRPC["gRPC 路径<br/>经 JVM serving 系统<br/>路由 A/B 特征 后处理 日志"]
        HTTP["HTTP 直连路径<br/>新兴 LLM 应用"]
    end
    subgraph MSS["MSS 共享推理后端<br/>XGBoost TF PyTorch LLM 统一接口"]
        TRITON["Triton Inference Server<br/>模型加载 批处理 GPU 调度"]
        CP["Java 控制面<br/>部署 版本 健康检查 扩缩 多 region"]
        CP --> TRITON
    end
    GRPC --> MSS
    HTTP --> TRITON
    INPROC["小模型 CPU 进程内推理"] -.->|"省远程调用开销"| GRPC
    style MSS fill:#e8f5e9

一句话：LLM 不做特殊雪花。XGBoost 集成和大型 LLM 用同一个 gRPC 调用打分，客户端库、健康检查、部署流水线全部复用。这个"不特殊化"原则后面会反复出现。

二、决策一：引擎从 TensorRT-LLM 换到 vLLM

平台最初建在 TensorRT-LLM 上——当时性能领先，且已和 Triton 集成。到 2025 年夏天两件事变了：开源引擎的性能差距基本抹平；工作负载也从单一形态扩展到 embedding 生成、ranking/retrieval 的 prefill-only 推理、自回归解码、以及带逐步约束逻辑的自定义模型。重新 benchmark 后选 vLLM 作为 paved-path 引擎，理由是运营契合度而非峰值性能：

自定义模型架构免多步编译流水线，非标模型迭代更快；
有自定义解码逻辑的扩展钩子（后面约束解码全靠它）；
可调试性好——编译型引擎里查失败和中间状态很痛；
研究侧很多同学本来就在用 vLLM，研究到生产的交接成本低。

注意选型口径：不是"谁快选谁"，是"谁在我们的负载组合 + 团队现状下总成本最低"。

三、决策二：打包方式，选 vLLM backend 但要锁版本

Triton 支持两种打包，区别在模型产物与前端升级的耦合紧度：

Python backend：作者在打包时显式定义输入输出 tensor 规格，规格冻结在产物里，必须和前端 request builder 的期望匹配——前端每次动 I/O 规格，打包代码都要配合改，否则运行时才挂。
vLLM backend：产物只有一个指向权重和 tokenizer 的 JSON 配置，I/O 规格由 Triton 在部署时动态生成。模型和前端各自独立演进。

vLLM backend 是架构上正确的默认，但生产咬了两口：

Triton 与 vLLM 版本漂移。Triton 的 vLLM backend 是针对特定 vLLM API 面编译的，一漂移就整个加载失败——真实案例是 Triton 25.09 还在 import vllm.engine.metrics，而这个模块在 vLLM 0.11.2 里已经删了。对策：烘焙镜像时锁死兼容版本对，并禁止模型作者在打包时覆盖 vLLM 版本。
自定义模型逻辑。vLLM backend 假设标准 HuggingFace 兼容模型并接管全生命周期；需要自定义前后处理、ensemble 流水线、非标 tokenization 的模型，只能退回 Python backend 拿 execute() 的完全控制权。这个逃生门对一部分模型会长期必要。

四、决策三：API 面——gRPC 不动，加一层 OpenAI 兼容前端

内部打分协议保持统一 gRPC 不变，但 OpenAI 兼容 API 已成 LLM 生态事实标准——推理引擎、编排框架、评估工具、客户端库全说它——所以平台把它作为附加前端暴露。回报体现在实验到生产的路径上：从托管模型毕业到自托管微调模型（为质量、延迟、成本或数据隐私），几乎是平滑迁移，同一套 API，代码改动极小。

实现上直接复用 NVIDIA 的 Triton OpenAI 兼容前端：内嵌一个 Triton server，用 TritonLLMEngine 把请求 schema 转成 Triton 推理请求，FastAPI 对外服务；KServe 的 HTTP/gRPC 前端同时开启，Java 控制面仍走 gRPC 访问同一实例。但直接采用暴露了一个缺口：response_format 字段 schema 里接受、实际在到达 vLLM 之前被静默丢弃——调用方以为自己要了 JSON 输出，实际没有任何 guided decoding 约束，拿到畸形 JSON 也收不到任何报错。Netflix 的解法是 git-subtree 掉这个前端并打补丁，在请求时把 response_format 翻译成 vLLM 的 guided decoding 参数。静默丢参数比报错危险得多，这是个通用教训。

五、决策四：发布策略——Red-Black 与 Versioned

GPU 部署拉起比 CPU 服务慢，模型版本间 I/O schema 还可能变，发布要解决的是"新版本上线不掉请求"。平台给两种策略：

flowchart TD
    Q["新版本要改 I/O schema 吗<br/>例如 tensor 维度变了"] -->|"否 接口稳定"| RB["Red-Black<br/>新旧并存 健康检查后分阶段切流<br/>新扩容与老缩容同速率 失败原子回滚"]
    Q -->|"是 无法避免"| V["Versioned<br/>每个 modelId + modelVersion 独立部署<br/>多版本同时在线服务"]
    RB --> RBGAP["已知缺口<br/>消费者要等新版全量才能改配置<br/>迁移窗口内老请求打到新部署会失败"]
    V --> VCOST["代价<br/>过渡期 GPU 成本临时上涨<br/>平台按闲置清理旧版本 但永远保留最新"]
    style RB fill:#e8f5e9
    style V fill:#fff3cd

Red-Black 的协调缺口很微妙：新版本要改 schema 时，上游消费者没法提前改配置（改了会打到还在线上的旧版），只能等新版全量后再切，于是迁移窗口内必然有"老请求打新部署"的失败。Versioned 用冗余部署彻底解耦模型发布与消费者更新。Netflix 的建议是把可变配置（如 tensor shape）直接嵌进推理模型让它版本无关，尽量走便宜的 Red-Black，Versioned 只留给接口变更无法避免的少数情况。

六、两个运维细节

启动序列。直接启动时从 S3 或 Hugging Face 拉大模型太慢，冷启动会超出调度器容忍度；对策是在模型"announce"时就把模型物化到 Amazon FSx，warm start 命中高性能文件系统而非对象存储。另外 OpenAI 兼容前端内嵌 Triton 还是独立跑 Triton，是打包时按部署配置的。其余步骤是机械的：解包、经 Python entry_points 装自定义 vLLM 插件、清理 Prometheus multiprocess 目录、引擎就绪前闸住 gRPC 端口。

统一 metrics 端点。vLLM 把指标写成 PROMETHEUS_MULTIPROC_DIR 下的 .db 文件，Triton 走自己的 Prometheus 端点，两边互不知情；Triton 内置桥接只暴露 40 多个 vLLM 指标里的 9 个，token 吞吐、KV cache 利用率、prefix cache 命中率这些关键指标全缺。解法是加了一个轻量 HTTP 代理：HTTP 拉 Triton 指标，用 MultiProcessCollector 从磁盘读 vLLM 指标，合并成单个 /metrics 输出——存量 dashboard 和告警零改动。

七、深水区：约束解码的规模问题

这是最硬核的一节。Netflix 一些生产负载需要细粒度控制 token 生成，思路是把约束推进解码循环内部——不为非法生成付钱再重试或修补，而是让模型"构造性地"生成合规输出。实现走 vLLM 的自定义 logits processor 接口：每个约束建模为随已生成 token 历史演进的状态机，每步吐出 token 可用性掩码；每个请求配自己的 processor 实例，因为不同请求规则不同。

V0 为什么撑不住：初版纯 Python 实现功能正确，但 vLLM V0 里自定义 logits processor 是逐请求跑的——GPU 为整个 batch 算出 logits，CPU 拷贝过来等传输完，然后串行对每个请求跑约束逻辑（GIL 挡住了并行）。CPU 耗时随 batch 线性增长，尾延迟爆炸，端到端变成 CPU-bound，尽管 GPU 前向是高效批处理的。这个瓶颈在单请求 benchmark 里完全不可见，只在真实并发下现形。

V1 的结构修复（2025 Q4 迁移）：vLLM V1 把 logits 处理提升到批级，processor 改写为对批级数据结构操作、跨请求一起算掩码，热路径用 C++ 多线程重写绕过 GIL。代价是 V1 API 要求经 update_state(batch_update) 显式跟踪 batch 成员变化——比 V0 的逐请求接口复杂，但动态演化的 batch 里要维持正确状态别无选择。效果是 logits 处理时间随 batch 增长保持平坦。

两个设计阶段没想到的状态陷阱：

Partial prefill：V1 做 chunked prefill，一个请求可能跨多个引擎 step 才填完，而 BatchUpdate 的粒度分不清"填完了"还是"填了一半"，只能内部自己跟踪。
Preemption：显存压力下 vLLM 可能逐出半完成请求的 KV cache，之后带着不同的 prompt 和输出 token 列表重新调度——这直接打破状态机"输出 token 列表单调增长"的假设。对策是检测 token 历史在解码步之间变短，发现就重置状态机、按新 prompt 重新初始化。

八、工程实践联想

单请求 benchmark 会撒谎。 V0 约束解码的瓶颈只在真实并发下出现——GPU 批处理越高效，串行 CPU 段相对越刺眼（阿姆达尔定律的实战版）。凡是有"批 GPU + 逐请求 CPU"形态的系统，压测必须带真实并发模型，否则上线即踩雷。
生态兼容比自研协议值钱。 OpenAI 兼容前端让"托管换自托管"几乎零成本，本质是买了个退出期权。但采用第三方组件时要主动审计静默行为——response_format 那种"schema 接受、执行丢弃"的缺口，只有端到端验证能抓到，类型系统和 schema 校验都救不了你。
锁版本不是洁癖，是边界合同。 Triton 25.09 对 vLLM 0.11.2 的事故说明：两个各自快速迭代的组件之间，API 面就是合同，合同必须显式 pin 住，且要封死用户绕过 pin 的后门（禁止打包时覆盖版本）。
接口变更的协调成本要摆上台面。 Red-Black 的"老请求打新部署"缺口是典型的分布式系统两将军问题变体；Versioned 用资源换解耦是标准解法，但更便宜的做法是从源头消灭破坏式变更——把可变配置嵌进模型。设计 schema 时就该问：这个字段未来变了，谁要协调谁？
有状态逻辑要对底层语义变更做回归审计。 partial prefill 和 preemption 两个坑，根因都是状态机的隐含假设（一次填完、token 单调增长）被引擎新语义打破。引擎升级时不只跑功能测试，要把每条状态假设列出来逐条对账。

本篇小结

Netflix 在既有 JVM serving 体系内自建 LLM 推理全栈，核心原则是 LLM 不做特例：所有模型统一 gRPC 打分，共享 MSS + Triton + Java 控制面。
四个决策层层相扣：引擎选 vLLM（运营契合度胜过峰值性能）→ 打包选 Triton vLLM backend（I/O 规格部署时动态生成，代价是版本锁死，自定义模型留 Python backend 逃生门）→ API 面加 OpenAI 兼容前端（顺手修了 response_format 静默丢失）→ 发布双策略 Red-Black / Versioned 应对 schema 变更协调。
运维两个坑：模型先物化到 FSx 解决冷启动；自建代理合并 Triton 与 vLLM 双 metrics 源（官方桥接只暴露 9/40+ 指标）。
约束解码是全文精华：约束建模为状态机 + 逐步 token 掩码；V0 逐请求串行被 GIL 卡死、CPU 随 batch 线性增长，V1 批级化 + C++ 热路径后耗时拉平；partial prefill 与 preemption 两个状态陷阱靠内部跟踪和"token 历史缩短即重置"解决。
后续方向：system prompt 压缩、vLLM V1 异步调度、logits processor 向量化成 GPU 融合算子、低精度模型变体。
全文最值得带走的元教训：设计评审看不出这些坑，生产负载是最终的验收测试——所以平台要为"发现设计阶段想不到的问题"留好观测口和逃生门。

参考资料

In-House LLM Serving at Netflix，Netflix TechBlog，2026-07-17（原文）。
vLLM：开源 LLM 推理引擎，本文的 paved-path 选择。
NVIDIA Triton Inference Server：MSS 底层的模型加载、批处理与 GPU 调度层。
TensorRT-LLM：平台初代引擎，被替换前的 baseline。
KServe：与 OpenAI 前端并置启用的 HTTP/gRPC 前端。
Amazon FSx：模型物化的高性能文件系统，用于压低冷启动。

GenPage 学习笔记：Netflix 用一个 Transformer 直接生成整个首页

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

GenPage 学习笔记：Netflix 用一个 Transformer 直接生成整个首页

原文：GenPage: Towards End-to-End Generative Homepage Construction at Netflix 目标读者：做推荐、搜推广或 AI 工程的工程师；也适合想看「LLM 范式怎么落进重工业级在线系统」的人。阅读目标：搞清楚两件事——GenPage 怎么把「首页构建」改写成「序列生成」问题，以及为了让这个改写扛住生产环境，他们必须解决哪几个工程难题。

一、问题的改写：从多级流水线到一次生成

Netflix 首页不是一个列表，是一个二维结构：哪些行出现、每行里放哪些实体、整体怎么排版，几乎全都个性化。传统做法是多级流水线——行级和实体级各自有召回与排序组件，模型多、阶段之间的优化目标互相对不齐，特征工程沉重。

GenPage 的改写只有一句话：把用户历史和请求上下文当作 prompt，自回归生成整个首页作为 response。 要回答的问题从「给这个候选打多少分」变成：

已知关于这个用户和这次请求的一切，应该生成什么样的首页来最大化用户满意度？

和 TIGER、HSTU、OneRec 这些只生成扁平排序列表的生成式推荐不同，GenPage 把行、实体、布局一起生成。动机四条：端到端建模（一个 transformer 替代多级堆栈，砍掉阶段间目标错位和大量特征工程）；整页级 RL 优化（捕捉行与实体之间的交互，比如顶部的 Continue Watching 满足即时意图但会压低整页浏览深度）；更好的 scaling 行为；以及对新产品形态（直播、游戏、播客、个性化 UI、逐实体艺术图）的扩展性。

先说成绩再放细节：线上 A/B 对一个成熟、高度优化的多级生产系统，核心用户参与指标统计显著提升（p ＜ 0.001），同时端到端 serving 延迟降了 20%。

二、数据：自建 tokenizer，把首页变成一门语言

从传统推荐迁到生成式 transformer，第一件事是重新想数据表示。GenPage 把上下文和首页都编码成一条离散 token 序列。每个训练样本对应一次首页曝光，由三部分组成：Context（用户行为历史、档案属性、请求上下文）、Page（页面上展示的行和实体，按布局顺序）、Feedback（用户与页面的交互）。只有前两者进入 token 化，Feedback 交给奖励系统产生监督信号。

他们没有用现成的文本 tokenizer，而是为首页数据建了领域专用 tokenizer，换来两个关键优势：

计算效率。举例：「用户 30 天前看了 50 分钟《女子监狱》」这件事，GPT-5 tokenizer 要 16 个 token，他们的方案压到 4 个——[Entity_ID]、[Action_Type]、[Action_Time_Bucket]、[Action_Duration_Bucket]。序列变短直接降低推理成本和延迟。
产品控制。token 和产品概念（行、实体）一一对应，给业务规则的执行留了一个干净的接口（第五节会看到这条多值钱）。

上下文 token 里，用户历史表示为动作序列（显式信号如播放、加片单、点赞，隐式信号如预告片观看、详情页访问），档案 token 编码语言与 profile 类型，请求上下文 token 编码时段、星期几、设备。太长的数据源（比如完整曝光历史）用摘要版本——作者坦白这是手工痕迹，本质是把 prompt engineering 塞回了流水线，端到端学压缩是未来方向。各段之间插特殊 token 作分隔，连续信号（时间戳、时长）分桶离散化。

页面 token 侧：每个实体、每个行各是一个 token，首页按从左到右、从上到下序列化。词表每日更新纳新；服务时仍不在词表里的实体，靠语义 embedding 融合和 fallback token 处理（见第五节）。分页推荐也自然落在范式里：每次翻页请求前，把已生成行的 page token 连同用户在这些行上的最新实时行为追加进 prompt，模型同时看到长期偏好和会话内行为。

三、奖励系统：一个标量，两种用法

监督信号来自 Netflix 内部的奖励系统（既有工作，通过线上 A/B 调参对齐长期满意度）：给页面上每个曝光实体打一个标量奖励——通宵刷完的剧比看了 10 分钟的电影奖励高，被曝光后放弃的实体拿负奖励。页面级奖励定义为页面上所有曝光实体奖励之和。 这个标量同时喂给监督后训练和 RL，但用法不同，见下。

四、模型与训练：LLM 配方照搬到推荐

架构是标准的 decoder-only transformer，理由是简单、灵活、能吃整个 transformer 训练与 serving 生态。有一个值得记的细节：输入 embedding 和输出投影不共享权重（untie）——预训练优化的是词表上的 softmax，WBC 后训练优化的是逐 token 的 sigmoid 分数，两种目标对 logits 的要求不同，解绑给模型留出兼顾的余地。

训练配方照搬 LLM：先预训练教模型「首页这门语言」，再后训练对齐用户满意度。

预训练（next-token prediction）：只用线上拿到正反馈的曝光样本，让模型 bootstrap 出模仿现有生产系统的能力。作者特意澄清：样本形态其实更像 LLM 的 SFT 对而不是裸文本预训练，叫它预训练是因为从零训练而非微调。局限也直说：预训练只教模仿，不优化奖励幅度；而且模型上线后反复在自己生成的页面上训练，有退化风险——所以要后训练。
后训练之 WBC（weighted binary classification）：把生成变成 token 级价值预测。自定义 tokenization 在这里再次兑现——每个页面 token 直接对应一个实体或行，奖励可以干净地挂上去：奖励的符号给二分类标签（正参与 vs 放弃），幅度给权重（通宵刷剧权重高于短播放），对对应 token 的 logit 优化加权二分类交叉熵。此时 logit 可解释为「在这个位置生成这个 token 的价值估计」。推理时贪心逐 token 取最高价值。优点是构造上自带 token 级 credit assignment，不用像 RL 那样去推断每个决策对最终页面奖励的贡献。
后训练之 RL：把页面生成当序列决策，直接优化页面级奖励。借鉴 RLHF 两步走：先训一个 transformer 奖励模型，预测生成页面的页面级奖励（以实体奖励之和为监督目标；注意它和奖励系统是两回事——奖励系统处理真实曝光的反馈，奖励模型不用真把页面给用户看，这让 RL 能对任意候选页面打分）；再用 Dr. GRPO 优化策略，并用 KL 惩罚把策略锚在预训练 checkpoint 附近——奖励模型只在生产策略生成的页面附近可靠，KL 约束既把页面留在奖励模型的覆盖区内，也压制 reward hacking。另加规则化的 format rewards：页面得长得像行的列表，业务关键的行和实体不能排太靠下。

RL 相对 WBC 多开三扇门：整页优化（多样性、stopping power、页面级业务约束都能进奖励）；test-time reasoning（推理输出可看作自动化特征工程）；多 token 实体支持——若实体要用多个 token 表示（如 [Show_ID] 加 [Episode_#]），WBC 的逐 token 标注会有歧义（一个实体级奖励怎么摊到多个 token 上），RL 优化序列级 return 天然绕开这个问题。

flowchart TD
    subgraph DATA["训练样本: 一次首页曝光"]
        CTX["上下文 token<br/>用户历史 档案 请求上下文"]
        PAGE["页面 token<br/>行与实体 按布局顺序序列化"]
        FB["用户反馈<br/>播放 点赞 放弃"]
    end
    CTX --> PRE["预训练<br/>next-token prediction<br/>只用正反馈样本"]
    PAGE --> PRE
    FB --> RS["奖励系统<br/>每个曝光实体一个标量奖励"]
    PRE --> WBC["后训练 WBC<br/>符号作标签 幅度作权重<br/>加权二分类交叉熵"]
    RS --> WBC
    RS --> RM["奖励模型<br/>预测生成页面的页面级奖励"]
    RM --> RL["后训练 RL<br/>Dr. GRPO 加 format rewards"]
    PRE --> RL
    RL -.->|"KL 惩罚锚定预训练 checkpoint<br/>防 reward hacking"| PRE
    style PRE fill:#fff3cd
    style RL fill:#e8f5e9

五、上线要解决的四个工程问题

范式讲得再漂亮，进不了生产都是纸上谈兵。原文列的四个难题，恰好是每个想把生成式推荐搬上线的团队都会撞上的：

实体冷启动。新内容没有交互数据，token embedding 学不出来。两个互补策略：context injection——把新实体或时效实体（如 Live Now 赛事）的元数据直接注入上下文 token；semantic embedding fusion——实体表示改为 ID embedding 与内容 embedding（来自简介、演职员、字幕、类型、视频内容）的融合，训练时以小概率把实体 ID token 随机换成通用 fallback token，逼模型学会只靠内容 embedding 做推荐。效果：新实体的内容元数据一到，它在潜在空间里立刻就有有意义的表示，不等交互数据。
模型新鲜度。每天从头重训大 transformer 不现实，但推荐模型必须跟上趋势和新片入库。方案是 multi-cadence incremental training：大周期在全量历史窗口上做完整预训练加后训练；两次大周期之间，每天从昨天的 checkpoint 继续后训练，数据用最新一天加历史采样的混合，防过拟合和灾难性遗忘。每日新进词表的 token 用同类型 fallback token 初始化（如新行用 [Row_Fallback_Token]），训练时随机把少量已知 token 替换成 fallback，教模型优雅处理未知 token。
业务规则。首页必须满足结构约束（行的列表）和产品逻辑（去重、行钉位置、类目一致性——喜剧行里必须都是喜剧）。训练信号只能鼓励服从，不能保证。所以规则在推理时强制执行：constrained decoding，每个自回归步先算出合规 token 的掩码打到 logits 上。自定义 tokenization 让这件事格外便宜——实体和行都是单 token，业务规则直接映射成 token 级掩码，没有文本词表上多 token 记账的麻烦。钉行就是把那个位置其他 token 全 mask 掉。
推理延迟。逐 token 生成整个页面太贵。利用首页结构做 hybrid row decoding：每行只有前几个实体（用户注意力最集中、决定行质感的位置）自回归生成，然后基于这个前缀做一次前向，拿到所有合格实体的 logits，按分数补齐该行其余位置，同样受业务规则约束。自回归条件性保留在最值钱的地方，长行的逐 token 解码成本省掉了。

flowchart LR
    REQ["请求"] --> CTX2["构造上下文 token<br/>含会话内最新行为"]
    CTX2 --> GEN["自回归生成<br/>每行只生成前几个实体"]
    GEN --> MASK["约束解码<br/>业务规则映射为 token 掩码"]
    MASK --> GEN
    GEN --> FILL["整行补齐<br/>一次前向取全部合格实体<br/>按分数补满该行"]
    FILL --> OUT["输出首页若干行"]
    OUT -.->|"翻页时把已生成行和最新行为<br/>追加回 prompt"| CTX2
    style MASK fill:#fff3cd

六、离线实验：真正起作用的是什么

消融在 Netflix 内部数据上做，模型约 200M 参数，只报各研究内部的相对比较。四个问题，四个答案：

预训练有用吗？ 有。WBC 前加不加预训练对比，全指标显著提升。Entity AUC 从 0.91 到 0.92 看着小，翻译过来是随机正负实体对的错排率从 9% 降到 8%——成熟生产系统上单点改动罕见的幅度。
模型规模怎么 scale？ 从约 120M 扫到约 900M 参数，预训练 loss 和 WBC loss 都呈幂律下降，和 LLM 的 scaling 行为同构。
上下文信息怎么 scale？ 固定模型规模，持续丰富 prompt（加新数据源加改进 tokenization），WBC loss 大幅下降。两组扫描不严格可比，但差距悬殊：模型扩约 7.5 倍只降 WBC loss 约 1.3%，上下文富化累计降约 6.9%，好几次单次设计良好的上下文加入就超过整轮扩容。结论：当前阶段个性化质量的瓶颈首先是模型能看到的信息和表示，其次才是容量；等上下文榨干了，容量才会成为主驱动。
RL 真在做页面级优化吗？ 页面奖励持续提升（作者承认这条基本是 confirmatory——奖励和策略优化用的是同一个模型）。更有意思的副产品：多样性根本不在 RL 目标里，但页面多样性（页内实体两两 embedding 距离）随训练上升——策略在整页层面优化，而不是孤立地抠每个 token。

七、线上 A/B 与意外发现

线上对生产基线的 A/B 里，GenPage 在既有候选集上解码（候选集顺便处理掉大量资格类业务规则）。几个观察都值得记：

所有训练数据配置不同的变体都在核心指标上显著提升，增益对设计选择鲁棒，不依赖某个特定配置。
出现了非预期的曝光类目分布漂移（新内容 vs 老内容、剧集 vs 电影）。作者的诊断很诚实：这大概是 GenPage 个性化更锐利的表现——首页 impression 效率上升，用户用更少曝光完成参与；而更锐利的个性化把从生产系统继承来的组件（比如奖励系统）尚未与新范式对齐的问题暴露了出来。
会话内响应性强且自然：最新行为迅速影响后续推荐，一两天后淡回长期偏好——模型自己在 attend 动作时间戳，生产栈里要靠大量手工特征工程才能做到的事，在生成式范式里涌现出来。
延迟降 20%，和「生成式一定慢」的直觉相反：多个排序阶段和重特征计算被一个跑在原始 token 上的 transformer 取代，自定义 tokenization 与 hybrid decoding 再压缩了解码步数。作者强调这还没压榨完，余量可以再投给容量或更富的 prompt。

工程实践联想

prompt 工程是新的特征工程，而且 ROI 可能更高。 6.9% 对 1.3% 这组数字值得贴在每个推荐团队的墙上：在堆模型容量之前，先问自己信息瓶颈有没有解决——模型看不见的信号，再大的容量也学不到。这和我们日常给 LLM 应用调 prompt 的经验完全同构：多数时候收益不在换更大的模型，在把上下文喂对。
自定义 tokenizer 本质是一次领域建模。 4 token 对 16 token 的压缩只是表面收益，真正值钱的是「token 与产品概念一一对应」——它让业务规则从模型输出后的事后修补，变成解码期的一层掩码。凡是需要严格控制生成内容的场景（合规、结构约束、配额），这个思路可以直接搬：把控制点设计进词表，而不是指望 prompt 约束。
规则兜底放在解码时，别指望训练。 训练信号只能鼓励、不能保证——这句坦白适用于所有生成式系统。凡是硬约束（不能出现的内容、必须出现的位置），都应该有推理期的机制级保障，RLHF 式的软对齐管软偏好。
模仿学习起步、对齐训练接棒，是离线冷启动新系统的通用配方。 先用生产系统的正反馈样本 bootstrap，避开没有策略就没有数据的死锁；再承认模仿的天花板（不优化奖励幅度、自蒸馏会退化），用后训练接棒。WBC 和 RL 的二选一也很务实：先用简单可优化的对齐拿下实体级指标，把 RL 留给页面级目标，不上来就啃最硬的。
「单模型替代流水线」的延迟账要重新算。 直觉上生成式更慢，实际是把 N 个模型加 N 套特征计算换成一次前向序列。系统总成本从来不在单个模型的 FLOPs 上，在组件数量、数据依赖和特征管线上——架构简化的收益经常大于模型本身的开销。

本篇小结

问题改写：首页构建从「多级召回排序」改写为「prompt 进、页面出」的自回归序列生成，行、实体、布局一次生成；这是与 TIGER、HSTU、OneRec 等扁平列表生成式推荐的分界。
数据：领域专用 tokenizer 把上下文和页面编码成一条 token 序列，换来 4 倍级序列压缩和「token 即产品概念」的控制接口；反馈不进序列，进奖励系统。
训练：照搬 LLM 配方——正反馈样本上 next-token 预训练，后训练二选一：WBC（token 级价值预测，自带 credit assignment）或 RL（奖励模型 + Dr. GRPO + KL 锚定，解锁整页优化、test-time reasoning、多 token 实体）。
上线四件套：冷启动靠 context injection 加 semantic embedding fusion；新鲜度靠多节奏增量训练加 fallback token；业务规则靠 constrained decoding（规则即 token 掩码）；延迟靠 hybrid row decoding（每行只自回归前几个实体）。
核心结论：线上核心指标显著优于成熟多级基线且延迟降 20%；离线两条最值得记——丰富 prompt 的收益远大于模型扩容（6.9% 对 1.3%），RL 在不含多样性目标时反而提升了页面多样性。
未竟之事：长上下文仍靠手工摘要，语言、多模态、reasoning 能力尚未接入；作者看好的方向是领域 token 与通用文本 token 的混合 tokenization——概念上等于给 LLM 增加一个「推荐模态」，LLM 和推荐系统的边界会继续模糊。

这篇最打动我的不是架构，是那份诚实：明说预训练样本其实更像 SFT，明说长上下文还是手工摘要，明说奖励提升是 confirmatory，明说线上出现了没优化的分布漂移。工业系统的论文能写到这个坦白程度，比指标本身更值得学。

参考资料

Lequn Wang, Jiangwei Pan, Linas Baltrunas, GenPage: Towards End-to-End Generative Homepage Construction at Netflix, Netflix TechBlog, 2026-06（本文唯一原文来源）。
原文提及的对照工作：TIGER、HSTU、OneRec（生成扁平排序列表的生成式推荐系统）。
原文提及的 RL 算法：Dr. GRPO（GRPO 的变体，缓解训练目标中的偏差）。

Agent Memory 科普：用 Mem0 给 AI 加上长时记忆

Fri, 26 Jun 2026 10:00:00 +0800

Agent Memory 科普：用 Mem0 给 AI 加上长时记忆

做 AI 应用时，经常会遇到一个尴尬：用户上一句还在说「我 gluten-free」，下一句推荐餐厅时模型就忘了。上下文窗口再长也解决不了「跨会话记忆」的问题，这就需要 Agent Memory。

一、为什么需要 Agent Memory？

大语言模型有两个和记忆相关的瓶颈：

上下文窗口有限：模型只能看到当前输入的若干 token，超出部分会被截断或遗忘。
无法跨会话保留信息：每次对话都是独立请求，模型不会记住你上周说过的话。

Agent Memory 就是用来解决这些问题的：它把重要信息从对话中提取出来，持久化存储，在后续交互中按需召回。

二、记忆的分类

记忆通常可以分为短期记忆和长期记忆两大类。

2.1 短期记忆

语义缓存：临时把刚刚检索到的外部知识（比如 RAG 召回结果）放在当前上下文里。
工作记忆：当前会话的临时工作区，会话结束后清除。

短期记忆主要依赖上下文窗口，属于「基于会话」的记忆。

2.2 长期记忆

程序性记忆（Procedural）：工作流、工具调用、技能等执行层面的记忆。
语义记忆（Semantic）：知识库、个人信息、实体（人物、地点、组织）等事实性记忆。
情景记忆（Episodic）：某次对话的摘要、经历、事件细节。

长期记忆需要外部存储，并且能被检索和更新。

三、Agent Memory 项目概览

目前社区里有一些比较有代表性的记忆项目：

项目	核心特点
Text2Mem	给所有记忆系统定义「操作指令集」，12 个原子操作 + 五元 JSON 契约 + 双层验证
Mem0	GitHub Star 最多的记忆中间件，5 个工厂 / 双存储 / 三种记忆类型
Letta	把 OS 虚拟内存思想搬进 Agent，Git 版本化记忆 + Sleeptime 异步后台学习
ReMe	阿里 AgentScope 出品，「文件即记忆」，记忆对用户完全透明可直接编辑
memU	让记忆本身变成一个 24/7 后台主动 Agent

这篇文章重点介绍 Mem0，因为它是目前工程化落地最方便、生态最好的一个。

四、Mem0 简介

Mem0 是一个为大模型应用设计的长时记忆中间件。它把「记忆」这件事从业务代码中抽离出来，变成一个独立、可配置的组件。

简单理解，Mem0 在 LLM 和向量数据库之间加了一层「记忆管理层」。你只需要调用统一的 Memory 接口去 add、search、get_all，底层用的是哪家向量库、哪个 Embedding 服务、是否接图数据库，它都帮你封装好了。

4.1 核心架构

Mem0 主要由三部分组成：

Embedder（向量化模块）：支持 OpenAI、Ollama、HuggingFace、Azure OpenAI、Gemini 等。
VectorStore（向量存储）：支持 Upstash Vector、Qdrant、OpenSearch、PGVector、Milvus、Chroma 等。
Memory 层：对外暴露统一的 Memory / AsyncMemory 类，负责把对话、事件等转换成向量并写入/读出，同时可选接入图数据库和本地 SQLite 历史库。

4.2 一个最小 Demo

下面是用 Upstash Vector 做向量库、vLLM 部署大模型和 Embedding 模型的最小示例：

from mem0 import Memory

config = {
    "embedder": {
        "provider": "openai",
        "config": {
            "api_key": "EMPTY",
            "openai_base_url": "http://localhost:5001/v1",
            "model": "custom_embedding",
        },
    },
    "vector_store": {
        "provider": "upstash_vector",
        "config": {
            "url": "xxx",
            "token": "xxx",
            "collection_name": "memory_test",
            "enable_embeddings": False,
        }
    },
    "llm": {
        "provider": "vllm",
        "config": {
            "model": "qwen25",
            "vllm_base_url": "http://localhost:5002/v1",
            "api_key": "EMPTY",
        },
    },
}

memory = Memory.from_config(config)
conversation_history = []

def chat_with_memories(user_input: str, user_id: str = "default_user") -> str:
    # 1. 先检索相关记忆
    relevant_memories = memory.search(query=user_input, user_id=user_id, limit=3)
    memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories["results"])
    system_prompt = f"You are a helpful AI. Answer based on query and memories.\nUser Memories:\n{memories_str}"

    # 2. 调用 LLM 生成回复
    messages = [{"role": "system", "content": system_prompt}]
    messages.extend(conversation_history)
    messages.append({"role": "user", "content": user_input})
    assistant_response = call_llm(messages=messages)

    conversation_history.append({"role": "user", "content": user_input})
    conversation_history.append({"role": "assistant", "content": assistant_response})

    # 3. 把对话写回记忆库
    memory.add(messages, user_id=user_id)
    return assistant_response

这个 Demo 展示了 Mem0 最核心的用法：

search：在回复前检索相关记忆。
add：把对话写回记忆库，让 LLM 自动抽取事实。

五、Mem0 的适配逻辑

Memory.from_config(config) 初始化时，会同时初始化多个组件：

class Memory(MemoryBase):
    def __init__(self, config: MemoryConfig = MemoryConfig()):
        self.config = config
        self.embedding_model = EmbedderFactory.create(...)
        self.vector_store = VectorStoreFactory.create(...)
        self.llm = LlmFactory.create(...)
        self.db = SQLiteManager(self.config.history_db_path)

5.1 数据库适配

VectorStoreFactory 通过一个 provider_to_class 映射，把 provider 名称映射到对应的向量库类：

class VectorStoreFactory:
    provider_to_class = {
        "qdrant": "mem0.vector_stores.qdrant.Qdrant",
        "chroma": "mem0.vector_stores.chroma.ChromaDB",
        "pgvector": "mem0.vector_stores.pgvector.PGVector",
        "upstash_vector": "mem0.vector_stores.upstash_vector.UpstashVector",
        ...
    }

只要实现 VectorStoreBase 的抽象方法，就可以接入自定义向量库。

5.2 LLM 适配

LlmFactory 除了返回模型类，还会返回对应的配置类：

class LlmFactory:
    provider_to_class = {
        "ollama": ("mem0.llms.ollama.OllamaLLM", OllamaConfig),
        "openai": ("mem0.llms.openai.OpenAILLM", OpenAIConfig),
        "vllm": ("mem0.llms.vllm.VllmLLM", VllmConfig),
        ...
    }

以 VllmConfig 为例，它的 temperature 默认是 0.1，top_p 默认是 0.1，说明 Mem0 官方推荐记忆操作尽量保持确定性，避免随机性导致记忆抽取不一致。

5.3 Embedding 适配

EmbedderFactory 同样用 provider 映射实现：

class EmbedderFactory:
    provider_to_class = {
        "openai": "mem0.embeddings.openai.OpenAIEmbedding",
        "ollama": "mem0.embeddings.ollama.OllamaEmbedding",
        "huggingface": "mem0.embeddings.huggingface.HuggingFaceEmbedding",
        ...
    }

因为 vLLM 兼容 OpenAI 协议，所以部署本地 Embedding 模型时可以直接配置 provider: openai。

六、Mem0 的核心流程

Mem0 最重要的两个函数是 search 和 add。

6.1 search：检索记忆

search 的逻辑很直接：

把 query 转成 embedding 向量。
在向量库中按 user_id / agent_id / run_id 过滤后做相似度搜索。
如果配置了 reranker，对结果做重排序。
可选启用图存储，同时检索实体/关系。

def _search_vector_store(self, query, filters, limit, threshold=None):
    embeddings = self.embedding_model.embed(query, "search")
    memories = self.vector_store.search(
        query=query, vectors=embeddings, limit=limit, filters=filters
    )
    # 整理结果，过滤低于 threshold 的项
    ...

6.2 add：写入记忆

add 是 Mem0 最复杂的函数。它会先让 LLM 从对话中抽取事实，再决定每条事实应该新增、更新、删除还是保持不变。

第一步：事实抽取

Mem0 会根据是否有 agent_id 以及消息角色，选择不同的抽取 prompt：

用户记忆抽取 prompt：只从用户消息中提取事实，比如个人偏好、计划、职业信息等。
助手记忆抽取 prompt：只从助手消息中提取事实，比如助手的偏好、能力、性格特征等。

返回格式是一个 JSON：

{"facts": ["姓名是 John", "正在旧金山找餐厅"]}

第二步：冲突检测与决策

对每个新事实，Mem0 会在向量库中搜索相似的已有记忆，然后把「新事实 + 已有记忆」一起交给 LLM，让它判断每条记忆应该执行：

ADD：新增一条记忆。
UPDATE：更新已有记忆。
DELETE：删除矛盾或过时的记忆。
NONE：无需变更。

为了避免 LLM 幻觉 UUID，Mem0 会把已有记忆的 UUID 映射成 0, 1, 2... 这样的临时 ID，LLM 决策后再映射回真实 ID 执行操作。

6.3 流程记忆（Procedural Memory）

Mem0 还有一种特殊的 procedural_memory，专门面向多步任务 Agent。它记录的是：

任务目标与当前进度
按序执行的每一步动作
每步动作的原始输出
关键发现、浏览历史、错误与挑战
当前上下文与下一步计划

这种记忆适合需要跨多轮继续执行的复杂任务，比如自动化网页操作、数据采集等。

七、Mem0 的优势与适用场景

7.1 优势

接口简单：add / search / get_all 就能覆盖大部分需求。
解耦底层：向量库、Embedding、LLM 都可以替换。
自动抽取与消冲突：不需要自己写事实抽取和去重逻辑。
工程化友好：配置驱动，容易接入现有项目。

7.2 适用场景

多轮对话助手：记住用户偏好、历史需求。
个性化推荐/客服：结合用户画像做推荐。
多步任务 Agent：记录任务进度和中间结果。
知识库 + 用户偏好结合：既检索文档，也记住用户个人情况。

八、与其他记忆项目的关系

Agent Memory 是一个正在快速发展的领域，不同项目侧重点不同：

如果你需要快速落地一个带记忆的 LLM 应用，Mem0 是目前最稳妥的选择。
如果你需要严格的记忆操作语义，可以关注 Text2Mem。
如果你需要版本化和后台学习，Letta 更有趣。
如果你希望记忆对用户透明可编辑，ReMe 是另一种思路。
如果你希望记忆本身变成主动 Agent，memU 的方向更激进。

九、总结

Agent Memory 是 LLM 应用从「一次性问答」进化到「长期陪伴型产品」的关键基础设施。Mem0 把这个能力做成了一个可插拔的中间件：

统一接口：add / search / get_all。
三层解耦：Embedder、VectorStore、LLM 自由组合。
LLM 驱动：自动抽取事实、检测冲突、决定增删改。
三种记忆：语义记忆、情景记忆、流程记忆，覆盖不同场景。

对于需要长期记忆的 AI 应用来说，Mem0 是一个值得优先考虑的底座。

参考：Mem0 官方文档与 GitHub 仓库

方糖猫 AI 视频平台：ReAct Agent 任务规划实战

Tue, 23 Jun 2026 10:00:00 +0800

方糖猫 AI 视频平台：ReAct Agent 任务规划实战

在方糖猫项目中，我们面对的是这样一个问题：用户输入一段文案，系统需要在几分钟内自动完成素材检索、脚本生成、视频渲染和后期处理，输出一条可发布的短视频。这个链路很长、步骤之间依赖复杂、失败场景多。我们最终选择用 ReAct Agent 来编排整个生成流程。这篇文章会还原当时的设计思路、关键实现和踩过的坑。

一、业务场景：为什么不是简单流水线？

短视频自动生成的典型流程大致如下：

flowchart LR
    A["文案输入"] --> B["素材检索"] --> C["故事板生成"] --> D["配音/字幕"] --> E["视频渲染"] --> F["FFmpeg 后处理"] --> G["成片"]

最直觉的做法是用一个硬编码的工作流引擎按顺序执行每个步骤。但我们很快发现几个问题：

步骤之间的依赖不是固定的。比如某些文案不需要 B-roll，某些素材缺失时需要回退到文字卡片，某些场景需要先合成配音再决定画面节奏。
失败恢复成本高。渲染失败后要重试还是跳过？素材检索为空时是终止还是换关键词重搜？每个决策点都需要上下文。
未来要支持更多视频类型。口播、科普、剧情、产品介绍，每种类型的工作流差异很大，硬编码会迅速失控。

所以我们需要一个能够根据输入动态决策、具备工具调用能力、失败后能自主重试或降级的编排机制。ReAct Agent 是其中一个可行方案。

二、ReAct Agent 的核心设计

2.1 任务拆解

我们把整个生成流程拆成 6 个核心步骤，每个步骤对应一个 Agent 任务：

任务	职责	关键输出
`AnalyzeIntent`	理解文案意图、视频类型、风格要求	意图标签、关键词、情绪基调
`RetrieveMaterials`	根据关键词检索本地素材库	Top-K 图片/视频/文案片段
`GenerateStoryboard`	规划每帧画面、配音、视觉元素	故事板 JSON
`SynthesizeSpeech`	调用 TTS 生成配音	音频文件 URL
`RenderVideo`	调用 Remotion 渲染视频	视频文件 URL
`PostProcess`	FFmpeg 后处理：转码、压缩、加字幕	成片 URL

每个任务都是一个 Tool，Agent 通过 Reasoning 决定调用哪个 Tool、以什么参数调用、如何处理返回结果。

2.2 Agent Loop 设计

我们的 Agent 遵循典型的 ReAct 循环：

flowchart LR
    O["观察（Observation）"] --> T["思考（Thought）"] --> A["行动（Action）"] --> O

具体实现中，我把每次循环抽象为三个动作：

Plan：根据当前状态生成下一步计划
Act：调用 Tool 执行计划
Reflect：检查 Tool 输出，决定继续、重试还是终止

一个简化版的状态机如下：

flowchart TD
    Start["Start"] --> AnalyzeIntent["AnalyzeIntent"]
    AnalyzeIntent --> RetrieveMaterials["RetrieveMaterials"]
    RetrieveMaterials -- "素材不足" --> Fallback["FallbackToTextCards"]
    Fallback --> GenerateStoryboard["GenerateStoryboard"]
    RetrieveMaterials --> GenerateStoryboard
    GenerateStoryboard --> SynthesizeSpeech["SynthesizeSpeech"]
    SynthesizeSpeech -- "TTS 失败" --> RetryAudio["Retry / SkipAudio"]
    SynthesizeSpeech --> RenderVideo["RenderVideo"]
    RenderVideo -- "渲染失败" --> RetryRender["Retry / ReduceResolution"]
    RenderVideo --> PostProcess["PostProcess"]
    PostProcess --> EndNode["End"]

三、关键实现

3.1 Tool 注册与统一接口

所有 Tool 都实现统一的 Tool 接口：

from abc import ABC, abstractmethod
from typing import Any, Dict

class Tool(ABC):
    @property
    @abstractmethod
    def name(self) -> str:
        pass

    @property
    @abstractmethod
    def description(self) -> str:
        pass

    @abstractmethod
    def run(self, params: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
        """
        params: LLM 生成的调用参数
        context: 当前任务上下文，包含前面步骤的输出
        """
        pass

所有 Tool 注册到一个 Registry 中，Agent 根据 LLM 的输出动态调用：

class ToolRegistry:
    def __init__(self):
        self._tools: Dict[str, Tool] = {}

    def register(self, tool: Tool):
        self._tools[tool.name] = tool

    def get(self, name: str) -> Tool:
        return self._tools[name]

这种设计的好处是：新增一种视频类型或新增一个处理步骤，只需要新增一个 Tool，Agent 的编排逻辑不需要改动。

3.2 Agent Loop 核心代码

class ReActAgent:
    def __init__(self, llm_client, tool_registry, max_steps=15):
        self.llm = llm_client
        self.tools = tool_registry
        self.max_steps = max_steps

    def run(self, user_input: str) -> Dict[str, Any]:
        context = {
            "user_input": user_input,
            "history": [],
            "status": "running"
        }

        for step in range(self.max_steps):
            # 1. 让 LLM 根据当前状态决定下一步
            prompt = self._build_prompt(context)
            action = self.llm.generate(prompt)

            # 2. 解析 LLM 输出：Tool 名称 + 参数
            tool_name, params = self._parse_action(action)

            if tool_name == "Finish":
                context["status"] = "completed"
                break

            # 3. 执行 Tool
            tool = self.tools.get(tool_name)
            try:
                result = tool.run(params, context)
                result["success"] = True
            except Exception as e:
                result = {"success": False, "error": str(e)}

            # 4. 更新上下文
            context["history"].append({
                "step": step,
                "tool": tool_name,
                "params": params,
                "result": result
            })

            # 5. 失败时触发重试或降级
            if not result["success"]:
                fallback = self._decide_fallback(tool_name, result)
                if fallback:
                    context["history"].append({"fallback": fallback})

        return context

3.3 Prompt 设计

Prompt 的核心不是让 LLM「自由发挥」，而是把它限定在一个结构化的决策空间里：

你是一名短视频生成助手。当前任务状态如下：

- 用户输入：{user_input}
- 已执行步骤：{history}
- 可用工具：
  1. AnalyzeIntent: 分析文案意图
  2. RetrieveMaterials: 检索素材
  3. GenerateStoryboard: 生成故事板
  4. SynthesizeSpeech: 合成配音
  5. RenderVideo: 渲染视频
  6. PostProcess: 后处理
  7. Finish: 任务完成

请输出下一步操作，格式如下：

Thought: <你的推理过程>
Action: <Tool 名称>
ActionInput: <JSON 格式的参数>

为了让输出更稳定，我们做了几层约束：

JSON Schema 约束：要求 LLM 输出固定字段
Few-shot 示例：在 Prompt 里放 2-3 个正确示例
Pydantic 校验 + 重试：后端严格校验输出格式，失败自动重试

四、踩过的坑

4.1 LLM 输出格式不稳定

最早用纯 Prompt 约束时，LLM 有时输出 Action: GenerateStoryboard，有时输出 下一步：生成故事板，导致解析失败率很高。

解决方案：

引入 JSON Schema，明确要求输出 JSON
后端用 Pydantic 校验，失败自动重试 3 次
重试时 temperature 从 0.7 降到 0.2，让输出更稳定

效果：结构解析成功率从约 75% 提升到 98% 以上。

4.2 任务卡住没有超时机制

早期 Agent 会无限循环，比如某一步失败后 LLM 反复决定重试同一个 Tool。

解决方案：

设置 max_steps=15
每个 Tool 设置独立超时
同一 Tool 连续失败 2 次后强制降级或人工介入

4.3 上下文过长导致成本飙升

随着步骤推进，history 越来越长，LLM Token 消耗快速增长。

解决方案：

对 history 做摘要，只保留关键结果
每个 Tool 输出只保留必要字段
长视频场景下采用「分段生成 + 本地组装」策略

五、当前效果与待优化方向

目前这套 Agent 编排已经支撑方糖猫平台的核心生成链路，能够覆盖常见的口播、科普类视频生成场景。

已验证的收益：

新增一种视频类型的支持成本明显降低，从改动整个工作流变成新增一个 Tool
失败恢复路径清晰，常见异常无需人工介入
渲染失败、素材缺失等场景可以自动降级，任务完成率稳定在较高水平

还在探索的方向：

更细粒度的 Agent 评估：不是只看任务是否完成，还要看成片质量
多 Agent 协作：把创意策划、素材审核、质量评估拆成独立 Agent
成本优化：不同步骤路由到不同模型，复杂推理用大模型，简单调用用小模型

六、什么场景适合 ReAct，什么不适合

适合：

步骤之间有复杂依赖，需要动态决策
失败场景多，需要自动重试或降级
流程经常变化，硬编码维护成本高

不适合：

步骤固定、成功率高、性能要求极高的场景，传统工作流更合适
对延迟极度敏感的场景，Agent 的多次 LLM 调用会显著增加耗时

七、总结

ReAct Agent 不是银弹，但它确实帮我们解决了一个核心问题：如何把复杂的 AI 视频生成流程，从「硬编码脚本」变成「可编排、可观测、可恢复」的工程系统。

关键经验：

Tool 接口要统一，新增能力时不要改动 Agent 核心逻辑
Prompt 输出要做 Schema 约束和后端校验，否则线上会不稳定
失败处理、超时、降级必须一开始就想清楚
Agent 的评估指标不能只看「跑通」，要看「生成质量」和「成本」

后续我会继续分享 RAG 素材库、多 Worker 分布式渲染、以及 Whisper + Remotion 渲染链路的实践，欢迎关注。

如果你也在做 AI 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 条目）。

AgentScope 2.0 深度解析：企业级 Agent 工程的底座该怎么选

Wed, 03 Jun 2026 20:00:00 +0800

AgentScope 2.0 深度解析：企业级 Agent 工程的底座该怎么选

最近深入研究了阿里通义实验室开源的 AgentScope 2.0，它是一个面向企业级多智能体场景的工程框架。这篇文章结合我的实际经验，聊聊 AgentScope 2.0 的核心设计，以及它对我们做 Agent 产品化有什么启发。

一、从 Demo 到生产，Agent 缺什么？

过去两年，我用 LLM 做过不少 Agent 原型：自动剪辑、视频生成、代码助手。但要从「能跑」变成「能上线」，需要解决的问题远不止 Prompt 调优：

问题	说明
代码执行安全	Agent 生成的代码直接运行，可能删库、耗光资源
高并发隔离	多个用户同时调用 Agent，如何互不干扰
状态持久化	Agent 对话状态不能存在内存里，否则重启就丢
工具管理	Tool 多了之后，Prompt 装不下，也影响模型判断
多 Agent 协作	复杂任务需要多个 Agent 配合，怎么编排
可观测性	Agent 为什么做了这个决定？出了问题怎么追溯

AgentScope 2.0 就是围绕这些工程化痛点设计的。

二、底层架构：沙箱与高并发

2.1 Docker 沙箱不是打包业务代码

很多开发者有个误解：用 Docker 跑 Agent，就要把业务代码打包进镜像。

AgentScope 2.0 的设计完全不同：业务代码运行在宿主机，Docker 只作为执行沙箱。

flowchart TD
    A["宿主机进程（Agent 推理、Prompt 组装）"]
    B["Docker 容器（只运行命令，不存业务代码）"]
    C["容器内执行 rm -rf / 也伤不到宿主机"]
    A -- "通过 Docker API 下发指令" --> B
    B -- "内核级隔离" --> C

这种设计的几个好处：

业务迭代快：改代码不用重新打镜像
安全性高：危险操作被锁在容器里
资源可控：每个容器的 CPU/内存/网络都可以限制

2.2 MCP 网关解决跨容器通信

容器隔离后，容器内的 Agent 访问不到宿主机的 MCP 工具。AgentScope 2.0 的做法是内置 MCP 网关，通过 HTTPS 在容器内外转发请求。

flowchart LR
    A["容器内 Agent"] -- "HTTPS" --> B["MCP 网关"]
    B -- "本地调用" --> C["宿主机 MCP Server"]

这解决了一个很实际的问题：沙箱安全和工具可用性之间的冲突。

2.3 三种隔离粒度

AgentScope 2.0 支持不同级别的隔离：

模式	粒度	适用场景
`GLOBAL`	全局共享	内部工具、只读查询
`USER`	用户级隔离	推荐默认，兼顾安全和性能
`SESSION`	会话级隔离	高敏感操作、金融/政务场景

不是越隔离越好。全用 SESSION 的话，资源消耗和启动延迟都会爆掉。

2.4 Warm Pool 预热池

高并发下，「1 请求 1 容器」的冷启动根本扛不住。AgentScope 2.0 用 Warm Pool 提前准备一批待命容器，请求来了直接分配。

flowchart LR
    A["请求"] --> B["Warm Pool（预热的容器）"]
    B --> C["秒级分配"]

这个思路和我们做视频渲染 Worker 预热池很类似：把启动成本前置，用空间换时间。

三、核心设计模式

3.1 ReAct 与 PE 模式

AgentScope 2.0 原生支持两种模式：

ReAct：边思考边行动，适合需要动态决策的任务
PE（Plan & Execute）：先计划再执行，适合步骤明确的长任务

我在方糖猫里用的是 ReAct，因为视频生成过程中经常有「素材不足→换方案→继续生成」这种动态分支。PE 更适合审批流、报告生成这类流程相对固定的场景。

3.2 结构化输出

AgentScope 2.0 通过 structured_model 机制，把 LLM 输出映射成 Java/Python 对象。

这和我们在第六篇文章里讲的 Schema + Pydantic 校验是一个思路，只是框架帮你封装好了。对于企业级应用来说，结构化输出不是可选项，是必选项。

3.3 工具组动态激活

大模型上下文窗口有限，Tool 多了之后不能全塞进 Prompt。AgentScope 2.0 的做法是：

把工具分组（Tool Group）
模型先决定激活哪个组
再获取组内具体工具

这种「渐进式披露」让模型在每一步只需要关注少量工具，降低决策噪音。

四、分层记忆系统

AgentScope 2.0 把记忆分成短期和长期两层：

4.1 短期记忆

默认是内存级缓存，适合单轮或多轮对话内的上下文。可以自定义扩展，比如接入 Redis。

4.2 长期记忆

支持两种外部记忆框架：

Graphiti：时序知识图谱，适合需要时间感知的场景
Mem0：混合存储，同时处理语义关联和结构化关系

长期记忆对于 Agent 的个性化和持续学习很重要。比如一个客服 Agent，如果能记住用户上个月的问题，体验会好很多。

五、多智能体协作编排

AgentScope 2.0 提供了几种协作模式：

模式	说明	适用场景
用户对话循环	ReActAgent + UserAgent	单助手交互
轮询 Round-Robin	按顺序分配任务	流水线处理
路由 Routing	路由 Agent 分发给专家 Agent	复杂任务分发
Handoff	确定性的任务交接	审批流、工单系统

我在做口播自动剪辑时，其实也需要多 Agent 协作：

一个 Agent 负责分析文案结构
一个 Agent 负责规划视觉元素
一个 Agent 负责检查输出合规性

当时我们是硬编码在代码里的，如果用 AgentScope 2.0 的 Handoff 或 Routing 模式，代码会更清晰。

六、状态持久化：不能存在内存里

AgentScope 2.0 通过 agent.state_dict() 保存完整状态，支持多种后端：

state = agent.state_dict()
store.save(session_id, state)

# 重启后恢复
state = store.load(session_id)
agent.load_state_dict(state)

支持 Redis、MySQL、JSON 文件等后端。这一点对于企业级应用非常关键：服务重启后，用户的对话上下文不能丢。

七、对我们自研 Agent 的启发

研究完 AgentScope 2.0，我最大的感受是：优秀的 Agent 框架不是在教你写 Prompt，而是在解决工程化问题。

对比我们自研的 Agent 架构，有几点值得借鉴：

7.1 沙箱执行应该提前考虑

我们目前 Agent 生成的代码是在 Python Worker 里直接执行的，虽然有限制，但不如 Docker 隔离彻底。未来如果要支持更开放的 Agent 能力，沙箱是必须的。

7.2 工具管理需要分组

我们现在是把所有 Tool 塞进 Prompt，Tool 多了之后会影响模型判断。可以借鉴 Tool Group 的思路。

7.3 状态持久化要补全

我们目前的任务状态存在数据库，但 Agent 的完整对话上下文没有持久化。服务重启后，长任务会丢失上下文。

7.4 多 Agent 协作模式可以显式化

与其在代码里写死协作逻辑，不如抽象成 Routing / Handoff 模式，更容易扩展和维护。

八、选型建议：什么时候用 AgentScope 2.0

强烈推荐

企业级多租户服务
需要 K8s 分布式部署
对安全隔离有严格要求（金融、政务、医疗）
已有 Spring Boot 微服务架构的团队

谨慎评估

只是做单轮 LLM 调用
追求极简代码量
团队没有 Java/Python 工程化背景

AgentScope 2.0 是一个「重框架」，对于简单场景可能是过度设计。但对于要上线、要服务真实用户的企业级 Agent 应用，它的价值很明显。

九、总结

AgentScope 2.0 给我的最大启发是：Agent 产品化的竞争，正在从模型能力转向工程底座。

谁能更好地解决安全、并发、状态、工具管理、多 Agent 协作这些问题，谁就能让 Agent 真正跑在生产环境里。

对于像我这样从 0 自研 Agent 系统的团队，AgentScope 2.0 不一定直接替换现有架构，但它提供了一套值得参考的工程化标准。

你在做 Agent 工程化时，遇到过哪些头疼的问题？欢迎在评论区交流。

Netflix 模型服务路由笔记：把路由器从请求路径上拆掉

Fri, 01 May 2026 10:00:00 +0800

Netflix 模型服务路由笔记：把路由器从请求路径上拆掉

原文：State of Routing in Model Serving（Nipun Kumar, Rajat Shah, Peter Chng，Netflix Technology Blog，2026-05-01）目标读者：做 ML 平台、推理服务、内部网关的工程师；以及所有面对"要不要在请求路径上加一层集中代理"这个问题的人。阅读目标：搞清楚 Netflix 为什么自建路由层、这层路由怎么和工作流级模型抽象配合、它规模化后踩了哪三个坑，以及 Lightbulb 是怎么在不丢能力的前提下把这层路由从请求路径上拆掉的。

一、先澄清前提：Netflix 的「模型」不是模型

这篇文章是一个系列的第一篇，讲 Netflix 中央 ML 模型服务平台的路由设计。截至 2025 年，这个平台承载数百种模型类型和版本，合计每秒一百万次请求。但要理解它的路由，得先理解它路由的对象。

业界说的 model inference 通常就是 infer(features) 到 score 这一条函数调用。Netflix 的「模型」是另一个东西：一个自包含的工作流，封装了前处理、后处理、特征计算逻辑，外加一个可选的、真正训练出来的 ML 组件，全部打成标准格式。这个工作流的端到端执行才叫 model serving。

这个定义直接决定了 API 的形状。调用方只需要给两类东西：

标准请求上下文：userId、国家、设备；
领域上下文：要排序的候选片单，或者一笔待检测的支付交易。

特征不用客户端算——模型定义里声明了它需要哪些 facts（原始未加工的观测数据），serving 平台负责在运行时调其他微服务把 facts 取来，模型自己完成特征计算和推理。离线训练时则由 fact store 提供快照做批量特征计算。

这个设计的收益是双向的：客户端一次接入之后，模型架构和数据输入再怎么演化都不需要客户端配合；模型研究员也只需要和平台这一方打交道。标题推荐和支付欺诈检测用的是同一套接入方式——这是后面一切路由抽象的地基。

二、平台的三条设计原则

原文列的原则里和路由直接相关的有三条，每一条都对应一个具体的工程约束：

模型创新独立于客户端应用。新用例只做一次性接入，之后几乎所有模型迭代——包括中间的 A/B 实验——对调用方透明。模型选择、实验分流、额外数据拉取、训练日志，全是平台的事。
客户端与模型分片解耦。模型分布在多个 serving 集群分片上，每个分片有自己的 VIP 地址。流量模式、SLA、模型架构、CPU 和内存余量都会影响模型到分片的映射，映射一变 VIP 就变。客户端不应该感知这种变化。
灵活的流量路由规则。支持按 A/B 实验路由、缓慢向新模型和新 VIP 切流、客户端覆写。

注意第二条：在 Netflix 这个设计里，「模型在哪」是个高频变动的运维事实，而不是部署时定死的静态配置。这决定了路由必须是个动态系统。

三、Switchboard：自建的路由层

现成的 API 网关（AWS API Gateway、独立的 Service Mesh 代理）为什么不行？原文给了四个理由：需要和 Netflix 实验平台一等公民集成、需要对客户端暴露 gRPC、需要用富领域上下文做路由定制、需要定制模型生命周期阶段（影子模式、金丝雀、回滚）。通用代理不为此设计，于是自研了 Switchboard——所有流量的弹性代理层，扛一百万 QPS。

Objective：用例的名字

整个抽象的核心是一个叫 Objective 的概念：serving 平台定义的一个枚举，每个进系统的请求都必须携带。它就是业务用例的名字，比如 ContinueWatchingRanking。它干三件事：让客户端只声明「我要什么」而不说「用哪个模型」；作为路由和模型选择的决策依据；把客户端和具体模型彻底解耦。

Switchboard 的四项能力

统一客户端抽象：所有客户端的模型请求只有一个联络点，没有新依赖、没有新 client 要管；平台侧则拿到跨模型版本的限流和并发控制旋钮，能对付行为恶劣的客户端。
上下文感知路由：按设备、地区、排序场景（首页还是搜索结果）、用户所在的 A/B 实验来路由。
动态流量切分：金丝雀和实验的实时切流，新模型先放给受控的小比例用户。
版本与生命周期管理：同一模型多版本并发承接流量，支撑影子模式测试（生产流量发给新模型但不影响用户，只做性能对比）和瞬时回滚。

Switchboard Rules：研究员的入口

Objective 是客户端和平台之间的契约，那研究员怎么把模型变体、实验、流量配比挂到 Objective 上？答案是一份 JavaScript 配置，叫 Switchboard Rules，编译产出一份 JSON 规则文件，规定三件事：某 Objective 的默认模型、一组 Objective 上要开哪些 A/B 实验及对应模型、向新模型渐进切流的定制。

原文给了一个 Continue Watching 场景的规则示例：定义 A/B 实验 12345，cell 1 走当前线上模型，cell 2 和 cell 3 走两个候选模型，绑定到 ContinueWatchingRanking 这个 Objective。

规则的分发是这次设计里最值得抄的部分：规则有独立于代码部署的发布周期，走 Netflix 的 Gutenberg 系统做 pub-sub，带版本管理、动态加载和回滚。Switchboard 和 serving 集群主机订阅同一份规则配置。控制面拿到规则后做三件事：产出模型到分片的分配方案、把规则里的模型都加载进分片验证依赖能跑通、把模型到分片 VIP 的映射交给 Switchboard。数据面则是四步：

flowchart TD
    C["客户端微服务<br/>携带 Objective 和标准上下文"] -->|"gRPC 请求"| SB["Switchboard<br/>集中路由层"]
    SB -->|"第一步 分配<br/>查实验平台<br/>userId 在哪个 cell"| EXP["实验平台"]
    EXP --> SB
    SB -->|"第二步 选模型<br/>按 cell 和 A B 规则<br/>确定模型版本"| SB
    SB -->|"第三步 路由<br/>查模型到 VIP 映射"| SHARD["Serving 集群分片<br/>对应 VIP"]
    SHARD -->|"第四步 执行<br/>跑完整模型工作流"| RESP["返回推理结果"]
    RESP --> SB
    SB --> RESP2["响应给客户端"]
    style SB fill:#fff3cd

到这一步故事很顺：30 多个客户端服务靠这层抽象获得了模型迭代的完全自由。然后规模化开始收账。

四、规模化的三笔账

Switchboard 跑大之后，三个问题浮出来，每一个都很典型：

单点故障。Switchboard 在所有请求的关键路径上。无意的 bug、 noisy neighbor 打过来的超额流量，极端情况下可能切断对所有 serving 主机的访问。它是 30 多个 ML 体验的共享依赖，它倒了大家一起倒。
额外延迟。请求路径上多一跳，序列化加反序列化带来 10-20ms 的延迟（取决于 payload 大小），还放大了尾延迟。对延迟敏感的客户端，这直接表现为服务超时、终端用户受影响。
客户端灵活性受损。Switchboard 挡在中间，serving 集群看不到请求的真实来源。区分真实流量和人为测试流量——这对模型训练数据至关重要——变得困难，需要持续的定制开发，MLOps 开销一直涨。

第三条值得停一下。集中代理的一个隐性代价是信息损耗：代理层为了抽象抹掉了来源信息，而下游恰恰需要这个信息做租户隔离和训练数据清洗。抽象不是免费的，它吃掉的信息总得有地方补回来。

五、Lightbulb：拆路由，而不是删路由

团队的结论不是推翻 Switchboard，而是重新摆放它职责的执行位置。要保留的能力列得很清楚：统一客户端抽象、分片解耦、灵活路由规则、轻量客户端、单一配置入口、配置快速传播、故障时的 fallback 和客户端缓存。要解决的是三件事：

把路由服务从直接请求路径上移走。路由规则变化频率很低，为它维持强一致性的可用性代价不划算；
把模型输入和请求元数据分开。payload 可能很大，Switchboard 为了做路由决策要把整个 payload 反序列化再序列化，这是延迟和成本的大头；
给路由层更好的隔离。多租户挤在一个路由集群里，一个租户的异常流量会级联影响其他租户，而不同用例的延迟要求差异又很大。

做法是把原来一整份规则拆成两套配置：模型服务配置（请求时该用哪个模型及所需元数据）和路由规则（定了模型之后，请求该去哪个 VIP）。数据面也跟着拆开——路由本身交给 Envoy 做：

flowchart LR
    C["客户端服务"] -->|"最小请求上下文"| LB["Lightbulb<br/>只做配置解析"]
    LB -->|"返回 routingKey<br/>和 ObjectiveConfig"| C
    C -->|"完整请求<br/>头部带 routingKey<br/>body 带 ObjectiveConfig"| ENVOY["Envoy 代理<br/>客户端侧出口"]
    ENVOY -->|"按 routingKey 映射到 VIP<br/>头部判断 开销极小"| SHARD["Serving 集群分片"]
    SHARD --> ENVOY
    ENVOY --> C
    style LB fill:#e8f5e9
    style ENVOY fill:#fff3cd

几个关键设计决策：

Envoy 在 Netflix 本来就把所有应用间出口流量都接管了，它能按控制面发布的路由规则把请求发到不同集群（VIP），但它没有路由决策所需的信息，也不会给请求体补充 A/B 变体所需的 serving 参数。Lightbulb 就是补这个缺口的。
Lightbulb 只吃最小的请求上下文（用例信息），解析出两样东西：routingKey 和 ObjectiveConfig。前者是给 Envoy 的路由元数据，后者放模型 id 和模型执行所需的其他请求级配置。把配置解析和「怎么到达推理集群」彻底分开了。
routingKey 放请求头给 Envoy 消费；ObjectiveConfig 由客户端放进请求体。刻意不把所有东西都塞进头部，避免头部膨胀。
真正的路由由 Envoy 执行：routingKey 在头部，映射到 VIP 的判定开销极小。

Switchboard 时代的核心收益——单一接入点、模型 id 对用例的抽象、上下文感知路由——全部保留；单点和额外跳数没了。

六、工程实践联想

这篇架构演进史里有几条可以直接搬进日常：

先问「这层代理吃掉了什么信息」。加一层集中代理时，大家习惯算延迟账，很少有人算信息账。Switchboard 的第三个坑就是信息账：来源身份被抽象抹掉，训练数据分不清真假流量。设计代理层时，把「下游需要但代理会吞掉的字段」列出来，和延迟预算一起评审。
配置和代码分开发布，是实验平台的生命线。Switchboard Rules 走 Gutenberg pub-sub、有独立发布周期、能动态加载能回滚——模型实验的迭代速度取决于配置的流转速度，不取决于服务的部署速度。凡是「业务方天天要改、改了就要生效」的东西，都不应该长在代码发布列车里。
控制面集中、数据面分散，是规模化的标准答案。Lightbulb 的本质是把「做决策」（低频、需要一致性、可以集中）和「执行决策」（高频、要求低延迟、必须分散）拆开。Envoy 执行、Lightbulb 决策，各归各位。同一个套路在服务网格、CDN、feature flag 系统里反复出现。
低频变化的路径上不要维持强一致。路由规则变化频率很低，为它维护一个高可用的在线路由服务是过度支付——推到客户端侧缓存，故障时还能 fallback。「这个信息多久变一次」应该直接决定它放在请求路径上还是路径外。
给模型起「用例名」而不是暴露「模型名」。Objective 这个枚举是整个抽象的关键：客户端说的是意图，平台负责兑现。这个套路在任何平台工程里都成立——暴露稳定的能力枚举，藏住易变的实现标识，实现侧的迭代自由度就是这么来的。

本篇小结

前提：Netflix 的「模型」是自包含工作流（前处理、特征计算、可选的 ML 组件、后处理），serving 而非 inference 是抽象单位；客户端只给标准上下文加领域上下文，facts 由平台在运行时取。
第一版架构：Switchboard 集中路由层，配 Objective 枚举（用例名）和 Switchboard Rules（JS 配置编译成 JSON，Gutenberg pub-sub 分发，独立于代码部署）；提供统一接入、上下文路由、动态切流、影子模式和瞬时回滚。
规模化的三笔账：单点故障、10-20ms 额外延迟加尾延迟放大、请求来源信息被代理吞掉导致租户隔离和训练数据清洗困难。
第二版架构：Lightbulb 把模型选择从路由里拆出来——Lightbulb 解析最小上下文产出 routingKey（进头部）加 ObjectiveConfig（进请求体），Envoy 在客户端侧按 routingKey 路由到 VIP；请求路径上不再有集中路由器，能力一项没丢。
元教训：集中式代理解决抽象问题，规模化之后要把决策和执行拆开——决策可以集中（低频、要一致性），执行必须分散（高频、要低延迟）。

参考资料

State of Routing in Model Serving，Netflix Technology Blog，2026-05-01（本系列第一篇，后续会讲推理与特征拉取）。
原文引用的内部系统：Netflix 实验平台（A/B 分配）、Gutenberg（配置 pub-sub 与版本管理）、ML fact store（离线训练特征快照）。
Envoy Proxy（Lightbulb 架构中承担实际路由的客户端侧代理）。

Spring Boot + Python 双栈架构：AI 服务的工程化实践

Mon, 20 Apr 2026 14:00:00 +0800

Spring Boot + Python 双栈架构：AI 服务的工程化实践

我开发的方糖猫 AI 视频平台不是一个纯 Python 项目，也不是一个纯 Java 项目。它同时使用了 Spring Boot 3 和 Python 3.11：Java 负责业务系统和 API 服务，Python 负责 AI 推理、渲染和多媒体处理。这篇文章会分享我们为什么要这样做，以及如何解决两个技术栈之间的协作问题。

一、为什么必须双栈？

做一个 AI 视频生成平台，需要两类能力：

能力类型	典型需求	更适合的栈
企业级业务系统	用户、订单、权限、支付、任务管理	Java / Spring Boot
AI 推理与多媒体	LLM 调用、Whisper、RAG、Remotion、FFmpeg	Python

Java 的优势在于生态成熟、工程规范、团队熟悉；Python 的优势在于 AI 库丰富、模型推理和多媒体处理工具链完善。

如果全用 Java，AI 库支持差，很多模型没有 Java SDK；如果全用 Python，业务系统的稳定性、事务处理、监控运维又很难做好。

所以我们的选择是：Java 做业务底盘，Python 做 AI 引擎，两者通过清晰的接口协作。

二、整体架构

flowchart TD
    FE["前端 (Vue 3)"]
    GW["API 网关 / BFF (Spring Boot)<br/>用户认证、请求路由、限流、任务状态查询、SSE 推送"]
    BIZ["业务服务<br/>(Spring Boot)"]
    SCHED["任务调度服务<br/>(Spring Boot)"]
    RES["资源管理服务<br/>(Spring Boot)"]
    AI["AI Worker (Python)<br/>ReAct Agent、RAG 检索、Whisper、TTS、Remotion、FFmpeg"]
    STORE["存储层：MySQL / Redis / OSS / ChromaDB"]

    FE --> GW
    GW --> BIZ
    GW --> SCHED
    GW --> RES
    SCHED -- "RocketMQ / Kafka" --> AI
    AI --> STORE

三、职责划分

3.1 Java 侧职责

API 网关：统一入口、鉴权、限流、日志
用户与任务管理：用户注册登录、任务创建、任务状态机、历史记录
素材元数据管理：素材上传、分类、标签、权限
支付与计费（如有）：订单、套餐、用量统计
任务调度：把渲染/生成任务发送到消息队列
实时通知：SSE 推送任务进度给用户

3.2 Python 侧职责

AI Agent 编排：ReAct 任务规划、Tool 调用
RAG 检索：Embedding 计算、向量库查询
语音识别：Whisper 转写
语音合成：TTS 配音
视频渲染：Remotion 组件化渲染
后处理：FFmpeg 转码、压缩、字幕、多分辨率输出

3.3 边界原则

我们定了几条原则来避免职责混乱：

Python 不直接暴露给用户。所有用户请求都走 Java API。
Python 只做无状态计算。任务状态、用户信息、素材元数据都在 Java 侧维护。
通信以异步为主。AI 任务通常耗时较长，同步调用容易导致超时和耦合。
数据以 ID 为纽带。Java 和 Python 之间不传大对象，只传任务 ID 和必要参数。

四、服务间通信

4.1 异步通信：RocketMQ

AI 生成和渲染任务都走 RocketMQ：

// Java 侧发送任务
SendResult result = rocketMQTemplate.syncSend(
    "video-render",
    MessageBuilder.withPayload(taskMessage).build()
);

# Python 侧消费任务
class RenderConsumer:
    def on_message(self, msg):
        task = json.loads(msg.body)
        result = render_engine.process(task)
        self.update_task_status(task["task_id"], "completed", result)
        return ConsumeStatus.CONSUME_SUCCESS

异步通信的优点：

解耦 Java 和 Python 服务
Python Worker 可以独立扩缩容
任务失败可以重试，不阻塞主流程

4.2 同步通信：HTTP / gRPC

少数场景需要同步调用，比如：

查询 RAG 素材（用户在前端点击「生成」前希望看到素材推荐）
获取任务实时状态
健康检查

我们主要用 HTTP REST，因为：

简单直观，Java 和 Python 生态都完善
调试方便，curl 即可测试
对延迟要求不极端

gRPC 我们也考虑过，但因为团队对 gRPC 熟悉度不高，且收益不明显，暂时没引入。

4.3 数据一致性

双栈架构下，任务状态是核心数据。我们用数据库作为唯一真相源：

flowchart TD
    A["用户提交任务"] --> B["Java 写入任务记录（status=pending）"]
    B --> C["发送 RocketMQ 消息"]
    C --> D["Python Worker 消费"]
    D --> E["Python 更新任务状态（status=processing/completed/failed）"]

Python Worker 更新数据库时，通过乐观锁防止并发冲突：

UPDATE render_task
SET status = 'processing',
    worker_id = 'worker-01',
    updated_at = NOW()
WHERE task_id = 'xxx'
  AND status = 'pending'

五、数据库设计

5.1 按服务分库还是分表？

我们没有完全按微服务分库，而是按业务域分表：

user：用户信息
task：生成任务
material：素材元数据
template：视频模板
subscription：订阅/套餐

所有表都在一个 MySQL 实例里，通过业务 ID 关联。这种方案在业务量不大时性价比最高，未来可按域拆分。

5.2 Python 侧如何访问数据库

Python 侧需要读取/更新任务状态，我们用的是 SQLAlchemy + 只读/写分离：

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine("mysql+pymysql://user:pass@host/db")
Session = sessionmaker(bind=engine)

def update_task_status(task_id: str, status: str):
    with Session() as session:
        session.execute(
            "UPDATE render_task SET status = %s WHERE task_id = %s",
            (status, task_id)
        )
        session.commit()

为了降低耦合，Python 侧只更新少量任务状态字段，不碰业务核心表。

六、部署与运维

6.1 容器化

两个栈都用 Docker 打包：

# Java 服务 Dockerfile
FROM eclipse-temurin:17-jdk
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

# Python Worker Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "worker.py"]

6.2 CI/CD

我们用一个简单的 GitHub Actions / Jenkins 流程：

代码提交触发构建
分别构建 Java 镜像和 Python 镜像
推送到镜像仓库
生产环境滚动更新

6.3 日志与链路追踪

双栈环境下，排查问题最大的难点是链路跨语言。我们的做法：

所有请求携带 trace_id
Java 和 Python 都把 trace_id 打到日志里
用 ELK / Loki 做日志聚合，按 trace_id 查询全链路

import logging

logger = logging.getLogger(__name__)

logger.info("Start render", extra={"trace_id": trace_id, "task_id": task_id})

6.4 监控告警

层级	监控项
Java 服务	JVM 内存、GC、接口响应时间、错误率
Python Worker	CPU/GPU 利用率、任务处理速率、队列堆积
数据库	连接数、慢查询
消息队列	堆积量、消费速率

七、踩过的坑

7.1 序列化不一致

Java 侧用 Jackson，Python 侧用默认 json，时间格式、枚举值、空值处理不一致，导致接口对接时经常报错。

解决：

统一用 ISO 8601 时间格式
枚举值用字符串传递
制定统一的 JSON Schema，用 Pydantic 和 Java Bean Validation 双向校验

7.2 Python 服务内存泄漏

Python Worker 长时间运行后，内存占用越来越高，尤其是加载大模型后。

解决：

Worker 处理一定数量任务后自动重启
模型用单例模式加载，避免重复初始化
显式清理大对象，调用 gc.collect()

7.3 跨语言异常处理

Python 异常信息传到 Java 侧变成一团乱码，前端无法友好展示。

解决：

定义统一的错误码体系
Python 捕获异常后按规范封装错误响应
Java 侧根据错误码映射为用户友好的提示

7.4 开发环境复杂度

开发时需要同时启动 Java 服务、Python Worker、MySQL、Redis、RocketMQ，新成员上手成本高。

解决：

提供 docker-compose.yml 一键启动基础设施
编写本地开发文档
支持 Windows 开发环境降级（Python Worker 用 HTTP 模拟 RocketMQ）

八、双栈架构的收益与代价

8.1 收益

方面	说明
团队分工清晰	Java 工程师做业务，Python 工程师做 AI
技术选型合理	每个栈都用最合适的工具
稳定性高	业务系统独立演进，AI 故障不直接影响用户注册/支付
扩展灵活	Python Worker 可以根据渲染负载单独扩容

8.2 代价

方面	说明
运维复杂	两套构建、部署、监控体系
链路排查难	跨语言日志追踪需要额外设计
接口契约维护	Java 和 Python 之间需要稳定的 API 契约

九、什么情况下不要双栈？

虽然双栈适合我们，但不是所有项目都需要：

纯业务系统：全 Java 即可
纯模型研究/实验：全 Python 即可
团队规模小：双栈会增加认知负担
MVP 早期：先用最熟悉的栈跑通，后期再拆分

我们是在产品验证基本跑通、团队有 5 人以上时才明确拆成双栈。

十、总结

Spring Boot + Python 双栈不是最优架构，而是适合我们团队能力和业务形态的架构。几个关键经验：

职责边界要清晰，否则双栈会变成双倍的混乱。
异步通信是主力，同步只用于低延迟查询场景。
数据库是状态的唯一真相源，避免两端各自维护状态。
日志追踪要跨语言打通，否则线上出问题很难排查。
不要为双栈而双栈，MVP 阶段先用单栈验证。

如果你也在做 Java + Python 的混合架构，欢迎交流接口契约、部署和监控的经验。

RAG 系统完全笔记：从检索器到生产部署

Sat, 11 Apr 2026 10:00:00 +0800

RAG 系统完全笔记：从检索器到生产部署

最近重刷了吴恩达 DeepLearning.ai 的《Retrieval Augmented Generation》课程，整理了一份从检索器到生产部署的完整笔记。RAG 不只是「把文档塞进向量库然后问大模型」，它的每个环节都有值得细究的工程决策。本文在每个算法之外，也补充了对应的落地工具与最佳实践。

一、RAG 是什么？为什么需要它？

大语言模型（LLM）有两个天然缺陷：

知识有截止日期：训练数据之后发生的事件、私有文档，模型都不知道。
容易 hallucination（幻觉）：没有可靠依据时，模型会一本正经地编造答案。

RAG 的解决思路很简单：在生成答案前，先从外部知识库中检索相关文档，把检索结果作为上下文喂给 LLM。这样模型既能利用最新、最专有的知识，又能基于检索到的内容生成，显著降低幻觉风险。

一个完整的 RAG 系统分为离线索引和在线检索生成两条流水线：

flowchart LR
    subgraph 离线索引
        A[原始文档] --> B[文档分块 Chunking]
        B --> C[Embedding 编码]
        C --> D[(向量数据库)]
    end
    subgraph 在线检索生成
        E[用户查询] --> F[查询改写]
        F --> G[检索器 Retriever]
        D -.-> G
        G --> H[重排序 Re-ranking]
        H --> I[LLM 生成]
        I --> J[最终答案]
    end

落地框架：搭建整条 pipeline 不必从零写，LangChain 和 LlamaIndex 是最主流的两个 RAG 编排框架，检索器、分块器、重排序器、提示词模板都有现成实现；需要精细控制流程状态（如 Agentic RAG）时可以用 LangGraph。入门建议先用 LlamaIndex 快速跑通，再根据瓶颈逐环节替换。

二、检索器：找到正确的文档

检索器是 RAG 系统的第一道关卡。常见检索方式有三种，以及它们的组合。

2.1 元数据过滤

在向量搜索之前，先用结构化条件缩小范围：

作者、发布时间、信源
地区、类别、权限标签

例如，企业知识库中只允许查询「本部门」文档，就可以通过 department_id 元数据过滤。

最佳实践：主流向量库都支持「过滤 + 向量搜索」的混合查询——Elasticsearch 的 filter 子句、Qdrant 的 payload filter、pgvector 配合普通 WHERE 条件都可以。权限过滤一定要放在检索阶段做，而不是检索出来再在应用层过滤，否则 Top-K 里可能挤掉有权限的文档，还会把不该出现的文档内容带进 LLM 上下文。

2.2 关键词搜索

基于词频的检索，计算查询词与文档的匹配程度。

TF-IDF

TF（词频）：查询中的词在一篇文档里出现了多少次。
IDF（逆文档频率）：查询中的词在所有文档中出现的频率的倒数。词越稀有，权重越高。

写成公式：

$$ \mathrm{tf}(t, d) = \frac{f_{t,d}}{\sum_{t’ \in d} f_{t’,d}}, \qquad \mathrm{idf}(t, D) = \log \frac{N}{1 + |{d \in D : t \in d}|} $$

公式中各符号的含义：

$t$（term）：一个词项（term），通常指查询中的某个词。
$d$（document）：一篇文档，即被评分的单篇文档。
$D$（document collection）：整个文档集合（语料库），包含全部 $N$ 篇文档。
$f$：词频计数函数（frequency）。$f_{t,d}$ 表示词 $t$ 在文档 $d$ 中出现的次数，例如「检索」在某文档中出现 3 次，则 $f_{t,d} = 3$。
$\sum_{t’ \in d} f_{t’,d}$：文档 $d$ 中所有词项的出现次数之和，即文档总词数（长度）。分子除以它，就把词频归一化成「占比」，避免长文档天然占优。
$N$：文档集合 $D$ 中的文档总数。
$|{d \in D : t \in d}|$：包含词 $t$ 的文档篇数（document frequency）。分母加 1 是平滑处理，防止词在所有文档中都不出现时除以零。

直观理解：$\mathrm{tf}$ 衡量「这个词在本文档中有多重要」（出现占比越高越重要），$\mathrm{idf}$ 衡量「这个词在整个语料库中有多稀有」（越稀有的词越能区分文档，权重越高），两者相乘就是词的综合权重。

文档 $d$ 对查询 $q$ 的得分即查询中各词的 TF-IDF 之和：

$$ \mathrm{score}(q, d) = \sum_{t \in q} \mathrm{tf}(t, d) \cdot \mathrm{idf}(t, D) $$

BM25

BM25 是 TF-IDF 的改进版，引入了两个可调参数：

$$ \mathrm{score}(q, d) = \sum_{t \in q} \mathrm{idf}(t) \cdot \frac{f_{t,d} \cdot (k_1 + 1)} {f_{t,d} + k_1 \cdot \left(1 - b + b \cdot \dfrac{|d|}{\mathrm{avgdl}}\right)} $$

$k_1$：控制词频对评分的影响（词频饱和曲线），常见取值 $1.2 \sim 2.0$。
$b$：控制文档长度归一化的强度，$|d|$ 是文档长度，$\mathrm{avgdl}$ 是平均文档长度，常见取值 $0.75$。

BM25 在短查询、精确匹配场景中仍然非常有效，比如查找包含特定术语的技术文档。

工业实现：Elasticsearch

BM25 不是纸面算法，它就是 Elasticsearch 的默认评分器（自 ES 5.0 / Lucene 6.0 起，替代了旧的 TF-IDF）。最普通的 match 查询，底层走的就是 BM25：

GET /my-index/_search
{
  "query": {
    "match": {
      "content": "检索增强生成"
    }
  }
}

$k_1$ 和 $b$ 两个参数可以在索引设置里自定义（注意修改 similarity 需要关闭索引或重建索引）：

PUT /my-index
{
  "settings": {
    "similarity": {
      "my_bm25": {
        "type": "BM25",
        "k1": 1.2,
        "b": 0.75
      }
    }
  },
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "similarity": "my_bm25"
      }
    }
  }
}

调试时还可以加 "explain": true，ES 会返回每个文档 BM25 打分的详细拆解（tf、idf、长度归一化各自贡献了多少），对排查「为什么这篇文档排在前面」非常有用。

不想维护 ES 集群时，轻量替代方案有 OpenSearch（同源于 Lucene）、纯 Python 的 rank_bm25 库，以及 LangChain 内置的 BM25Retriever。注意中文 BM25 的效果强依赖分词器：ES 建议装 IK Analyzer，并针对领域维护自定义词典（产品名、缩写、术语）。

2.3 语义搜索

将查询和文档都编码成向量，通过 余弦相似度（cosine similarity） 找到语义相近的文档。即使关键词不同，语义接近也能召回。

$$ \cos(\mathbf{q}, \mathbf{d}) = \frac{\mathbf{q} \cdot \mathbf{d}}{|\mathbf{q}| , |\mathbf{d}|} = \frac{\sum_i q_i d_i}{\sqrt{\sum_i q_i^2} \cdot \sqrt{\sum_i d_i^2}} $$

余弦相似度取值在 $[-1, 1]$ 之间，越接近 $1$ 表示语义越相近。实际工程中通常先对向量做 L2 归一化，此时余弦相似度就退化为简单的内积，检索更高效。

落地工具：向量由 Embedding 模型生成，选型参考 Hugging Face 的 MTEB / C-MTEB 榜单：

API 方案：OpenAI text-embedding-3 系列、Cohere Embed、阿里 DashScope 通用文本向量。
自托管方案：BGE-M3（BAAI，中英文效果好，支持稠密 + 稀疏 + 多向量三种输出）、gte-Qwen 系列、E5 系列，均可用 sentence-transformers 或 FlagEmbedding 库本地加载。

最佳实践：查询和文档必须用同一个 Embedding 模型（部分模型对查询和文档有不同前缀，如 E5 的 query: / passage:，不要混用）；更换 Embedding 模型意味着全量重建索引，选型时先在自有数据上做小规模评测再定。

2.4 混合搜索

实际工程中，通常把多种检索方式组合起来：

flowchart LR
    Q[用户查询] --> K[关键词搜索 BM25]
    Q --> S[语义搜索 向量]
    K --> M[结果融合]
    S --> M
    M --> F[元数据过滤]
    F --> R[重排序]
    R --> O[最终上下文]

两路结果分数量纲不同，直接相加不合理，标准做法是 RRF（Reciprocal Rank Fusion）：只看排名不看分数。

$$ \mathrm{RRF}(d) = \sum_{r \in \text{各路检索}} \frac{1}{k + \mathrm{rank}_r(d)} $$

其中 $k$ 是平滑常数，通常取 $60$。文档在任一路排得靠前，融合后得分就高。

落地工具：这套组合在 Elasticsearch 8.x 里一个引擎就能实现——BM25 + kNN 向量检索（底层 HNSW），原生支持 RRF 融合；代码侧则可以用 LangChain 的 EnsembleRetriever（内部同样是 RRF）把 BM25Retriever 和任意向量检索器组合起来。

2.5 检索质量评估

精准度（Precision）：检索出的相关文档 / 检索出的所有文档。反映结果的可信度。
召回率（Recall）：检索出的相关文档 / 所有相关文档。反映结果的完整度。

$$ \mathrm{Precision} = \frac{|\text{相关文档} \cap \text{检索结果}|}{|\text{检索结果}|}, \qquad \mathrm{Recall} = \frac{|\text{相关文档} \cap \text{检索结果}|}{|\text{相关文档}|} $$

平均精准度（MAP）：先对单次查询在相关文档出现的每个位置取精准度平均（AP），再对多次查询求平均。

$$ \mathrm{MAP} = \frac{1}{|Q|} \sum_{q=1}^{|Q|} \mathrm{AP}(q), \qquad \mathrm{AP}(q) = \frac{1}{m_q} \sum_{k=1}^{n} P(k) \cdot \mathrm{rel}(k) $$

其中 $m_q$ 是查询 $q$ 的相关文档总数，$P(k)$ 是前 $k$ 个结果的精准度，$\mathrm{rel}(k)$ 表示第 $k$ 个结果是否相关。

平均倒数排名（MRR）：最相关文档在结果列表中的排名的倒数。排名第一，MRR 就是 1；排名第十，MRR 就是 0.1。

$$ \mathrm{MRR} = \frac{1}{|Q|} \sum_{q=1}^{|Q|} \frac{1}{\mathrm{rank}_q} $$

落地工具：评估的前提是有一批带标注的「黄金测试集」（golden dataset），通常 50-200 条真实用户问题加人工标注的相关文档。标注成本高时可以用 Ragas 的合成数据功能自动生成测试集；Ragas 和 DeepEval 还都提供 context precision / context recall 等无需人工标注、由 LLM 打分的检索评估指标，适合纳入 CI 做回归测试。

三、向量数据库：如何高效存储和检索

向量数据库的核心问题是：给定一个查询向量，如何快速找到最相似的文档向量？

3.1 KNN：精确但慢

KNN（K-Nearest Neighbors）会实时计算查询向量与所有文档向量的距离，结果准确，但当向量数量达到亿级时，计算量不可接受。设向量库有 $N$ 个 $d$ 维向量，暴力检索的复杂度为 $O(Nd)$。

适用场景：向量量在万级以内、或需要精确结果做基准评测时，暴力 KNN 反而最省事——FAISS 的 IndexFlatIP、NumPy 一次矩阵乘法就够，不必引入索引结构。

3.2 ANN：近似但快

ANN（Approximate Nearest Neighbor）通过构建近邻图或索引结构来加速检索，牺牲了极小的准确率，换取了数量级的性能提升。

HNSW（Hierarchical Navigable Small World） 是目前最常用的 ANN 算法之一，采用分层导航图结构，能够在亿级向量库中快速找到近似最近邻：

flowchart TB
    Q[查询向量] --> E[顶层入口点]
    subgraph HNSW["HNSW 分层图"]
        direction TB
        L2["Layer 2（最稀疏，快速定位大致区域）"]
        L1["Layer 1（中间过渡层）"]
        L0["Layer 0（包含全部节点，精确找最近邻）"]
        L2 --> L1 --> L0
    end
    E --> L2
    L0 --> R["Top-K 近似最近邻"]

查询时从最稀疏的顶层开始贪心搜索，逐层向下，每层把入口点收敛到更接近目标的区域，最后在最稠密的第 0 层做精细查找。平均查询复杂度约为 $O(\log N)$。

落地工具：

向量库选型：Milvus、Qdrant、Weaviate（独立向量数据库）、pgvector（已有 PostgreSQL 时的最简方案）、Chroma（轻量嵌入式）、FAISS（Meta 的索引库，无服务化能力）、Elasticsearch kNN（想复用 BM25 生态时）。
HNSW 三个关键参数：M（每个节点的最大连接数，默认 16，越大越准但越耗内存）、ef_construction（建索引时的搜索宽度，默认 100）、ef_search（查询时的搜索宽度，运行时调大它就能在召回率和延迟之间实时权衡，是最常用的调优旋钮）。

四、文档分块：粒度决定召回质量

把长文档切成小块（chunk）是 RAG 的关键步骤。chunk 太大或太小都有问题：

太大：一个向量要表达太多内容，指向性弱，容易引入无关信息。
太小：上下文不足，语义不明确。

4.1 固定大小分块

文本：250 字符左右（例如 225 字符正文 + 25 字符重叠）。
代码：500 字符左右，重叠 50-100 字符。

重叠（overlap）能避免关键信息被切分断掉。

落地工具：LangChain 的 CharacterTextSplitter / RecursiveCharacterTextSplitter、LlamaIndex 的 SentenceSplitter。其中 RecursiveCharacterTextSplitter 是事实上的默认选择：按「段落 → 句子 → 词 → 字符」的优先级递归切分，尽量在大小限制内保留自然边界。

4.2 按特殊字符分块

按换行、段落、标题等自然边界切分，保留文档结构。

落地工具：Markdown 文档用 LangChain 的 MarkdownHeaderTextSplitter 按标题层级切；HTML/PDF 等复杂格式先用 Unstructured 做版面解析再分块；代码可以按语法树切分（LangChain 的 Language 参数基于 tree-sitter）。

4.3 语义分块

按句子处理，判断当前句子与下一个句子的语义相似度。如果不相似，就在当前位置切分。即对相邻句子的向量 $s_i$、$s_{i+1}$，当 $\cos(s_i, s_{i+1}) < \tau$（$\tau$ 为预设阈值）时切分。这样切出来的 chunk 内部语义更连贯。

落地工具：LangChain 的 SemanticChunker（基于 Embedding，可选百分位/标准差阈值）、LlamaIndex 的 SemanticSplitterNodeParser、专用库 chonkie。

4.4 LLM 分块

直接让大模型根据语义边界做分块，效果通常最好，但成本也最高。实践中一般用小型模型（如 GPT-4o-mini 级别）离线跑一遍建索引，在线查询不再产生额外成本。

4.5 上下文感知分块

在分块后补充描述信息，例如 chunk 所属的章节、文档标题等，帮助提升索引相关性。

最佳实践：Anthropic 提出的 Contextual Retrieval 是这个思路的成熟方案——索引入库前，让 LLM 为每个 chunk 生成一段 50-100 token 的上下文说明（「本段出自 XX 文档第三章，讨论……」）拼在 chunk 前面，再做 Embedding 和 BM25 索引，官方报告可将检索失败率降低约 49%（配合重排序可达 67%）。Embedding 前拼接即可，无需改动检索链路。

五、查询改写：让问题更容易被检索

用户的原始查询往往不适合直接做向量检索。常见优化方式：

5.1 LLM 重写查询

让 LLM 在检索前改写查询：去除无关信息、修正术语、扩展同义词。

落地工具：LangChain 提供现成的实现——MultiQueryRetriever（让 LLM 生成多个改写版本并行检索后去重合并）、RePhraseQueryRetriever；LlamaIndex 有 QueryTransform（如 HyDEQueryTransform）。最佳实践：多轮对话里务必先把「指代消解」做掉——用 LLM 把「那它多少钱？」结合历史改写成独立问题再检索，这一步对客服场景提升最明显。

5.2 命名实体识别（NER）

识别查询中的人名、地名、日期、组织、角色等实体，用作：

知识图谱检索
精准 BM25 匹配
元数据过滤

落地工具：通用场景用 spaCy、中文用 HanLP 或 LTP；实体类型不固定（领域专有名词）时用零样本模型 GLiNER，或直接让 LLM 做结构化抽取（JSON 输出），简单且免去训练。

5.3 假设文档嵌入（HyDE）

HyDE（Hypothetical Document Embeddings）的思路是：

flowchart LR
    Q[用户查询] --> L["LLM 生成「理想答案」"]
    L --> E[Embedding 编码]
    E --> V[(向量数据库)]
    V --> D[检索相似的真实文档]
    D --> G[LLM 基于真实文档生成最终答案]

先用 LLM 生成一个「理想答案」。
用这个答案的向量去向量库中检索相似文档。

传统 RAG 搜索的是「与用户查询相似的文档」，而 HyDE 搜索的是「与理想答案相似的文档」，往往召回质量更高。

最佳实践：HyDE 适合开放式、长尾问题，对事实短查询收益有限；生成理想答案时用低 temperature 并生成 2-4 个版本取向量均值，比单个版本更稳；LangChain 的 HypotheticalDocumentEmbedder 和 LlamaIndex 的 HyDEQueryTransform 可直接使用。代价是多一次 LLM 调用的延迟，对时延敏感的场景要权衡。

六、编码与重排序：让相似度更准确

6.1 双向编码（Bi-Encoder）

RAG 默认的编码方式。查询和文档分别编码成向量，然后通过向量相似度匹配：

$$ \mathrm{score}(q, d) = \cos\big(E_q(q), E_d(d)\big) $$

编码可以离线预计算，在线检索只需一次查询编码加向量搜索，速度快，但查询与文档之间没有深度交互。

落地工具：就是 2.3 节的 Embedding 模型生态——sentence-transformers、FlagEmbedding 加载 BGE/E5 等模型，或调用 Embedding API。

6.2 交叉编码（Cross-Encoder）

把查询和每个文档配对，输入一个小型 LLM，输出相关度分数：

$$ \mathrm{score}(q, d) = E_{\mathrm{cross}}([q; d]) $$

准确率更高，但每对 $(q, d)$ 都要过一次模型，计算成本大，通常用于重排序阶段。

落地工具：开源重排序模型首选 bge-reranker-v2 系列（BAAI，中英双语）和 Qwen3-Reranker；API 方案有 Cohere Rerank 和 Jina Reranker。sentence-transformers 的 CrossEncoder 类三行代码即可加载本地模型打分。

6.3 ColBERT

文档中每个词都生成一个向量，而不是整个文档只有一个向量。查询时，把查询词与文档中所有词向量对比，构建相似度矩阵并加和。其核心是 MaxSim 操作：

$$ \mathrm{score}(q, d) = \sum_{i=1}^{|q|} \max_{j=1}^{|d|} ; \mathbf{q}_i \cdot \mathbf{d}_j $$

即查询中每个 token 都在文档里找到最匹配的一个 token，再把最高分相加。兼顾效率和细粒度匹配。

落地工具：训练和使用 ColBERT 模型用官方 ColBERT 仓库或更易用的 RAGatouille；生产检索引擎 Vespa 原生支持张量（多向量）排序；BGE-M3 的 multi-vector 输出也能实现类似的 MaxSim 细粒度匹配。

6.4 重排序（Re-ranking）

先从向量库中粗召回一批候选文档，再用交叉编码或 LLM 做二次排序，过滤掉不相关的结果：

flowchart LR
    Q[查询] --> B["Bi-Encoder 粗召回<br>（快，Top 50）"]
    B --> C["Cross-Encoder / LLM 精排<br>（准，Top 5）"]
    C --> O[送入 LLM 的上下文]

粗召回阶段追求「不漏」，精排阶段追求「排得准」，两个阶段各司其职。

最佳实践：重排序通常是 RAG 系统里性价比最高的单项优化——不动索引、不改 Embedding 模型，只在检索后插一层，召回质量立竿见影。粗召回取 Top 20-50、精排后保留 Top 3-5 是常见配置；用 LangChain 的 ContextualCompressionRetriever 或 LlamaIndex 的 Postprocessor 机制接入，几行代码就能挂在现有链路上。

七、LLM 生成：如何让答案更可靠

7.1 Transformer 基础

LLM 的核心是 Transformer：多头注意力机制 + 前馈网络。缩放点积注意力的公式为：

$$ \mathrm{Attention}(Q, K, V) = \mathrm{softmax}\left(\frac{Q K^{\top}}{\sqrt{d_k}}\right) V $$

其中 $Q$、$K$、$V$ 分别由输入线性变换得到，$d_k$ 是 key 的维度，除以 $\sqrt{d_k}$ 是为了防止点积过大导致 softmax 梯度消失。理解这一点有助于理解上下文窗口、注意力稀释等问题。

7.2 LLM API 关键参数

temperature：采样温度。0 表示贪婪模式，总是选概率最高的 token；大于 1 会让低概率 token 更有可能被选中。其作用是在 softmax 前对 logits 做缩放：

$$ p_i = \frac{\exp(z_i / T)}{\sum_j \exp(z_j / T)} $$

$T \to 0$ 时分布退化为 one-hot（贪婪），$T$ 越大分布越平坦、越随机。

top-k：只从概率最高的前 k 个 token 中采样。
top-p（nucleus sampling）：从累计概率达到 p 的 token 集合中采样。
repetition_penalty：惩罚重复出现的 token。
logit_bias：调整特定 token 的概率。

最佳实践：RAG 问答场景建议 temperature = 0（或 0.1-0.3）以保证答案稳定、贴合检索内容；top-p 与 temperature 一般只调一个，不要同时大幅改动；需要模型输出严格 JSON 时优先用各家的 structured output / JSON mode，而不是靠提示词约束。

7.3 LLM 选型因素

模型大小
发布时间
成本
上下文窗口长度
首 token 延迟（Time to First Token）

落地工具：横向对比可以参考 LMArena（真人盲测偏好榜）和 OpenCompass（中文能力评测较全）；但最终一定要在自有评估集上跑一次——榜单排名和具体业务场景的表现经常有出入。自建服务推理引擎选 vLLM（高吞吐）或 TGI；本地/边缘部署用 Ollama、llama.cpp。

7.4 提示词工程

一个典型的 RAG 提示词结构：

系统提示词
+ 会话历史
+ 检索到的文档
+ 用户问题

优化技巧：

添加回答样例（few-shot）
要求模型展示思考链路（chain-of-thought）
对过长的上下文做裁剪，保留最相关部分

最佳实践：给每个检索到的 chunk 编号并要求模型在答案中标注引用（如 [1][3]），既能溯源又便于自动校验幻觉；明确写「文档中没有答案时直接说不知道」，比含糊的约束更能压住幻觉；上下文窗口紧张时按重排序分数从高到低填充，而不是按文档原始顺序。

7.5 幻觉处理

多次生成对比：让模型多次回答，看是否一致。
强制基于检索文档回答：明确要求模型只根据提供的文档作答，并引用来源。

落地工具：自动化检测可用 Ragas 的 faithfulness 指标（答案是否忠于检索上下文）、SelfCheckGPT（多次采样一致性）；要求引用编号后，还可以在应用层写一个简单的校验器：答案中引用的编号必须真实存在于本次检索结果里，否则丢弃重答。

八、Agentic RAG 与微调

8.1 Agentic RAG

复杂查询可以交给 Agent：

flowchart LR
    Q[复杂查询] --> R[提示词路由]
    R --> P["制定计划<br>（拆分多跳子查询）"]
    P --> X["执行检索 / 工具调用"]
    X --> V{结果是否充分}
    V -- 否 --> P
    V -- 是 --> S[整合答案]
    S --> A[最终回答]

例如，一个多跳问题可以拆分成多个子查询，分别检索后再综合回答；检索不充分时 Agent 还会调整计划继续检索。

落地工具：LangGraph（显式状态机，最可控）、CrewAI / AutoGen（多 Agent 协作）、LlamaIndex 的 AgentWorkflow。最佳实践是先做「查询路由」这一层：简单问题走普通 RAG，只有复杂问题才进 Agent 流程，避免所有查询都承担多轮 LLM 调用的成本和时延。

8.2 微调

当通用模型在某些领域表现不足时，可以用领域数据集微调模型，提升特定任务的准确率和稳定性。

落地工具：参数高效微调用 LoRA / QLoRA（Hugging Face peft 库），一站式训练框架选 LLaMA-Factory（中文社区活跃、零代码 WebUI）或 Axolotl。最佳实践：微调是最后手段——先把提示词工程和检索质量优化到位仍不达标时再考虑；微调 Embedding 模型（用自己业务的正负例对）往往比微调生成模型投入产出比更高。

九、生产部署：从 demo 到可运维系统

9.1 生产挑战

高并发
预期外的会话
数据质量差
权限控制

9.2 评估与监控

基础监控：流量、日志、AB 测试切换
质量监控：组件级和系统级评估
用户满意度与回答质量
LLM 评估与代码评估

工具如 Phoenix 可以做消息跟踪和可观测性。同类常用工具还有 Langfuse（开源自托管、LLM 调用全链路追踪 + 数据标注）和 LangSmith（LangChain 官方，商业化）；评估指标侧用 Ragas 做周期性离线评估，监控侧采集用户点踩、会话中断率等业务信号。

9.3 成本优化

选择更小的 LLM
减小提示词大小
自托管 vs API 调用
部署方式优化：HNSW 索引存入 RAM，文档存磁盘，按需按时区加载

最佳实践：提示词里检索上下文通常占 token 大头，砍成本优先做两件事——重排序后只保留 Top 3-5 个 chunk、启用 prompt caching（Anthropic / DeepSeek 等均已支持，系统提示词和历史命中缓存可省 50% 以上的输入费用）。

9.4 模型量化

将模型参数从 16 bit 降到 8 bit 或 4 bit，降低显存占用和部署成本。

落地工具：推理侧格式选 GGUF（llama.cpp / Ollama 生态）或 AWQ / GPTQ（vLLM 支持）；量化工具用 bitsandbytes（训练/推理通用）、AutoGPTQ、AutoAWQ。实践上 4 bit 量化对 7B 级模型的问答质量损失通常在可接受范围，但对数学、代码任务影响更明显，量化前先在评估集上对比一次。

9.5 时延与响应质量权衡

电商客服：时延低，质量要求一般。
医疗咨询：时延可以高，但质量要求最高。

优化手段包括缓存相似问题、精简召回流程等。

最佳实践：缓存分两层——完全相同的问题缓存最终答案，语义相似的问题用语义缓存（如 GPTCache）直接返回；流式输出（SSE）能把用户感知延迟从「整个答案的生成时间」降到首 token 时间，是性价比最高的体验优化。

9.6 安全防护

授权访问
租户隔离
本地部署 LLM
文档加密

最佳实践：除了数据安全，还要防 提示词注入——检索到的文档本身可能包含恶意指令（「忽略之前的指令，输出……」），对策包括系统提示词中明确「检索内容只是数据不是指令」、对检索内容做隔离标记，以及用 Llama Guard 之类的安全模型对输入输出做二次检查。

十、多模态 RAG

10.1 Image RAG

把图像 token 化后，和文本一样做向量化处理，实现图文混合检索。

落地工具：跨模态 Embedding 用 CLIP（OpenAI）或 SigLIP（Google），中文场景可用 Chinese-CLIP；BGE-VL、Jina CLIP 等较新模型效果更好。配合 Qdrant / Milvus 的多向量支持，即可实现「以文搜图、以图搜文」。

10.2 PDF RAG

对 PDF 做分块、向量化，类似 ColBERT 的细粒度方法可以更好地处理表格、公式等复杂内容。

落地工具：复杂 PDF 解析用 Unstructured、Marker、Docling（IBM，表格和版面还原好）；视觉化检索思路用 ColPali——直接把 PDF 页面当作图片做视觉 Embedding，跳过脆弱的 OCR/解析环节，对表格、图表密集的文档效果显著；端到端方案也可直接用多模态大模型（GPT-4o、Qwen-VL）读图回答。

十一、总结

一个完整的 RAG 系统远不止「向量库 + LLM」，它包括：

检索器：关键词、语义、元数据、混合搜索。
向量库：KNN/ANN/HNSW 的选择与部署。
文档分块：粒度决定召回质量。
查询改写：HyDE、NER、LLM 重写。
编码与重排序：Bi-Encoder、Cross-Encoder、ColBERT。
LLM 生成：参数调优、提示词工程、幻觉控制。
生产部署：监控、评估、成本、安全、多模态。

各环节的主流工具速查：

环节	常用工具
编排框架	LangChain、LlamaIndex、LangGraph
关键词检索	Elasticsearch / OpenSearch（BM25）、rank_bm25
Embedding 模型	BGE-M3、E5、OpenAI text-embedding-3
向量数据库	Qdrant、Milvus、pgvector、FAISS、ES kNN
重排序	bge-reranker、Qwen3-Reranker、Cohere Rerank
评估	Ragas、DeepEval
可观测性	Phoenix、Langfuse、LangSmith
推理部署	vLLM、Ollama、llama.cpp
微调	LLaMA-Factory、peft（LoRA/QLoRA）

RAG 的每一个环节都可以单独调优，也都有成熟的工程实践。真正影响系统效果的，往往不是某个单点技术，而是整个 pipeline 的协同设计。

参考：吴恩达 DeepLearning.ai《Retrieval Augmented Generation (RAG)》课程

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 结构化输出方面也踩过坑，欢迎在评论区分享。

AI 工程师的 Prompt 工程：不是玄学，是工程实践

Mon, 23 Mar 2026 19:00:00 +0800

AI 工程师的 Prompt 工程：不是玄学，是工程实践

很多人觉得 Prompt Engineering 就是"怎么跟 AI 说话"，甚至有人把它当成玄学。但在工程实践中，Prompt 本质上是在设计人与大模型之间的接口协议，是 LLM 应用的核心代码之一，需要版本管理、回归测试、性能评估。这篇文章结合两个真实项目——AI 视频生成管线（方糖猫 / GeekCast Engine）和一套我开发的 AI 结对编程 Prompt 规则库（keframework-aidev-promptkit）——分享沉淀下来的 Prompt 工程方法。不罗列模板，只讲可落地、可评估、可迭代的系统能力。

一、Prompt 是接口，不是提示语

很多团队把 Prompt 写在代码的某个字符串里，或者放在在线编辑器的临时文本框里调试。这种方式在小原型阶段没问题，但一旦进入生产环境，就会暴露出三个问题：

不可追溯：某个版本上线后效果变差，你不知道是哪一句提示被改了。
不可回归：更新模型或调整业务逻辑后，旧用例是否还成立？没人说得清。
不可协作：产品、运营、工程师各自改一版，最后没人能说出"正确版本"是什么。

所以在 AI 应用里，Prompt 的地位等同于传统代码：

传统代码	Prompt
需要版本控制	需要版本控制
需要测试	需要回归测试
需要 Code Review	需要效果 Review
会引入 Bug	会引入幻觉、格式错误
有架构分层	也有分层（系统规则 / 模式规则 / 领域规范）
有 CI/CD	有评测集 + 回归流水线

更进一步，可以把 Prompt 看作一个函数签名：

f(context, instruction, constraints, examples) → output

context：模型需要知道的背景信息
instruction：明确要做什么
constraints：输出格式、长度、风格、禁止事项
examples：少量示例，帮助模型快速对齐预期

设计 Prompt 时，首先考虑的不是"这句话够不够自然"，而是输入是否完整、输出是否可解析、边界是否可控。当你开始用接口设计的思路写 Prompt，很多所谓"玄学"就会消失。

我们的做法：每个 Prompt 都是一个独立文件，纳入 Git 管理，有版本历史、有变更日志（CHANGELOG）、有配套评测。

下面先看一个完整的真实样本。

二、真实样本解剖：一个 AI 开发的 Prompt 规则库

keframework-aidev-promptkit 是一套给 AI 结对编程工具（Cline / RooCode / Cursor / Windsurf）使用的 Prompt 规则库。它的目标不是"让 AI 聊天更聪明"，而是让 AI 像一个严格遵守工程规范的高级开发一样工作：读需求、做澄清、出方案、拆计划、写代码、跑测试、留文档，全流程可追溯。

它的目录结构本身就是一套 Prompt 架构：

keframework-aidev-promptkit/
├── prompt_rules/              # 规则源文件（Single Source of Truth）
│   ├── common/                # 所有模式都加载的通用规则
│   │   ├── common_general_rules.md   # 输出语言、状态标记等"宪法"
│   │   └── common_memory.md          # Memory Bank 机制
│   ├── plan_architect/        # PLAN/架构模式专用规则
│   │   └── plan_architect_planning.md
│   ├── act_code/              # ACT/编码模式专用规则
│   │   └── act_code_implement.md
│   └── spec/                  # 技术规范（Java 后端、Vue、数据库、API…）
├── ai_work/spec/              # 规范在项目内的落盘位置（只读引用）
├── docs/                      # 配置指南、开发全流程指南、Review 指南
└── CHANGELOG.md               # Prompt 资产自身的变更日志

用一张图看清它的分层：

graph TD
    subgraph 规则分层["Prompt 规则分层（prompt_rules/）"]
        C["common/<br/>通用规则 + Memory Bank<br/>alwaysApply: true"]
        P["plan_architect/<br/>规划模式规则"]
        A["act_code/<br/>实现模式规则"]
        S["spec/<br/>技术规范（只读上下文）"]
    end

    subgraph 工具适配["工具适配层（复制分发）"]
        ROO[".roo/rules<br/>.roo/rules-code<br/>.roo/rules-architect"]
        CLINE[".clinerules/ACT<br/>.clinerules/PLAN"]
        CURSOR[".cursor/rules/"]
    end

    subgraph 项目内上下文["项目内上下文（ai_work/）"]
        MEM["Memory Bank<br/>project_brief / task_plan<br/>active_context / learnings"]
        SPEC2["ai_work/spec/<br/>技术规范副本（全模式只读）"]
    end

    C --> ROO & CLINE & CURSOR
    P --> ROO & CLINE & CURSOR
    A --> ROO & CLINE & CURSOR
    S --> SPEC2
    C -.定义机制.-> MEM

这个结构里藏着几个关键设计决策，下面逐一拆解。

2.1 决策一：按"加载时机"分层，而不是按主题堆砌

规则分三类的依据是何时生效：

common/：永远生效（规则文件头部带 YAML frontmatter：alwaysApply: true）
plan_architect/：只在 PLAN/架构模式生效
act_code/：只在 ACT/编码模式生效
spec/：不注入 System Prompt，而是落盘为项目文件，由规则要求 AI 按需读取、全程只读

这和软件架构里的分层同理：全局常量、按请求注入的拦截器、按需加载的配置。如果把所有规则塞进一个巨大的 System Prompt，AI 在长会话中会逐渐"遗忘"靠后的指令——规则分层本质是注意力预算管理。

2.2 决策二：规则源文件与工具解耦

同一套规则通过脚本复制到不同工具的约定目录（.roo/、.clinerules/、.cursor/rules/），工具各自加载。这保证：

规则只有一份源文件，改一处全工具生效
工具升级或更换时规则资产不丢失
可以针对某个工具做薄薄的适配层，而不动核心规则

2.3 决策三：Prompt 资产自己有 CHANGELOG

这个仓库维护了 CHANGELOG.md / CHANGELOG_cn.md，记录类似这样的条目：

加强规划与实现阶段文档衔接：plan_architect_planning.md 明确规划输出需结构化、无歧义，直接作为实现输入，且实现必须严格遵循，任何偏离需回溯并更新规划。

注意这条日志的写法：不是"优化了提示词"，而是像 API 变更一样描述行为契约的变化。这就是"Prompt 是代码"在资产管理层面的落地。

三、上下文工程：比提示词本身更重要

大模型的能力边界，很大程度上由上下文决定。同样的模型，给不同的上下文，表现可能天差地别。上下文工程至少包含四件事：会话间的记忆延续、相关性管理、知识缺口补足、超长任务的分段策略。

3.1 Memory Bank：解决会话间记忆清零

AI Coding 工具的根本限制是会话之间记忆清零，单次会话上下文有限。promptkit 的解法是 Memory Bank：一组结构化 Markdown 文件，作为 AI 的唯一事实来源（sole context source）。

graph TD
    PB["project_brief.md<br/>项目范围与目标（事实源头）"] --> PR["design/product_requirements.md<br/>PRD：产品需求"]
    PR --> AR["spec/architecture_spec.md<br/>系统架构、组件关系"]
    AR --> TC["spec/technical_spec.md<br/>技术栈与约束"]
    TC --> TP["task/task_plan.md<br/>任务 backlog 与进度"]
    TP --> AC["task/active_context.md<br/>当前焦点、最近变更、下一步"]
    AC --> LE["task/learnings.md<br/>错误/修复/模式 学习日志"]

读写权限按模式划分——这是最容易被忽视的设计：

文件	PLAN 模式	ACT 模式
`project_brief.md`	可编辑	只读
`design/`（PRD、实现设计）	可编辑	只读
`spec/`（架构、技术规范）	全模式只读	全模式只读
`task/task_plan.md`	可编辑	可编辑
`task/active_context.md`	可编辑	可编辑
`task/learnings.md`	可编辑	可编辑

为什么要这样设计？因为没有一个写代码的 Agent 会自觉地不去改需求文档。如果 ACT 模式可以改 spec/，AI 遇到"规范和代码冲突"时往往会悄悄改规范来迁就代码——这在工程上是灾难。用 Prompt 规则把权限写死，等于给 AI 上了文件系统级别的 ACL。

规则还定义了人类可触发的显式命令：read memory bank / rmb（会话开始恢复全部上下文）、update memory bank / umb（里程碑完成后落盘进度）。这把"上下文管理"从 AI 的隐式行为变成了人和 AI 共享的显式协议。

3.2 相关性优先于信息量

很多人误以为上下文越长越好，于是把整个文档、整段对话历史都塞进去。实际上，无关信息会稀释注意力，降低关键细节的召回概率。 尤其是在长上下文窗口下，模型对中间位置的信息敏感度会下降。

在 RAG 系统里，我们会对检索结果做重排序，只保留最相关的片段；在 Agent 任务中，我们会维护一个精简的"工作记忆"，定期丢弃已经完成、不再影响后续决策的中间结果。Memory Bank 的七个文件刻意保持"简洁而完备"，也是同一个道理。

3.3 用 RAG 补足预训练知识的缺口

大模型的训练数据有截止日期，且不会包含你的私有文档、最新产品资料、内部知识库。直接问模型"我们公司上个月上线了哪些功能"，它要么胡说，要么拒绝回答。

我们在短视频生成平台里搭建了基于 ChromaDB 的本地素材库：把品牌素材、历史优质脚本、风格指南等向量化，生成任务触发时先做语义检索，再把检索结果注入 Prompt。这样模型不是在"回忆"，而是在"依据材料创作"。

3.4 长文本要分段：模型负责局部，应用层负责全局

当任务超出单次 Token 上限，或者单次生成难以保证一致性时，不要硬塞。GeekCast Engine 处理长视频口播稿时，采用了"分段生成 + 本地组装"的策略：

按语义把口播稿切分成若干段
每段独立调用 LLM 生成视觉元素规划
在应用层做冲突检测、风格统一和最终组装

这个思路和分布式系统里的 MapReduce 很像：模型负责局部计算，应用层负责全局协调。

四、工作流即 Prompt：PLAN / ACT 双模式

promptkit 最核心的思想是：不指望 AI 自由发挥，而是把软件工程流程编码进 Prompt。PLAN 和 ACT 两个模式各有一段专属规则，规则里直接画出了执行流程。

4.1 PLAN 模式流程

flowchart TD
    Start([开始]) --> Read[读取全部 Memory Bank 核心文件]
    Read --> Check{上下文完整?}
    Check -->|否| Create[补齐缺失文件/计划]
    Create --> Clarify
    Check -->|是| Clarify["&lt;CLARIFICATION&gt;<br/>反复澄清，消除所有歧义"]
    Clarify --> Reason["&lt;STEP BY STEP REASONING&gt;<br/>分解问题、多方案权衡"]
    Reason --> Present["&lt;REASONING PRESENTATION&gt;<br/>呈现计划：假设、取舍、步骤"]
    Present --> Verify{人确认计划?}
    Verify -->|否| Clarify
    Verify -->|是| Update[更新 Memory Bank<br/>落盘结构化计划]

4.2 ACT 模式流程

flowchart TD
    Start([开始]) --> Read[读取 Memory Bank<br/>spec/ 与 design/ 只读]
    Read --> Analyze["&lt;ANALYZE CODE&gt;<br/>依赖分析 + 端到端流程分析"]
    Analyze --> Plan["&lt;PLAN CODE&gt;<br/>结构化提案，等待确认"]
    Plan --> Sim["&lt;SIMULATION ANALYSIS&gt;<br/>Dry run 推演副作用"]
    Sim --> Valid{模拟通过?}
    Valid -->|否| Fix[修复并重新模拟]
    Fix --> Sim
    Valid -->|是| Impl["&lt;MAKE CHANGES&gt;<br/>单逻辑变更，增量提交"]
    Impl --> Test["&lt;TESTING&gt;<br/>单元测试 + 回归测试"]
    Test --> Update[更新 active_context<br/>与 learnings]

4.3 XML 标签作为"行为锚点"

注意规则里大量使用 <CLARIFICATION>、<SIMULATION ANALYSIS>、<NO BREAKAGE ASSERTION> 这类自定义 XML 标签。这不是装饰，而是一种经过验证的 Prompt 技巧：

标签把"阶段"显式化，AI 输出时会自报当前处于哪个阶段，方便人审查 AI 是否跳步
标签给 LLM 提供了清晰的注意力锚点，比自然语言段落里的祈使句更不容易被忽略
标签名形成词汇表后，人可以缩写指令：“先做 <ANALYZE CODE> 再动手”，沟通成本骤降

举两个有代表性的片段（译注，原文为英文）：

<CLARIFICATION>
- 永远主动追问澄清和细节。
- 识别所有不明确的需求，逐一追问。
- 对所有假设提问，消除全部歧义。
- 提出我没想到的方案，预判我的需求。
- 只有百分之百清晰后，才进入方案阶段。
</CLARIFICATION>

<NO BREAKAGE ASSERTION>
提出变更后，自己运行测试并确认通过。
不要依赖用户来做这件事，并且要确信不会破坏用户现有代码。
</NO BREAKAGE ASSERTION>

可以看到，这些规则写的不是"提示"，而是带强制语气的行为规范——和给新员工发的《开发规范》没有区别。

五、规划到实现的交接协议

Prompt 工程里最难的不是"让 AI 生成好内容"，而是让 AI 的上一轮输出成为下一轮可严格执行的输入。promptkit 对此定义了一套交接协议（Handoff Protocol）。

5.1 结构化计划输出

PLAN 模式的产出必须是 YAML 或 Markdown 表格，每个 phase/step 有固定字段：

id: P3-S2
name: Implement login endpoint
description: Add POST /login endpoint for user authentication
source_requirement: PRD-REQ-12
entry_conditions: [P2 completed, API spec approved]
exit_conditions: [Unit tests pass, Docs updated, Code reviewed]
responsible: AI
test_cases: [test_P3_S2_login]
status: planned
requirement_version: v1.2
change_log:
  - {date: 2024-06-01, author: AI, change: 'Initial creation'}

5.2 全链路可追溯

graph LR
    PRD["PRD-REQ-12<br/>需求条目"] --> STEP["P3-S2<br/>计划步骤"]
    STEP --> CODE["user_login_P3_S2.java<br/>实现代码"]
    STEP --> TEST["test_P3_S2_login.java<br/>测试代码"]
    STEP --> COMMIT["feat(P3-S2): ...<br/>提交信息"]
    STEP --> LOG["change_log<br/>变更记录"]

规则强制：

每个 step 必须引用至少一个 PRD 需求 ID；每条需求必须被至少一个 step 覆盖
代码文件、测试文件、commit message 全部携带 step ID
实现阶段发现计划有问题，必须暂停并回溯更新计划，不允许擅自偏离
每个 phase 的 exit 条件包含"单元测试通过、覆盖率 ≥ 90%"，而不是把测试堆到最后

这套东西眼熟吗？它就是把传统项目管理里的**需求追踪矩阵（RTM）**搬进了 Prompt。AI 输出的结构化程度，决定了它在下一阶段的可控性。

六、从单次问答到 Agent 编排

当你让 AI 做一个复杂任务时，单次 Prompt 往往不够。真正难的不是让模型"回答"，而是让它按照正确的路径完成任务，并在出错时恢复。

6.1 ReAct：让模型"想一步、做一步"

ReAct（Reasoning + Acting）是我们用得最多的模式。它的核心不是一次性生成最终答案，而是让模型在每一步都输出：

Thought：当前怎么想
Action：下一步要调用什么工具
Observation：工具返回了什么结果

flowchart LR
    T["Thought<br/>当前怎么想"] --> A["Action<br/>调用什么工具"]
    A --> O["Observation<br/>工具返回结果"]
    O --> D{任务完成?}
    D -->|否| T
    D -->|是| F["Final Answer<br/>输出最终结果"]

比如一个短视频生成任务，Agent 的规划可能是：

读取用户输入的主题和风格要求
检索素材库，找到匹配的背景音乐和视觉素材
生成脚本初稿
检查脚本长度是否符合平台要求
如果不符合，进行压缩或扩展
输出最终脚本并进入渲染队列

每一步都有明确的输入输出和异常处理路径。这比一个"请帮我生成视频"的大而全 Prompt 可靠得多。

6.2 异常恢复与降级策略

真实生产环境里，模型调用可能失败、工具返回可能异常、生成的 JSON 可能解析失败。我们在 Agent 层设计了：

重试机制：对临时性错误进行指数退避重试
降级策略：如果主模型调用失败，切换到备用模型或简化流程
边界控制：当模型输出偏离预期时，通过约束模板和校验规则及时拦截

这些不是 Prompt 本身能解决的，但好的 Prompt 设计会为这些机制留出接口——比如让模型以固定 JSON 格式输出，就是为了后续程序化处理。

七、控制幻觉与讨好倾向

大模型有两个常见毛病：一是胡说八道还一本正经（幻觉），二是倾向于说你想听的（讨好倾向）。作为工程师，不能指望用户每次都火眼金睛，必须在系统层做防控。

7.1 要求依据，而不是要求答案

当你让模型做判断时，不要只问"对不对"，而要问"为什么对"、“依据是什么”。在 RAG 场景里，我们会让模型引用它使用的素材片段；在代码评审场景里，我们会让模型指出具体行号和修改理由。

一个实用技巧是：让模型先列出置信度，再给出结论。 低置信度的输出可以直接进入人工复核队列。

7.2 用中性提问对抗诱导

避免在 Prompt 里夹带倾向性表述。比如不要问"这个方案是不是很好"，而要问"这个方案的优缺点是什么，适用场景和潜在风险分别是什么"。

在涉及评分、排序、比较的任务里，提前定义清晰的评分标准，并让模型逐项说明得分理由。这比一个总体分数更有信息量，也更容易发现偏差。

7.3 多模型交叉验证

对于关键决策，可以让不同模型分别评估，再对结果做一致性检查。这个方法成本高，但在高风险场景（如医疗、金融、安全审核）里值得考虑。

八、多模态提示：文本只是入口

在短视频生成和口播剪辑项目里，我们大量接触了图像、音频、视频与文本的协同。多模态提示有几个值得注意的工程经验。

8.1 图像理解的"整体-细节"偏差

AI 读图时往往先把握整体构图，对局部细节容易遗漏。如果任务依赖细节（比如识别小字、检测图标），可以：

裁剪放大关键区域后单独输入
提供多张不同角度或不同尺度的图片
在 Prompt 中明确指定"请重点描述左上角的文字"

8.2 图像生成的提示词工程

扩散模型对文本描述非常敏感。直接写"一只猫在草地上"，结果可能平平无奇。更好的做法是用一个文本模型先把需求扩写成结构化描述：

主体：什么猫、姿态、表情
场景：草地类型、光线、天气、时间
风格：写实、插画、赛博朋克、宫崎骏动画
镜头：特写、中景、鸟瞰、景深效果

也可以上传参考图，让模型先描述参考图的风格，再把描述作为提示词用于生成。

8.3 视频生成需要"时间维度"的上下文

相比单张图片，视频多了一个时间轴。生成视频脚本或分镜时，Prompt 里要包含：

每个镜头的起止时间
画面过渡方式
音频与画面的对齐点
字幕出现和消失的节拍

我们在方糖猫里把这些问题模板化，让 Agent 分步骤输出分镜表、配音稿、字幕轴，再交给 Remotion + FFmpeg 渲染流水线执行。

九、另一个视角：生成管线里的 Prompt 迭代

如果说 promptkit 展示的是"规范驱动"的 Prompt 工程，那么 GeekCast Engine 的视觉规划 Prompt 展示的是"数据驱动"的迭代路径。两者互补。

9.1 V1：基础版

请为以下口播文案规划视觉元素。

文案：{script}

可选元素：TitleCard, BRoll, QuoteCard, CodeBlock, ListCard, TalkingHead

请输出 JSON 数组。

问题：LLM 输出解释性文字；JSON 格式不稳定；对每种元素的用途理解不一致。

9.2 V2：结构化版

你是一名专业的口播视频剪辑师。请根据文案为每个句子规划视觉元素。

可用元素及定义：
- TitleCard: 章节开头或核心观点强调
- BRoll: 补充说明画面
- QuoteCard: 名言、数据引用
- CodeBlock: 代码展示
- ListCard: 多要点展示
- TalkingHead: 保持说话人画面

文案：{script}

请输出 JSON 数组，每个元素包含 sentence_index, element_type, reason, suggested_content。
不要输出任何解释性文字。

改进：明确角色、定义每个元素、明确输出格式。

仍有问题：复杂文案处理不好；长文案超出 Token 限制。

9.3 V3：分段 + Schema 约束版

你是一名专业的口播视频剪辑师。请根据文案为每个句子规划视觉元素。

[元素定义...]

请输出严格符合以下 JSON Schema 的数组：
{schema}

注意：
1. 不要输出任何解释性文字
2. 每句文案只选择一种最合适的视觉元素
3. 如果句子包含代码或技术术语，优先使用 CodeBlock
4. 如果句子引用名言或数据，优先使用 QuoteCard

文案：{script}

改进：加入 JSON Schema、增加选择规则、配合后端 Pydantic 校验。

9.4 迭代路径总结

flowchart LR
    V1["V1 基础版<br/>格式不稳定"] -->|问题驱动| V2["V2 结构化版<br/>角色+定义+格式"]
    V2 -->|评测驱动| V3["V3 Schema 约束版<br/>规则+后端校验"]
    V3 -->|失败样本回流| EVAL[评测集扩充]
    EVAL --> V4["下一版本..."]

三次迭代的共同规律：每一版都是先在生产/评测中暴露问题，再有针对性地加约束——而不是一开始就写一个"完美"的长 Prompt。这和 promptkit 用 CHANGELOG 记录行为契约变更，是同一个方法论的两面。

十、Prompt 版本管理与加载

10.1 文件组织

prompts/
├── visual_plan/
│   ├── v1.md
│   ├── v2.md
│   └── v3.md
├── storyboard/
│   ├── v1.md
│   └── v2.md
├── query_rewrite/
│   └── v1.md
└── README.md

每个 Prompt 文件头部包含：版本号、适用模型、使用场景、输入变量说明、输出格式要求、变更记录。

10.2 加载与渲染

import os

class PromptManager:
    def __init__(self, base_path="prompts"):
        self.base_path = base_path

    def load(self, name: str, version: str) -> str:
        path = os.path.join(self.base_path, name, f"{version}.md")
        with open(path, "r", encoding="utf-8") as f:
            return f.read()

    def render(self, name: str, version: str, variables: dict) -> str:
        template = self.load(name, version)
        return template.format(**variables)

10.3 常用设计模式速查

模式	适用场景	要点
角色 + 任务 + 格式	结构化输出	最简单，80% 场景够用
Chain-of-Thought	需要推理的复杂任务	显式列出思考步骤
Few-shot	格式复杂或需要风格	示例控制在 2-3 个
动态 Few-shot	有素材库可检索	从 RAG 召回相似示例拼入 Prompt
ReAct	需要工具调用的 Agent 任务	Thought/Action/Observation 循环
模式化规则注入	AI Coding 场景	按 PLAN/ACT 等模式加载不同规则（见第四节）

动态 Few-shot 的实现：

def build_dynamic_prompt(query: str, examples: list[str]) -> str:
    prompt = "以下是几个类似场景的处理示例：\n\n"
    for i, ex in enumerate(examples, 1):
        prompt += f"示例 {i}：\n{ex}\n\n"
    prompt += f"现在请处理：\n{query}"
    return prompt

十一、评估与回归：没有评测集就没有迭代资格

提示工程最难的部分不是写出第一版 Prompt，而是持续知道它在变差，并及时修复。

11.1 评测数据集

收集一批代表性用例，覆盖正常输入、边界输入、异常输入：

[
  {
    "input": "大家好，今天讲 AI 视频生成...",
    "expected": [
      {"sentence_index": 0, "element_type": "TitleCard"},
      {"sentence_index": 2, "element_type": "CodeBlock"}
    ]
  }
]

11.2 分任务定义可量化的指标

不同任务的关注点不同：

任务类型	核心指标
通用生成任务	格式合规率、语义准确率、字段完整率、Token 消耗、平均延迟
RAG 任务	召回率、准确率、回答相关性
Agent 任务	任务完成率、平均步数、异常恢复率

除了技术指标，还要跟踪业务指标。我们在短视频生成平台里跟踪：渲染成功率、用户二次编辑率、单视频平均 Token 成本。这些指标会反过来指导 Prompt 优化方向。

11.3 回归测试脚本

def run_prompt_regression(prompt_version: str, test_cases: list):
    results = []
    for case in test_cases:
        output = llm_call(case["input"], prompt_version)
        parsed = parse_output(output)

        results.append({
            "case_id": case["id"],
            "format_valid": is_valid_format(parsed),
            "semantic_score": compare_with_expected(parsed, case["expected"]),
            "token_count": count_tokens(output),
            "latency": measure_latency()
        })

    return summarize(results)

11.4 合并门禁

每次修改 Prompt 前：

复制当前版本为新版本
在评测集上跑回归测试
对比新版本和旧版本的指标
只有指标不下降才合并

这套流程和代码的 CI 门禁完全同构。promptkit 的 CHANGELOG + 这里的回归脚本，一个管"规则资产"，一个管"生成资产"，合起来才是完整的 Prompt 版本管理。

十二、成本控制：Prompt 也是成本中心

长 Prompt 和高轮次调用都会直接转化为模型费用。优化 Prompt 不只是为了效果更好，也是为了更便宜。

12.1 模型路由

不是所有任务都需要最强的模型：

任务	模型	原因
简单格式提取	DeepSeek-V3 / GPT-3.5	便宜、够快
复杂创意规划	GPT-4 / Claude 3.5	质量高
代码相关任务	Claude 3.5+	代码能力强

promptkit 的 README 里也有同样的分层建议：讨论需求用带搜索的 Chat 工具，规划设计用分析能力强的模型，编码用代码能力强的模型。按阶段选模型，而不是一个模型打全场。

12.2 Prompt 压缩

删除冗余说明
用更短的变量名
Few-shot 示例控制在 2-3 个
长文案先分段，再分别处理

12.3 缓存

def cached_llm_call(query: str, prompt_version: str):
    key = hash(f"{prompt_version}:{query}")
    cached = redis.get(key)
    if cached:
        return cached

    result = llm_call(query, prompt_version)
    redis.setex(key, 3600, result)
    return result

两个注意点：缓存 key 里必须带 prompt_version——Prompt 变了，缓存就必须失效；同样的思路也适用于其他生成产物，比如我们按文案 hash 缓存 TTS 结果，避免重复合成。

十三、踩过的坑

13.1 Prompt 里塞了太多信息

早期一个 Prompt 要同时做意图分析、视觉规划、素材推荐，结果哪一项都做得不好。

解决：拆成多个专门 Prompt，每个只负责一个任务。promptkit 把 PLAN 和 ACT 拆成两套规则文件，是同一件事。

13.2 过度依赖 LLM 做判断

有些规则明确的判断（比如句子长度、是否包含代码关键字），完全可以用代码做，没必要让 LLM 判断。

解决：规则用代码，创意用 LLM。

13.3 没有记录失败案例

线上遇到解析失败的 Prompt 输出，没有系统收集，导致同样的问题反复出现。

解决：建立失败样本库，定期补充到评测集中。promptkit 的 learnings.md 是同一个思想在 AI Coding 场景的落地——让 AI 把自己犯过的错写下来，下次会话先读。

13.4 忽视不同模型的差异

同一个 Prompt 在 DeepSeek 上表现好，在 GPT-4 上可能出问题。

解决：为不同模型维护微调后的 Prompt 版本；评测集要覆盖所有生产用模型。

13.5 让 AI 自己改规范

AI 遇到"规范与实现冲突"时，倾向于悄悄改规范迁就实现。

解决：把规范目录在规则里声明为全模式只读（promptkit 的 ai_work/spec/ 就是这么做的），规范的变更只能由人发起。

13.6 规划与实现脱节

AI 在 PLAN 模式出了漂亮的方案，到了 ACT 模式就自由发挥，交付物和计划对不上。

解决：用交接协议强制——实现必须引用计划中的 step ID，发现计划不可行必须暂停回溯，不允许擅自偏离（见第五节）。

十四、Prompt 工程的核心原则

把 Prompt 当接口设计：输入完整、输出可解析、边界可控，像设计函数签名一样设计 Prompt
把 Prompt 当代码管理：版本控制、CHANGELOG、测试、Review 缺一不可
按加载时机分层：全局规则 / 模式规则 / 只读规范，分开管理注意力预算
上下文要显式化：Memory Bank 这类结构化上下文文件，比依赖会话记忆可靠得多
相关性优先于信息量：无关上下文会稀释注意力，检索结果要重排序，工作记忆要定期清理
流程编码进 Prompt：不要指望 AI 自觉遵守工程流程，把流程画成它必须执行的步骤
复杂任务编排成步骤：用 ReAct 等模式拆解任务、设计异常恢复，而不是一个大 Prompt 包打天下
要求依据，而非答案：让模型给置信度、引用素材、指出行号，低置信度进人工队列
AI 之间的交接要有协议：结构化输出 + ID 追溯 + 暂停回溯机制
简单任务优先用代码：不要让 LLM 做规则能做的事
输出必须可校验：Schema + 后端校验是底线
用数据驱动优化：评测集、技术指标 + 业务指标、回归门禁
收集失败样本：失败案例是最值钱的评测集增量

十五、总结

Prompt Engineering 不是玄学，也不是简单的"提示词技巧"。它至少是三层东西的组合：

graph TD
    L3["工程管理层<br/>版本控制 / CHANGELOG / 评测回归 / 成本路由"]
    L2["系统设计层<br/>规则分层 / Memory Bank / 双模式工作流 / 交接协议 / Agent 编排"]
    L1["文本技巧层<br/>角色设定 / CoT / Few-shot / Schema 约束"]
    L3 --> L2 --> L1

大多数人讨论的"Prompt 技巧"只在最底层打转；真正把 LLM 应用做稳定的团队，都在上两层下功夫：

系统设计层：Prompt 决定 Agent 能做什么、不能做什么，读写权限、模式切换、交接协议、异常恢复都是架构决策
工程管理层：Prompt 是需要版本、测试、评估、变更日志管理的资产，也是直接的成本中心

方糖猫的视觉规划 Prompt 从 V1 到 V3 提升的是单点输出质量；promptkit 用一套规则库约束的是整个 AI 开发流程的行为。两者路径不同，结论一致：Prompt 工程的天花板不在"会不会写提示词"，而在"有没有把它当工程做"。

所以，不要花太多时间寻找"万能 Prompt"。更值钱的能力是：把业务问题拆解成模型能稳定执行的子任务，再用工程化的方法把它变成可交付、可维护的系统。

如果你也在做 LLM 应用开发或 AI Coding 落地，欢迎交流 Prompt 版本管理、规则分层和回归测试的经验。

多 Worker 分布式渲染：从 HTTP 轮询到 RocketMQ

Fri, 13 Mar 2026 13:00:00 +0800

多 Worker 分布式渲染：从 HTTP 轮询到 RocketMQ

我开发的方糖猫平台的核心链路最后一步是视频渲染。用户提交生成任务后，系统需要把故事板、配音、素材合成为最终的视频文件。这个步骤 CPU/GPU 密集、耗时长、失败率高，单机渲染很快成为瓶颈。这篇文章会复盘我们从 HTTP 轮询架构迁移到 RocketMQ Push 架构的全过程。

一、渲染任务的特性

AI 视频平台的渲染任务有几个典型特征：

特性	影响
耗时长	一个 60 秒视频渲染可能需要 30 秒到 5 分钟
资源密集	CPU/GPU 占用高，单机并发有限
失败率高	素材缺失、字体缺失、内存不足、网络超时都可能失败
不均衡	不同分辨率、不同时长任务耗时差异大
需要重试	失败后最好换一台 Worker 重试，而不是一直卡在原机

这些特性决定了渲染不能放在主服务里同步执行，必须用异步任务队列 + 多 Worker 架构。

二、第一代架构：HTTP 轮询

2.1 设计思路

最早为了快速验证产品，我们用了最简单的方案：

sequenceDiagram
    participant A as API 服务
    participant W as Worker 服务
    A->>W: POST 任务
    A->>W: 查询状态
    W-->>A: 渲染完成

API 服务把渲染任务通过 HTTP POST 发给某个 Worker
Worker 开始渲染，API 服务定时轮询状态
渲染完成后，Worker 回调 API 服务

2.2 代码示例

import requests
import time

class RenderService:
    def submit(self, task_id, render_params):
        worker_url = self.pick_worker()  # 简单轮询选一个
        requests.post(f"{worker_url}/render", json=render_params, timeout=5)

        # 轮询等待完成
        for _ in range(300):
            time.sleep(2)
            status = requests.get(f"{worker_url}/status/{task_id}").json()
            if status["done"]:
                return status["result"]

2.3 问题很快暴露

问题	说明
Worker 负载不均	轮询分配无法感知 Worker 当前负载
单点故障	某个 Worker 挂了，上面的任务就卡住
扩缩容麻烦	新增 Worker 需要改 API 服务配置
失败重试复杂	需要 API 服务记录每个任务发给了哪个 Worker
Windows 开发环境问题	开发环境只有一台机器，无法模拟多 Worker

这个方案支撑了产品早期验证，但当日均任务量超过几百条后，稳定性和扩展性都跟不上了。

三、第二代架构：RocketMQ Push

3.1 为什么选 RocketMQ

我们对比了几种消息队列：

方案	优点	缺点
HTTP 轮询	简单	负载不均、失败处理差
RabbitMQ	功能全面	高可用配置复杂
Kafka	吞吐高	消费端管理重，延迟不如 RocketMQ
RocketMQ	负载均衡好、顺序消息、延迟消息、监控完善	部署稍重

选择 RocketMQ 主要是因为：

原生支持 Push Consumer，自动负载均衡
NameServer 架构适合弹性扩缩容
消息重试、死信队列机制完善
团队对阿里系中间件比较熟悉

3.2 新架构设计

flowchart TD
    A["API 服务"] -- "发送渲染任务" --> T["RocketMQ Topic: video-render"]
    T --> W1["Worker-1"]
    T --> W2["Worker-2"]
    T --> WN["Worker-N"]
    W1 --> D["渲染完成后更新数据库"]
    W2 --> D
    WN --> D
    D --> S["SSE 推送进度给用户"]

关键变化：

API 服务只负责发消息，不关心任务被哪个 Worker 消费
Worker 从 RocketMQ 拉取任务，自动负载均衡
渲染完成后 Worker 更新数据库，并通过 SSE 通知前端
新增 Worker 只需启动新实例，自动加入消费组

3.3 生产者实现

from rocketmq.client import Producer, Message

producer = Producer("render-producer-group")
producer.set_name_server_address("localhost:9876")
producer.start()

def submit_render_task(task_id: str, params: dict):
    body = json.dumps({
        "task_id": task_id,
        "params": params,
        "submitted_at": time.time()
    })
    msg = Message("video-render")
    msg.set_keys(task_id)
    msg.set_tags("normal")
    msg.set_body(body)
    producer.send_sync(msg)

3.4 消费者实现

from rocketmq.client import PushConsumer, ConsumeStatus

class RenderConsumer:
    def __init__(self):
        self.consumer = PushConsumer("render-consumer-group")
        self.consumer.set_name_server_address("localhost:9876")
        self.consumer.subscribe("video-render", "*", self.on_message)

    def on_message(self, msg):
        try:
            data = json.loads(msg.body)
            task_id = data["task_id"]
            params = data["params"]

            # 幂等检查
            if self.is_task_processed(task_id):
                return ConsumeStatus.CONSUME_SUCCESS

            # 更新任务状态为处理中
            self.update_task_status(task_id, "processing")

            # 执行渲染
            result = self.render(params)

            # 更新任务状态为完成
            self.update_task_status(task_id, "completed", result)

            return ConsumeStatus.CONSUME_SUCCESS
        except Exception as e:
            logger.error(f"Render failed: {e}")
            return ConsumeStatus.RECONSUME_LATER

    def start(self):
        self.consumer.start()

四、关键设计细节

4.1 幂等处理

消息队列可能重复投递，渲染任务又是耗时操作，必须做幂等：

def is_task_processed(task_id: str) -> bool:
    """基于数据库状态做幂等判断"""
    task = db.get_task(task_id)
    return task.status in ("completed", "processing")

如果任务已经是 processing 状态，说明可能被其他 Worker 在处理，需要进一步判断心跳时间，避免任务永远卡住。

4.2 心跳与任务认领

每个 Worker 在处理任务时会定时更新心跳：

def update_task_status(task_id, status, result=None):
    db.execute("""
        UPDATE render_task
        SET status = %s,
            result = %s,
            worker_id = %s,
            heartbeat_at = NOW()
        WHERE task_id = %s
    """, (status, result, WORKER_ID, task_id))

如果某个 Worker 挂了，心跳超过阈值的任务会被标记为失败，重新进入队列重试。

4.3 失败重试与死信队列

RocketMQ 支持消费失败自动重试，默认 16 次，间隔递增。如果还是失败，消息进入死信队列：

# 消费失败时返回重试
return ConsumeStatus.RECONSUME_LATER

对于死信消息，我们单独处理：

分析失败原因
通知运营或用户
部分场景自动降级（比如降低分辨率重试）

4.4 并发控制

每个 Worker 同时能处理几个任务，取决于机器配置。我们通过线程池控制：

from concurrent.futures import ThreadPoolExecutor

# 根据 CPU/GPU 核心数设置
executor = ThreadPoolExecutor(max_workers=2)

def on_message(self, msg):
    future = executor.submit(self.handle_render, msg)
    # 注意：PushConsumer 是阻塞回调，这里需要等待结果
    result = future.result()
    return result

实际部署中，我们更推荐一个 Worker 进程只消费一个任务，通过启动多个 Worker 进程来提升并发。

五、Windows 开发环境兼容

5.1 问题

RocketMQ 在 Windows 上部署比较麻烦，开发环境有时候只有一台机器。为了不影响开发效率，我们设计了一个降级策略：

生产环境：RocketMQ Push Consumer
开发环境：HTTP 轮询模拟（单 Worker）

5.2 抽象层设计

class TaskConsumer(ABC):
    @abstractmethod
    def start(self):
        pass

class RocketMQConsumer(TaskConsumer):
    """生产环境使用"""
    pass

class HttpPollConsumer(TaskConsumer):
    """开发环境使用"""
    pass

# 根据配置切换
consumer = RocketMQConsumer() if env == "production" else HttpPollConsumer()

这样业务逻辑完全一致，只是消息消费方式不同。

六、监控与告警

6.1 关键指标

指标	说明
队列堆积量	判断是否需要扩容 Worker
任务平均处理时间	评估渲染性能和资源需求
任务成功率	健康度核心指标
Worker 在线数量	消费组健康状态
重试次数分布	发现系统性问题

6.2 告警规则

队列堆积超过 100 条，持续 5 分钟 → 扩容提醒
任务成功率低于 95% → 人工介入
Worker 数量异常减少 → 服务异常告警

七、演进效果

迁移到 RocketMQ 后，渲染系统的稳定性明显提升：

指标	HTTP 轮询	RocketMQ Push
平均等待时间	X 分钟	Y 分钟
任务成功率	X%	Y%
Worker 利用率	不均	均衡
扩容成本	需要改配置	启动实例即可
失败重试	自建逻辑	原生支持

（待补充真实数据）

八、踩过的坑

8.1 消息体过大

早期的渲染参数里包含完整的素材 URL 列表，消息体很大。RocketMQ 默认单条消息限制 4MB，我们遇到过消息发送失败。

解决：消息体只传 task_id 和关键参数，Worker 消费后自己从数据库/redis 拉取完整参数。

8.2 消费组订阅不一致

不同 Worker 用同一个消费组但订阅了不同 Tag，导致消息分发混乱。

解决：严格规范消费组命名和订阅规则，每个消费组只负责一个 Topic。

8.3 任务卡住没有超时释放

某个 Worker 处理到一半进程挂了，任务状态一直是 processing。

解决：增加心跳检测，心跳超时的任务自动重置为 pending，重新入队。

九、总结

视频渲染是 AI 视频平台里最典型的「重任务」场景，必须用异步队列 + 分布式 Worker 来解决。几个关键经验：

不要过早优化，但也不能过度将就。HTTP 轮询能验证产品，但流量起来后必须升级。
RocketMQ 的 Push Consumer 很适合这种场景，负载均衡和重试机制省去很多自建成本。
幂等和心跳是必须的，否则任务会丢或卡住。
监控要跟上，队列堆积和成功率是最核心的两个指标。

如果你也在做类似的异步任务处理系统，欢迎交流消息队列选型和 Worker 调度经验。

口播视频自动剪辑：Whisper 词级时间轴 + LLM 视觉规划

Mon, 23 Feb 2026 12:00:00 +0800

口播视频自动剪辑：Whisper 词级时间轴 + LLM 视觉规划

我开发的 GeekCast Engine 是一个面向口播类视频的 AI 自动剪辑平台。用户上传一段口播视频后，系统自动完成转写、粗剪、视觉规划和成片渲染。这篇文章会重点拆解两个核心模块：Whisper 词级时间轴处理 和 LLM 视觉元素规划。

一、口播剪辑的核心痛点

口播视频通常是一个人对着镜头讲话，形式单一，但剪辑过程却很繁琐：

气口和语气词太多：「嗯」「啊」「这个」「那个」需要逐个删掉
节奏单调：长时间只有说话人画面，观众容易疲劳
信息密度不均：有些段落需要配合 B-roll、标题卡、代码块来强化表达
长视频处理困难：10 分钟以上的口播，人工剪辑耗时往往在数小时

我们的目标不是完全替代剪辑师，而是把重复、机械、规则明确的工作自动化，让人专注于创意和审校。

二、整体技术架构

flowchart TD
    A["口播视频上传"] --> B["Whisper 词级转写"]
    B --> C["LLM 语义分析 + 视觉规划"]
    C --> D["自动粗剪（删气口/语气词/冗余片段）"]
    D --> E["Remotion 组件化渲染"]
    E --> F["FFmpeg 后处理输出成片"]

整个流程里，最关键的两个环节是：

时间轴精度：决定了粗剪是否精准
视觉规划质量：决定了成片是否好看

三、Whisper 词级时间轴

3.1 为什么选择 Whisper

OpenAI Whisper 是目前开源语音识别模型中最成熟的选择之一，优势很明显：

支持 99 种语言，中文识别效果不错
提供 word-level timestamps（词级时间戳），这是自动剪辑的基础
模型大小可选，从小到大有 tiny/base/small/medium/large

3.2 词级时间戳的获取

Whisper 本身不直接输出词级时间戳，需要借助 whisper-timestamped 或 faster-whisper 等工具。我们用 faster-whisper，因为它：

推理速度更快
支持 VAD（语音活动检测），减少静音误判
对长音频更稳定

from faster_whisper import WhisperModel

model = WhisperModel("small", device="cuda", compute_type="float16")

segments, info = model.transcribe(
    "input.mp3",
    word_timestamps=True,
    vad_filter=True,
    language="zh"
)

words = []
for segment in segments:
    for word in segment.words:
        words.append({
            "text": word.word,
            "start": word.start,
            "end": word.end,
            "probability": word.probability
        })

3.3 词级数据结构

转写完成后，每个词对应一个时间片段：

{
  "text": "大家好",
  "start": 0.32,
  "end": 0.98,
  "probability": 0.95
}

多个词可以聚合成句子、段落，形成完整的时间轴树：

Paragraph
  ├── Sentence 1
  │     ├── Word 1
  │     ├── Word 2
  │     └── Word 3
  └── Sentence 2
        ├── Word 4
        └── Word 5

3.4 气口和语气词删除

基于词级时间轴，我们可以做很多精细化编辑：

# 语气词列表
FILLER_WORDS = {"嗯", "啊", "这个", "那个", "就是", "然后", "对吧"}

def remove_fillers(words, filler_words=FILLER_WORDS):
    """删除单个语气词，保留相邻词的时间连续性"""
    result = []
    for w in words:
        if w["text"].strip() in filler_words:
            continue
        result.append(w)
    return result


def remove_long_pauses(words, threshold=0.8):
    """删除过长的停顿片段"""
    result = []
    for i, w in enumerate(words):
        if i > 0:
            gap = w["start"] - words[i-1]["end"]
            if gap > threshold:
                continue  # 也可以只压缩，不完全删除
        result.append(w)
    return result

3.5 时间轴漂移问题

实际使用中发现，Whisper 的词级时间戳在语速快、口音重、背景音乐干扰时会出现漂移。我们做了几个处理：

置信度过滤：识别概率低于 0.7 的词标记为待审校
句子级对齐：用 VAD 检测到的语音段和转写句子做二次对齐
人工修正入口：前端提供波形图 + 时间轴，允许用户微调

四、LLM 视觉规划

4.1 视觉元素类型

我们定义了口播视频中常用的几类视觉元素：

元素类型	作用	示例
标题卡	章节切换、强调重点	大标题 + 副标题
B-roll	缓解视觉疲劳，补充画面	相关图片/视频片段
引用卡	引用名人名言、数据	金句 + 出处
代码块	技术类口播展示代码	高亮代码片段
列表卡	展示多个要点	1/2/3 列表

4.2 LLM 规划任务

输入是一段按句子切分好的口播文本，输出是每个句子应该配什么视觉元素。Prompt 设计如下：

你是一名专业的口播视频剪辑师。请根据以下口播文案，为每个句子规划合适的视觉元素。

可用视觉元素：
- TitleCard: 标题卡，用于章节开头或强调核心观点
- BRoll: B-roll 画面，用于补充说明内容
- QuoteCard: 引用卡，用于展示名言、数据
- CodeBlock: 代码块，用于展示代码
- ListCard: 列表卡，用于展示多个要点
- TalkingHead: 保持说话人画面，不添加额外元素

口播文案：
{script}

请输出 JSON 数组，每个元素包含：
- sentence_index: 句子序号
- element_type: 视觉元素类型
- reason: 选择理由
- suggested_content: 建议展示的内容（如 B-roll 的画面描述、标题文字等）

4.3 输出结构化

LLM 返回的结果类似：

[
  {
    "sentence_index": 0,
    "element_type": "TitleCard",
    "reason": "开场需要点题",
    "suggested_content": "AI 自动剪辑实战"
  },
  {
    "sentence_index": 3,
    "element_type": "BRoll",
    "reason": "解释'时间轴'概念时需要补充画面",
    "suggested_content": "视频编辑软件中的时间轴界面"
  },
  {
    "sentence_index": 8,
    "element_type": "CodeBlock",
    "reason": "展示 Whisper 调用代码",
    "suggested_content": "faster_whisper 示例代码"
  }
]

4.4 与素材库联动

视觉规划中的 suggested_content 会作为查询条件，调用我们在第二篇文章中讲的 RAG 素材库，检索匹配的 B-roll、图片或文案片段。

def plan_and_retrieve(script: str):
    # 1. LLM 做视觉规划
    plan = llm.generate_visual_plan(script)

    # 2. 对每个 B-roll 规划项检索素材
    for item in plan:
        if item["element_type"] == "BRoll":
            item["materials"] = rag_retrieve(item["suggested_content"])

    return plan

五、长视频 Token 限制处理

口播视频动辄 10 分钟以上，对应的文案可能超过 3000 字，直接塞给 LLM 做视觉规划会触发 Token 限制，而且单次规划效果也不好。

我们的解决方案是：分段生成 + 本地组装。

5.1 分段策略

按段落切分：每段约 800-1200 字
保留上下文：每段开头会附带上一段的结尾摘要
独立规划：每段分别调用 LLM 做视觉规划
全局对齐：最后统一调整时间轴、样式和转场

def split_script(script: str, max_chars: int = 1000):
    """按段落切分文案，尽量保持段落完整性"""
    paragraphs = script.split('\n')
    chunks = []
    current = ""

    for p in paragraphs:
        if len(current) + len(p) > max_chars and current:
            chunks.append(current)
            current = p
        else:
            current += '\n' + p

    if current:
        chunks.append(current)

    return chunks

5.2 本地组装

分段规划完成后，需要在本地合并：

统一句子索引
统一视觉风格（字体、配色、动画）
处理段与段之间的转场
生成最终的 Remotion 渲染数据

六、Remotion 组件化渲染

6.1 为什么用 Remotion

Remotion 让我们可以用 React 组件来描述视频画面，非常契合「视觉元素 = 组件」的思路。

每个视觉元素对应一个 React 组件：

// 标题卡组件
export const TitleCard: React.FC<{ title: string; subtitle: string }> = ({ title, subtitle }) => {
  return (
    <AbsoluteFill style={{ backgroundColor: '#111', justifyContent: 'center', alignItems: 'center' }}>
      <h1 style={{ color: '#fff', fontSize: 80 }}>{title}</h1>
      <p style={{ color: '#aaa', fontSize: 36 }}>{subtitle}</p>
    </AbsoluteFill>
  );
};

6.2 渲染流程

flowchart TD
    A["视觉规划结果"] --> B["生成 Remotion composition（每个视觉元素对应一个组件实例）"]
    B --> C["Remotion 渲染为视频文件"]
    C --> D["FFmpeg 后处理：合成音频、加字幕、转码、多分辨率输出"]

6.3 多分辨率输出

平台需要同时支持横屏（16:9）和竖屏（9:16），我们在 Remotion 组件内部做响应式布局：

const { width, height } = useVideoConfig();
const isVertical = height > width;

七、踩过的坑

7.1 Whisper 模型选择纠结

tiny 速度最快但准确率太低
large 准确率最高但显存和速度压力大
最终我们选 small 做默认模型，large 做可选质量模式

7.2 LLM 规划风格不一致

同一个文案多次调用 LLM，返回的视觉规划可能风格差异很大。我们做了：

Prompt 里加入平台风格示例
视觉元素类型和样式模板固定
对返回结果做规则校验和兜底

7.3 代码块渲染需要特殊处理

代码块里的长行、特殊字符、换行等都会影响 Remotion 渲染。我们专门封装了一个 CodeBlock 组件，处理：

自动换行和字体缩放
语法高亮
行号显示

八、效果与反思

目前 GeekCast Engine 能在一分钟左右完成 5-10 分钟口播视频的自动粗剪和视觉规划，最终成片需要人工简单审校即可发布。

量化效果（待补充真实数据）：

10 分钟口播视频，人工剪辑平均 X 小时，自动剪辑约 X 分钟
气口和语气词删除覆盖率约 X%
LLM 视觉规划采纳率约 X%

反思：

自动剪辑还不能做到 100% 无人工，但已经能替代 60%-70% 的重复劳动
视觉规划比粗剪更难，未来需要结合用户反馈做迭代优化
长视频场景下，分段策略和上下文保留是关键

九、总结

口播视频自动剪辑是把 ASR、LLM、视频渲染三项技术串联起来的典型 AI 工程场景。几个关键经验：

词级时间轴是粗剪的基础，Whisper + faster-whisper 是性价比较高的方案
LLM 视觉规划要把输出结构固定，Prompt 设计决定可控性
长视频必须分段处理，本地组装时注意风格和转场一致性
Remotion 让视频渲染工程化，组件化思路适合多变的视觉需求

如果你也在做 AI 视频生成或自动剪辑相关的项目，欢迎交流 Whisper 调优和 LLM 规划的经验。

Netflix 的 LLM 后训练框架：从「跑通脚本」到「管好四根支柱」

Fri, 13 Feb 2026 10:00:00 +0800

Netflix 的 LLM 后训练框架：从「跑通脚本」到「管好四根支柱」

原文：Scaling LLM Post-Training at Netflix 目标读者：做过或想做 LLM 微调/强化学习的工程师，尤其是正在考虑「自建训练管线还是买现成框架」的人。阅读目标：搞清楚两件事——后训练在 Netflix 规模下到底难在哪；以及一个内部框架靠什么证明自己比「组装开源组件」更有价值。

〇、先拆一个直觉：后训练不就是「拿个开源模型 finetune 一下」吗

直觉版本的后训练长这样：准备点私有数据，从 Hugging Face 拉一个开源权重，写个 batch 循环迭代。实验规模下确实就几行代码。原文的核心论点是：从「跑通脚本」到「生产级后训练」之间隔着一整条工程鸿沟——数据管线、多机 GPU 集群的分布式状态、训练与推理交错的工作流，每一个都是深渊。

Netflix 的场景是推荐、个性化和搜索，需要让通用基座模型理解自家片库和用户交互历史。这种场景下，post-training 很快就不再是建模问题，而是分布式系统问题。AI Platform 团队建这个框架的目标很直白：把基础设施复杂度藏起来，让模型开发者专注模型本身，而不是分布式管道工。

一、三个环节，每个都有自己的坑

原文把后训练旅程拆成三步，每一步都有一批「纸面上没有」的坑。

数据：难的不是读取，是精确控制

Loss masking 是命门。 HF chat template 只负责把对话序列化成文本，不告诉你哪些 token 该进 loss。必须显式做 loss mask，只让 assistant 的 token 参与优化——否则模型会去学习 prompt 和非目标文本，质量直接掉。
变长序列是隐形浪费。 batch 内 padding 浪费算力，FSDP 各 worker 形状不齐会带来 GPU 同步开销。更省的做法是 sequence packing：把多个样本塞进定长序列，再用 document mask 阻止跨样本注意力。

模型：加载不了只是开始

模型放不进单卡时，需要 FSDP/TP 分片，并且要把权重分片直接加载到 device mesh 上，避免在任何单设备上物化完整模型。
加载完还要让它「可训练」：全量微调还是 LoRA，activation checkpointing、编译、精度设置——RL 场景下 rollout 和 policy 的精度必须对齐，这是容易翻车的细节。
大词表（＞128k）的内存陷阱：logits 形状是 batch × seq_len × vocab，峰值内存会炸。常见缓解：投影前先丢掉被忽略的 token，沿序列维度分块算 logits 和 loss。

训练：生产训练不是一个 for 循环

要支持从 SFT 的单次前反向传播，到 on-policy RL 那种「rollout 生成、reward/reference 推理、policy 更新交错进行」的工作流。Netflix 用 Ray 的 actor 模型做编排，把建模逻辑和硬件解耦。另外两样是标配：实验追踪（loss 这类质量指标 + MFU 这类效率指标）和标准化 checkpoint 带来的容错恢复。

二、框架总览：四根支柱

整个技术栈从底到顶是：Mako（Netflix 内部 ML 计算平台，在 AWS 上供给 GPU）→ 开源三件套（PyTorch、Ray、vLLM，基本开箱即用）→ Post-Training Framework（以库的形式提供 SFT、DPO、RL、知识蒸馏等标准化 recipe，用户用配置文件选配方、插任务组件）。

flowchart TD
    subgraph APP["使用者: 模型开发者"]
        CFG["配置文件<br/>选 recipe 插组件"]
    end
    subgraph FW["Post-Training Framework"]
        R1["SFT"] --- R2["DPO"] --- R3["RL"] --- R4["蒸馏"]
    end
    subgraph OSS["开源基础组件"]
        PT["PyTorch"] --- RAY["Ray"] --- VLLM["vLLM"]
    end
    subgraph INFRA["基础设施"]
        MAKO["Mako 内部 ML 计算平台<br/>在 AWS 上供给 GPU"]
    end
    CFG --> FW
    FW --> OSS
    OSS --> MAKO
    style FW fill:#fff3cd

框架的能力沿四个维度组织，对应 ML 系统的三支柱加一个新增支柱：

Data：SFT、奖励建模、RL 各自的数据集抽象；超本地存储的数据集从云和磁盘做高吞吐流式读取；异步 on-the-fly packing，把 CPU 密集的打包和 GPU 计算重叠，减少空闲。
Model：支持现代架构（Qwen3、Gemma3）和 MoE 变体（Qwen3 MoE、GPT-OSS）；LoRA 直接集成进模型定义；高层 sharding API，开发者不用写底层分布式代码就能跨 device mesh 分片。
Compute：统一作业提交接口，单机到几百卡一个入口；自定义架构和 LoRA 下依然准确的 MFU 监控；完整 checkpoint（参数、优化器、dataloader、data mixer 状态），中断后精确恢复。
Workflow：这是 RL 逼出来的第四支柱——支持超越「单个训练循环」的多阶段执行模式。

三、教训一：从 SFT 到 RL，架构要换心

框架最初围绕 SFT 设计：数据流相对静态、单一训练循环、SPMD 执行模型（每个 GPU worker 跑同一个 step 函数，处理不同数据分片，靠 PyTorch 分布式原语同步）。这个假设在 2025 年失效了——DeepSeek-R1 和 GRPO 这类高效 on-policy RL 普及之后，SFT 从终点变成了入场券。

两者差异的本质在学习信号：SFT 的信号稠密而即时（每个 token 位置都有全词表 logits 和可微 loss），长得就像 pre-training；on-policy RL 的信号稀疏而延迟（episode 结束才有一个标量 reward），且训练数据依赖当前 policy 生成。单个子阶段（policy 更新、rollout、reference 推理、reward 打分）各自都能 SPMD 化，但端到端算法需要显式协调：prompt、采样轨迹、reward、advantage 这些产物在阶段间不停交接，生命周期要有人管。

架构上的变化：原来的 driver 是「瘦」的，只负责拉起 N 个相同的 Ray actor，扩容就是加 worker；RL 要求把系统拆成不同角色（Policy、Rollout Worker、Reward Model、Reference Model），driver 进化成主动控制器，编码整个控制面——何时生成 rollout、怎么组 batch 和打分、何时触发优化、跨阶段怎么调度集群资源。

flowchart LR
    subgraph SFT["SFT 架构: 瘦 driver + SPMD"]
        D1["瘦 driver<br/>只负责拉起 worker"] --> A1["actor 1<br/>完整训练循环"]
        D1 --> A2["actor 2<br/>完整训练循环"]
        D1 --> A3["actor N<br/>完整训练循环"]
    end
    subgraph RL["RL 架构: 主动控制器 + 多角色"]
        C["主动控制器<br/>编码控制面<br/>何时 rollout 何时优化"] --> P["Policy 更新"]
        C --> R["Rollout Worker"]
        C --> RM["Reward Model"]
        C --> REF["Reference Model"]
        R -->|"轨迹"| RM
        RM -->|"reward 和 advantage"| P
    end
    SFT ==>|"2025 年 DeepSeek-R1 与 GRPO 普及<br/>SFT 从终点变成入场券"| RL
    style RL fill:#fff3cd

落地方式是集成开源库 Verl 的核心设施来管理 Ray actor 生命周期和 GPU 资源分配，自己只做「建模表面积」——Data/Model/Compute 抽象和内部优化。最终是混合设计：用户在 SFT 和 RL 之间切换不用换心智模型。这个取舍值得画重点：编排不自己造轮子，抽象层才是护城河。

四、教训二：全面押注 Hugging Face，但模型实现自己来

HF Hub 事实上已是开源权重、tokenizer、配置的默认分发渠道，框架选择贴着生态走而不是另立内部标准：checkpoint 一律按 HF 格式存取，避免「围墙花园」摩擦。

Tokenizer 的故事最有教训价值。早期直接绑定底层分词库（SentencePiece、tiktoken）追求控制力，结果造成静默的训练-推理 skew：推理栈（vLLM）默认用 HF AutoTokenizer，归一化、特殊 token、chat template 的细微差异会产生不同的 token 边界——这类 mismatch 之后会以「莫名其妙的质量回退」形式冒出来，极难排查。修法：AutoTokenizer 成为唯一事实源，上面加一层薄薄的兼容层（BaseHFModelTokenizer）处理后训练特有需求（padding token、生成标记注入、语义 ID），同时保证字节级分词路径和生产一致。

模型实现则相反：不直接用 transformers 的模型类训练，而是维护自己优化的统一模型定义，能读写 HF checkpoint。这一层换来 FlexAttention、分块交叉熵、统一 MFU 核算、统一 LoRA 扩展，跨架构不用重实现；统一的模块命名还让程序化定位和替换组件（Attention、MLP、输出头）成为可能。

代价很直接：支持一个新模型家族，要写 HF 参考实现到内部定义的桥。Netflix 的解法是 AI coding agent + logit verifier：agent 自动生成大部分转换代码，验收标准是给定随机输入、内部模型的 logits 必须在容差内匹配 HF——因为验收可以机械检查，agent 能自主迭代到正确为止，大幅缩短新架构的支持周期。当前只支持显式适配过的架构（和 vLLM、SGLang、torchtitan 同款取舍），计划中的 HF fallback 后端会允许直接跑原生 transformers 模型做快速探索，代价是部分优化不生效。

五、教训三：差异化价值投在深水区

自建框架值不值，取决于有没有超出「组装开源件」的价值。Netflix 的答案：开源换速度，重投入换两个方向——贴合自家负载特征的性能和Netflix 特有的业务需求。两个具体例子：

On-the-fly sequence packing。 FSDP 训练里长尾序列制造 straggler，快的 worker 在同步点干等。标准的离线 bin-packing 有效，但在他们的数据规模下预处理延迟可观、数据难保鲜。解法是从存储流式读样本、在内存里动态打包，打包异步跑、和 GPU 计算重叠。结果：最倾斜的数据集上有效 token 吞吐提升最高 4.7 倍（A100 和 H200 上均验证）。
词表大小对齐 64。 业务常加自定义 token 和语义 ID，某些词表大小会让 LM head 从高度优化的 cuBLAS kernel 掉到慢得多的 CUTLASS 路径，该层耗时翻三倍。框架自动把词表 pad 到 64 的倍数，开发者不需要知道这层硬件玄学。

第二个方向是支持「非标准」transformer 用例：比如基于用户交互事件序列（而非自然语言）训练的模型，需要定制的 RL 循环、对接高度定制的推理引擎、优化业务定义的指标——这些要求定制环境、奖励计算和编排模式，但性能、追踪、容错的底层保障必须一样。

工程实践联想

「跑通」和「生产化」之间的鸿沟，大部分都是状态管理。 Loss mask、checkpoint 完整性、训练-推理一致性——每一项单看都是小细节，合起来决定系统可不可靠。这和我们写业务系统一样：demo 一周，上线半年，差的全在边界条件。
训练-推理 skew 是数据系统里「双写不一致」的 LLM 版本。 两份各自「正确」的实现（训练 tokenizer vs 推理 tokenizer）因为微小差异产生静默错误。通用解法也通用：指定唯一事实源，其他都向它对齐，用兼容性测试兜底——logit verifier 本质就是契约测试。
AI coding agent 最好用的地方是「验收可机械检查」的场景。 HF 到内部模型定义的桥接，验收是 logits 数值匹配，agent 可以放心自主迭代。反过来说，给 agent 派活之前先问：这活的验收标准能不能写成断言？写不出断言的活，agent 做完了你还得人工审。
编排层买、抽象层造，这个取舍可以抄。 Verl 管 actor 生命周期，自己只做 Data/Model/Compute/Workflow 抽象。通用版：消息队列买、存储买，贴合业务的领域模型自己造——护城河在建模，不在管道。
性能优化要贴着自家负载的真实分布做。 4.7 倍不是来自通用调优，是来自「我们的序列长度方差极端」这个具体事实；词表对齐 64 同理。先测量自己的负载长什么样，再决定优化什么——别人的 benchmark 不构成你的优化清单。

本篇小结

定位：后训练在 Netflix 规模下是工程问题。框架目标是让模型开发者不碰分布式管道。
三个坑位：数据（loss mask、packing）、模型（分片加载、大词表 logits 内存）、训练（不只是 for 循环，要编排和容错）。
四根支柱：Data、Model、Compute、Workflow——第四根是 RL 逼出来的。
架构演进：SFT 的「瘦 driver + SPMD」演进为 RL 的「主动控制器 + 多角色」，编排集成 Verl，自己保住抽象层。
生态策略：checkpoint 和 tokenizer 全面贴 HF（AutoTokenizer 是唯一事实源，治训练-推理 skew）；模型实现自己维护换优化空间，桥接新架构用 AI agent + logit verifier 自动化。
差异化投入：on-the-fly packing 最高 4.7 倍吞吐；词表对齐 64 避开 kernel 回退；支持交互序列这类非自然语言 transformer。
一句话：训练框架的价值不在堆了多少组件，在于把分布式系统的坑变成了配置项。

参考资料

Scaling LLM Post-Training at Netflix（原文，Baolin Li、Lingyi Liu、Binh Tang、Shaojing Li）
Verl（字节跳动开源的 RL 后训练库，Netflix 用其核心设施做 actor 生命周期与 GPU 资源管理）
DeepSeek-R1（GRPO 等高效 on-policy RL 方法的代表作，原文称其为「SFT 变成入场券」的转折点）
Torchtune、Torchtitan（原文致谢的两个 PyTorch 原生训练参考实现）
Thinking Machines Tinker（原文对比的外部微调服务）