目录速览 / 关于本指南1. 产品概述2. 核心概念3. 系统架构4. 环境准备5. 安装与部署6. 初始化配置7. 数据源接入8. 语义建模9. 数据集与助理10. Chat BI 使用11. Headless BI 使用12. 扩展开发 SPI13. 权限与安全14. 最佳实践15. 常见问题 FAQ16. API 参考17. 团队落地提示18. 参考资源SuperSonic 全面使用指南腾讯音乐开源的下一代 AIBI 平台统一 Chat BILLM 驱动与 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.x2025 年使用Java 21 Spring Boot 3.3.9较旧版本使用 Java 11 / Spring Boot 2.7.2。本文以最新版为主涉及版本差异处会标注。请按你实际下载的 Release 包对应版本准备 JDK。1产品概述1.1 什么是 SuperSonicSuperSonic 是腾讯音乐开源的新一代 AIBI 平台核心思路是把两种数据分析范式融合到同一个可生产化系统中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维度Chat BIHeadless BI面向角色业务用户数据 / 分析工程师入口对话界面自然语言语义建模界面配置化核心产物即问即答的表格 图表统一语义模型 开放 API依赖必须先有 Headless BI 建好的语义模型是 Chat 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 与物理 SQLS2SQL语义查询语句由 Semantic Parser 生成描述“查哪些指标、按哪些维度、加哪些过滤”不绑定具体物理库语法。物理 SQL由 Semantic Translator 把 S2SQL 翻译成目标数据库可执行的真正 SQL处理 JOIN、方言差异等。这种“两段式”是 SuperSonic 区别于纯 Text2SQL 的关键LLM 只生成 S2SQL复杂逻辑交给语义层稳定性与可解释性都更好。2.5 Schema 感知与 RAGSuperSonic 采用关键词链接Keyword-linking式 Schema 感知而非纯粹向量检索Knowledge Base知识库从语义模型周期性抽取 Schema 信息构建字典与前缀树trie索引。Schema Mapper把用户问句中的文字匹配到具体的指标 / 维度 / 实体 / 值。同时结合Chat Memory / Exemplar向量库存储历史成功查询提供 few-shot 示例做检索增强进一步提升准确率。3系统架构3.1 六层架构层级职责关键组件① 前端层提供可复用聊天组件与建模界面React 18 TypeScriptchat-sdkChatItem / ChatMsg② API 网关统一 REST 入口与响应封装Spring Boot REST端口 9080ResponseAdvice/ResultData③ 聊天智能层解析编排、智能体、记忆管理ChatQueryServiceNL2SQLParserAgentServiceMemoryService④ 语义层Headless BI 核心S2SQL→SQLS2SemanticLayerServiceDefaultSemanticTranslator⑤ LLM 集成多供应商模型编排与 SQL 优化LangChain4jOnePassSCSqlGenStrategy自一致性投票LLMSqlCorrector⑥ 数据访问多库查询与向量记忆检索JdbcQueryExecutor向量库 Chroma / Milvus3.2 查询处理流水线双阶段解析 执行1解析阶段 ParseChatQueryService.parse()接收自然语言从MemoryService检索相似示例LLM 用 few-shot 自一致性投票生成若干S2SQL 候选返回给用户选择。2执行阶段 Execute用户选定解析 →S2SemanticLayerService.queryByReq()→DefaultSemanticTranslator将 S2SQL 转为物理 SQL →LLMSqlCorrector优化 →JdbcQueryExecutor执行目标库。3沉淀与呈现成功查询存入MemoryService作为未来示例结果经语义层解读并以 ECharts 可视化。3.3 核心组件详解组件作用Knowledge Base抽取并索引 Schema前缀树trie结构支撑 Schema 匹配与查询理解。Schema MapperEmbeddingMapper/KeywordMapper把查询文本映射到 Schema 元素。Semantic ParserLLMSqlParser/RuleSqlParser生成 S2SQLText2SQL。Semantic CorrectorLLMSqlCorrector/RuleSqlCorrector校验并优化查询含物理 SQL 优化。Semantic TranslatorDefaultSemanticTranslatorS2SQL → 物理 SQLHeadless BI 核心翻译器。Chat PluginPluginManager对接外部系统天气、汇率等ExemplarService提供 few-shot。Chat MemoryMemoryService从s2_chat_memory学习历史查询提供相似示例。可插拔系统广泛使用 Spring SPIMETA-INF/spring.factories实现解析器、校正器、优化器、执行器的替换与扩展。4环境准备4.1 软硬件要求项目要求 / 说明JDK最新版Java 21旧版可用 Java 11按 Release 包要求前端 Node 18 / pnpm构建工具Maven 3.x源码编译元数据库MySQL推荐/ H2默认演示/ PostgreSQL向量库可选Chroma / Milvus用于记忆检索增强内存生产建议 ≥ 4GB 堆内存Docker 可设资源限制端口服务默认9080部分 Docker 镜像 / 旧文档写作 8080以实际映射为准元数据库 3306 等4.2 技术栈一览后端Spring Boot 3.3.9、Java 21、MavenORM MyBatis Plus 3.5.10SQL 解析 JSQLParser 4.9SQL 引擎 Apache Calcite 1.38.0连接池 Druid 1.2.24中文 NLP HanLP。LLM 编排LangChain4j 0.36.2OpenAI、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 提供多种部署形态按场景选择部署产物说明supersonic-standalone.jar一体化Chat Headless BI典型部署supersonic-chat.jar仅聊天服务适合分布式supersonic-headless.jar仅语义层服务可无 UIsupersonic-webapp.tar.gz前端静态资源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 21sh bin/supersonic-daemon.sh start3浏览器访问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 方式四在线体验官方只读 Demohttp://117.72.46.148:9080注册新用户即可体验周末定期重置请勿改动系统配置。5.5 配置 Profile通过 Spring Profiles 切换环境h2默认演示、local开发、prd生产后端可接 H2 / MySQL / PostgreSQL。6初始化配置6.1 元数据库初始化MySQLCREATE 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: true6.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_URLhttps://api.openai.com/v1 export OPENAI_API_KEYyour_api_key export OPENAI_MODEL_NAMEgpt-4oPython 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-16kEmbedding 为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 创建数据模型ModelSuperSonic 提供两种建模型方式方式说明适用快速创建直接指定一张物理表创建为模型可一键生成表中已有字段的原子指标与维度表结构清晰、字段即所需SQL 脚本写一条逻辑 SQL 作为模型如SELECT imp_date, user_name, 1 AS pv ...需派生表中没有的列常量 / 计算列注意① 模型英文名称不能含中划线-② 语义类型分 主键度量维度主键可绑定标签对象做标签化查询③ 快速创建只生成表中已有字段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 组装数据集Dataset1进入数据集模块新建数据集从模型中选择要纳入的指标与维度。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 使用语义层 APIHeadless BI 通过开放的语义层 API 暴露一致的数据语义可被传统 BI / 应用直接调用而不必关心底层物理表结构。仪表盘 / 看板基于已组装的数据集配置可视化组件趋势、排行、占比等沉淀为固定看板供团队日常使用。统一口径所有取数都经由语义层保证“同一指标处处一致”避免各部门口径打架。组合用法先用 Headless BI 把模型与口径定好再用 Chat BI 让全员即问即答——这是 SuperSonic 的推荐落地路径。12扩展开发Java SPISuperSonic 设计为可插拔框架可通过 Spring SPIMETA-INF/spring.factories替换或新增实现自定义解析器 / 校正器 / 优化器 / 执行器适配你的特定方言或业务规则。Chat 插件PluginManager集成外部 API天气、汇率、企业内部系统或自定义计算逻辑。Exemplar 检索用向量库提供更精准的 few-shot 示例。示例扩展点文件结构示意# META-INF/spring.factories org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.yourorg.supersonic.CustomParserAutoConfiguration13权限与安全三级数据权限数据集级 / 列级 / 行级在数据集配置中设置。账号与角色支持基于角色的访问控制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 / 排错现象可能原因 / 解决服务起不来 / 端口被占检查 9080 / 3306 是否被占用Docker 改端口映射或宿主机释放端口。数据源连接失败网络不通、账号缺 SELECT 权限、防火墙 / 白名单未放通用telnet自检。自然语言理解偏差完善语义模型同义词与业务术语表问法贴近已定义名称。查询慢预定义维度、开启缓存、调大连接池、设行数上限与时间粒度。LLM 调用报错检查baseUrl/apiKey/modelName确认厂商兼容 OpenAI 协议timeOut适当调大。图表不显示确认前端资源webapp已正确加载检查返回数据结构是否为表格。中文问答效果差换中文友好模型通义 / 智谱 / DeepSeek / 本地 qwenEmbedding 用中文模型。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官方文档Wikigithub.com/tencentmusic/supersonic/wiki文档站点supersonic-ai.github.io或 supersonicbi.github.io在线 Demohttp://117.72.46.148:9080架构解析DeepWiki tencentmusic/supersonic本指南整理于 2026-07内容随官方版本演进请以最新官方文档为准。SuperSonic 全面使用指南 · 基于官方文档与社区实践整理 · MIT License
