1. 一开场先把场景说清楚问数项目智能体到底解决什么问题做AI Agent开发最怕的就是一上来就聊框架、聊LangGraph、聊MCP结果连要解决什么问题都没想明白。我在做LCODER的“问数项目智能体”时第一步不是写代码而是把业务场景掰开揉碎。所谓“问数”就是让用户用自然语言直接向系统提问系统自动理解意图、查询数据库、返回结果全程不需要懂SQL也不需要知道表结构长什么样。这个需求在企业里太普遍了。业务部门想看本月销售额以往要么等数据组排期要么自己用Excel手工拼要么在BI工具里翻半天报表。而数据团队呢每天被几十个“这个数帮我拉一下”的需求淹没真正用来做深度分析的时间少得可怜。问数智能体要解决的就是这条“取数链路”的等待问题把SQL生成、数据查询、结果解读这三件事全部自动化。适合谁来参考这篇文章如果你正准备在公司内部落地一个“自然语言查数”的工具或者想系统了解一个企业级AI Agent从0到1的架构设计这篇就是按实战路子写的。本篇是第一篇只讲项目架构不会糊一脸代码先把骨架立住。我给的边界再明确一点这篇不谈模型微调不谈Prompt调参技巧重点放在架构分层、核心模块职责、以及“为什么这样设计”。后面几篇再逐个模块拆实现细节。2. 技术选型背后是三个硬约束2.1 先想清楚约束再谈选型AI Agent开发有一个很典型的误区看到别人用LangGraph就跟风用LangGraph看到Spring AI火就切Spring AI。我在LCODER这个项目里做选型第一件事是先列约束条件。第一个约束是团队现状。我们后端主力是Java服务端生态以Spring Boot为主如果强行引入一套Python技术栈的Agent框架运维、监控、人员学习成本都会翻倍。第二个约束是部署环境。企业内网部署为主不能完全依赖云端大模型API需要兼容私有化模型同时支持国内主流大模型厂商的接口。第三个约束是性能。问数场景的请求链路比普通对话长得多涉及意图识别、SQL生成、查询执行、结果解释多个环节任何一个环节超时都会让用户体验断崖式下跌。基于这三个约束我选型的结果是Agent编排层用LangGraph的思想但实现层根据团队情况选择Java生态或者Python异步服务均可关键在于“状态流转”和“节点编排”这两个抽象能力必须保留。模型接入层统一封装预留给多个模型服务商。数据执行层走JDBC/连接池不走任何中间代理。说到这里必须插一句如果你的数据量只有几百张表、查询模式极其固定那根本不需要Agent写几个预设SQL就能解决问题。问数项目做Agent化前提是“查询组合空间足够大无法穷举预设规则”。2.2 为什么编排比模型本身更决定成败很多团队做AI Agent时过分关注“用哪个大模型”却忽略了“Agent的决策路径是怎么设计的”。以问数项目为例一次完整的用户提问会依次经过意图识别、问题改写、Schema匹配、SQL生成、工具执行、结果总结。这个链条上任何一步出错结果都会跑偏。如果你只是把用户问题直接丢给大模型让它生成SQL这在简单场景下没问题但一旦涉及多表关联、过滤条件带权限、需要连续追问上下文时单次生成的质量会非常不稳定。所以架构上必须把步骤拆成独立的处理节点每个节点只做一件事节点之间通过可观测的消息流转连接。这正是LangGraph的StateGraph模型解决的问题——把“线性提示词调用”升级成“可控的状态机流转”。在对多个Agent框架的对比中我会看四点是否支持节点级重试、是否支持分支条件跳转、状态快照能否可观测、有没有内置的人工介入位点Human-in-the-loop。这四个点恰恰是LangGraph这类框架做得最成熟的也是从“玩具Demo”走向“生产可用”的分水岭。3. 四层架构拆解从入口到数据落地的完整闭环3.1 整体分层设计问数项目智能体总共分四层我画过很多次架构图最后稳定下来的结构是这样接入层对话/API入口、编排层Agent脑、执行层工具与数据、模型层LLM网关。每一层职责单一互相之间只通过接口通信不共享内部状态。接入层负责统一的对话入口和身份认证无论是Web端、IM机器人还是OpenAPI都走同一套协议。编排层是Agent的“大脑”接收结构化后的用户请求维护会话状态决定下一步调用哪个工具。执行层包含SQL查询工具、元数据获取工具、权限校验工具所有数据操作都被封装成Agent可调用的Tool。模型层则屏蔽不同大模型厂商的差异统一暴露Chat和Function Calling两套接口。这个分层的好处非常直接可替换性。模型层可以随时切换底层模型编排层的逻辑完全不用动执行层加一个新数据源也只需要注册一个新的Tool。对于企业内部项目来说这种“不被单一技术绑架”的能力太重要了。架构上还需要注意一点不要把所有逻辑塞进Agent编排层。很多做AI应用的人容易犯的错就是把语法校验、权限过滤、SQL合法性检查全部写在Agent的Prompt里导致模型负担过重。正确的做法是把这些逻辑下沉到执行层让Tool自己校验输入输出Agent只负责“做决策”不负责“做脏活”。3.2 单Agent还是Multi-Agent问数场景怎么选当前AI Agent领域另一个热门话题是Multi-Agent协作Spring AI Multi-Agent、LangGraph多智能体协作都是社区讨论度很高的方向。但在问数项目里我的选择是“单Agent 多工具”而不是一开始就上多Agent。原因不复杂。多Agent意味着多个大模型实例协作每个实例都有独立的上下文窗口和决策路径协作粒度越细整体延迟越高、成本越大。问数场景本质上是“一个用户问题 → 一次或几次SQL查询 → 一个最终答案”决策链相对固定用单Agent处理意图分支、用多个工具完成数据操作已经覆盖了绝大多数情况。那Multi-Agent的用武之地在哪我觉得适合更复杂的场景比如同时询问销售趋势、库存情况、竞品动态需要多个专业Agent并行拉取不同域的数据再汇总分析。这种场景我会在第二期架构里引入协作模式但第一期的核心目标是把链路跑通不追求复杂的多角色协同。4. 从提问到出数一次“问数”的完整Agent内部工作流4.1 问数Agent的状态流转设计LangGraph的核心思想是StateGraph把Agent的一次处理过程定义为一个图节点是操作边是状态跳转条件。我在设计问数项目的Agent工作流时严格遵循了这个思路。整体流程分成五个核心节点IntentRouter、ProblemRewriter、SchemaMatcher、Text2SQL、ResultInterpreter。你可能会问这跟直接给大模型一段长Prompt让它输出SQL有什么区别区别在可控性。举例来说“上个月华东区各产品的退货率是多少”这句话直接生成SQL时模型很可能把“上个月”理解成自然月但业务上可能是指财月也可能把“华东区”匹配错字段。而拆成独立节点后IntentRouter负责识别这是“数据查询类意图”还是“闲聊类意图”SchemaMatcher负责从元数据里挑出与“华东区、退货率、产品”相关的表和字段Text2SQL只处理结构化的查询生成每个环节都有独立的日志和可干预点出错时一眼就能定位。这五步的状态流转用一张表就能看得很清楚节点输入输出失败分支IntentRouter用户原始问题 会话历史意图标签查数/闲聊/拒答非查数意图直接走闲聊回复ProblemRewriter原始问题 上下文改写后的查询问题信息不足时反问澄清SchemaMatcher改写问题 表结构元数据候选表和字段列表无匹配时返回“找不到对应数据”Text2SQL候选Schema 改写问题SQL语句生成失败则重试或降级ResultInterpreter查询结果 用户问题最终自然语言回答执行异常则返回错误信息4.2 MCP协议的地位工具调用的工程化标准说到工具调用就绕不开MCPModel Context Protocol。这个协议最近热度非常高本质上是给大模型提供了一个标准化的“工具插拔”接口让Agent不用关心每个工具背后的实现细节。在问数项目里SQL执行器、元数据读取器、权限校验器都会被封装成标准的MCP Server。我强烈建议做AI Agent开发的人尽早熟悉MCP这套规范。原因有两个一是标准化带来的可复用性同一个数据查询MCP Server今天在问数Agent里可以用明天在别的智能体里也能注册使用不需要重新开发二是生态效应MCP的Server和Client实现越来越多未来企业内部AI工具的互操作性大概率会以MCP为底座。但也要泼一盆冷水MCP解决了“工具怎么暴露”的问题解决不了“工具该不该被调用”的问题。真正的业务判断仍然集中在Agent编排层。所以架构上不要把MCP理解成“接入即智能”它只是让Agent多了一双手大脑还是编排层。4.3 超时与降级设计长链路调用最容易被忽视的坑一次问数请求的完整链路里最耗时的往往是大模型推理。如果再把“意图识别 Text2SQL 结果解释”串起来一次请求跑完可能要10到20秒这个延迟在企业内部机器人的使用场景里还能接受但在网页端交互里已经明显感觉到“卡”了。所以在架构设计时必须预设超时控制和降级通道。我从一开始就定了一条规则任何节点单次最长等待时间不超过8秒整条链路最长不超过30秒。超时后按优先级降级先尝试跳过结果解释节点直接返回表格数据仍然超时则返回“查询已提交请稍后查看历史记录”把同步问题转成异步处理。这个设计在初期看起来有点过度防御但我做过几个AI项目后可以负责任地说生产环境出问题的概率排序大概是超时 权限错误 SQL语法错误 模型生成质量问题。如果你的Agent架构里没有超时降级兜底上线第一周就会被用户投诉淹没。5. 权限与数据安全企业级问数绕不开的底线5.1 从“谁能问”到“能问什么”问数Agent一旦面向企业内部开放就不能只验证“这个人能不能用”还必须验证“这个人能看哪些数据”。最简单也最实用的方案是把权限校验做成Agent调用SQL执行器前的强制Tool。具体做法是接入层从SSO或统一身份中心拿到用户的组织角色和授权标签编排层把这个身份信息注入Agent的执行上下文。SQL执行器在执行前会检查目标表是否在当前用户的授权范围内并对SELECT语句做一次AST解析自动追加行级权限过滤条件。例如销售岗位的用户查“全国业绩”系统会在SQL后面自动拼接“WHERE region IN (当前用户的区域列表)”保证他只能看到自己区域的数。这里有个关键细节权限过滤必须下沉到Tool端不能依靠模型自觉。因为模型生成的SQL很可能漏掉过滤条件一旦执行层不做二次拦截数据越权就发生了。生产环境必须默认“执行层守最后一道门”而不是“信任模型每次都对”。5.2 查询审计与脱敏策略企业数据安全还有一个维度是“事后可追溯”。每次问数请求的全链路数据——原始问题、改写后的问题、生成的SQL、执行的表、返回行数、处理耗时——都需要落审计日志。我的做法是把这条审计链路做成异步的不阻塞主查询流程日志单独走一套持久化通道。这样即便数据库执行异常审计记录也已经存下来了。字段级脱敏同样前置到执行层。架构里设计了一个字段元数据配置表每张表的每个字段可以配置脱敏规则比如手机号掩码、金额四舍五入、身份证号只显示前后几位。SQL执行器拿到查询结果集后按照配置规则做统一脱敏再交给大模型做结果解释。每次都让模型自己判断哪些信息不能展示是绝对不靠谱的合规问题必须用代码保证。6. 落地节奏从MVP到大规模使用开发计划怎么排6.1 MVP边界划定与里程碑第一期的项目范围我建议用“单数据源、单轮查询、只读SQL”三个条件来收敛。不要一期就做多数据源联合查询也不要一上来就做多轮会话更不要开放写操作。这三个限制条件能极大降低初期的复杂度让团队聚焦在核心链路的稳定性上。下面是我给问数项目定的里程碑参考你可以按团队情况调整阶段周期核心交付验收标准架构与数据准备1-2周元数据采集、Schema获取、权限模型定义元数据覆盖率100%权限标签可配置Agent编排v12-3周Step1到Step5的最小链路跑通单轮问数端到端平均耗时低于20秒工具与执行层完善1-2周SQL执行器、脱敏、审计上线越权查询被拦截率达100%联调与体验优化2周真实业务场景测试、错误反馈闭环问数准确率回答与人工核对一致超过85%6.2 落地阶段最容易踩的三个坑第一个坑是元数据质量。Text2SQL的效果上限取决于你给模型的Schema信息有多准确。很多团队直接拿数据库的comment当字段描述结果“创建时间”“更新时间”这类无关字段全部注入模型不仅浪费token还增加误导。正确做法是维护一份人工审核过的语义层元数据只把最常用的字段和表暴露给模型。第二个坑是人机协作位。用户的问题经常是模糊的比如“看一下最近的数据”这个“最近”到底是指最近7天还是最近30天如果让模型猜答对的概率很低。所以架构上要有“追问澄清”的路径Agent在信息不足时必须反问而不是硬着头皮生成一个可能错误的SQL。这块能力建立在ProblemRewriter节点的设计深度上值得多花时间。第三个坑是回归测试的缺失。问数Agent不是“写完SQL生成器就结束”的项目模型一更新、元数据一调整、权限规则一变化都可能引入新的问题。我从一开始就在项目计划里加入了“问数回归集”的概念——维护200到300条典型问题和对应的正确SQL作为基准测试集每次改动都跑一遍用准确率来防止“修一个bug引出三个bug”。这个习惯花不了太多成本但对项目长期维护的帮助非常大。关于权限过滤再补充一点实测心得直接用字符串拼接的方式给SQL加过滤条件大概率会翻车。SQL的写法太灵活了子查询、JOIN、UNION都可能绕过简单拼接。目前比较可靠的做法是引入SQL语法解析库把模型生成的语句解析成AST然后在AST层面修改WHERE节点重新生成SQL。这个方案能覆盖绝大多数复杂查询。关于“问数Agent是不是伪需求”的实战总结很多技术圈的人会争论问数Agent是不是一个“看起来很美好实际用不起来”的伪需求。我在做LCODER这个项目的过程中最大的体会是问数Agent真正难的地方从来不是大模型生成SQL的能力而是工程架构能不能兜住“不可控”这件事。模型可能写错SQL可能选错字段可能漏掉过滤条件这些都不是靠换一个更强的模型就能根治的必须靠节点化的编排、工具层的二次校验、完善的审计机制来兜底。我个人目前最看重的一个架构决策就是把“决策”和“执行”严格分离。Agent负责判断用户想要什么、需要调用哪个工具、怎么把结果讲得让用户听得懂而工具层负责保证每一次数据访问都干净、安全、可追踪。只要这个原则不被破坏后面无论换模型、加数据源还是升级Multi-Agent协作都不会出现推倒重来的情况。这一篇的项目架构先讲到这里下一篇我准备把Text2SQL节点单独拉出来写一篇重点讲Schema注入之后怎么控制Token消耗、如何让模型输出符合数据库方言的SQL、以及回归测试集具体怎么搭建感兴趣的话可以继续跟。
