https://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/Recent content in 第二章 阅读准备 on Machine Learning 学习笔记Hugoenhttps://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/version-and-source-anchors/Mon, 01 Jan 0001 00:00:00 +0000https://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/version-and-source-anchors/<h1 id="上游版本提交与源码锚点约定">上游版本、提交与源码锚点约定<a class="anchor" href="#%e4%b8%8a%e6%b8%b8%e7%89%88%e6%9c%ac%e6%8f%90%e4%ba%a4%e4%b8%8e%e6%ba%90%e7%a0%81%e9%94%9a%e7%82%b9%e7%ba%a6%e5%ae%9a">#</a></h1> <p>这一节负责把“引用哪份源码、怎样稳定落到具体位置”说明清楚。没有这层约定，后面的章节就很容易在不同版本之间漂移，读者也很难判断哪些结论是事实，哪些只是工作性推断。</p> <h2 id="为什么这层必须先说清楚">为什么这层必须先说清楚<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e8%bf%99%e5%b1%82%e5%bf%85%e9%a1%bb%e5%85%88%e8%af%b4%e6%b8%85%e6%a5%9a">#</a></h2> <p>这本书不是只讲观念，也不是只讲接口。它会反复回到真实代码路径，所以一开始就必须先回答两个问题：</p> <ol> <li>整本书默认以哪一版上游仓库为准；</li> <li>正文里的源码引用怎样稳定落到具体位置。</li> </ol> <p>如果这两个问题不先收口，后面的章节就很容易出现这种情况：</p> <ul> <li>某一页讲的是 <code>main</code> 的行为</li> <li>另一页讲的是旧 tag 的行为</li> <li>读者却以为整本书都在讲同一份代码</li> </ul> <p>这会直接破坏一本系统书最基本的可信度。</p> <h2 id="当前的上游基线是什么">当前的上游基线是什么<a class="anchor" href="#%e5%bd%93%e5%89%8d%e7%9a%84%e4%b8%8a%e6%b8%b8%e5%9f%ba%e7%ba%bf%e6%98%af%e4%bb%80%e4%b9%88">#</a></h2> <p>本书当前默认以：</p> <ul> <li><code>sgl-project/sglang</code></li> <li><code>v0.5.10</code></li> <li>commit <code>1519acf37c23f2189adb93f57ca9cd2db1bebf18</code></li> </ul> <p>为基线。</p> <p>这个约定的价值，不只是“以后方便核对”，而是让后面的每个结论都能回到同一份源码时间点上。这样读者在不同章节之间切换时，不需要一直怀疑“是不是版本又变了”。</p> <h2 id="为什么源码链接不能靠手写">为什么源码链接不能靠手写<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e6%ba%90%e7%a0%81%e9%93%be%e6%8e%a5%e4%b8%8d%e8%83%bd%e9%9d%a0%e6%89%8b%e5%86%99">#</a></h2> <p>如果所有链接都手写成 GitHub 长链接，短期看起来当然能用，但后面会很快出现三个问题：</p> <ol> <li>版本一旦更新，整本书要到处找链接替换；</li> <li>同一段代码在多章被引用时，容易出现路径或行号不一致；</li> <li>正文会混入很多又长又难维护的 URL。</li> </ol> <p>所以这本书现在统一用 <code>sglref</code> 这套约定：正文只写稳定的引用 id，实际渲染时再落到固定 commit 的 GitHub 行号。</p> <h2 id="sglref-解决的是什么问题"><code>sglref</code> 解决的是什么问题<a class="anchor" href="#sglref-%e8%a7%a3%e5%86%b3%e7%9a%84%e6%98%af%e4%bb%80%e4%b9%88%e9%97%ae%e9%a2%98">#</a></h2> <p><code>sglref</code> 不是为了花哨，而是为了把两件事拆开：</p> <ul> <li>正文里引用“什么概念 / 什么符号”</li> <li>渲染时跳到“哪一份代码 / 哪一行”</li> </ul> <p>这样做的收益很直接：</p> <ul> <li>作者写正文时不必反复手拼 GitHub URL；</li> <li>同一锚点在多章复用时，只需要维护一份映射；</li> <li>以后如果锚点更新，可以集中改，不必改散落在正文里的每个链接。</li> </ul> <p>这本书后面的所有代码书写和 review，都会默认站在这个约定之上。</p> <h2 id="反复回扣的主锚点有哪些">反复回扣的主锚点有哪些<a class="anchor" href="#%e5%8f%8d%e5%a4%8d%e5%9b%9e%e6%89%a3%e7%9a%84%e4%b8%bb%e9%94%9a%e7%82%b9%e6%9c%89%e5%93%aa%e4%ba%9b">#</a></h2> <p>从整本书后面的结构看，最值得反复回扣的几组锚点大概是：</p> <ul> <li>入口锚点： <ul> <li><code>python/sglang/launch_server.py</code></li> <li><code>python/sglang/srt/entrypoints/http_server.py</code></li> </ul> </li> <li>请求主线锚点： <ul> <li><code>python/sglang/srt/managers/tokenizer_manager.py</code></li> <li><code>python/sglang/srt/managers/scheduler.py</code></li> <li><code>python/sglang/srt/managers/detokenizer_manager.py</code></li> </ul> </li> <li>执行核心锚点： <ul> <li><code>python/sglang/srt/managers/schedule_batch.py</code></li> <li><code>python/sglang/srt/model_executor/forward_batch_info.py</code></li> <li><code>python/sglang/srt/model_executor/model_runner.py</code></li> <li><code>python/sglang/srt/sampling/sampling_params.py</code></li> </ul> </li> <li>结构化语义锚点： <ul> <li><code>python/sglang/srt/entrypoints/openai/protocol.py</code></li> <li><code>python/sglang/srt/function_call/function_call_parser.py</code></li> </ul> </li> <li>维护与证据锚点： <ul> <li><code>python/sglang/srt/observability/req_time_stats.py</code></li> <li><code>python/sglang/srt/utils/request_logger.py</code></li> </ul> </li> </ul> <p>这份列表不是为了让读者现在就背下来，而是为了让后面的章节在反复回扣时看起来像回到同一组主脊梁，而不是不断引入新的零散文件。</p>https://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/terminology-and-object-map/Mon, 01 Jan 0001 00:00:00 +0000https://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/terminology-and-object-map/<h1 id="术语表与对象对照">术语表与对象对照<a class="anchor" href="#%e6%9c%af%e8%af%ad%e8%a1%a8%e4%b8%8e%e5%af%b9%e8%b1%a1%e5%af%b9%e7%85%a7">#</a></h1> <p>这一节解决“同一个词在不同层里是什么意思”这个问题。SGLang 的很多对象会在协议层、manager 层、scheduler 层和执行层反复出现，如果术语不先对齐，后面越深入越容易混淆。</p> <h2 id="为什么术语要先收口">为什么术语要先收口<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e6%9c%af%e8%af%ad%e8%a6%81%e5%85%88%e6%94%b6%e5%8f%a3">#</a></h2> <p>系统书一旦变厚，最先失稳的往往不是局部事实，而是对象边界。尤其对 SGLang 这种系统来说，很多词会在不同章节反复出现，但并不站在同一抽象层。只要口径稍微漂移，读者就会在章节之间反复重建对象模型，最后把“回扣”读成“混乱”。</p> <p>所以这一节不是附录词典，而是整本书后面反复要回来的总坐标。</p> <h2 id="第一组请求对象">第一组：请求对象<a class="anchor" href="#%e7%ac%ac%e4%b8%80%e7%bb%84%e8%af%b7%e6%b1%82%e5%af%b9%e8%b1%a1">#</a></h2> <p>最先需要对齐的是请求对象这组词：</p> <table> <thead> <tr> <th>术语</th> <th>主层次</th> <th>更像什么</th> <th>不要和什么混读</th> </tr> </thead> <tbody> <tr> <td><code>GenerateReqInput</code></td> <td>协议 / 运行时交界</td> <td>统一的 runtime 请求输入</td> <td>不要把它看成 HTTP request body</td> </tr> <tr> <td><code>ReqState</code></td> <td>API server 侧</td> <td>请求状态与返回收口容器</td> <td>不要把它看成 scheduler 的主语</td> </tr> <tr> <td><code>Req</code></td> <td>调度 / 执行交界</td> <td>单请求运行时本体</td> <td>不要把它当成回包对象</td> </tr> </tbody> </table> <p>更稳的记法是：</p> <ul> <li><code>GenerateReqInput</code> 负责统一输入形态</li> <li><code>ReqState</code> 负责 API server 侧状态</li> <li><code>Req</code> 负责 runtime 侧工作单元</li> </ul> <h2 id="第二组batch-与执行对象">第二组：batch 与执行对象<a class="anchor" href="#%e7%ac%ac%e4%ba%8c%e7%bb%84batch-%e4%b8%8e%e6%89%a7%e8%a1%8c%e5%af%b9%e8%b1%a1">#</a></h2> <p>第二组最容易混的是 batch 和执行对象：</p> <table> <thead> <tr> <th>术语</th> <th>主层次</th> <th>更像什么</th> <th>不要和什么混读</th> </tr> </thead> <tbody> <tr> <td><code>ScheduleBatch</code></td> <td>调度层</td> <td>这一轮被组织出来的运行批次</td> <td>不等于执行层输入</td> </tr> <tr> <td><code>ForwardBatch</code></td> <td>执行前边界</td> <td>前向真正消费的对象</td> <td>不等于 waiting queue 的延续</td> </tr> <tr> <td><code>ModelRunner</code></td> <td>执行壳</td> <td>在当前并行拓扑下运行模型前向</td> <td>不等于调度器的附属函数</td> </tr> </tbody> </table> <p>这组对象是第三部分反复回扣的主轴。只要这组边界先稳住，后面读第五章和第六章就不会把调度与执行混成一层。</p>https://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/reading-paths-by-role/Mon, 01 Jan 0001 00:00:00 +0000https://kingye.me/study-ml/docs/book/sglang-internals/part1-prerequisite/source-reading-prep/reading-paths-by-role/<h1 id="不同角色的建议阅读路径">不同角色的建议阅读路径<a class="anchor" href="#%e4%b8%8d%e5%90%8c%e8%a7%92%e8%89%b2%e7%9a%84%e5%bb%ba%e8%ae%ae%e9%98%85%e8%af%bb%e8%b7%af%e5%be%84">#</a></h1> <p>这一节不是在重新列目录，而是在回答“不同背景的工程师应该怎样进入这本书”。平台工程、推理 runtime 和框架工程读同一套材料时，最关心的切口并不一样。</p> <h2 id="为什么这层值得单独成节">为什么这层值得单独成节<a class="anchor" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e8%bf%99%e5%b1%82%e5%80%bc%e5%be%97%e5%8d%95%e7%8b%ac%e6%88%90%e8%8a%82">#</a></h2> <p>一本系统书一旦变厚，单纯给出目录顺序就不够了。读者还会自然问：</p> <ul> <li>如果我是平台工程师，我最该先抓哪几章？</li> <li>如果我最关心吞吐、batch 和 cache，该避开哪些前期噪声？</li> <li>如果我更偏接口和结构化语义，应该先看哪里？</li> </ul> <p>这一节的作用，就是把整本书按角色重新剪成几条更具体的阅读线。</p> <h2 id="路线一平台工程--serving-工程">路线一：平台工程 / serving 工程<a class="anchor" href="#%e8%b7%af%e7%ba%bf%e4%b8%80%e5%b9%b3%e5%8f%b0%e5%b7%a5%e7%a8%8b--serving-%e5%b7%a5%e7%a8%8b">#</a></h2> <p>如果你的核心问题是：</p> <ul> <li>服务怎样启动与装配</li> <li>请求怎样穿过 managers</li> <li>多 worker / rank / mode 怎样改变系统行为</li> <li>线上故障怎样先回到正确的证据链</li> </ul> <p>那么更稳的顺序通常是：</p> <ol> <li>第一章 系统概览</li> <li>第三章 请求路径</li> <li>第四章 运行时架构</li> <li>第五章 调度、批处理与 KV Cache</li> <li>第九章 可观测性与调试</li> </ol> <p>这条路线的重点不是尽快钻执行细节，而是先把系统边界和控制面立住。</p> <h2 id="路线二推理-runtime--性能工程">路线二：推理 runtime / 性能工程<a class="anchor" href="#%e8%b7%af%e7%ba%bf%e4%ba%8c%e6%8e%a8%e7%90%86-runtime--%e6%80%a7%e8%83%bd%e5%b7%a5%e7%a8%8b">#</a></h2> <p>如果你的核心问题是：</p> <ul> <li>batch 为什么会长成这样</li> <li>prefix reuse、KV cache 和吞吐为什么会互相影响</li> <li>token selection、finish reason 和 output tail 为什么会这样工作</li> <li>优化后应该拿什么证明它真的更快了</li> </ul> <p>那么更稳的顺序通常是：</p> <ol> <li>第一章 系统概览</li> <li>第三章 请求路径</li> <li>第五章 调度、批处理与 KV Cache</li> <li>第六章 执行模型与采样</li> <li>第九章 可观测性与调试</li> </ol> <p>这条路线会更快进入系统内部的“硬”部分，但仍然保留足够的入口和路径背景，避免一开始就把 <code>scheduler.py</code> 读散。</p>