目录

速览 / 关于本指南1. 产品概述2. 核心概念3. 系统架构4. 环境准备5. 安装与部署6. 初始化配置7. 数据源接入8. 语义建模9. 数据集与助理10. Chat BI 使用11. Headless BI 使用12. 扩展开发 SPI13. 权限与安全14. 最佳实践15. 常见问题 FAQ16. API 参考17. 团队落地提示18. 参考资源

SuperSonic 全面使用指南

腾讯音乐开源的下一代 AI+BI 平台，统一 Chat BI（LLM 驱动）与 Headless BI（语义层驱动）两大范式。

本指南基于官方文档、GitHub 仓库（tencentmusic/supersonic）及社区实践整理，覆盖从概念、架构到部署、建模、使用与排错的全流程。

License: MIT Java / Spring Boot React + ECharts Chat BI + Headless BI 中文友好

0速览 / 关于本指南

本指南面向数据工程师（建模者）与业务分析师 / 业务用户（使用者）两类角色，帮助你把 SuperSonic 从“装起来”到“真正用起来”。

30 秒理解

用自然语言问数据库，系统依托语义层把问题转成受治理的 SQL，返回表格 + 图表。

两条主线

Chat BI：业务人员对话式分析；Headless BI：工程师构建统一语义模型与权限。

最低门槛

Docker 一条命令起服务，自带样例模型，开箱即用。

生产关键

语义模型质量 > 模型本身；三级权限（数据集/列/行）保障安全。

版本提示：SuperSonic 持续迭代，技术栈存在代差——最新版（v0.9.x+，2025 年）使用Java 21 + Spring Boot 3.3.9；较旧版本使用 Java 11 / Spring Boot 2.7.2。本文以最新版为主，涉及版本差异处会标注。请按你实际下载的 Release 包对应版本准备 JDK。

1产品概述

1.1 什么是 SuperSonic

SuperSonic 是腾讯音乐开源的新一代 AI+BI 平台，核心思路是把两种数据分析范式融合到同一个可生产化系统中：

• Chat BI：基于大语言模型（LLM），用户用自然语言提问，系统自动生成 SQL 并以合适图表可视化结果。
• Headless BI：基于语义层（Semantic Layer），由分析工程师构建统一的指标 / 维度 / 标签定义，通过开放 API 暴露一致的数据语义。

二者融合带来两个关键收益：① 把业务术语、列值等数据语义注入 Prompt，显著降低 LLM 幻觉；② 把 JOIN、公式等复杂 SQL 语法从 LLM卸载到语义层，降低生成复杂度。

1.2 核心特性

双范式开箱即用

内置 Chat BI 与 Headless BI 两套界面，无需二选一。

语义增强

将业务术语、列值注入 Prompt，减少幻觉。

查询简化

复杂 SQL 由语义层生成，LLM 只产出语义查询（S2SQL）。

规则 + LLM 混合解析

内置基于规则的语义解析器，便于演示与集成测试。

对话体验

输入联想、多轮对话、查询后问题推荐。

三级数据权限

数据集级 / 列级 / 行级访问控制。

可扩展架构

基于 Java SPI，可自定义解析器、校正器、执行器与插件。

多数据源

MySQL、PostgreSQL、ClickHouse、Hive、Presto、Trino、DuckDB 等。

1.3 适用场景

• 非技术业务人员用自然语言即问即答，无需写 SQL。
• 数据团队构建受治理的语义层，确保各部门指标口径统一。
• 把对话式问答嵌入现有报表 / 仪表盘，为 BI 增加按需分析能力。
• 用交互式 AI 探索替代传统“提需求→等开发”的报表流程。

许可证：MIT，可放心用于商业与内部项目。

2核心概念

2.1 Chat BI 与 Headless BI

一句话：Headless BI 负责“把数据讲清楚”（定义与治理），Chat BI 负责“让人问得方便”（对话与可视化）。

2.2 语义层（Semantic Layer）

语义层是一层逻辑数据模型，把物理表、字段抽象为业务能读懂的“指标 / 维度 / 标签”，并定义它们之间的关系与口径。所有 Chat BI 查询最终都落到这一层翻译出的物理 SQL，从而保证“同一指标，处处一致”。

2.3 关键名词

Domain 主题域

业务域划分，如“销售分析”“用户行为”，是模型的容器。

Model 数据模型

对一张物理表或一条逻辑 SQL 的抽象。语义类型分：主键度量维度。

Metric 指标

可度量的数值（销售额、订单量），含聚合方式（SUM/AVG/COUNT）与格式。

Dimension 维度

分析角度（时间、地区、品类），可配置层级（如 年→季→月）。

Tag 标签

枚举值（用户等级、商品状态），绑定到主键，支持标签化查询。

Entity 实体

模型中的业务实体，用于关联与同义词映射。

2.4 S2SQL 与物理 SQL

• S2SQL（语义查询语句）：由 Semantic Parser 生成，描述“查哪些指标、按哪些维度、加哪些过滤”，不绑定具体物理库语法。
• 物理 SQL：由 Semantic Translator 把 S2SQL 翻译成目标数据库可执行的真正 SQL（处理 JOIN、方言差异等）。

这种“两段式”是 SuperSonic 区别于纯 Text2SQL 的关键：LLM 只生成 S2SQL，复杂逻辑交给语义层，稳定性与可解释性都更好。

2.5 Schema 感知与 RAG

SuperSonic 采用关键词链接（Keyword-linking）式 Schema 感知，而非纯粹向量检索：

• Knowledge Base（知识库）：从语义模型周期性抽取 Schema 信息，构建字典与前缀树（trie）索引。
• Schema Mapper：把用户问句中的文字匹配到具体的指标 / 维度 / 实体 / 值。

同时结合Chat Memory / Exemplar（向量库存储历史成功查询，提供 few-shot 示例）做检索增强，进一步提升准确率。

3系统架构

3.1 六层架构

3.2 查询处理流水线（双阶段：解析 + 执行）

1

解析阶段 Parse：ChatQueryService.parse()接收自然语言；从MemoryService检索相似示例；LLM 用 few-shot + 自一致性投票生成若干S2SQL 候选返回给用户选择。

2

执行阶段 Execute：用户选定解析 →S2SemanticLayerService.queryByReq()→DefaultSemanticTranslator将 S2SQL 转为物理 SQL →LLMSqlCorrector优化 →JdbcQueryExecutor执行目标库。

3

沉淀与呈现：成功查询存入MemoryService作为未来示例；结果经语义层解读并以 ECharts 可视化。

3.3 核心组件详解

可插拔：系统广泛使用 Spring SPI（META-INF/spring.factories）实现解析器、校正器、优化器、执行器的替换与扩展。

4环境准备

4.1 软硬件要求

4.2 技术栈一览

• 后端：Spring Boot 3.3.9、Java 21、Maven；ORM MyBatis Plus 3.5.10；SQL 解析 JSQLParser 4.9；SQL 引擎 Apache Calcite 1.38.0；连接池 Druid 1.2.24；中文 NLP HanLP。
• LLM 编排：LangChain4j 0.36.2（OpenAI、Ollama、Chroma、Milvus）。
• 前端：React 18 + TypeScript、Ant Design、ECharts、Axios、pnpm。
• 数据驱动：MySQL、H2、PostgreSQL、ClickHouse、Apache Doris、Kyuubi Hive、Presto、Trino、DuckDB、Arrow Flight SQL。

5安装与部署

SuperSonic 提供多种部署形态，按场景选择：

5.1 方式一：Docker Compose（推荐，最快）

# 1) 获取官方 docker-compose（以仓库实际路径为准） # github.com/tencentmusic/supersonic 的 docker/ 目录 docker-compose up -d # 2) 访问 # http://localhost:9080 （或镜像映射的 8080，依 docker-compose 而定） # 默认账号：admin / 123456（部分镜像为 admin / admin123）

避坑：启动失败先查端口冲突（9080 / 3306），并确认 Docker 版本 ≥ 20.10。首次登录务必修改默认密码。

5.2 方式二：官方 Release 包（Standalone，生产可用）

1

从 Release 页面 下载预构建包并解压。

2

进入解压目录，执行启动脚本（需 Java 21）：
sh bin/supersonic-daemon.sh start

3

浏览器访问http://localhost:9080开始探索（自带样例语义模型与对话）。

5.3 方式三：源码编译

git clone https://github.com/tencentmusic/supersonic.git cd supersonic mvn clean install -DskipTests # 编译产物在 assembly/build 目录下，解压后同 5.2 启动

5.4 方式四：在线体验

官方只读 Demo：http://117.72.46.148:9080（注册新用户即可体验，周末定期重置，请勿改动系统配置）。

5.5 配置 Profile

通过 Spring Profiles 切换环境：h2（默认演示）、local（开发）、prd（生产）；后端可接 H2 / MySQL / PostgreSQL。

6初始化配置

6.1 元数据库初始化（MySQL）

CREATE DATABASE supersonic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE supersonic; SOURCE /path/to/launchers/standalone/src/main/resources/db/schema-mysql.sql; SOURCE /path/to/launchers/standalone/src/main/resources/db/data-mysql.sql;

6.2 主配置文件

核心配置位于conf/application.yml（或 Profile 对应的application-local.yml），主要含：数据源（spring.datasource）、服务端口、以及 SuperSonic 专属项（s2命名空间，如 demo 名称、是否启用 LLM）。

# 示例：启用 Demo 与 LLM s2: demo: names: S2VisitsDemo,S2ArtistDemo enableLLM: true

6.3 配置 LLM（最关键的一步）

SuperSonic 支持两个粒度配置 Chat Model：系统设置（全局）与助理（Agent）级别（覆盖系统设置，优先级更高）。

支持的主流供应商

open_ai（兼容各云 OpenAI 协议）ollama（本地模型）
理论支持（待验证）：azureqianfan 文心一言dashscope 通义千问zhipu 智谱

配置参数

provider/baseUrl/apiKey/modelName/temperature(0~1) /timeOut(ms)

Java LLM 代理（默认方式，推荐）

直接通过 YAML 配置即可，支持 OpenAI / Ollama：

# 系统设置 → LLM 配置中填写 provider : OPEN_AI # 或 OLLAMA baseUrl : https://api.openai.com/v1 apiKey : REPLACE_WITH_YOUR_KEY modelName: gpt-4o temperature: 0.0 timeOut : 60000 # 也可用环境变量覆盖 export OPENAI_BASE_URL=https://api.openai.com/v1 export OPENAI_API_KEY=your_api_key export OPENAI_MODEL_NAME=gpt-4o

Python LLM 代理（可选）

启动命令：sh assembly/bin/supersonic-daemon.sh start pyllm（同时启动 Java 服务，但经 Python 访问 LLM）。配置在chat/core/src/main/python/config/run_config.ini，基于 LangChain，默认 LLM 为gpt-3.5-turbo-16k，Embedding 为GanymedeNil/text2vec-large-chinese。可在[LLMProvider]/[LLMModel]下切换为 Azure、文心一言等 LangChain 支持的厂商。

选型建议：中文场景优先选对中文友好的模型（如通义、智谱、DeepSeek，或本地 Ollama 的 qwen/llama 系列）；temperature设 0 更利于查询稳定。生产环境推荐用 open_ai 兼容协议接入你自托管的模型网关。

7数据源接入

7.1 支持的数据源

MySQL、PostgreSQL、ClickHouse、Apache Doris、Kyuubi Hive、Presto、Trino、DuckDB、H2、Arrow Flight SQL 等。

7.2 添加步骤

1

进入数据源管理页面，点击“新增连接”。

2

填写：连接名、数据库类型、Host / 端口、用户名 / 密码、数据库名。

3

点击“测试连接”，成功后保存。

排错：连接失败通常源于网络不通（telnet 地址 端口自检）、账号缺少SELECT权限、或防火墙 / 白名单未放通。StarRocks 等可用 MySQL 协议 JDBC（如jdbc:mysql://fe_host:9030/db）接入。

8语义建模（Headless BI 核心）

这是决定问答质量最关键的一步。流程总览：建主题域 → 建数据模型 → 定义指标 / 维度 / 标签 → 加同义词与描述。

8.1 创建主题域（Domain）

按业务域划分，如“销售分析”“用户行为”，作为模型的容器。

8.2 创建数据模型（Model）

SuperSonic 提供两种建模型方式：

注意：① 模型英文名称不能含中划线（-）；② 语义类型分 主键度量维度；主键可绑定标签对象做标签化查询；③ 快速创建只生成表中已有字段，SQL 创建可新增派生列。

8.3 定义指标（Metric）

• 原子指标：直接来自字段聚合（SUM/AVG/COUNT）。
• 衍生指标：基于原子指标计算（如gmv = SUM(order_amount)，可加过滤status = completed）。
• 设置聚合方式、数值格式（千分位、百分比）、单位等。

8.4 定义维度（Dimension）

时间、地区、品类等分析角度；可配置层级（年→季→月→日）以支持下钻。

8.5 标签与同义词

• 标签（Tag）：枚举值（用户等级、商品状态），绑定到主键，支持按标签筛选。
• 同义词（Synonyms）：大幅提升自然语言命中率，例如“营收”“销售额”都指向同一指标；“GMV”映射到“订单总金额”。
• 描述（Description）：为字段 / 指标写好业务说明，帮助 LLM 理解语义。

8.6 建模最佳实践

• 维度 / 指标名称用业务人员熟悉的词汇，而非技术字段名。
• 务必配置同义词与描述，这是提升问答准确率最有效的手段。
• 按业务域分层设计模型，公共维度 / 指标统一管理复用。
• 新指标至少用5 种不同问法测试覆盖。
• 避免在语义层堆“宽表”，每个指标应明确业务口径；时间维度统一粒度。

9数据集与助理配置

9.1 组装数据集（Dataset）

1

进入数据集模块，新建数据集，从模型中选择要纳入的指标与维度。

2

配置属性：默认过滤条件、时间粒度、行数上限。

3

配置访问权限（三级：数据集级 / 列级 / 行级）。

9.2 配置助理（Assistant / Agent）

• 新建助理，选择其可访问的数据集。
• 配置响应格式、查询参数、可视化偏好（图表类型倾向）。
• 助理级 LLM 配置会覆盖系统级：在“助理管理”填写provider/baseUrl/apiKey/modelName即可。

三级权限含义：① 数据集级——谁能看这个数据集；② 列级——能看哪些字段；③ 行级——能看哪些数据行（如只看自己区域）。满足企业级安全合规。

10Chat BI 使用

10.1 对话查询

打开 Chat 界面，在对话框输入自然语言，系统返回数据表格 + 自动匹配的图表。例：

• “上个季度各地区的销售额对比”
• “最近一周销售额异常波动的产品有哪些”
• “今年每月的 PV 和 UV 趋势”

10.2 增强体验

• 输入联想：边输入边提示。
• 多轮对话：可在上一问基础上追问（“那华东呢？”）。
• 查询后推荐：结果后给出可继续探索的问题。
• 图表自适配：依据数据特征自动选柱状 / 折线 / 饼图等（ECharts 渲染）。

10.3 提升问答准确率的技巧

• 问法贴近已定义的指标 / 维度 / 同义词名称。
• 涉及时间务必说明粒度（日 / 月 / 季度 / 年）。
• 对返回结果可在界面校正，校正会反哺语义模型。

11Headless BI 使用

• 语义层 API：Headless BI 通过开放的语义层 API 暴露一致的数据语义，可被传统 BI / 应用直接调用，而不必关心底层物理表结构。
• 仪表盘 / 看板：基于已组装的数据集，配置可视化组件（趋势、排行、占比等），沉淀为固定看板供团队日常使用。
• 统一口径：所有取数都经由语义层，保证“同一指标，处处一致”，避免各部门口径打架。

组合用法：先用 Headless BI 把模型与口径定好，再用 Chat BI 让全员即问即答——这是 SuperSonic 的推荐落地路径。

12扩展开发（Java SPI）

SuperSonic 设计为可插拔框架，可通过 Spring SPI（META-INF/spring.factories）替换或新增实现：

• 自定义解析器 / 校正器 / 优化器 / 执行器：适配你的特定方言或业务规则。
• Chat 插件（PluginManager）：集成外部 API（天气、汇率、企业内部系统）或自定义计算逻辑。
• Exemplar 检索：用向量库提供更精准的 few-shot 示例。

示例扩展点文件结构（示意）：

# META-INF/spring.factories org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ com.yourorg.supersonic.CustomParserAutoConfiguration

13权限与安全

• 三级数据权限：数据集级 / 列级 / 行级（在数据集配置中设置）。
• 账号与角色：支持基于角色的访问控制（RBAC）；注册用户可绑定角色。
• 默认凭证：常见默认admin / 123456（部分镜像admin / admin123），首次登录务必修改。
• LLM 密钥：API Key 存于配置文件 / 环境变量，生产环境建议使用密钥管理，避免明文提交到代码库。

14最佳实践

14.1 语义模型设计

• 按业务域分层；公共维度 / 指标统一复用。
• 名称业务化、配齐同义词与描述。
• 指标口径显式定义（如“GMV 仅含已完成订单”）。

14.2 提升问答准确率

• 优先投入语义建模与同义词，而非盲目换更大模型。
• 用历史成功查询沉淀 Exemplar（记忆）做 few-shot。
• 对高频问题做“查询后推荐”引导。

14.3 性能调优

• 预定义常用分析维度，减少实时计算。
• 合理使用缓存（可配置 Redis 作为语义层缓存，ttl控制指标 / 模型缓存时间）。
• 根据并发调整数据库连接池（如 Hikarimaximum-pool-size）。
• 复杂查询设置合理的数据更新频率与行数上限。

15常见问题 FAQ / 排错

16API 参考（常用端点示意）

以下为社区实践中常见端点形态，具体路径以你所部署版本的 OpenAPI 文档为准。

# 列出语义模型 GET /api/semantic/models # 自然语言查询 POST /api/chat/query { "query": "各区域销售对比", "modelId": "sales_model" } # 指标同步（将外部定义的指标同步进语义层） POST /api/metric/sync { "modelName": "ecommerce", "metrics": ["gmv", "orders_count"], "updateMode": "incremental" }

建议：部署后访问/swagger-ui.html或项目 OpenAPI 文档查看完整、准确的接口定义。

17团队落地提示（结合前面 ChatBI 规划）

若你正按“基于公司实际需求、借助 AI 能力与开源产品搭建数据 / ChatBI 平台”的年度方向推进，可把 SuperSonic 定位为：

• 语义层底座：用 Headless BI 统一快递 100 各业务线（寄件、电子面单、AI&数据）的指标口径，解决前文提到的“数据割裂 / 孤岛 / 重复建设”。
• ChatBI 入口：业务方自然语言即问即答，呼应此前 ChatBI 全面落地规划（腾讯 SuperSonic 即核心选型之一）。
• 治理贯穿：三级数据权限（数据集 / 列 / 行）与国内数据安全要求天然契合。
• 务实落地：优先用开源 SuperSonic + 自托管模型网关，避免直接采购通用产品导致改造成本高（与上半年调研结论一致）。

18参考资源

• GitHub 仓库：github.com/tencentmusic/supersonic
• 官方文档（Wiki）：github.com/tencentmusic/supersonic/wiki
• 文档站点：supersonic-ai.github.io（或 supersonicbi.github.io）
• 在线 Demo：http://117.72.46.148:9080
• 架构解析：DeepWiki tencentmusic/supersonic

本指南整理于 2026-07，内容随官方版本演进，请以最新官方文档为准。

SuperSonic 全面使用指南 · 基于官方文档与社区实践整理 · MIT License