Marin

"我不害怕风暴，因为我正在学习如何掌舵我的船。"
– 路易莎·梅·奥尔科特

Marin 是一个用于研究和开发 基础模型 的开源框架。

Marin 的一个关键特性是 可复现性：从原始数据到最终模型的每一步都会被记录下来，而不仅仅是最终结果。 这包括失败的实验，因此整个研究过程都是透明的。

Marin 的主要应用场景是训练语言模型，如 Llama、DeepSeek、Qwen 等。具体来说，涵盖了数据整理、转换、过滤、分词、训练和评估等环节。

我们使用 Marin 训练了首个性能超越 Llama 3.1 8B 的开源 8B 参数模型。你可以查看 训练脚本 或阅读 回顾报告。

Marin 的文档可以在 ReadTheDocs 或 docs/ 文件夹中找到。

要开始使用 Marin：

• 安装 Marin。
• 使用 Marin 训练一个 小型语言模型。
• 查看如何使用 Marin 运行规模更大的 DCLM 1B/1x 实验。
• 参阅我们已运行的 实验汇总。
• 参与 Marin 的 Speedrun 比赛，尝试找到训练语言模型的最高效方式。
• 加入 Marin Discord，与社区成员交流。

示例

Marin 中的实验被定义为一组可以相互依赖并按拓扑顺序执行的步骤，类似于 Makefile。

作为使用 Marin 的简短示例，这里提供了一个在 TinyStories 数据集上训练小型模型的完整脚本。更多细节请参阅 完整脚本。

from fray.cluster import ResourceConfig

from experiments.defaults import default_tokenize, default_train
from experiments.llama import llama3_tokenizer, llama_nano
from experiments.simple_train_config import SimpleTrainConfig
from marin.execution.executor import executor_main

# 1. 选择数据集
tinystories_hf_id = "roneneldan/TinyStories"

# 2. 对数据集进行分词
tinystories_tokenized = default_tokenize(
    name=tinystories_hf_id,  # 分词文件的保存路径（会自动加上 tokenized/ 前缀）
    dataset=tinystories_hf_id,  # Hugging Face 数据集 ID
    tokenizer=llama3_tokenizer,
)

# 3. 定义训练配置
nano_train_config = SimpleTrainConfig(
    # 定义所需的硬件资源
    resources=ResourceConfig.with_cpu(),
    train_batch_size=4,
    num_train_steps=100,
    # 设置超参数
    learning_rate=6e-4,
    weight_decay=0.1,
    # 为了教程快速完成，限制评估批次
    max_eval_batches=4,
)

# 4. 训练模型
nano_tinystories_model = default_train(
    name="marin-nano-tinystories",
    # 步骤之间可以相互依赖：nano_tinystories_model 依赖于 tinystories_tokenized
    tokenized=tinystories_tokenized,
    model_config=llama_nano,
    train_config=nano_train_config,
    # wandb 标签
    tags=["llama", "nano", "tinystories", "tutorial"],
    # 在训练过程中可以运行许多 [eval_harness](https://github.com/EleutherAI/lm-evaluation-harness) 任务
    # 但对于这么小的模型来说，没有必要进行评估
    eval_harness_tasks=[],
    # 为了加快教程速度，跳过默认验证集
    use_default_validation=False,
)

if __name__ == "__main__":
    executor_main(steps=[
        nano_tinystories_model,
    ])

在这里，我们创建了两个 步骤，一个是用于对数据集进行分词，另一个是用于训练模型。训练步骤依赖于分词步骤，因此会在分词完成后执行。

稍作修改，你就可以将其扩展到在更大规模的数据集上训练更大的模型（训练大模型指南），或者处理 多源混合数据集，甚至可以扩展到非常大的 TPU Pod（或多切片 TPU，以及不久后的多节点 GPU）。

代理技能

• 请查看 .agents/skills/（以及 .claude/skills/）以获取可加载的代理技能。例如，.agents/skills/add-dataset/ 提供了添加新数据集的分步指南。

Marin 快速上手指南

Marin 是一个用于基础模型（Foundation Models）研发与训练的开源框架。其核心优势在于可复现性：从原始数据到最终模型的每一步（包括数据清洗、分词、训练、评估及失败的实验）都会被完整记录，确保研究过程的透明化。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux 或 macOS（推荐 Linux 以获得最佳兼容性）。
• Python：建议 Python 3.10 或更高版本。
• 硬件资源：
  • 入门/教程：CPU 即可运行微型模型训练示例。
  • 生产/大规模训练：支持多节点 GPU 集群及 TPU Pods。
• 前置依赖：
  • git：用于克隆代码库。
  • pip：Python 包管理工具。
  • （可选）conda 或 venv：建议使用虚拟环境隔离依赖。

提示：由于 Marin 涉及大量数据处理和深度学习依赖，建议配置稳定的网络连接以加速 PyTorch 及相关库的下载。如有条件，可配置国内 PyPI 镜像源加速 pip 安装。

安装步骤

1. 克隆仓库

   git clone https://github.com/marin-community/marin.git
   cd marin
   

2. 创建并激活虚拟环境

   python -m venv .venv
   source .venv/bin/activate  # Linux/macOS
   # .venv\Scripts\activate   # Windows
   

3. 安装 Marin 及其依赖

   pip install -e .
   

   注：根据具体硬件（如 NVIDIA GPU 或 TPU），可能需要额外安装特定版本的 PyTorch 或 JAX。请参考官方文档中的 安装指南 获取详细配置。

基本使用

Marin 的实验被定义为一系列相互依赖的步骤（Steps），类似于 Makefile，按拓扑顺序执行。以下是一个在 CPU 上使用 TinyStories 数据集训练微型语言模型的完整示例。

1. 创建训练脚本

新建一个 Python 文件（例如 train_tiny.py），填入以下代码：

from fray.cluster import ResourceConfig

from experiments.defaults import default_tokenize, default_train
from experiments.llama import llama3_tokenizer, llama_nano
from experiments.simple_train_config import SimpleTrainConfig
from marin.execution.executor import executor_main

# 1. 选择数据集
tinystories_hf_id = "roneneldan/TinyStories"

# 2. 对数据集进行分词 (Tokenize)
tinystories_tokenized = default_tokenize(
    name=tinystories_hf_id,  # 写入分词文件的路径前缀
    dataset=tinystories_hf_id,  # HuggingFace 数据集 ID
    tokenizer=llama3_tokenizer,
)

# 3. 定义训练配置
nano_train_config = SimpleTrainConfig(
    # 定义硬件资源，此处使用 CPU
    resources=ResourceConfig.with_cpu(),
    train_batch_size=4,
    num_train_steps=100,
    # 设置超参数
    learning_rate=6e-4,
    weight_decay=0.1,
    # 为加快教程速度，减少评估批次
    max_eval_batches=4,
)

# 4. 训练模型
nano_tinystories_model = default_train(
    name="marin-nano-tinystories",
    # 步骤依赖：训练步骤依赖于分词步骤
    tokenized=tinystories_tokenized,
    model_config=llama_nano,
    train_config=nano_train_config,
    # WandB 标签
    tags=["llama", "nano", "tinystories", "tutorial"],
    # 评估任务列表（微型模型可留空以加快速度）
    eval_harness_tasks=[],
    # 跳过默认验证集以加快教程运行
    use_default_validation=False,
)

if __name__ == "__main__":
    executor_main(steps=[
        nano_tinystories_model,
    ])

2. 运行实验

在终端中执行该脚本：

python train_tiny.py

3. 流程说明

• 依赖管理：default_train 步骤依赖于 tinystories_tokenized 步骤。Executor 会自动先执行分词，待完成后才开始训练。
• 扩展性：通过修改 ResourceConfig 和数据集配置，您可以轻松将此示例扩展为在大型 GPU 集群上训练更大规模的模型（如 Llama 3、DeepSeek 等），或混合多种数据源。

更多高级用法，如训练 DCLM 1B 模型或参与 Speedrun 竞赛，请参阅官方文档中的 训练语言模型教程。