执行摘要

• 一句话：将原生 gRPC 服务器接入启动流程与参数系统
• 推荐动作：建议技术负责人审查此 PR 以理解 gRPC 集成架构；开发者在启用 --grpc-port 前需确保编译包含 Rust 扩展。测试覆盖可进一步扩展。

功能与动机

为 SGLang 提供原生高性能 gRPC 接口，替代遗留的 SMG gRPC 方案，允许用户在不改变 HTTP 使用方式的同时启用 gRPC 服务。关联 Issue #22907 和 RFC #22558。

实现拆解

1. 参数系统改造（server_args.py）：新增 smg_grpc_mode 替代 grpc_mode，将 grpc_mode 保留为弃用别名；新增 grpc_port 控制原生 gRPC 端口，环境变量 SGLANG_GRPC_PORT 提供回退；重命名 grpc_http_sidecar_port 为 smg_http_sidecar_port，保持向后兼容；在 _handle_deprecated_args 中添加多 tokenizer 校验、auth 冲突检测、端口范围验证等。

2. 启动入口分发（launch_server.py）：将 server_args.grpc_mode 检查改为 server_args.smg_grpc_mode or server_args.grpc_mode，保持遗留 SMG gRPC 服务器启动路径单独分支。

3. HTTP 服务生命周期嵌入（http_server.py）：在 lifespan 函数中，当 is_single_tokenizer_mode 且 grpc_port 设置且非 SMG 模式时，在 yield 前启动原生 gRPC 服务器，在 finally 中关闭；新增 _start_native_grpc_server_for_runtime 和 _shutdown_native_grpc_server 函数。

4. 环境变量与弃用告警（environ.py）：添加 SGLANG_GRPC_WORKER_THREADS 环境变量；弃用 SGLANG_ENABLE_GRPC，改用 --grpc-port 启用。

5. 单元测试覆盖（test_server_args.py）：新增 TestGrpcServerArgs 类，覆盖默认值、HTTP 独占不派生 gRPC 端口、gRPC 端口启用原生和环境变量、SMG 派生端口、弃用别名、多 tokenizer 限制、auth 冲突等场景。

关键文件：

• python/sglang/srt/entrypoints/http_server.py（模块 HTTP 入口；类别 source；类型 core-logic；符号 _start_native_grpc_server_for_runtime, _shutdown_native_grpc_server）: 核心文件：在 lifespan 中嵌入原生 gRPC 服务器启动和关闭，新增 _start_native_grpc_server_for_runtime 和 _shutdown_native_grpc_server 函数。
• test/registered/unit/server_args/test_server_args.py（模块 参数测试；类别 test；类型 test-coverage；符号 TestGrpcServerArgs, _args, test_defaults_native_grpc_off_legacy_off, test_http_only_high_port_does_not_derive_grpc_port）: 新增 TestGrpcServerArgs 测试类，覆盖参数默认值、gRPC 端口启用、SMG 模式、弃用别名、多 tokenizer 限制等场景。
• python/sglang/srt/server_args.py（模块 参数系统；类别 source；类型 core-logic）: 定义 smg_grpc_mode、grpc_mode（弃用）、grpc_port 等新字段，在 _handle_deprecated_args 中处理兼容性、校验多 tokenizer 和 auth 冲突。
• python/sglang/launch_server.py（模块 启动器；类别 source；类型 core-logic）: 更新 run_server 中 gRPC 模式判断逻辑，使用 smg_grpc_mode 替代 grpc_mode。
• python/sglang/srt/environ.py（模块 环境变量；类别 source；类型 core-logic）: 新增 SGLANG_GRPC_WORKER_THREADS 环境变量并弃用 SGLANG_ENABLE_GRPC。
• python/sglang/srt/entrypoints/grpc_server.py（模块 gRPC 入口；类别 source；类型 core-logic）: 将引用 grpc_http_sidecar_port 改为 smg_http_sidecar_port。

关键符号：_start_native_grpc_server_for_runtime, _shutdown_native_grpc_server, run_server, _handle_deprecated_args, prepare_server_args

评论区精华

• Kangyan-Zhou 报告阻塞问题：max_prefill_tokens 参数在 Rust start_server 中不存在，导致 --grpc-port 启动立即崩溃（TypeError: start_server() got an unexpected keyword argument 'max_prefill_tokens'）。作者在后继 commit 中修复，删除了无效参数。

• JustinTong0323 提出 auth bypass 风险：gRPC 服务器绕过 HTTP 的认证中间件，应拒绝带 api_key 的配置或传递 auth。作者在 _handle_deprecated_args 中添加了 auth 冲突检查并抛出 ValueError。

• Kangyan-Zhou 指出测试覆盖不足：TestGrpcServerArgs 仅覆盖参数解析，未覆盖 start_server 实际调用和 --use-ray/--admin-api-key 等场景。

  • max_prefill_tokens 参数传递错误导致启动崩溃 (correctness): alexnails 删除了无效参数，修复后启动正常。
  • gRPC 服务器绕过 HTTP 认证中间件 (security): 在 _handle_deprecated_args 中添加检查，当 api_key 设置时拒绝同时启用原生 gRPC。
  • 缺少端到端集成测试覆盖 (testing): 承认测试不足，后续 PR 将补充集成测试。

风险与影响

• 风险：
  • 参数兼容性风险：--grpc-mode 用户升级后仍可用但收到弃用警告，若下游脚本解析输出可能受影响。
  • 功能缺失风险：原生 gRPC 启动失败（如编译缺失 _core 扩展）会抛出 RuntimeError，但错误信息可能不够直观。
  • 测试不足风险：仅有参数级单元测试，缺少启动集成测试，可能遗漏实际运行时错误（如生命周期钩子错误）。
  • 安全考虑：HTTP auth 与 gRPC 不共享，虽然参数阶段拒绝同时使用，但用户可能分别配置导致不一致。
  • 影响：影响范围中等，主要涉及服务器启动流程和参数体系。对普通用户无影响，只有主动使用 --grpc-port 的用户会启动 gRPC 服务器。对团队而言，这是向原生 gRPC 迁移的关键一步，后续可移除遗留 SMG 模式。
  • 风险标记：缺少集成测试覆盖, 启动参数兼容性, gRPC 实验性功能

关联脉络

• PR #22907 [gRPC] Native gRPC server implementation and phase 1 fixes: 本 PR 是原始 PR #22907 的 phase-1 拆分第三部分，即服务端集成部分。
• PR #23506 [gRPC] Native server: Rust crate: 提供 Rust gRPC 服务器核心，本 PR 中的 _start_native_grpc_server_for_runtime 调用 Rust crate 的 start_server。
• PR #23507 [gRPC] Native server: Python bridge entrypoint: 提供 RuntimeHandle 等 Python 侧桥接，本 PR 依赖该桥接同步请求。