执行摘要

• 一句话：暴露 stream_interval 作为请求级采样参数
• 推荐动作：此 PR 设计简洁，clamp 模式值得在其他请求级参数中借鉴。建议阅读 vllm/v1/engine/output_processor.py 中的 clamp 逻辑和测试用例，以理解安全边界的设计思路。

功能与动机

原本 stream_interval 仅在服务器启动时全局配置，无法按请求调整。对于长时间生成任务，客户端可能希望缩短间隔以获得更实时的反馈，或拉长间隔以减少通信开销。PR 让客户端可以根据任务特点动态指定间隔，提升灵活性。讨论中 njhill 要求客户端不能降低服务器设置的间隔，最终采用 clamp 策略确保安全。

实现拆解

1. 数据模型：在 vllm/sampling_params.py 的 SamplingParams 类中添加 stream_interval: int | None 字段，并在 from_optional 方法中增加对应参数，在 _verify_args 中校验其值至少为 1。
2. API 协议：在 vllm/entrypoints/openai/chat_completion/protocol.py 和 completion/protocol.py 的请求模型中添加同名字段，并在 to_sampling_params 方法中传递给 SamplingParams.from_optional。
3. 输出处理器：在 vllm/v1/engine/output_processor.py 的 from_new_request 中实现 clamp：stream_interval = max(sampling_params.stream_interval, stream_interval)，确保请求值不会低于引擎全局设置。
4. 测试：在 tests/v1/engine/test_output_processor.py 中添加 test_request_stream_interval_raises_but_not_below_engine_default，验证低于引擎设置的值被 clamp、高于的值生效，且生成文本不受影响。

关键文件：

• vllm/sampling_params.py（模块 采样参数；类别 source；类型 core-logic；符号 SamplingParams, from_optional, _verify_args）: 定义了 SamplingParams 的新字段 stream_interval，是本次变更的核心数据模型。
• vllm/v1/engine/output_processor.py（模块 输出处理器；类别 source；类型 core-logic；符号 from_new_request）: 实现了请求级 stream_interval 与引擎设置比较并 clamp 的核心逻辑。
• tests/v1/engine/test_output_processor.py（模块 测试；类别 test；类型 test-coverage；符号 test_request_stream_interval_raises_but_not_below_engine_default）: 新增针对 clamp 行为的单元测试，确保正确性。
• vllm/entrypoints/openai/chat_completion/protocol.py（模块 Chat接口；类别 source；类型 core-logic；符号 ChatCompletionRequest, to_sampling_params）: Chat API 请求模型新增 stream_interval 字段并传递到 SamplingParams。
• vllm/entrypoints/openai/completion/protocol.py（模块 Completion接口；类别 source；类型 core-logic；符号 CompletionRequest, to_sampling_params）: Completion API 请求模型新增 stream_interval 字段并传递到 SamplingParams。

关键符号：SamplingParams.from_optional, SamplingParams._verify_args, OutputProcessor.from_new_request, ChatCompletionRequest.to_sampling_params, CompletionRequest.to_sampling_params

关键源码片段

vllm/sampling_params.py

定义了 SamplingParams 的新字段 stream_interval，是本次变更的核心数据模型。

# sampling_params.py 中与 stream_interval 相关的核心变更
class SamplingParams:
    # ... 其他字段 ...
    stream_interval: int | None = None
    '''Number of newly generated tokens to batch into each streamed
    `RequestOutput`. Raises the interval above the engine-level
    `--stream-interval`. Values below engine setting are clamped up to it.
    The first and final outputs are always emitted immediately.'''
​
    @staticmethod
    def from_optional(
        # ... 其他参数 ...
        stream_interval: int | None = None, # 新增请求级间隔
    ) -> 'SamplingParams':
        return cls(
            # ... 其他字段 ...
            stream_interval=stream_interval,
        )
​
    def _verify_args(self) -> None:
        # ... 已有验证 ...
        if self.stream_interval is not None and self.stream_interval < 1:
            raise VLLMValidationError(
                f'stream_interval must be at least 1, got {self.stream_interval}.',
                parameter='stream_interval',
                value=self.stream_interval,
            )

vllm/v1/engine/output_processor.py

实现了请求级 stream_interval 与引擎设置比较并 clamp 的核心逻辑。

# vllm/v1/engine/output_processor.py 中 from_new_request 方法的 clamp 逻辑
@classmethod
def from_new_request(
    cls,
    request: EngineCoreRequest,
    # ...
    stream_interval: int,
    # ...
) -> 'OutputProcessor':
    # ... 前期处理 ...
    if sampling_params.stream_interval is not None:
        # 请求级间隔不能低于引擎设置，clamp 到最大值
        stream_interval = max(sampling_params.stream_interval, stream_interval)
    # ... 后续处理 ...

tests/v1/engine/test_output_processor.py

新增针对 clamp 行为的单元测试，确保正确性。

def test_request_stream_interval_raises_but_not_below_engine_default(
    dummy_test_vectors,
):
    '''验证请求级 stream_interval 低于引擎默认值时被 clamp，高于时生效，且生成文本不变。'''
    engine_stream_interval = 5
    request_stream_intervals = [1, 10]
    output_processor = OutputProcessor(
        dummy_test_vectors.tokenizer,
        log_stats=False,
        stream_interval=engine_stream_interval,
    )
    # 构造请求并处理输出，断言 token 数符合预期间隔
    # 完整实现参见源文件

评论区精华

njhill 在 review 中提出："I'm not sure that this is something we would want the client to be in control of? ... I don't think the client should be able to reduce the interval from the server setting." 作者回应后接受此建议，修改实现为 clamp 策略：请求的 stream_interval 低于引擎设置时自动提升至引擎值。最终 njhill 批准合并。

• 是否允许客户端控制 stream_interval (design): 采用 clamp，请求值低于引擎设置时自动提升到引擎值。

风险与影响

• 风险：无重大风险。主要风险点在于客户端可能设置过大的值导致输出延迟，但这是用户主动行为且受引擎最小限制保护。新参数默认为 None，不影响现有请求。验证逻辑确保值 >=1。测试覆盖了 clamp 边界。API 协议的新字段对旧客户端透明（忽略未知字段）。
• 影响：影响范围限于 OpenAI API 用户，新增可选参数，无性能开销。团队维护成本低，逻辑集中在少数几个文件。向后兼容，不会破坏现有部署。
• 风险标记：客户端可配置流间隔, 需 clamp 约束

关联脉络

• 暂无明显关联 PR