# 论文 vs 代码一致性核查：MLLM-TSAD

- 论文：Can Multimodal LLMs Perform Time Series Anomaly Detection?（arXiv:2502.17812 v2，WWW '26，Xiongxiao Xu 等）
- 仓库：https://github.com/mllm-ts/VisualTimeAnomaly（浅克隆至 `workdir/p2-tsad`，最新提交 `7158c4f`，2026-02-14）
- 核查日期：2026-10-24

## 核查对象与方法（含命令）

```bash
# 1. 浅克隆官方仓库
git clone --depth 1 https://github.com/mllm-ts/VisualTimeAnomaly.git \
  "<项目目录>/workdir/p2-tsad"
# 2. 论文全文（PDF 17 页，v2）
curl -sL -m 60 https://arxiv.org/pdf/2502.17812 -o /tmp/p2.pdf
# 3. 代码静态检查：通读 README.md、src/ 全部 11 个 .py/.sh 文件
#    （generator.py / utils.py / prompt.py / main.py / config.py /
#      dataloader.py / result_agg.py / openai|gemini|llava|qwen_api.py / *.sh）
# 4. 轻量运行：uv 建临时 venv（numpy/scipy/pandas/matplotlib/tqdm），
#    运行 generator.py 生成小样本并验证图像尺寸、data.pkl 与 prompt 构建
```

## 论文关键声明清单

1. 方法：时间序列数值 → 图像（TSI Construction）→ 文本 prompt + 图像输入 MLLM，zero-shot 检测（Fig 1）。
2. 异常粒度：2 类 point（global/contextual）、3 类 range（seasonal/trend/shapelet）、4 类 variate（triangle/square/sawtooth/random），外加 irregular（随机丢点）。
3. 数据：合成 sine/cosine；单变量长 400、多变量长 200；异常注入比例 5%；"points or ranges of length 20"；每类 100 个 TSI 且噪声不同；真实数据 UCR Symbol（单变量）、UEA ArticularyWordRecognition（多变量）；不规则率 r=0%~25%（步长 5%），irregular 场景不含 contextual。
4. 多变量 variate 异常："one variate-wise anomaly is injected into a 20-variate time series"（维持 5% 比例）。
5. MLLM：GPT-4o、GPT-4o-mini、Gemini-1.5-Pro、Gemini-1.5-Flash、LLaVA-NeXT-72B/8B、Qwen2-VL-72B/7B；temperature=0.4（附录 B）；8×A6000。
6. 评测指标：precision、recall、F1；每实验 100 图像跑 3 次。
7. 关键报告数字：max F1 point 4.09 / range 50.33 / variate 63.40（Fig 3）；Gemini range F1 30.34→30.39（r=0%→25%）；幻觉频率表（Table 3）等。
8. RQ3：text / vision / T+V 三种输入模态对比（Fig 7、Table 3）。
9. 对照实验：传统基线 iForest、OCSVM、OmniAnomaly、THOC、TranAD；ViTST（C1 视觉单独）等。
10. TSAD-Agents：Scanning/Planning/Detection/Checking 四 agent，LangChain 实现、Gemini 驱动，含 iForest 与 Gemini 工具集（Table 4）。
11. 数据集发布：README 声称发布 12.4k 图像数据集。

## 证据对照表

| # | 论文声明 | 代码证据（文件:行号） | 判定 |
|---|---|---|---|
| 1 | 数值→图像转换 | `src/generator.py:262-275`（单变量 `plot_series`，figsize 10×1.5）、`src/generator.py:101-113`（多变量 `plot_rectangle_stack_series`，figsize 10×10）、实现于 `src/utils.py:98-157`；train 集画 GT 高亮、eval 集不画（`utils.py:127-154`） | 一致（运行实测 1000×150 / 1000×1000 px） |
| 2 | 单变量 400 / 多变量 200 | `src/generator.py:217`（`STREAM_LENGTH=400`）、`src/generator.py:66`（`STREAM_LENGTH=200`）；运行实测 series len=400、shape=(200,4) | 一致 |
| 3 | 合成 sine/cosine | `src/generator.py:69` `behavior=[sine, cosine]` | 一致 |
| 4 | 2+3+4 类异常 | `src/generator.py:237-246`（global/contextual/seasonal/trend/shapelet）、`src/generator.py:70-75`（triangle/square/sawtooth/random_walk） | 一致 |
| 5 | 5% 异常比例（单变量） | `src/generator.py:238-246` 各异常 `ratio=0.05`；运行实测 400 点含 20 异常点 | 一致 |
| 6 | "ranges of length 20" | `src/generator.py:238-246` `radius=5`（每段 10 点）×`0.05/(2×5)=2` 段=共 20 点 | 解释性一致（"length 20"按总异常长度理解；论文表述含糊） |
| 7 | 20-variate 注入 1 个异常（5%） | `src/generator.py:162-164` 异常变量数随机 `randint(1, floor(sqrt(dim))-1)`；`src/test.sh:16` dim 列表为 4 9 16 25 36（无 20）；`src/generator.py:413` 默认 dim=9 | 不一致/表述不符：非固定 1 个且无 dim=20；对 dim=9 为 1~2 个（约 11%~22% 比例） |
| 8 | 不规则 0-25% 步长 5%、随机丢点、irr 无 contextual | `src/generator.py:174-190`（`drop()` 随机置 NaN）；`src/generator.sh`（drop_ratio 0.05…0.25，irr 异常列表无 contextual） | 一致 |
| 9 | 真实数据 Symbol / ArticularyWordRecognition | `src/generator.py:146/296` 读 `Univariate_arff`/`Multivariate_arff` 下 .arff；`src/main.py:182` 支持该 tsname | 部分：代码支持，但 .arff 数据文件与下载脚本均不在仓库 |
| 10 | 8 个 MLLM | `src/main.py:177-179` choices（gpt-4o、gpt-4o-mini、gemini-1.5-pro、gemini-1.5-flash、llama3-llava-next-8b、llava-next-72b、Qwen2-VL-7B/72B-Instruct）；`src/llava_api.py:16-22`（llava-hf/{model}-hf）、`src/qwen_api.py:16-20` | 一致（LLaVA-NeXT-8B 对应 `llama3-llava-next-8b`，与附录 B"LLaMA3-8B 底座"吻合） |
| 11 | temperature=0.4 | `src/prompt.py:83` 默认 0.4；`src/gemini_api.py:62`、`src/llava_api.py:82`、`src/qwen_api.py:82` | 一致 |
| 12 | zero-shot | `src/config.py:3-10` 仅 `0shot-vision` variant（vision=True、few_shots=0）；`src/main.py:176` 默认值；`create_vision_messages` 未使用 few_shots 参数（`src/prompt.py:28-77`） | 一致 |
| 13 | 评测 P/R/F1 | `src/result_agg.py:40-77`（sklearn precision/recall/f1） | 一致；注意细节：单变量最终表改用 affiliation F1（`result_agg.py:372-374`），论文正文未提 affiliation |
| 14 | prompt 模板（附录 C 三类） | `src/prompt.py:7-20` 与附录 C 逐字一致（连 range prompt 的 "incluing" 拼写错误都相同，`prompt.py:12`） | 一致 |
| 15 | RQ3：text / vision / T+V | `src/config.py` 仅 vision variant；`src/prompt.py:79-98` 中 `vision=False` 分支无 messages 实现 | 不一致：text 与 T+V 模态的推理实现缺失 |
| 16 | 传统基线 iForest/OCSVM/OmniAnomaly/THOC/TranAD、ViTST | 全仓库 grep `iforest|isolation|vitst|ocsvm|OneClass|omni|tranad|thoc` 无任何匹配 | 缺失（无法验证） |
| 17 | TSAD-Agents 四 agent + LangChain + Gemini | 全仓库 grep `agent|langchain`（.py/.sh/.md）无任何匹配；`src/` 无 agent 相关文件 | 缺失：论文第 6 节核心框架（Table 4 全部结果）无实现 |
| 18 | 12.4k 图像数据集已发布 | README.md:14 声称 "release the dateset and code"；仓库实际无 data/、无 .pkl/.arff；按 generator.sh 组合推算 eval 集图像数 = 500+2000+2000+2000（合成）+400+1500+2000+2000（真实）= 12400，与 12.4k 吻合 | 部分：数量声明与配置组合吻合，但数据集文件未随仓库发布 |
| 19 | 每实验 100 图像跑 3 次 | `src/main.py:33-171` 仅有失败重试逻辑（num_retries=4），无"重复 3 次"的脚本 | 无法验证（可能为人工重复） |
| 20 | 幻觉频率统计（Table 3）、Fig 3-7 绘图脚本 | 仓库无对应统计/绘图脚本 | 无法验证 |

## 运行尝试记录

1. `git clone --depth 1` 成功；仓库仅 12 个文件（README、LICENSE、teaser.png、src/ 下 11 个 .py/.sh），无 tests/、无 CI。
2. 论文 PDF 下载成功（17 页，arXiv v2，2026-02-17 版本，WWW '26 正式版）。
3. 依赖环境：系统 Python 3.13 与 miniconda base 均缺 numpy 等；用 `uv venv /tmp/p2venv` 安装 numpy/scipy/pandas/matplotlib/tqdm 成功。
4. 生成器运行成功：
   - `python generator.py --category synthetic --scenario univariate --anomaly_type global --num_ts 2 --seed 0` → 生成 train/eval 各 2 张图与 data.pkl；
   - `python generator.py --category synthetic --scenario multivariate --anomaly_type triangle --num_ts 1 --dim 4 --seed 0` → 生成 1 张图。
5. 产物验证：单变量 PNG 1000×150 RGBA、多变量（dim=4，2×2 布局）PNG 1000×1000 RGBA；data.pkl 中单变量长度 400、异常点 20 个（5%）；多变量 (200, 4)、异常 variate id=[2]。
6. prompt 链路验证：`create_openai_request(vision=True, ...)` 返回 temperature=0.4、base64 `image_url`，三类 prompt 文本与附录 C 一致。
7. 未运行 `main.py` 端到端推理：需要 API credentials（`src/credentials.yml` 因含密钥被环境安全策略禁止读取，未尝试）与 LLaVA/Qwen 大模型权重；按要求未下载权重与大数据集。
8. 测试生成的 `src/data/`（约 428KB）保留在 workdir 作为运行证据（清理删除操作被安全策略阻止）。

## 官方性确认

- 确认官方：README.md:1-2 标题与 arXiv:2502.17812 链接匹配；论文第 2 页脚注 1 明确指向 `https://github.com/mllm-ts/VisualTimeAnomaly`；LICENSE 为 MIT，Copyright (c) 2025 mllm-ts（作者机构 org）。
- 小瑕疵：README 标注 "WWW (The Web Conference)'25"，与正式出版信息 WWW '26 不一致（疑似历史笔误）；README "release the dateset" 含拼写错误且数据集实际未随仓库发布。

## 结论

**部分一致**。

- 一致且可运行验证的部分：VisualTimeAnomaly benchmark 的数据生成（长度 400/200、5% 单变量异常比例、2+3+4 类异常、不规则丢点机制、每类 100 样本）、时间序列→图像的可视化转换、附录 C 的三类 prompt、8 个 MLLM 接入、temperature=0.4、zero-shot vision 推理、P/R/F1 评测。生成器与 prompt 链路已实际运行通过。
- 缺失/不一致的部分：(1) 论文第 6 节核心贡献 TSAD-Agents（四 agent、LangChain）在仓库中完全无实现；(2) RQ3 的 text 与 T+V 模态推理实现缺失（仅 vision）；(3) 传统基线（iForest/OCSVM/OmniAnomaly/THOC/TranAD）与 ViTST 对照实验无实现；(4) 多变量异常比例声明（20 维 1 个=5%）与代码不符（dim 4/9/16/25/36、异常变量数 1~⌊√dim⌋−1 随机）；(5) 12.4k 数据集未随仓库发布（需自生成，真实数据 .arff 需自行获取）；(6) 论文图表与幻觉统计脚本不在仓库，Table 4 等数字无法验证。因此仓库仅覆盖论文 benchmark 的 vision 部分，无法完整复现论文全部实验与数字。

## 局限

- 未实际调用任何 MLLM API/模型推理（无凭证、不下载权重），论文报告数字（如 F1 4.09/50.33/63.40、Table 3/4）只能静态核对无法数值复现。
- 论文 v2（2026-02-17）与仓库最新提交（2026-02-14）时间相近但非同版；TSAD-Agents 等实现可能在论文作者其他未公开分支，本核查仅覆盖 GitHub 默认分支。
- "ranges of length 20" 与 3 次重复实验等表述按最合理解释判定，论文本身存在模糊性。