1. 为什么 Data Agent 的技术栈值得单独拿出来聊Data Agent 这个词在 2025 年下半年开始被频繁提及到 2026 年已经从一个模糊的概念演变成了企业级数据平台的核心组件。我所在的团队从 2024 年底就开始跟踪这个方向先后调研了市面上十几款声称自己是 Data Agent 的产品也自己动手搭过几套原型。说实话市面上真正能跑通“从自然语言到数据洞察”这条链路的方案并不多大部分产品在演示环境里表现惊艳一放到真实的数据仓库上就露馅。Data Agent 本质上是一个能理解自然语言、自主规划数据操作步骤、调用工具执行查询、并对结果进行解释和可视化的智能体。它和传统的 BI 工具最大的区别在于BI 是“人找数据”Data Agent 是“数据找人”。你不需要知道数据存在哪张表、字段叫什么、用什么 SQL 方言只需要用日常语言描述你想知道什么它就能帮你把整条链路跑通。这个方向之所以在 2026 年突然火起来核心原因是三个条件同时成熟了大模型的代码生成能力足够可靠、数据平台的元数据治理足够完善、流式输出技术让交互体验足够流畅。但这也意味着Data Agent 的技术栈横跨了多个领域——大模型应用开发、数据工程、前端交互、后端架构每一层都有坑。这篇文章适合三类人看正在选型 Data Agent 平台的技术负责人、准备自己搭建 Data Agent 原型的开发工程师、以及想了解这个方向技术全貌的产品经理。我会从技术栈的每一层拆开讲结合我们实际调研和实操的经验把选型逻辑、架构设计、关键实现细节和踩过的坑都摊开来说。2. Data Agent 的核心技术栈拆解2.1 大模型层不是越强越好而是越合适越好Data Agent 的大脑是大模型但选型逻辑和做聊天机器人完全不同。聊天机器人可以容忍一定的模糊性但 Data Agent 生成的 SQL 一旦有语法错误或者逻辑偏差整个查询结果就是错的。我们实测下来在 Text-to-SQL 这个任务上不同模型的表现差距非常大。目前市面上主流的选型分三个梯队。第一梯队是 GPT-4 系列和 Claude 3.5 Sonnet在复杂 SQL 生成任务上的准确率明显领先但成本和数据合规是问题。第二梯队是国内的 DeepSeek-V3 和 Qwen2.5-72B在中文语境下的表名、字段名理解上有天然优势而且可以私有化部署。第三梯队是一些专门微调过的 SQL 生成模型比如 SQLCoder 系列在特定数据集上表现不错但泛化能力有限。我们内部做过一个测试用同样的 200 条自然语言查询在同一个数据仓库上跑。GPT-4 的首次生成准确率大约是 78%DeepSeek-V3 是 72%Qwen2.5-72B 是 69%。但加上一轮自动纠错之后DeepSeek-V3 能到 89%和 GPT-4 的 91% 差距很小了。考虑到私有化部署的成本优势我们最终在原型里选了 DeepSeek-V3。注意不要迷信榜单上的 Text-to-SQL 准确率。那些测试集通常是干净的、结构良好的数据库而真实企业环境里的表名可能是t_ord_mst_2024这种字段名可能是amt_1、amt_2。模型对业务语义的理解能力比单纯的 SQL 语法能力更重要。2.2 编排层Agent 框架的选择决定了扩展性Data Agent 不是一次性的问答而是一个多步骤的规划-执行-反思循环。编排层负责管理这个循环决定什么时候调用什么工具、什么时候需要向用户澄清、什么时候可以给出最终答案。目前主流的编排框架有 LangChain、LlamaIndex、AutoGen 和 Semantic Kernel。我们全都试过一遍最后在原型里用的是 LangGraph。原因很简单Data Agent 的执行流程是一个有状态的图而不是一条直线。用户问“上个月销售额下降的原因是什么”Agent 可能需要先查销售额、再查各区域明细、再查促销活动记录、最后做归因分析。这个过程中每一步的输出都会影响下一步的决策LangGraph 的状态管理和条件边机制天然适合这种场景。LangChain 的 AgentExecutor 更适合简单的工具调用场景一旦步骤超过五步调试起来非常痛苦。LlamaIndex 在 RAG 场景下很强但它的 Agent 编排能力相对弱一些。AutoGen 的多 Agent 协作模式很优雅但引入多个 Agent 之后Token 消耗和延迟都会成倍增加对于 Data Agent 这种需要快速响应的场景不太合适。编排层还有一个关键决策是让模型自由规划还是给它一个预设的流程模板。我们试过完全自由的 ReAct 模式结果模型经常陷入“查了又查”的死循环。后来改成“半自由”模式——给模型一个粗粒度的流程框架理解意图→定位数据→生成查询→执行→解释但在每个步骤内部允许它自由选择工具和参数。这样既保证了可控性又保留了灵活性。2.3 数据访问层元数据治理是成败的关键Data Agent 能不能用好很大程度上取决于元数据的质量。模型再强如果它不知道t_ord_mst是订单主表、amt_1是含税金额那它生成的 SQL 就是瞎猜。我们在调研中发现很多企业兴冲冲地上了 Data Agent结果发现模型根本找不到正确的表。原因不是模型不行而是元数据太烂。表没有注释、字段没有说明、表之间的关系没有定义。这种情况下再强的模型也白搭。所以数据访问层的核心不是数据库连接池而是元数据服务。我们建议至少要做好三件事第一给所有核心表加上业务含义清晰的注释第二建立字段级别的同义词映射比如“销售额”“营收”“收入”都映射到同一个字段第三定义表之间的外键关系和常见的 Join 路径。这三件事做完Text-to-SQL 的准确率能提升 20 个百分点以上。数据访问层的另一个关键是查询执行的安全控制。Data Agent 生成的 SQL 必须经过审核才能执行否则一个DELETE或者UPDATE就可能造成生产事故。我们的做法是在执行前加一层 SQL 解析器只允许SELECT语句通过并且对查询的行数和执行时间做限制。2.4 交互层SSE 流式输出是体验的分水岭Data Agent 的响应时间通常在 3 到 15 秒之间取决于查询的复杂度和数据量。如果让用户盯着一个 loading 图标等十几秒体验会非常糟糕。SSEServer-Sent Events流式输出是解决这个问题的标准方案。SSE 的核心思路是后端不等整个回答生成完再返回而是每生成一个 Token 就推送给前端前端实时渲染。这样用户能看到 Agent 在“思考”的过程——先显示“正在理解你的问题”再显示“正在查找相关数据表”再显示“正在生成查询语句”最后才显示结果。这种渐进式的反馈让等待变得可以接受。实现 SSE 的时候有几个坑要注意。第一SSE 连接是单向的只能服务器推送给客户端如果用户想中途取消查询需要另外发一个 HTTP 请求来触发 abort。第二SSE 连接在 Nginx 后面默认会被缓冲需要设置proxy_buffering off和X-Accel-Buffering: no。第三如果 Agent 的执行过程中有多个步骤每个步骤的输出要打上类型标记前端才能区分哪些是思考过程、哪些是最终结果。我们实测下来加上 SSE 流式输出之后用户感知的等待时间从平均 8 秒降到了 3 秒左右。虽然实际执行时间没变但体验完全不一样了。2.5 前端渲染层不只是聊天窗口Data Agent 的前端不只是个聊天窗口。它需要渲染表格、图表、SQL 代码块、执行计划等多种内容类型。我们调研了市面上几款产品发现前端体验做得好的通常都有一套专门的内容渲染协议。我们的做法是定义一套 JSON Schema后端返回的每个消息块都带有type字段前端根据type决定用什么组件渲染。比如type: table就用表格组件type: chart就用 ECharts 渲染type: sql就用代码高亮组件。这样后端不需要关心前端怎么渲染前端也不需要理解后端的业务逻辑。图表渲染这块有个细节Data Agent 返回的数据通常是二维表结构但用户可能想要柱状图、折线图、饼图等不同形式。我们的做法是让模型在返回数据的同时也返回一个推荐的图表类型和维度映射前端根据这个推荐来渲染。用户也可以手动切换图表类型前端重新渲染即可不需要再请求后端。3. 技术架构的三种典型模式3.1 单体架构适合快速验证最简单的 Data Agent 架构就是一个单体服务里面包含了模型调用、编排逻辑、数据访问和 API 接口。这种架构的好处是部署简单、调试方便适合在概念验证阶段使用。我们最早的原型就是一个 Python FastAPI 服务里面直接调 LangGraph、直接连数据库、直接返回 SSE 流。整个服务不到 2000 行代码但已经能跑通“自然语言→SQL→结果→图表”的完整链路。这个阶段最重要的是验证核心可行性不要过早考虑扩展性和高可用。单体架构的瓶颈也很明显。模型调用是 IO 密集型的数据库查询也是 IO 密集型的如果并发请求多了一个慢查询就会阻塞整个服务。所以单体架构只适合内部试用不适合直接上生产。3.2 微服务架构适合企业级部署当 Data Agent 需要服务多个部门、接入多个数据源的时候微服务架构就更合适了。我们调研的一家金融企业他们的 Data Agent 平台拆成了五个服务对话服务、编排服务、元数据服务、查询执行服务、结果渲染服务。对话服务负责和前端交互管理会话状态和 SSE 连接。编排服务负责调用大模型、管理 Agent 执行流程。元数据服务负责维护表结构、字段说明、同义词映射。查询执行服务负责 SQL 审核、执行和结果缓存。结果渲染服务负责把查询结果转换成图表配置。这种拆法的好处是每个服务可以独立扩展。比如编排服务是 CPU 密集型的可以多部署几个实例查询执行服务是 IO 密集型的可以配置连接池和缓存。但代价是运维复杂度上升服务之间的通信延迟也会增加。3.3 事件驱动架构适合高并发场景如果 Data Agent 需要支持大量并发用户事件驱动架构是更好的选择。用户发起查询后请求被放入消息队列后台的工作进程从队列中取出任务并执行执行结果通过 SSE 或 WebSocket 推送给用户。这种架构的好处是天然支持异步和削峰填谷。用户不需要等待查询完成可以关闭页面稍后再来看结果。但缺点是交互体验会打折扣因为用户看不到实时的执行过程。我们实测下来对于大多数企业内部的 Data Agent 场景微服务架构已经足够。事件驱动架构更适合面向外部用户的 SaaS 产品内部工具没必要上这么复杂的架构。4. 实操从零搭建一个 Data Agent 原型4.1 环境准备与依赖安装我们以 Python 技术栈为例搭建一个最小可用的 Data Agent 原型。需要准备的东西包括一个能调用大模型的 API Key、一个测试用的数据库SQLite 就够了、Python 3.10 以上的运行环境。核心依赖包括langgraph用于编排 Agent 流程langchain-community用于数据库连接和工具封装fastapi和uvicorn用于提供 HTTP 接口和 SSE 流式输出sqlalchemy用于数据库操作sse-starlette用于简化 SSE 的实现。pip install langgraph langchain-community fastapi uvicorn sqlalchemy sse-starlette openai数据库我们用 SQLite 建两张测试表一张订单表orders包含订单 ID、客户 ID、金额、日期一张客户表customers包含客户 ID、名称、地区。建表语句和示例数据可以直接用 SQL 脚本生成。4.2 元数据服务的搭建元数据服务是 Data Agent 的“地图”。我们用一个简单的 JSON 文件来存储元数据包含每张表的名称、业务描述、字段列表和字段说明。metadata { orders: { description: 订单主表记录所有订单信息, columns: { order_id: 订单唯一标识, customer_id: 客户ID关联customers表, amount: 订单金额单位元, order_date: 下单日期格式YYYY-MM-DD } }, customers: { description: 客户信息表, columns: { customer_id: 客户唯一标识, name: 客户名称, region: 客户所在地区 } } }这个元数据会在生成 SQL 的时候作为上下文传给模型。实测下来加上元数据之后模型生成的 SQL 准确率明显提升尤其是涉及多表 Join 的查询。4.3 Agent 编排逻辑的实现Agent 的核心是一个状态图包含四个节点理解意图、生成 SQL、执行查询、解释结果。每个节点都是一个函数接收当前状态并返回更新后的状态。from langgraph.graph import StateGraph, END from typing import TypedDict class AgentState(TypedDict): question: str sql: str result: list explanation: str def understand_intent(state): # 调用模型理解用户意图确定需要查询哪些表 return {question: state[question]} def generate_sql(state): # 调用模型生成 SQL传入元数据作为上下文 return {sql: SELECT ...} def execute_query(state): # 执行 SQL 并返回结果 return {result: [...]} def explain_result(state): # 调用模型解释查询结果 return {explanation: ...} graph StateGraph(AgentState) graph.add_node(understand, understand_intent) graph.add_node(generate, generate_sql) graph.add_node(execute, execute_query) graph.add_node(explain, explain_result) graph.set_entry_point(understand) graph.add_edge(understand, generate) graph.add_edge(generate, execute) graph.add_edge(execute, explain) graph.add_edge(explain, END) app graph.compile()这个流程看起来简单但每个节点内部的 Prompt 设计才是关键。比如生成 SQL 的 Prompt 需要包含数据库的元数据、用户的问题、SQL 方言的说明、以及一些 Few-shot 示例。我们试过不加 Few-shot准确率会下降 10% 左右。4.4 SSE 流式输出的实现SSE 的实现用sse-starlette的EventSourceResponse它封装了 SSE 的协议细节用起来很简单。from sse_starlette.sse import EventSourceResponse from fastapi import FastAPI app FastAPI() app.get(/query) async def query(question: str): async def event_generator(): yield {event: thinking, data: 正在理解你的问题...} # 执行 Agent 流程 result await run_agent(question) yield {event: sql, data: result[sql]} yield {event: result, data: json.dumps(result[result])} yield {event: explanation, data: result[explanation]} return EventSourceResponse(event_generator())前端用EventSource接收事件根据event类型决定渲染方式。这里有个细节EventSource默认只支持 GET 请求如果查询参数很长可能会超出 URL 长度限制。我们的做法是先用 POST 创建一个会话拿到 session_id然后用 GET 请求 SSE 流通过 session_id 关联查询。4.5 前端渲染与交互前端我们用的是 React 加 ECharts。核心逻辑是监听 SSE 事件把不同的事件类型渲染成不同的组件。const eventSource new EventSource(/query?session_id${sessionId}); eventSource.addEventListener(thinking, (e) { setThinking(e.data); }); eventSource.addEventListener(sql, (e) { setSql(e.data); }); eventSource.addEventListener(result, (e) { const data JSON.parse(e.data); setTableData(data); // 根据数据自动推荐图表类型 const chartConfig recommendChart(data); setChartConfig(chartConfig); }); eventSource.addEventListener(explanation, (e) { setExplanation(e.data); eventSource.close(); });图表推荐逻辑很简单如果结果只有两列且其中一列是数值推荐柱状图如果结果包含日期列推荐折线图如果结果只有一列且是数值推荐饼图。这个逻辑用几十行代码就能实现但能大幅提升用户体验。5. 常见问题与排查技巧实录5.1 模型生成的 SQL 总是找不到正确的表这是最常见的问题根本原因通常是元数据质量不够。排查思路是先看模型生成的 SQL 里用了哪些表名再对比元数据里有没有这些表。如果模型用了不存在的表名说明元数据里的表名和模型理解的不一致。解决办法有两个一是在元数据里加上表名的同义词比如orders表加上“订单”“交易”“销售记录”等别名二是在 Prompt 里明确列出所有可用的表名让模型只能从这些表里选。我们实测下来第二种方法效果更直接。5.2 SSE 连接经常断开SSE 连接断开的原因通常有三个Nginx 的缓冲设置、连接超时时间、以及服务端的异常处理。首先检查 Nginx 配置确保proxy_buffering off和proxy_read_timeout设置足够长。其次在服务端加上心跳机制每隔 15 秒发送一个空事件保持连接活跃。最后在event_generator里加上 try-catch确保异常时能正常关闭连接。5.3 查询结果太大导致前端卡死Data Agent 生成的 SQL 如果没有加LIMIT可能会返回几十万行数据前端渲染直接卡死。解决办法是在查询执行层强制加上行数限制比如最多返回 1000 行。如果用户确实需要更多数据可以提供导出功能而不是在前端渲染。5.4 模型解释结果时出现幻觉模型在解释查询结果时可能会编造一些数据中不存在的信息。比如查询结果显示销售额下降了 10%模型可能会说“主要是因为华东地区促销活动减少”但数据里根本没有促销活动的信息。解决办法是在解释结果的 Prompt 里明确要求只能基于查询结果中的数据进行分析不能引入外部信息。5.5 多轮对话中上下文丢失Data Agent 通常需要支持多轮对话比如用户先问“上个月销售额是多少”再问“那前个月呢”。如果每次查询都是独立的模型就不知道“那前个月”指的是什么。解决办法是在会话状态里保存历史查询和结果每次生成 SQL 时把最近几轮的历史作为上下文传给模型。问题现象可能原因排查方法解决方案SQL 找不到表元数据缺失或表名不一致对比生成的 SQL 和元数据补充同义词映射Prompt 中列出可用表SSE 连接断开Nginx 缓冲或超时检查 Nginx 配置和服务端日志关闭缓冲加心跳设置超时前端卡死查询结果行数过多查看返回的数据量强制 LIMIT提供导出功能解释出现幻觉Prompt 约束不够检查解释结果的 Prompt明确要求只基于查询结果分析多轮对话丢失上下文会话状态未保存检查会话管理逻辑保存历史查询和结果传入上下文6. 选型建议与个人体会如果你正在选型 Data Agent 平台我的建议是先想清楚三个问题数据在哪里、用户是谁、并发量多大。数据在私有化环境里就必须选支持私有化部署的模型和框架。用户是业务人员前端体验就比技术指标更重要。并发量不大单体架构就够用没必要上微服务。我们团队在调研过程中最大的体会是Data Agent 的瓶颈往往不在模型而在数据治理。很多企业花了大价钱买模型、搭平台结果发现元数据一塌糊涂模型根本找不到正确的表。所以如果你准备启动 Data Agent 项目我建议先把元数据治理做好这比选什么模型重要得多。另一个体会是不要追求一步到位。我们最早想做一个全能的 Data Agent能查数据、能做分析、能生成报告。结果发现每个方向都做不深。后来聚焦在“自然语言查数据”这一个场景上反而做出了可用的产品。先解决一个具体问题再逐步扩展这个节奏更稳妥。最后分享一个实用技巧在 Prompt 里加上“如果用户的问题不够明确请先向用户澄清”这句话能大幅减少误查询。我们实测下来加上这句话之后因为理解偏差导致的错误查询减少了将近一半。用户一开始可能觉得多了一步确认有点麻烦但比起查错数据带来的误导这点麻烦是值得的。 Data Agent 技术栈全拆解：从大模型选型到 SSE 流式输出实战
1. 为什么 Data Agent 的技术栈值得单独拿出来聊Data Agent 这个词在 2025 年下半年开始被频繁提及到 2026 年已经从一个模糊的概念演变成了企业级数据平台的核心组件。我所在的团队从 2024 年底就开始跟踪这个方向先后调研了市面上十几款声称自己是 Data Agent 的产品也自己动手搭过几套原型。说实话市面上真正能跑通“从自然语言到数据洞察”这条链路的方案并不多大部分产品在演示环境里表现惊艳一放到真实的数据仓库上就露馅。Data Agent 本质上是一个能理解自然语言、自主规划数据操作步骤、调用工具执行查询、并对结果进行解释和可视化的智能体。它和传统的 BI 工具最大的区别在于BI 是“人找数据”Data Agent 是“数据找人”。你不需要知道数据存在哪张表、字段叫什么、用什么 SQL 方言只需要用日常语言描述你想知道什么它就能帮你把整条链路跑通。这个方向之所以在 2026 年突然火起来核心原因是三个条件同时成熟了大模型的代码生成能力足够可靠、数据平台的元数据治理足够完善、流式输出技术让交互体验足够流畅。但这也意味着Data Agent 的技术栈横跨了多个领域——大模型应用开发、数据工程、前端交互、后端架构每一层都有坑。这篇文章适合三类人看正在选型 Data Agent 平台的技术负责人、准备自己搭建 Data Agent 原型的开发工程师、以及想了解这个方向技术全貌的产品经理。我会从技术栈的每一层拆开讲结合我们实际调研和实操的经验把选型逻辑、架构设计、关键实现细节和踩过的坑都摊开来说。2. Data Agent 的核心技术栈拆解2.1 大模型层不是越强越好而是越合适越好Data Agent 的大脑是大模型但选型逻辑和做聊天机器人完全不同。聊天机器人可以容忍一定的模糊性但 Data Agent 生成的 SQL 一旦有语法错误或者逻辑偏差整个查询结果就是错的。我们实测下来在 Text-to-SQL 这个任务上不同模型的表现差距非常大。目前市面上主流的选型分三个梯队。第一梯队是 GPT-4 系列和 Claude 3.5 Sonnet在复杂 SQL 生成任务上的准确率明显领先但成本和数据合规是问题。第二梯队是国内的 DeepSeek-V3 和 Qwen2.5-72B在中文语境下的表名、字段名理解上有天然优势而且可以私有化部署。第三梯队是一些专门微调过的 SQL 生成模型比如 SQLCoder 系列在特定数据集上表现不错但泛化能力有限。我们内部做过一个测试用同样的 200 条自然语言查询在同一个数据仓库上跑。GPT-4 的首次生成准确率大约是 78%DeepSeek-V3 是 72%Qwen2.5-72B 是 69%。但加上一轮自动纠错之后DeepSeek-V3 能到 89%和 GPT-4 的 91% 差距很小了。考虑到私有化部署的成本优势我们最终在原型里选了 DeepSeek-V3。注意不要迷信榜单上的 Text-to-SQL 准确率。那些测试集通常是干净的、结构良好的数据库而真实企业环境里的表名可能是t_ord_mst_2024这种字段名可能是amt_1、amt_2。模型对业务语义的理解能力比单纯的 SQL 语法能力更重要。2.2 编排层Agent 框架的选择决定了扩展性Data Agent 不是一次性的问答而是一个多步骤的规划-执行-反思循环。编排层负责管理这个循环决定什么时候调用什么工具、什么时候需要向用户澄清、什么时候可以给出最终答案。目前主流的编排框架有 LangChain、LlamaIndex、AutoGen 和 Semantic Kernel。我们全都试过一遍最后在原型里用的是 LangGraph。原因很简单Data Agent 的执行流程是一个有状态的图而不是一条直线。用户问“上个月销售额下降的原因是什么”Agent 可能需要先查销售额、再查各区域明细、再查促销活动记录、最后做归因分析。这个过程中每一步的输出都会影响下一步的决策LangGraph 的状态管理和条件边机制天然适合这种场景。LangChain 的 AgentExecutor 更适合简单的工具调用场景一旦步骤超过五步调试起来非常痛苦。LlamaIndex 在 RAG 场景下很强但它的 Agent 编排能力相对弱一些。AutoGen 的多 Agent 协作模式很优雅但引入多个 Agent 之后Token 消耗和延迟都会成倍增加对于 Data Agent 这种需要快速响应的场景不太合适。编排层还有一个关键决策是让模型自由规划还是给它一个预设的流程模板。我们试过完全自由的 ReAct 模式结果模型经常陷入“查了又查”的死循环。后来改成“半自由”模式——给模型一个粗粒度的流程框架理解意图→定位数据→生成查询→执行→解释但在每个步骤内部允许它自由选择工具和参数。这样既保证了可控性又保留了灵活性。2.3 数据访问层元数据治理是成败的关键Data Agent 能不能用好很大程度上取决于元数据的质量。模型再强如果它不知道t_ord_mst是订单主表、amt_1是含税金额那它生成的 SQL 就是瞎猜。我们在调研中发现很多企业兴冲冲地上了 Data Agent结果发现模型根本找不到正确的表。原因不是模型不行而是元数据太烂。表没有注释、字段没有说明、表之间的关系没有定义。这种情况下再强的模型也白搭。所以数据访问层的核心不是数据库连接池而是元数据服务。我们建议至少要做好三件事第一给所有核心表加上业务含义清晰的注释第二建立字段级别的同义词映射比如“销售额”“营收”“收入”都映射到同一个字段第三定义表之间的外键关系和常见的 Join 路径。这三件事做完Text-to-SQL 的准确率能提升 20 个百分点以上。数据访问层的另一个关键是查询执行的安全控制。Data Agent 生成的 SQL 必须经过审核才能执行否则一个DELETE或者UPDATE就可能造成生产事故。我们的做法是在执行前加一层 SQL 解析器只允许SELECT语句通过并且对查询的行数和执行时间做限制。2.4 交互层SSE 流式输出是体验的分水岭Data Agent 的响应时间通常在 3 到 15 秒之间取决于查询的复杂度和数据量。如果让用户盯着一个 loading 图标等十几秒体验会非常糟糕。SSEServer-Sent Events流式输出是解决这个问题的标准方案。SSE 的核心思路是后端不等整个回答生成完再返回而是每生成一个 Token 就推送给前端前端实时渲染。这样用户能看到 Agent 在“思考”的过程——先显示“正在理解你的问题”再显示“正在查找相关数据表”再显示“正在生成查询语句”最后才显示结果。这种渐进式的反馈让等待变得可以接受。实现 SSE 的时候有几个坑要注意。第一SSE 连接是单向的只能服务器推送给客户端如果用户想中途取消查询需要另外发一个 HTTP 请求来触发 abort。第二SSE 连接在 Nginx 后面默认会被缓冲需要设置proxy_buffering off和X-Accel-Buffering: no。第三如果 Agent 的执行过程中有多个步骤每个步骤的输出要打上类型标记前端才能区分哪些是思考过程、哪些是最终结果。我们实测下来加上 SSE 流式输出之后用户感知的等待时间从平均 8 秒降到了 3 秒左右。虽然实际执行时间没变但体验完全不一样了。2.5 前端渲染层不只是聊天窗口Data Agent 的前端不只是个聊天窗口。它需要渲染表格、图表、SQL 代码块、执行计划等多种内容类型。我们调研了市面上几款产品发现前端体验做得好的通常都有一套专门的内容渲染协议。我们的做法是定义一套 JSON Schema后端返回的每个消息块都带有type字段前端根据type决定用什么组件渲染。比如type: table就用表格组件type: chart就用 ECharts 渲染type: sql就用代码高亮组件。这样后端不需要关心前端怎么渲染前端也不需要理解后端的业务逻辑。图表渲染这块有个细节Data Agent 返回的数据通常是二维表结构但用户可能想要柱状图、折线图、饼图等不同形式。我们的做法是让模型在返回数据的同时也返回一个推荐的图表类型和维度映射前端根据这个推荐来渲染。用户也可以手动切换图表类型前端重新渲染即可不需要再请求后端。3. 技术架构的三种典型模式3.1 单体架构适合快速验证最简单的 Data Agent 架构就是一个单体服务里面包含了模型调用、编排逻辑、数据访问和 API 接口。这种架构的好处是部署简单、调试方便适合在概念验证阶段使用。我们最早的原型就是一个 Python FastAPI 服务里面直接调 LangGraph、直接连数据库、直接返回 SSE 流。整个服务不到 2000 行代码但已经能跑通“自然语言→SQL→结果→图表”的完整链路。这个阶段最重要的是验证核心可行性不要过早考虑扩展性和高可用。单体架构的瓶颈也很明显。模型调用是 IO 密集型的数据库查询也是 IO 密集型的如果并发请求多了一个慢查询就会阻塞整个服务。所以单体架构只适合内部试用不适合直接上生产。3.2 微服务架构适合企业级部署当 Data Agent 需要服务多个部门、接入多个数据源的时候微服务架构就更合适了。我们调研的一家金融企业他们的 Data Agent 平台拆成了五个服务对话服务、编排服务、元数据服务、查询执行服务、结果渲染服务。对话服务负责和前端交互管理会话状态和 SSE 连接。编排服务负责调用大模型、管理 Agent 执行流程。元数据服务负责维护表结构、字段说明、同义词映射。查询执行服务负责 SQL 审核、执行和结果缓存。结果渲染服务负责把查询结果转换成图表配置。这种拆法的好处是每个服务可以独立扩展。比如编排服务是 CPU 密集型的可以多部署几个实例查询执行服务是 IO 密集型的可以配置连接池和缓存。但代价是运维复杂度上升服务之间的通信延迟也会增加。3.3 事件驱动架构适合高并发场景如果 Data Agent 需要支持大量并发用户事件驱动架构是更好的选择。用户发起查询后请求被放入消息队列后台的工作进程从队列中取出任务并执行执行结果通过 SSE 或 WebSocket 推送给用户。这种架构的好处是天然支持异步和削峰填谷。用户不需要等待查询完成可以关闭页面稍后再来看结果。但缺点是交互体验会打折扣因为用户看不到实时的执行过程。我们实测下来对于大多数企业内部的 Data Agent 场景微服务架构已经足够。事件驱动架构更适合面向外部用户的 SaaS 产品内部工具没必要上这么复杂的架构。4. 实操从零搭建一个 Data Agent 原型4.1 环境准备与依赖安装我们以 Python 技术栈为例搭建一个最小可用的 Data Agent 原型。需要准备的东西包括一个能调用大模型的 API Key、一个测试用的数据库SQLite 就够了、Python 3.10 以上的运行环境。核心依赖包括langgraph用于编排 Agent 流程langchain-community用于数据库连接和工具封装fastapi和uvicorn用于提供 HTTP 接口和 SSE 流式输出sqlalchemy用于数据库操作sse-starlette用于简化 SSE 的实现。pip install langgraph langchain-community fastapi uvicorn sqlalchemy sse-starlette openai数据库我们用 SQLite 建两张测试表一张订单表orders包含订单 ID、客户 ID、金额、日期一张客户表customers包含客户 ID、名称、地区。建表语句和示例数据可以直接用 SQL 脚本生成。4.2 元数据服务的搭建元数据服务是 Data Agent 的“地图”。我们用一个简单的 JSON 文件来存储元数据包含每张表的名称、业务描述、字段列表和字段说明。metadata { orders: { description: 订单主表记录所有订单信息, columns: { order_id: 订单唯一标识, customer_id: 客户ID关联customers表, amount: 订单金额单位元, order_date: 下单日期格式YYYY-MM-DD } }, customers: { description: 客户信息表, columns: { customer_id: 客户唯一标识, name: 客户名称, region: 客户所在地区 } } }这个元数据会在生成 SQL 的时候作为上下文传给模型。实测下来加上元数据之后模型生成的 SQL 准确率明显提升尤其是涉及多表 Join 的查询。4.3 Agent 编排逻辑的实现Agent 的核心是一个状态图包含四个节点理解意图、生成 SQL、执行查询、解释结果。每个节点都是一个函数接收当前状态并返回更新后的状态。from langgraph.graph import StateGraph, END from typing import TypedDict class AgentState(TypedDict): question: str sql: str result: list explanation: str def understand_intent(state): # 调用模型理解用户意图确定需要查询哪些表 return {question: state[question]} def generate_sql(state): # 调用模型生成 SQL传入元数据作为上下文 return {sql: SELECT ...} def execute_query(state): # 执行 SQL 并返回结果 return {result: [...]} def explain_result(state): # 调用模型解释查询结果 return {explanation: ...} graph StateGraph(AgentState) graph.add_node(understand, understand_intent) graph.add_node(generate, generate_sql) graph.add_node(execute, execute_query) graph.add_node(explain, explain_result) graph.set_entry_point(understand) graph.add_edge(understand, generate) graph.add_edge(generate, execute) graph.add_edge(execute, explain) graph.add_edge(explain, END) app graph.compile()这个流程看起来简单但每个节点内部的 Prompt 设计才是关键。比如生成 SQL 的 Prompt 需要包含数据库的元数据、用户的问题、SQL 方言的说明、以及一些 Few-shot 示例。我们试过不加 Few-shot准确率会下降 10% 左右。4.4 SSE 流式输出的实现SSE 的实现用sse-starlette的EventSourceResponse它封装了 SSE 的协议细节用起来很简单。from sse_starlette.sse import EventSourceResponse from fastapi import FastAPI app FastAPI() app.get(/query) async def query(question: str): async def event_generator(): yield {event: thinking, data: 正在理解你的问题...} # 执行 Agent 流程 result await run_agent(question) yield {event: sql, data: result[sql]} yield {event: result, data: json.dumps(result[result])} yield {event: explanation, data: result[explanation]} return EventSourceResponse(event_generator())前端用EventSource接收事件根据event类型决定渲染方式。这里有个细节EventSource默认只支持 GET 请求如果查询参数很长可能会超出 URL 长度限制。我们的做法是先用 POST 创建一个会话拿到 session_id然后用 GET 请求 SSE 流通过 session_id 关联查询。4.5 前端渲染与交互前端我们用的是 React 加 ECharts。核心逻辑是监听 SSE 事件把不同的事件类型渲染成不同的组件。const eventSource new EventSource(/query?session_id${sessionId}); eventSource.addEventListener(thinking, (e) { setThinking(e.data); }); eventSource.addEventListener(sql, (e) { setSql(e.data); }); eventSource.addEventListener(result, (e) { const data JSON.parse(e.data); setTableData(data); // 根据数据自动推荐图表类型 const chartConfig recommendChart(data); setChartConfig(chartConfig); }); eventSource.addEventListener(explanation, (e) { setExplanation(e.data); eventSource.close(); });图表推荐逻辑很简单如果结果只有两列且其中一列是数值推荐柱状图如果结果包含日期列推荐折线图如果结果只有一列且是数值推荐饼图。这个逻辑用几十行代码就能实现但能大幅提升用户体验。5. 常见问题与排查技巧实录5.1 模型生成的 SQL 总是找不到正确的表这是最常见的问题根本原因通常是元数据质量不够。排查思路是先看模型生成的 SQL 里用了哪些表名再对比元数据里有没有这些表。如果模型用了不存在的表名说明元数据里的表名和模型理解的不一致。解决办法有两个一是在元数据里加上表名的同义词比如orders表加上“订单”“交易”“销售记录”等别名二是在 Prompt 里明确列出所有可用的表名让模型只能从这些表里选。我们实测下来第二种方法效果更直接。5.2 SSE 连接经常断开SSE 连接断开的原因通常有三个Nginx 的缓冲设置、连接超时时间、以及服务端的异常处理。首先检查 Nginx 配置确保proxy_buffering off和proxy_read_timeout设置足够长。其次在服务端加上心跳机制每隔 15 秒发送一个空事件保持连接活跃。最后在event_generator里加上 try-catch确保异常时能正常关闭连接。5.3 查询结果太大导致前端卡死Data Agent 生成的 SQL 如果没有加LIMIT可能会返回几十万行数据前端渲染直接卡死。解决办法是在查询执行层强制加上行数限制比如最多返回 1000 行。如果用户确实需要更多数据可以提供导出功能而不是在前端渲染。5.4 模型解释结果时出现幻觉模型在解释查询结果时可能会编造一些数据中不存在的信息。比如查询结果显示销售额下降了 10%模型可能会说“主要是因为华东地区促销活动减少”但数据里根本没有促销活动的信息。解决办法是在解释结果的 Prompt 里明确要求只能基于查询结果中的数据进行分析不能引入外部信息。5.5 多轮对话中上下文丢失Data Agent 通常需要支持多轮对话比如用户先问“上个月销售额是多少”再问“那前个月呢”。如果每次查询都是独立的模型就不知道“那前个月”指的是什么。解决办法是在会话状态里保存历史查询和结果每次生成 SQL 时把最近几轮的历史作为上下文传给模型。问题现象可能原因排查方法解决方案SQL 找不到表元数据缺失或表名不一致对比生成的 SQL 和元数据补充同义词映射Prompt 中列出可用表SSE 连接断开Nginx 缓冲或超时检查 Nginx 配置和服务端日志关闭缓冲加心跳设置超时前端卡死查询结果行数过多查看返回的数据量强制 LIMIT提供导出功能解释出现幻觉Prompt 约束不够检查解释结果的 Prompt明确要求只基于查询结果分析多轮对话丢失上下文会话状态未保存检查会话管理逻辑保存历史查询和结果传入上下文6. 选型建议与个人体会如果你正在选型 Data Agent 平台我的建议是先想清楚三个问题数据在哪里、用户是谁、并发量多大。数据在私有化环境里就必须选支持私有化部署的模型和框架。用户是业务人员前端体验就比技术指标更重要。并发量不大单体架构就够用没必要上微服务。我们团队在调研过程中最大的体会是Data Agent 的瓶颈往往不在模型而在数据治理。很多企业花了大价钱买模型、搭平台结果发现元数据一塌糊涂模型根本找不到正确的表。所以如果你准备启动 Data Agent 项目我建议先把元数据治理做好这比选什么模型重要得多。另一个体会是不要追求一步到位。我们最早想做一个全能的 Data Agent能查数据、能做分析、能生成报告。结果发现每个方向都做不深。后来聚焦在“自然语言查数据”这一个场景上反而做出了可用的产品。先解决一个具体问题再逐步扩展这个节奏更稳妥。最后分享一个实用技巧在 Prompt 里加上“如果用户的问题不够明确请先向用户澄清”这句话能大幅减少误查询。我们实测下来加上这句话之后因为理解偏差导致的错误查询减少了将近一半。用户一开始可能觉得多了一步确认有点麻烦但比起查错数据带来的误导这点麻烦是值得的。