Data Agent
Data Agent 是云原生数据仓库 AnalyticDB PostgreSQL 版(以下简称 AnalyticDB for PostgreSQL)提供的数据处理分析 Agent。它以自然语言为交互入口,提供只读问数分析和 DBA 只读诊断两大核心能力,帮助用户无需编写 SQL 即可完成数据查询、结果分析和实例健康诊断。
前提条件
AnalyticDB for PostgreSQL 7.0 版实例,内核小版本 7.2.1.0 及以上。
功能概述
Data Agent 面向 AnalyticDB for PostgreSQL 的 DBA 和数据分析用户,解决以下常见问题:
不熟悉表结构和字段含义,写 SQL 效率低。
执行计划不易解读,性能问题定位耗时。
需要在多个工具(控制台、监控、SQL 客户端)之间切换才能完成一次完整的分析或诊断。
Data Agent 与 AnalyticDB for PostgreSQL 内核同源,能够访问 Ontology 语义层和内核级可观测数据(执行计划、segment/slice 视图、管控面指标),因此可以准确理解业务语义并给出专业级的分析结论和诊断建议。产品默认只读查询,不写入用户数据;Ontology 语义层在构建时需要将元数据写入数据库(ontology_graph和 semantic.views表),此操作为产品内部管理动作,不涉及用户业务数据。数据与 AI 资产不出客户环境。
核心能力
只读问数分析
用户用自然语言描述分析需求,Data Agent 自动生成只读 SQL、执行查询并返回结构化结果。支持多轮追问(如切换图表类型、追加过滤条件)和 SQL 溯源(查看生成的 SQL 及其执行计划)。
典型场景包括:多维对比分析(如品类环比、区域同比)、趋势分析、Top N 排名、占比分布、跨表关联查询等。
DBA 只读诊断
用户将慢 SQL 或直接描述问题发送给 Data Agent,Agent 自动读取执行计划、定位性能瓶颈(如全表扫描、数据倾斜、锁等待),并给出可执行的改写方案和分级优化建议。
支持的诊断模板包括:SQL 诊断优化、资源使用诊断、慢查询分析、锁等待分析、数据倾斜诊断、表膨胀检查、长事务诊断、索引使用诊断。
Ontology 语义层
Ontology 是 Data Agent 的语义知识图谱,解决 NL2SQL 中"模型不理解业务"的核心问题。它将数据库的表、列、业务概念、指标公式、JOIN 关系和业务规则组织成结构化的语义网络,使 Agent 在生成 SQL 时能够准确理解"月活跃用户""品类环比"这类业务术语对应的表和计算方式,而不需要用户每次手动解释。
Ontology 采用双层架构:
图谱层(基于 Apache AGE 图数据库扩展):存储概念、表、列、指标、业务规则之间的关联关系,支持概念发现、跨表 JOIN 路径查找、权威度排序(OntoRank)。
语义模型层(基于 JSONB + YAML):存储列定义、指标公式、同义词、数据特征等结构化元数据,以 YAML 文件作为人工可编辑的工作格式,双向同步到数据库。
Data Agent 提供 Ontology 的完整生命周期管理:
构建(Builder):扫描数据库元数据和查询日志,通过模型提取业务概念和关联关系,生成语义模型 YAML,同步到图谱。支持全量构建和增量更新。
消费(Consumer):Agent 收到自然语言问题后,通过 Ontology 匹配相关概念、查找 JOIN 路径、获取指标公式,生成更准确的 SQL。
维护(Maintainer):增量刷新变更的表和列,重新计算概念权威度评分。
Desktop 客户端提供 Ontology 管理界面,支持 5 步向导式构建(初始化 → 生成 YAML → 同步 YAML → 构建图谱 → 可视化),以及力导向图可视化展示概念-表-列的关联关系。
Ontology 提供表访问的三级管控:已注册到语义模型且非敏感的表走增强模式(使用语义模型中的同义词、指标和 JOIN 关系);未注册表执行敏感检测(表名模式匹配 + 表注释标记),命中敏感标记的表阻断访问;其余表基于 RBAC 权限判断,有 SELECT 权限但未注册的表走基础模式(仅用信息模式元数据,准确率受限)。
声明
Data Agent 生成的内容由 AI 模型产生,仅供参考。分析结论和诊断建议不保证绝对准确,请结合业务实际情况判断,重要操作请先在测试环境验证。
Data Agent 为只读设计,问数分析和诊断能力不执行写入、修改或删除等变更操作,不存在因 Agent 操作导致的数据变更风险。Ontology 语义层在构建时需要将元数据写入数据库(
ontology_graph和semantic.views表),此操作为产品内部管理动作,不涉及用户业务数据。Data Agent 以当前登录用户的身份执行查询,不会超出账号自身权限范围。
任何功能均不会将您的数据外传,所有查询和诊断在您的 AnalyticDB for PostgreSQL 实例内完成。
工作原理
Data Agent 的整体架构分为四层:
Agent Runtime 层:Data Agent 所在层,负责自然语言理解、SQL 生成、工具编排和结果呈现。
Agent Context 层:提供 Ontology 语义层、知识库、记忆、Skill 等上下文支撑。
Disk+OSS 存储层:AnalyticDB for PostgreSQL 实例的结构化表存储。
MaaS 层:模型调用,包括 NL2SQL、诊断归因、结果分析等。使用前需获取 ADB-PG AI Gateway 的 API Key。
Data Agent 通过 MCP(Model Context Protocol)Server 与 AnalyticDB for PostgreSQL 实例交互。所有 SQL 在执行前经过两层校验:
安全校验(SQLGuard)
双层并行校验。正则层负责语句类型白名单(仅允许 SELECT/WITH 只读语句)、多语句注入防护、危险函数拦截(pg_sleep、pg_terminate_backend、dblink、文件读写函数等)、危险模式拦截(COPY PROGRAM、INTO OUTFILE 等)、敏感表访问阻断(pg_user、pg_shadow 等系统表)、破坏性 DML/DDL 拦截。AST 层(pglast)提供 PostgreSQL 原生解析器级别的语法校验,在 Greenplum 方言或解析失败时自动降级到正则层。
质量检查(Query Quality Guard)
基于 sqlglot 的 SQL 静态分析,拦截影响执行计划的常见反模式。阻断级规则包括隐式笛卡尔积检测、大表无 WHERE 过滤、大表全表聚合无 GROUP BY;警告级规则包括 SELECT *、子查询嵌套过深、SELECT 列数过多、分区表未引用分区键导致无法分区裁剪、瀑布式 CTE 层层转手。阻断时返回具体问题和修改建议,由 Agent 重写后重新提交。
查询结果默认自动注入 LIMIT 防止超大数据量返回。
Skill 包
Data Agent 的能力以四个内置 Skill 包组织,Agent 根据用户意图自动加载对应的 Skill 及其参考文档:
Skill 包 | 用途 | 覆盖场景 |
adbpg-query | 数据查询。通过 MCP 工具执行只读查询,支持语义模型驱动的 SQL 生成,结果支持导出 CSV | 日常取数、统计分析、结果导出 |
adbpg-diagnostics | 数据库诊断。按场景匹配 8 个诊断模板,每个模板对应一份诊断流程参考文档 | SQL 诊断优化、资源使用诊断、慢查询分析、锁等待分析、数据倾斜诊断、表膨胀检查、长事务诊断、索引使用诊断 |
adbpg-optimizer | SQL 模式识别与优化。识别 MPP 环境下的高危 SQL 写法(Lateral关联、子查询投影列、无分区裁剪等)并给出改写方案 | 慢 SQL 改写、批量 SQL 风险分诊、优化器回退排查 |
adbpg-ontology | Ontology 语义层管理。支持 Builder(构建图谱)、Maintainer(增量维护 + OntoRank 权威度重算)、Consumer(语义发现辅助 SQL 生成)三种模式 | 语义模型构建、概念发现、JOIN 路径查找、指标公式检索 |
Skill 包随 Desktop 客户端内置提供,Agent 运行过程中自动按需加载,无需用户手动配置。
使用方式
通过 Desktop 客户端使用
Data Agent 以 Desktop 客户端形式提供,安装后即可使用。当前支持的平台:
平台 | 架构 | 下载 |
macOS | Apple Silicon (arm64) | |
macOS | Intel (x64) | |
Windows | Intel (x64) |
安装 Data Agent Desktop 客户端。
获取 ADB-PG AI Gateway 的 API Key。在 AnalyticDB PostgreSQL 控制台的 AgenticDB > 模型算子管理 页面,单击 创建 API Key,在弹窗中输入描述并确认。创建完成后需提交工单由阿里云技术团队完成后台配置。
在 Desktop 客户端,左侧菜单栏单击设置 > AI,在模型Provider区域,单击连接,填入步骤2获取的 API Key 和接入点地址。
在 Desktop 客户端,左侧导航栏单击数据源,然后单击上方添加数据源,配置 AnalyticDB for PostgreSQL 实例连接信息(Host、Port、用户名、密码、数据库名)。建议使用具备
SELECT权限的只读账号,最小化权限范围。(可选)如需使用管控面诊断能力(实例指标、慢 SQL 记录等),配置阿里云 RAM AK/SK。具体操作请参见 创建 AccessKey。建议为 AK/SK 关联的 RAM 用户授予
AliyunGPDBReadOnlyAccess系统策略。(可选)如需使用 Ontology 语义层,需先完成权限配置和构建,详见Ontology 使用指南。
在对话框中输入自然语言问题或发送待分析的 SQL。
Desktop 客户端还提供以下辅助能力:
DBA 诊断面板:按场景模板(SQL 诊断、资源使用、慢查询、锁等待、数据倾斜、表膨胀、长事务、索引使用)填写参数表单,一键触发结构化诊断,无需手写诊断 SQL。
实例监控:通过管控面 OpenAPI 拉取实例性能指标(CPU、内存、IO、QPS、TPS),以图表形式展示趋势,支持时间范围选择和节点维度切换。
Ontology 可视化:力导向图展示概念-表-列的关联关系,支持节点筛选和详情下钻。
结果可视化:问数结果支持自动生成 ECharts 图表(柱状图、折线图、饼图、散点图),支持多轮对话中切换图表类型。
通过 CLI/Skill 集成
此能力暂未开放,后续版本将支持通过 MCP Server 和 Skill 形式供其他 AI 编程工具集成调用。
安全与权限
Data Agent 在产品侧和用户侧共同构建安全防护体系。
产品侧保障
只读保障:Agent 仅注册只读工具,SQLGuard 在正则层和 AST 层双重校验,数据库侧使用
READ ONLY事务包裹。数据不出域:所有查询和诊断在客户 AnalyticDB for PostgreSQL 实例内完成,数据和 AI 资产不出客户环境。
数据库账号
执行只读问数和数据库内诊断使用的数据库账号,建议使用只具备目标表SELECT权限的只读账号。锁等待、数据倾斜、表膨胀等诊断能力需要读取pg_stat_activity、gp_toolkit等系统视图,普通只读账号即可访问;若需查看其他用户的会话信息(如锁等待诊断中被阻塞的其他会话),需额外授予pg_read_all_stats权限。
建议由 DBA 创建专用只读账号,仅授权业务所需的特定表,严禁全库授权:
CREATE ROLE readonly_agent LOGIN PASSWORD '<强密码>';
GRANT CONNECT ON DATABASE mydb TO readonly_agent;
GRANT USAGE ON SCHEMA public TO readonly_agent;
GRANT SELECT ON public.orders, public.customers TO readonly_agent; -- 仅授权所需表为只读账号配置专用资源组,避免 Agent 查询与业务负载争抢资源:
CREATE RESOURCE GROUP agent_rg WITH (concurrency=5, cpu_max_percent=10, memory_limit=10);
ALTER ROLE readonly_agent RESOURCE GROUP agent_rg;RAM AK/SK
使用实例指标、慢 SQL 记录等管控面诊断能力时,需要配置阿里云 RAM AK/SK。Data Agent 管控面调用的 OpenAPI 均为只读接口。推荐为 AK/SK 关联的 RAM 用户授予AliyunGPDBReadOnlyAccess系统策略,该策略覆盖 Data Agent 所需的全部只读接口。
网络访问控制
确保 AnalyticDB PostgreSQL 实例的白名单中已添加 Data Agent 运行环境的出口 IP。在控制台 数据安全性 > 白名单设置 中添加。
应用场景
用户角色 | 典型场景 |
数据分析师 / BI 工程师 | 自然语言取数、多维对比分析、趋势解读、本地 CSV 与库内数据联合分析、图表切换 |
DBA / 运维工程师 | 慢 SQL 诊断与改写建议、实例健康巡检、锁等待分析、数据倾斜诊断、表膨胀检查、长事务排查、索引使用分析 |
数据工程师 / 业务开发 | Ontology 语义模型构建、业务概念与表列映射维护、JOIN 关系梳理、指标口径固化 |
计费说明
Data Agent 本身不单独计费。使用过程中产生的费用包括:
MaaS Token 消耗:Agent 编排、NL2SQL、诊断分析调用模型产生的 Token 费用,按 AI Gateway 计费标准收取。
实例费用:查询消耗的 AnalyticDB for PostgreSQL 实例计算和存储资源,按实例原有计费方式收取。
常见问题
Data Agent 能访问业务数据吗?
能,但仅限只读查询。用户在对话中提出的分析需求,Data Agent 会生成 SELECT 语句并在实例上执行,返回查询结果。诊断类能力主要读取执行计划、系统视图和监控元数据。所有操作以当前登录用户的权限为边界。
为什么有时候回答不准确?
Data Agent 的准确性取决于业务语义的可理解程度。表结构复杂、字段含义不清或业务口径未定义时,模型可能生成不符合预期的 SQL。建议通过 Ontology 语义层完善表列的业务描述和指标口径,或在使用时提供更具体的上下文(如表名、字段名、问题描述)。
使用 Data Agent 会对实例性能产生影响吗?
诊断类能力只读取系统视图和监控数据,对实例性能影响可忽略。问数分析类能力会在实例上实际执行 SELECT 查询,大数据量查询会占用实例计算资源,建议遵循业务低谷期执行或通过 LIMIT 限制返回行数。