执行摘要

• 一句话：保护可选 SGLang Anthropic 辅助模块导入，隔离故障至 501 路由。
• 推荐动作：这个 PR 值得精读。它不是一个大型功能，但展示了一个处理可选依赖和提升系统容错性的清晰、完整的模式：1）在导入点保护可选依赖；2）提供运行时能力查询函数；3）在功能入口点进行守卫检查；4）返回结构化且与路由合同一致的错误响应；5）通过隔离的测试用例覆盖缺失场景。这对于维护类似架构的模块具有很好的借鉴意义。

功能与动机

如 PR body 所述，SGLang 的安装可以只暴露核心 OpenAI 兼容 API，而不包含所有可选的 Anthropic 辅助模块。Miles 此前在会话服务器模块加载时会导入这些模块，导致服务器无法启动，即使调用者仅需不相关的 API。本次变更旨在检测可选能力并将该限制隔离到 Anthropic 路由，保持其余会话接口可用。

实现拆解

1. 在 anthropic_adapter.py 中保护导入并新增能力检查函数：将 sglang.srt.entrypoints.anthropic 包下的 utils、protocol 模块的导入包裹在 try/except ImportError 块中，导入失败时将对应符号设为 None。新增 anthropic_adapter_available() 函数，通过检查这些符号是否为 None 来判断适配器是否可用。
2. 在 sessions.py 中保护导入并在路由中添加守卫：同样用 try/except 包裹 anthropic_utils 和 serving 模块的导入。在 anthropic_messages 路由的处理函数入口处，检查所有必需的 Anthropic 辅助符号和适配器可用性。若任一不可用，立即返回一个结构化的 Anthropic 风格 501 错误 JSON 响应，并终止请求处理。
3. 在测试中增加缺失模块场景的覆盖：新增参数化测试 test_sessions_module_imports_without_optional_sglang_anthropic_helpers，通过子进程模拟不同的模块缺失场景，验证 sessions 模块仍可成功导入。新增测试用例 test_unavailable_sglang_adapter_returns_501_without_record，模拟运行时适配器不可用，验证返回正确的 501 状态码、错误格式且不会创建会话记录。

关键文件：

• miles/rollout/session/anthropic_adapter.py（模块 会话适配层；类别 source；类型 dependency-wiring；符号 anthropic_adapter_available）: 核心变更：保护了对 SGLang Anthropic 协议和工具库的导入，并新增了 anthropic_adapter_available 能力检查函数，是故障隔离的基础。
• miles/rollout/session/sessions.py（模块 会话路由；类别 source；类型 dependency-wiring；符号 anthropic_messages）: 关键集成点：保护了对 SGLang Anthropic serving 模块的导入，并在 /v1/messages 路由入口添加了守卫检查，实现了故障隔离。
• tests/fast/router/test_session_anthropic.py（模块 会话路由测试；类别 test；类型 test-coverage；符号 test_sessions_module_imports_without_optional_sglang_anthropic_helpers, test_unavailable_sglang_adapter_returns_501_without_record）: 测试覆盖：新增了参数化测试验证模块缺失时的导入鲁棒性，以及运行时适配器不可用时的 501 响应行为，为变更提供了验证。

关键符号：anthropic_adapter_available, test_sessions_module_imports_without_optional_sglang_anthropic_helpers, test_unavailable_sglang_adapter_returns_501_without_record, anthropic_messages

关键源码片段

miles/rollout/session/anthropic_adapter.py

核心变更：保护了对 SGLang Anthropic 协议和工具库的导入，并新增了 anthropic_adapter_available 能力检查函数，是故障隔离的基础。

"""Anthropic protocol helpers for the session HTTP adapter."""
​
import json
​
from pydantic import ValidationError
from starlette.responses import Response
​
# 可选依赖：SGLang 的 Anthropic 辅助模块。导入失败时设置为 None。
try:
    from sglang.srt.entrypoints.anthropic import utils as anthropic_utils
    from sglang.srt.entrypoints.anthropic.protocol import AnthropicMessagesRequest, is_server_tool
except ImportError:
    anthropic_utils = None
    AnthropicMessagesRequest = None
    is_server_tool = None
​
from miles.rollout.session.core import JSON_MEDIA_TYPE, _render_json
​
​
def anthropic_adapter_available() -> bool:
    """Whether the optional SGLang Anthropic helpers this adapter needs exist."""
    return anthropic_utils is not None and AnthropicMessagesRequest is not None
​
​
# ... ( 后续函数定义 )

miles/rollout/session/sessions.py

关键集成点：保护了对 SGLang Anthropic serving 模块的导入，并在 /v1/messages 路由入口添加了守卫检查，实现了故障隔离。

    # 可选依赖：SGLang 的 Anthropic serving 和转换函数。
    try:
        from sglang.srt.entrypoints.anthropic import utils as anthropic_utils
        from sglang.srt.entrypoints.anthropic.serving import convert_response, convert_to_chat_completion_request
    except ImportError:
        anthropic_utils = None
        convert_response = None
        convert_to_chat_completion_request = None
​
    # ... ( 其他导入 )
    from miles.rollout.session.anthropic_adapter import _validate_anthropic_features, anthropic_adapter_available
​
    # ... ( 路由设置函数 )
​
    @app.post("/sessions/{session_id}/v1/messages")
    async def anthropic_messages(request: Request, session_id: str):
        """Serve Anthropic Messages through the OpenAI session path."""
        # 守卫检查：所有必需的 SGLang Anthropic 辅助模块是否可用。
        if (
            anthropic_utils is None
            or convert_response is None
            or convert_to_chat_completion_request is None
            or not anthropic_adapter_available()
        ):
            # 依赖缺失时，直接返回 Anthropic 风格的 501 错误。
            # 注意：不能调用依赖缺失的 _anthropic_error_response，因此直接构造 JSON 信封。
            return JSONResponse(
                status_code=501,
                content={
                    "type": "error",
                    "error": {
                        "type": "api_error",
                        "message": "The installed SGLang does not support the Anthropic Messages adapter",
                    },
                },
            )
        body = await request.body()
        # ... ( 后续正常处理逻辑 )

评论区精华

Review 评论由 claude[bot] 在第一版提交中提出两个关键问题：

1. 错误响应格式不一致：第一版 501 响应返回了裸的 {"error": "..."} 格式，而该路由上所有其他错误路径都通过 _anthropic_error_response 返回 Anthropic 标准的 {"type": "error", "error": {"type": ..., "message": ...}} 信封。评论指出这破坏了路由的协议一致性。
2. 导入保护不完整：anthropic_adapter.py 中对 protocol 模块的导入未被 try/except 包裹，导致当整个 sglang.srt.entrypoints.anthropic 包缺失时，sessions.py 的导入仍会失败，与 PR 的修复目标相悖。

决策与结论：作者在第二个 commit (982e221) 中完全采纳了这两条建议，修复了上述两个问题，随后获得 guapisolo 的批准。这表明团队重视 API 合同的完整性和修复的彻底性。

• 501 错误响应格式一致性 (correctness): 作者在后续提交中修复，将 501 响应改为返回完整的 Anthropic 风格错误信封。
• 导入保护范围不完整 (correctness): 作者在后续提交中修复，将 protocol 模块的导入也纳入 try/except 保护范围，并通过 anthropic_adapter_available() 函数统一检查。

风险与影响

• 风险：风险较低。主要风险点在于对可选依赖的导入保护逻辑需要仔细验证，确保在所有缺失模块的组合下，系统行为符合预期。测试覆盖了单个子模块缺失和整个 Anthropic 包缺失的情况，降低了遗漏风险。501 响应被硬编码为 JSON 格式，而非调用可能依赖缺失的 _anthropic_error_response 函数，这是一个正确的设计权衡。
• 影响：影响范围有限且正面。用户影响：使用仅配置了 OpenAI 兼容接口的 SGLang 部署的用户，其 Miles 会话服务器将不再因此崩溃，提升了部署灵活性。尝试调用 Anthropic Messages API 的用户会收到清晰的 501 错误，而非服务器启动失败。系统影响：提升了 miles.rollout.session 模块的健壮性。团队影响：提供了一个处理可选依赖的标准模式（try/except + 运行时检查），可被其他模块参考。
• 风险标记：可选依赖容错, 路由守卫边界

关联脉络

• PR #1999 Implement a worker spec for the session server: 同属 miles.rollout.session 模块的演进，前者建立了会话服务器的启动规范，而本 PR 处理了该服务器对外部可选依赖的容错性，共同增强了会话服务的健壮性和部署灵活性。
• PR #1992 Resolve the sglang config at construction time instead of mid-run: 同属提升系统健壮性的重构。该 PR 将配置解析提前，确保启动时配置完整；本 PR 将可选依赖的检测前置到路由入口，确保运行时能力可用。两者都旨在通过前置检查来避免运行时失败。