跳到主要内容

Pro版:工程化技术概括

说一个项目是企业级,肯定得看实际的工程质量。Nexus Agent Pro 在每一个工程细节上都对标真实生产系统的标准来做。从几个维度来评估

Pro 版全链路架构​

在拆解各项工程能力之前,先从全链路看 Nexus Agent Pro 是怎么运转的,流程图把 离线知识构建 和 在线问答执行 放在同一个架构视图中:文档先被解析并投影为多种可检索资产,用户问题再经过前置编排、五通道召回、融合精排和证据治理,最终由 LLM 基于受控证据生成答案并通过 SSE 返回。

Nexus Agent Pro 全链路动态架构流程图
  1. 文档解析与知识构建:文档上传归档后,系统根据策略创建异步任务,由 Python 完成智能解析并输出统一解析产物。Java 再依据文档语法树、来源区间和页码覆盖层进行投影与构建调度,形成文档结构树、表格结构、父子分块、PGVector 与 ES 索引、知识图谱和摘要树。
  2. 在线会话与前置编排:请求先经过业务网关、鉴权、知识范围校验和 Redis 会话租约,再装载滑动窗口、摘要记忆和上一轮证据锚点。查询理解、问题改写、子问题拆分、知识范围收缩和预算规划完成后,系统才决定进入检索问答、智能体执行还是信息澄清,而不是把原始问题直接交给模型。
  3. 检索与证据生成主链路:检索计划会并行调用向量、关键词、表格、知识图谱和摘要树五个通道,随后执行去重、通道加权、分数校准、上下文扩展和 BGE 交叉编码器精排。最终只有能够回到真实原文、满足问题支持度和覆盖约束的候选,才能进入提示词证据清单并参与回答生成和引用绑定。
  4. 共享工程底座:关系数据库、PGVector、ES、Neo4j、Redis、消息队列和 MinIO 分别承载业务状态、向量分块、关键词索引、图关系、租约进度、文档任务以及原件和解析产物;运营工作台、链路追踪和质量治理则贯穿路由、通道和执行阶段。
架构设计的核心

这条链路的重点不是简单地把更多数据库或模型拼在一起,而是让每个阶段都产生可验证、可追踪的结构化结果。Python 负责解析、精排、图算法和摘要等能力输出,Java 负责流程编排、结果校验、检索融合、证据决策和最终生成。即使某个工具服务降级,未经校验的结果也不会直接进入最终回答。

工程能力分层​

可以从能力分层的角度来看整体工程结构。更好地理解 前端层、接口与流式层、会话编排、检索与证据链、文档解析知识构建、Python 算法服务、存储与基础设施、平台服务、模型扩展设施,能直观看到 Nexus Agent Pro 的工程复杂度主要分布在哪些层面。

工程能力分层:super agent capacity pro

能看到每一层都有清晰职责:前端层负责用户交互和运营控制台,接口与流式层负责请求接入、鉴权、SSE 和任务中断,核心链路负责从记忆到检索再到生成的主流程,底层基础设施则支撑数据存储、异步处理、图谱导航、工具扩展和全链路观测。

Java + Python 混合架构

项目采用 Java 主链路 + Python 工具服务 的混合架构。Java 掌控 RAG 主链路的编排、检索融合、证据组织和回答生成;Python 作为无状态的工具服务,承接文档解析、交叉编码器精排、引用修复、知识图谱抽取、结构树构建这些 Java 不擅长的活。两者通过网络接口解耦,边界是"Python 出能力、Java 做决策"。这块的完整设计见下面的 Python 工具服务 一节。

工程规范​

  • 按能力拆分:应用入口、问答执行、文档知识构建、知识增强、Python 工具连接和模型服务连接各有明确归属,新增能力时更容易找到应该修改的位置
  • 协作方向清晰:问答、知识构建和知识增强只使用自己需要的能力,由应用入口统一把各部分连接起来,避免模块之间相互牵扯
  • 统一组装与启动:拆分后的 Java 模块仍由同一个后端应用统一配置和启动,既保留清晰边界,也不会增加不必要的部署负担
  • 外部连接集中管理:模型服务与 Python 工具服务分别由独立模块连接,超时、取消和调用失败在连接边界统一处理,不让这些细节散落到业务流程中
  • 公共能力按需复用:统一返回、异常处理、缓存、任务锁定、占用续期和唯一编号等能力集中封装,聊天与文档处理可以按需使用
  • 接口说明保持同步:接口说明跟随接口定义生成,便于调试和对接,也减少功能已经变化、说明还停留在旧版本的情况
分层架构详解

Nexus Agent Pro 按照每部分负责什么事情来组织工程。随着问答和知识处理能力增加,业务工程已经进一步拆成 6 个模块,分别承担应用入口、问答执行、文档知识构建、知识增强、Python 工具连接和模型服务连接。

  • 业务工程(nexus-agent-business):集中组织这 6 个模块。聊天模块负责接收请求、管理会话和接好各项能力;查资料与回答、处理文档、构建内容关系和分层摘要,则交给各自的模块。
  • 通用能力(nexus-agent-common):提供统一返回结果、异常处理、分页和数据处理等公共能力,减少各处重复编写相同逻辑。
  • 基础组件(nexus-agent-*-framework):提供缓存、任务锁定、任务占用续期、延迟处理和唯一编号等支撑,供聊天与文档处理共同使用。
  • Python 工具服务(nexus-agent-rag-tools):独立运行,提供文档解析、材料相关程度打分、内容关系抽取和分层摘要构建等能力。Java 负责决定查哪些资料、采用哪些依据以及怎样组织回答。

这样的拆分让小伙伴更容易顺着业务找到对应部分:调整文档处理方式,重点看知识构建模块;改进查资料和回答的过程,重点看问答执行模块;处理模型连接,则集中在模型服务连接模块。各部分通过约定好的接口配合,减少一次改动需要同时理解的内容。

这里的 Java 模块拆分属于同一个后端应用内部的职责划分,由聊天模块统一组装和启动,并不需要把这 6 个模块分别部署成 6 个服务。

分层架构的模块职责​

业务工程中的 6 个模块分别负责:

模块负责什么主要内容
nexus-agent-business-chat应用入口与业务组织接收聊天和管理请求,处理身份校验、会话与记忆、对话记录,并连接各模块、统一启动应用
nexus-agent-rag-runtime问答执行理解问题、确定可用资料范围、从多种途径查找资料、筛选回答依据、组织答案与引用,以及安排工具调用
nexus-agent-knowledge-indexing文档知识构建管理文档处理任务,组织解析与内容切分,保存章节、表格等结构,并建立用于查找资料的数据
nexus-agent-knowledge-augmentation知识增强从已有文档内容中构建关系网络和分层摘要,检查构建结果,并为问答提供相应的查找能力
nexus-agent-rag-tools-http连接 Python 工具服务将处理请求交给 Python 工具,接收结果,统一处理连接超时和调用错误
nexus-agent-model-http连接模型服务发送对话请求、接收逐步生成的回答,将文本转换为便于按含义查找的数据,并处理连接、取消和错误

这些业务模块共同使用的通用能力、基础组件,以及独立的 Python 工具服务如下:

模块或模块组负责什么主要内容
nexus-agent-common-frame通用基础约定统一返回结果、异常处理、公共状态与工具
nexus-agent-common-web通用应用支持分页、数据字段自动填充、日期与数据格式处理、接口文档支持
nexus-agent-id-generator-framework生成唯一编号为多实例运行下的业务记录生成唯一编号
nexus-agent-redis-tool-framework通用缓存操作统一缓存读写和缓存名称管理
nexus-agent-redisson-framework多实例任务协作任务锁定、占用续期、延迟队列和重复执行限制
nexus-agent-rag-toolsPython 工具能力执行文档解析、材料相关程度打分、内容关系抽取和分层摘要构建

其中,连接模块负责把请求送出去、把结果接回来,业务模块负责决定这些结果怎样使用。例如,Python 可以给候选材料打分,但哪些材料最终用于回答、答案引用哪些原文,仍由 Java 问答流程决定。

Python 工具服务​

前面反复提到 Python 工具服务,这里集中讲清楚它到底管哪些活、边界怎么划。它是一个 纯工具服务,Java 依然牢牢掌控整条 Agent 主链路(编排、检索融合、证据组织、回答生成、引用发送),Python 只承接那些 Java 不擅长的活:文档解析、模型推理(交叉编码器打分)、图算法和摘要聚类。

它对外提供一个健康检查加五项核心能力:

能力作用
健康检查返回模型和解析器的可用状态,供启动探活
文档解析把各种格式的文档解析成结构化内容(唯一解析入口)
精排交叉编码器重排,给候选证据打相关性分(唯一精排通道)
引用修复把答案句和候选证据做语义匹配,校准引用
图谱抽取从文本块里抽实体、关系、社区候选
结构树构建对内容层次聚类、逐层摘要,建成摘要树

Java 侧所有调用统一走一个封装好的客户端,服务地址和各接口超时都在配置里(文档解析这种耗时长的,超时给得比较宽)。

文档解析:云端解析 + 本地解析分流​

文档解析只有一个入口,入口内部按文件类型自动分流,不给用户提供切换开关:

文件类型解析方式说明
TXT / MD / HTML本地解析确定性的结构解析,不依赖任何云服务密钥
PDF / DOCX / XLSX / 图片COR服务大模型文档解析:文字识别、版面分析、阅读顺序、复杂表格、图片结构
DOC / XLS转换先转成 DOCX / XLSX 再解析

本地解析适合 Markdown 标题、纯文本段落和简单网页,输出稳定。OCR 则处理真正复杂的文档,把文字识别、版面、阅读顺序、表格、图片的结果统一整理成结构化内容块,并保存原始解析产物、页面图片、表格图片等,方便管理端查看和位置标注。解析结果会返回纯文本、各类产物、结构化内容块和结构节点,Java 拿到后负责保存产物、生成父块/子块、写各类索引。

职责边界:Python 出能力,Java 做决策​

环节Python 工具服务负责Java 主链路负责
文档解析文字识别、版面、表格/图片抽取,产出结构化内容保存产物、生成父块/子块、写索引
精排交叉编码器打分决定候选池、何时精排、结果怎么用
引用修复答案句 ↔ 证据的语义匹配决定何时调用、怎么过滤引用、发前端、归档
知识图谱实体/关系/证据候选抽取、社区发现同义实体合并、校验、入库、翻译成检索单元、打分
结构树聚类、大模型摘要、质量信号质量过滤、保存节点、写摘要索引
路由 / 融合 / 最终证据 / 引用决策❌ 不参与✅ 完全由 Java 掌控

最后一行最重要:路由、融合、最终证据选择、引用决策这些"拿主意"的环节,Python 是不管的。 Python 给的永远是"候选"和"打分",Java 拿到之后校验、筛选、组织,才形成最终结果。这样即便 Python 服务出问题、或返回了不靠谱的东西,也进不了主链路的最终决策。图谱抽取、结构树构建这两块的详细设计,见 知识图谱与结构树;精排、引用修复在检索链路里的位置,见 多通道混合检索。

下面这张管理端截图对应的正是这条离线知识构建链路。顶部列出了原始文档、解析块、父级块、检索子块、图谱证据和分层摘要等产物类型及数量;下方的结构链路把一个解析块的上游原文与下游产物串起来。通过这种产物视图,运营人员既能检查解析任务是否生成完整,也能沿关系回溯检索索引和最终引用的来源。

管理端文档解析产物视图:原始文档、解析块、父子块与下游知识产物

图:文档解析产物与下游知识资产的结构链路,体现解析、切块、索引和引用之间的工程化追踪关系。

集群安全与并发控制​

这是很多 Agent 项目完全忽略的部分,但在生产环境中至关重要。一个 AI 对话系统如果不做并发控制,很容易出现同一条消息被多个实例重复处理、长对话锁超时被其他实例抢占等问题。

  • Redis 租约互斥:RedisLeaseManager 实现集群级别的会话锁定,防止同一条消息被多个实例重复处理
  • JVM 级任务注册:ChatRuntimeRegistry 维护进程内的任务注册表,防止同进程重入
  • 租约续期:执行过程中自动续期,防止长对话超时导致锁释放后被其他实例抢占
  • 优雅降级:无论成功还是失败,统一触发清理流程,不会留下孤儿锁
为什么需要两层锁

只用 Redis 分布式锁能防止跨实例重复处理,但不能防止同一个 JVM 内的并发重入。只用 JVM 级锁能防止进程内重入,但不能防止集群间的重复。两层锁配合使用,才能在分布式环境下做到万无一失。

并发控制的完整生命周期​

一次对话请求的并发控制流程如下:

  1. 请求进入:先在注册 JVM 级任务,防止同进程重入
  2. 获取租约:通过获取集群级分布式租约,防止跨实例重复处理
  3. 自动续期:对话执行过程中,后台线程自动续期租约,防止长对话超时
  4. 执行完毕:主动释放 Redis 租约 + 注销 JVM 任务注册
  5. 异常保护:任何环节出现异常,统一触发清理,不产生死锁

这套机制确保了在多实例部署的生产环境中,每条消息都只会被一个实例处理一次,即使实例宕机或重启也不会出现数据不一致。

设计模式实战​

项目中落地了多种经典设计模式,不是为了用模式而用,每个都解决了实际的扩展性或解耦问题:

设计模式应用场景解决的问题
策略模式三种会话记忆策略、多种切块策略不同策略可插拔替换,新增策略不改已有代码
工厂模式检索通道创建、切块器创建复杂对象的创建逻辑集中管理
模板方法文档处理流水线各节点统一执行流程,子类只关注核心逻辑
责任链模式RAG 前置编排器的五步决策链多个处理步骤按顺序串联,灵活组合
观察者模式SSE 流式输出回调流式事件的异步通知与推送
适配器 / 门面用一个客户端封装 Python 工具服务屏蔽外部服务细节,统一调用入口
AOP重复执行限制、全局异常拦截、全链路 Trace横切关注点与业务代码解耦

设计模式的具体落地细节​

策略模式在会话记忆中的应用

会话记忆模块定义了统一的策略接口,三种实现(无记忆、滑动窗口、摘要压缩)各自独立。系统通过配置项决定使用哪种策略,运行时通过工厂方法获取对应实现。如果未来需要新增一种记忆策略(比如基于 RAG 的长期记忆),只需要新增一个实现类,不需要修改任何已有代码。这就是开闭原则在实际项目中的落地。

责任链模式在前置编排器中的应用尤为典型。五步决策链(路由判定 → 问题改写 → 歧义检测 → 子问题拆分 → 知识域收缩)的每一步都是一个独立的处理节点,节点之间通过链式调用串联。这种设计使得:

  • 每个节点可以独立开发和测试
  • 可以灵活调整节点的执行顺序
  • 可以按需跳过某些节点(比如简单问题不需要子问题拆分)
  • 新增决策步骤只需要加一个节点,不影响已有流程

模板方法在文档处理中的应用同样精巧。文档处理流水线的每个阶段(解析、策略推荐、切块、向量化、索引构建)都遵循统一的模板:前置检查 → 核心逻辑 → 状态更新 → 日志记录。子类只需要实现核心逻辑部分,其他环节由模板统一处理,确保了整个流水线的一致性和可追踪性。

可扩展性​

核心模块都预留了扩展点,这是企业级项目和 Demo 项目最本质的区别:

  • 新增检索通道:实现 RetrievalChannel 接口,注册为 Spring Bean,自动参与多通道混合检索和加权融合
  • 新增切块策略:实现切块策略接口,可加入 Parent/Child 组合流水线的任意位置
  • 新增记忆策略:实现记忆策略接口,系统自动识别并可配置使用
  • 新增工具调用:给 ReactAgent 注册新的 Tool,自动参与工具选择
  • 新增 MCP Server:部署符合 MCP 协议的 Server,Agent 自动发现并注册
  • 新增 Skill:在 Skills 目录下放入 SKILL.md 配置文件,零配置即刻生效

不需要改框架代码,加个实现类或配置文件就完事了。这才是面向接口编程和插件化架构的正确打开方式。

可扩展性设计的核心思想

Nexus Agent Pro 的可扩展性不是"留了几个接口"这么简单,而是贯穿整个系统的依赖倒置原则——核心逻辑依赖抽象而非具体实现。检索引擎不关心具体有几个通道、每个通道怎么实现,它只关心"通道接口"。切块引擎不关心具体有几种策略,它只关心"策略接口"。这种设计使得系统可以在不修改核心代码的前提下,持续扩展新能力。

扩展点的完整清单​

扩展点接口 / 协议扩展方式生效方式
检索通道RetrievalChannel 接口新增 Spring Bean自动参与多通道融合
切块策略切块策略接口新增实现类加入 Parent/Child 流水线
记忆策略记忆策略接口新增实现类配置切换
Agent 工具Tool 注册注册新 Tool自动参与工具选择
MCP 工具MCP 协议部署 MCP ServerAgent 自动发现
Skills 能力SKILL.md放入目录零配置生效
Python 工具能力网络接口Python 侧新增接口 + Java 侧客户端Java 主链路调用

全链路可观测​

项目中可以对全链路进行追踪,每个环节的耗时、输入输出、决策结果都有记录。思考过程、检索通道使用情况、证据来源、工具调用记录。

全部可视化呈现在管理后台的观测面板中。出了问题不用猜,直接看链路调用图就知道哪一步出了问题。

可观测的具体维度​

观测维度记录内容用途
编排决策路由结果、改写前后对比、子问题列表分析编排逻辑是否合理
检索过程各通道命中数、分数分布、融合结果优化检索参数
证据评估证据数量、质量评分、预算使用情况调整证据阈值
模型调用输入 Token 数、输出 Token 数、响应延迟成本分析和性能优化
工具调用调用次数、成功率、平均耗时工具可靠性监控
端到端延迟各阶段耗时、总延迟性能瓶颈定位
可观测性的实际价值

在生产环境中,用户反馈"回答不准确"或"响应太慢"时,传统做法是翻日志、加断点、猜测问题。有了全链路追踪后,可以直接打开观测面板,看到这次请求的完整链路:编排器判断走了哪个分支、检索了哪些文档、证据评分是多少、模型用了多少 Token。问题根因一目了然,大幅缩短排查时间。

和其他普通的 Agent 项目有什么区别​

市面上大多数 Agent 项目,说白了就是跑通一个示例就完事了。Nexus Agent Pro 和这些项目的差距在哪?直接对比一下:

对比维度普通 RAG 项目Nexus Agent Pro
检索方式单路向量检索多通道并行(向量 + 关键词 + 表格 + 知识图谱 + 结构树)+ 加权融合 + 交叉编码器精排
问题处理原始问题直接检索改写 + 子问题拆分 + 知识域收缩
意图判断无前置编排器五步决策 + 查询理解意图识别 + 歧义主动追问
执行策略所有问题走同一个模型三层执行器按场景分流(追问 / 知识问答 / Agent)
会话记忆全量塞给模型或不带无记忆 / 滑动窗口 / 摘要压缩三种策略
文档解析拍平成纯文本Python + OCR 识别,产出结构化内容块/表格/位置坐标
文档切块固定长度一刀切基于结构化内容块的父块/子块切分 + 策略推荐
文档入库同步处理,无日志Kafka 异步流水线 + 12 阶段任务日志
Agent 能力无或仅简单对话ReAct 循环 + 联网搜索 + 工具调用 + 检查端点持久化
证据控制无预算裁剪 + 无证据短路 + 引用修复
检索粒度命中什么用什么父子块块聚合,检索用小块、回答用大块
关系类问题搞不定知识图谱检索(实体/关系/社区/跨文档)
全局总结局部片段拼不出全局结构树(层级摘要),先召回摘要再下钻原文
表格问答拍平成文本丢结构结构化行列单元格 + 受控查询计划 + 单元格级高亮
流式输出简单 SSE 推文本正文 + 引用来源 + 推荐追问 + 停止生成
Agent 安全无限制模型调用次数 Hook + 工具调用次数 Hook + 重试兜底
MCP 协议无或硬编码 Function CallMCP 标准协议 + 动态发现 + 多工具编排 + 安全沙箱
能力扩展固定能力,改代码才能加Skills 声明式定义 + 自动加载 + 热插拔扩展
集群安全单机运行分布式租约互斥 + 进行任务注册 + 租约续期
可观测性无全链路追踪 + 可视化观测面板
知识路由无,全库检索三级漏斗(领域 → 主题 → 文档)+ 混合打分自动锁定文档
文档结构无图数据库构建 + 向量数据库 + 知识图谱 + 结构树
路由质量观测无影子路由静默对比 + 命中率追踪 + 持续优化闭环
工具服务全塞在一个进程主链路编排 + Python 工具服务出力,职责边界清晰
面试小贴士

在面试中聊项目对比时,不要只列功能差异,更要讲清楚"为什么要这么做"。比如不是简单说"我们用了多通道检索",而是说"纯向量检索对精确匹配天然弱势,用户问一个订单号向量检索完全找不到,所以我们加了关键词通道;表格统计、实体关系、全局总结又各有短板,所以又补了表格、知识图谱、结构树通道,最后按检索意图动态加权融合再交叉编码器精排"。讲清楚问题 → 方案 → 权衡,比列功能清单有说服力得多。

技术选型背后的考量​

每个技术的选型都不是随意的,背后都有明确的工程考量:

为什么选 PGVector + Elasticsearch 双引擎,而不是只用一个?

向量数据库擅长语义理解但对精确匹配弱,倒排索引擅长精确匹配但缺乏语义理解能力。两者互补才能覆盖用户检索的所有场景。PGVector 的优势是和 PostgreSQL 深度集成,既是关系型数据库又支持向量检索,运维成本低。Elasticsearch 则是倒排索引领域的工业标准,性能和功能都久经验证。

为什么用 Kafka 做异步解耦?

文档处理流水线是典型的长耗时任务(解析 → 切块 → 向量化 → 索引),如果同步处理用户要等很久。用 Kafka 做异步解耦后,上传操作秒级完成,后续处理在后台异步进行。同时 Kafka 提供了可靠的消息投递保证,即使处理实例宕机也不会丢失任务。

为什么选 Redisson 做分布式能力?

Redisson 不仅提供了分布式锁,还有完善的租约(Lease)机制、看门狗(Watchdog)自动续期、可重入锁等高级特性。在 Nexus Agent Pro 的集群并发控制场景中,这些能力都是必不可少的。相比直接用 Redis 命令手写分布式锁,Redisson 更安全、更稳定、经过了大量生产环境的验证。

为什么要单独拆一个 Python 工具服务?

Java 在 Web、并发、企业级工程上很强,但复杂 PDF 的文字识别与版面解析、交叉编码器精排、图算法、层次聚类这些活,最成熟的工具链都在 Python 生态。硬用 Java 造轮子成本高、质量还不一定好。所以把这几块拆成一个独立的 Python 服务,Java 通过网络接口调用。关键是边界清晰——Python 只出能力(解析、打分、抽取候选),不做任何决策;路由、融合、最终证据、引用决策全在 Java,Python 的产物都要过 Java 校验。这是"能力外包、但控制权收拢"的架构,也是很多真实企业 AI 系统的做法。详见上面的 Python 工具服务 一节。

为什么精排用本地的交叉编码器?

精排统一走 Python 工具服务里的交叉编码器模型。好处是模型可控、可预热、可缓存、可观测,出问题能明确报错而不是偷偷降级。交叉编码器把问题和候选拼在一起判断相关性,比"分别编码再算距离"的向量方式更准,适合在融合后的干净候选集上做精排。

总结​

Nexus Agent Pro 的工程化水平体现在方方面面:从分层架构的模块解耦,到集群环境下的并发安全;从设计模式的恰当运用,到全链路可观测的调试能力;从面向接口的扩展性设计,到每一个技术选型背后的工程权衡。

是一个你可以在面试中逐层展开、越聊越深的项目。 不管面试官从哪个角度切入——架构设计、并发控制、设计模式、技术选型——你都能给出有深度、有细节的回答。这才是"企业级"三个字真正的含义。

Nexus Agent Pro 项目的申请​

Nexus Agent Pro 项目是本人根据大厂的真实开发思路,花费了很多的精力和时间认真打磨出来的,也为了更好的保护已经加入星球的小伙伴的权益。所以决定 Nexus Agent Pro 不再进行开源,而是将项目放到了私有库中。

普通版本的 Nexus Agent 项目依然还是正常开源,本人也依然会继续进行优化。开源地址为: 👉 点击这里跳转到 Nexus Agent

已经加入星球的小伙伴,可以按照以下指示来申请和学习 Nexus Agent Pro:👉 点击这里学习 Nexus Agent Pro

🎁优惠