执行摘要

• 一句话：源码检出按需构建 Rust 扩展，统一三 crate 模块命名
• 推荐动作：值得精读，尤其 loader.py 的指纹缓存、文件锁与原子暂存设计，对构建系统开发者有直接借鉴价值。建议关注两个后续优化点：一是缓存失效以整个 rust 工作区为粒度，可优化为按 crate 依赖子图计算 digest；二是 auto 模式下无 Rust 工具链时直接抛错，可考虑先探测 cargo 可用性并给出更友好的降级提示。

功能与动机

PR body 明确指出：Source checkouts (editable installs) currently require the PyO3 extensions (sglang.srt.grpc._core, sglang.srt.server._core, sglang.srt.multimodal._core) to be prebuilt into the wheel: importing them from a plain checkout fails with ModuleNotFoundError (or, for --grpc-port, a hard RuntimeError)。目标是让带有 Rust 工具链的源码检出开箱即用，消除纯 checkout 开发时必须先构建 wheel 的额外步骤，降低 SGLang 开发者调试 gRPC、RustServer 与 inkling 多模态路径的门槛。

实现拆解

按以下 5 步推进实现：

1. 新增按需加载器：新建 python/sglang/srt/rust_extensions/loader.py（412 行），核心函数 load_rust_extension 实现三级加载；crate 通过扫描 rust/ 工作区所有 Cargo.toml 的 [package.metadata.sglang] python-module 元数据定位（与 setup.py 同源），新增 crate 无需任何注册代码；Python 3.10 兼容通过 tomllib/tomli 回退实现。

2. 统一扩展模块命名与 wheel 布局：三个 Rust crate 的 #[pymodule] 入口从 _core 分别改为 _multimodal（sglang-mm）、_grpc（sglang-grpc）、_server（sglang-server），Python 侧模块路径统一收敛到 sglang.srt.rust_extensions.*；新建 rust_extensions/init.py 导出入口；python/setup.py 同步 wheel 内模块名；python/sglang/srt/server/init.py 调整使扩展包在源码检出可导入；同时删除 python/sglang/srt/grpc/init.py 中的旧模块残留。

3. 三处调用点接线：http_server.py 的 _start_native_grpc_server_for_runtime、rust_server.py 的 RustServer.launch、image_processing_rust.py 的 inkling 导入全部改走 load_rust_extension；其中 gRPC 启动路径删除了原先“扩展不在 wheel 中则硬报错”的 try/except 分支。

4. 缓存、并发与三态控制：_build_context 以源码内容 hash（_source_digest）、工具链版本、Python ABI（EXT_SUFFIX/SOABI 等）、构建环境变量（RUSTFLAGS 等）生成 fingerprint 与 target_fingerprint；_filesystem_lock 用 fcntl 文件锁串行化多进程并发构建；构建完成后复核源码 digest 防中途变化；_stage_atomically 原子暂存产物；environ.py 新增 SGLANG_RUST_BUILD_MODE=auto|never|force 环境变量契约。

5. 配套依赖与测试：rust/Cargo.lock 通过 cargo update --precise 定向升级 dynamo 家族（dynamo-protocols 5.1.0→5.3.1 等），并在 rust/sglang-server/src/api_server/openai/chat.rs 的 chat_logprobs 中填充新 token_id 字段；scripts/ci/utils/stage_rust_ext_modules.sh 更新 CI 暂存路径；新增 test/registered/rust/test_rust_extension.py（350 行，纯 mock 不触发真实 cargo），另有多处测试/导入路径跟随调整（test_utils.py、_mm_rust_utils.py、test_server_args.py、bench_parity.py）。

关键文件：

• python/sglang/srt/rust_extensions/loader.py（模块 扩展加载；类别 source；类型 dependency-wiring；符号 _CrateSpec, _BuildContext, load_rust_extension, _import_bundled_extension）: 本 PR 核心新增文件，412 行实现三级按需加载、crate 发现、指纹缓存、并发锁与原子暂存，是所有 Rust 扩展导入的统一入口。
• test/registered/rust/test_rust_extension.py（模块 单元测试；类别 test；类型 test-coverage；符号 _hold_filesystem_lock, _FailingExtensionLoader, TestRustExtension, test_bundled_wheel_extension_never_touches_source_or_cargo）: 350 行 mock 测试，覆盖加载器全部决策路径，是理解指纹与缓存设计意图的最佳入口，也是后续维护的回归护栏。
• python/sglang/srt/entrypoints/http_server.py（模块 启动入口；类别 source；类型 dependency-wiring）: gRPC 启动路径从硬报错改为按需加载，是用户可见行为变化最明显的接线点。
• python/sglang/srt/managers/rust_server.py（模块 Rust 服务；类别 source；类型 dependency-wiring）: RustServer.launch 是 Rust 原生 server 的入口，Type 引用与运行导入同步迁移到新命名空间。
• python/sglang/srt/multimodal/inkling/image_processing_rust.py（模块 多模态预处理；类别 source；类型 dependency-wiring）: inkling 多模态预处理是第三个接线点，验证 sglang-mm 扩展在 Python 侧的消费方式。
• rust/sglang-server/src/lib.rs（模块 服务内核；类别 source；类型 core-logic；符号 _core, _server）: Rust server crate 的 PyO3 入口更名，是命名空间统一的关键一端。
• rust/sglang-grpc/src/lib.rs（模块 gRPC 内核；类别 source；类型 core-logic；符号 _core, _grpc）: gRPC crate 的 PyO3 入口更名，与 http_server 接线对应。
• rust/sglang-mm/src/lib.rs（模块 多模态内核；类别 source；类型 core-logic；符号 _core, _multimodal）: 多模态 crate 的 PyO3 入口更名，并同步更新 crate 文档注释。
• python/setup.py（模块 构建配置；类别 source；类型 core-logic）: wheel 构建配置必须与加载器发现逻辑保持一致，否则打包出的模块路径与运行期期望不符。
• scripts/ci/utils/stage_rust_ext_modules.sh（模块 CI 脚本；类别 infra；类型 infrastructure）: CI 暂存脚本路径同步更新，否则打包产物在 CI 环境中的布局与本地不一致。
• python/sglang/srt/environ.py（模块 环境配置；类别 source；类型 core-logic）: 新环境变量 SGLANG_RUST_BUILD_MODE 的运行契约在这里登记。
• rust/sglang-server/src/api_server/openai/chat.rs（模块 对话接口；类别 source；类型 entrypoint）: 伴随 Cargo.lock 升级，chat_logprobs 填充新增 token_id 字段，是依赖升级在业务逻辑上的落地。
• rust/Cargo.lock（模块 依赖锁；类别 other；类型 core-logic）: 定向升级 dynamo 家族，是 chat_logprobs token_id 填充与 --locked 可复现构建的基础。

关键符号：load_rust_extension, _discover_crate, _build_context, _source_digest, _source_files, _import_bundled_extension, _filesystem_lock, chat_logprobs

关键源码片段

test/registered/rust/test_rust_extension.py

350 行 mock 测试，覆盖加载器全部决策路径，是理解指纹与缓存设计意图的最佳入口，也是后续维护的回归护栏。

def test_fingerprint_is_content_based_and_covers_build_inputs(self):
    with TemporaryDirectory() as directory:
        workspace = self._workspace(Path(directory))
        crate = rust_extension._discover_crate(workspace, "demo._core")
        with mock.patch.object(
            rust_extension,
            "_command_version",
            side_effect=lambda command, *args, **kwargs: f"{command} 1.0",
        ):
            first = rust_extension._build_context(crate)
            source = workspace / "demo" / "lib.rs"
            # 只改动 mtime 不得改变指纹，证明指纹基于内容 hash 而非时间戳，
            # 避免 git checkout 等操作触发无谓的全量重建。
            os.utime(source, (1, 1))
            self.assertEqual(first, rust_extension._build_context(crate))
​
            # 内容变化必须让 fingerprint 变化，从而命中新的缓存路径。
            source.write_text("fn changed() {}\n", encoding="utf-8")
            changed_source = rust_extension._build_context(crate)
            self.assertNotEqual(first.fingerprint, changed_source.fingerprint)
​
            # RUSTFLAGS 属于构建环境变量，改变它应同时影响
            # fingerprint 与 target_fingerprint（后者用于隔离编译产物）。
            with mock.patch.dict(os.environ, {"RUSTFLAGS": "-Ctarget-cpu=native"}):
                changed_flags = rust_extension._build_context(crate)
            self.assertNotEqual(changed_source.fingerprint, changed_flags.fingerprint)
            self.assertNotEqual(
                changed_source.target_fingerprint,
                changed_flags.target_fingerprint,
            )
​
​
def test_auto_builds_once_then_uses_cache(self):
    # auto 模式首次触发 cargo build，之后同一 fingerprint 直接命中缓存，
    # 验证 cargo_build 只被调用一次，避免重复编译。
    with TemporaryDirectory() as directory:
        root = Path(directory)
        workspace = self._workspace(root)
        artifact = root / "libdemo_extension.so"
        artifact.write_bytes(b"extension")
        context = rust_extension._BuildContext("source", "fingerprint", "target")
        loaded = ModuleType("demo._core")
        with (
            mock.patch.object(
                rust_extension, "_import_bundled_extension", return_value=None
            ),
            mock.patch.object(rust_extension, "_build_context", return_value=context),
            mock.patch.object(rust_extension, "_source_digest", return_value="source"),
            mock.patch.object(
                rust_extension, "_cargo_build", return_value=artifact
            ) as cargo_build,
            mock.patch.object(
                rust_extension, "_load_extension_from_path", return_value=loaded
            ),
        ):
            self.assertIs(
                rust_extension.load_rust_extension(
                    "demo._core", workspace=workspace, cache_dir=root / "cache"
                ),
                loaded,
            )
            self.assertIs(
                rust_extension.load_rust_extension(
                    "demo._core", workspace=workspace, cache_dir=root / "cache"
                ),
                loaded,
            )
        cargo_build.assert_called_once()

评论区精华

本 PR 无外部 review 讨论（review 评论为 0），唯一评论是作者 merrymercy 触发的 CI 重跑指令 "/tag-and-rerun-ci"。设计决策主要沉淀在 PR body 与 commit 演进中：

commit 2 "Fix Python 3.10 TOML compatibility"：确认 loader 需要兼容 3.10，引入 tomli 回退，避免新加载器自身成为版本门槛。

commit 3 "Group Rust extensions under explicit package"：扩展从散落在 sglang.srt.grpc/server/multimodal 下收敛为独立 rust_extensions 包，说明作者在迭代中意识到统一命名空间对发现与缓存的重要性。

commit 4/5/6 依次跟进 CI 暂存路径与各导入点验证，体现“命名迁移必须同步修改所有引用方”的工程约束。

• 暂无高价值评论线程

风险与影响

• 风险：

  1. 首次编译延迟：auto 模式在源码检出且无缓存时会触发 cargo build --release，Rust release 编译可能耗时数分钟，首次启动 gRPC/RustServer/inkling 相关路径会显著变慢，且编译失败信息依赖异常向上传播。
  2. 无 Rust 工具链的源码检出会直接失败：_command_version 在 crate 发现前就会抛 RuntimeError；用户只能显式设置 SGLANG_RUST_BUILD_MODE=never 来获得更友好的错误。
  3. 模块路径迁移破坏性：sglang.srt.grpc._core、sglang.srt.server._core、sglang.srt.multimodal._core 三个旧路径不再存在，任何直接 import 旧路径的第三方代码、文档示例会 ModuleNotFoundError；setup.py 与 CI 脚本已同步，但外部引用无法枚举。
  4. 缓存失效粒度过粗：_source_digest 遍历整个 rust/ 工作区，任一 crate 的源码变化都会让全部三个扩展的缓存集体失效，触发多 crate 重编译。
  5. fcntl 平台限制：_filesystem_lock 依赖 fcntl，仅支持 Unix 系平台，Windows 源码检出不可用；当前 SGLang 主要目标平台为 Linux，属已知边界。
  6. dynamo 依赖升级：Cargo.lock 升级 dynamo-protocols 5.1.0→5.3.1 并新增 token_id 字段，依赖旧版字段行为的其他路径可能存在细微差异；--locked 构建已保证可复现性。
     - 影响：影响范围集中在构建期与开发环境，运行时推理路径不变。

• 开发者：源码检出（editable install）搭配 Rust 工具链即可直接使用 gRPC 端口、RustServer 与 inkling 多模态预处理，无需预构建 wheel，显著降低 SGLang 本地开发与调试门槛。

• 系统/发布：wheel 内扩展模块路径发生 breaking 变更（sglang.srt.rust_extensions.*），setup.py、CI 暂存脚本、测试导入全部联动更新；新增 SGLANG_RUST_BUILD_MODE 环境变量作为新的运行契约。
• 团队/工程：未来新增 Rust crate 只需在 Cargo.toml 声明 python-module 元数据即可自动接入加载器，无需在 Python 侧登记，降低 Rust 化组件的扩展成本，推动更多子模块向 Rust 迁移。
• 风险标记：首次使用触发全量 Rust 编译（分钟级延迟）, 无 Rust 工具链时 auto 模式直接失败, 扩展模块路径迁移破坏旧导入, 缓存粒度为整个 workspace，易集体失效, 文件锁依赖 fcntl，仅支持 Unix

关联脉络

• PR #34309 标题未在材料中提供（PR body 提及移除 test_cargo_workspace.py）: 本 PR 原计划将 test/registered/rust/test_cargo_workspace.py 的 cargo test --workspace 改为 --locked，但该文件已被 #34309 移除，故该部分变更被丢弃而非重新添加。