企业官网建设流程全解析

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

本文以 evaluation/README.md 为骨架，结合 evaluation 目录下的完整脚本源码，系统讲解 SuperSonic 评测体系的运行流程、底层实现与实战价值。读完本文，你将掌握如何启动一次"构建表数据 → 数据建模 → 获取模型预测 → 对比评估"的完整评测，理解 Execution Accuracy / Exact Match / Partial Match 等指标的计算原理，并知道如何借助这套工具评估提示词、参数配置与代码改动对 NL2SQL 准确率和响应速度的影响。

一、评测流程概览

evaluation/README.md 将评测流程概括为两步：

1. 正常启动项目（必须包括 LLM 服务）：SuperSonic 的 Chat BI 能力依赖 LLM 完成自然语言到 SQL 的转换，评测的本质是验证这条链路，因此 LLM 服务不可缺失；
2. 执行evaluation.sh脚本：脚本会自动完成构建表数据、数据建模、获取模型预测结果、执行对比逻辑四件事，评测结束后在命令行直接看到执行准确率，错误 case 会写入同目录的error_case.json文件。

看似只有两步，背后却是一条完整的自动化流水线。下文先说明运行环境与配置，再逐层拆解脚本内部的四个环节，最后解读输出结果与评测意义。

二、前置条件与运行环境

运行评测前需要准备：

依赖清单如下（版本号以仓库为准）：

pysqlite3==0.5.2 PyJWT==2.8.0 PyYAML==6.0.1 sqlparse==0.4.4 nltk==3.8.1

• pysqlite3：评测用的 SQLite 数据库驱动；
• PyJWT：生成访问 SuperSonic API 所需的 HS512 签名 Token；
• PyYAML：读取 evaluation/config/config.yaml 配置；
• sqlparse：解析预测 SQL，用于结果集的字段对齐；
• nltk：提供word_tokenize，用于 SQL 语句分词。

三、一键执行入口：evaluation.sh

evaluation/evaluation.sh 是整个评测的入口脚本，完整内容如下：

#!/usr/bin/env bash path=$(pwd) echo ${path} python_path=${PYTHON_PATH:-"python3"} pip_path=${PIP_PATH:-"pip3"} requirementPath=$path/requirements.txt ${pip_path} install -r ${requirementPath} echo "install python modules success" python $path/evaluation.py

脚本逻辑非常简单：先安装依赖，再执行evaluation.py。两点值得注意：

• path=$(pwd)取当前执行目录，因此建议在evaluation/目录下运行，确保相对路径正确；
• 支持通过环境变量覆盖解释器，例如在仅提供python命令的机器上可执行PYTHON_PATH=python PIP_PATH=pip bash evaluation.sh。

evaluation.py的主流程位于if __name__ == "__main__"段：

build_table() # 1. 构建表数据 time_cost = get_pred_result() # 2. 数据建模 + 获取模型预测结果（记录每题耗时） get_evaluation_result(time_cost) # 3. 执行对比逻辑，输出准确率 remove_unused_file() # 4. 清理临时文件

配置：config.yaml

evaluation/config/config.yaml 是唯一需要手工关心的配置文件，内容极简：

url: http://localhost:9080

url指向 SuperSonic 服务地址，会被 build_models.py、build_pred_result.py、evaluation.py 三处共同读取，用于拼接领域、模型、数据集、Agent、Chat 以及查询解析等全部 API 地址。

四、流水线第一环：构建表数据（build_tables.py）

build_tables.py 负责在 evaluation/data/ 下生成 SQLite 数据库internet.db，并在每次运行前删除旧库重建，保证评测数据始终可复现。

评测数据建模为 4 张表，模拟"互联网企业-品牌-收入"场景：

表内数据为百度、阿里巴巴、腾讯、京东、网易等公司及其子品牌的少量样例记录，imp_date取当前日期，方便在明细查询时做时间维过滤。这张数据库同时承担两个角色：一是作为语义模型 SQL 查询的真实数据源（建模脚本中sqlQuery直接对internet.db查询），二是作为评测执行准确率时的落点数据库（预测 SQL 与金标 SQL 都在其上执行并比较结果集）。

五、流水线第二环：数据建模（build_models.py）

build_models.py 通过 SuperSonic 的 REST API 自动完成"领域 → 模型 → 关系 → 数据集 → Agent → 会话"的建模链路，全程无需人工在界面上操作。

5.1 认证：HS512 JWT

脚本使用 PyJWT 生成管理员的访问令牌：

def get_authorization(): exp = time.time() + 100000 # secret 请和 com.tencent.supersonic.auth.api.authentication.config.AuthenticationConfig.tokenAppSecret 保持一致 secret = "WIaO9YRRVt+7QtpPvyWsARFngnEcbaKBk783uGFwMrbJBaochsqCH62L4Kijcb0sZCYoSsiKGV/zPml5MnZ3uQ==" token = jwt.encode({"token_user_name": "admin", "exp": exp}, secret, algorithm="HS512") return "Bearer " + token

源码注释明确指出，secret必须与 SuperSonic 服务端AuthenticationConfig.tokenAppSecret（位于 auth 模块）保持一致，否则所有 API 调用都会被拒绝。若你修改了服务端密钥，请同步更新此处的硬编码值。

5.2 建模链路

build()函数按依赖顺序执行，并带幂等保护：通过getDomainList/getModelList先查询是否已存在同bizName的领域或模型，已存在则跳过创建、直接复用。

1. 创建领域（Domain）：调用/api/semantic/domain/createDomain创建"DuSQL_互联网企业"（bizName: internet），并记录domain_id；
2. 创建模型（Model）：依次创建 4 个模型（company、brand、company_revenue、company_brand_revenue）。每个模型的modelDetail均以sql_query方式声明，直接查询第五节构建的internet.db中对应表，并显式声明：
   • identifiers：主键/外键（如company_id主键、brand.company_id外键）；
   • dimensions：时间维度imp_date与company_name、brand_name等类别维度；
   • measures：annual_turnover、revenue_proportion等度量（默认SUM聚合）；
   • isCreateDimension / isCreateMetric：标记是否自动派生维度/指标；
3. 创建模型关系（ModelRela）：调用/api/semantic/modelRela建立 4 条 inner join 关系，例如company.company_id = brand.company_id、brand.brand_id = company_revenue.brand_id，支撑多表 JOIN 查询；
4. 创建数据集（DataSet）：调用/api/semantic/dataSet将 4 个模型及其维度、指标组织为"DuSQL 互联网企业"数据集（typeEnum: DATASET），并附带默认查询配置（时间粒度 DAY、RECENT 模式）；
5. 创建 Agent：调用/api/chat/agent创建 id 为 10 的 Agent，其toolConfig挂载NL2SQL_LLM工具并绑定上述数据集，使 Chat 能力与语义层打通；
6. 创建会话（Chat）：调用/api/chat/manage/save创建名为"DuSQL问答"的会话，再从/api/chat/manage/getAll取回chat_id供下一环节使用。

六、流水线第三环：获取模型预测结果（build_pred_result.py）

build_pred_result.py 是评测与 SuperSonic Chat 能力的直接对接点，核心逻辑如下：

1. 读取问题集：从 evaluation/data/internet.txt 逐行读取 100 条自然语言问题（如"在各公司所有品牌收入排名中，给出每一个品牌，其所在公司以及收入占该公司的总收入比例，同时给出该公司的年营业额"），这些是评测输入；
2. 调用查询解析接口：对每条问题向{url}/api/chat/query/parse发起 POST，请求体为{"agentId": agent_id, "chatId": chat_id, "queryText": query}，携带上一步生成的 Bearer Token；
3. 提取预测 SQL：从响应data.selectedParses[0].sqlInfo.querySQL取最优解析结果，并做三项清洗：

querySQL = querySQL.replace("`dusql`.", "").replace("dusql", "").replace("\n", "")

即去掉数据库名前缀、反引号残留与换行符，使预测 SQL 与金标 SQL 格式对齐； 4.兜底策略：接口异常或未返回有效 SQL 时，写入默认 SQLselect * from tablea（一条必然无法匹配的语句，用于标记失败）； 5.记录耗时：每条问题记录请求耗时cost，并在相邻问题间time.sleep(3)限速；请求全部开始前还有time.sleep(60)的预热等待，给 Agent 冷启动留出时间； 6.写结果文件：全部问题处理完后，将预测 SQL 逐行写入 evaluation/data/pred_example_dusql.txt（与金标文件行号一一对应），并把耗时列表返回给主流程。

这一环节决定了评测的可移植性：脚本只依赖 SuperSonic 的 HTTP API，与具体 LLM 品牌无关。因此切换大模型只需修改 SuperSonic 服务端的 LLM 配置，评测脚本零改动即可重跑。

七、流水线第四环：对比逻辑与准确率评估（evaluation.py）

evaluation/evaluation.py 是全仓库最核心的评测实现，采用 DuSQL 数据集标准的评估方法。它读取三份文件：预测 SQL（pred_example_dusql.txt）、金标 SQL（evaluation/data/gold_example_dusql.txt）、表结构（evaluation/data/tables_dusql.json，用于构建外键映射以支持列名等价替换）。

7.1 SQL 结构化解析

预测与金标 SQL 先经 process_sql.py 解析为标准的结构化表示，文件头部完整定义了内部 DSL：

# col_unit: (agg_id, col_id, isDistinct(bool)) # val_unit: (unit_op, col_unit1, col_unit2) # table_unit: (table_type, col_unit/sql) # cond_unit: (not_op, op_id, val_unit, val1, val2) # condition: [cond_unit1, 'and'/'or', cond_unit2, ...] # sql { # 'select': (isDistinct(bool), [(agg_id, val_unit), ...]) # 'from': {'table_units': [...], 'conds': condition} # 'where': condition # 'groupBy': [col_unit1, ...] # 'orderBy': ('asc'/'desc', [val_unit1, ...]) # 'having': condition # 'limit': None/limit value # 'intersect': None/sql # 'except': None/sql # 'union': None/sql # }

其中聚合函数集合为AGG_OPS = ('none','max','min','count','sum','avg')，操作符集合为WHERE_OPS = ('not','between','=','>','<','>=','<=','!=','in','like','is','exists')，可通过 Schema 的get_schema(db)从 SQLite 元数据动态构造表-列映射。

7.2 难度分级（Hardness）

基于金标 SQL 结构，Evaluator.eval_hardness用三个计数器给每条 SQL 定级：

• count_component1：统计 where / group / order / limit / JOIN / or / like 的复合度；
• count_component2：统计 intersect / union / except 嵌套子查询数量；
• count_others：统计多聚合、多 select 列、多 where 条件、多 group 列等"其它复杂度"。

按组合规则划分为easy/medium/hard/extra四个难度等级，最终报告按等级分别统计准确率，便于定位模型在哪个复杂度区间掉点。

7.3 三类核心指标

主流程默认etype = "exec"，即执行准确率；代码同时完整实现了匹配评估逻辑。

Execution Accuracy（执行准确率）：eval_exec_match在internet.db上真实执行预测 SQL 与金标 SQL，再对两个结果集做比较：

• 提取预测结果列名并清洗：re.sub("t\d+.", "", p_fields[i].replace("","").lower())，即去掉T1.` 等别名前缀、反引号并转小写；
• 对每一列将取值排序后映射为{字段名: 排序后的值列表}，逐字段比较；
• 特殊跳过sys_imp_date这类系统字段，避免时间口径差异干扰；
• 预测 SQL 执行异常时直接判定不相等，并将结果写入错误 case。

Exact Matching Accuracy（精确匹配率）：eval_exact_match先对结构化表示逐组件做部分匹配，再要求所有部分 F1 均为 1，且 from 中的表集合一致，才算整句精确匹配。

Partial Matching（部分匹配）：eval_partial_match对 10 个组件分别统计 accuracy / recall / F1：

partial_types = ['select', 'select(no AGG)', 'where', 'where(no OP)', 'group(no Having)', 'group', 'order', 'and/or', 'IUEN', 'keywords']

• select(no AGG)：忽略聚合函数只看列选择；
• where(no OP)：忽略操作符只看条件列；
• group(no Having)：不含 having 的 group 匹配；
• IUEN：intersect / union / except / nested 的嵌套匹配；
• keywords：where/group/order/limit/or/not/in/like 等关键结构词匹配。

每个组件的acc、rec、f1由get_scores计算，且仅在预测与金标组件数一致时计分，避免"多选一列"被计为命中。此外脚本顶部还有两个全局开关：

DISABLE_VALUE = True # 关闭条件值评估：比较 where 时忽略具体数值 DISABLE_DISTINCT = True # 关闭 select 中 distinct 的评估

这意味着默认评估更关注 SQL结构正确性而非字面数值，符合业务问答"结构对了、值可变"的实际诉求。

7.4 报告输出与错误 case

print_scores在命令行以表格形式打印结果：第一行列easy / medium / hard / extra / all五个分组，随后是count（题目数）、execution（执行准确率），以及 partial 各维度的 acc / rec / F1。文件末尾还会打印整体执行准确率scores['all']['exec']。

对于执行不相等或精确匹配为 0 的题目，脚本会把明细写入 evaluation/error_case.json：

element = {"query": questions[index], "gold_sql": g_str, "pred_sql": p_str} # 执行失败时额外写入 element["p_res_map"] = result["p_res_map"] element["q_res_map"] = result["q_res_map"]

即每条错误 case 包含：原始问题、金标 SQL、预测 SQL，以及预测/金标各自排序后的结果集映射（便于肉眼比对差异来源）。文件末尾追加一个耗时统计对象：

cost_dic = {"max_time": max(time_cost), "min_time": min(time_cost), "avg_time": sum(time_cost)/len(time_cost)}

同时覆盖准确率与响应速度两个维度的评测结论。

7.5 临时文件清理

主流程最后调用remove_unused_file()，删除运行中生成的data/internet.db与data/pred_example_dusql.txt，保证每次评测从干净的初始状态开始（internet.db会在下一轮由build_table()重建，pred_example_dusql.txt由get_pred_result()重写）。

八、如何解读评测结果并定位问题

一次完整评测后你会得到两类产出：

1. 命令行报告：按难度分组的execution准确率。重点关注all列整体准确率，以及easy→medium→hard→extra的准确率衰减曲线——若低难度题目准确率明显低于高难度题目，通常意味着基础语义解析（表列映射、条件抽取）存在问题而非模型能力不足；
2. error_case.json：逐条给出问题、金标 SQL、预测 SQL 与结果集差异。典型排查路径：
   • 预测 SQL 为默认的select * from tablea：该题接口调用失败或未产生可用解析，优先排查 LLM 服务与 Agent 配置；
   • 结构大体正确但p_res_map与q_res_map列不一致：多为表/列选择错误，检查语义模型的维度、指标配置；
   • 结果集值不一致：多为条件值、聚合方式差异，可结合 partial 报告中的where、select(no AGG)分数交叉验证。

九、评测意义：快速迭代的量化标尺

evaluation/README.md 明确指出评测工具的两大意义，结合源码可进一步展开：

1. 快速对接其他大模型：评测链路只调用/api/chat/query/parse这一稳定 HTTP 接口，服务端更换 LLM（改模型名、接入点、密钥）后脚本无需改动即可重跑，准确率与耗时（max/min/avg_time）立刻可对比；
2. 量化提示词与代码改动的影响：无论是调整提示词模板、修改 NL2SQL 解析逻辑、优化插件参数，还是改动 Agent 的 toolConfig，都可以通过"改配置 → 重跑evaluation.sh→ 对比execution准确率与error_case.json"形成闭环，判断改动是正向还是负向，避免凭感觉上线。

由于数据集（100 条 DuSQL 风格问题与金标 SQL）、表数据、建模流程全部固化且可复现，这套评测成为 SuperSonic 团队在 benchmark 之外、贴近真实 Chat BI 场景的回归验证手段：任何涉及"自然语言 → SQL"的能力变更，都能以统一标尺衡量其准确率与响应速度的变化。

十、把评测接入日常开发：实用建议

• 目录约定：在 evaluation/ 目录内执行bash evaluation.sh，保证path=$(pwd)解析正确；
• 服务就绪检查：运行前确认curl http://localhost:9080可访问，且 LLM 服务可用（README 明确强调"必须包括 LLM 服务"）；
• 密钥同步：修改服务端AuthenticationConfig.tokenAppSecret后，务必同步更新 build_models.py 中的secret常量；
• 定制评测集：扩展评测只需三步——向data/internet.txt追加自然语言问题、向data/gold_example_dusql.txt追加行号一一对应的金标 SQL（格式为SQL\t表名）、在data/tables_dusql.json中补充外键与表结构信息；
• 耗时口径：get_pred_result的耗时仅包含 HTTP 请求往返时间（不含 60s 预热与 3s 间隔），可作为响应速度的相对对比指标。

这套开箱即用的评测脚本，让 Chat BI 的每一次迭代都能"用数据说话"——这正是它作为 SuperSonic 质量基线的核心价值。

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