执行摘要

• 一句话：添加 system_fingerprint 字段支持四种模式
• 推荐动作：该 PR 代码质量较高，测试覆盖充分，review 中提出的问题均已解决。推荐阅读 fingerprint.py 了解模块设计，以及 completion/serving.py 中流式指纹注入的精确控制。整体设计考虑了兼容性、性能和信息安全，值得参考。

功能与动机

PR body 指出需要支持 system_fingerprint 字段帮助客户端识别服务环境。关联 issue 评论虽提到 OpenAI 已弃用该字段，但作者认为仍有用，并通过 --fingerprint-value 支持自定义覆盖。

实现拆解

1. 新增指纹核心模块 vllm/entrypoints/openai/fingerprint.py，定义 build_system_fingerprint 函数根据模式构建指纹字符串：full 模式包含版本号、非平凡并行度（tp/pp/dp/ep）和配置哈希前缀；hash 模式仅含版本号和哈希；custom 模式返回用户指定值；none 返回 None。采用模块级全局变量 _DEFAULT_MODE 和 _CUSTOM_VALUE 存储默认模式，通过 set_default_fingerprint_mode 在启动时配置。

2. 在服务启动入口注入模式：修改 vllm/entrypoints/openai/generate/api_router.py，在 init_generate_state 中调用 set_default_fingerprint_mode 以应用 CLI 参数 --fingerprint-mode 和 --fingerprint-value，确保在所有 serving 类构造前生效。

3. 基类计算并缓存指纹：修改 vllm/entrypoints/openai/engine/serving.py 中 OpenAIServing.__init__，在初始化时调用 get_system_fingerprint(engine_client.vllm_config)，并将结果缓存到 self.system_fingerprint。计算异常时优雅降级为 None，不阻断启动。

4. 各响应端点注入指纹字段：分别修改 completion/serving.py、chat_completion/serving.py 和 batch_serving.py，在非流式响应（CompletionResponse、ChatCompletionResponse）和流式响应的最终块（include_usage 为真时标记 usage 块，否则标记终止块）上设置 system_fingerprint。同时将序列化策略从 exclude_unset=False 改为 exclude_unset=True 以抑制未设置字段的输出。

5. 协议模型添加字段：在 CompletionStreamResponse、ChatCompletionResponse、CompletionResponse 等协议类中增加 system_fingerprint: str | None = None 字段定义。

6. 测试覆盖：新增 tests/entrypoints/openai/test_fingerprint.py，验证四种模式输出格式、并行度编码、哈希失败降级、模式切换等行为，测试采用 SimpleNamespace 模拟配置对象。

关键文件：

• vllm/entrypoints/openai/fingerprint.py（模块 指纹模块；类别 source；类型 core-logic；符号 set_default_fingerprint_mode, get_system_fingerprint, build_system_fingerprint）: 核心模块，定义了指纹构建、模式设置和获取函数。
• tests/entrypoints/openai/test_fingerprint.py（模块 测试；类别 test；类型 test-coverage；符号 _cfg, _reset, test_four_modes_produce_expected_shapes, test_full_mode_emits_only_non_trivial_parallelism）: 单元测试，覆盖四种模式、并行度编码、哈希失败降级等。
• vllm/entrypoints/openai/engine/serving.py（模块 引擎服务；类别 source；类型 dependency-wiring）: 基类 OpenAIServing 中计算并缓存指纹，是所有 serving 类的共同入口。
• vllm/entrypoints/openai/completion/serving.py（模块 补全服务；类别 source；类型 core-logic）: 补全服务中注入指纹字段至响应，并调整序列化策略。
• vllm/entrypoints/openai/chat_completion/serving.py（模块 聊天服务；类别 source；类型 core-logic）: 聊天服务中注入指纹字段至响应。
• vllm/entrypoints/openai/generate/api_router.py（模块 路由；类别 source；类型 entrypoint）: 服务启动入口，调用 set_default_fingerprint_mode 应用 CLI 参数。
• vllm/entrypoints/openai/cli_args.py（模块 配置；类别 source；类型 configuration）: 新增 --fingerprint-mode 和 --fingerprint-value CLI 参数。
• vllm/entrypoints/openai/completion/protocol.py（模块 协议；类别 source；类型 data-contract）: 补全协议模型添加 system_fingerprint 字段。
• vllm/entrypoints/openai/chat_completion/protocol.py（模块 协议；类别 source；类型 data-contract）: 聊天协议模型添加 system_fingerprint 字段。
• vllm/entrypoints/openai/chat_completion/batch_serving.py（模块 批处理；类别 source；类型 core-logic）: 批处理服务最终响应添加 fingerprint。

关键符号：set_default_fingerprint_mode, get_system_fingerprint, build_system_fingerprint

关键源码片段

vllm/entrypoints/openai/fingerprint.py

核心模块，定义了指纹构建、模式设置和获取函数。

def build_system_fingerprint(
    vllm_config: Any,
    mode: FingerprintMode = "full",
    custom_value: str | None = None,
) -> str | None:
    # 如果模式为 none，直接返回 None
    if mode == "none":
        return None
    # 如果模式为 custom，返回用户指定的值
    if mode == "custom":
        return custom_value
​
    # 延迟导入版本号，避免模块级依赖
    from vllm import __version__ as vllm_version
​
    # 计算配置哈希：捕获所有异常，失败时使用 "nohash" 占位
    try:
        hash8 = vllm_config.compute_hash()[:8]
    except Exception:
        hash8 = "nohash"
​
    # hash 模式：仅版本号加哈希
    if mode == "hash":
        return f"vllm-{vllm_version}-{hash8}"
​
    # full 模式：构建包含版本号、非平凡并行度、哈希的字符串
    parts: list[str] = [f"vllm-{vllm_version}"]
    pc = getattr(vllm_config, "parallel_config", None)
    if pc is not None:
        # 只添加大于 1 的并行度，避免无意义的标注
        tp = getattr(pc, "tensor_parallel_size", 1)
        if tp > 1:
            parts.append(f"tp{tp}")
        pp = getattr(pc, "pipeline_parallel_size", 1)
        if pp > 1:
            parts.append(f"pp{pp}")
        dp = getattr(pc, "data_parallel_size", 1)
        if dp > 1:
            parts.append(f"dp{dp}")
        if getattr(pc, "enable_expert_parallel", False):
            parts.append("ep")
    parts.append(hash8)
    return "-".join(parts)

tests/entrypoints/openai/test_fingerprint.py

单元测试，覆盖四种模式、并行度编码、哈希失败降级等。

def test_four_modes_produce_expected_shapes():
    # 构造一个模拟的 vllm_config，具有 tp=8, ep=True
    cfg = _cfg(tp=8, ep=True)
    # 验证 full 模式包含 tp8 和 ep
    assert fp.build_system_fingerprint(cfg, "full") == (
        f"vllm-{v}-tp8-ep-a3b21f94"
    )
    # 验证 hash 模式不含 tp8
    assert fp.build_system_fingerprint(cfg, "hash") == f"vllm-{v}-a3b21f94"
    # 验证 custom 模式返回自定义字符串
    assert fp.build_system_fingerprint(cfg, "custom", "my-fp") == "my-fp"
    # 验证 none 模式返回 None
    assert fp.build_system_fingerprint(cfg, "none") is None

评论区精华

review 评论中讨论了三个要点：
(1) 缓存键安全性：gemini-code-assist 指出使用 id(vllm_config) 作为缓存键可能在对象回收后产生错误，建议改用 WeakKeyDictionary；最终提交移除了模块级缓存，改为由 serving 类实例缓存，彻底规避该问题。
(2) 属性访问健壮性：gemini-code-assist 建议对并行配置属性使用 getattr 返回值而不是直接访问，以避免 AttributeError；实现已按建议修复。
(3) 流式响应序列化开销：Codex 提醒 exclude_unset=False 会导致每个流式块都携带 null 的 system_fingerprint；作者随后改为 exclude_unset=True 并仅在最终块显式设置字段，njhill 补充质疑此变更可能影响其他字段序列化行为，但经确认后接受。

• 使用 id(vllm_config) 作为缓存键的潜在问题 (correctness): 后续提交移除了模块级缓存，改为 serving 类实例缓存，避免了问题。
• 并行配置属性访问的健壮性 (correctness): 作者采用了建议，修改为使用 getattr 返回值。
• 流式响应中 system_fingerprint 的序列化开销 (performance): 作者改为 exclude_unset=True，并显式在最终块设置 fingerprint，且补充了 object 字段以保持兼容。

风险与影响

• 风险：主要风险包括：
  (1) 配置哈希依赖：vllm_config.compute_hash() 可能因依赖缺失或中途变更而抛出异常，但代码已捕获所有异常并降级为 'nohash'，保证启动不中断。
  (2) 序列化兼容性：将 exclude_unset=True 改为默认可能影响其他未显式设置的字段（如 object）在流式响应中缺失，但后续提交已显式补回 object 字段，维持兼容。
  (3) 性能风险：指纹仅启动时计算一次，每请求仅读取缓存属性，无额外开销。
  (4) 信息泄露：full 模式可能暴露并行度配置，但哈希模式可规避，且 custom 模式允许用户完全控制。

• 影响：对客户端：非流式响应新增 system_fingerprint 字段，符合 OpenAI 规范；流式响应仅在最终块携带。对服务端：新增 CLI 参数 --fingerprint-mode 和 --fingerprint-value，需配置人员了解。对团队：新增 84 行核心逻辑、76 行测试，维护成本低。向下兼容：指纹计算失败时字段为 None，不影响现有逻辑。

• 风险标记：配置哈希依赖, 序列化兼容性调整, 新模块依赖

关联脉络

• 暂无明显关联 PR