Data Agent 使用指南
Data Agent 是云原生数据仓库AnalyticDB PostgreSQL版提供的数据处理分析 Agent,通过桌面客户端使用,具备自然语言问数、业务语义理解(Ontology)与 DBA 智能诊断三类能力:以自然语言获取查询结果与分析建议,以语义层保证业务口径准确,以慢查询分析、SQL 诊断优化、锁等待分析等诊断场景定位运维问题。本文介绍 Data Agent 的安装配置、智能问数与业务分析、DBA 智能诊断的使用方法。
安装与基本设置
环境要求:AnalyticDB for PostgreSQL 7.0 实例,内核小版本 7.2.1.4 及以上;客户端支持 macOS(arm64/x64)与 Windows(x64)。安装包获取方式参见Data Agent。
完成以下三步即可开始使用:配置模型服务 → 连接数据源 → 选择工作区。另有一项可选配置(RAM AccessKey),仅在使用实例监控及部分依赖监控指标的诊断场景时需要。
配置模型服务
首次启动应用时,会引导填写 AI Gateway 的接入信息(Base URL 与 API 密钥);也可以点击「稍后设置」,之后在「设置 → 模型 → 模型 Provider」中添加。
在 AnalyticDB for PostgreSQL 控制台获取接入信息:进入 AgenticDB → 模型算子管理,点击创建 API Key,填写描述后确认,即可获得接入地址与 API Key。创建完成后需提交工单,由阿里云技术团队完成后台配置。
在表单中填写 Base URL 与 API 密钥 两项:Base URL 为模型服务的接入地址,API 密钥用于身份验证。
保存配置。保存后,该 Provider 出现在模型列表中并自动成为默认模型;新建会话时,输入框右下角的模型选择器显示为「默认模型」。
连接数据源
在左侧「数据源」中点击「添加数据源」,填写名称、主机地址、端口、用户名、密码与默认数据库。
如果应用与实例不在同一内网环境,先在实例控制台开启公网访问,并将本机公网 IP 加入实例白名单(本机公网 IP 可通过
ifconfig.me等服务查询)。点击「测试连接」。连接成功后会列出该账号可访问的数据库,确认无误再保存。
建议使用具备 SELECT 权限的只读账号连接实例,最小化权限范围,避免使用高权限账号。
工作区与数据源
工作区用于关联会话与数据源。可以为工作区绑定一个默认数据源,此后从该工作区发起的会话默认访问该数据源。
对话过程中,也可以在输入框右下角临时切换当前会话使用的数据源。该切换只作用于当前会话,不改变工作区的默认绑定。
可选:配置 RAM AccessKey(AK/SK)
RAM AccessKey(AK/SK)用于调用阿里云 OpenAPI,获取 CPU/内存/IO 趋势、慢 SQL 记录等实例监控与运维数据;为可选的全局配置,填写一次即对所有数据源生效,所调用的 OpenAPI 均为只读接口。实例监控页面及部分依赖这些指标的诊断场景(如资源使用诊断)需要它;仅依赖数据库连接的功能不受影响,未配置也可正常使用。
在实例监控页点击「配置 AK/SK」打开配置框。
在 RAM 控制台创建 AccessKey,参见创建AccessKey;创建后为其关联的 RAM 用户授予 AliyunGPDBReadOnlyAccess 系统策略。
在配置框中填写 AccessKey 完成配置。该配置为全局配置,填写一次即对所有数据源生效。
界面导览
应用主界面包含以下区域:
对话:自然语言问数与业务分析的入口。
DBA 诊断:内置诊断场景模板,针对所选实例逐个场景发起诊断(见下文 DBA 智能诊断章节)。
实例监控:实例运行状态与资源监控曲线(见下文)。
Ontology:以图谱形式呈现指定库的业务语义层,包括业务域、概念、指标与口径规则(见下文智能问数与业务分析章节)。
技能:查看应用内置的技能包及其说明。
数据源 / 工作区 / 设置:管理实例连接、会话归属与应用配置。
DBA 诊断页中间为数据源列表,右侧为场景模板列表;选择不同数据源即可对不同实例分别诊断。
实例监控页左侧列出账号下的全部实例,右侧展示所选实例的运行状态与监控曲线,包括协调节点与计算节点健康度、引擎版本、实例模式、所在地域,以及连接数、QPS、TPS、查询平均响应时间等指标。监控分为「实例监控」与「节点监控」两个维度,时间范围支持 30 分钟、1 小时、6 小时及自定义。实例监控的数据通过 RAM AccessKey 所述 OpenAPI 获取,首次使用前需完成该配置。
智能问数与业务分析
功能概述
自然语言问数仅生成只读语句(SELECT/WITH),并在只读事务中执行,不会修改数据;除查询结果外,还会结合业务口径给出分析结论与建议。下面以咖啡连锁零售库为例,说明从提问到输出分析报告的过程。
Ontology 语义层
问数与业务分析依赖对业务口径的准确理解,而表名、列名与注释中并不包含全部业务知识;语义层不是 LLM 自动生成,而是业务人员出定义、LLM 辅助业务建模的共建过程,是整个 Ontology 的口径源头。业务人员提供:
「有效收入」需要在订单金额基础上扣除作废订单、员工内部单、接近免费的促销单以及特定时段的税务调整,这些规则不体现在列注释中。
「门店绩效指数」由收入增长、顾客满意度、运营效率、新客占比按固定权重加权计算,权重由运营部门定义,不在数据中。
「收入」在财务月报与运营日报中口径不同,混用会导致结果偏差。
Ontology(语义层)将上述业务知识以图谱形式固化,内容包括业务域划分、指标计算公式、口径适用场景、表间关联关系以及敏感数据标识。Agent 回答时以语义层中的定义为准。
语义层的作用包括:
口径一致:指标按业务定义计算,避免用错列或套错公式。
歧义澄清:提问存在歧义时(如只说「查收入」未说明报表类型),Agent 会先反问确认。
敏感数据隔离:敏感数据(如员工薪酬)会被识别并跳过,不进入分析。
在咖啡连锁示例中,语义层覆盖 6 个业务域、16 张表、190 个概念、77 个指标。在 Ontology 页面可以逐层查看每个概念的映射表、关联指标和业务规则;带口径警告的指标(如「商品收入」不可与门店维度成交额混用)会明确标注。
构建语义层
管理员在目标数据库完成环境准备与授权:启用
age扩展、创建semantic与图相关 schema,并为构建账号授予相应权限。授权脚本与常见问题见Ontology 使用指南。账号上建议区分构建账号(ontology_builder)与查询账号(ontology_reader),两者也可为同一账号。在客户端 Ontology 页面使用构建账号连接。
依次执行初始化 → 生成语义 → 同步 YAML → 构建。
构建完成后,查询账号即可使用语义层,日常增量更新无需重新授权。
示例:生成经营分析报告
在对话框中输入:
「查看 coffee 库下有哪些业务表,根据这些表的内容分析下对应业务,给出分析结果和业务建议。」
Agent 的处理过程如下:
读取语义层:加载 Ontology,理解数据分层与业务域结构,并检查数据权限;识别到员工薪酬属于敏感域后自动跳过。
对齐指标口径:读取绩效指数、有效收入、忠诚度等指标的定义与扣减规则,保证后续计算口径一致。
识别异常:分析中发现新客数量从 113 降至 0、各门店运营效率趋近于零等异常信号,并回查绩效指数的因子拆解与截断规则予以确认。
输出分析报告:报告先说明业务整体情况,再展开三个问题(新客归零、绩效指数失效、收入口径虚增),并附门店矩阵对比、收入扣减结构拆解、品类与渠道分析、客户分层(4–6 单客户为主力,Diamond 等级仅 5 人)。
给出分级建议:输出 20 条按优先级分级的建议,P0 修正数据口径、P1 增长、P2 门店管理、P3 数据质量治理。
最终报告包含结论、依据与行动建议。
DBA 智能诊断
功能概述
DBA 智能诊断将常见运维问题的定位过程封装为诊断场景模板,每个场景对应一类问题。选定数据源与目标数据库后,点击对应模板即可发起诊断;Agent 自动完成诊断能力调用、关联分析、结论与处置建议输出,并生成结构化报告。
只读操作:诊断仅执行只读查询,不修改任何数据。
独立会话:每次诊断生成一个独立会话,可在左侧会话列表回看历史报告。
继续交互:除点击场景模板外,也可以在对话框中直接用自然语言描述问题,由 Agent 自行选择诊断方式;诊断生成的会话同样支持继续追问与补充要求。
操作路径:左侧「DBA 诊断」→ 选择数据源 → 点击场景模板 → 勾选目标数据库(部分场景需另填 SQL 或时间范围)→「开始诊断」。
诊断场景说明
各场景分别对应一类运维问题,以下逐一说明用途与适用时机。每个场景配有演示视频,展示从点击模板到生成报告的过程。
慢查询分析
汇总指定时间段内资源消耗最高的 SQL,并检查当前是否有慢查询在运行,用于定位导致实例变慢的语句。实例整体变慢或收到资源告警时优先使用。
SQL 诊断优化
针对单条 SQL 分析执行计划,定位耗时环节(扫描、连接、聚合等),判断计划是否合理,并给出改写或索引建议。适用于单条查询变慢或新查询上线前审查。
资源使用诊断
分析 CPU、内存、IO 等资源偏高的原因,区分业务量增长与慢 SQL 影响,并给出是否需要扩容的判断。适用于资源告警后的归因与扩容决策前评估。
锁等待分析
梳理当前锁等待关系:阻塞方与被阻塞方、阻塞源持有的锁类型、被阻塞语句。查询卡住或 DDL 后其他访问挂起时,用于定位阻塞源头。
长事务诊断
查找长时间未提交的事务,判断其是否为僵死连接、是否影响 VACUUM 回收。膨胀反复出现或连接被长期占用时,可由此定位原因。
数据倾斜诊断
检查数据在各计算节点间是否分布均匀、分布键选择是否合适。个别节点持续繁忙、汇总类查询明显偏慢时,可优先排查数据倾斜。
表膨胀检查
定位存在膨胀的表并估算可回收空间,给出清理建议。表体积增长但行数未相应增加时通常为膨胀信号。
索引使用诊断
检查索引使用情况:哪些索引长期未被命中、占用空间可清理,哪些表频繁全表扫描、缺少合适索引。适用于写入变慢、存储持续增长,或需要确认索引健康度的场景。
诊断报告结构
各场景报告结构一致,包含以下部分:
结论摘要:开头说明是否存在问题、问题对象与处置方向。
明细与图表:数值结果以表格和图表呈现。
处置建议:SQL 建议基于真实表结构生成,执行前请结合实例实际情况确认;涉及有风险的操作(如终止会话、VACUUM FULL)会同时说明影响与注意事项。
诊断报告与问数结论均由模型生成,可能存在偏差;涉及变更操作(如终止会话、清理空间、改写 SQL)前,请人工核对报告中的对象与语句,确认影响后再执行。