# PR #36920 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Add configurable HTTP/2 connection window
- 合并时间：2026-08-29 13:18
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/36920

---

# 执行摘要

- 一句话：新增可配置 HTTP/2 连接窗口参数
- 推荐动作：该 PR 值得精读，尤其是对负责部署和调优 SGLang 服务端性能的工程师。核心关注点是参数命名、校验范围和传递链路的设计，以及如何与现有 HTTP/2 配置相结合。

# 功能与动机

PR 描述指出，仅增加 `--http2-max-concurrent-streams` 无法防止客户端并发上传大量大型请求体时发生的连接级流控停顿。Granian 默认的 HTTP/2 连接接收窗口为 1 MiB，因此服务 workload 需要一种独立于流限制的调优该窗口的方式。

# 实现拆解

1. **新增参数定义**：在 `python/sglang/srt/server_args.py` 的 `ServerArgs` 类中新增 `http2_initial_connection_window_size` 参数，默认值设为 1024 * 1024（即 1 MiB），与 Granian 默认值一致。
2. **参数校验**：在 `python/sglang/srt/arg_groups/serving_hook.py` 的 `handle_ssl_validation` 函数中添加了对新参数的有效性检查，要求取值在 1024 到 2^31 - 1 之间，否则抛出 ValueError。
3. **参数传递**：修改 `python/sglang/srt/entrypoints/http_server.py` 中的 `_run_granian_server` 函数，新增 `http2_initial_connection_window_size` 参数，并将其传递给 `HTTP2Settings` 的 `initial_connection_window_size` 字段。同时，在 `_setup_and_run_http_server` 和 `_run_with_ssl_refresh` 中调用此函数时传入对应的服务器参数。
4. **测试更新**：更新 `test/registered/unit/entrypoints/test_http2_server_config.py`，在现有测试中增加对新参数的断言，验证其正确传递到 Granian 配置。

关键文件：
- `python/sglang/srt/entrypoints/http_server.py`（模块 HTTP 服务器；类别 source；类型 core-logic；符号 _run_granian_server, _setup_and_run_http_server, _run_with_ssl_refresh）: 核心变更文件，负责将新参数传递给 Granian HTTP2Settings，并涉及两个调用点的参数传递。
- `python/sglang/srt/arg_groups/serving_hook.py`（模块 参数校验；类别 source；类型 core-logic；符号 handle_ssl_validation）: 新增参数校验逻辑，确保窗口大小在合法范围内。
- `python/sglang/srt/server_args.py`（模块 参数定义；类别 source；类型 core-logic；符号 http2_initial_connection_window_size）: 新增参数定义，提供默认值和帮助信息。
- `test/registered/unit/entrypoints/test_http2_server_config.py`（模块 HTTP/2 配置测试；类别 test；类型 test-coverage；符号 test_passes_explicit_max_concurrent_streams）: 更新现有测试以覆盖新参数的传递。

关键符号：_run_granian_server, _setup_and_run_http_server, _run_with_ssl_refresh, handle_ssl_validation

## 关键源码片段

### `python/sglang/srt/entrypoints/http_server.py`

核心变更文件，负责将新参数传递给 Granian HTTP2Settings，并涉及两个调用点的参数传递。

```python
from granian.http import HTTP2Settings

def _run_granian_server(
    host,
    port,
    log_level,
    http2_max_concurrent_streams,
    http2_initial_connection_window_size,  # 新增参数
    tokenizer_worker_num=1,
    ssl_certfile=None,
    ssl_keyfile=None,
    ssl_ca_certs=None,
    ssl_keyfile_password=None,
    ssl_verify=False,
    backlog=2048,
    backpressure=2048,
):
    # ... 省略部分代码 ...

    granian_kwargs = dict(
        target=target,
        address=host,
        port=port,
        interface=Interfaces.ASGI,
        http=HTTPModes.auto,
        http2_settings=HTTP2Settings(
            initial_connection_window_size=http2_initial_connection_window_size,
            max_concurrent_streams=http2_max_concurrent_streams,
        ),
        # ...
    )
    # ...

```

### `python/sglang/srt/arg_groups/serving_hook.py`

新增参数校验逻辑，确保窗口大小在合法范围内。

```python
def handle_ssl_validation(server_args: Any):
    cfg = resolving_view(server_args)
    # ... 省略 SSL 相关校验 ...
    if cfg.enable_http2:
        if not 0 < cfg.http2_max_concurrent_streams < 2**32:
            raise ValueError("--http2-max-concurrent-streams must be between 1 and 4294967295.")
        if not 1024 <= cfg.http2_initial_connection_window_size < 2**31:
            raise ValueError("--http2-initial-connection-window-size must be between 1024 and 2147483647.")
        # ...

```

### `python/sglang/srt/server_args.py`

新增参数定义，提供默认值和帮助信息。

```python
class ServerArgs:
    # ...
    http2_initial_connection_window_size: A[
        int,
        "Initial connection-level HTTP/2 receive window in bytes (1024 to 2^31 - 1). Only applies with --enable-http2.",
        NS("serving"),
    ] = 1024 * 1024
    # ...

```

# 评论区精华

PR 的 review 评论为空，仅有一位 reviewer（ispobock）批准了该 PR，无公开的讨论内容。

- 暂无高价值评论线程

# 风险与影响

- 风险：该变更涉及 HTTP/2 服务器配置，主要风险包括：调整连接窗口大小可能影响服务器内存占用和并发行为，但仅影响网络层，不涉及模型执行逻辑；参数校验可防止非法值导致的运行时错误，但未对现有 `http2_max_concurrent_streams` 的边界检查进行调整；测试覆盖了参数传递，但未验证窗口大小调整对实际吞吐量的影响。
- 影响：该参数默认值与 Granian 默认一致，因此现有用户无需修改配置即可保持行为不变。对于需要高并发上传大请求体的场景，调整此参数可显著提升吞吐量（PR 中提及 64 MiB 窗口下 2048 请求耗时降至 0.7 秒左右）。该变更对团队影响较小，属于配置层面的增强。
- 风险标记：配置变更，影响服务器网络层 , 新增参数，需文档同步

# 关联脉络

- 暂无明显关联 PR