Agent 架构学习手册

从组件到编排

Agent 的基础能力包括模型调用、工具调用、MCP、RAG、记忆、结构化输出和提示词管理。LangChain 把这些能力封装成可组合组件，通过链式流程连接输入、检索、模型和输出。掌握组件职责，比记住某一种语言的调用写法更重要。

何时需要图编排

链适合表达以顺序处理为主的业务流程；复杂 Agent 还需要循环、条件分支、并行、共享状态以及中断恢复。LangGraph 在组件之上增加状态、节点、边和检查点，以图来描述执行关系。DeepAgents 则在这一层进一步封装任务规划、多 Agent、Skill 等通用能力。

产品落地的基础设施

Agent 不只是模型脚本，还依赖后端服务和数据系统：关系数据库维护业务实体，Milvus 支持向量检索，ElasticSearch 支持全文检索，Neo4j 保存图关系，Redis 管理缓存或会话数据，对象存储承载文件，RabbitMQ 承载异步任务。Nest 组织服务逻辑，Docker Compose 管理本地依赖环境。

观测与综合应用

LangSmith、LangFuse 等观测方案记录用户输入、模型及工具调用、报错、耗时和 token 消耗，帮助定位参数错误、循环失控与性能问题，也可支持 RAG 评估。企业知识库是串联文档处理、检索、生成和后端工程的综合场景；Transformer、注意力和自回归生成则帮助理解模型能力的来源与边界。

为什么只有大模型还不够

直接调用大模型擅长理解和生成文本，但不会自动获得业务系统访问权，也不会天然记住跨次调用的信息。训练数据之外的新信息、企业私密知识和具体操作能力，都需要应用层补充。

三类核心扩展

Tool 把读写文件、运行命令、访问浏览器等动作变成模型可请求的工具；Memory 管理历史消息与需要保留的信息，使多轮对话能够延续；RAG 在回答前查询外部知识，将相关材料补充到上下文。模型负责理解与规划，应用负责提供上下文、实际执行动作和管理状态。

从能力到产品

代码助手通过文件和命令工具修改项目，浏览器助手通过自动化工具操作网页，业务问答助手通过知识库获得领域资料。它们的共同点是将模型推理与外部能力相连，而不是仅把聊天窗口换一个界面。

框架与后端分工

LangChain 提供模型、工具、记忆和检索等组件；复杂分支、循环和多 Agent 协作可以进一步使用 LangGraph。后端框架负责把这些组件组织为接口和业务服务，数据库、缓存等基础设施负责状态与知识的存储。实现语言可以变化，能力边界和架构关系不变。

下一 Token 预测

生成模型根据已给出的上下文预测下一 Token 的概率，再逐步追加输出。Agent 的工具、检索、历史消息与用户记忆，本质上是在循环中提供新的上下文，让模型基于更新后的信息继续决策，而不是在每次对话时改写模型权重。

三类架构

Encoder-only 利用双向注意力形成输入表示，常用于分类、嵌入和重排；Decoder-only 使用因果注意力，适合自回归生成，也是主流对话模型常用结构；Encoder–Decoder 将输入编码与输出生成分开，适用于序列转换。这里是常见分工，并非所有产品的绝对分类。

文本如何进入模型

Tokenizer 把文本拆成 Token，再映射为词表 ID，查嵌入表得到向量，并引入位置信息。向量序列经过注意力与前馈网络产生隐藏状态；输出投影得到全词表分数，Softmax 转为概率分布，再选择下一个 Token。

训练与推理

训练利用文本中的实际后续 Token 作为监督，计算预测误差并反向传播更新参数。通常的推理调用只执行前向计算、保持参数不变；会话记忆是外部保存并重新提供的内容。自回归输出直到结束标记或其他停止条件。

Q、K、V 的职责

每个位置的表示经不同变换得到查询 Q、键 K、值 V。Q 与允许关注的位置的 K 计算匹配分数，归一化后形成注意力权重，用这些权重融合 V。因果模型必须屏蔽未来位置；“聚合上下文”不等于生成时可以读取未来 Token。

从注意力到候选词

注意力更新位置间的信息，前馈网络继续非线性加工表示。经过多层处理后，最终隐藏状态映射为词表 logits，再转为概率。注意力与前馈网络共同学习语言特征，不应把语法或知识简单归给某个单独模块。

KV Cache 降低重复计算

初次处理 Prompt 时计算并缓存各层历史 K、V。逐步生成时复用历史缓存，为新位置计算所需表示与新的 Q、K、V，再把新 K、V 追加到缓存。它避免历史内容反复计算，并不意味着新 Token 只需要计算 Q。

训练如何获得模型

训练准备数据，用真实后续 Token 监督预测，计算损失并反向传播更新参数，再通过评估观察效果。推理使用训练好的参数进行前向计算和自回归生成。大量矩阵运算适合利用 GPU 并行能力。

采样控制生成风格

贪心选最高分候选；Top-K 限定最高的 K 个候选；Top-P 选择累计概率达到阈值的候选集合。Temperature 调整概率分布的尖锐程度，低温更集中，高温更分散。这些控制选择方式，不等于保证事实正确。

模板解决什么问题

复杂提示词会包含角色、背景、任务、格式、用户输入和检索材料。把全部内容长期维护为一个拼接字符串，难以复用和调整。模板用占位符表达变化的数据，用组合表达可复用片段，让不同业务共享角色设定或输出格式，而分别维护任务内容。

字符串模板与聊天模板

普通模板产生一段文本，聊天模板则产生带消息角色的序列。后者可以分别组织系统、用户和助手内容，更贴近多轮对话的输入结构。插入历史记录时，应把它作为一段有角色的消息序列，而不只是把所有对话压平成一个字符串字段。

组合与预填充

角色、背景、格式等片段可以分别维护，使用时再拼成最终提示词。稳定信息还可以提前填入，生成只剩必要变量的新模板，降低重复传参和跨任务不一致的风险。这种方式使提示词成为可复用组件，而不是散落在业务代码中的文本。

Few-shot 与示例选择

少量示例可以说明期望的输入输出关系，但示例越多，消耗的上下文越大。可按剩余长度预算挑选示例，也可将示例向量化，按当前问题选择语义相近的例子。对话形式的示例则保留用户与助手消息的关系。模板负责组织内容，选择器负责决定本次携带哪些示例。

从自然语言到数据契约

应用经常需要对象或数组，而不是任意文本。仅在提示词中要求 JSON，仍可能收到 Markdown 包裹或额外说明。输出解析器把格式描述与结果解析结合起来：在输入中表达期望结构，在输出中提取并校验数据。简单 JSON、复杂结构和 XML 等格式，可能需要不同解析策略。

模型侧约束与解析侧处理

工具调用可用参数结构来承载所需数据，即使并不真正执行该工具，也能利用其结构化参数。部分模型还提供原生 JSON Schema 输出约束。与仅靠提示词相比，这些机制把结构要求带到模型或服务层；框架可对支持情况作封装，但具体选择和严格程度取决于模型及配置，不能把格式支持等同于事实正确。

流式输出的额外状态

流式传输得到的是文本或工具参数片段，某一时刻可能还不是完整 JSON。累积解析器可以在内容逐步到达时形成供界面展示的局部对象。严格结构校验则往往要等到完整对象到达，因此“使用流接口”与“每个字段都能实时使用”不是一回事。

如何选择

若目标是最终获得完整结构化数据，优先考虑模型支持的结构化输出能力；若要处理非 JSON 格式或渐进显示，则需结合相应解析器。中间片段只代表生成进度，不能因为它被解析成了部分对象，就直接当作完整工具参数执行有副作用的操作。

工具契约

工具由实际执行逻辑及名称、用途描述、参数结构组成。描述让模型判断什么时候应使用它，参数结构约束模型应提供哪些信息。例如读文件工具需要文件路径，而文件读取本身由应用完成。模型返回工具调用请求，并不等于模型亲自执行了文件操作。

一次调用的完整过程

应用先把用户问题、角色要求和可用工具信息提供给模型。模型判断是否需要工具，并返回工具名称与参数；应用找到对应工具并执行，再将结果加入对话上下文，让模型基于真实结果回答。若仍需更多资料，可以继续这一闭环。

消息角色与结果关联

系统消息定义角色和行为规范，用户消息表达目标，模型消息承载回复或调用请求，工具消息承载执行结果。工具结果应与原调用的标识关联，避免模型混淆多个调用的结果。保存这些消息，也是后续多轮工具协作的基础。

配置与可靠性

模型访问凭据属于运行配置，不应写死在业务逻辑或提交到代码仓库。工具定义、模型推理和执行结果应保持清晰分离：应用负责真实执行，模型负责解读返回内容，而不是在未读取文件时猜测文件内容。

能力拆分

一个能创建项目的代码助手，至少需要读取目录、读取文件、写入文件以及执行命令等工具。文件工具负责观察和修改项目，命令工具负责安装依赖、启动服务等动作。组合这些小工具，比把整个开发过程写成一个不可分解的大工具更容易让模型按任务选择。

Agent Loop

用户只提出目标，模型决定下一步需要哪个工具以及参数。应用执行后把结果送回模型，模型再决定继续操作还是给出最终答复。创建目录、生成文件、安装依赖和启动项目，因而可以在多轮交互中完成，而不是一次模型响应就完成所有事情。

执行上下文与退出条件

命令执行依赖明确的工作目录，工具结果中保留目录信息有助于后续调用维持一致的路径上下文。循环还需要最大轮次限制，避免模型持续请求工具而无法结束。没有新的工具调用请求时，才把模型回复作为最终结果。

可见性与体验

非流式模式可能长时间没有可见输出，但模型仍在生成文件内容；流式展示可以改善等待体验，不改变实际的工具执行闭环。这个简化方案展示的是代码助手的基本原理，并不等同于完整 IDE 产品。

从本地函数到跨进程协议

普通工具函数通常与 Agent 运行在同一语言和进程环境中。若需要复用其他语言实现的能力，可以启动独立进程并通信，或访问远程服务。但如果每个服务都自定义协议，接入方仍需逐一适配。MCP 的价值是统一这层交互，使工具可以在不同客户端之间复用。

客户端、服务端与传输

Agent 应用通过 MCP Client 连接 MCP Server，发现并调用其提供的能力。本地进程可使用标准输入输出流通信，远程服务可通过 HTTP 通信。协议边界隔离了工具的实现语言；对模型而言，接入后的工具仍然需要名称、描述和参数结构。

Tool 与 Resource 的区别

Tool 表达可调用的操作，调用后返回执行结果；Resource 表达可读取和引用的信息。读取 Resource 后，可以把内容作为系统或用户消息中的背景资料，不必把它当作一次工具操作。两者分别侧重执行能力与上下文供给。

与 Agent 闭环的关系

MCP 工具经适配后参与同样的模型决策、应用执行、结果回传循环。MCP 解决的是接入和通信问题，并不替代 Agent Loop。若工具只需在同进程内部使用，普通工具函数更直接，也能避免额外的进程通信成本；本地服务进程的生命周期则需要由应用管理。

复用的基本思路

MCP 使应用可以复用已有工具，而不必重新理解和封装每个底层服务。位置服务负责地点查询与路线规划，文件服务负责保存资料，浏览器服务负责打开网页、点击和截图。模型读取工具描述，按任务选择工具并组织参数。

组合场景

例如查询某车站附近酒店，先通过位置服务获取地点和路线，再由文件工具保存整理结果，必要时由浏览器工具打开相关页面。多个服务不需要预先合并为一个专用接口，Agent 可以在工具调用闭环中串联它们。

接入与适配

服务可能通过 HTTP 远程连接，也可能由客户端启动本地进程并通过标准输入输出通信。本地 MCP 进程仍可在内部调用远程地图接口，因此本地传输并不代表业务数据必然来自本机。不同工具返回的内容也可能是字符串或带文本字段的对象，适配层应统一为模型能理解的结果。

职责边界

客户端负责凭据配置、工具接入和可访问文件目录等运行条件，MCP 服务负责具体能力，模型负责基于描述选择调用。应用仍需执行模型发出的调用请求，并将结果放回上下文；标准协议不会让工具自动脱离应用控制而执行。

智能录入的数据流

传统录入要求用户先把信息整理到表单或表格；智能录入允许提交自然语言，由模型提取符合约定结构的记录。流程是非结构化文本 → 结构化输出 → 应用保存到数据库。模型承担字段识别与组织，数据库操作仍由应用层完成。

结构约束的来源

结构化输出可依赖工具参数、原生 JSON Schema 或提示词加解析器。抽象封装可以屏蔽部分接口差异，但应理解这些机制分别在哪里约束数据。结构契约描述的是字段、类型及组织形式，不代表模型识别出的内容天然没有错误。

流式 Agent 的两个累积过程

非流式调用一次得到完整模型消息；流式调用逐步得到消息片段。应用一方面要把片段合成为完整消息，供历史管理和下一轮模型调用使用；另一方面要解析工具参数的局部内容，展示当前正在生成的文件或文本。这两个过程目标不同，不宜混淆。

展示与执行分离

界面可以展示逐步补全的参数，并记录已经展示到的位置以避免重复。但写文件等真实操作，应在流结束后从完整消息取出工具调用和完整参数，再一次执行。工具结果进入历史后才继续 Agent Loop。这样既能降低等待感，又不会把不完整的生成结果当成最终指令。

检索、增强、生成

模型训练完成后，不会自动知道最新事件或企业内部文档。RAG 在生成答案之前，先根据问题检索相关材料，再把材料加入提示词，最后让模型基于这些背景知识回答。它减少对模型参数中既有知识的依赖，但检索到材料并不意味着回答必然正确。

向量为什么能表达语义

嵌入模型把文本等内容转换为数值向量。语义接近的内容在嵌入空间中通常更接近，因此不必要求问题与文档使用完全相同的关键词。原文用食用性和硬度两个维度解释水果、苹果、香蕉与石头的关系；这只是教学类比，真实嵌入通常有数百或更多维度。

相似度与嵌入模型

余弦相似度比较两个向量方向的接近程度，夹角越小，相似度越高。嵌入模型负责生成这种表示，大语言模型负责理解上下文并生成语言，两者职责不同。文档向量需要关联原文及来源元信息，检索到向量后才能取回可供阅读的内容。

离线入库与在线问答

入库时对文档片段生成嵌入并存入向量数据库；问答时把用户问题也转换为向量，检索最相近的若干片段，把原问题和片段一起交给模型。向量检索是常见实现方式，RAG 的本质则是用外部检索结果增强生成，并不限定只能采用一种检索方法。

Loader 统一不同来源

知识可能来自 Word、PDF、网页、电子书或其他内容源。Loader 将这些不同格式中的内容提取成统一的文档对象，为后续处理建立共同输入。它关注的是加载和提取，不负责直接生成最终问答。

为什么需要分块

整本书或长文档不适合每次都完整进入模型上下文。Splitter 把大文档拆成较小的文档块，使检索能够定位到与问题有关的局部内容，减少携带无关内容的开销。分块后的对象仍然是文档，只是粒度不同。

分隔符、块大小与重叠

分隔符决定优先在哪里切开文本，例如段落、句号或其他标点；块大小决定如何把分割后的内容组织到一个块中，而不是简单地把每行都变成一条记录。相邻块可保留适量重复内容，以降低跨边界信息断裂的影响。实际分块要兼顾长度和语义连续性。

完整数据链路

不同来源 → Loader 提取 → Splitter 分块 → 嵌入模型向量化 → 向量数据库。查询时检索相关块，再补充到模型上下文。Loader 和 Splitter 因而属于知识库的入库阶段，检索与生成属于问答阶段。

先理解三个参数

分隔符决定候选边界，块大小决定目标长度，重叠区间用于保留相邻块之间的部分上下文。三者不能混为一谈：按句号分隔不等于一句一块，设定目标长度也不意味着每块都必须精确等长。重叠会增加存储与上下文开销，原文给出的常见参考是块大小的 10%–20%，实际是否产生重叠还取决于切分结果。

固定分隔与递归分隔

按单一字符切分的策略较简单，但遇到没有该分隔符的长段落时，可能产生过大的块。递归切分则按分隔符优先级逐层尝试：先保留较大的结构，超长时再退到更细的标点或字符边界。它通常比只指定一个分隔符更灵活，因此适合作为通用起点。

字符长度不等于 Token 长度

不同语言、词语和模型分词器会导致不同的 token 数量，无法用固定字符比例精确换算。严格按 token 截断可以控制长度，却可能在不自然的位置破坏语义。另一种选择是保留递归分隔策略，同时用 token 数量衡量块长度，兼顾模型预算与结构边界。

按文档语法保留结构

Markdown 可以优先沿标题层级切分，LaTeX 可以沿自身语法结构切分，代码文档也可以根据语言结构选择分隔规则。这些都是递归切分思想的应用。选择策略时应先看材料结构和长度约束，而不是为了覆盖所有切分器而增加复杂度。

会话数据模型

用户、会话、消息构成两个一对多关系：一个用户拥有多个会话，一个会话包含多条消息。主键标识记录，外键建立关联。加载用户会话列表与读取某会话历史，是这两层关系的常见查询。

把向量与业务记录放在一起

消息可以同时保存文本和嵌入向量。PostgreSQL 配合 pgvector，在关系查询之外增加向量相似度检索，使按用户、会话等条件过滤与语义匹配能够在同一数据系统中组合。

与双库方案比较

关系库与独立向量库并用时，通常需要用一致 ID 关联记录，并处理双写与检索后的回查。向量放进 PostgreSQL 可以简化这一链路，减少两套数据的同步工作；是否采用独立向量库仍取决于具体需求，而不是单凭产品名称决定。

映射与查询边界

ORM 可以表达实体、字段及一对多关系，降低常规关联查询的样板工作。向量检索涉及扩展能力时，仍可能需要专门查询表达。消息持久化、关系约束和语义索引是互补职责，不应把保存全部历史等同于自动形成有效长期记忆。

两类查询的分工

关系数据库适合按业务标识、字段条件及表关系查询；向量数据库适合按嵌入相似度寻找语义相关内容。例如日记列表可以按日期查询，而“心情较好的户外活动”可以作为自然语言检索问题。两者通常是互补关系，不必把全部业务数据访问都交给向量检索。

数据层次与索引

Milvus 按 database、collection、entity 组织数据。Collection 用 schema 约定字段，entity 是符合该结构的数据记录。向量字段用于相似度检索，正文、日期、标签和业务标识等字段作为内容与元数据。向量字段的维度必须与嵌入模型输出一致，还需建立合适的向量索引以支持快速查询。

写入、检索、更新与删除

新增内容时生成嵌入并保存；查询时把问题向量化，再返回相似的记录；内容变更时需同步更新其向量表示。按标识或条件删除记录不需要重新调用嵌入模型。检索得到相关记录后，再由大模型组织为自然语言答案，这才组成 RAG。

双存储设计

同一业务内容可以在关系库中保留结构化实体，在 Milvus 中保存可检索表示，通过共同标识关联。原文采用双写思路，同时维护两边的增删改，重点是保持内容及标识同步；只更新其中一侧会使业务记录和语义检索结果脱节。

目标与两阶段架构

当问题是“某人物会哪些武功”时，答案可能分布在多处段落，并不对应一个固定关键词。电子书助手采用 RAG：先把书籍处理成可检索的片段，再在提问时查出相关证据，由模型理解和归纳，而不是要求模型预先记住整本书。

入库的数据设计

加载 EPUB 后先保留章节结构，再将较长章节递归切分为更小的片段。每条记录除正文和向量外，还保存书籍标识、书名、章节号及章内分块序号。向量服务于语义匹配，元信息服务于定位来源与关联业务资料。

检索与生成

查询问题经嵌入模型向量化后，在 Milvus 中匹配相近片段。将这些片段与用户问题一同交给模型，要求根据材料回答并引用原文。这样输出不仅有归纳结论，也能让读者回到支撑结论的文档片段。

与业务系统关联

书籍标识可以关联关系库中的书籍实体，从而补充向量库以外的业务信息。替换文档来源后，同一架构也可用于企业内部文档；可复用的是加载、分块、向量化、检索与生成的关系，而不只是电子书这个界面。

倒排索引

全文检索先对文本分词，再建立“词条 → 文档 ID 列表”的映射。查询时把问题拆成词条，找到对应文档并合并候选，不必依靠逐条扫描长文本。Elasticsearch 中，索引组织一类文档，文档包含不同字段；需要分词的文本字段与不分词的精确值字段承担不同用途。

中文分词

分词决定索引中有哪些词条，也决定查询能否正确命中。把中文逐字拆开通常不符合专业词汇的语义边界。原文使用 IK：索引阶段采用更细粒度的切分，查询阶段采用较紧凑的切分，以兼顾覆盖和查询表达。入库与查询的分析策略需要配合。

BM25 负责相关性排序

倒排索引解决找候选，BM25 决定候选的顺序。它考虑词频饱和，避免单纯重复关键词无限提高得分；考虑文档长度，使长短文本更公平；提高稀有词的区分权重。

与业务数据库、向量库协作

原始业务数据可以保留在关系数据库，需要检索的内容同步到搜索索引。关键词检索擅长专业术语、编号和精确实体，向量检索擅长语义相近但表达不同的内容，二者是互补能力，而不是互相替代。

召回与筛选分工

向量检索按语义匹配，全文检索按关键词命中。两路同时召回能扩大覆盖，但也带来重复与不相关片段。上下文窗口有限，把所有候选直接送给大模型会增加噪声，因此应先合并去重，再精筛。

重排模型的作用

嵌入模型把文本转成便于快速检索的向量；重排模型联合考虑问题与候选文档，输出相关性分数。它用于候选已经缩小后的排序与去噪，选择最能支撑回答的片段，而不是承担整个语料库的第一轮查找。

多问题扩展

同一原始问题可以改写成几个不同角度的检索表达，各自进入关键词和向量检索。所有结果统一去重，最终仍围绕原始问题重排，避免扩展后的表述偏离用户需求。

整体链路

同一批文档进入全文索引与向量索引；在线阶段依次完成问题改写、多路召回、结果合并、重复消除、相关性重排和 Top-N 上下文生成。召回侧追求找得全，重排侧追求找得准，生成侧利用经过筛选的证据回答。

为什么增加关系检索

向量和关键词检索主要返回相关文本片段。面对“某产品属于哪一类、该类产品含哪些配料”这样的关系问题，需要把实体之间的边显式存储，才能顺着关系跨越多个信息点。Neo4j 以节点与关系组织这些知识。

从文档到图谱

构建阶段从非结构化文档中提取实体及关系，形成品类、配料、产地、适用人群等连接。检索阶段将问题转化为图查询，沿相关关系取出证据，再交由生成模型组织答案。图查询语言负责表达节点和关系模式。

三种检索各司其职

向量检索适合自然语言表达、同义问题与模糊语义；BM25 适合术语、编号、文件名与字段筛选；图谱检索适合从属、层级、上下游以及多跳关联。图谱不能取代所有全文与语义检索。

Graph RAG 的组合方式

Graph RAG 将图谱关联证据加入检索增强生成。可以结合语义匹配定位相关实体或文档，再沿图拓展关系，最后把结构化关联和文本证据共同用于回答，以增强关系解释能力。

模型无状态，应用有历史

一次模型调用并不会自动继承上一次调用的全部信息。连续对话依赖应用把相关历史消息再次提供给模型。工具调用同样需要保留请求和结果，使模型知道已经做过什么。历史不断增长，而模型上下文窗口有限，因此必须主动管理进入下一次调用的内容。

存储层与选择层

消息可以保存在内存、文件、Redis 或数据库中，这是存储问题；本次调用应携带哪些历史，则是上下文选择问题。持久化能够恢复以前的会话，但不意味着应该把全部历史一次性塞给模型。这两个维度应分开设计。

三种策略及取舍

截断只保留最近若干条消息或一定 token 预算内的消息，成本低但会丢失早期信息。总结把较旧对话压缩成摘要，同时保留近期原始消息，减少上下文开销，但摘要可能损失细节。检索将历史对话或摘要向量化，根据当前问题取回语义相关内容，适合跨较长时间查找以前聊过的话题。

组合使用

总结与检索可以结合：周期性生成摘要并写入向量库，需要时按当前问题检索这些摘要，再与近期消息共同构建上下文。每轮对话结束后保存新内容，使下一轮能够检索到。框架接口会变化，稳定的设计核心仍是历史保存、预算控制与相关内容选择。

为什么不只放进程内存

单机 CLI 可以把会话保存在进程中，但多实例后端需要共享上下文。最近消息、摘要和运行状态属于高频读写数据，还常有闲置自动失效需求，适合使用低延迟、支持 TTL 的共享 Redis。

短期上下文与永久历史分层

请求读取近期对话与摘要，生成后更新短期记忆；消息另外写入 PostgreSQL 保存完整历史，并可进一步建立语义检索。Redis 过期用于释放运行时上下文，不应使永久聊天记录随之消失。

数据结构与生命周期

List 可保存有序消息，String 保存摘要，Hash 保存会话元信息；Set、ZSet 等适合集合与排序需求。TTL 对会话闲置清理有用。Redis 也具备 RDB、AOF 等持久化选项，因此“短期”是应用生命周期设计，不是 Redis 天生不能持久化。

压缩与存储分工

滑动窗口截断和历史摘要决定交给模型的上下文内容，Redis 负责跨实例存取。两者应分开理解：存储容量增加不会扩大模型上下文窗口，仍需通过摘要和截断控制输入。

短期与长期的区别

短期记忆保存当前会话的近期消息和摘要；长期记忆保留跨会话有用的用户事实、偏好与任务知识，并在需要时检索回来。它不是把所有历史对话无差别地塞入提示词。

三种作用域

用户记忆绑定用户身份，适合姓名、偏好等跨会话信息；会话记忆绑定用户与本次运行，保存临时目标与任务进度；Agent 记忆绑定助手角色，保存风格和专业设定。作用域决定读取边界，避免临时任务混入长期用户画像。

多路召回

原文介绍的方案结合向量语义、BM25 关键词与知识图谱关联检索，并融合排序。语义匹配补足同义表达，关键词保留实体与参数精度，图关系支持关联查找。具体部署具备哪些检索路径，应以所选版本与配置为准。

写入和部署设计

每轮对话后可提取值得保存的信息，判断属于用户层还是会话层，再按作用域写入。服务可采用托管或自建模式；Redis 承载短期上下文，长期记忆服务负责抽取、存储与召回，形成分层记忆系统。

统一组件接口

提示词模板、聊天模型、输出解析器等组件可以使用共同的运行抽象。将组件声明为一条处理链后，应用统一发起执行，而不必在业务逻辑中逐个调用并手动传递每一步结果。LCEL 的核心正是这种基于 Runnable 的声明式组合。

组合关系

顺序组合把前一步输出交给后一步；并行组合让同一输入进入多个处理分支，并汇总为具名结果；条件分支或路由根据输入选择不同子流程。普通函数也可以包装为组件，承接无法直接由现有组件表达的自定义处理。

数据与历史的组织

透传组件保留原始输入，扩展操作在不丢失已有字段的情况下加入计算结果，字段选择组件取出下一步所需信息。数组映射对各元素应用同一子链。历史包装层则按会话标识取得对应消息记录，在调用前补充历史、调用后保存新消息。

执行方式与边界

同一流程可提供单次执行、批量执行和流式输出入口。批量处理意味着执行多份输入，而不是改变单份输入的业务含义；流式能否逐步透传，还取决于中间组件是否支持渐进处理。声明式组合让应用专注于步骤之间的关系，而不是仅把函数调用换一个名称。

把流程拆成原子步骤

设计链之前，先识别输入、输出和控制关系，再区分顺序、分支、并行及自定义步骤。RAG 是较直接的例子：检索向量库 → 构建带文档片段的提示词 → 调用模型 → 解析并输出结果。知识检索与语言生成仍是独立职责。

工具场景需要显式状态

工具调用场景可维护消息历史、可用工具、是否完成及最终回答等状态。一次链执行先调用模型，再判断是否存在工具请求：若有则执行并把结果加入消息；若没有则标记结束。外层继续执行，直到完成。这说明把步骤组装成链，并不自动消除循环和状态管理。

在组件外增加运行能力

重试在同一节点失败后重新尝试，回退则在当前方案失败时转向其他备选方案，两者目的不同。链还可以携带配置，让各节点读取用户、权限或语言等运行上下文；回调用于观察节点输入输出或运行情况，避免把观测逻辑混入每个业务函数。

声明式组合的收益

当业务流程由明确节点组成时，运行配置、错误恢复和观测能力可以围绕节点统一附加。流程设计的关键不是追求更短的写法，而是让职责与数据流清楚，并在复用组件的同时保留对执行状态的理解。

模型适配层

不同模型服务对系统消息、输入字段和特性支持有各自约定。聊天模型抽象以统一接口屏蔽常见差异，使应用不必与某一家服务的请求结构直接耦合。兼容通用格式可以降低接入成本，但使用模型独有能力时，仍可能需要专门适配。

输入与输出层

提示词模板管理角色、背景、任务变量、历史和少量示例；输出层则负责把模型结果转换成应用需要的文本或结构化对象。工具参数和 JSON Schema 是模型侧结构约束，输出解析器处理格式提取、非 JSON 格式和渐进解析等需求。

行动与状态层

Tool 用名称、描述和参数结构表达外部能力；模型提出调用请求，应用执行并回传结果，形成 Agent Loop。MCP 把工具接入扩展到本地或远程进程。Memory 保存和选择历史消息，通过截断、总结、检索等策略控制上下文，而不是任由消息无限增长。

知识层

Loader 从不同来源提取文档，Splitter 切成合适片段，嵌入模型生成向量，向量数据库保存可检索表示。在线查询将问题向量化，找回相关原文并补充到提示词，由模型生成答案。业务标识和来源元数据让语义检索结果能够与其他业务资料关联。

编排与运行治理层

LCEL 用统一的 Runnable 把上述组件连接成顺序、分支和并行流程，提供单次、批量和流式入口。组件化后，可统一附加重试、回退、配置与回调，记录耗时、token 消耗和输入输出。理解 LangChain 可以分成两部分：每个组件负责什么，以及这些组件如何组成可观测的业务流程。

为什么拆分 Agent

单 Agent 把所有功能提示词和工具描述放在同一上下文中，容易引入与当前任务无关的信息。按职责拆分后，每个 Worker 只接收必要的提示和工具；独立任务可以并行，不同角色也能分别执行与审阅。拆分的目标是降低干扰和明确职责，并不意味着所有任务都应采用多 Agent。

节点、边与共享状态

图中的节点表示处理步骤，边决定流转方向，共享 state 承载节点之间的信息。状态需要定义默认值和更新合并规则，避免把多次写入简单理解为覆盖。条件边实现路由：满足结束条件就退出，否则返回先前节点，从而形成循环。

持久化和人工介入

检查点保存执行状态，使后续调用能够延续原会话。流程中断后可等待人工确认，再从保存的状态恢复，适合审批和高风险操作。模型节点判断是否有工具调用，工具节点执行后回到模型节点，便构成基础 Agent 循环。

Supervisor–Worker 架构

Supervisor 负责识别任务与分发，Worker 承担天气查询、资料调研等专门任务，结果通过状态和消息汇总。观测时可分别查看每个节点更新的增量状态和某一时刻的完整状态，以理解图的运行过程。

传统流程的局限

固定 RAG 把问题向量化，检索相似文档，再拼接上下文生成回答。它不区分是否需要检索，也不会自然判断证据是否充分；多步关联问题、本地知识缺失、专业术语精确匹配都是需要额外处理的情况。

让模型参与检索决策

Agentic RAG 将路由、查询规划、结果评估和补充检索纳入流程。简单问题可直接回答，需要内部资料的问题进入检索；模型根据已获得的证据决定是否继续查找，而不是把首次召回结果直接交给生成节点。

多跳检索与外部补充

复杂问题可拆成子问题，逐轮收集并去重证据，再整合生成。存在前后依赖时，后续检索需要利用已查到的信息。本地检索后评估资料是否足以回答；覆盖不足时可转向联网搜索，并将补充结果重新纳入评估。

按业务取舍

图编排适合表达分支和循环，各节点通过状态交换问题、证据和评估结论。关键词检索可补足纯向量检索对实体与术语的不足。闭环不是必须照搬的模板：业务可能只需要意图路由与较固定的检索链，关键是针对实际缺陷选择策略。

框架层次

LangChain 提供模型、工具等组件，LangGraph 提供状态、循环路由和检查点执行；DeepAgents 在此基础上组合规划、文件系统、子 Agent、长期记忆与上下文压缩，减少复杂 Agent 的重复基础建设。需要极致定制时仍可直接使用底层图编排。

中间件是扩展边界

中间件可在 Agent、模型与工具调用前后加入逻辑，调整状态、参数和返回值，也可扩展工具或提前结束流程。把共用能力放在这一层，业务 Agent 不必重复实现相同逻辑。

文件、Skill 与子 Agent

文件系统中间件为 Agent 提供读写、修改和搜索能力，并通过后端和权限范围约束访问。Skill 将可复用任务知识组织成提示资源。子 Agent 中间件声明专门角色，使复杂任务按能力分工。

记忆与上下文压缩

长期记忆可保存在可持续读取和更新的 Markdown 中；会话历史达到阈值后，摘要中间件将较早内容压缩为总结，保留近期消息。压缩用于控制 Token 和窗口大小，但总结质量决定哪些关键信息能被继续保留。

规划中心与三个角色

主 Agent 把调研主题拆成计划，按“规划、调研、分析、起草、审阅、定稿”推进。调研员聚焦单一子主题，联网收集事实和来源；分析师在需要数字比较时借助计算工具；编辑审阅准确性、结构与引用，返回修改建议。

产物驱动协作

调研与分析分别输出结构化材料及文件，主 Agent 汇总材料撰写报告。多个互不依赖的调研任务可以并行。编辑不直接改写报告，而由主 Agent 根据反馈修订，使审阅与定稿责任分离。

可靠执行机制

复杂任务先维护待办清单，标明当前、未开始与已完成项，子任务也可有自己的计划。数字分析交给受约束的执行环境，不依赖模型凭语言猜测计算结果。来源 URL 随事实一起保存，支撑报告引用。

上下文与可复用能力

Skill 封装调研和报告规范，持久记忆保存跨任务信息，摘要机制压缩过长会话。框架可把原始会话归档，同时保留可继续工作的摘要；触发阈值应与所用模型的上下文限制相匹配。

从 HTTP 路由到应用架构

Nest 在底层 HTTP 能力之上提供模块化、依赖注入、类型约束与统一请求处理组件。它的价值是为复杂 Agent 后端组织业务边界和共享能力，而不只是增加几个路由。底层默认可使用 Express。

IoC 与 DI

对象创建和依赖管理交给容器，业务类声明所需服务，不必自行构造完整依赖链。Provider 将模型、工具和业务服务纳入统一管理，控制器负责入口，服务负责业务，各模块组织自己的职责。

AOP：横向治理

身份校验、参数校验、日志和异常格式是跨业务模块的共性逻辑。把它们抽离为组件，再声明式地应用到相应入口，可减少重复代码并集中维护。Guard 判断认证和权限是否放行；Pipe 校验与转换入参；Interceptor 环绕处理日志、耗时与响应；Exception Filter 统一处理异常。

认证上下文

客户端携带令牌，服务端验证通过后建立当前用户上下文，再交给业务处理。JWT 的信息读取与验证不是一回事，不能只解码就当作认证成功。认证与授权应作为通用边界能力，而不是散落在每个业务方法里。

三类数据分工

对象存储保存 PDF、图片、音视频以及生成产物；关系数据库保存文件来源、名称、切片与版本等元数据；向量索引负责文本片段的语义匹配。检索结果携带文件或切片 ID，回查元数据并定位原始文件，支撑引用溯源。

对象不是目录中的普通文件

对象通常由唯一 Key、二进制内容和元数据组成，放在 Bucket 中。界面的文件夹视图可由 Key 中的斜杠与前缀模拟，不能直接套用本地文件系统的真实目录模型。块存储提供磁盘级能力，文件存储提供目录层级，对象存储提供对象访问接口。

托管与自建的取舍

阿里云 OSS 代表托管服务，可减少存储运维；MinIO、RustFS 代表自建选择，适合数据需要留在内部的场景。选型应考虑部署规模、协议兼容、运维能力及具体版本许可，不把某种许可证简单理解为无条件可用或不可用。

兼容性降低耦合

S3 兼容接口让应用有机会复用统一的对象访问方式，但仍应核对具体服务支持的功能。对象存储与数据库通过稳定标识关联，而不是让生成模型直接承担文件定位和归档职责。

异步解耦的场景

文档解析成 Markdown 后，向量化与全文索引不必占住同一个同步接口。生产者发布解析完成消息，不同消费者分别完成向量索引和全文索引，让各处理阶段独立推进。若两项任务都必须执行，应由路由把消息送入各自队列，而不是让两类处理竞争同一份任务。

核心组件

Broker 是承载消息系统的服务；Connection 是客户端的 TCP 连接；Channel 是连接内的逻辑通道，减少反复建立物理连接的开销。Producer 发布消息，Exchange 根据绑定规则路由，Queue 保存等待处理的消息，Consumer 从队列取出任务执行。

四种交换机

Direct 按路由键精确匹配；Fanout 广播到所有绑定队列；Topic 按分段通配规则匹配，星号匹配一个段，井号匹配零个或多个段；Headers 使用消息头条件，而不是路由键决定去向。

架构价值

队列把任务提交与实际处理分开，消费者可按职责独立扩展。交换机决定任务如何分发，队列承接等待，消费者执行具体工作，不能把“异步”误解为所有下游任务自动都会收到消息。

业务、数据和专项组件

关系数据库保存用户等原始业务数据；Redis、全文检索、向量检索和消息队列提供缓存、搜索、异步处理等专项能力。业务服务协调这些组件，对外提供统一功能。原始数据与派生索引的可靠性要求应分别理解，不能笼统认为所有中间件数据都可丢失。

镜像与容器

镜像封装应用及其运行依赖，容器是镜像的运行实例。同一镜像可运行多个实例，服务环境保持一致并相互隔离。端口映射把宿主机入口连接到容器内服务；环境变量承载运行配置。

数据与构建产物分离

数据库即使运行在容器中，也需要将数据目录挂载到持久存储，避免把业务数据绑定在某个容器生命周期上。多阶段构建将依赖安装、编译和最终运行环境分开，最终镜像只保留运行所需产物与依赖，减少无关源码和构建工具。

开发与生产编排

Compose 用一份声明描述多个服务、网络、数据卷与启动依赖。开发环境可统一启动数据库和中间件；生产环境再加入应用镜像。在同一 Compose 网络内，服务可以通过服务名寻址，应用连接地址应随部署环境调整。

把脚本能力变成服务

产品中的 Agent 通常运行在后端，由前端提交问题、后端调用模型并返回结果。Nest 通过模块组织功能，Controller 处理接口与输入输出，Service 承载业务逻辑；模型与链可以作为服务中的协作组件，而不是散落在路由处理里。

依赖注入与配置解耦

依赖注入让服务声明所需能力，由容器提供相应实例。聊天模型可以作为独立 Provider，由工厂根据运行配置创建，再注入业务服务，从而把模型选择与业务流程分开。配置集中管理，避免密钥与连接参数硬编码在业务逻辑中，也避免每次请求都重复构造相同组件。

SSE 的传输原理

SSE 在一次 HTTP 请求对应的响应流中，持续向浏览器发送事件，响应类型为 text/event-stream。后端把模型输出片段转换成事件，浏览器接收后逐步展示。它适合服务端持续向客户端发送文本，不要求每次得到完整答案后才结束响应。

从生成流到展示流

业务服务负责产生异步文本片段，控制层负责将片段映射为 SSE 事件，前端负责接收与增量渲染。Nest 可用异步流和响应式抽象衔接这些环节。模型生成、业务处理、协议封装和界面展示分层后，便于分别替换模型或交互方式。

从文字流到事件流

只有文本的 SSE 不能完整表达工具执行过程。界面需要知道当前内容是回答文本、工具参数还是执行结果，因此应把带类型和状态的结构化事件放进流中。这样同一条连接既能增量显示文字，也能驱动搜索结果卡片、邮件状态等组件。

前后端的职责分界

后端用 LangChain 执行模型与工具循环，通过适配层把内部消息转换成面向 UI 的消息流；前端负责解析消息并按内容片段类型渲染。消息标识、角色与内容片段共同组成会话状态，工具名称决定采用哪种展示组件。业务执行不应混入界面渲染逻辑。

状态如何映射到组件

文本经历开始、增量、结束；工具经历参数接收、参数完整、结果可用等状态。前端据此展示等待、成功或错误，结果就绪后才读取输出并呈现业务内容。Markdown 流也需要能够处理未结束文本的增量渲染层。

协议名称的边界

原文以 AGUI 描述 Agent 与图形界面的交互目标，实际示例采用 Vercel AI SDK 的流式消息协议，并由其 LangChain 适配层连接后端。这里保留的是该事件流设计，不能把 AI SDK 协议直接等同于独立的 AG-UI 标准。

输入与输出链路

语音输入先经 ASR（自动语音识别，也称语音转文本）得到文字，再交给语言模型生成回答。输出侧由 TTS 将回答文本合成为语音。原文采用录音结束后上传并识别的输入方式；这是一种具体设计选择，而不是说所有 ASR 都不能流式处理。

为什么输出要流式

模型回答通常逐步生成，如果必须等全部文本结束才开始合成语音，会明显增加等待。流式 TTS 接收持续到达的文本，并逐步产生音频，让文字显示和语音播放在生成过程中同时推进。

SSE 与 WebSocket 分工

文本回答通过 SSE 推送，二进制音频通过单独的 WebSocket 通道推送。SSE 是文本事件协议，若用它传音频通常要额外编码，因此此方案将二进制流交给更合适的传输通道。后端在生成文本时发出事件，语音中继监听这些事件，把文本送到 TTS 服务，再把返回音频转发给浏览器。

会话、控制事件与播放

后端通过会话标识关联本次文本生成和音频连接。连接启动、文本片段、结束或错误等控制信息与音频数据分开处理：控制信息表示状态，二进制片段用于播放。前端用媒体源和缓冲区逐步追加音频，实现边接收边播放。整体架构由识别服务、模型服务、语音中继、两个传输通道和前端播放缓冲共同组成。

模型和素材存储各司其职

图片理解、图片修改及音视频处理需要相应多模态能力的模型。对象存储保存用户输入素材和生成产物，并提供模型可访问的素材地址。模型决定能处理什么模态，存储层解决素材传输、保存与后续访问。

为什么采用客户端直传

大文件先传业务服务器、再转交对象存储，会重复传输并占用服务器带宽。直传模式由后端发放临时访问凭证，客户端直接上传到对象存储；业务服务保留授权与后续处理职责。

生成产物需要归档

模型返回的图片或音视频可能位于临时地址，不能把临时结果视为永久资产。需要将有保留价值的产物转存到自身存储，并向前端返回可持续管理的对象地址。有效期依具体模型服务而定。

AI 画板的完整链路

用户素材直传后，前端把素材引用与修改需求交给后端；后端调用多模态模型，再保存生成结果并返回引用。上传、推理和归档是独立阶段，界面围绕各阶段展示状态，而无需承担模型调用与长期凭证管理。

定时任务最终执行什么

用户提出“到某时做某事”时，系统需要同时理解触发时间与任务指令。到期后并不只是输出一条固定字符串，而是启动一个 Agent Loop，根据保存的目标调用搜索、邮件、数据库等业务工具。定时触发与模型执行因此是两个不同层次。

先建立可复用业务工具

搜索工具取得外部信息，邮件工具负责发送整理结果，业务数据工具负责访问系统资料。工具不应把所有逻辑都塞进模型提示词，而应封装真正可执行的服务。通过依赖注入把业务 Service 交给工具，使同一能力既可服务 HTTP 接口，也可被 Agent 调用。

Agent Loop 与流式接口

模型产生工具请求后，应用执行并把结果加入消息历史，再次调用模型，直到不再请求工具。对交互式调用，可以将普通回答片段通过 SSE 推给前端；对于流式工具参数，则先累积成完整调用，再执行实际工具。模型文字生成与工具动作是不同类型的输出。

为后台执行复用同一能力

把工具独立于具体交互界面，有助于后台任务复用搜索、发送邮件等能力。定时任务的持久化与调度可以在这一基础上独立加入，而不必为每种任务另写一套固定业务流程。

把自然语言拆成调度与指令

定时任务包含两部分：何时触发，以及到时要执行什么。模型把用户目标转成调度类型、时间参数和指令文本，系统保存这些结构化信息；触发时再启动 Agent 解释指令并调用工具。这使“每天整理资讯并发邮件”可以复用搜索与邮件能力，而不是为该句需求写死一个专用流程。

三类时间模型

日历型任务按 cron 规则触发，间隔型任务按固定时长重复，一次性任务在指定时刻触发。任务记录需要保存标识、指令、类型、相应时间参数与启停状态，以支持列表管理及状态切换。相对时间还需要当前时间作为推断依据，不能假定模型天然知道准确的运行时刻。

业务数据与工具层

关系数据库保存任务和业务实体，ORM 把实体对象操作映射到表操作。业务 Service 封装数据访问，再作为工具的底层能力；这样模型面对的是明确的动作及参数，而不是任意拼接数据库操作。定时任务工具同样负责创建、查询与管理任务。

触发后的独立执行

调度器到期后把已保存的指令交给专用 Agent Loop，由模型选择搜索、邮件或业务数据工具，逐轮使用执行结果完成任务。后台运行不需要为了界面展示而强制流式返回。原文还限制该执行器不提供定时任务工具，防止执行中的任务继续创建新的定时任务，清楚区分任务管理与任务执行。

离线构建与在线检索

离线对文档解析、清洗和分块，建立向量及 BM25 索引。在线先改写查询，再执行混合召回，按一致 chunk_id 去重，融合候选并重排，将精筛证据交给模型。父子分块让小块用于定位，大块用于生成上下文。

RRF 与 Rerank 的分工

不同检索器的原始分值尺度不同，不能直接相加。RRF 根据候选在各列表中的排名融合，先做低成本粗排；再截取候选交给重排模型深度比较，减少精排开销。图谱检索补充实体关系，Agentic RAG 则让模型参与规划、评估和重新检索。

权限与幻觉治理

块继承文档权限，并同步进入各检索索引；根据当前用户角色先限定可访问范围，再召回和重排，防止无权限资料进入模型上下文。提高原始资料质量、筛除低相关片段、要求基于引用作答、证据不足时拒答，以及二次核查，都可减少无依据输出。

检索层评估

建立贴近业务、包含正确文档和关键片段标注的数据集。Recall@K 衡量相关材料的覆盖，Precision@K 衡量候选中相关材料的比例，Hit@K 看是否至少命中，MRR 看首个相关结果的位置。覆盖比例与命中样本比例是不同指标，不应混称。

生成层与代码搜索

忠实度关注证据支撑，答案相关性关注切题，完整性关注关键点覆盖，上下文利用率观察证据是否真正被使用；可由模型裁判并结合人工复核。代码检索中，标识符精确匹配和文件实时性很重要，按内容搜索、文件名定位、读取上下文再迭代，是不同于预建向量索引的 Agentic Search 路线。

观测执行过程

Trace 记录 Agent、图或链中各步骤的输入输出、工具参数与结果、Token 消耗、耗时和错误。它让调试从只看最终文本，转为分析哪个节点出了问题。Monitor 将多次运行汇总为调用次数、资源消耗等统计指标。

数据集与实验

Dataset 统一保存真实业务问题及标准答案。Evaluator 定义评分规则；Experiment 在同一数据集上批量执行 Agent 并保存评分，使不同版本的效果可以在共同基准上比较。观测说明系统如何运行，评估回答系统运行得是否有效。

RAG 的几个评估维度

忠实度关注答案能否被检索上下文支撑；有用性关注是否切题并解决需求；检索相关性关注召回片段是否与问题相关。评估可以使用大模型裁判，也需要明确每个指标的判断依据。

优化闭环

先收集运行链路，再建立样本与评分规则，批量评测后定位低分案例，回到检索、提示和图流程中优化。单次示例跑通不等于业务质量得到验证，量化评估用于持续比较改动效果。

统一的可观测链路

Langfuse 支持采集模型与工具执行过程，利用 OpenTelemetry 等埋点机制连接不同框架。Trace 用于查看单次执行，监控汇总耗时、消耗、错误等指标，还可根据阈值触发通知。

效果评估仍需数据与规则

数据集保存问题与评估依据，评估器定义质量判断，实验批量执行并比较结果。这与运行监控互补：请求没有报错，并不表示回答忠实、完整或有用。

自建服务的组件分工

Web 接收请求并提供界面，后台 Worker 处理异步任务；Redis 承载队列与缓存；PostgreSQL 保存业务元数据；ClickHouse 支撑高吞吐链路数据的查询分析；对象存储保存附件或相关大文件。

选型关注数据控制与运维

托管模式减少部署工作，自建模式让数据和基础设施由团队掌控，同时也需要承担资源和运维成本。LangSmith 在 LangChain 生态接入方便，Langfuse 强调跨框架埋点与开源自建。不能把开源自建理解为没有任何运行成本。

建设目标与能力边界

企业知识分散在业务资料、经验和流程规范中，关键词查找难以覆盖自然语言需求。知识库将文档管理、语义问答、全文检索、知识图谱与权限管理结合，统一归集并复用知识。

多模态入口包括文本与网页、图片、音频和视频：文本统一为 Markdown；图片借助 OCR 和图像理解生成描述；音频通过 ASR 转写；视频结合语音与画面形成可检索内容。原文件与抽取图片进入对象存储。

存储与检索架构

本篇是初始方案：PostgreSQL/PGVector 管理结构化数据与向量，Elasticsearch 承担关键词检索，Neo4j 保存实体与关系，Redis 管理短期记忆及权限缓存，MinIO 保存资源，Mem0 保存用户级与会话级长期记忆。后续章节会调整正文存储、队列和向量库选型。

上传后的耗时解析、分块、向量化与建图异步执行，任务表记录进度。问答侧由 Agent 判断问题复杂度，结合关键词和向量召回、RRF 融合、Reranker 重排，复杂问题补充图谱多跳检索。

安全、生成与观测

检索结果必须限定在用户可访问的文档范围内，再与分层记忆组成模型上下文。回答通过 SSE 流式输出，可选 TTS 与 WebSocket 语音播放。

会话与消息持久化；观测链路记录耗时、Token、召回来源和异常，配合数据集评测迭代效果。

架构与原理图

用户与角色基础模型

用户、角色通过关联表构成多对多关系：用户可拥有多个角色，同一角色可分配给多个用户。文档归属和会话历史均以用户身份为基础。

双令牌机制

AccessToken 用于业务请求，生命周期短，过期后需要重新获取；RefreshToken 生命周期较长，仅用于换取新访问令牌，不应直接调用业务接口。刷新令牌泄露风险更大，需要妥善保护。

登录后获得两种令牌；业务请求使用访问令牌；过期后凭刷新令牌获取新令牌，再继续业务访问。具体有效期是项目配置，不是 JWT 的固定要求。

认证与授权分离

受保护请求先验证 JWT 身份，再验证角色是否允许访问；通过后才进入业务处理。身份无效与权限不足是两类不同失败。注册、登录和刷新属于身份模块；用户信息与角色查询服务于后续文档权限控制。

架构与原理图

邮箱验证与账号激活

注册不仅创建账号，还生成激活凭据写入 Redis 并发送邮件；验证成功后将邮箱标记为已激活。登录流程只放行已激活账号，形成注册、验证、登录的闭环。

密码找回流程

通过已注册邮箱发送短时验证码，Redis 保存其有效状态。用户提交验证码与新密码，校验通过后更新密码，并删除验证码以保证一次性使用。邮件服务负责送达，Redis 负责临时验证状态。

管理能力与权限边界

用户和角色管理区分普通用户与管理员的操作范围，不同接口采用相应授权规则。DTO 描述请求输入，VO 描述对外返回的数据，两者面向不同边界。

架构与原理图

RBAC 与直接赋权

RBAC 是基于角色的访问控制：先把权限归集到角色，再给用户分配角色，以复用权限组合。项目额外支持对用户直接赋权，满足临时特例，但角色仍是主要载体。用户、角色、权限之间通过关联模型表达多对多关系。

三类权限与权限码

菜单和按钮权限控制前端显隐，接口权限由后端强制校验。统一用权限码判断权限，菜单地址和接口地址主要用于展示与管理。树形父级用于分类，不自动产生业务授权含义。

前端隐藏入口不能替代服务端访问控制。团队组织架构管理与功能权限是不同维度，后续可共同支撑数据访问范围。

三层授权流水线

身份校验 → 角色校验 → 权限码校验，串行执行、失败即终止。身份缺失或令牌无效返回 401；角色或权限不足返回 403。普通用户需要满足接口要求的权限集合，项目中的超级管理员可按规则直接放行。

文档生命周期与分层存储

文档是知识问答的来源，未经审核的错误、敏感或垃圾内容不应直接成为检索依据。上传解析与正式发布是两个阶段，审核通过后才构建分块、全文索引、向量索引与知识图谱。

原始二进制文件保存到 RustFS；标题、作者、分类、状态、权限、统计等元数据存 PostgreSQL；完整 Markdown 正文独立存入 MongoDB，通过内容关联 ID 一一对应。

为什么拆分元数据与正文

列表筛选、分页、权限和统计只读轻量元数据；详情页才读取长正文，避免长文本拖累列表查询，并隔离两类数据的读写负载。图片外置到对象存储，正文只保留链接。

MongoDB 单文档有 16MB 上限。原文基于图片外置和常见企业文档规模判断该上限通常不是主要问题；这是方案的适用前提，而非取消容量限制。

章节演进说明

本篇早期文字将“已驳回”列为状态，但其存储图已出现“已归档”；第 55 篇进一步明确为草稿、待审核、已发布、已归档，驳回回到草稿。阅读时应区分方案演进。

架构与原理图

审核是知识入库门禁

只有已发布文档可以写入向量、全文和图谱三套索引。草稿、待审核、已归档文档不参与召回，避免隐私、无效或未审核内容成为回答依据。

四状态与流转

草稿：可编辑；提交后进入待审核。待审核：审核通过进入已发布；驳回带意见回到草稿。已发布：触发异步构建三套索引。已归档：下线并清理索引，保留正文。

已发布文档重新提审或退回草稿编辑时，需要清理旧索引；审核重新通过后再重建。测试模式可跳过审批，但不改变“仅已发布可入索引”的规则。

审核审计

审核记录独立持久化，包含文档、审批人、结果、意见和时间，以支持历史追溯。完整生命周期覆盖上传解析、提交、审核、修改重审与归档。

架构与原理图

统一文档表示

PDF、XLSX、DOCX、PPTX、TXT/MD 的结构不同，但解析结果统一为 Markdown，保留标题、段落、表格等语义，便于后续按结构切分和检索。文档图片提取后放入对象存储，正文保存资源链接。

解析组件职责

不同格式由各自解析器负责，格式分发与存储流程分离：PDF 关注页面、文本、图片与表格；电子表格保留工作表及表格结构；Word 保留文档结构；幻灯片按页组织内容。部分格式在解析失败时采用备用解析器。

通用 Loader 的默认文本提取不一定满足图片外置、标题规范化等定制需求，因此本阶段采用专门解析管线。第 69 篇后续改用 MinerU 增强 OCR、公式和表格能力。

存储与后续处理

解析产出的正文存 MongoDB，元数据存 PostgreSQL，原始文件与图片存 RustFS。文档发布后再进入分块、向量化、全文索引和知识图谱链路。

架构与原理图

为什么更换文档解析方案

自研解析需要同时处理版面、扫描件 OCR、公式、表格和图片，完善成本较高。MinerU 将这些能力集中为解析服务，项目因此由分散的格式解析器转向统一解析方案。扫描 PDF 没有可直接提取的文字层，必须经过 OCR。

解析模式与资源边界

文章区分轻量解析与需要鉴权的精准解析：需要完整图片资源时，选择能返回 Markdown 与图片包的模式，不能只取得文本后忽略图片。具体 API 能力与额度属于当时服务状态。

异步解析与对象存储

总体设计为提交解析任务、上传文件、查询任务状态、获取结果包。应用取出 Markdown 与图片，将图片转存到自己的对象存储，替换正文中的本地图片链接，避免依赖临时结果地址。

可以再用视觉模型生成图片描述，增强图文内容的检索语义。最终产物仍是统一正文与外置图片，后续入库、审核和检索流程保持不变。

架构与原理图

异步 RAG 流水线

发布文档后需要构建三类检索数据，耗时任务不应阻塞发布接口。接口更新发布状态并向 RabbitMQ 投递事件，由独立消费者异步执行，三条管线并行解耦。

三条处理链路

Search：文档元数据与正文进入 Elasticsearch 文档级索引，支持独立的全文搜索。

RAG：根据文档 ID 加载正文，按 Markdown 标题与段落切块，生成 Embedding 后写入 Elasticsearch 分块索引，同时支撑向量与关键词检索。

KG：加载正文、分块、抽取实体与关系，写入 Neo4j，支撑关联查询。

职责与方案演进

消息基础设施负责投递和消费；流水线负责分块、向量化与索引写入。Elasticsearch 同时支持倒排索引与向量字段，因此该阶段不另设专门向量库。

此篇 Search 消息携带文档快照；第 59 篇改为仅传文档 ID、消费时读取完整正文，避免消息截断造成全文检索缺失。

架构与原理图

全文检索链路的定位

文档级全文搜索与 RAG 分块语义检索是不同用途：前者写入文档索引，返回文档级关键词命中；后者写入分块索引，为问答提供相关片段。知识图谱是第三条独立链路。

发布订阅与索引同步

文档发布事件由交换机路由到各自队列，Search 消费者依据文档快照建立全文索引，与 RAG 消费者并行。Topic 交换机按路由键匹配订阅，实现消息分类分发。

文档删除也需要触发索引删除，使检索库与业务数据保持联动，而非只处理新增。

本篇仍采用快照传正文；第 59 篇会修正为按文档 ID 拉取完整正文，避免索引内容被消息长度限制截断。

架构与原理图

图谱抽取与领域建模

图谱实体与关系必须依据业务领域定义。企业知识可涵盖人员、组织、概念、流程、产品、地点、时间、制度和资源；医疗、工业等领域则需要对应的专业类型。关系可表达包含、归属、依赖、使用、负责、因果与冲突。

三级溯源结构

图谱分为文档、文本块和知识实体三级：文档包含文本块，文本块提及知识实体，知识实体之间具有语义关系。

必须保留文档和文本块节点，才能从抽取结果回溯原文，支持引用、可解释性与纠错。知识实体可以跨文档复用，不能失去来源关联。

构建与删除的边界

发布事件经独立消息队列进入建图流水线：读取正文、分块、由大模型抽取实体关系并写入 Neo4j。结构化输出约束抽取结果，减少格式不确定性。

删除文档时联动清理文档及文本块，再清理已无任何文本块引用的知识实体，避免误删仍被其他文档使用的实体。

架构与原理图

可见性是数据权限

功能权限决定能否调用检索功能，数据权限决定能看到哪些文档。可见性由公开标记、所属团队、作者与文档状态共同决定：作者可查看自己的文档，其他用户可查看已发布的公开文档或所属团队文档。

在召回阶段过滤

关键词和向量召回都应基于当前用户身份与团队范围过滤，再进入 RRF 融合和重排。不能只隐藏前端结果，也不能把无权限正文先交给模型再过滤。

相同规则应覆盖独立全文搜索、知识图谱检索和文档列表；图谱查询也必须结合文档来源施加范围限制。

权限变化与状态边界

文档公开性或团队归属变化后，需要同步三条索引链路，避免旧权限长期残留。

作者可在业务列表中看到自己的草稿，不意味着草稿进入 RAG；第 55 篇的“仅已发布进入三套索引”仍是知识召回的状态门禁。

架构与原理图

三种检索入口

文档全文搜索返回整篇文档的关键词命中；RAG 在分块索引上做关键词与向量混合检索，为模型提供片段；图谱搜索返回节点与关系。独立搜索入口不等于 AI 问答流程。

完整正文与高亮

早期 Search 消息只保留前 1000 字，导致后续正文无法检索。修正为消息仅传文档 ID，由消费者读取完整正文建索引，避免消息截断。

Elasticsearch 的倒排索引配合中文 IK 分词完成关键词检索；高亮返回命中词附近片段，帮助用户定位相关内容。

图谱搜索与结果组织

关键词可匹配文档标题与摘要、文本块标题与内容、知识实体名称与描述，再返回对应节点及关系。实体、文本块、文档的三级结构同时支撑检索和来源追溯。

架构与原理图

混合检索的组成

关键词检索擅长精确词项匹配，向量检索按语义相似性召回。Elasticsearch 的倒排索引与向量字段使二者能在同一分块索引中完成。kNN 表示寻找与查询向量最近的若干向量。

从召回到回答

双路召回 → RRF 倒数排名融合 → Reranker 精细重排 → 选择高相关片段 → 构建上下文 → 模型生成回答。融合综合两路排名，重排进一步判断候选与问题的相关性并过滤噪声。

检索能力与生成能力分层：检索入口只返回命中资料，问答入口在相同检索结果上构建提示词与上下文并生成答案。

引用与选型边界

回答保留文档及片段来源以支持溯源，前端可据此展示引用位置。本篇先描述非流式闭环，SSE 输出将在后续加入。

原文在该项目规模下选用 Elasticsearch 同时承担全文与向量检索；是否采用专门向量库应结合数据规模与检索需求理解，不把经验规模当成普遍硬阈值。

架构与原理图

会话与消息的数据模型

会话保存所属用户、标题和时间等整体信息；消息保存角色、内容、RAG 来源与时间。一个会话对应多条消息，来源字段使历史回答仍可追溯引用。

外键与生命周期一致性

消息脱离会话没有独立意义，因此使用外键并级联删除：删除会话时同时清理其消息，避免孤立记录。

文档与作者不同：作者账号删除后，文档仍可能需要归档和溯源，不能简单随用户级联删除。关系约束要依据子记录是否能独立存在来设计。

原文针对企业内部、并发有限的场景采用数据库外键；高并发场景的关联维护需要另行权衡，不能仅按是否互联网项目作绝对判断。

历史记录闭环

回答完成后持久化问答消息，前端以会话列表和会话内消息列表组织历史，打通会话管理、消息读取与引用展示。对话持久化不同于向模型提供记忆，后者在第 65 篇继续设计。

架构与原理图

短期记忆与长期记忆

短期记忆是近期对话上下文，解决连续追问与指代；长期记忆是用户信息、偏好等可跨会话复用的事实，不是完整聊天原文。

短期记忆的缓存与持久化

Redis 按用户与会话隔离保存滑动窗口，项目默认保留约 20 条消息、TTL 24 小时；缓存失效时从 PostgreSQL 最近消息回填。超出窗口的内容做摘要，控制上下文长度。

回答前利用近期上下文改写“这个”“那个人”等指代不明的问题，再检索知识库。对话消息保存在 PostgreSQL，并同步回写 Redis。

长期记忆的分层与质量边界

Mem0 区分用户层的稳定身份、岗位与偏好，以及会话层的当前任务、进度与待办。删除会话只清会话层，用户层记忆继续保留。

回答后由异步分类器判断是否出现新事实以及应归哪一层。事实来自用户表达；寒暄、助手转述的制度、知识库片段和网络结果不应写入用户画像。异步抽取意味着刚写入的记忆可能尚不可检索。

问答总体流程

加载短期窗口 → 基于上下文改写问题 → 并行检索知识库与 Mem0 → 组装资料、记忆、近期对话和当前问题 → 流式作答 → 持久化与回写 → 异步抽取长期记忆。

架构与原理图

固定 RAG 与 Agentic RAG

传统 RAG 是提问、单次检索、生成的固定流水线。Agentic RAG 让模型决策何时检索、搜索什么、资料是否足够、是否改写再查和是否联网，形成有界的决策循环。

五类意图与工具边界

意图分为闲聊、个人偏好、知识库、联网、知识库不足再联网。按本轮意图挂载工具：内部制度只查知识库，公开时效问题可联网，闲聊与偏好无需检索。识别失败时默认知识库，避免漏查内部问题。

检索、评估与改写闭环

检索器在可见文档范围内进行 BM25 与向量召回、RRF 融合和重排。相关性分数高不等于切题，因此还需评估资料是否真正回答当前问题。

资料切题则作答；不足时依据原问题、上轮检索词与失败原因改写再检索。项目将知识库检索限制为最多两次，仍不足时只在意图允许的情况下联网；纯内部知识不足则明确告知，不能用用户记忆编造制度。

生成、引用与会话

只有评估切题的资料进入回答上下文，回答标注实际使用的来源，前端不展示未引用资料。整个过程结合长短期记忆、流式进度与会话持久化；意图、评估和改写使用结构化输出约束结果。

架构与原理图

图谱补充文本检索

Graph RAG 将实体和关系引入问答，适合回答负责人、审批关系、归属和跨实体关联等问题。它与提供具体制度段落的混合文本检索互补，而非取代文本证据。

纳入 Agent 决策循环

知识库相关意图同时提供混合文本检索与图谱检索工具；模型按需要并行调用。图谱侧以问题中拆出的关键词匹配实体，再获取关联关系及来源文档，一并返回给模型。

工具挂载仍受意图限制，网络搜索不是每轮启用。保留原有切题评估、查询改写和有界重试机制，使 Agent 能整合两类证据后作答。

展示与观测

前端按工具消息类型展示对应过程，图谱结果可用节点与边的力导图表达；链路观测用于核对实际调用与检索结果。最终方案成为同时支持文本混合检索和图谱检索的 Agentic Graph RAG。

架构与原理图

前端模块与分层

前端围绕文档管理、文档搜索、知识图谱和 AI 问答四类业务界面组织。整体分为应用入口、路由、布局、业务页面、公共组件、身份状态与请求封装，避免页面直接承担全部基础职责。

前后端权限协作

前端根据权限集合控制页面、菜单和按钮的可见性，后端负责接口级强制校验。文档从草稿、提审到发布，再进入检索体系，前端展示应与业务状态一致。

图谱与问答呈现

图谱界面将实体组织为节点、关系组织为边，支持概览、统计与过滤；它是独立图谱入口，后续才与 RAG 进一步融合。

AI 问答展示引用来源；检索不到相关资料时明确说明，而不是生成无依据答案。联调验证用户权限、审核、三类检索和来源引用是否形成完整闭环。

流式 UI 的职责分工

模型输出不仅是文字，还包括思考过程、检索进度与工具调用。LangChain/LangGraph 负责 Agent 推理与工具编排，Vercel AI SDK 的 UI Message Stream Protocol 负责将这些过程组织成可消费的消息流，SSE 负责传输。

后端事件与适配层

后端创建或续用会话，检索资料，输出自定义进度事件，再将 Agent 产生的内容与工具消息适配为 UI 消息流。协议适配层将 Agent 框架格式与前端渲染格式解耦。

前端按语义部件渲染

前端消费流式消息，根据部件类型呈现正文、思考、引用和工具卡片，而不是把所有事件拼成同一段文本。新增工具主要扩展对应的消息语义和展示组件，沿用同一流式架构。

架构与原理图

从检索系统到完整产品

核心检索与问答之外，还需要文档组织、协作、分享与历史追溯能力。这些功能不改变 Agent 的核心原理，但影响产品完整性和日常使用体验。

文档组织与协作

分类管理组织知识内容；评论和点赞承载协作反馈；收藏提供个人常用文档入口。版本管理记录历史并支持恢复，避免文档演变不可追溯。

分享与通知

分享链接支持公开或密码访问，并可设置过期时间，用于受控传播。通知承载评论、点赞等互动提醒，以及管理员站内消息，使用户及时获知文档动态。

架构与原理图

Tracing：观察真实执行链路

可观测性记录每次问答的上下文、工具调用、耗时、Token 消耗与错误，帮助定位 Agent 行为与成本。原文在开发中使用 LangSmith，生产方案选择可自行部署的 LangFuse。

OpenTelemetry 的 Span 描述函数或阶段的执行数据，由处理器向 LangFuse 上报；必要时补充业务自定义观测点。

评测：从个例调试到可重复实验

实验需要数据集、评估器和可独立运行的 Agent 入口。数据集包含问题与预期结果；评估器把检索、回答和工具行为转成指标；实验结果集中上报，用于比较迭代前后表现。

指标与优化闭环

RAG 常见指标包括 Recall@K、Precision@K 和回答忠实度。业务指标包括意图识别是否正确、应检索或联网时是否调用对应工具、首轮不足时是否改写再查。

部分指标可公式计算，语义判断可借助 LLM as Judge。指标和数据集应贴合实际业务，完成“测量 → 找问题 → 优化 → 重跑实验”的闭环，而不是只展示某次调试结果。

按能力组合，而不是堆技术名词

原文项目案例中的共同结构包括意图识别、多 Agent 分工、混合检索、知识图谱、短期与长期记忆以及效果评估。这些能力应由业务问题驱动：医疗实体关联需要图谱，政策问答需要可靠检索，订单业务需要连接真实系统。

工具与人工介入

订单、CRM、工单等既有能力可以封装成工具，由 Agent 按需求调用。退款审批等需要人工决策的步骤可中断流程，确认后恢复。Workflow 是预先规定步骤，Agent 则让模型动态决定下一步；二者可以组合，而非互相排斥。

关系图谱辅助 NL2SQL

表与表之间的关系可以存为图谱，先检索起始表，再沿关系找到相关表，为生成 SQL 提供结构依据。意图识别通常可通过提示与少量案例完成，类别和业务复杂时再考虑专门模型。

多模态、反思与量化验证

多模态嵌入把图文放入可匹配的表示空间，与先 OCR 后只检索文字的方案不同。生成与评价节点可组成修正循环；检索召回、意图识别及端到端回答质量则应通过数据集评估，而不是仅凭演示判断。

客服路由与工具边界

FAQ 可先匹配标准问答，命中后直接返回标准答案；复杂政策问题走检索生成，订单物流等实时事实通过工具查询。主 Agent 分流政策、投诉等任务，无法解决或需要审批的请求转人工，不能把自动生成与业务批准混为一谈。

NL2SQL 的约束

自然语言查数需要表、字段等 Schema 背景，可通过关键词与向量检索获取。稳定需求可使用模板或拼接查询，复杂需求再生成 SQL；执行前检查操作和表范围。Prompt 可按角色、规则、动态 Schema、示例与用户问题分层管理。

父子分块

先按章节形成较大的父块，再切成更小子块并保存 parent_id。子块进入检索索引以提高定位精度，命中后取回父块，为生成提供连续上下文。文档的路径、章节、页码及权限信息随块保留，兼顾引用和访问筛选。

跨模态检索与记忆

OCR 只保留识别出的文字，可能遗漏图形和布局；多模态嵌入直接将图文映射到可比较空间，支持文搜图等需求。运行时记忆可用近期窗口和摘要，长期记忆再按语义与关键词召回；观测与评估用于判断这些设计是否真正有效。

文档与图片统一入库

文档解析可统一输出 Markdown，按章节与长度分块，采用父子结构兼顾精确定位与上下文完整。图片可以保存原文件到对象存储，再由多模态模型生成描述加入 Markdown，使描述参与文本语义检索；这与直接多模态向量化是不同路线。

元数据支撑可信访问

保存文件路径、章节、页码、版本和权限信息，使每个检索片段能定位原文并接受访问过滤。引用溯源来自稳定的数据关联，不是生成模型临时猜测来源。

HyDE 增加一个召回角度

模型先根据问题生成假设回答或文档，将其向量化后检索真实知识库。假设文档只是检索媒介，不能当作证据。它可与原问题的向量、关键词混合检索并行，再将本地结果去重和排名融合，结合网络搜索结果做统一重排。

按意图选择数据源

政策类问题适合文档混合检索，剩余假期等结构化业务问题适合受约束的数据查询，组织架构等关系问题适合图谱查询。路由、指代消解和查询改写帮助问题进入合适链路，而不是强迫所有问题使用同一种检索。

交互与评估

前端可通过带类型的流式事件呈现文本及工具状态，后端保持执行逻辑独立。评估数据集与人工抽检用于检验召回和回答质量，不能仅因增加多路召回便认定系统效果更好。