https://kingye.me/study-ml/docs/book/sglang/codebase-walkthrough/Recent content in 7. 代码导读 on Machine Learning 学习笔记Hugoenhttps://kingye.me/study-ml/docs/book/sglang/codebase-walkthrough/repo-reading-order/Mon, 01 Jan 0001 00:00:00 +0000https://kingye.me/study-ml/docs/book/sglang/codebase-walkthrough/repo-reading-order/<h1 id="从仓库入口回到请求主线">从仓库入口回到请求主线<a class="anchor" href="#%e4%bb%8e%e4%bb%93%e5%ba%93%e5%85%a5%e5%8f%a3%e5%9b%9e%e5%88%b0%e8%af%b7%e6%b1%82%e4%b8%bb%e7%ba%bf">#</a></h1> <h2 id="这章解决什么问题">这章解决什么问题<a class="anchor" href="#%e8%bf%99%e7%ab%a0%e8%a7%a3%e5%86%b3%e4%bb%80%e4%b9%88%e9%97%ae%e9%a2%98">#</a></h2> <p>如果你第一次进入 SGLang 仓库，最容易犯的错误是直接钻进 <code>python/sglang/srt</code>。这样当然能看到大量核心实现，但你会很快失去“哪些入口是给用户的，哪些入口是给 runtime 的”这层方位感。更稳的读法，是先看四个文件：<code>README.md</code>、<code>python/sglang/__init__.py</code>、<code>python/sglang/lang/api.py</code> 和 <code>python/sglang/launch_server.py</code>。</p> <p><code>README.md</code> 的价值不是介绍所有内部细节，而是告诉你项目怎样向外描述自己。当前 README 直接把 “Backend Tutorial” 和 “Frontend Tutorial” 分开列出，这能帮助你先建立“双表面”认知。<code>python/sglang/__init__.py</code> 则把 public surface 展开成 import 入口：一边是 <code>function</code>、<code>gen</code>、<code>system</code>、<code>user</code>、<code>assistant</code> 等语言层 API，另一边是 <code>RuntimeEndpoint</code>、<code>ServerArgs</code> 与 <code>Engine</code> 这类运行时入口。</p> <p>接着读 <code>python/sglang/lang/api.py</code>，你会看到 <code>Runtime(...)</code> 与 <code>Engine(...)</code> 都只是懒导入包装，而 <code>gen(...)</code> 则把 <code>regex</code>、<code>json_schema</code>、sampling 参数等语言层能力显式暴露出来。最后再看 <code>python/sglang/launch_server.py</code>，你就能把“language API”“offline engine”“server entrypoint”三类入口区分开，而不是把它们混成一个抽象的“调用 SGLang”。</p> <h2 id="为什么按这条顺序读仓库">为什么按这条顺序读仓库<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e6%8c%89%e8%bf%99%e6%9d%a1%e9%a1%ba%e5%ba%8f%e8%af%bb%e4%bb%93%e5%ba%93">#</a></h2> <p>这样安排顺序，不是为了显得系统化，而是为了减少误读。仓库顶层目录天然混合了“对外表面”“核心 runtime”“示例与测试”“性能与扩展”四类材料。如果你没有先用几个稳定入口把外层地图建立起来，后面看到 <code>entrypoints</code>、<code>managers</code>、<code>mem_cache</code>、<code>benchmark</code>、<code>sgl-kernel</code> 时，就很难判断它们在整体叙事里分别扮演什么角色。</p> <p>因此，这一章的真正设计理由，是先建立阅读顺序，再建立目录认识。你不是在背一个文件系统，而是在学习一套“从公开入口走回主链路，再从主链路走向扩展材料”的路径。只有这样，代码导读章节才和前面的 request lifecycle、runtime architecture、scheduling/memory 构成同一本书，而不是一组平行笔记。</p> <h2 id="回到-pythonsglangsrt-时先找五个目录">回到 <code>python/sglang/srt</code> 时，先找五个目录<a class="anchor" href="#%e5%9b%9e%e5%88%b0-pythonsglangsrt-%e6%97%b6%e5%85%88%e6%89%be%e4%ba%94%e4%b8%aa%e7%9b%ae%e5%bd%95">#</a></h2> <p>带着入口感再回到 <code>python/sglang/srt</code>，阅读顺序会清楚很多。第一站看 <code>entrypoints/</code>，因为这里定义了 HTTP、gRPC、engine 等真正进入 runtime 的门。第二站看 <code>managers/</code>，因为请求状态、队列、批次、流式输出和大量运行时编排都在这里。第三站看 <code>model_executor/</code>，这里更接近模型前向与设备执行。第四站看 <code>mem_cache/</code>，这里解释请求状态如何映射到可复用的 KV 存储。第五站看 <code>observability/</code>，这里提供 metrics、trace 与 request stage 观测能力。</p>