Data Agent 语义分析

功能概述

Data Agent 在执行问数、SQL 生成等任务时，需要理解业务数据的结构和语义。语义分析功能通过自动扫描 MaxCompute 数据源表，提取表之间的关联关系、字段含义以及指标计算口径，生成结构化的语义模型（YAML 格式）。该模型以可视化图谱和源码双屏联动的方式呈现分析结果，便于直观查看数据资产间的关联关系。

通过语义分析，您可以：

• 自动梳理数据资产关系：系统自动识别表结构、字段语义和表间关联，无需手动整理。

• 生成可视化语义图谱：以图谱形式展示数据集和指标的关联关系，支持图谱与 YAML 源码的双屏联动查看。

• 提升 AI 问数准确率：将语义模型加载至 Data Agent 会话上下文（通过 /dataworks-semantic 指令），使 AI 基于业务语义生成更准确的 SQL。

• 支持人工修正与迭代：分析结果支持在线编辑和保存，修改后即时生效，无需重新运行任务。

从 MaxCompute 数据源到精准问数，语义分析端到端流程如下：

前提条件

• 已开通 Data Agent。如未开通，请参考开通流程完成开通操作。

• 工作空间内已配置可用的 MaxCompute 数据源。

• 已有可用的资源组，建议规格不少于 4 CU。

步骤一：创建语义分析任务

1. 进入 Data Agent 设置中心，在导航栏单击语义分析。

2. 在语义分析列表页，单击新建任务。

3. 在新建任务弹窗中，配置以下参数：

   配置项	说明
   名称	必填。格式需符合使用限制中所述要求。
   数据源类型	必填。当前仅支持 MaxCompute。
   业务域及关注	必填。用自然语言描述本次分析希望聚焦的业务域与表层级。例如"电商直播域，主播带货和商品销售两大维度，DWD 到 ADS 层"。 该配置有双重作用： 影响表的分析方向：指引 AI 引擎聚焦的分析方向，使其重点提取相关维度的指标和关联。 影响代码的读取范围：AI 会根据业务域描述，通过代码所在空间中的 DataWorks 文件夹结构定位相关代码和调度任务。例如填写"电商直播域"，AI 引擎会重点分析"电商""直播"等文件夹下的节点代码，而非遍历整个工作空间。 描述越详细，AI 引擎的表分析越精准、代码扫描范围越聚焦。
   代码所在空间	必填。从下拉列表中选择 DataWorks 工作空间。 该工作空间不仅是执行环境，同时作为 AI 引擎的业务知识来源。AI 引擎会读取该空间下的 SQL 脚本、调度任务和代码文件夹结构，从中提取指标计算口径与加工逻辑。例如从 SQL 代码中提取 SUM(CASE WHEN order_status='paid' THEN pay_amount END) 等计算表达式，理解指标的实际计算方式。 重要 请务必选择包含数据加工代码的工作空间。若选错工作空间，AI 无法读取真实加工代码，只能依赖字段注释推测指标含义，导致模型口径与实际不一致。
   资源组	必填。选择用于运行任务的资源组。
   重点分析表	必填。从级联选择器中选择需要重点分析的表——左栏展开 MaxCompute 项目，右栏勾选具体表，最多 30 张表。模型会聚焦分析这些表的结构和关联关系。
   引用文件	选填。支持上传文件或输入文件 URL 两种方式使用外部参考资料。

4. 填写完成后，单击确定。系统提示"任务已创建"后，列表自动刷新。

步骤二：运行语义分析任务

任务创建完成后，可通过以下方式运行：

1. 在语义分析列表页，找到目标任务，在操作列单击运行。

2. 系统弹出"运行已提交"提示，并自动打开任务详情弹窗。

任务提交后，系统将在后台执行语义分析。运行耗时取决于分析表数量和数据量，通常需数分钟。AI 引擎从以下两个维度并行分析：

• 维度一：读取代码所在空间中的 SQL 脚本与调度任务。根据业务域描述，通过 DataWorks 文件夹结构定位相关代码，解读 SQL 中的真实指标计算口径和表间加工关系。

• 维度二：扫描重点分析表的元数据。提取每张表的字段业务含义、同义词、表间层级关系、业务指标定义、派生指标公式以及示例问答。

两个维度的分析结果交叉验证后，合并为一份完整的语义模型。

步骤三：查看任务详情与运行状态

单击任务列表中的任务名称，即可打开任务详情弹窗。任务详情包含以下页签：

步骤四：查看与编辑语义模型

前往运行历史页签，对状态为"成功"的运行记录单击查看结果，即可打开语义模型结果查看器。

结果查看器提供图谱与源码的双屏联动视图：

• 语义模型图谱：以可视化方式展示数据集之间的关联关系。图谱中的节点代表数据集或指标，边代表它们之间的关联关系。单击图谱中的节点或边，右侧源码编辑器会自动滚动到对应行并高亮。

• YAML 源码编辑器：展示语义模型的 YAML 源码。源码顶层结构包含数据集定义、字段描述、ai_context系等信息。移动光标浏览源码时，左侧图谱会自动高亮并居中对应的节点或边。

结果查看器还支持以下功能：

• 全屏查看：单击全屏按钮可全屏查看图谱或源码。

• 编辑与保存：单击编辑进入编辑模式，修改 YAML 内容后可单击保存写回后端。保存后修改立即生效，无需重新运行任务。如需撤销修改，可单击重置恢复至上次保存的版本。还支持对比修改查看差异。

语义模型 YAML 结构详解

AI 语义分析引擎生成的语义模型采用 YAML 格式，其顶层结构包含四大核心模块：

以下为简化的 YAML 源码示例：

semantic_model:
  - ai_context:
      instructions: |
        电商直播数据分析域。涵盖主播带货和商品销售两大分析维度。
        数据分层：ODS → DWD → DWS → ADS
        分区字段为 dt，金额单位均为人民币元
      few_shots:
        - question: 昨天 GMV 最高的前10个主播是谁？
          sql: |
            SELECT anchor_name, gmv
            FROM ads_ctlive_anchor_stats
            WHERE stat_period = '1d'
            ORDER BY gmv DESC LIMIT 10;

    metrics:
      - name: GMV
        description: 成交总额（元）
        ai_context:
          synonyms: [成交额, 销售额, 交易额]
        expression:
          dialects:
            - dialect: MaxCompute
              expression: SUM(gmv)

    metric_formulas:
      - name: 客单价
        description: 平均每单成交金额（元）
        formula: GMV / 订单数

    datasets:
      - source: ads_ctlive_anchor_stats
        description: ADS-主播成交统计表
        fields:
          - name: anchor_name
            type: string
            description: 主播昵称
            synonyms: [主播, 主播名, 达人]
          - name: gmv
            type: double
            description: 成交总额（元）
            metric: true
            synonyms: [成交额, GMV, 销售额]

步骤五：在 Data Agent 中加载与使用语义模型

通过前述步骤，您已在控制台成功生成 YAML 语义模型。但该模型仅存储于服务端，Data Agent 会话不会自动加载。您需要在 Agent 会话中主动加载语义模型，使 AI 在回答时引用模型中的业务知识。

操作步骤：

1. 打开 新版 Data Agent，进入对话窗口。

2. 在聊天输入框中输入 /dataworks-semantic 并发送。

3. Agent 自动执行：环境检查 → 列出可用任务 → 下载 YAML 产物 → 注入当前会话 AI 上下文。

4. 确认加载成功后，即可基于语义模型进行问数、SQL 生成等操作。

加载语义模型后，以下场景的回答质量会显著提升：

场景示例：电商直播域端到端实践

以下以电商直播场景为例，展示从创建任务到精准问数的完整流程。

1. 创建任务（步骤一）

在语义分析页面单击新建任务，填入以下配置：

2. 运行任务（步骤二）

单击运行后，AI 语义引擎将自动执行以下分析：根据"电商直播域"定位工作空间中对应文件夹的 SQL 脚本 → 从代码中提取真实指标计算口径（例如发现 gmv = SUM(CASE WHEN order_status='paid' THEN pay_amount END)）→ 扫描 4 张表的元数据与字段关系 → 识别 ADS / DWS 层级关联 → 生成包含指标定义、派生公式和示例 SQL 的结构化 YAML 模型。

3. 查看与编辑模型（步骤三、四）

任务运行成功后，在任务详情页打开语义模型页签。您可以通过图谱视图直观确认表间关联是否合理，同时在 YAML 编辑器中微调指标定义或补充业务说明。确认无误后保存即可。

4. 加载到 Data Agent（步骤五）

进入 Data Agent 会话，依次执行 /dataworks-semantic download <任务名> 和 /dataworks-semantic index <任务名> 将模型下载到本地并构建索引。此后该会话中的所有问答都将基于语义模型进行精准回答。

5. 验证效果

加载完成后，用同样的问题对比加载前后的回答质量：

用户提问："昨天 GMV 最高的前 10 个主播是谁？"

-- AI 猜测表名和字段
SELECT host_name, total_amount
FROM live_stream_sales
WHERE date = '2026-07-27'
ORDER BY total_amount DESC
LIMIT 10;

-- 基于语义模型生成
SELECT anchor_name, gmv
FROM ads_ctlive_anchor_stats
WHERE stat_period = '1d'
ORDER BY gmv DESC
LIMIT 10;

用户提问："近 30 天各品类的客单价是多少？"

-- AI 不理解"客单价"的口径
SELECT category, AVG(price) AS avg_price
FROM products
GROUP BY category;

-- 语义模型知道：客单价 = GMV / 订单数
SELECT cate_level1_name,
  SUM(gmv) / SUM(order_cnt) AS avg_order_value
FROM ads_ctlive_item_stats
WHERE stat_period = '30d'
GROUP BY cate_level1_name
ORDER BY avg_order_value DESC;

加载语义模型后，AI 在回答问题时会自动参考模型中的 ai_context（业务指令）、metrics（指标定义与同义词）、metric_formulas（派生公式）和 datasets（表与字段映射），从"推测"转变为"基于知识的精准生成"。

常见问题

Q: 任务运行失败可能是什么原因？

A: 任务运行失败通常由以下原因导致：

• 资源组规格不足：资源组规格低于 4 CU 时，任务可能因资源不足而失败。建议选择规格不少于 4 CU 的资源组。

• MaxCompute 项目权限不足：执行语义分析的工作空间需要对目标 MaxCompute 项目具备读取权限。请确认工作空间与 MaxCompute 项目的绑定关系及权限配置。

• 数据量过大：单次分析涉及的表过多或数据量过大可能导致超时。建议减少重点分析表数量后重试。

Q: 编辑 YAML 后需要重新运行任务吗？

A: 不需要。在结果查看器中编辑 YAML 并保存后，修改立即生效。下次通过 /dataworks-semantic 下载时会自动获取最新版本。

Q: 在 Data Agent 中使用语义模型时提示 token 过期？

A: 运行 /dataworks-semantic check 检查环境。如果提示认证相关错误，请刷新认证信息后重试。

Q: 下载时提示"local edits detected"怎么办？

A: 说明上次下载后 YAML 文件被修改过（哈希值不匹配）。如需覆盖本地修改，添加 --force 参数强制下载。建议先将修改内容备份到其他位置。

相关文档

• Data Agent 费用

• 新版 Data Agent