OntiCards 用戶手冊

企業級智能數據中枢 · 让資料庫"聽得懂人話"

本手冊详細介绍 OntiCards 各功能模塊的使用方法，覆盖从登入初始化、數據源接入、智能問數、數據质檢到系統管理的全流程操作，幫助業務人員、數據分析師、數據治理專員和管理者快速上手並用好這套 AI 數據中枢。

---

一、產品概述

1.1 產品定位

OntiCards 是面向企業的 AI 數據中枢（AI Data Hub），围绕業務資料庫提供一站式能力：

📌 让企業資料庫从「只有會寫 SQL 才能使用」變成 懂業務語言就可以查詢、质檢、管理、稽核數據。

與傳統 BI 工具不同，OntiCards 以 AI 驱動的自然語言交互 為核心，让業務團隊真正"自助"用數據；又與傳統 NL2SQL 玩具不同，OntiCards 把 數據接入 → 元數據理解 → 智能問數 → 數據质檢 → 平台管理 串成一條完整的閉環。

1.2 核心能力

1.3 适用人群

1.4 主導航結構

登入後左侧主導航包含以下模塊：

二、登入與初始化

2.1 登入方式

訪問 OntiCards 後將進入登入頁面。系統提供以下登入方式：

方式一：用戶名密碼登入（預設）

• 在用戶名輸入框填寫帳戶名

• 在密碼輸入框填寫密碼（點击眼睛圖示可显示明文）

• 點击「登入」按鈕

💡 忘記密碼請联系系統管理員重置。

方式二：JWT-SSO 單點登入（企業版組態）

支持與企業內部身份系統（通過JWT的方式）打通，使用企業帳號一鍵登入。具體接入請參考 部署指南 - SSO 組態。

2.2 概覽首頁

登入成功後預設進入「概覽」首頁。

首頁包含以下區域：

• 添加數據源快捷入口：提供 8 種主流資料庫的連接卡片（PostgreSQL、MySQL、Oracle、SQL Server、Trino、SQLite、KingBase、OceanBase(MySQL)、DMBase(达梦)），點击「連接」按鈕直接進入新建數據源流程

• 數據源概覽：顶部展示当前帳號下數據源總數、數據表總數、數據卡片總數、向量索引數等核心指標

• 數據源列表：展示已添加的所有數據源卡片，显示連接狀態、數據表數、數據卡片數、最後更新時間

• 使用流程：以 8 步流程圖展示完整使用路徑（連數據源 → 自動解析 → 數據增強 → 問題修復 → 數據增強 → 建術語庫 → 智能取數 → 數據治理）

• 數據流通場景：展示 B 系統對接、API 取數、數據導出、數據訂阅讀取、數據質素監控、指標中心、數據預覽等典型場景

• 快捷操作區（右侧）：系統設置、工作空間列表、查看 API 密鑰、最近動態

2.3 首次使用流程

推薦的首次使用流程：

登录系统
   ↓
[必选] 添加数据源
   ↓
[自动] 系统生成数据卡片
   ↓
[推荐] 字段注释增强（上传 Excel 字典）
   ↓
[推荐] 创建并启用业务术语库
   ↓
[推荐] 启动数据盘点（全域或定向）
   ↓
开始自然语言问数
   ↓
[按需] 配置数据质检规则 → 启动执行
   ↓
[按需] 监控查询情况、查看历史与成本

⏱️ 完成前 4 步（登入、添加數據源、生成卡片、补充術語）通常 30 分钟內即可上手問數。

三、工作空間（數據源管理）

「工作空間」是 OntiCards 中管理所有數據源的中心。

3.1 工作空間總覽

進入「工作空間」後看到所有已添加的數據源。

顶部指標卡：

數據源卡片展示每個數據源的：

• 資料庫類別型標簽（POSTGRESQL、DM、ORACLE 等）

• 名稱與英文別名

• 資料庫類別型圖示

• 表數量、卡片數、向量索引數

• 狀態（可用 / 異常）

• 最後更新日期

• 操作按鈕：刷新、設置、详情

3.2 添加數據源

步驟 1：進入添加表單

在「工作空間」頁或「概覽」頁點击「連接」按鈕（位于添加數據源快捷區或右上角），弹出添加數據源對話方塊。

步驟 2：填寫連接資訊

步驟 3：測試連接

點击「測試連接」，系統會驗證：

• 網絡可达性

• 帳號密碼正確性

• 目標庫存在性

• 必要權限（SELECT）

測試通過後按鈕變為「請先測試連接」可继续點击保存。

步驟 4：保存

點击「請先測試連接」變為「保存」後提交，系統會：

1. 寫入數據源元數據

1. 自動拉取所有表與欄位資訊

1. 自動啟動 數據卡片生成工作（非同步執行）

1. 寫入「工作」標簽，可在「工作」頁查看進度

🔐 重要：為安全起见，建議使用 仅具備 SELECT 權限的只讀帳號。OntiCards 不執行任何 DML/DDL 操作。

3.3 支持的資料庫類別型

3.4 刷新數據源

当資料庫結構發生變化（新增表、新增/修改欄位）時，需要刷新：

1. 在數據源卡片右上角點击「刷新」圖示

1. 系統增量識別變化的表與欄位

1. 對新增的表自動啟動數據卡片生成

1. 已有的卡片會保留人工編輯結果

💡 智能增量識別：仅重生成有變化的表，避免大庫刷新耗時。

3.5 刪除數據源

1. 在數據源卡片右上角「...」選單中點击「刪除」

1. 弹出確認對話方塊

1. 確認後該數據源及其所有數據卡片、历史查詢將被清除

⚠️ 刪除操作 不可逆。如担心誤刪，可先將數據源標記為「停用」（如有此權限）。

四、數據源详情

點击數據源卡片任意位置，即可進入該數據源的详情頁。

详情頁包含以下顶部資訊和 8 個功能 Tab：

顶部資訊：

• 數據源名稱、連接狀態徽標

• 數據表數、數據卡片數、向量索引數、最後更新時間

• 「設置」按鈕：進入數據源組態

• 「執行盘點」按鈕：快速啟動數據盘點工作

8 個功能 Tab：

4.1 概覽

展示：

• 連接資訊：類別型、數據名、Schema、版本

• 表與卡片完成情况：列出所有表，每张表显示"已生成/未生成"卡片狀態

• 表內欄位分布：主鍵、外鍵、索引數

4.2 庫表

該 Tab 列出該數據源下的所有表與视圖：

• 表名：預設以資料庫原名展示

• 類別型：表（TABLE）/ 视圖（VIEW）

• 欄位數：每张表的欄位數量

• 描述：自動生成的表業務描述

• 狀態：卡片是否已生成（已填充 / 未填充）

• 操作：查看详情、生成/重新生成數據卡片

點击表名或「查看详情」：

可進入表详情頁，浏覽：

• 表的完整欄位列表（欄位名、類別型、是否主鍵、是否可空、預設值、註解）

• 欄位與數據卡片的對應關係

• 欄位在示例查詢中的常见用法

4.3 卡片（數據卡片）

數據卡片是 OntiCards 最重要的元數據資產之一。系統會為每张表自動生成一张"業務說明書"。

卡片列表展示該數據源下所有表的數據卡片，每张卡片显示：

• 資料庫類別型徽標

• 表名（如 EMP、DEPT）

• 業務描述（自動摘要）

• 關鍵欄位標簽

• 欄位數與註解數（如 7 字段 / 21 标签）

點击「查看」 進入卡片详情：

一张完整的數據卡片包含 6 個核心模塊，以 sys_region（行政區劃字典表）為例：

關于「LLM 填充」徽標：

• 卡片標題旁的 🪄 LLM 填充 識別表示該卡片由大模型自動生成

• 人工編輯 後的卡片會自動取消該徽標，刷新數據源時不會被覆盖

• 「JSON」標簽可查看卡片結構化數據，便于與外部系統對接

人工編輯：

點击「編輯」按鈕可以人工修正：

• 調整表描述

• 修改/新增欄位註解

• 增刪標簽

• 增刪關鍵概念

• 增刪适用場景

💡 小技巧：人工編輯後的卡片會被锁定，刷新數據源時不會被覆盖。系統也支持「重新生成」操作。

4.4 增強（欄位註解增強）

「增強」Tab 用于 通過 Excel 字典批量补充欄位註解，适合以下場景：

• 系統自動生成的註解不够準確

• 企業有現成的業務數據字典 Excel 檔案

• 業務專家需要批量补全大量欄位

使用流程：

1. 準備一個 Excel 檔案（.xlsx / .xls），最大 20MB

1. 第一個工作表將被作為預設字典表

1. 組態列映射：選擇哪一列是表名、欄位名、欄位註解

1. 點击「開始處理」

1. 處理完成後，對應欄位的註解會寫入數據卡片

💡 Excel 列映射可灵活組態（表名/欄位名/欄位註解對應的列），並支持一张工作表包含多個表名（不同行）。

4.5 問數（智能問數）

問數是 OntiCards 的核心交互入口。在該 Tab 下：

左侧主區域：

• 問題輸入框：支持多行輸入，按 Ctrl + Enter 換行

• 「執行查詢」按鈕：提交自然語言問題

• 模式切換：「單數據源」/「多數據源」

当前數據源卡片：明確显示本次查詢作用于哪個數據源

示例問題區（右侧「示例問句方式」）：點击即可填入示例問題，快速體驗。

多數據源模式：

切換到「多數據源」後，可同時勾選多個數據源，系統會：

1. 理解問題

1. 自動規劃需要查詢哪些數據源

1. 跨庫查詢後對齐欄位

1. 合並呈現結果

實际問數示例：

如上圖所示，在「數據质檢-測試數據源」下提問「實付金額最大的訂單資訊」：

• 顶部統計：數據表/卡片/問數單/最近問數 4 個概覽指標

• 来源選擇：明確告訴系統本次查詢作用于哪個數據源

• 問題輸入區：右下角带快捷鍵提示 Ctrl + Enter

• 右侧示例：點击示例問題即可快速填入

• 檢索結果概覽：底部显示涉及數據源數、結果條數、合並方式、關鍵欄位

如上圖所示，問數結果區主要由 4 塊組成：

4.6 知識（業務術語庫）

「知識」Tab 用于 管理與該數據源關联的業務術語庫：

• 显示該數據源已關联的術語庫列表

• 提供「添加術語庫」「創建術語庫」「刷新」操作

• 当數據源還沒有關联任何術語庫時，會以空狀態引導

📚 業務術語庫的具體創建與管理见 第六章 業務術語庫。

4.7 历史（历史查詢）

「历史」Tab 展示該數據源下的所有历史查詢記錄：

顶部統計：總查詢數、成功率、失败數、平均耗時

篩選與搜索：

• 搜索框：按問題關鍵詞或生成的 SQL 片段搜索

• 「篩選」按鈕：按時間範围、數據表、狀態篩選

• 「搜索」按鈕：執行篩選

• 「導出」按鈕：導出当前結果

查詢記錄列表：

點击「详情」查看：

查詢详情面板包含 6大塊資訊：

① 基本資訊

• 原始問題（如"所有產品列出来，按价格排序"）

• 備數據源資訊

• 生成的完整 SQL（带「復製」按鈕）

• 来源 / 涉及的數據源

• 涉及的表清單

• 融合策略（如 SINGLE_CLUSTER / MULTI_CLUSTER）

② 性能指標

③ Token 消耗

• LLM 輸入 Token

• LLM 輸出 Token

• 總計

💡 監控每次問數的 Token 消耗有助于成本管理（详见 第十一章 成本管理）。

④ 召回質素

🎯 Top1 得分 < 0.5 通常表示問題表述不够清晰或業務術語未覆盖，可結合 第五章 優化查詢結果 的建議調整。

⑤ 涉及的數據卡片：點击後可查看數據卡片的详情資訊

⑥ 查詢結果記錄：本次查詢的結果（表格形式呈現）

4.8 工作（數據盘點）

「工作」Tab 或右上角的「執行盘點」按鈕用于管理與啟動 數據盘點工作。其會分析表與表之間的關联關係，結果會用于：

• 提升多表 JOIN 查詢的準確率

• 自動生成關係卡片

• 發現潜在的數據關係

支持两種盘點模式：

• 定向盘點：選擇目標表與參考表，做精細化盘點

• 全域盘點：對全庫所有表做整體盘點

創建定向盘點工作：

操作步驟：

1. 點击「創建盘點工作」進入「定向盘點組態」頁面

1. 在「目標表（需要推薦註解）」區勾選需要补充關係的表（如 product）

1. 在「參考表（提供參考註解）」區勾選提供候選關係的表（如 shop_order、order_item）

1. （可選）上傳字典檔案（CSV / Excel 格式，需包含 column_name 與 column_comment 列）

1. 點击「執行定向盘點」，系統開始分析

查看盘點結果·表關係確認：

盘點完成後進入「盘點結果」Tab，可查看系統推薦的關係列表：

✅ 勾選確認無誤的關係，點击「確認表關係」即可生成 關係卡片。

盘點結果·關係圖谱视圖：

在「盘點結果」Tab 切換至「關係圖谱」子视圖，可以更直觀地看到表與表之間的 關係連線 和整體連接關係，便于从全局理解數據模型。

關係卡片详情：

點击某條已確認關係，可進入「關係卡片」详情頁：

關係卡片以 業務語言 解释一條關係的含义，包括：

• 關联欄位：參與關联的欄位（如 product.product_id ↔ order_item.product_id）

• 業務含义：用自然語言解释"為什麼這两张表能這樣連"

• 業務角色：明確主表（商品）與从表（訂單）的角色劃分

• 關係類別型：外鍵關联 / 同名欄位 / 業務推斷

• 推薦連接：LEFT JOIN / INNER JOIN / 全連接

• 推薦依據：模型给出該推薦的原因（如欄位類別型一致、值域分布匹配等）

• 整體置信度：模型對該關係的總體評分（如 98%）

• 适用場景：這條關係适合回答什麼類別型的業務問題

• 融合策略建議：基于主从數據展示的預聚合建議

• 联表查詢建議：可直接套用的 SQL 模板

🔍 數據盘點的更多操作細節见 第七章 數據盘點。

五、智能問數（自然語言查詢）

5.1 基本查詢

在「問數」Tab 的輸入框中輸入日常問題，例如：

• 列出 2025 年 5 月份銷售排行榜前 10 的產品資訊

• 統計今年 3 月份各部門的訂單總量

• 查詢庫存不足的商品有哪些

• 去年 12 月份什麼商品賣得最好

按回车或點击「執行查詢」，系統會：

1. 理解問題：識別意圖、涉及的時間範围、維度、指標

1. 檢索元數據：匹配相關表與欄位

1. 生成 SQL：根據資料庫方言生成可執行 SQL

1. 安全校驗：拦截非 SELECT 語句

1. 執行查詢：執行 SQL 並返回結果

1. 結果展示：以表格、圖表形式展示

5.2 多步推理查詢

OntiCards 支持 多步推理（Multi-step Reasoning）。系統會將復雜問題拆解為多個子問題，依次執行後合並結果。

示例問題：

"查詢上月銷量前 10 的商品，這些商品目前的庫存分別是多少？"

系統會拆解為：

1. 取上月銷量前 10 的商品

1. 查這 10 個商品的当前庫存

1. 合並两张結果

5.3 跨源融合查詢

前置條件：

• 已添加多個數據源

• 業務術語庫已組態並啟用

• 切換到「多數據源」模式

示例問題：

"电商系統的訂單與 CRM 的客戶檔案對比，找出哪些 VIP 客戶最近 3 個月未下單？"

系統會：

1. 解析出需要查「訂單庫」與「CRM 庫」

1. 在訂單庫中找最近 3 個月的訂單

1. 在 CRM 庫中找 VIP 客戶

1. 跨庫對齐結果

跨庫查詢示例（輸入階段）：

如上圖所示：

• 顶部統計區：數據表 3 张 / 數據卡片 3 张 / 問數單 3 個 / 最近同步 2026 年 5 月 9 日

• 多數據源開關：「多數據源」已啟用（單數據源 → 多數據源 一鍵切換）

• 可選數據源（多選）：共 14 個數據源可勾選，已選 2 個（高亮態）

• 問題輸入區：提問「查詢采購金額大于30000的訂單，包括供應商名稱、訂單日期和總金額」33 字符

• 示例問句方式（右侧）：點击可快速填入問題

跨庫查詢結果融合（輸出階段）：

查詢详情弹窗內清晰展示 跨源融合 的全鏈路：

💡 跨庫查詢的融合方式（SINGLE_SOURCE / MULTI_CLUSTER / JOIN_FUSION 等）由系統根據問題復雜度自動選擇，結果详情中可清晰看到每一步耗時。

5.4 查詢結果解讀

查詢結果頁通常包含以下資訊：

• 數據表格：查詢返回的核心數據

• 數據来源：明確標註来自哪個資料庫、哪些表

• 識別到的時間範围

• 識別的篩選條件

• 選擇的表與欄位

• 應用的業務術語

• 查詢說明：系統是如何理解你問題的，包括：

• 生成的 SQL：可一鍵復製

• 提示與告警：哪些條件被識別、哪些被忽略、原因是什麼

實际查詢結果示例：

如上圖所示，提問「實付金額最大的訂單資訊」後，系統返回：

• 檢索結果概覽：涉及 1 個數據源，返回 1 條結果，合並方式 SINGLE_CLUSTER，關鍵欄位 id

• 數據源 1（1 條）：關联的卡片為 public.orders

• 生成 SQL（高亮代碼塊，可一鍵復製 / 復製 / 解释）：

  SELECT t1."id", t1."order_no", t1."customer_name",
         t1."original_amount", t1."paid_amount",
         t1."status", t1."created_at"
  FROM public.orders AS t1
  ORDER BY t1."paid_amount" DESC
  LIMIT 1;

• 查詢結果表：展示關鍵欄位值（id / order_no / customer_name / original_amount / paid_amount / status / created_at）

💡 未組態相關術語庫時，系統會在底部给出提示「暫未匹配到相關術語庫，或術語庫功能未啟用」，可按需去 第六章 業務術語庫 創建。

5.5 優化查詢結果

如果結果不符合預期，按以下顺序排查：

1. 查看「查詢說明」：理解系統的解析逻輯

1. 补充數據卡片：表與欄位的描述越丰富，問數越準確（可手動調整或上傳字典檔案）

1. 补充業務術語庫：把"高价值客戶"等業務概念显式定义，助于系統理解專業術語名詞

• 增加時間範围限定

• 明確排序方式

• 明確輸出格式

1. 調整提問方式：更具體地表达意圖

1. 啟用數據盘點：补充表之間的關係，提升 JOIN 準確率

提問技巧：

六、業務術語庫

6.1 什麼是業務術語庫

業務術語庫（Glossary）用于 把企業內部的業務概念显式定义，让系統真正"懂業務語言"。

典型例子：

6.2 創建術語庫

進入「業務術語」頁面：

步驟：

1. 點击「新建術語庫」按鈕

• 術語庫名稱（如"銷售術語庫"）

• 行業分類別（可選）

• 描述（說明該術語庫的應用範围）

1. 填寫：

• 術語名稱：業務口徑（如"高价值客戶"）

• 別名/同义詞：可選（如"VIP 客戶""重點客戶"）

• 定义：用 SQL 表达式或自然語言定义

• 關联欄位：關联到具體的庫.表.欄位

1. 在術語庫內添加業務術語，每條術語包含：

1. 啟用術語庫（開關開啟後，問數時才會被使用）

💡 系統提供"财務術語庫""电商零售術語庫"等行業模板，可作為起點。

術語庫详情示例（财務術語庫）：

如上圖所示，進入「财務術語庫」後可看到完整的術語卡片列表，每张卡片包含：

• 術語名稱：如「營業收入」「營業成本」「毛利」「毛利率」「净利潤」等

• 狀態徽標：「已啟用」/「已停用」一鍵切換

• 別名 / 同义詞：支持多個（如「毛利潤」對應「毛利」）

• 類別型標簽：標記該術語的種類別（銷售類別 / 成本類別 / 費用類別 / 資產類別 / 風險類別等）

• 定义：用自然語言 + 公式（如「毛利率 = 毛利 / 營業收入 × 100%」）

常用财務術語速查：

6.3 在數據源中關联術語庫

創建好的術語庫需要 關联到具體數據源 才會被使用。

1. 進入數據源详情 → 「知識」Tab

1. 點击「添加術語庫」

1. 選擇目標術語庫

1. 關联後，該數據源的所有問數都會自動展開該術語庫中的概念

七、數據盘點

數據盘點是 AI 自動分析表與表之間關係 的能力，能显著提升多表 JOIN 查詢的準確率。

7.1 全域盘點

适用場景：首次接入數據源，希望系統自動發現所有表的關係。

步驟：

1. 進入數據源详情 → 「工作」Tab

1. 選擇「全域盘點」模式

1. 點击「創建盘點工作」

1. 等待系統完成（表數越多耗時越長）

1. 在工作列表中查看進度與結果

1. 完成後系統會生成 關係卡片，並自動應用到問數引擎

7.2 定向盘點

适用場景：

• 只想盘點几张核心業務表

• 系統推薦的關係不準確，需要补充參考

• 人工對部分表有明確的關係預期

步驟：

1. 進入「工作」Tab → 「定向盘點」

1. 選擇 目標表（需要补充關係的表）

1. 選擇 參考表（提供候選關係的表）

1. （可選）上傳字典檔案輔助欄位推薦

1. 點击「執行定向盘點」

1. 系統會分析並推薦欄位間的關係

1. 人工確認 / 修正後點击「確認表關係」生成 關係卡片

📌 組態頁與盘點結果视圖的详細說明见 §4.8 工作（數據盘點）。

7.3 盘點結果管理

盘點完成後，系統會生成两類別核心產物：

• 關係列表（表關係確認视圖）：列出全部候選關係，可逐條勾選確認

• 關係卡片：每條確認的關係都會生成一张「關係卡片」，用于問數時自動調用

關係卡片生命周期：

1. 生成：盘點結果確認後自動產出

1. 應用：在問數涉及相關表時被自動召回

1. 編輯：支持人工微調（業務含义、推薦連接、置信度等）

1. 回滚：關係錯誤時可刪除並重新盘點

📌 關係卡片详情與欄位說明见 §4.8 工作（數據盘點）。

八、欄位註解增強

当 AI 自動生成的數據卡片描述不够準確時，可通過 上傳 Excel 數據字典 的方式批量补充欄位註解。

8.1 準備 Excel 字典檔案

要求：

• 檔案格式：.xlsx 或 .xls

• 檔案大小：≤ 20MB

• 預設讀取 第一個工作表

• 必須包含表名、欄位名、欄位註解三列（顺序不限，可在上傳時映射）

示例：

8.2 上傳與組態

1. 進入數據源详情 → 「增強」Tab

1. 上傳 Excel 檔案

1. 組態 列映射：

1. （可選）工作表名稱：留空則使用第一個工作表

1. 點击「開始處理」

8.3 查看增強結果

處理完成後：

• 數據卡片中對應欄位的註解會被更新

• 「庫表」Tab 中欄位的描述列會显示新的註解

• 後续問數時系統會優先使用增強後的註解

💡 批處理建議：字典列名支持 A/B/C/E 等 Excel 列號表示，也支持下拉選擇具體列名。

九、數據质檢

OntiCards 內置完整的數據質素檢查能力。

9.1 規則庫管理

進入「數據质檢」頁面：

顶部指標卡：

• 規則庫總數

• 啟用的規則數

• 质檢報告總數

• 当前質素評分

质檢總覽：

環形圖展示「活跃規則」「啟用規則」「總規則數」的占比，以及 当前質素評分（如 81.1 分）。

質素維度評估：

按維度展示得分，包括：

• 有效性（如 86.9）

• 一致性（如 77.8）

規則類別型分布：多物件檢查、一致性檢查、唯一性檢查、日期檢查 等

關鍵發現：列出問題最严重的欄位

快捷入口：

• 新建規則庫

• 創建規則

• 查看報告

• 整庫報告

最近報告：展示历史報告卡片，可點击查看详情。

規則庫管理頁（點击「規則庫」Tab 進入）：

頁面采用 左右双欄布局：

• 左侧「規則庫」列表：显示所有規則庫（如「浙報-有道理-測試數據源」），含數據源/Schema 識別、規則數量與運行狀態

• 顶部篩選：按「全部數據源」「全部程度」過濾

• 新增規則按鈕：唤起創建規則弹窗

• 規則列表（每行一條規則）：展示規則名、程度（严重/警告）、AI 解析、作用範围（schema.table + 列名）、條件表达式（自動轉 SQL 預覽）、啟用/編輯/刪除三件套操作

• 右侧「质檢規則庫」详情：

💡 同一條規則可被多個數據源復用。規則級別可設置為「严重（critical）」「警告（warning）」两種，决定問題严重程度與報告評分。

9.2 創建质檢規則

步驟 1：創建規則庫

1. 在「數據质檢」首頁點击「新建規則庫」

• 規則庫名稱

• 關联的數據源

1. 填寫：

1. 保存後即可在規則庫內添加規則

步驟 2：添加規則

支持三種創建方式：

• 手動專家模式：完全手工填寫規則名、目標表/列、SQL 條件（适合復雜業務規則）

• 自然語言模式：用一句話描述需求，AI 自動生成 SQL 與組態（推薦，門槛最低）

• 單條模板建規則：从預設模板（空值檢測/一致性/唯一性/範围 等）挑選並填入參數

方式一：模板模式

从預設模板中選擇（最快捷）：

• 邮箱格式校驗

• 手機號格式校驗

• 身份證號校驗

• 金額非空檢查

• 日期範围檢查

• ...

方式二：AI 模式（推薦）

用自然語言描述規則，系統自動生成組態：

• "檢查訂單表的金額是否大于 0"

• "檢查用戶表手機號是否為 11 位"

• "檢查邮箱格式是否正確"

方式三：手動模式

直接組態規則參數：

9.3 執行质檢

1. 進入數據源 → 「數據质檢」或顶層「數據质檢」

1. 選擇規則庫或指定規則

1. 點击「開始執行」

1. 等待執行完成（根據數據量大小耗時不同）

1. 在執行結果頁查看详細情况

1. 可下載质檢報告物理檔案

9.4 質素評分

| 等級 | 分數範围 | 說明 | | -- | ------- | ------- | | 優秀 | ≥ 95 | 數據質素非常好 | | 良好 | 85 - 95 | 數據質素良好 | | 一般 | 70 - 85 | 有改進空間 | | 较差 | 60 - 70 | 問題较多 | | 差 | < 60 | 严重問題 |

評分依據：通過率、平均問題數、問題严重程度加權計算。

9.5 质檢報告

報告列表頁展示所有历史報告卡片，每张卡片显示：

• 報告 ID

• 质檢物件（數據源、Schema）

• 平均得分

• 已導出 / 未導出狀態

• 已查/總表數

• 起始/截止時間

• 操作按鈕：查看详情、下載、刪除

報告详情包含：

• 各維度評分明細

• 每张表的健康分

• 每條規則的檢查結果（通過/失败/異常數）

• 失败樣本（前 N 條）

單條報告详情頁：

進入單條報告後可见：

• 報告頭：质檢結果評分、生成時間，並提供「生成檔案」「下載報告檔案」「刷新」「刪除」4 個全局操作

• 質素評分卡（左上）：環形進度展示「良好（81.1）」等級，含總規則數（8）、通過數（0）、失败數（8）、檢測表數（0）

• 規則庫质檢執行明細：每條規則一行，欄位含狀態、規則名稱、類別型、級別（警告/严重）、目標表/列、通過/總數、失败數、详情入口

• 历史導出檔案：報告底部保留历史下載檔案，可重新下載或刪除

規則執行明細（點击「详情」展開）：

單條規則的執行详情展示 3 大區塊：

下載報告檔案（點击「下載報告檔案」按鈕生成）：

下載的報告為 Markdown 格式，按 5 個章節 組織：

1. 基本資訊 — 報告 ID / 目標數據源 / 時間範围

1. 質素概覽 — 整體評分、通過率、問題數

1. 執行明細（基于規則庫） — 各規則的失败情况

1. 失败樣例明細 — 具體命中行

1. 智能總結 — AI 自動分析本次质檢的 失效規則详情（按失效率排序）、失效規則類別型分布、典型問題樣本（如時間倒挂、金額異常、身份不一致等）、根因分析（如前端錄入缺乏強校驗、历史數據手工修改未做一致性檢查等）

十、監控中心

監控中心是系統的可觀測性仪表盘，提供系統運行監控、數據分析和性能監控的全方位能力，覆盖查詢量、成功率、Token 消耗、耗時與數據源健康等關鍵指標。

10.1 監控總覽

顶部指標卡（過去 24 小時）：

历史對比分析：

• 今日 vs 昨日：查詢量、Token、平均耗時

• 本周 vs 上周：查詢量、Token、平均耗時

24 小時訪問熱度：

折線圖展示 0-23 點的查詢量分布。

性能指標：

• 平均耗時

• 成功數

• 錯誤數

• 超時數

查詢狀態分布：

成功 / 錯誤 / 超時 三色比例。

查詢質素指標：

• 平均返回卡片數

• 平均候選卡片數

• Top10 分數

• 平均結果數

• 零結果率

查詢次數趨勢：每日查詢量柱狀圖

最近 7 天趨勢表：

10.2 趨勢分析

• 按時間範围（7 天 / 14 天 / 30 天）切換

• 顶部數據概覽（共 6 张卡）：總查詢數、總 Token、總成本、平均成功率、日均查詢、日均 Token、缺失天數

• 周環比：查詢量、Token、成本 vs 上周

• 月環比：查詢量、Token、成本 vs 上月

• 環比分析：

• 峰值谷值分析：自動識別本周期內查詢量最高 / 最低日及對應工作日

• 周/周末分布：周一~周日每日查詢量與工作日平均/周末對比

• 高峰時段 TOP 2：統計峰值查詢所在的小時段（如 10:00-11:00 / 11:00-12:00）

• 查詢量趨勢：堆叠柱狀圖（成功 / 失败 / 超時）

• Token 消耗趨勢：双線圖（Embedding / LLM）

• 详細數據表：含日期、查詢量、成功率、Token、成本、平均耗時，支持下載 CSV

10.3 實時監控

• 顶部 3 卡（最近 1 小時）：查詢數 / 平均耗時 / Token 消耗

• 当前系統狀態：連接成功數 / 連接失败數 / 正常運行徽標

• QPS 吞吐量監控：当前 / 1 分钟均 / 5 分钟均 / 15 分钟均 / 峰值

• 每分钟查詢量：折線圖實時滚動展示（暫無數據時显示「暫無數據」占位）

• 錯誤告警：錯誤率、超時率（均為 0 時显示綠色「運行狀態良好」提示）

• 數據源健康狀態：標記近期無數據源使用情况，建議查詢以生成數據源查詢請求

• 最近查詢樣例：滚動展示最近 1 小時內的查詢工作

• 自動刷新

10.4 性能分析

• 按時間範围（7 天 / 14 天 / 30 天）切換

• 各階段平均耗時卡（5 卡）：向量檢索、重排序、LLM 生成 SQL、SQL 執行、總計

• 延迟時間分布：0-500ms / 500ms-1s / 1s-2s / 2s-5s / 5s-10s / >10s 共 6 檔

• 各環節耗時占比：水平條形圖展示各階段耗時占比 + 较上周期涨跌

• 查詢復雜度分布：簡單查詢（單表）/ 中等查詢（多表）/ 復雜查詢（跨庫）占比

• 性能趨勢對比：總平均耗時 vs 上周期 + 各階段環比（向量檢索 -43.1% 等）

• 每日趨勢：按日展示平均耗時

• 數據源性能對比：每行的查詢數、平均耗時、最小/最大耗時、SQL 執行

• 查詢耗時 TOP 10：列出 Top 10 慢查詢（含問題、耗時、Token、時間）

十一、成本管理

「成本管理」模塊提供 Token 价格規則組態與成本統計能力，幫助實時跟踪查詢成本消耗、控製預算並優化模型使用策略。

11.1 Token 价格組態

支持為不同模型組件組態單价：

💡 實际單价以你采購的 LLM 服務為準，可在「系統與帳戶 → 模型組態」調整模型與對應單价。

11.2 成本統計

顶部指標卡：

• 近 30 天總成本

• 30 天總 Token

• 今日總成本

• 24 小時成本

環比變化：查詢量、Token、回應時間

查詢狀態分布

24 小時 Token 消耗分布：

按組件分類別（Embedding / Rerank / LLM）

每日成本趨勢（近 7 天）：

横向條形圖展示每日成本，右侧显示占比與金額。

24 小時查詢分布：

24 小時查詢量分布柱狀圖（按 30 分钟粒度）

數據源使用統計：

每個數據源消耗的 Token 與成本占比。

⚠️ 成本說明：成本為預估值，仅供參考。實际費用以云厂商帳單為準。

十二、系統與帳戶

進入「系統與帳戶」/「設置」：

設置中心包含 7 個子模塊：

12.1 帳戶資訊

• 頭像、昵稱

• 邮箱（用于找回密碼）

• 修改密碼

• 「保存修改」提交

12.2 用戶管理

仅管理員可见。提供：

• 用戶列表：用戶名、昵稱、角色、狀態、最後登入時間

• 搜索：按用戶名、昵稱、邮箱

• 添加用戶：右上角「添加用戶」按鈕

• 編輯用戶：每行末尾的「編輯」圖示

• 刪除用戶：每行末尾的「刪除」圖示

• 分頁：共 N 條記錄，可翻頁

角色包括：

• 管理員：拥有所有權限

• 普通用戶：受限的功能訪問

12.3 API 密鑰

用于第三方系統集成。提供：

• API 密鑰列表

• 狀態显示（啟用 / 停用）

• 「創建密鑰」生成新的 API Key

• 復製密鑰值

• 啟用/停用、刪除密鑰

使用方式：

curl -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer ak_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "查询最近 7 天的订单量",
    "data_source_id": 1
  }'

🔐 安全提示：請妥善保管 API 密鑰，定期轮換。如發現泄露，立即停用並重新創建。

详細介面文檔：API 介面文檔

12.4 模型組態

OntiCards 依赖 3 類別 AI 模型：

組態步驟：

1. 選擇模型類別型卡片

• 名稱（如 qwen3.7-max）

• 兼容 OpenAI 的 API 地址（如 https://dashscope.aliyuncs.com/compatible-mode/v1）

• API Key

1. 填寫：

1. 測試連接

1. 啟用

✅ 系統支持 任意 OpenAI 兼容介面，可對接阿裡云通义、DeepSeek、OpenAI、Azure OpenAI、Anthropic 等。

12.5 數據保密

用于組態 敏感欄位脱敏：

• 選擇數據源

• 選擇需要脱敏的欄位

• 選擇脱敏策略（部分掩碼、哈希、置空）

• 應用到問數結果展示

脱敏後的欄位：

• 在查詢結果中按規則展示

• 在導出檔案中按規則展示

• 不影響原始資料庫

12.6 鉴權日誌

記錄所有用戶操作：

• 登入 / 登出

• 數據源新增 / 修改 / 刪除

• 規則新增 / 執行

• API 調用

• 敏感操作

每條記錄包含：用戶、時間、IP、操作類別型、物件、結果。

12.7 系統設置

系統級組態：

• 預設主題（淺色 / 深色）

十三、數據安全

OntiCards 在多個層面保障數據安全：

13.1 訪問隔离

• 用戶與數據源是 多對一 關係

• 每位用戶只能訪問自己添加的數據源

• 不同用戶之間的數據源互相不可见

• 工作空間與術語庫按用戶隔离

13.2 只讀保護

• 系統 只執行 SELECT（查詢）操作

• 不提供 任何 INSERT / UPDATE / DELETE / DROP / ALTER 的入口

• 所有生成的 SQL 都經過安全校驗

• 危險關鍵詞（如 DROP、TRUNCATE）被強製過濾

13.3 密碼保護

• 資料庫密碼使用加密演算法（AES-256）存储

• 密碼 不會 出現在界面、查詢結果、日誌中

• 密碼在傳輸過程中通過 HTTPS 加密

• 切換數據源時密碼自動遮罩显示

13.4 操作稽核

• 所有用戶的關鍵操作被記錄

• 包含：時間、用戶、IP、操作類別型、物件、結果

• 稽核日誌不可篡改（只追加）

• 支持導出與第三方 SIEM 對接

13.5 敏感脱敏

• 欄位級脱敏策略

• 問數結果按策略脱敏

• API 返回結果按策略脱敏

• 不影響原始數據存储

13.6 SSO 與 MFA

• 支持 JWT Token 模式 SSO

• 可對接企業級身份系統（LDAP、AD、OAuth2.0、OIDC、CAS）

• 可啟用多因素認證（MFA）

🔐 JWT 模式 SSO 的完整對接流程见 第十五章 SSO 單點登入對接（JWT 模式）。

十四、API 與第三方集成

OntiCards 通過 REST API 暴露核心能力，支持與以下系統集成：

• AI 智能體 / Agent：把"自然語言問數"能力嵌入到 AI Agent

• RPA / 自動化平台：定時自動問數並推送結果

• BI 平台：作為 BI 的「智能問數」增強層

• 企業微信 / 钉钉 / 飞書機器人：让用戶在 IM 中直接問數據

• 自研業務系統：把"問數據"能力嵌入到業務後台

14.1 鉴權方式

使用 API Key 進行鉴權：

Authorization: Bearer ak_xxxxxxxxxxxxxxxx

14.2 核心介面

示例：自然語言問數

curl -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer ak_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "查询最近 30 天的订单量",
    "data_source_id": 1
  }'

回應：

{
  "query_id": "q_abc123",
  "status": "success",
  "sql": "SELECT DATE(created_at) AS day, COUNT(*) FROM orders WHERE created_at >= NOW() - INTERVAL 30 DAY GROUP BY day",
  "data": [
    {"day": "2026-07-27", "count": 1234},
    {"day": "2026-07-28", "count": 1456}
  ],
  "duration_ms": 412,
  "tokens": 1432
}

详細 API 文檔：API 介面文檔

14.3 Webhook

支持組態 Webhook，在以下事件触發時推送通知：

• 查詢完成

• 质檢報告生成

• 數據源異常

十五、SSO 單點登入對接（JWT 模式）

当企業已有自己的用戶體系（門戶、OA、業務系統）時，可通過 JWT 模式 SSO 單點登入 與 OntiCards 打通用戶體系：用戶在己方系統完成登入後，無需二次輸入帳號密碼，即可直接跳轉進入 OntiCards。

🔐 本章面向負責對接的開發人員。SSO 組態完成後，終端用戶的登入體驗與普通登入一致。

15.1 什麼是 JWT Token

JWT（JSON Web Token）是一種開放標準（RFC 7519），用于在各方之間安全地傳輸資訊。JWT 由三部分組成，用點號分隔：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InpoYW5nX3NhbiIsInVzZXJfaWQiOiJTWVNfVVNFUl8wMDEifQ.signature
|______________|.|__________________________________________|.______________|
    Header      |              Payload                      |   Signature
     头部        |              用户数据                      |     签名

15.2 整體流程

1. 客户后端生成 JWT Token
   ↓
2. 拼接 SSO 登录 URL（带上 token 和 redirect_url）
   ↓
3. 用户浏览器跳转到 OntiCards 的 SSO 接口
   ↓
4. OntiCards 验证 JWT、创建/关联用户、生成自己的 Token
   ↓
5. 浏览器跳转到 redirect_url，带上 OntiCards 的 Token
   ↓
6. 客户前端接收 Token，登录完成

💡 用戶自動關联：首次通過 SSO 訪問時，OntiCards 會根據 user_id + source 查找已存在用戶；新用戶自動創建，老用戶直接關联登入，無需人工開通帳號。

15.3 組態清單

對接前需要準備以下組態：

服務端組態：在 OntiCards 服務端 .env 中組態共享密鑰（详见部署指南）：

SSO_SECRET_KEY=客户提供的共享密钥

15.4 Token 生成详解

Token 生成必須由客戶後端完成（共享密鑰不能暴露在前端）。

① Header（頭部）：固定格式，聲明使用 HS256 演算法，然後進行 Base64URL 編碼：

{
    "alg": "HS256",
    "typ": "JWT"
}

② Payload（負載/用戶數據）：包含要傳递的用戶資訊：

③ Signature（簽名）：將前两部分用點號連接後，用共享密鑰簽名：

签名字符串 = Header_base64 + "." + Payload_base64
签名 = HMAC-SHA256(签名字符串, 共享密钥)

最終的 JWT Token：

JWT Token = Header_base64 + "." + Payload_base64 + "." + Signature_base64

15.5 各語言示例

Python：

import jwt
from datetime import datetime, timedelta, timezone

SECRET_KEY = "your_shared_secret_key"  # 与 OntiCards 服务端共享的密钥

payload = {
    "username": "zhang_san",
    "user_id": "SYS_USER_001",
    "nickname": "张三",
    "email": "zhangsan@example.com",
    "source": "your_app",
    "iat": datetime.now(timezone.utc),
    "exp": datetime.now(timezone.utc) + timedelta(minutes=5)  # 5 分钟后过期
}

token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")
print(token)

Java（jjwt 0.12+）：

String token = Jwts.builder()
    .claims(Map.of(
        "username", "zhang_san",
        "user_id", "SYS_USER_001",
        "nickname", "张三",
        "email", "zhangsan@example.com",
        "source", "your_app"))
    .issuedAt(new Date())
    .expiration(new Date(System.currentTimeMillis() + 5 * 60 * 1000))
    .signWith(Keys.hmacShaKeyFor(secretKey.getBytes(StandardCharsets.UTF_8)))
    .compact();

Node.js：

const jwt = require('jsonwebtoken');

const token = jwt.sign({
    username: 'zhang_san',
    user_id: 'SYS_USER_001',
    nickname: '张三',
    email: 'zhangsan@example.com',
    source: 'your_app'
}, 'your_shared_secret_key', {
    algorithm: 'HS256',
    expiresIn: '5m'  // 5 分钟后过期
});

⚠️ 生產環境 Token 生成必須在後端完成，共享密鑰絕不能出現在前端代碼中。

15.6 拼接登入 URL 並跳轉

構造 URL：

{OntiCards API地址}/sso/login?token={JWT Token}&redirect_url={回调地址}

示例：

https://api.onticards.com/sso/login?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&redirect_url=https://frontend.onticards.com/overview

跳轉代碼（生成 Token 後執行跳轉，推薦直接跳轉）：

const ssoUrl = `${API_BASE}/sso/login?token=${encodeURIComponent(token)}&redirect_url=${encodeURIComponent(FRONTEND_URL)}`;
window.location.href = ssoUrl;

15.7 回調接收 Token

登入成功後，瀏覽器會跳轉到：

https://frontend.onticards.com/overview?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

前端接收 Token 的代碼：

// 从 URL 获取 access_token 参数
function getAccessToken() {
    return new URLSearchParams(window.location.search).get('access_token');
}

const token = getAccessToken();
if (token) {
    localStorage.setItem('access_token', token);
    // 清理 URL 中的 token 参数（防止 token 泄露）
    window.history.replaceState({}, document.title, window.location.pathname);
}

// 后续 API 请求时在 Header 中携带 Token
fetch('/api/your-endpoint', {
    headers: { 'Authorization': 'Bearer ' + localStorage.getItem('access_token') }
});

15.8 錯誤碼說明

15.9 測試驗證

本地測試頁面：

• SSO 測試中心：http://localhost:9103/static/sso_test.html

• 回調測試頁面：http://localhost:9103/static/sso_callback.html

對接檢查清單：

• [ ] 生成 JWT Token（驗證三部分結構：Header.Payload.Signature）

• [ ] Payload 中包含必填欄位：username、user_id、exp

• [ ] Token 使用 HS256 演算法簽名

• [ ] 拼接 SSO 登入 URL 並測試跳轉流程

• [ ] 驗證回調頁面能接收 access_token

• [ ] 確認 Token 有效期（建議 5 分钟）

• [ ] 生產環境使用強密鑰，不要使用示例密鑰

十六、常见問題（FAQ）

Q1：登入後看不到數據源？

原因：

• 你是新用戶，還沒有添加過數據源

• 或管理員還未授權

解决：

• 在「工作空間」點击「添加新數據源」

• 或联系管理員授權

Q2：數據卡片生成很慢？

原因：

• 數據源表數量大

• 欄位數多

• LLM 回應慢

建議：

• 等待系統非同步完成（可在「工作」Tab 查看進度）

• 調整 LLM 基础對話模型為更快的模型

• 大表可分批刷新

Q3：問數結果不準？

按以下顺序排查：

1. 數據卡片質素：表與欄位的描述是否準確

1. 業務術語庫：是否定义了你問題中的業務概念

1. 數據盘點：表之間的關係是否已盘點

1. 提問方式：是否表达得足够具體

1. 查看「查詢說明」：系統如何理解你的問題

Q4：部分條件被忽略？

系統在解析時無法在当前資料庫中識別某些條件。會：

• 執行能識別的條件

• 在結果中明確標註「被忽略的條件」及原因

• 提示你如何补充（如增加數據卡片）

Q5：查詢速度慢？

建議：

• 增加時間範围限製

• 加上必要的篩選條件

• 避免一次性查詢過多數據

• 联系 DBA 優化相關表索引

Q6：Token 消耗大？

建議：

• 簡化問題描述

• 减少不必要的历史對話

• 切換到更小更快的模型

• 在「系統與帳戶 → 模型組態」中調整

Q7：API Key 泄露了怎麼辦？

立即處理：

1. 在「API 密鑰」中停用該密鑰

1. 創建新密鑰

1. 更新所有使用方

1. 檢查「鉴權日誌」看是否有異常調用

Q8：想增加新資料庫類別型？

• 開源版支持的資料庫见 §3.3

• 商業版可定製更多資料庫

• 提交 Feature Request

十七、获取幫助

文檔

線上资源

• GitHub Issues：提交 Bug 或功能請求

• 產品官網：

• 技術博客：

• 社區论坛：扫碼加入用戶交流群

商業支持

需要企業級支持、定製開發、私有化部署、行列級權限、SSO 增強等高級能力，請联系商業團隊。

---

本文檔最後更新時間：2026 年 8 月