Data Agent

更新时间:
复制 MD 格式

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)

ADB-PG-Data-Agent-arm64.dmg

macOS

Intel (x64)

ADB-PG-Data-Agent-x64.dmg

Windows

Intel (x64)

ADB-PG-Data-Agent-x64.exe

  1. 安装 Data Agent Desktop 客户端。

  2. 获取 ADB-PG AI Gateway 的 API Key。在 AnalyticDB PostgreSQL 控制台的 AgenticDB > 模型算子管理 页面,单击 创建 API Key,在弹窗中输入描述并确认。创建完成后需提交工单由阿里云技术团队完成后台配置。

  3. 在 Desktop 客户端,左侧菜单栏单击设置 > AI,在模型Provider区域,单击连接,填入步骤2获取的 API Key 和接入点地址。

  4. 在 Desktop 客户端,左侧导航栏单击数据源,然后单击上方添加数据源,配置 AnalyticDB for PostgreSQL 实例连接信息(Host、Port、用户名、密码、数据库名)。建议使用具备SELECT权限的只读账号,最小化权限范围。

  5. (可选)如需使用管控面诊断能力(实例指标、慢 SQL 记录等),配置阿里云 RAM AK/SK。具体操作请参见 创建 AccessKey。建议为 AK/SK 关联的 RAM 用户授予AliyunGPDBReadOnlyAccess系统策略。

  6. (可选)如需使用 Ontology 语义层,需先完成权限配置和构建,详见Ontology 使用指南。

  7. 在对话框中输入自然语言问题或发送待分析的 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 限制返回行数。