DataWorks：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