SuperSonic 架构与实战指南：LLM 驱动的 Chat BI 与语义层 Headless BI 融合的下一代 AI+BI 平台

• 后端
• AI 应用
• 数据分析
• 数据可视化
• 前端

SuperSonic 是一款将Chat BI（由大语言模型 LLM 驱动）与Headless BI（由语义层 Semantic Layer 驱动）两种范式统一起来的开源 AI+BI 平台。本文以仓库 README_JP.md 为主线，系统讲解其设计动机、开箱即用的核心能力、六大可扩展组件，以及从在线体验、Docker 部署到本地构建的完整上手路径，并结合仓库源码给出可验证的实现依据，帮助你快速掌握这一"用自然语言查数据、用语义模型管口径"的平台级解决方案。

一、SuperSonic 是什么：两种 BI 范式的一次统一

SuperSonic 的核心定位可以概括为一句话：它既是 Chat BI 平台，也是 Headless BI 平台，并且让两者互相增益。其关键主张是：Chat BI 不再是脱离治理的"裸奔" Text2SQL，而是可以像传统 BI 一样访问统一、被治理过的语义数据模型；同时，两种 BI 范式都能从这一统中获益：

• Chat BI 的 Text2SQL 被语义模型的上下文检索增强：LLM 生成 SQL 时，可以从语义模型中获取业务术语、口径定义等上下文，显著降低幻觉；
• Headless BI 的查询接口被自然语言 API 扩展：语义层既可以被传统仪表盘消费，也可以直接接受自然语言查询，形成更开放的交互入口。

在使用层面，用户只需要通过Headless BI 接口构建逻辑语义模型（包括指标 Metric / 维度 Dimension / 标签 Tag的定义、含义及相互关系），就可以通过Chat BI 接口用自然语言查询数据，并以合适的图表完成可视化。与此同时，SuperSonic 采用了可扩展、可配置的架构设计，允许通过Java SPI机制注册自定义实现，将平台从"开箱即用的产品"扩展为"可定制的框架"。

从仓库结构可以印证这一点：chat/与headless/是平级的独立 Maven 模块（chat/api、chat/server 与 headless/api、headless/core、headless/server），并由 launchers/standalone 中的StandaloneLauncher统一装配为单体服务——这正是"Chat BI + Headless BI 一体部署"的工程落地。

二、项目动机：为什么 Text2SQL 需要与语义层结合

以 ChatGPT 为代表的大语言模型的出现，重新定义了信息检索方式，也催生了数据分析领域的新范式Chat BI。学术与工业界实现 Chat BI 的主流思路，是直接借助 LLM 将自然语言转换为 SQL，即Text2SQL / NL2SQL。虽然部分方案已展现出不错的效果，但在大规模真实业务场景下的可靠性仍然不足。

与此同时，另一股新兴范式Headless BI也备受关注：它通过通用语义层（Universal Semantic Layer），以开放 API 对外暴露一致的数据语义，把"口径"沉淀在模型层而非应用层。

SuperSonic 的核心洞察在于：将 Chat BI 与 Headless BI 结合，可以从两个方向显著增强 Text2SQL 生成质量：

1. 降低幻觉（Reduce Hallucination）：把数据语义（业务术语、列取值等）注入 prompt，帮助 LLM 更准确地理解业务语义，避免凭空编造字段与口径；
2. 降低复杂度（Reduce Complexity）：把高级 SQL 语法（多表 Join、表达式等）的生成从 LLM 下沉到语义层，LLM 只需完成"语义解析"而非"物理 SQL 生成"，大幅收敛出错面。

正是在这一思路下，SuperSonic 被开发出来并在实际产品中投入使用，同时以"可扩展框架"的形式开源，推动数据查询对话领域进一步发展。

三、开箱即用的核心能力

SuperSonic 在初始配置下即提供了完整可用的功能清单：

• 内置 Chat BI 界面：面向业务用户，直接输入自然语言查询即可获得数据与图表；
• 内置 Headless BI 界面：面向分析工程师，用于构建和维护语义模型；
• 内置基于规则的语义解析器（Rule-based Semantic Parser）：在特定场景（如演示、集成测试）下无需调用 LLM 也能完成解析，提升推理效率并降低运行成本；
• 高级交互能力：输入自动补全（Auto-completion）、多轮对话（Multi-turn Conversation）、查询后的问题推荐（Recommended Questions）等；
• 三级数据访问控制（3-Level Data Permission）：覆盖数据集级别（Dataset）、列级别（Column）、**行级别（Row）**的细粒度权限管控，确保不同角色的数据可见范围。

从源码可以找到这些能力的落点：规则解析与查询语句生成对应 headless/core/.../translator/parser 目录下的StructQueryParser、SqlQueryParser等解析器；多轮对话与推荐问题相关服务位于 chat/server；三级权限控制则贯穿 chat 与 headless 两个服务端的数据访问链路。这些模块共同构成了"体验完整、权限可控"的初始产品形态。

四、可扩展组件：六大核心构建块

SuperSonic 采用流水线式架构组织一次"自然语言 → 可执行 SQL"的查询旅程，其高层架构与主流程可概括为六个可替换的组件，且均可通过 SPI 机制扩展自定义实现：

其中，S2SQL（SuperSonic 语义查询语言）是整条链路的中间产物——它比物理 SQL 更抽象，屏蔽了底层表结构细节。在源码中可以看到完整的解析与翻译实现：语义解析阶段由 headless/core 下的StructQueryParser、MetricExpressionParser、DimExpressionParser等负责把 S2SQL 拆解为结构化的查询意图；翻译阶段则由同目录下的SqlQueryParser及 calcite 子目录（如SchemaBuilder、S2SQLSqlValidatorImpl）完成"语义语句 → 物理 SQL"的落地与校验。

而Chat Plugin的工程化实现集中在 chat/server：PluginController提供插件管理的 REST 接口，PluginServiceImpl负责插件的配置与调度，PluginTool将插件包装为可供 LLM 调用的工具（Tool）。这意味着你可以在不修改核心代码的前提下，通过注册新插件为对话体验接入报表、查询 API、自定义计算等外部能力。

五、快速体验：三种上手路径

SuperSonic 提供了由浅入深的三种体验方式，你可以根据自己的环境任选其一。

1. 在线 Playground（零成本体验）

直接访问在线体验地址（http://117.72.46.148:9080），以新用户身份注册即可体验完整功能。需要注意两点约束：请勿修改系统设置；服务会在每周周末定期重启以重置配置，临时数据不会持久保留。

2. Docker 部署（一条命令拉起全栈）

Docker 方式适合在本地或测试环境快速部署，步骤如下：

1. 安装 Docker 与 docker-compose；
2. 下载 docker-compose.yml 编排文件；
3. 执行docker-compose up -d拉起服务；
4. 浏览器打开http://localhost:9080开始探索。

从仓库自带的 docker/docker-compose.yml 可以看到完整的部署拓扑：它定义了两个服务——supersonic_postgres（基于pgvector/pgvector:pg17的数据库，映射宿主机端口15432）与supersonic_standalone（镜像supersonicbi/supersonic:${SUPERSONIC_VERSION:-latest}，映射宿主机端口9080）。standalone 服务通过S2_DB_TYPE、S2_DB_HOST、S2_DB_PORT、S2_DB_DATABASE、S2_DB_USER、S2_DB_PASSWORD一组环境变量注入数据库连接信息，并配置了 CPU（2 核）与内存（2048M）资源上限，同时以数据库健康检查（pg_isready）作为启动前置条件。

如果你倾向更轻量的方式，仓库还提供了两条辅助脚本：

• assembly/bin/supersonic-docker-compose.sh：docker-compose -f docker-compose.yml -p supersonic up；
• assembly/bin/supersonic-docker-run.sh：直接docker run运行supersonicbi/supersonic:latest镜像，支持通过环境变量指定数据库类型（S2_DB_TYPE，支持h2、mysql、postgres），默认使用内置 H2 数据库，适合无需外部数据库的快速验证。

3. 本地构建运行（预编译二进制）

SuperSonic 自带示例语义模型与示例聊天会话，可通过以下步骤在本地快速体验：

1. 从**发布页（Releases）**下载最新预编译二进制包；
2. 执行启动脚本assembly/bin/supersonic-daemon.sh start启动独立 Java 服务；
3. 浏览器打开http://localhost:9080开始探索。

对照 assembly/bin/supersonic-daemon.sh 的源码实现，脚本实际支持start | stop | restart三种命令，并会根据服务类型选择不同启动入口：

• standalone→com.tencent.supersonic.StandaloneLauncher（应用名supersonic_standalone）；
• chat→com.tencent.supersonic.ChatLauncher（应用名supersonic_chat）；
• headless→com.tencent.supersonic.HeadlessLauncher（应用名supersonic_headless）。

启动时通过-Dspring.profiles.active="$profile"激活配置环境，profile 默认取自S2_DB_TYPE（即按数据库类型加载对应配置）。内存参数为-Xms1024m -Xmx2048m，并启用了 ZGC（-XX:+UseZGC -XX:+ZGenerational）以降低大堆场景下的停顿。如需接入自有数据库，可在 assembly/bin/supersonic-env.sh 中通过S2_DB_TYPE（支持h2、mysql、postgres）以及S2_DB_HOST、S2_DB_PORT、S2_DB_USER、S2_DB_PASSWORD、S2_DB_DATABASE等环境变量完成配置——这与 Docker 方式的数据库参数一一对应，两套部署路径共享同一套配置语义。

注意：本地构建运行方式要求本机已具备 JDK 运行环境（脚本会优先使用JAVA_HOME，并在缺失时尝试探测/usr/jdk64/jdk*）。H2 配置适合"零依赖"快速试用；正式环境建议使用 MySQL 或 PostgreSQL 保证数据持久化。

六、构建与二次开发

对于希望从源码构建、二次开发的读者，仓库提供了多模块 Maven 工程结构（根 pom.xml）与 Docker 镜像构建文件（docker/Dockerfile、docker/DockerfileS2）。项目采用 Java SPI 作为扩展机制，因此自定义组件（如新的语义解析器、新的 Schema 映射器、新的聊天插件）都可以通过标准 SPI 声明注册，而无需改动平台核心。

前端方面，Web 界面位于 webapp/packages 下：supersonic-fe为面向管理端的完整 Web 应用，chat-sdk为可独立嵌入的聊天 SDK，两者均可单独构建并接入后端服务。完整的源码编译与部署步骤可参考项目官方部署文档（见 README_JP.md 中"ビルドと開発"章节所指向的官方文档链接）。

七、小结

SuperSonic 的价值不在于"又一个 Text2SQL 工具"，而在于它把**语义治理（Headless BI）与自然语言交互（Chat BI）**放到同一平台中形成闭环：语义层为 LLM 提供可信的上下文，LLM 为语义层提供更自然的入口。通过六大可扩展组件与 Java SPI 机制，它既可以直接部署体验（在线 Playground、Docker、预编译二进制三种方式），也可以作为可插拔框架融入企业现有的数据基础设施。无论你是业务用户、分析工程师还是平台开发者，都可以从本文的架构解析与部署路径中找到适合自己的切入方式，并进一步深入 headless/core 与 chat/server 的源码，理解 S2SQL 从生成、校验到翻译为物理 SQL 的完整链路。

• 后端
• AI 应用
• 数据分析
• 数据可视化
• 前端