MigrationGPT

MigrationGPT 是一个基于大语言模型（LLM）的鸟类迁徙轨迹建模与分析框架。它利用 Qwen 模型，结合 H3 地理空间索引，将鸟类的迁徙路径转化为序列数据进行训练，从而学习迁徙模式并评估轨迹的“困惑度”（Perplexity）。

核心特性

• 混合编码 (Hybrid Encoding): 将轨迹点编码为 H3 空间 Token，并辅以归一化的连续特征（经纬度、位移距离、时间正弦/余弦编码）。
• 高效数据处理: 基于 Polars 的高性能数据清洗、重采样和特征工程管道。
• 定制化 Tokenizer: 替换 LLM 原有词表，构建专用的地理空间词表，大幅降低序列长度并提升模型专注度。
• 端到端工作流: 提供从原始 CSV 数据清洗、模型微调到推理评估和可视化的完整脚本支持。

安装

确保你的环境满足 requirements.txt 中的依赖：

pip install -r requirements.txt

主要依赖包括：

• torch
• transformers
• polars
• h3
• matplotlib, scipy (用于可视化)

快速开始

本项目的工作流分为五个主要步骤：

1. 数据筛选 (Filter)

从原始 CSV 数据中筛选出记录时长超过特定阈值（如 5000 小时）的鸟类数据。

python scripts/filter_data.py \
    --input data/raw_csvs \
    --output results/filtered \
    --min-hours 5000

2. 数据预处理 (Process)

对筛选后的数据进行重采样（Resampling）和特征工程，生成训练所需的 Parquet 文件。

python scripts/process_new_data.py \
    --input results/filtered/processed.parquet \
    --output results/processed \
    --interval-hours 2 \
    --h3-resolution 6

3. 模型训练 (Train)

使用 HuggingFace Trainer 对 Qwen 模型进行微调。脚本会自动替换词表并调整模型 Embedding 层。

python scripts/train.py \
    --data-path results/processed/features.parquet \
    --model-name-or-path Qwen/Qwen3-0.6B \
    --output-dir results/training \
    --epochs 3 \
    --batch-size 4

4. 推理与评估 (Inference)

计算模型对特定鸟类或物种轨迹的困惑度（Perplexity）。困惑度越低，说明模型认为该轨迹越符合学习到的迁徙模式。

# 计算所有鸟类的困惑度
python scripts/inference.py \
    --model-dir results/training/final_model \
    --data-path results/processed/features.parquet \
    --output results/perplexity.csv \
    --all

5. 可视化 (Visualize)

生成困惑度分布的统计图表（箱线图、小提琴图、密度图等），用于对比不同物种或群体的迁徙模式差异。

python scripts/visualize_perplexity.py \
    --input results/perplexity.csv \
    --output results/plots \
    --plot-type all

项目结构

MigrationGpt/
├── data/                   # 数据存放目录
├── results/                # 输出结果目录
├── scripts/                # 命令行工具脚本
│   ├── filter_data.py          # 数据筛选
│   ├── process_new_data.py     # 数据预处理
│   ├── train.py                # 模型训练
│   ├── inference.py            # 推理评估
│   └── visualize_perplexity.py # 结果可视化
├── src/                    # 核心源码
│   ├── models/                 # 模型相关逻辑
│   │   ├── encoding.py             # 特征编码
│   │   ├── tokenizer_utils.py      # Tokenizer 处理
│   │   └── training.py             # 训练辅助函数
│   └── pre_process/            # 数据预处理逻辑
│       ├── pipeline_polars.py      # 清洗管道
│       └── resamping_polars.py     # 重采样算法
└── requirements.txt        # 项目依赖