Sonar-TS：面向时间序列数据库的“搜索-然后-验证”自然语言查询
Sonar-TS 论文的官方实现 (ICML 2026)。
## 🎬 宣传视频
▶️ 点击预告片观看带有声音的 75 秒完整宣传片 —— 为什么用自然语言查询时间序列很困难，Search-Then-Verify 如何解决它，以及它的应用场景。
## 📖 简介
时间序列数据在工业界无处不在。常见的例子包括温度读数、股票价格和工厂传感器日志。当非专家用户想要从这类数据中提取特定信息时，经常会遇到严重的障碍。例如，他们可能会问：*“在过去的一个月里，哪一天的上午 10 点到下午 3 点之间气温急剧上升，然后又迅速下降？”* 如今，没有任何现有方法能够直接在真实的时间序列数据库上回答这类自然语言问题。
现有方法在两个典型方面存在不足。Text-to-SQL 方法专为关系型数据设计，无法描述定义时间序列的基于形状的形态特征（例如 *高原*、*快速下降*、*波动稳定*）。时间序列语言模型可以回答短时间窗口内的问题，但无法扩展到实际应用所需的数据库规模的历史数据。
这就留下了一个真实且尚未解决的问题：一个允许用户用自然语言描述时间序列模式，并基于底层数据库获得答案的接口。我们通过以下三项贡献填补了这一空白：
* **新问题。** 我们将该问题正式定义为**面向时间序列数据库的自然语言查询 (NLQ4TSDB)**。
* **新基准测试。** 我们发布了 **NLQTSBench**，这是第一个用于标准化评估 NLQ4TSDB 的基准测试。
* **新框架。** 我们提出了 **Sonar-TS**，这是一个通过 *Search-Then-Verify* pipeline 解决 NLQ4TSDB 的框架。
## 🗂️ NLQTSBench
**NLQTSBench** 是第一个用于 NLQ4TSDB 的标准化基准测试：
* **规模与多样性：** 包含跨越 **4 个难度级别**和 **9 个子任务**的 **1,153 个任务**。
* **下载：** 托管在 HuggingFace 上，地址为 [**mrtan/NLQTSBench**](https://huggingface.co/datasets/mrtan/NLQTSBench)。
## 🔍 Sonar-TS 框架
Sonar-TS 是一个三阶段 pipeline：
1. **离线数据处理** 在原始序列之上构建多尺度特征表。
2. **在线查询** 通过任务规划、代码生成和执行来运行 LLM。它的经验（例如技能）来自 *Prompt Cold Start* 循环 ([`cold_start/`](cold_start/))。
3. **后处理** 将验证后的结果渲染为自然语言答案，并提供可选的可视化。
## 🚀 快速开始
### 1. 安装依赖
```
git clone https://github.com/Atlamtiz/Sonar-TS.git
cd Sonar-TS
conda create -n sonarts python=3.11 -y && conda activate sonarts
pip install -r requirements.txt
```
### 2. 从 HuggingFace 下载基准测试数据
原始 CSV 文件（约 1.7 GB）存放在 HuggingFace 上。一条命令即可将它们拉取到预期位置：
```
python scripts/download_dataset.py
```
这会将 1,153 个 CSV 文件放置在 `nlqtsbench/ts_data/` 下。基准测试规范 (`nlqtsbench/tasks.json`) 已经在此仓库中。
### 3. 配置你的 DeepSeek API key
该框架默认使用 **DeepSeek** (`deepseek-v4-flash`)，配备 **10 个 worker 线程**，每个 worker 使用一个专属的 API key。如果有 10 个 key，完整的基准测试运行大约需要 25 分钟。
复制模板并粘贴你的 key：
```
cp -n configs/deepseek_api-key.txt.example configs/deepseek_api-key.txt
$EDITOR configs/deepseek_api-key.txt # paste one key per line
```
如果你的 key 少于 10 个，请同时降低 `configs/online.yaml` 中的 `concurrency.workers` 数量以使其匹配。
### 4. 构建任务专属的数据库 + 特征（一次性操作，约 10 分钟）
```
python -m scripts.load_benchmark # CSV → per-task database
python -m scripts.build_index # SAX feature tables per task
```
### 5. 运行基准测试
```
python main.py
```
**有用的 flags**（通过 `python main.py --help` 获取完整列表）：
| Flag | 效果 |
| --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--limit N` | 仅处理前 `N` 个任务。在提交完整的约 25 分钟运行之前，用于快速冒烟测试。 |
| `--workers N` | 覆盖 worker 线程数（默认：10，来自 `configs/online.yaml`）。如果你的 key 较少，请降低此数值。 |
| `--figures` | 同时为每个任务渲染一张 PNG (`output/figures/`)。通过多进程 Kaleido 池增加约 15-20 分钟。 |
| `--rebuild` | 丢弃 `output/predict_partial.jsonl` 并重新运行每个任务。在编辑 prompts、skills 或 configs 后使用。 |
| `--out-dir ` | 将结果写入自定义目录，而不是 `./output/`。 |
结果将以与论文对齐的按类别/按级别/总体表格的形式打印到终端，并写入 `./output/`：
```
output/
├── predict.json submission-format predictions
├── summary.json per-subtask / per-category / overall scores
└── per_task.json one row per task with prediction + score
```
### 🎯 示例输出
由 `python main.py --figures` 生成的可视化。精选样本位于 [`output/figures/examples/`](output/figures/examples/)；相应的得分明细位于 [`output/summary.json`](output/summary.json) 和 [`output/per_task.json`](output/per_task.json)。
左：形状识别。右：复合趋势。
## 📁 项目结构
```
Sonar-TS
├── main.py
├── requirements.txt
├── LICENSE
│
├── configs/
│ ├── online.yaml
│ ├── offline.yaml
│ ├── deepseek_api-key.txt.example
│ └── deepseek_api-key.txt (gitignored)
│
├── sonar_ts/
│ ├── pipeline.py
│ ├── planner.py
│ ├── generator.py
│ ├── executor.py
│ ├── evaluator.py
│ ├── llm.py
│ ├── schema.py
│ ├── storage.py
│ ├── offline.py
│ ├── prompts/
│ ├── postprocess/
│ └── skills/
│
├── scripts/
│ ├── download_dataset.py
│ ├── load_benchmark.py
│ ├── build_index.py
│ ├── run_benchmark.py
│ └── render_samples.py
│
├── cold_start/
│ ├── orchestrator.py
│ ├── run_cold_start.py
│ ├── download_train_data.py
│ ├── agents/
│ ├── train_data/
│ └── discovered_skills/
│
├── nlqtsbench/
│ ├── tasks.json
│ ├── predict_perfect.json
│ └── ts_data/
│
├── docs/figures/
│
├── databases/
└── output/
```
## 📑 引用
```
@misc{tan2026sonartssearchthenverifynaturallanguage,
title={Sonar-TS: Search-Then-Verify Natural Language Querying for Time Series Databases},
author={Zhao Tan and Yiji Zhao and Shiyu Wang and Chang Xu and Yuxuan Liang and Xiping Liu and Shirui Pan and Ming Jin},
year={2026},
eprint={2602.17001},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2602.17001},
}
```
## 🏛️ 所属机构
