★ FEATURED ARTICLE 上周帮一家做零售数据分析的客户搭内部数据平台发现这个圈子变化比想象中快以前要凑齐 Agent 框架、向量数据库、可视化工具三样东西才能开工现在数据库自己把 Agent 这件事干了。我说的就是 DolphinX-Web一个基于数据库自带 Agent 能力搭起来的数据入库与分析框架从零到跑通完整链路我实测十到十五分钟熟练之后十分钟以内完全可行。这篇文章把我的搭建全过程记录下来包括为什么选数据库自带的 Agent 而不是外挂框架、入库链路怎么设计、分析查询怎么写以及上线一个月之后踩过的几个坑。如果你也在给团队搭数据底座或者正在纠结 Agent 到底应该放在哪一层这篇应该能帮你省不少试错时间。1. 为什么我放弃外挂 Agent改用数据库自带的 Agent1.1 外挂方案的三宗罪先说结论不是外挂 Agent 框架不行而是在数据入库 数据分析这个场景里它的成本常常被严重低估。我之前用过的方案是通用 LLM 编排框架 数据库连接器链路大概是自然语言 → 编排器拆解 → 生成 SQL → 调用数据库连接器执行 → 拿结果再格式化返回。听起来顺理成章实际跑起来问题很多。第一宗罪是链路太长。每个环节都是独立组件任何一个版本升级都可能破坏下游。有一阵子我光排查为什么 Agent 不认新加的表就花了三个小时最后发现是连接器缓存了旧的 schema。第二宗罪是权限边界难控制。外挂 Agent 为了能查库通常得给它一个高权限账号一旦它的 prompt 被注入攻击等于把整个库的钥匙交出去了。第三宗罪是 prompt 不可控。你要在提示词里塞表结构、字段说明、业务口径塞得越多越容易漂移今天能用明天模型一更新可能就废了。这套组合拳不是不能用而是维护成本全在后面前期搭得快后期还债还得勤。1.2 原生 Agent 做了什么不一样的事DolphinX-Web 的做法完全不同它的 Agent 是跑在数据库内核边上的Schema 感知、权限校验、SQL 生成这些能力不是靠提示词注入而是直接读取系统的数据字典和权限模型。这意味着它天然知道有哪些表、哪些字段、哪个字段是主键、哪个字段有索引不需要你维护任何元数据上下文。权限这块更省心。Agent 执行查询时继承的是数据库自身的行级权限用户在 Web 控制台里能看到什么数据Agent 就只能访问什么数据不存在应用层模拟权限但漏了一条的问题。我对比过两类方案的差异核心区别可以整理成一张表对比项外挂 Agent 方案DolphinX-Web 原生 AgentSchema 感知依赖手动维护上下文易过期实时读取数据字典权限控制高权限连接账号 应用层模拟继承库内行级权限天然一致SQL 生成上下文prompt 注入模型迭代后易漂移基于系统目录动态生成数据流转数据要经过外部 API 处理在库内闭环不外送维护成本多组件升级联动单产品升级这张表不是我纸上谈兵是两边都跑过生产负载之后总结出来的。特别是数据在库内闭环这条对零售、金融这类对数据流转敏感的业务来说基本是决定性的。1.3 什么项目适合 DolphinX-Web什么不适合任何工具都有边界我用了三个月之后明确划了一条线。适合的场景内部数据平台、业务方自助取数、BI 报表的即席查询、日志类数据的快速入库分析、IoT 设备数据的分区归档。共同特点是数据源相对单一、目标统一进一个库、查询模式偏标准 SQLAgent 的自动生成能力能覆盖八成以上的需求。不适合的场景跨数据库联邦查询比如同时查 MySQL、SQLite、Oracle 还得做实时关联、复杂 ETL 里的大规模清洗转换、还有需要自定义 Agent 人格和复杂多轮业务流程的场景。这些情况 DolphinX-Web 的 Agent 就显得太规矩你得回到专业 ETL 工具或业务编排框架上去。2. 搭框架前 5 分钟版本、初始化与 Agent 自检2.1 版本选择与部署参数我这边用的是 DolphinX-Web 3.2.4官方标注的稳定版本。选版本这件事我吃过亏一开始图新鲜上了 4.0 的预览版Agent 的自然语言解析确实更快但调度模块有个内存泄漏跑三天节点就重启一回后来还是退回 3.2 LTS。生产环境求稳新特性等它至少出一个 patch 版本再考虑。部署方式我用的 Docker 单机版测试阶段够用。命令如下docker run -d --name dolphinx-web \ -p 8080:8080 \ -p 5432:5432 \ -e DX_ADMIN_PASSWORD你的初始密码 \ -e DX_AGENT_MODELlocal \ -v /data/dolphinx:/var/lib/dolphinx \ dolphindb/dolphinx-web:3.2.4注意两个环境变量DX_ADMIN_PASSWORD是 Web 控制台的管理员初始密码DX_AGENT_MODELlocal表示 Agent 用库内集成的轻量推理引擎不走外部模型服务业务数据完全留在本地。如果你的环境允许外部推理模型也可以切换成 remote 模式接已有的模型 API但出于数据安全考虑我建议默认 local。启动之后浏览器访问http://服务器IP:8080首次登录会引导你改密码、建管理员账号。这一步做完框架的骨架就有了。2.2 Agent 注册与基础配置DolphinX-Web 装好之后 Agent 默认是禁用状态需要手动启用一次。在 Web 控制台的命令行面板它内置了一个类似 psql 的交互终端执行-- 启用主 Agent dx agent enable NAMEmain-agent MODELlocal ROLEanalyst; -- 测试 Agent 是否正常响应 dx agent probe QUERYSELECT count(*) FROM information_schema.tables;probe是最关键的一步它会实际走一遍自然语言解析 → 数据字典读取 → SQL 生成 → 执行 → 返回结果的完整链路。如果 probe 返回正常说明 Agent 和存储引擎之间是通的如果卡住八成是初始化时数据字典没有加载完整重启一下容器通常能解决。这一步我建议顺便把 Agent 的工作参数调一下。重点两个一个是RESULT_FORMATmarkdown让 Agent 默认用 Markdown 表格输出结果下游对接脚本解析起来非常舒服另一个是MAX_ROWS1000防止业务方一个自然语言查询把几百万行全倒出来把 Web 页面拖死。2.3 用三条测试语句确认 Agent 的工作边界光能响应还不够得确认它真能干活。我会习惯性跑三条测试语句覆盖不同层级的任务-- 元数据问答确认能看懂表结构 dx ask 这个库里有几张表分别是什么用途 -- 简单查询确认精确数值 dx ask crm_customers 表里有效手机号有多少个 -- 聚合分析确认能生成带分组和排序的 SQL dx ask 过去30天每天的新增客户数按天展示从多到少三条都通过环境准备才算结束时间大概五到六分钟。剩下的时间就留给入库和分析框架的搭建。3. 数据入库让 Agent 自己搞定建表、清洗与调度3.1 三种数据入口先想清楚你的数据从哪来DolphinX-Web 的 Agent 支持三种入库入口文件上传、API 拉取、消息流订阅。我建议不要贪多先确认你的数据产生方式再选。文件上传适合 Excel、CSV 这种历史数据的批量导入比如把散落在业务手里的月度报表归集起来API 拉取适合对接业务系统的接口比如每十分钟从订单服务拉一次增量数据消息流订阅适合高频实时数据比如埋点日志、设备上报走的是 Kafka 兼容协议。三种入口在 Agent 看来都是一个入库任务区别只在于 SOURCE 字段的声明方式。我搭建时第一优先处理的是历史数据所以先走文件上传。在控制台上传一个真实的业务文件比如 CRM 客户明细 CSV然后直接给 Agent 下指令。3.2 用自然语言定义一张入库任务这是整个框架体验最不像传统数据库的地方。传统做法是你得手动写建表语句、写清洗脚本、配定时任务在 DolphinX-Web 里你只需要把需求说清楚dx agent task CREATE 把上传的 crm_customers.csv 入库 目标表名 crm_customers 按 create_date 字段做范围分区 手机号格式不正确的行先丢进清洗队列 同一 user_id 重复的只保留最新一条 每 6 小时自动扫描一次新数据 ;Agent 收到这段自然语言描述之后会自动做四件事生成建表 DDL含分区键和字段类型推断、生成字段映射规则、生成数据质量校验规则、生成调度计划。我把它生成的 DDL 拉出来看过基本挑不出毛病类型推断、长度设置、可空约束都符合直觉。如果你的业务对表结构有特殊约定也可以在任务配置里手动指定模板让它照着来。生成的调度任务本质上是一份可读的配置我把它贴出来方便大家理解 Agent 到底在背后做了什么ingestion_task: name: ingest_crm_customers source: type: file path: file:///uploads/crm_customers.csv format: csv header: true target: table: crm_customers partition_by: create_date partition_type: range partition_interval: 1 month cleaning: rules: - field: phone action: drop_invalid pattern: ^1[3-9][0-9]{9}$ - field: user_id action: deduplicate keep: latest - field: email action: normalize lowercase: true schedule: interval: 6h next_run: auto这份配置可以手工改改完保存就生效。我建议把清洗规则写在入库阶段而不是分析阶段原因后面踩坑部分会细说。3.3 入库结果看板与失败重放机制任务跑完Agent 会自动生成一份入库质量报告包含总行数、成功行数、清洗丢弃行数、分区分布、耗时。这些信息在控制台的任务详情页一眼能看到不需要自己写 SQL 去核对。我最看重的其实是失败重放机制。入库任务跑失败是常态原因可能是一个脏数据字符让解析器崩了也可能是目标分区被占用。DolphinX-Web 会把失败的批次放进死信队列你只需要在控制台点重放Agent 会自动跳过已经入库的批次只补跑失败的。生产环境跑了两个月这条机制救了我至少五次比从头重新导一遍省事太多。4. 分析框架从自然语言到 SQL 再到看板4.1 权限是第一块地基Agent 也越不过去分析框架最容易被忽略的是权限设计。很多团队把精力花在让 Agent 生成 SQL 上结果上线一查业务方能看到不该看的字段。DolphinX-Web 的 Agent 继承的是数据库的行级权限这意味着你在 Web 控制台给用户开什么表的读权限Agent 就只能在那个范围内回答问题。我强烈建议在搭建分析框架之前先在控制台把用户组和行级策略配好。比如销售组只能查自己区域的数据财务组只能查结算相关的表这些策略配完之后Agent 执行任何查询都会自动追加对应的 WHERE 条件。你不需要在 prompt 里反复叮嘱不要越权权限本身就在执行层拦住了。4.2 一组典型分析查询的完整体验权限配好之后分析查询就是纯自然语言交互了。我随便举一个业务方真实会问的问题dx ask 分析近 30 天每天的订单量按地区分组 和上周同期做对比只展示订单量 Top5 的地区 Agent 收到这个问题后会经历拆解意图 → 识别表 → 生成 SQL → 校验语义 → 执行 → 返回结果六个环节。期间你可以在控制台看到它的执行日志每一步做了什么都有记录这一点对于排查问题特别重要。最终返回的是一张带周同比的 Markdown 表格业务方直接就能读。如果我想确认它生成的 SQL 到底长什么样可以加一个开关让它把 SQL 也打出来dx ask SELECT 模式执行近30天订单量 Top5 地区 SHOW_SQLtrue;它生成的 SQL 大致长这样我简化过SELECT region, SUM(order_amount) AS total_amount, COUNT(order_id) AS order_cnt, (SUM(order_amount) - LAG(SUM(order_amount), 7) OVER (ORDER BY region)) / NULLIF(LAG(SUM(order_amount), 7) OVER (ORDER BY region), 0) AS wow_change FROM fact_orders WHERE order_date CURRENT_DATE - INTERVAL 30 days AND region IN ( SELECT region FROM fact_orders WHERE order_date CURRENT_DATE - INTERVAL 7 days GROUP BY region ORDER BY SUM(order_amount) DESC LIMIT 5 ) GROUP BY region ORDER BY total_amount DESC;当然Agent 生成的 SQL 我不会盲目信任生产环境一定要在执行前校验开关上做文章。DolphinX-Web 默认对 UPDATE、DELETE 之外的所有查询都只读执行并且超过一定代价的 SQL 会自动拒绝这个阈值可以在设置里调。4.3 把常用分析固化成看板高频问题重复问是浪费把稳定口径固化成看板才是正路。在 DolphinX-Web 里你只需要在一段自然语言后面加一个动作指令dx ask 近30天订单量Top5地区按周刷新 SAVE_ASdashboard.sales_top_region;存完之后看板会自动出现在 Web 界面的数据看板区域并且按任务调度周期自动刷新数据。更关键的是Agent 会把这些指标的计算口径记下来。以后再有人问订单量相关的问题它会优先使用这个已定义的口径而不是每次现场生成 SQL——这就避免了同一指标在不同人口中有不同算法的混乱。5. 上线一个月踩过的坑每一个都能让你白忙半天5.1 Agent 自动维护索引的建议在高峰期执行把表锁了这是上线后踩到的第一个真正的坑。DolphinX-Web 的 Agent 带一个索引顾问功能它会定期扫描慢查询并生成建索引建议。听起来很贴心但默认配置下它会在建议生成后立即执行。我这边有一张大表Agent 建议给一个 varchar 字段建前缀索引执行时直接把表锁住晚高峰写请求全部排队业务方五分钟内连发了十几条告警。排查链路是这样的先看慢查询发现不是 SQL 问题全是锁等待再看锁监控发现一张大表上有长时间运行的 DDL再翻 Agent 日志才发现是索引顾问自动触发了 ALTER TABLE。根因找到后处理很简单把AUTO_INDEX从 true 改成 false让建议只落地到报告里由我确认后再在低峰期手动执行。5.2 Agent 的 SQL 生成本能优秀但想当然的时候拉不回来第二个坑发生在指标口径上。业务方问客户数Agent 直接对 crm_customers 表做了COUNT(*)但实际业务口径里客户的定义是 已激活且过去三个月有成交两个口径差了很大。第一次发现这个问题是在业务反馈数据不准的时候。排查过程分三步先让 Agent 输出它生成的 SQL发现它确实没带激活状态条件再查 Agent 的上下文日志发现它读取的是表本身的字段注释而注释里没有详细口径说明最后找到解决办法——在 DolphinX-Web 里给关键表配指标字典。说白了就是给 Agent 补一批语义注释哪个字段是激活状态、成交的定义是什么、默认时间范围是什么。补完之后再问客户数Agent 生成的 SQL 就带上了完整条件。这个坑给我们的教训是Agent 再聪明也猜不到你业务里那些藏在人脑子里的口径。趁早把口径沉淀成元数据才是正经事。5.3 行级权限下 Agent 的上下文偶发越权提示第三个坑比较诡异有用户反馈让 Agent 查数据时偶发报无权限访问表 xxx但我确认行级权限配置是没问题的。一开始怀疑是权限配置被覆盖检查了用户组、角色、策略全部正常。后来把 Agent 执行日志翻到底才发现问题出在 Agent 的会话上下文。登录用户的权限临时被刷新时Agent 长连接上还保留着旧的权限快照恰好这个快照里策略没更新完就出现了明明有权限但被拦的假象。解决办法也不复杂把 Agent 会话的权限缓存改为每次请求强制校验同时让用户在控制台重新登录一次。改完之后这个问题再没出现过。5.4 并发不高但查询偶发超时其实是连接池参数没调第四个坑更像传统数据库运维问题。一次简单的并发压测20 个并发用户同时跑自然语言查询结果时不时有查询超时。数据库 CPU 和内存都没打满连接数看起来也正常就很奇怪。我沿着 Agent 的执行日志一路查下去发现超时的查询全卡在获取数据库连接这一步。DolphinX-Web 的 Agent 默认连接池是 10SQL 生成快、执行快但连接不够用的时候只能排队。把连接池上限从 10 调到 50同时把空闲连接回收时间从 300 秒降到 60 秒超时立刻消失。这里我想提醒一句Agent 会掩盖一部分性能问题因为查询被它优化掉了但连接池这类基础参数还得按传统数据库的思路去调。5.5 排查必备用 trace_id 串起每次 Agent 任务的完整链路最后分享一个排查方法论。DolphinX-Web 每次 Agent 任务都会生成一个 trace_id分布在 Web 控制台、任务日志、查询日志里。遇到任何诡异的Agent 不按套路出牌第一件事就是拿 trace_id 把整条链路串起来看从用户输入、意图拆解、SQL 生成、权限校验到实际执行每一跳都有时间戳和结果码。我第一次排查越权提示问题就是靠 trace_id 连续翻了五六个日志节点才确定问题出在权限快照没有实时刷新。如果只看最后的报错信息这个问题可能到现在还悬着。这个产品上线运行到现在我的整体使用感受是它把数据入库和数据分析这两个日常高频动作的门槛压得非常低低到业务方可以直接上手。但有一点必须说清楚数据库自带的 Agent 不是银弹它帮你省下来的是从零搭框架的时间至于指标口径、权限边界、索引策略这些数据平台的地基工程该人做的还是得人做。尤其是把常用指标提前写进元数据字典——我发现做好这一件事后面所有自然语言查询的准确率都能再上一个台阶。
阅读完成 · 觉得有帮助？
