English | 简体中文 | 官网 | 视频介绍 | 更新日志 | 社区与支持
面向 AI Agent 与数据应用的开源语义层和受治理查询引擎。
KnowFlow Analytics 把指标、维度、业务术语、维度值、实体关系和聚合口径维护成一份经过审核、可版本化的语义模型。同一份模型可以服务自然语言问数、AI Agent、结构化查询 API、嵌入式数据应用和回归评测，不需要为每个入口重复维护 Prompt 与 Few-shot。
LLM 只负责把用户意图表达成由业务名组成的语义 SQL（S2SQL）。真正访问数据库的物理表、字段、Join、聚合和参数，由系统根据已发布的语义模型确定性编译。
开源的是语义建模层与受治理查询引擎，包含建模工作台、AI 一键建模、发布与版本回滚、发布前验证和词汇缺口回流，以及底下那套 S2SQL 编译、治理关卡、只读 Guard 和查询 API。
面向业务用户的问数助手、报表和多用户权限不在开源版内，它们属于商业版 KnowFlow。两者共用同一份语义模型与同一个查询引擎，详见开源版与商业版。
准备 Docker，以及可访问的 OpenAI-compatible Chat / Embedding 模型。Compose 会启动 Analytics 和它自己的 catalog PostgreSQL；模型端点在「设置」里填写，要分析的业务库在「数据库连接」里添加，支持多个。也可以直接上传 Excel，它会落库成一个数据源。
git clone https://github.com/knowflow-ai/analytics.git
cd analytics
docker compose -f docker-compose.oss.yml up -d打开 http://localhost:9395，按页面提示填写业务数据库和两个模型端点。
默认镜像是 knowflowai/analytics:v0.0.5，支持 linux/amd64 和 linux/arm64。
典型的 Text-to-SQL 应用把 Schema、业务说明和少量 SQL 样例拼进 Prompt，让模型直接生成物理 SQL。它可以快速完成单点验证，但业务复杂后会遇到三个问题：
- 业务含义散落在 Prompt 和 Few-shot 中。不同 Agent、页面和服务各维护一份，很快产生口径漂移。
- 每次提问都要重新推断指标、聚合、Join 和事实粒度。Prompt 可以引导模型，却不能强制这些规则始终成立。
- 修复通常只覆盖当前问法。换一种表达、组合两个已有指标，或者更换模型，原来的样例未必继续有效。
语义层把这类知识从 Prompt 中拿出来，变成独立于问题和模型的受治理资源：
| 关注点 | 直接 Text-to-SQL | KnowFlow Analytics |
|---|---|---|
| 业务定义 | 写在 Prompt、文档片段或 Few-shot 中 | 指标、维度、术语和值字典进入版本化 Catalog |
| Join 与粒度 | 模型根据 Schema 临时推断 | 人工确认关系基数，发布时冻结安全路径和事实根 |
| SQL 生成 | LLM 直接输出物理 SQL | LLM 输出业务名 S2SQL，Translator 编译参数化物理 SQL |
| 歧义处理 | 改 Prompt、增加样例或静默选一个 | 展示业务候选，人工确认；确认可在严格上下文内记忆 |
| 复用范围 | 通常绑定某个 Agent 或问数入口 | 同一 Release 服务 Agent、UI、API、评测和其它数据应用 |
| 变更控制 | Prompt 修改后整体行为可能漂移 | Candidate Revision 审核、校验、发布、回滚 |
| 失败策略 | SQL 合法就可能执行 | 成员、路径、聚合或版本无法证明时 fail closed |
这里的“泛化”不是让模型在未知业务里猜得更大胆，而是在已经治理的业务边界内复用稳定语义：
- “销售额”“营收”“GMV”可以映射到同一个指标，新增问法通常只需补业务词典，不用重写整套 Prompt。
- 已定义的指标、维度、过滤值和时间口径可以自由组合，覆盖建模时没有逐题枚举的问题。
- Agent、问数页面和结构化 API 读取同一份 Release，不会因为入口不同而使用不同口径。
- 更换 Chat 模型后，指标公式、Join 路径、聚合方式和执行边界仍由语义层控制。
Few-shot 仍然有价值，但它适合帮助模型学习表达形式，不应承担业务事实和执行规则的所有权。
Cube Core 把指标、维度、Join 和访问规则定义一次，再通过 SQL、REST、GraphQL 提供给 BI、应用和 AI Agent。Wren AI 也通过 MDL 与 context layer，让业务定义、样例、记忆和治理信息能够被 Agent 复用。
KnowFlow Analytics 与它们遵循相同的基本方向：语义模型是可复用的数据基础设施，不是某次 LLM 调用的附件。 当前项目更聚焦以下产品选择：
- AI 辅助完成初始建模，但产出始终是可逐项审核的草案。
- LLM 不生成最终物理 SQL，执行 SQL 由语义模型确定性编译。
- 发布前同时检查模型结构和真实数据，包括关系基数、扇出、主标识与指标样本。
- 自然语言有歧义时显式确认，并把人工选择保存为有版本和上下文边界的记忆。
- 每次查询都有固定阶段诊断，可导出脱敏 Markdown 报告。
KnowFlow Analytics 的数据源目前是 PostgreSQL、MySQL 与上传表格。它不是 Cube 或 Wren AI 的协议实现，也不要求引入它们的运行时。
graph LR
DB["PostgreSQL"] --> C["受治理语义 Catalog"]
C --> R["不可变 Release"]
R --> A["AI Agent / Tool"]
R --> N["自然语言问数"]
R --> S["结构化查询 API"]
R --> E["嵌入式数据应用"]
R --> Q["评测与质量门禁"]
- AI Agent：Agent 通过资源 API 获取业务定义并发起受治理查询，不需要自己拼物理表、列和 Join。
- 自然语言问数：内置 UI 负责建模、发布前试问、线上提问、澄清和诊断。
- 结构化查询：调用方直接提交已治理的指标、维度和过滤条件，跳过自然语言理解。
- 嵌入式应用：业务系统可以把 Analytics 作为独立查询后端，复用同一套指标和权限边界。
- 质量工程：Golden Suite、真实数据质量报告和查询失败记录都绑定同一 Revision / Release。
这也是语义层相对单点 Text-to-SQL 的主要价值：建模成本只付一次，治理结果可以被多个消费者长期复用。
目录包含 Model、Relation、Metric、Dimension、Term 和 DimensionValue。业务名称、别名、指标公式、默认聚合、可加性、时间轴和真实维度值都属于模型数据，而不是藏在 Prompt 里。
AI 可以建议实体名、字段角色、指标、维度和别名。建议先进入 Candidate Revision；覆盖人工内容的建议默认不选中，必须经过审核、结构校验和发布。
每个查询作用域冻结一个事实根、明确的指标与维度成员，以及从事实根出发的安全 Join 路径。用户维护语义目录，不需要再维护第二套“主题”配置。
作用域不在提问时由路由器挑选。最终 LLM 看到候选作用域成员的并集并写出业务名 S2SQL，编译器再逐个真实作用域尝试确定性翻译：恰好一个翻得出就绑定它，零个说明这个问题跨了事实根，多个则按粒度收敛取最粗的那个。模型提议、编译器裁定——校验比选择容易，而翻译本身已经在验证成员归属、冻结路径可达性和全部治理规则。
自然语言问题
→ Mapper：说法映射到已发布业务名
→ Parser：生成只包含业务名的 S2SQL
→ Corrector：校验成员、过滤、聚合和确认义务
→ Translator：绑定冻结路径，编译参数化物理 SQL
→ Guard：只读 AST 白名单、结果上限和执行超时
→ PostgreSQL
如果 S2SQL 引用了未发布名称、丢失已确认过滤值、跨越不安全关系或没有落实人工选择，查询不会进入数据库。
澄清是兜底，不是常规路径。普通问数最多展示一张业务确认卡，只在同名语义元素、或同一短语落到跨事实根的多个指标时出现，不暴露内部 Scope、Dataset 或语义 ID。人工选择必须在最终 S2SQL 里真的被用上，否则这次查询不执行。
问不出来的说法不会就这么算了。拒答、澄清、模型自己猜的成员、不认识的取值，以及用户的点赞点踩，都进同一个词汇缺口收件箱，按说法聚合后回流到建模端：补一条业务词典，下一次同样的问法就能直接答。这比把选择记进一张记忆表更可控——词典是可审核、可发布、对所有人生效的语义资源，记忆不是。
详细设计见 docs/semantic-confirmation-and-scope-routing.md。
- 结构化 Playground 用来验证模型与 SQL 翻译。
- 自然语言 Playground 用来验证别名、映射和完整查询链。
- 数据质量报告使用真实只读查询检查主标识、关系基数、扇出、指标样本和可达性。
- 一键诊断展示固定阶段时间线，并导出脱敏 Markdown。
诊断详细合同见 docs/one-click-query-diagnostics.md。
| 类别 | 当前能力 |
|---|---|
| 数据源 | 多个 PostgreSQL / MySQL 连接、上传表格（Excel 落库成数据源）、按项目绑定 |
| 数据建模 | Schema 快照、漂移检测、关系画布、人工基数确认、SQL Model |
| AI 建模 | 实体/字段命名、角色分类、指标与维度草案、别名和值字典建议 |
| 指标治理 | 原子/派生指标、默认聚合、展示格式、半可加约束、指标时间轴 |
| 查询编译 | S2SQL、冻结 Join 路径、参数化 SQL、只读 Guard |
| 高级查询 | Set operations、同比/环比、滚动比率、组内占比 |
| 歧义治理 | 生成后确定性反推作用域、同名冲突确认卡、跨事实根指标短语澄清 |
| 版本管理 | Revision、ETag、不可变 Release、语义索引绑定、切换到任意已发布版 |
| 问数引擎 | 流式阶段推送、结果解读、文本 S2SQL 下钻续跑、默认时间窗可见可撤（引擎能力，开源版的入口是「问数验证」，对话式问数页在商业版） |
| 反馈闭环 | 词汇缺口收件箱（六类）、按说法聚合、一键补业务词典 |
| 运行配置 | 助手级覆盖：行数、时间窗、多轮改写、自洽次数、模型与温度 |
| 质量保障 | 双模式 Playground、Golden Suite、真实数据质量报告 |
| 可观测性 | 固定查询时间线、失败记录、脱敏 Markdown 诊断导出 |
| 部署 | 独立 Web UI、Docker Compose、OpenAI-compatible 模型端点 |
上表是开源版自带的能力。面向业务用户的问数助手、报表和多用户权限见开源版与商业版。
开源版给的是建模能力和查询引擎。它自带一套完整的建模工作台，四步走完就能发布一份可用的语义模型，并在「问数验证」里用自然语言试问、逐题核对结果。
它不提供面向业务用户的问数产品面。日常提问的对话页、把回答钉成报表、按人分配数据权限，这三件事在商业版 KnowFlow 里。
| 开源版 | 商业版 | |
|---|---|---|
| 建模工作台（数据源、语义建模、问数验证、问数反馈） | 有 | 有 |
| AI 一键建模、别名与值字典建议 | 有 | 有 |
| 发布、版本回滚、发布前质量报告 | 有 | 有 |
| S2SQL 编译、治理关卡、只读 Guard、查询 API | 有 | 有 |
| PostgreSQL / MySQL / 上传表格，多数据源 | 有 | 有 |
| 词汇缺口收件箱、Golden Suite、诊断导出 | 有 | 有 |
| 问数助手：对话式提问、多轮追问、下钻、结果解读、会话分享 | 无 | 有 |
| 报表：把回答钉成卡片、按项目归档、刷新重跑、导出 Excel | 无 | 有 |
| 项目授权与数据范围：多用户 RBAC、行级与列级权限 | 无 | 有 |
| 与知识库、Agent、企业账号体系打通 | 无 | 有 |
| 登录 | 单用户加可选共享口令 | 企业账号、LDAP / OIDC、企业微信 |
开源版能问数，入口在建模工作台的「问数验证」里，用途是发布前逐题核对模型建得对不对。商业版把同一个引擎接到面向业务用户的产品面上。
业务同事直接用中文提问，回答卡上写清系统怎么理解的，下面可以继续下钻。
同比环比按带符号的增长率展示。紫色那个 chip 是系统自己补的理解，它把「销售」认成销售金额，并且把这件事说了出来。
满意的回答钉成卡片，按项目归档成报表，随时刷新取最新数字，可整页导出 Excel。
商业版还提供项目级授权与行列级数据范围，同一个项目里不同的人看到的行和列由授权决定。
想试用或了解商业版，可以走官网，或者加微信 skycode007 备注「问数」。
scripts/product_accuracy_campaign.py 走与浏览器相同的鉴权 API：原始数据库 → 导入 → 关系确认 → AI 建模 → 发布 → 发布后加载隐藏问题 → 自然语言试问 → 与参考 SQL 结果逐行比较。
0.0.2 最近一次实测是改最终 Prompt 目录格式时的对照实验：一个数据集、22 道中文问题，每道都走完整问数链路，两种格式结果有分歧时补跑到 n≥4。
| 逐条字典（旧） | 竖线表（新） | |
|---|---|---|
| Prompt 均值 | 6161 字符 | 4744 字符 |
| 端到端耗时 | 14.8 s | 11.7 s |
| 22 题结果一致 | 20 / 22 | 20 / 22 |
两道分歧题都是新格式更好。「卖得最好的产品是哪个」6/6 稳定答对；「各城市有多少家门店」4/4 且 6 秒返回，而旧格式该题首次模型调用连续超时 30 秒，两次退到 Rule 兜底给出一份门店名单——一个看起来正常的错误答案。
这次实验也暴露了一个尚未修复的静默错答：「平均每单销售金额」模型写成 AVG(销售金额)，算出的是明细行均值 49.37，按单应为 98.66，六道治理关全部放行。粒度曲解不在现有任何一道关的判据里，已记入待办。
这是一个数据集上的对照实验，不是通用 Text-to-SQL 基准结论。项目更关注“静默错答”而不只是完成率：拒绝或澄清对用户可见，一个看起来正常的错误数字不可见——上面那个 AVG 正是后者，也是下一步要补的判据。
连接数据源
→ 导入表并确认实体关系
→ AI 生成建模草案
→ 审核指标、维度、术语和值字典
→ 运行结构校验与真实数据质量报告
→ 用两个 Playground 试问
→ 发布不可变 Release
→ Agent、UI 或 API 开始查询
建模工作台分四页：数据源、语义建模、问数验证、问数反馈。语义建模里的常驻导航是实体与关系、业务词典、目录总览；查询作用域只在高级诊断中展示。
| 变量 | 默认值 | 作用 |
|---|---|---|
KNOWFLOW_ANALYTICS_IMAGE |
knowflowai/analytics:v0.0.5 |
要运行的 Analytics 镜像 |
KNOWFLOW_OSS_BIND_ADDRESS |
127.0.0.1 |
宿主机监听地址 |
KNOWFLOW_OSS_PORT |
9395 |
宿主机端口 |
CATALOG_DB_PASSWORD |
analytics |
内置 catalog PostgreSQL 密码，必须 URL-safe |
KNOWFLOW_OSS_ACCESS_PASSWORD |
空 | 独立版共享访问口令 |
远程部署时再把监听地址设为 0.0.0.0，同时配置访问口令、HTTPS 反向代理和防火墙：
KNOWFLOW_OSS_BIND_ADDRESS=0.0.0.0 \
KNOWFLOW_OSS_ACCESS_PASSWORD='replace-me' \
docker compose -f docker-compose.oss.yml up -dKNOWFLOW_OSS_ACCESS_PASSWORD 是单用户共享口令，不是多用户认证或 RBAC。
docker compose -f docker-compose.oss.yml logs -f analytics
docker compose -f docker-compose.oss.yml restart analytics
docker compose -f docker-compose.oss.yml down # 保留数据状态存放在两个 volume：catalog-data 保存语义资源、Revision 和 Release，analytics-data 保存独立版设置。它们不复制业务库数据。
容器连接宿主机 PostgreSQL 时使用：
postgresql://user:password@host.docker.internal:5432/your_database
更多运行参数
需要 Python 3.12+、Node 18+、uv 和 PostgreSQL。
uv sync --python 3.12 --all-extras
(cd web && npm install)
createdb analytics_catalog
cp .env.oss.example .env
# 编辑 KNOWFLOW_OSS_CATALOG_DATABASE_URL
set -a; source .env; set +a
# 终端 1
uv run knowflow-analytics-oss
# 终端 2
cd web && npm run dev自己构建独立镜像：
docker build -t knowflowai/analytics:local .
KNOWFLOW_ANALYTICS_IMAGE=knowflowai/analytics:local \
docker compose -f docker-compose.oss.yml up -d测试：
uv run pytest
uv run ruff check src tests
(cd web && npx vitest run)src/knowflow_analytics/
├── api.py # 项目、Revision、Catalog、发布和查询 API
├── application.py # 用例编排与产品不变量
├── catalog/ # PostgreSQL 持久化与 Release
├── modeling/ # 内省、AI 建模、质量报告和 Scope 编译
├── query/ # Mapper、Parser、Corrector、澄清与诊断
├── semantic/ # 语义索引与 S2SQL Translator
├── execution/ # SQL Guard 与只读 PostgreSQL 执行
├── gateways/ # Chat、Embedding、Knowledge 网关
└── oss/ # 独立版配置、鉴权和静态托管
改查询管道前，先阅读 tests/unit/test_query_stage_pipeline.py、tests/unit/test_textual_s2sql_pipeline.py 和相关设计文档。自然语言与结构化查询是两条独立合同，不能为了实现方便合并。
- 物理 SQL 参数化，并经过 AST 白名单、只读事务和执行限制。
- 查询结果直接返回调用方，不会再发给模型生成总结。
- 建模时可采样低基数维度值，用于值字典和别名建议；可通过配置关闭。
- 普通业务答案不暴露内部 Scope、Dataset、语义 ID 或物理 SQL。
- 诊断导出会脱敏密码、API key、连接串凭据和确认 token。
- 独立版配置文件权限为
0600；.env、local.env和data/均被 Git 与 Docker 构建上下文排除。
生产环境仍应使用专用只读数据库账号，并在服务外配置网络隔离、TLS 和正式身份认证。
- 数据源支持 PostgreSQL、MySQL 与上传表格。MySQL 的五种时间粒度、同比自连接与占比窗口都在真库上与 PostgreSQL 逐行比对过；其它方言尚未支持。
- 独立版是单用户 + 可选共享口令，不提供多用户 RBAC 或行列权限；需要按人分配数据范围请看商业版。
- AI 建模在请求周期内同步执行，大型 Schema 需要分批导入或调高超时。
- 同一实体存在两条等长最短 Join 路径时，该实体不会自动进入作用域。
- 既无主标识也无业务度量的事件/桥接表不会成为事实根。
- 多轮改写默认开启，只读取同一会话、Release 和业务范围内上一轮成功的语义查询，并且只能补口径、不能替用户新增分组维度。
- 确认记忆已在
0.0.2移除。人工选择只在当次查询内生效，长期修复走业务词典。 - 结果解读默认关闭；它只允许复述结果里出现过的数字，不做任何模型计算。
- 官网：www.knowflowchat.cn
- 视频介绍：两分钟看完 KnowFlow Analytics（微信视频号）
- 微信公众号：KnowFlow 企业知识库
- 交流群：加微信
skycode007，备注“加群” - 更新日志：CHANGELOG.md
- 问题反馈：GitHub Issues
- KnowFlow 社区：社区与支持
Issue 和 Pull Request 都欢迎。涉及 Mapper、Parser、S2SQL、Corrector、Translator、路由或执行的改动，请说明所影响的阶段、输入输出和失败行为，并补对应契约测试。不要在运行时代码中加入面向某个数据集、业务名或基准题措辞的修复分支。
KnowFlow Analytics 使用 Apache License 2.0。