Metadata-Version: 2.4
Name: saddlellm
Version: 2.32
Summary: LLM training, fine-tuning, distillation, quantization and deployment toolkit
Author: niqinggood
Author-email: niqinggood@163.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch
Requires-Dist: transformers
Requires-Dist: datasets
Requires-Dist: peft
Requires-Dist: trl
Requires-Dist: bitsandbytes
Requires-Dist: fastapi
Requires-Dist: pydantic
Requires-Dist: psutil
Requires-Dist: nvidia-ml-py
Requires-Dist: prometheus_client
Requires-Dist: prometheus_fastapi_instrumentator
Requires-Dist: evaluate
Requires-Dist: numpy
Requires-Dist: tqdm
Requires-Dist: accelerate
Requires-Dist: pyyaml
Provides-Extra: data
Requires-Dist: datasketch; extra == "data"
Requires-Dist: langdetect; extra == "data"
Requires-Dist: pyarrow; extra == "data"
Requires-Dist: simhash; extra == "data"
Provides-Extra: text
Requires-Dist: beautifulsoup4; extra == "text"
Requires-Dist: chardet; extra == "text"
Requires-Dist: dateparser; extra == "text"
Requires-Dist: emoji; extra == "text"
Requires-Dist: ftfy; extra == "text"
Requires-Dist: jieba; extra == "text"
Requires-Dist: nltk; extra == "text"
Requires-Dist: pandarallel; extra == "text"
Requires-Dist: pypinyin; extra == "text"
Requires-Dist: rapidfuzz; extra == "text"
Requires-Dist: scikit-learn; extra == "text"
Requires-Dist: sentence-transformers; extra == "text"
Requires-Dist: slimit; extra == "text"
Requires-Dist: unidecode; extra == "text"
Requires-Dist: zhconv; extra == "text"
Requires-Dist: zstandard; extra == "text"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SaddleLLM

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

当前版本：`2.31`

> 建议先运行环境检查、数据检查和 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 或其他可选依赖。

## 安装

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

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

验证安装：

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

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

```powershell
python -m saddle_llm.cli --help
```

## 最短上手流程

### 1. 检查环境

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

### 2. 运行内置 smoke test

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

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

```powershell
saddle-llm smoke-test --skip-training
```

### 3. 检查训练数据

```powershell
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`

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

### 5. Dry-run 和训练

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

训练失败时显示完整 traceback：

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

推荐顺序：

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

## Python API

### 创建领域训练工厂

```python
from saddle_llm import LLMTrainingFactory

factory = LLMTrainingFactory.for_domain(
    domain="general",
    root_dir="./llm_factory",
    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 计划

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

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

### 创建 DPO 计划

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

### 执行 Orchestrator 配置

```python
from saddle_llm import TrainingOrchestrator

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

## 数据格式

### SFT：Alpaca JSONL

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

### SFT：Messages JSONL

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

### Preference：DPO/ORPO JSONL

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

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


## 测试

```powershell
python -m pytest -q
```

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

## 目录结构

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

## 文档导航

- [完整文档](SADDLE_LLM_FULL_DOCUMENTATION.md)
- [训练指南](TRAINING_GUIDE.md)
- [代码学习指南](SADDLE_LLM_CODE_GUIDE.md)


## 当前边界

- CLI、数据检查、Recipe、Orchestrator 和 smoke-test 是推荐入口。
- native GRPO 适合小规模研究和链路验证；大规模实验应进一步验证吞吐、分布式和 checkpoint 行为。
- VLA、多模态、部分高级架构及部分第三方后端仍属于实验性能力。

## License

MIT
