常见問題（FAQ）

本文檔彙總了 OntiCards 使用過程中的常见問題。

一、基础使用問題

Q1: 查不到想要的數據怎麼辦？

可能原因：

• 數據卡片尚未生成完成

• 提問不够具體，系統無法準確理解

• 資料庫結構刚刚發生了變化，尚未刷新

解决方法：

1. 在"數據源管理"中查看數據卡片生成進度

1. 如有必要，點击"刷新數據源"

• × "查庫存" → √ "查詢廣州倉庫庫存低于 50 的商品"

• × "銷量" → √ "統計最近 30 天銷量超過 100 件的商品"

1. 換一種更具體的問法，例如：

Q2: 為什麼會出現"部分條件忽略"？

原因說明： 系統理解了您的問題，但在当前資料庫中找不到某些條件對應的欄位。為保證您仍然能看到有价值的結果，系統會先執行能滿足的條件。

如何减少這種情况：

• 使用您所在企業數據表中真實存在的業務欄位/口徑

• 如不確定，可以先問："商品相關都有哪些欄位可以查？"

Q3: 查詢多個資料庫時，需要做什麼組態？

您不需要寫任何復雜組態！ 只要：

1. 在系統中分別添加多個數據源

1. 在提問中自然表达您的意圖

系統會自動：

1. 找到涉及的所有數據源和數據表

1. 分別查詢

1. 根據您的語义選擇合适的整合方式（交集/並集/彙總）

示例提問：

• "在廣州和深圳都有庫存的商品"

• "彙總所有倉庫最近 30 天的銷量"

Q4: 查詢速度有點慢怎麼辦？

常见原因：

• 單個表數據量很大

• 查詢條件過于寬泛，未限製時間或範围

• 第一次查詢某些表時，系統需要額外理解表結構

建議：

• 增加時間範围限製，如"最近 30 天"、"本月"、"本周"

• 尽量加上必要的篩選條件（地區、品類別、金額區間等）

• 避免一次性查詢過多表或所有历史數據

Q5: 數據源結構變了需要我做什麼？

如出現以下情况，建議在系統中刷新數據源：

• 新增了表

• 刪除了表

• 欄位有较大調整（新增、刪除、重命名）

• 表的業務含义發生了明显變化

操作步驟：

1. 在"數據源管理"中找到對應的數據源

1. 點击"刷新數據源"

1. 系統會智能識別變化的表，只更新有變更的部分

二、功能使用問題

Q6: 什麼是數據卡片？

數據卡片是系統自動生成的"數據說明書"，包含：

• 表描述：這张表是做什麼的

• 欄位說明：每個欄位的含义和用途

• 常见查詢場景：如何使用這张表

• 業務關鍵詞：相關的業務術語

數據卡片只需生成一次，之後會自動使用並按需增量更新。

Q7: 什麼是數據盘點？需要做吗？

什麼是數據盘點： 數據盘點幫助系統理解表與表之間的關係（如訂單表和客戶表通過 customer_id 關联），从而在多表查詢時生成更準確的 SQL。

為什麼推薦做：

• 提升多表查詢準確率 20-25%

• 减少 JOIN 條件錯誤和笛卡尔积問題

• 支持跨數據源關係識別

两種盘點方式：

• 全域盘點：一鍵自動發現所有表關係，适合快速上手

• 定向盘點：對核心表精細治理，質素更高

Q8: 什麼是業務術語庫？

業務術語庫幫助系統理解您企業的業務術語，如"高价值客戶"、"核心商品"等。

示例：

術語庫是可選的，但不組態時系統只能基于數據卡片理解查詢。

Q9: 如何創建质檢規則？

OntiCards 支持三種規則創建方式：

方式一：模板模式（推薦新手） 从預設的規則模板中選擇，系統已為常见場景預置規則。

方式二：AI 模式（推薦） 用日常語言描述規則，系統自動轉換為质檢規則。

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

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

方式三：手動模式（适合專家） 直接組態規則的各項參數。

Q10: 质檢執行需要註意什麼？

1. 數據静態性：建議在業務低峰期執行，確保數據沒有實時更新

1. 執行時間：质檢可能消耗一定資料庫资源，大規模质檢建議安排在夜間

1. 執行頻率：核心數據建議定期執行，發現問題及時處理

Q11: 历史查詢記錄會保存多久？

系統支持組態历史數據的保留天數：

數據會由定時工作自動清理，也可以手動触發清理。

三、安全與權限問題

Q12: 系統如何保障數據安全？

• 訪問隔离：每位用戶只能訪問自己添加的數據源，互相不可见

• 只讀查詢：系統只執行查詢操作，不提供修改、刪除數據的入口

• 敏感資訊保護：資料庫密碼加密存储，不會出現在界面、結果或日誌中

• SQL 限製：仅允許 SELECT，配合 SQL 白名單

您可以放心使用：OntiCards 只負責"幫您查"，不會"幫您改"任何業務數據。

Q13: 可以限製用戶訪問特定數據吗？

当前版本支持：

• 系統級用戶隔离：每個用戶只能訪問自己添加的數據源

• 資料庫帳號權限：落到資料庫後由連接該數據源的資料庫帳號權限决定

後续規劃：細粒度權限體系（欄位級、行列級）將在後续版本中提供。

Q14: 可以多人共用一個數據源吗？

可以。每個用戶都可以添加自己的數據源，也可以共享數據源的連接資訊让其他用戶添加。

註意：同一數據源被多個用戶添加後，數據源結構資訊會同步更新。

四、部署與運維問題

Q15: 支持哪些部署方式？

当前推薦使用 Docker Compose 一鍵部署。

環境要求：

• Docker 20.10+

• Docker Compose 2.0+

• 2 核 CPU / 4GB 記憶體（最低）

详細部署步驟請參考：部署指南

Q16: 支持哪些作業系統？

Docker 支持的作業系統均可部署：

• Linux（Ubuntu、CentOS、Debian 等）

• macOS

• Windows（通過 WSL2）

Q17: 支持哪些資料庫？

Q18: 需要多大記憶體？

Q19: 如何升級到新版本？

# 进入项目目录
cd onticards

# 拉取最新代码
git pull

# 更新 Docker 镜像
docker-compose pull

# 重启服务
docker-compose up -d

Q20: 如何備份數據？

# 备份数据库
docker-compose exec backend tar -czf /backup/db.tar.gz /app/data/

# 复制备份文件
docker-compose cp backend:/backup/db.tar.gz ./backup/

五、性能與優化問題

Q21: 首次查詢為什麼比较慢？

首次查詢某些表時，系統需要：

1. 理解表結構和業務含义

1. 生成數據卡片

1. 建立向量索引

後续查詢會快很多，因為這些資訊會被快取。

Q22: 復雜查詢（如多表關联）不準確怎麼辦？

1. 先做數據盘點，让系統理解表關係

1. 补充數據卡片資訊，提供更多業務上下文

1. 組態術語庫，統一定义業務概念

1. 尝試將復雜問題拆成几步查詢

Q23: 如何提升查詢準確率？

1. 补充數據卡片：给表和欄位添加準確的業務描述

1. 組態術語庫：定义企業標準業務術語

1. 做數據盘點：建立表間關係

1. 優化提問方式：具體、明確、包含時間範围

六、錯誤與異常處理

Q24: 退出時看到錯誤提示，正常吗？

在部分版本中，退出登入時可能偶尔出現 "Missing Authorization token" 一類別提示。這是由于退出過程中清除登入資訊時，某些後台請求正好在執行。

不影響退出結果，也不影響數據安全，可以直接忽略。新版本已優化退出流程。

Q25: 查詢結果與其它系統不一致？

1. 確認是否使用了相同的時間範围、統計口徑和篩選條件

1. 檢查數據卡片是否已經刷新到最新表結構

1. 如仍有疑問，可將問題描述發给管理員协助排查

Q26: LLM 調用失败怎麼辦？

1. 確認 API Key 組態正確

1. 檢查網絡是否能訪問 LLM 服務商

1. 如需代理，確保 LLM_BASE_URL 組態了正確的代理地址

1. 查看後端日誌確認具體錯誤資訊

七、其他問題

Q27: 如何联系技術支持？

• 查看 問題排查指南

• 提交 GitHub Issue：https://github.com/stepll2026/OntiCards/issues

Q28: 可以自定义 Logo 和主題吗？

可以通過修改前端代碼實現自定义 Logo 和主題。

待补充：详細的自定义文檔。

Q29: 是否支持多語言？

当前版本主要支持中文界面。

規劃中：國际化多語言支持將在後续版本中提供。

Q30: 有沒有線上 Demo 可以體驗？

---

如果您的問題沒有在 FAQ 中找到答案，欢迎提交 Issue，我們會尽快回覆。