nanoGPT：Karpathy 开源的极简型 GPT 开发工具，支持多硬件适配与 GPT-2 复现

一、nanoGPT是什么？

nanoGPT是由AI研究者Andrej Karpathy开发的开源项目，基于PyTorch框架构建，定位为“最简单、最高效的中等规模GPT训练与微调仓库”。它是minGPT的重写版本，核心目标是“优先实用性而非教育性”，通过精简的代码（核心文件仅约300行/个）降低大语言模型（LLM）开发门槛，同时支持从零训练新模型、基于GPT-2等预训练权重微调，以及多硬件环境（GPU、CPU、Apple Silicon MPS）适配。该项目可在单节点8XA100 40GB GPU上用4天复现124M参数的GPT-2模型，且支持通过分布式训练进一步提升效率，适合AI研究者、开发者、学生及小团队开展中等规模LLM的开发与实验，是学习LLM训练逻辑、定制化模型开发的优质工具。

nanoGPT并非一个“全新的大语言模型”，而是一套用于“训练、微调中等规模GPT模型”的开源工具集，核心价值在于“用极简代码实现高效的LLM开发流程”。目前仍处于积极开发阶段，但核心功能已稳定可用于实战。

从项目定位来看，nanoGPT有三个核心属性：

1. 对minGPT的“实用性升级”：nanoGPT是minGPT的重写版本，minGPT更侧重“教育性”（帮助开发者理解GPT原理），而nanoGPT则优先“实战性”——去掉冗余的教学代码，保留核心训练逻辑，同时优化性能，使其能快速适配真实场景的模型训练需求（如复现GPT-2、微调特定领域模型）。

2. 中等规模LLM的“轻量化工具”：与支持千亿参数模型的Megatron-LM等工具不同，nanoGPT聚焦“中等规模GPT”（如GPT-2 124M~1.3B参数），无需依赖超大规模计算集群，普通GPU（如单张A100）、甚至CPU、Apple Silicon Macbook都能运行，降低了LLM开发的硬件门槛。

3. “可 hack 性”极强的代码库：nanoGPT的核心文件（model.py模型定义、train.py训练循环）均仅约300行代码，结构清晰、无冗余封装，开发者可快速修改核心逻辑（如调整Transformer层数、注意力机制、训练参数），适配自定义需求（如添加新的嵌入层、修改损失函数）。

此外，nanoGPT的核心能力已得到验证：文档明确提到，其train.py脚本可在单节点8XA100 40GB GPU上，用约4天时间复现124M参数的GPT-2模型，且训练出的模型在OpenWebText数据集上的验证损失（val/loss）可达到~2.85，与GPT-2原模型在该数据集上的微调后性能持平（原GPT-2在OpenWebText上的初始验证损失约3.11，微调后降至2.85左右）。

二、nanoGPT的功能特色

nanoGPT的核心优势围绕“简洁、高效、灵活、易上手”展开，具体可拆解为五大功能特色：

1. 代码极简：核心逻辑透明，易修改、易调试

nanoGPT摒弃了复杂的框架封装，核心功能通过少数几个文件实现，且每个文件的代码量极少，开发者可快速掌握全流程逻辑：

• model.py（约300行）：完整定义GPT模型结构，包括嵌入层（Token Embedding + Position Embedding）、Transformer块（多头注意力、层归一化、FeedForward网络）、输出层（线性映射+Softmax），同时支持加载OpenAI官方的GPT-2权重；

• train.py（约300行）：实现端到端训练循环，包括数据加载、梯度计算、优化器更新、验证损失监控、Checkpoint保存（定期保存最优模型），逻辑清晰到“每一行都可追溯”；

• sample.py（约200行）：实现模型推理功能，支持从预训练模型（如GPT-2-xl）或自定义训练的模型中采样生成文本，可指定起始prompt、生成数量、最大长度等参数；

• 辅助文件精简：configurator.py负责参数配置，bench.py用于性能基准测试，无多余依赖文件，项目结构一目了然（如图1所示）。

这种极简设计的优势在于：开发者无需花费大量时间阅读复杂文档或拆解多层封装，即可直接修改核心逻辑（如在model.py中添加Rotary Embedding、在train.py中调整学习率调度策略），尤其适合用于LLM训练原理的学习和实验验证。

2. 多硬件适配：从GPU到CPU/MPS，无硬件门槛

nanoGPT对硬件环境的兼容性极强，无需特殊硬件即可启动训练，不同硬件场景下仅需调整少量参数：

• GPU场景：支持单GPU、多GPU（分布式训练），兼容NVIDIA GPU（如A100、V100、RTX 3090），默认启用PyTorch 2.0的torch.compile()优化，可将训练迭代时间从~250ms/次降至135ms/次（文档实测数据）；

• CPU场景：通过--device=cpu参数即可切换，同时支持关闭torch.compile()（--compile=False）以适配CPU环境，虽训练速度较慢，但可用于小规模实验（如字符级GPT训练，3分钟内完成）；

• Apple Silicon场景：针对M1/M2芯片优化，添加--device=mps参数即可调用Metal Performance Shaders（MPS）加速，训练速度比CPU快2~3倍，支持更大规模的模型（如4层Transformer、128维嵌入）。

这种适配性让不同资源条件的用户都能参与LLM开发：学生可用Macbook做入门实验，开发者用单GPU做微调，企业团队用多GPU集群复现GPT-2。

3. 全流程支持：从数据预处理到采样推理，一站式覆盖

nanoGPT提供LLM开发的全流程工具，无需依赖第三方工具即可完成“数据准备→模型训练→微调→推理”的完整链路：

• 数据预处理：通过data/目录下的prepare.py脚本，自动下载并处理主流数据集（如莎士比亚作品、OpenWebText），将原始文本转换为模型可读取的“Token ID二进制文件”（train.bin/val.bin），支持OpenAI的BPE编码（通过tiktoken库）；

• 从零训练：通过train.py支持从随机初始化权重开始训练，可自定义模型规模（层数、注意力头数、嵌入维度）、训练参数（批次大小、上下文窗口、学习率）；

• 模型微调：支持基于GPT-2预训练权重（124M~1.3B参数）微调，仅需在配置文件中设置init_from=gpt2（或gpt2-medium/gpt2-xl），并降低学习率，微调过程可在单GPU上几分钟内完成；

• 采样推理：通过sample.py快速生成文本，支持指定起始prompt（文本或文件）、生成数量（--num_samples）、最大生成长度（--max_new_tokens），可直接调用GPT-2-xl等大模型生成结果。

例如，基于莎士比亚数据集微调GPT-2后，仅需一行命令即可生成符合莎士比亚风格的戏剧文本，流程极简且结果可直接验证。

4. 性能优化：兼顾速度与资源效率

nanoGPT在“轻量”的同时，通过多种优化手段保证训练效率，尤其适合资源有限的场景：

• PyTorch 2.0编译优化：默认启用torch.compile()，对模型计算图进行优化，减少冗余操作，文档显示迭代速度提升约46%（250ms→135ms）；

• 分布式训练支持：通过PyTorch DDP（Distributed Data Parallel）实现多GPU/多节点训练，支持8卡GPU单节点、多节点集群（如2节点16卡），复现GPT-2时可通过多卡并行将训练时间从单卡数周缩短至4天；

• 内存优化：支持动态调整批次大小（--batch_size）、上下文窗口（--block_size），内存不足时可减小参数（如CPU场景下将block_size从256降至64），避免OOM（内存溢出）错误；

• 基准测试工具：提供bench.py脚本，可单独测试模型的前向/反向传播速度，帮助开发者评估硬件适配性，优化参数配置（如调整n_embd/n_layer以平衡速度与模型效果）。

5. 可复现性强：明确的基准与配置，结果可验证

nanoGPT提供详细的训练配置和基准数据，确保模型训练结果可复现：

• GPT-2复现指南：文档明确给出OpenWebText数据集预处理步骤、多GPU训练命令（如torchrun --nproc_per_node=8 train.py config/train_gpt2.py），以及预期损失（~2.85），开发者可按步骤复现GPT-2性能；

• 预训练模型基准：提供GPT-2系列模型在OpenWebText上的训练/验证损失基准（如表1所示），开发者可对比自身训练结果，判断模型训练是否正常；

• 配置文件标准化：通过config/目录提供预设配置（如train_shakespeare_char.py/finetune_shakespeare.py），参数（如模型规模、训练轮次）明确，避免因参数混乱导致结果不可复现。

表1：GPT-2系列模型在OpenWebText上的损失基准

三、nanoGPT的技术细节

nanoGPT的技术核心围绕“Transformer架构实现”“训练流程设计”“性能优化”展开，虽代码简洁，但覆盖了LLM训练的关键技术点，以下从核心模块拆解：

1. 核心模型架构（基于Transformer）

nanoGPT的模型定义在model.py中，严格遵循GPT的“Decoder-only Transformer”架构，核心由三部分组成：

（1）嵌入层（Embedding Layer）

负责将“Token”和“位置信息”转换为向量表示：

• Token Embedding：通过嵌入矩阵将输入的Token ID（如BPE编码后的整数）映射为高维向量（维度由n_embd参数指定，如128、384）；

• Position Embedding：采用“固定位置编码”（与GPT-2一致），生成每个位置的向量，与Token Embedding相加，为模型提供序列的位置信息；

• 输出处理：嵌入层输出后会经过“层归一化（LayerNorm）”和“dropout”（防止过拟合），再传入Transformer块。

（2）Transformer块（Transformer Block）

模型的核心计算单元，nanoGPT采用“预归一化”（Pre-LN）设计（与GPT-2一致），每个块包含两个子层：

• 多头自注意力（Multi-Head Self-Attention）：

• 将输入向量拆分为多个“头”（数量由n_head指定，如4、6），每个头独立计算注意力，捕捉不同维度的序列依赖；

• 支持“因果掩码（Causal Mask）”，确保模型在生成文本时仅关注当前及之前的Token，不泄露未来信息；

• 输出经过线性映射和dropout后，与输入进行“残差连接”（Residual Connection）。

• 前馈网络（Feed-Forward Network, FFN）：

• 采用“两层线性+GELU激活函数”结构（GPT-2标准设计），第一层将输入维度扩大4倍（如n_embd=384→1536），第二层缩小回原维度；

• 同样经过dropout和残差连接，最终输出经过层归一化。

（3）输出层（Output Layer）

将Transformer块的输出转换为“Token概率分布”：

• 线性映射：将Transformer块的输出（维度n_embd）映射到“词汇表大小”维度（如GPT-2的50257）；

• 无Softmax：输出层不直接计算Softmax（训练时通过F.cross_entropy自动计算，推理时采样阶段再计算概率），减少计算量。

此外，model.py还支持“加载GPT-2预训练权重”——通过Hugging Face transformers库下载官方权重，自动映射到nanoGPT的模型结构中，无需手动处理权重格式。

2. 训练流程设计（train.py核心逻辑）

train.py实现了LLM训练的完整循环，逻辑清晰，可拆解为6个步骤：

（1）参数配置与初始化

• 读取配置文件（如config/train_shakespeare_char.py）或命令行参数，确定模型规模（n_layer/n_head/n_embd）、训练参数（batch_size/max_iters/lr）、硬件配置（device/compile）；

• 初始化模型（从随机权重或GPT-2预训练权重）、优化器（采用AdamW，与GPT-2一致）、学习率调度器（线性衰减，从初始学习率降至0）；

• 初始化日志工具（如wandb，可选），用于监控训练损失、学习率等指标。

（2）数据加载

• 读取prepare.py生成的train.bin/val.bin文件（二进制格式，存储Token ID）；

• 实现“数据采样器”：每次从数据中随机截取“上下文窗口大小（block_size）”的序列，组成批次（batch_size个样本）；

• 支持“数据并行”：多GPU场景下，每个GPU负责处理批次的一部分数据，通过DDP同步梯度。

（3）训练循环（Train Loop）

核心逻辑为“迭代-计算损失-反向传播-更新参数”，每轮迭代包括：

• 数据输入：将批次数据传输到指定设备（GPU/CPU/MPS）；

• 前向传播：模型处理输入序列，输出Token概率分布；

• 损失计算：以“下一个Token”为目标，计算交叉熵损失（仅针对非padding部分）；

• 反向传播：调用loss.backward()计算梯度，通过DDP同步多GPU梯度；

• 参数更新：优化器根据梯度更新模型参数，学习率按调度器衰减；

• 梯度裁剪（Gradient Clipping）：可选启用，防止梯度爆炸（默认未启用，与GPT-2一致）。

（4）验证循环（Val Loop）

定期（如每100次迭代）评估模型在验证集上的性能：

• 关闭模型“训练模式”（model.eval()），禁用dropout；

• 无梯度计算（torch.no_grad()），减少内存占用；

• 计算验证损失（平均多个批次的损失，如eval_iters=200），监控模型是否过拟合；

• 保存“最优模型”：若当前验证损失低于历史最低，保存Checkpoint（model.pt/optimizer.pt）到--out_dir目录。

（5）Checkpoint管理

• 定期保存：每--save_interval次迭代保存一次Checkpoint，包含模型权重、优化器状态、训练参数，支持断点续训；

• 最优模型保存：单独保存验证损失最低的模型（best_model.pt），方便后续推理或微调；

• 轻量化存储：仅保存必要参数，避免冗余（如不保存训练日志、中间变量）。

（6）日志与可视化

• 控制台输出：每--log_interval次迭代打印“迭代次数、训练损失、学习率、耗时”；

• wandb集成：若启用--wandb_log，自动将损失、学习率等指标上传到wandb平台，支持实时可视化和多实验对比。

3. 分布式训练实现（DDP）

nanoGPT通过PyTorch DDP实现多GPU/多节点训练，核心步骤如下：

• 初始化DDP：通过torch.distributed.init_process_group()初始化分布式环境，指定通信后端（默认NCCL，适合NVIDIA GPU）；

• 模型包装：用torch.nn.parallel.DistributedDataParallel包装模型，自动实现梯度同步；

• 数据分片：通过DistributedSampler将训练数据分片到每个GPU，确保每个GPU处理不重复的数据；

• 多节点配置：支持跨节点训练，需指定主节点IP（--master_addr）、端口（--master_port）、节点编号（--node_rank），例如2节点16卡训练：

 # 主节点（IP：123.456.123.456）
 torchrun --nproc_per_node=8 --nnodes=2 --node_rank=0 --master_addr=123.456.123.456 --master_port=1234 train.py
 # 工作节点
 torchrun --nproc_per_node=8 --nnodes=2 --node_rank=1 --master_addr=123.456.123.456 --master_port=1234 train.py

• 性能优化：若节点间无Infiniband网络，需添加NCCL_IB_DISABLE=1禁用IB，避免通信错误（虽速度会下降，但可保证训练正常运行）。

4. 数据预处理逻辑（prepare.py）

nanoGPT的data/目录下提供针对不同数据集的prepare.py脚本，核心功能是“将原始文本转换为模型可读取的二进制文件”，以莎士比亚字符级数据集为例：

1. 下载数据：自动从指定URL下载莎士比亚作品的原始文本文件（约1MB）；

2. 字符映射：构建“字符→ID”的映射表（如'a'→0、'b'→1，包含所有出现的字符），生成meta.pkl文件保存映射关系；

3. 序列转换：将原始文本转换为“ID序列”，例如“ANGELO:”→[10, 2, 5, 7, 9, 15, 3]；

4. 划分训练/验证集：按9:1比例划分序列，分别保存为train.bin和val.bin（二进制格式，存储为uint16类型，减少存储空间）；

5. OpenWebText适配：针对OpenWebText数据集，脚本会通过Hugging Face datasets库下载数据，用tiktoken库进行BPE编码（与GPT-2一致），生成更大规模的train.bin/val.bin（约数十GB）。

这种预处理方式确保模型输入格式统一，且二进制文件加载速度远快于文本文件，提升训练效率。

四、nanoGPT的应用场景

nanoGPT的“轻量、灵活、易上手”特性，使其适用于多个场景，覆盖不同用户群体：

1. AI研究者：LLM训练原理验证与实验

对于研究LLM训练机制、优化技术的研究者，nanoGPT是理想的实验工具：

• 复现经典模型：可快速复现GPT-2，验证“规模定律（Scaling Laws）”（如参数增加对损失的影响），文档中scaling_laws.ipynb笔记本提供了相关实验代码；

• 测试新优化技术：由于代码简洁，可快速集成新的技术（如Rotary Embedding、Alibi注意力、动态批处理），验证其对训练速度、模型效果的影响；

• 数据集对比实验：支持自定义数据集（如特定领域文本、小语种数据），对比不同数据对模型性能的影响，例如测试“字符级编码”与“BPE编码”的效果差异。

例如，研究者可基于nanoGPT测试“预训练+微调”流程在小数据集上的有效性，或验证“分布式训练的通信效率”，实验结果可快速复现。

2. 开发者：定制化LLM开发与落地

对于需要开发“轻量级、特定领域LLM”的开发者，nanoGPT可降低开发成本：

• 垂直领域微调：基于GPT-2微调特定领域模型（如法律文本、医疗报告、代码生成），无需从头训练，单GPU几分钟内即可完成，适合小团队落地；

• 嵌入式场景适配：支持训练小参数模型（如10M~100M参数），适配嵌入式设备（如边缘计算节点），例如开发“本地运行的字符级文本生成模型”；

• 产品原型开发：快速生成LLM原型，验证产品需求（如“对话机器人”“文本续写工具”），例如基于莎士比亚数据集微调的模型可作为“戏剧生成工具”原型。

例如，开发者可微调一个“代码片段生成模型”，用于IDE插件，nanoGPT的轻量化特性确保插件可本地运行，无需依赖云端API。

3. 学生：学习LLM训练与Transformer原理

对于学习大语言模型的学生，nanoGPT是“看得见、改得动”的学习材料：

• 理解模型结构：通过model.py可直观理解GPT的Transformer架构，包括注意力机制、残差连接、层归一化的具体实现；

• 掌握训练流程：train.py清晰展示了“数据加载→损失计算→梯度更新”的全流程，学生可跟踪每一步的张量形状、计算逻辑，理解“为什么需要因果掩码”“学习率为什么要衰减”；

• 动手实践：无需复杂硬件，用Macbook即可完成小规模训练（如字符级GPT），观察“训练轮次增加对生成文本质量的影响”，加深对“过拟合”“dropout作用”的理解。

例如，学生可修改n_head（注意力头数），对比训练后模型的损失变化，理解“多头注意力的作用”，这种动手实践比纯理论学习更有效。

4. 小团队：资源有限下的LLM探索

对于缺乏大规模计算资源的小团队，nanoGPT可实现“低成本LLM探索”：

• 无集群也能训练：单GPU即可训练100M参数左右的模型，或微调GPT-2-medium（350M参数），无需租用昂贵的多节点集群；

• 快速验证需求：通过小规模实验验证“LLM是否适合团队产品”，例如测试“模型能否生成符合品牌风格的文案”，再决定是否投入更多资源；

• 技术积累：基于nanoGPT积累LLM开发经验，为后续更大规模模型开发打下基础，例如掌握“分布式训练配置”“Checkpoint管理”“微调参数调优”等技能。

五、nanoGPT的使用方法

nanoGPT的使用流程分为“环境准备→数据准备→模型训练/微调→采样推理”四步，以下详细说明（基于官方文档，适配不同硬件场景）：

1. 环境准备（依赖安装）

首先安装必要的依赖，支持Windows、Linux、macOS，推荐Python 3.8+：

（1）基础依赖安装

执行以下命令安装核心依赖：

pip install torch numpy transformers datasets tiktoken wandb tqdm

各依赖的作用：

• torch：PyTorch框架，模型训练与推理的核心；

• numpy：数据处理（如数组操作）；

• transformers：加载GPT-2预训练权重；

• datasets：下载OpenWebText等数据集；

• tiktoken：OpenAI的BPE编码工具，与GPT-2编码一致；

• wandb：可选，用于训练日志可视化；

• tqdm：显示训练进度条。

（2）特殊环境配置

• Apple Silicon Macbook：需安装支持MPS的PyTorch版本（推荐PyTorch nightly版），安装命令参考PyTorch官网（https://pytorch.org/get-started/locally/）；

• Windows系统：PyTorch 2.0的torch.compile()可能存在兼容性问题，建议添加--compile=False禁用；

• 无wandb账号：无需强制安装，训练时添加--wandb_log=False即可禁用日志上传。

2. 数据准备（以两个典型数据集为例）

nanoGPT需先将原始文本转换为train.bin/val.bin，以下介绍两种常用数据集的准备方法：

（1）莎士比亚字符级数据集（适合入门）

该数据集体积小（约1MB），预处理速度快，适合首次尝试：

# 进入项目根目录，执行预处理脚本
python data/shakespeare_char/prepare.py

脚本执行后，会在data/shakespeare_char/目录下生成3个文件：

• input.txt：莎士比亚作品的原始文本；

• meta.pkl：字符→ID的映射表；

• train.bin/val.bin：训练/验证集的Token ID二进制文件。

（2）OpenWebText数据集（适合复现GPT-2）

OpenWebText是GPT-2训练数据（WebText）的开源复现，体积较大（预处理后约数十GB），预处理时间较长：

# 执行预处理脚本，自动下载并处理数据
python data/openwebtext/prepare.py

脚本会通过datasets库下载OpenWebText数据，用tiktoken进行BPE编码，最终在data/openwebtext/目录生成train.bin/val.bin（存储GPT-2格式的BPE Token ID）。

（3）自定义数据集准备

若需使用自己的文本数据，可参考以下步骤：

1. 准备input.txt：将所有文本合并为一个文件，编码为UTF-8；

2. 复制data/shakespeare_char/prepare.py到自定义目录（如data/my_data/）；

3. 修改脚本中的“数据读取路径”和“编码方式”（字符级或BPE）；

4. 执行脚本生成train.bin/val.bin。

3. 模型训练（分硬件场景）

nanoGPT的训练通过train.py实现，需指定配置文件或命令行参数，以下分场景说明：

（1）GPU场景（推荐，以A100为例）

适合训练中等规模模型（如384维嵌入、6层Transformer）：

# 使用预设配置训练莎士比亚字符级GPT
python train.py config/train_shakespeare_char.py

配置文件config/train_shakespeare_char.py的核心参数：

• n_layer=6：6层Transformer；

• n_head=6：6个注意力头；

• n_embd=384：嵌入维度384；

• block_size=256：上下文窗口大小256（一次处理256个字符）；

• batch_size=64：批次大小64；

• max_iters=5000：最大训练迭代次数5000；

• out_dir=out-shakespeare-char：模型保存目录。

训练效果：单A100 GPU约3分钟完成，验证损失约1.4697，模型保存到out-shakespeare-char/目录。

（2）CPU场景（适合无GPU设备）

需调整参数以降低资源占用：

python train.py config/train_shakespeare_char.py \
 --device=cpu \
 --compile=False \
 --eval_iters=20 \
 --log_interval=1 \
 --block_size=64 \
 --batch_size=12 \
 --n_layer=4 \
 --n_head=4 \
 --n_embd=128 \
 --max_iters=2000 \
 --lr_decay_iters=2000 \
 --dropout=0.0

参数调整说明：

• --device=cpu：指定CPU训练；

• --compile=False：禁用torch.compile()（CPU不支持）；

• --block_size=64：缩小上下文窗口；

• --n_layer=4/--n_head=4：减少Transformer层数和注意力头数；

• --max_iters=2000：减少训练迭代次数。

训练效果：CPU约3分钟完成，验证损失约1.88，生成文本质量略低于GPU训练模型。

（3）Apple Silicon场景（M1/M2芯片）

需启用MPS加速，参数介于GPU和CPU之间：

python train.py config/train_shakespeare_char.py \
 --device=mps \
 --block_size=128 \
 --batch_size=32 \
 --n_layer=5 \
 --n_head=5 \
 --n_embd=256

训练效果：M1芯片约2分钟完成，验证损失约1.6，速度比CPU快2~3倍。

（4）多GPU分布式训练（复现GPT-2）

需使用torchrun启动，以8XA100 GPU单节点为例：

# 复现GPT-2（124M参数）
torchrun --standalone --nproc_per_node=8 train.py config/train_gpt2.py

训练效果：8XA100 40GB GPU约4天完成，验证损失约2.85，与GPT-2原模型微调后性能持平。

4. 模型微调（基于GPT-2预训练权重）

微调比从零训练更快，适合特定领域适配，以莎士比亚文本微调为例：

（1）执行微调命令

# 使用GPT-2预训练权重微调
python train.py config/finetune_shakespeare.py

配置文件config/finetune_shakespeare.py的核心参数：

• init_from=gpt2：从GPT-2（124M参数）预训练权重初始化；

• learning_rate=1e-4：降低学习率（预训练模型微调需小学习率）；

• max_iters=1000：减少微调迭代次数；

• out_dir=out-shakespeare：微调模型保存目录。

（2）微调效果

单GPU约5分钟完成，验证损失约1.2，生成文本更符合莎士比亚风格，例如：

THEODORE:
Thou shalt sell me to the highest bidder: if I die,
I sell thee to the first; if I go mad,
I sell thee to the second; if I
lie, I sell thee to the third; if I slay,
I sell thee to the fourth: so buy or sell,
I tell thee again, thou shalt not sell my
possession.

5. 采样推理（生成文本）

训练/微调完成后，通过sample.py生成文本，支持两种模式：

（1）从自定义训练模型采样

# 从莎士比亚字符级训练模型采样
python sample.py --out_dir=out-shakespeare-char

核心参数：

• --out_dir=out-shakespeare-char：指定模型保存目录；

• --start="KING:"：指定起始prompt（可选，默认随机）；

• --num_samples=3：生成3个样本；

• --max_new_tokens=200：每个样本最大生成200个Token。

生成示例（GPU训练模型）：

ANGELO:
And cowards it be strawn to my bed,
And thrust the gates of my threats,
Because he that ale away, and hang'd
An one with him.

DUKE VINCENTIO:
I thank your eyes against it.

（2）从GPT-2预训练模型采样

无需训练，直接调用GPT-2-xl等大模型：

python sample.py \
 --init_from=gpt2-xl \
 --start="What is the answer to life, the universe, and everything?" \
 --num_samples=5 \
 --max_new_tokens=100

生成示例：

What is the answer to life, the universe, and everything?
For decades, this question has puzzled philosophers, scientists, and curious minds alike. In Douglas Adams' "The Hitchhiker's Guide to the Galaxy," the answer is famously 42—but is there a deeper meaning? Some argue that life's purpose is to seek connection, while others focus on growth, discovery, or compassion. Ultimately, the answer may vary from person to person, shaped by experience, values, and perspective.

6. 关键参数对照表（不同硬件）

为方便用户快速选择参数，下表总结了不同硬件场景的核心配置：

表2：nanoGPT不同硬件训练参数对照表

六、常见问题解答（FAQ）

1. 问题1：启用torch.compile()后报错，提示“不支持的平台”

问题描述：在Windows系统或CPU训练时，执行train.py报错“TorchCompileNotSupportedError”。
原因：PyTorch 2.0的torch.compile()目前对Windows、CPU的支持不完善，仅在Linux GPU上稳定。
解决方案：训练时添加--compile=False参数，禁用编译优化，命令示例：

python train.py config/train_shakespeare_char.py --device=cpu --compile=False

2. 问题2：GPU训练时出现“CUDA out of memory”（内存溢出）

问题描述：单GPU训练较大模型（如GPT-2-medium）时，提示内存不足。
原因：批次大小（batch_size）、上下文窗口（block_size）或模型规模过大，超出GPU内存。
解决方案：

• 减小batch_size（如从64降至32）；

• 缩小block_size（如从256降至128）；

• 减少模型规模（如n_layer从6降至4，n_embd从384降至256）；

• 启用混合精度训练（需手动添加torch.cuda.amp代码，文档暂未默认支持）。

3. 问题3：多节点训练时，节点间无法连接，提示“Connection refused”

问题描述：执行多节点训练命令后，工作节点无法连接主节点，报错“ConnectionRefusedError”。
原因：主节点IP（--master_addr）错误、端口（--master_port）被占用，或节点间网络不通。
解决方案：

• 确认主节点IP正确（通过ifconfig/ipconfig查看）；

• 选择未被占用的端口（如1234、2345），可通过netstat -tuln查看端口占用情况；

• 检查节点间网络是否互通（如用ping测试主节点IP，确保防火墙开放指定端口）；

• 无Infiniband网络时，添加NCCL_IB_DISABLE=1，命令示例：

 NCCL_IB_DISABLE=1 torchrun --nproc_per_node=8 --nnodes=2 --node_rank=0 --master_addr=123.456.123.456 --master_port=1234 train.py

4. 问题4：训练损失不下降，甚至上升

问题描述：训练多轮后，训练损失（train loss）始终高于3.0，或验证损失（val loss）持续上升。
原因：

• 模型规模过小（如128维嵌入、4层Transformer），无法拟合数据；

• 学习率过高（如预训练微调时用1e-3，导致参数震荡）；

• 数据预处理错误（如Token ID映射表错误，或训练集/验证集划分异常）。
  解决方案：

• 增大模型规模（如n_embd增至384，n_layer增至6）；

• 调整学习率（预训练微调建议1e-4~5e-5，从零训练建议3e-4~1e-3）；

• 检查meta.pkl和train.bin是否正常（可通过脚本读取少量数据验证Token ID是否正确）。

5. 问题5：Apple Silicon训练时，未启用MPS加速

问题描述：Macbook用户添加--device=mps后，训练速度与CPU一致，未体现2~3倍加速。
原因：PyTorch版本过低（需1.12+版本支持MPS），或未正确安装MPS依赖。
解决方案：

• 升级PyTorch至最新版（推荐PyTorch 2.0+），安装命令：

 pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu

• 验证MPS是否可用：执行python -c "import torch; print(torch.backends.mps.is_available())"，输出True即正常。

6. 问题6：采样生成的文本乱码或无意义

问题描述：生成的文本包含大量无意义字符（如“GLEORKEN VINGHARD III: Whell's the couse”）。
原因：

• 训练迭代次数不足（如仅训练2000次，模型未充分拟合）；

• 数据集过小（如字符级训练仅用1MB数据，模型未学习到语言规律）；

• 采样参数不当（如temperature过高，默认1.0，可降低至0.7~0.9）。
  解决方案：

• 增加训练迭代次数（如max_iters增至5000~10000）；

• 使用更大数据集（如切换到OpenWebText的BPE编码数据）；

• 采样时添加--temperature=0.8，降低随机性，命令示例：

 python sample.py --out_dir=out-shakespeare-char --temperature=0.8

七、相关链接

• GitHub仓库：https://github.com/karpathy/nanoGPT

• Karpathy Zero To Hero系列教程：https://www.youtube.com/playlist?list=PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ

八、总结

nanoGPT是一款“以实用性为核心”的中等规模GPT训练与微调开源工具，其核心价值在于“用极简代码降低LLM开发门槛”——约300行的核心文件（model.py/train.py）覆盖了模型定义、训练循环、推理采样全流程，同时支持多硬件适配（GPU/CPU/MPS）、分布式训练、GPT-2复现，兼顾简洁性与高效性。无论是AI研究者验证实验、开发者定制化模型、学生学习LLM原理，还是小团队低成本探索，nanoGPT都能提供清晰的流程、可复现的结果和灵活的修改空间。它没有追求千亿参数的大规模模型支持，而是聚焦“中等规模LLM”的实战需求，成为连接“理论学习”与“工程落地”的优质桥梁，也是开源社区中LLM开发工具的重要补充。