哈迪兰：哈迪兰实操全指南：从零上手到稳定产出

读完这篇教程，你将掌握哈迪兰从环境配置、核心参数调优到批量任务落地的完整操作链，直接解决“装好不会用、跑通不出活”的典型问题。

1. 环境准备与基础校验

- 安装哈迪兰主程序（建议2.4.0以上版本），解压至纯英文路径，避免中文目录导致编码报错。

- 创建虚拟环境：`python -m venv hadilan_env`，激活后执行 `pip install -r requirements.txt`。若网络受限，改用清华镜像源。

- 运行 `hadilan --self-test`，看到 `ALL CHECKS PASSED` 再继续。若出现 `libssl.so` 缺失，执行 `sudo apt install libssl1.1`（Ubuntu）或 `brew install openssl`（macOS）。

2. 输入数据规范化

- 哈迪兰对输入格式极其敏感。统一使用UTF-8无BOM编码，每行一条记录，字段间用 `\t` 分隔，禁止混用逗号。

- 日期字段强制转为 `YYYY-MM-DD`，数值字段去除千分位逗号和货币符号。可用内置工具：`hadilan clean --input raw.tsv --output clean.tsv --schema schema.json`。

- 检查空值：`hadilan stats --file clean.tsv`，若缺失率>5%，用 `--fill median`（数值）或 `--fill mode`（分类）处理，切勿直接删除行。

3. 核心参数调优（决定产出质量的关键）

- 打开配置文件 `config.yaml`，重点调整三项：

- `window_size`: 滑动窗口长度，默认30。处理高频波动数据时降为10，处理长期趋势时升到90。

- `depth`: 模型层数，默认6。数据量<1万行时降到3，防止过拟合；数据量>10万行时可升到8。

- `lr`: 学习率，默认0.001。若训练损失震荡，降为0.0003；若收敛过慢，升到0.003。

- 每次修改后执行 `hadilan train --config config.yaml --data clean.tsv --output model.bin`，观察训练日志中的 `val_loss`。连续5轮不下降，立即停止并回滚参数。

4. 训练与验证流程

- 按8:2划分训练/验证集，使用 `--split 0.8` 参数，哈迪兰自动保证分层采样。

- 训练命令示例：`hadilan train --config config.yaml --data clean.tsv --output model.bin --epochs 50 --early-stop 7`。

- 验证时运行 `hadilan evaluate --model model.bin --test test.tsv`，重点看 `F1-score` 和 `AUC`。若F1<0.75，回到第3步调整参数，不要盲目增加epochs。

5. 推理与批量输出

- 单条预测：`hadilan predict --model model.bin --input "你的文本或数值"`，输出为JSON格式。

- 批量预测：`hadilan predict --model model.bin --input batch.tsv --output results.tsv --batch-size 256`。注意 `batch-size` 超过512会爆显存（GPU）或内存（CPU）。

- 结果后处理：哈迪兰输出概率值，需自行设阈值（默认0.5）。用 `--threshold 0.6` 可降低假阳性，用 `--threshold 0.4` 可提高召回率。

6. 自动化与定时任务

- 将上述命令写成 `run_pipeline.sh`，用 `cron` 或 `systemd timer` 每天定时执行。

- 在脚本末尾添加日志归档：`cp results.tsv results_$(date +%Y%m%d).tsv`，并清理7天前的旧文件。

- 设置异常告警：若 `val_loss` 超过历史均值的1.5倍，脚本发送邮件或企业微信通知。

常见坑提醒：

- 千万别用Excel直接编辑输入文件，它会偷偷改编码和日期格式，导致哈迪兰解析失败。必须用 `sed` 或 `awk` 处理。

- 调参时不要同时改 `window_size` 和 `depth`，一次只动一个变量，否则你永远不知道是哪个参数导致效果变差。

- 训练中途断电或Ctrl+C，`model.bin` 会损坏。训练前先 `cp model.bin model.bak`，恢复时用备份。

- 推理阶段严禁修改 `config.yaml`，模型结构已经固化，改了参数会直接报 `shape mismatch` 错误。

- 若遇到 `NaN loss`，检查输入数据是否有无穷值，用 `awk '$1+0!=$1{print}'` 找出脏数据并删除。