常见问题（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，我们会尽快回复。