SaddleLLM

SaddleLLM 是一个面向本地研究与工程实验的大语言模型训练工具包，覆盖数据检查、训练规划、SFT、偏好优化、RL/GRPO、评估、蒸馏、量化和部署等流程。

当前版本：2.30.0

建议先运行环境检查、数据检查和 dry-run，再启动真实训练。仓库包含稳定主线和实验性模块，并非所有功能都适合直接用于大规模生产训练。

主要能力

• 训练工厂：领域工作区、Recipe、Orchestrator 和实验产物管理
• 数据处理：SFT、DPO、ORPO、KTO、RL/GRPO 和 VLA 数据检查与规范化
• 后训练：Full Fine-tuning、LoRA、QLoRA、SFT 和 preference optimization
• 强化学习：native GRPO、可验证奖励和 source-frontier profiling
• 模型实验：Dense、GQA、MoE、MLA、MTP 和 Long Context blueprint
• 评估与诊断：Benchmark、训练报告、环境检查和 smoke test
• 模型工程：蒸馏、量化、剪枝、部署和安全生成
• 多模态/VLA：提供实验性的数据、模型和训练入口

环境要求

• Python >=3.8；建议使用 Python 3.10+
• PyTorch
• Transformers
• Datasets
• PEFT
• TRL
• NVIDIA GPU（真实模型训练建议使用）

部分后端能力还需要 DeepSpeed、bitsandbytes、xFormers、flash-attn 或其他可选依赖。

安装

建议在独立虚拟环境中使用：

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

验证安装：

python -c "import saddle_llm; print(saddle_llm.__version__)"
saddle-llm --help

如果不安装 console script，也可以使用：

python -m saddle_llm.cli --help

最短上手流程

1. 检查环境

saddle-llm doctor
saddle-llm doctor --output build\doctor_report.json

2. 运行内置 smoke test

saddle-llm smoke-test --in-process --skip-doctor `
  --work-dir build\smoke_e2e_fast

只检查 fixture、数据和配置，不执行训练：

saddle-llm smoke-test --skip-training

3. 检查训练数据

saddle-llm inspect-data data\sft.jsonl --task sft
saddle-llm inspect-data data\preference.jsonl --task dpo
saddle-llm inspect-data data\rl.jsonl --task grpo

4. 检查并编译配置

仓库提供了以下模板：

• configs/sft_lora.yaml
• configs/dpo_qlora.yaml
• configs/preflight.yaml
• configs/vla_sft.yaml
• configs/mopd_sft.yaml

saddle-llm validate-config configs\sft_lora.yaml
saddle-llm plan configs\sft_lora.yaml

5. Dry-run 和训练

saddle-llm train configs\sft_lora.yaml --dry-run
saddle-llm train configs\sft_lora.yaml

训练失败时显示完整 traceback：

saddle-llm train configs\sft_lora.yaml --debug

推荐顺序：

doctor
  -> smoke-test --skip-training
  -> inspect-data
  -> validate-config
  -> preflight
  -> plan
  -> train --dry-run
  -> train
  -> report

Python API

创建领域训练工厂

from saddle_llm import LLMTrainingFactory

factory = LLMTrainingFactory.for_domain(
    domain="public_policy",
    root_dir="./llm_factory_public_policy",
    base_model="Qwen/Qwen2.5-7B-Instruct",
    max_seq_length=2048,
    global_batch_size=16,
    num_gpus=1,
    gpu_memory_gb=24.0,
)

factory.create_workspace()
factory.save_plan()

创建 SFT 计划

plan = factory.create_post_training_plan(
    data_path="./data/sft.jsonl",
    stage="sft",
    method="qlora",
    max_steps=1000,
    save=True,
)

该调用会生成规范化数据、Recipe、Orchestrator config 和训练计划。

创建 DPO 计划

plan = factory.create_post_training_plan(
    data_path="./data/preference.jsonl",
    stage="dpo",
    method="qlora",
    beta=0.1,
    save=True,
)

执行 Orchestrator 配置

from saddle_llm import TrainingOrchestrator

orchestrator = TrainingOrchestrator.from_yaml("./configs/train.yaml")
result = orchestrator.run()

数据格式

SFT：Alpaca JSONL

{"instruction":"总结下面的政策意见","input":"...","output":"..."}

SFT：Messages JSONL

{"messages":[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]}

Preference：DPO/ORPO JSONL

{"prompt":"...","chosen":"更好的回答","rejected":"较差的回答"}

在加载模型前运行 inspect-data，可以检查字段、重复样本、长度和 chosen == rejected 等问题。

Qwen3 Public Policy RLVR Pilot

仓库包含一个已经实际跑通的最小实验：

Qwen3-0.6B baseline evaluation
  -> Dataset A source profiling
  -> LoRA + GRPO/RLVR
  -> Benchmark A/B post evaluation
  -> metrics, raw predictions and adapter

Qwen3 需要 transformers>=4.51.0。为避免影响仓库原有环境，建议使用单独环境：

python -m venv --system-site-packages build\venv_qwen3
build\venv_qwen3\Scripts\python -m pip install `
  -r experiments\public_policy_rlvr\requirements.txt

先检查数据、切分和奖励：

build\venv_qwen3\Scripts\python `
  experiments\public_policy_rlvr\run.py --dry-run

运行完整 smoke experiment：

build\venv_qwen3\Scripts\python `
  experiments\public_policy_rlvr\run.py

也可以通过 Python API 调用：

from saddle_llm import (
    PublicPolicyPilotConfig,
    dry_run_public_policy_pilot,
    run_public_policy_pilot,
)

config = PublicPolicyPilotConfig.from_yaml(
    "experiments/public_policy_rlvr/smoke.yaml"
)

dry_run_public_policy_pilot(config)
result = run_public_policy_pilot(config)
print(result["delta"])

这个 smoke test 用于验证软件链路，不应被当作 RLVR 能够提升泛化能力的统计证据。正式实验仍需更大的 Benchmark、matched SFT/RL controls、多个随机种子和显著性检验。

测试

python -m pytest -q

当前项目级 pytest.ini 会排除 build/、dist/ 和 external_research/，避免测试发现过程进入第三方研究仓库。

目录结构

configs/                    训练 Recipe 模板
experiments/                可执行实验
outputs/                    实验输出
saddle_llm/                 Python 包源码
tests/                      项目测试
SADDLE_LLM_FULL_DOCUMENTATION.md
SADDLE_LLM_CODE_GUIDE.md
TRAINING_GUIDE.md

文档导航

• 完整文档
• 训练指南
• 代码学习指南
• Public Policy RLVR Pilot
• Public Policy RLVR 配置

当前边界

• CLI、数据检查、Recipe、Orchestrator 和 smoke-test 是推荐入口。
• native GRPO 适合小规模研究和链路验证；大规模实验应进一步验证吞吐、分布式和 checkpoint 行为。
• Public Policy A/B 数据来自同一 AASB 语料。仓库默认使用 joint group split 防止案例泄漏，但该实验更准确的表述是 cross-task transfer，而不是广义跨领域 OOD generalization。
• VLA、多模态、部分高级架构及部分第三方后端仍属于实验性能力。

License

MIT