作者：Lei阅读 --

LLM 与 Agent 源码品读地图：11 层、50+ 个值得逐行读的开源项目

把大模型与 Agent 开源栈拆成 11 层，每层回答"被什么稀缺资源塑形"，再给出代表项目与具体的"读什么"。从 micrograd 到 vLLM，从 LangGraph 到 OpenHands，一张可以按图索骥的源码阅读地图。

LLMAgentAI Infra源码阅读

读 huggingface/transformers 几十万行代码，不如先读 karpathy 8000 行的 nanochat——不是因为大仓库不好，而是因为读源码的正确单位不是”仓库”，是”层”。每一层被一个稀缺资源塑形：训练层缺显存、推理层缺带宽、Agent 层缺上下文。看懂了那个稀缺资源，这一层所有项目的设计都会突然变得”理所当然”。

这篇文章是一张地图：把 LLM/Agent 开源世界切成 11 层，每层先回答一个第一性问题（这层到底在跟什么资源搏斗），然后给出值得精读的代表项目——每个项目都注明”读什么”，而不是”它有多少 star”。

全部项目均为 2026 年 7 月仍活跃（或具有明确历史标本价值）的开源仓库，关键动态（改名、合并、捐赠）已逐一核实，文末附来源。

这张地图怎么用

三条使用原则：

  1. 每层精读一个，对照略读两个。 同层项目解决同一约束，读第二个时你只需要找”它跟第一个的分歧点在哪”。
  2. 读机制，不读 API。 框架层两年一换血（AutoGen 已并入 Microsoft Agent Framework），但”单控制器 vs 多控制器”、“图 vs 循环”这类权衡十年不变。API 会过时，约束不会。
  3. 从你的稀缺资源入层。 你被显存卡住就去读推理层，被 prompt 脆弱性折磨就去读结构化输出层——带着真问题读，效率翻倍。

整个栈长这样：

flowchart TB
    subgraph 应用与生态
        L11["11 协议 · 网关 · 评测 · 可观测"]
        L8["8 Agent 应用（coding/browser agent）"]
        L9["9 RAG 与记忆"]
    end
    subgraph 编排与接口
        L7["7 Agent 框架（编排）"]
        L10["10 提示编程 · 结构化输出"]
    end
    subgraph 模型系统
        L4["4 后训练（SFT / RLHF / RL）"]
        L5["5 推理与服务"]
        L3["3 预训练与分布式训练"]
    end
    subgraph 地基
        L2["2 工业级模型实现"]
        L1["1 教学级实现（从零读懂）"]
        L6["6 算子与底层性能"]
    end
    L1 --> L2 --> L3 --> L4
    L6 --> L3
    L6 --> L5
    L4 --> L5 --> L7
    L10 --> L7 --> L8
    L9 --> L8
    L11 -.横切.- L7

第 1 层：教学级实现——从零读懂 LLM 本体

这层的稀缺资源是你的认知带宽。 所以这层项目的共同取舍是：可读性 > 性能，删依赖、删抽象、删配置项，让”模型到底是什么”暴露在几百行代码里。

项目它是什么值得品读的点
karpathy/micrograd百余行的标量自动微分引擎 + 微型神经网络库engine.py 里 Value 类怎么一边做运算一边搭计算图、再拓扑排序反向传播——反向传播的最小可运行答案
karpathy/nanoGPT复现 GPT-2 的最小训练代码model.py 三百行左右装下完整 GPT：因果自注意力、残差流、权重初始化，没有一层多余抽象
karpathy/nanochat2025 年 10 月发布，约 8000 行的全栈 ChatGPT 克隆：“$100 能买到的最好的 ChatGPT”从 Rust tokenizer → 预训练 → 中期训练 → SFT → RL → 推理 → Web UI 一条龙压进单仓库；只留一个复杂度旋钮 --depth，其余超参全部自动推导
rasbt/LLMs-from-scratch《Build a Large Language Model (From Scratch)》官方代码一章一个可运行 notebook，从注意力机制一路写到指令微调，适合配书精读
jingyaogong/minimind中文社区”从零训练超小 LLM”项目tokenizer、预训练、SFT、LoRA、DPO、蒸馏全流程手写，对中文语料和消费级显卡友好
tinygrad/tinygradGeorge Hotz 的极简深度学习框架一个”框架”的本质复杂度到底有多少：懒计算、算子融合、多后端，全部塞进刻意压缩的代码量里

第 2 层：工业级模型实现——参考答案长什么样

这层的约束是兼容性与正确性：同一份代码要伺候几百种模型、无数下游。读法与第 1 层相反——别通读，挑单点。

项目它是什么值得品读的点
huggingface/transformers模型实现的事实标准库它著名的”单模型单文件”哲学：挑一个 modeling_llama.py 风格的文件对照论文逐行读，而不是研究库本身的抽象
meta-llama/llamaLlama 2 时代的官方实现历史意义：2023 年无数二创（含 llama.cpp）的起点，模型代码干净得像教学项目
deepseek-ai/DeepSeek-V3DeepSeek-V3 官方推理参考实现 + 技术报告MLA（多头潜在注意力）与 DeepSeekMoE 的第一手代码——前沿架构创新很少有这么完整的官方参考

第 3 层：预训练与分布式训练——跟显存和带宽搏斗

这层的稀缺资源是单卡显存与卡间带宽。 所有设计都是同一道题：怎么把一个装不进任何单卡的模型和它的优化器状态，切开、摆好、再高效地通信。

项目它是什么值得品读的点
NVIDIA/Megatron-LM张量并行/流水线并行的源头级实现ColumnParallelLinear / RowParallelLinear：一次矩阵乘法怎么切到多卡上且只多一次 all-reduce——TP 的全部秘密就在这两个类里
deepspeedai/DeepSpeedZeRO 系列的家ZeRO stage 1/2/3 逐级把优化器状态、梯度、参数分片出去；对照论文读 runtime 里的 zero 实现
pytorch/torchtitanPyTorch 官方原生预训练参考实现用 FSDP2/TP/PP/CP 的原生组合复现大模型训练，代码量远小于 Megatron——建议先读它再读 Megatron

第 4 层：后训练——SFT、RLHF 与 RL Scaling

这层的约束是”训练”和”生成”两种负载的撕扯：RL 后训练一半时间在训练（吃 Megatron/FSDP），一半时间在 rollout 采样（吃 vLLM/SGLang），怎么让两边共享权重、共享集群、互不拖累，是所有框架的核心分歧点。

项目它是什么值得品读的点
huggingface/trlSFT/DPO/GRPO 等 Trainer 的事实标准入口各种对齐算法损失函数的最短路径实现，适合当”算法字典”查
hiyouga/LLaMA-Factory一站式微调平台（WebUI + 海量模型适配）配置驱动的工程组织：怎么用一套 YAML 抽象吞下几百种模型 × 十几种训练法的组合爆炸
unslothai/unsloth微调加速与省显存方案它怎么用手写 Triton kernel 替换训练关键路径——kernel 层优化反哺训练框架的样本
verl-project/verl字节 HybridFlow 论文的开源实现，当前最主流的 RL 后训练框架之一单控制器 + 多控制器混合编程模型；训练侧接 FSDP/Megatron、rollout 侧接 vLLM/SGLang 的解耦方式
OpenRLHF/OpenRLHF基于 Ray + vLLM + ZeRO-3 的易用 RLHF 框架Actor/Critic/Reward/Reference 四个模型怎么用 Ray 摆到不同 GPU 组上——分布式 RLHF 拓扑的清晰示范
THUDM/slimeGLM 系列模型背后的 RL Scaling 框架Megatron 训练 + SGLang rollout + 共享 data buffer 的三段式显式数据流；被完整前沿模型训练闭环验证过的开源 RL 栈
vllm-project/vime2026 年 6 月 vLLM 社区发布的后训练框架直接承认继承 slime 的三段式解耦设计、把 rollout 换成 vLLM——读它和 slime 的 diff 就是在读两大推理引擎的接口差异
huggingface/open-r1DeepSeek-R1 的开放复现GRPO 训练、蒸馏、评测三件套怎么组装成一次”复现前沿推理模型”的完整工程

第 5 层：推理与服务——KV cache 就是一切

这层的稀缺资源是显存容量与访存带宽，具体化身叫 KV cache。 过去三年推理引擎的所有大创新，几乎都是”怎么管好 KV cache”的不同答案。

项目它是什么值得品读的点
vllm-project/vllm吞吐量标杆推理引擎PagedAttention（arXiv:2309.06180）：把操作系统的分页虚拟内存搬进 KV cache，碎片浪费近零，吞吐提升 2–4 倍——“表示决定成败”的教科书案例
sgl-project/sglang与 vLLM 双雄并立的推理引擎RadixAttention（arXiv:2312.07104）：radix tree 自动复用跨请求的 KV 前缀；外加压缩有限状态机加速约束解码
ggml-org/llama.cpp纯 C/C++ 的本地推理栈与 GGUF 量化格式不依赖 Python 生态从零实现推理意味着什么：手写算子、量化格式设计、跨平台后端抽象
NVIDIA/TensorRT-LLM编译期优化路线的代表与 vLLM 的运行时调度路线对照读：kernel 融合、in-flight batching，性能从”编译”里抠出来
ollama/ollamaGo 语言写的本地模型运行器读的不是推理（底层是 llama.cpp），而是产品化：Modelfile 模型分发、一条命令起服务的体验是怎么包出来的

第 6 层：算子与底层性能——SRAM 里的战争

这层的稀缺资源是 GPU 片上 SRAM 和 HBM 带宽。 再往下没有别的层了，这里是性能的最终来源。

项目它是什么值得品读的点
Dao-AILab/flash-attentionIO-aware 的精确注意力实现tiling + 重计算怎么把注意力的 O(N²) 显存消掉——先读论文再读 kernel，理解”算得多但搬得少反而更快”
triton-lang/tritonOpenAI 的 GPU kernel DSLpython/tutorials 目录从 vector-add 一路写到 matmul 和 flash attention，是普通工程师进入 kernel 世界的最平缓坡道
deepseek-ai/FlashMLA · DeepEP · DeepGEMM · 3FSDeepSeek 2025 年 2 月”开源周”放出的生产级基础设施：MLA 解码 kernel、MoE 专家并行通信库、FP8 GEMM、分布式文件系统前沿实验室把训练生产线上的真实代码直接开源极其罕见——读它们是在读”真跑过万卡的代码长什么样”

第 7 层：Agent 框架——控制流放在哪

这层的根本问题：控制流放在模型里还是代码里。 放模型里（自主循环）灵活但不可预测，放代码里（显式图）可控但僵硬。每个框架都是这条光谱上的一个点。

项目它是什么值得品读的点
langchain-ai/langgraph显式图 + 状态机的编排层，企业侧采用最广的选择之一checkpoint 持久化、人工介入、时间旅行调试——“把 agent 当分布式系统对待”的完整答案
openai/openai-agents-pythonOpenAI Agents SDKhandoff（agent 间移交）+ guardrail 两个极简抽象撑起多 agent 协作，代码量小，适合整仓精读
google/adk-pythonGoogle 的 Agent Development Kit工作流 agent（顺序/并行/循环）与 LLM agent 的显式分离；与 A2A 协议的原生集成
microsoft/agent-frameworkAutoGen + Semantic Kernel 的官方继任者（2025-10 公开预览，2026-04 发 1.0）两个大框架怎么合并成一个：AutoGen 的多 agent 编排抽象 × Semantic Kernel 的企业级线程/遥测/类型安全
huggingface/smolagents极简 agent 库，核心逻辑千行级code-as-action：让模型直接写 Python 代码当动作而非填 JSON 工具参数——一个反主流但论据扎实的设计决策
pydantic/pydantic-ai类型安全的 agent 层（V2 于 2026-06 稳定）FastAPI 风格的开发体验怎么搬到 agent 上：依赖注入、结构化输出、静态类型检查贯穿始终
crewAIInc/crewAIrole-based 多智能体协作框架”角色 + 任务 + 流程”的组织隐喻怎么落成代码；与 LangGraph 的图隐喻对照读
geekan/MetaGPT”SOP 即代码”的多智能体软件公司把人类工作流程（产品经理→架构师→工程师）编码成 agent 流水线的早期完整尝试
Significant-Gravitas/AutoGPT2023 年点燃自主 agent 热潮的历史标本读它是为了理解”为什么裸循环不够”：无结构的自主性会在哪些地方失控，后来的框架各自怎么补

第 8 层：Agent 应用——反馈闭环的工程学

这层的稀缺资源是反馈闭环的质量：agent 要行动就要有环境（沙箱、终端、浏览器），要纠错就要有可靠的观察。产品级 agent 的护城河全在这些”模型之外”的工程里。

项目它是什么值得品读的点
All-Hands-AI/OpenHands开源 coding agent 旗舰（前身 OpenDevin）事件流架构：agent 的每一步动作/观察都是事件，回放、恢复、审计全部免费获得
OpenHands/software-agent-sdkOpenHands 2025 年重设计的 Agent SDK（arXiv:2511.03690）与 OpenAI/Claude/Google 各家 SDK 的对比设计：原生沙箱执行、多 LLM 路由、内建安全分析
princeton-nlp/SWE-agent把 LLM 变成软件工程 agent 的学术代表作Agent-Computer Interface 概念的出处：给 agent 设计一个好用的”电脑界面”，收益不亚于换更强的模型
Aider-AI/aider终端里的 AI 结对编程repo map 机制：tree-sitter 抽符号 + 图排序，在有限上下文里塞进”仓库的骨架”——上下文预算管理的经典方案
cline/clineVS Code 里的 coding agentPlan/Act 双模式的状态管理，以及 MCP 工具生态怎么接进编辑器
openai/codexOpenAI 的终端 coding agent，Rust 实现，Apache-2.0一线大厂产品级 CLI agent 的完整开源样本：沙箱策略、headless 模式、MCP server 化
block/gooseBlock 开源的本地 agent 框架，Agentic AI Foundation 创始项目之一Rust 实现的可扩展本地 agent：扩展机制（extensions）怎么把”接工具”标准化
browser-use/browser-use浏览器操作 agent 的事实标准库DOM 怎么序列化成 LLM 可读、可点击的结构——“给模型看什么”决定了浏览器 agent 的上限

第 9 层：RAG 与记忆——上下文窗口之外的知识

这层的约束：上下文窗口有限且昂贵，而知识近乎无限。 检索（RAG）解决”知识放不下”，记忆解决”经历留不住”，本质都是给 LLM 外挂分层存储。

项目它是什么值得品读的点
run-llama/llama_index数据接入/索引/查询的 RAG 框架代表各种索引结构（向量、树、关键词表、知识图谱）的统一抽象是怎么设计的
infiniflow/ragflow深度文档理解路线的 RAG 引擎它赌的是”RAG 质量卡在文档解析而非检索”：版面分析、表格还原、分块可视化的完整实现
microsoft/graphrag基于知识图谱的 RAG用 LLM 抽实体关系建图 + 社区检测 + 分层摘要，回答”这批文档的主题是什么”这类全局问题——向量检索的盲区
mem0ai/mem0agent 记忆层记忆的抽取、更新、冲突消解流水线：什么值得记、旧记忆怎么改写
letta-ai/lettaMemGPT 论文（arXiv:2310.08560）的产品化延续”LLM 即操作系统”的内存分层：主上下文当 RAM、外部存储当磁盘，模型自己调函数换页

第 10 层：提示编程与结构化输出——驯服自然语言接口

这层的约束：LLM 的输入输出都是自由文本，而软件需要契约。 三个项目代表三种驯服路线：编译期优化、解码期约束、校验期重试。

项目它是什么值得品读的点
stanfordnlp/dspy声明式 LM 编程框架（arXiv:2310.03714）把 prompt 当可学习参数：签名（signature）声明意图，优化器自动搜索少样本示例与指令——“手调 prompt ≈ 手调权重”这个类比的完整落地
dottxt-ai/outlines约束解码库把 JSON Schema/正则/CFG 编译成状态机，在采样时直接把非法 token 的概率清零——从根上保证格式合法，而不是事后修
jxnl/instructor用 Pydantic 定义 LLM 输出结构最小可读的结构化输出方案：模式声明 + 校验失败自动重试，几百行核心值得整仓读完

第 11 层：协议、网关、评测与可观测——生态的横切面

这层的约束是互操作与度量：N 个模型 × M 个工具 × K 个 agent 的组合爆炸，要靠协议收敛；“agent 到底行不行”要靠基准和追踪回答。

项目它是什么值得品读的点
modelcontextprotocol/modelcontextprotocolMCP 协议规范（2024-11 由 Anthropic 开源，2025-12 捐入 Linux Foundation 旗下 Agentic AI Foundation）一份好的协议规范怎么写：能力协商、resources/tools/prompts 三原语的边界划分；配合 servers 仓库看参考实现
a2aproject/A2Aagent 间互操作协议（Google 发起后捐入 Linux Foundation）与 MCP 对照读：MCP 连”agent 和工具”，A2A 连”agent 和 agent”，Agent Card 的能力发现机制
BerriAI/litellm百余家模型 API 统一成 OpenAI 格式的网关适配层工程的极致样本:重试、降级、路由、计费怎么在代理层统一解决
EleutherAI/lm-evaluation-harness学术评测事实标准任务定义的抽象:几百个 benchmark 怎么收敛到一套 YAML + 模板体系
open-compass/opencompass中文社区评测体系代表与 lm-evaluation-harness 对照:评测集组织、主客观混合评测的另一套答案
princeton-nlp/SWE-bench用真实 GitHub issue + PR 评测 coding agent 的基准数据构建管线:怎么从真实仓库历史里自动挖出”可验证的任务”——评测集本身也是工程
langfuse/langfuse开源 LLM 可观测平台trace/span 模型怎么适配 LLM 应用:token 成本、多轮会话、评分回流的数据模型设计

三条精读路线

地图不等于路线。按你的目标挑一条，每条 4–6 个仓库，从小到大：

模型线（目标：彻底弄懂模型本体） micrograd → nanoGPT → LLMs-from-scratch（查漏）→ nanochat → transformers 里挑一个 modeling 单文件 → DeepSeek-V3 参考实现

系统线（目标：弄懂训练/推理基础设施） llama.cpp 或 vLLM（挑一个精读）→ flash-attention + Triton tutorials → torchtitan → Megatron-LM（只读并行原语）→ verl 或 slime

Agent 线（目标：会造也会评 agent） smolagents → openai-agents-python → LangGraph → OpenHands software-agent-sdk → SWE-agent + Aider（读 ACI 和 repo map 两个机制）→ MCP 规范

三个预期中的反驳

“框架迭代这么快，读了不就过时了？” 会过时的是 API，不会过时的是约束。AutoGen 两年内变成了 Microsoft Agent Framework，但它探索的”多 agent 会话该不该有中央调度”这个问题，被新框架原样继承。读源码读的是”约束下的设计决策”，这部分是复利资产。

“为什么不直接读最大最全的仓库？” 因为大仓库是地图，不是入口。transformers 的价值在覆盖面，nanochat 的价值在密度——先用高密度小仓库建立心智模型，再把大仓库当字典查，顺序反了会淹死。

“star 数不能代表可读性吗？” 不能。ollama star 极高，但它的品读价值在产品化而非推理内核；tinygrad 的 star 远少于 transformers，但每行代码的信息密度可能是后者十倍。这也是本文按”层 + 读什么”而非 star 排行组织的原因。

清单必有遗漏——同层的优秀项目远多于表格容量，我选的是”分歧点最清晰”的代表而非全集。如果你心里有某层更好的代表，欢迎告诉我。

参考来源

项目动态与工程实践

arXiv 论文