LiteLLM python-bridge 解析：Rust 核心与 Python SDK 之间“薄桥”的职责边界、错误契约与测试纪律

在 LiteLLM 的 Rust 核心改造中，litellm-rust/crates/python-bridge 是 Python 与 Rust 之间的 PyO3 边界层。本文围绕该 crate 的开发规则文档 CLAUDE.md 展开，结合 python-bridge 源码、python-interop crate 与 Python 侧 rust_bridge 适配层，完整还原这条“薄桥”的设计原则：每路由一个稳定入口、错误按“是否已触达 Provider”分类、GIL 与序列化下沉到互操作层，以及“bridge 禁用 / 启用 / 模块缺失”三态的测试要求。读完后你可以理解 LiteLLM 如何在渐进式（rollout）地把路由迁移到 Rust 的同时保证随时可回退。

1. 定位：一个刻意保持“薄”的 PyO3 边界 crate

规则文档首先明确了 python-bridge 的职责边界：

python-bridge is the PyO3 boundary between Python LiteLLM and Rust transforms. Keep this crate thin. It exposes LiteLLM Rust APIs, assembles domain requests, maps domain errors to Python exceptions, and delegates generic conversion and GIL handling to litellm-python-interop.

同目录的 AGENTS.md 用一句话概括了同样的约束：“Keep it thin: no business logic, no transforms, no I/O orchestration — just marshal in/out and call the core entrypoint.”（保持薄：无业务逻辑、无 transform、无 I/O 编排——只做出入参转换并调用 core 入口）。

从源码结构看，这一约束是真实落地的。lib.rs 中 crate 只包含 5 个模块：

模块	职责
routes	各路由（ocr、transcription、messages、chat_completions）的 PyO3 入口
errors	把 litellm_core::error::Error 映射为 Python 异常
execution	run_sync / run_async 两个执行器，处理 GIL 与运行时边界
marshal	Python dict → RouteOptions 等通用入参转换
function_trace	仅 trace-parity feature 开启时编译的诊断命名空间

模块入口 _native 使用 #[pymodule(gil_used = false)] 声明（lib.rs#L65-L76），即模块导入本身不持 GIL，注册顺序固定为：异常类型 → 路由函数 → ResponsesWebSocketConnection 类 → 诊断项。通用的 Python/Serde 互转（Pythonized、from_py）和 GIL 原语（release_gil、panic_to_pyerr）则放在独立的 python-interop crate 中，与规则文档“delegates generic conversion and GIL handling to litellm-python-interop”一一对应。

2. Bridge Shape：一条路由一个稳定方法，禁止按 Provider 散列导出

规则文档的“Bridge Shape”一节给出了四条硬性约束，每一条都能在源码中找到对应证据。

2.1 一个路由一个方法，由 bridge_route! 宏统一生成

规则要求“Prefer one stable method per top-level LiteLLM route, for example messages(...)”，并且“Do not add one exported PyO3 function per provider helper unless there is a measured reason”。

实现上，每条路由由 routes/definition.rs 中的 bridge_route! 宏一次性生成三样东西：同步函数（$sync_name）、异步函数（$async_name，即 a 前缀版本）和 register 注册函数。以 Messages 路由为例（routes/messages.rs）：

bridge_route! {
    sync = messages,
    asynchronous = amessages,
    inputs = MessagesInputs,
    required = {
        model: String,
        #[pyo3(from_py_with = litellm_python_interop::from_py)]
        body: serde_json::Value,
    },
    optional = {
        api_key: Option<String>,
        api_base: Option<String>,
        custom_llm_provider: Option<String>,
        #[pyo3(from_py_with = litellm_python_interop::from_py)]
        extra_headers: Option<serde_json::Value>,
        timeout_seconds: Option<f64>,
    },
    prepare = prepare_messages,
    errors = core_error_to_pyerr,
}

prepare 闭包负责把 Python 入参组装成 litellm_core 的领域请求，随后交给 execution 中的同步/异步执行器；errors 指定该路由的错误映射函数。宏生成的 add_function 还会拒绝重复注册同名 Python 函数（definition.rs#L128-L139），防止路由名冲突悄然覆盖既有接口。

当前 crate 暴露的完整公开面被 lib.rs 中的模块注册测试 精确钉死：RustBridgeDeclined、RustUpstreamError、ocr/aocr、transcription/atranscription、messages/amessages、chat_completions_decline、chat_completions/achat_completions、ResponsesWebSocketConnection 与 gil_stats。测试逐项断言公开符号列表相等——新增任何导出都必须显式修改该测试，这正是“防止按 provider helper 散列导出”约束的机械执行方式。

各路由的 Python 侧签名也由测试锁定（definition.rs 测试）：

路由	签名（同步/异步一致）
ocr / aocr	(model, document, api_key=None, api_base=None, custom_llm_provider=None, extra_headers=None, optional_params=None, timeout_seconds=None)
transcription / atranscription	(model, audio, api_key=None, ...) 同上其余参数
messages / amessages	(model, body, api_key=None, api_base=None, custom_llm_provider=None, extra_headers=None, timeout_seconds=None)
chat_completions / achat_completions	(model, messages, optional_params=None, api_key=None, api_base=None, custom_llm_provider=None, extra_headers=None, timeout_seconds=None)

2.2 Provider 分发属于 litellm-core，不属于 PyO3 crate

规则明确：“Provider dispatch belongs in the litellm-core route module (e.g. litellm_core::messages), not in this PyO3 crate。”以 Messages 路由为例，prepare_messages 只是校验 body 是 dict、把入参打包进 RouteOptions，真正的分发调用是 litellm_core::messages::messages（messages.rs#L24-L44）——bridge 里看不到任何 if provider == "anthropic" 之类的分支。

入参组装集中在 marshal.rs，其 RouteOptions 结构体即 Python 与 Rust 之间的“路由参数契约”：model（必填）、api_key、api_base、custom_llm_provider、extra_headers、timeout_seconds。其中两处防御性处理值得注意：

• extra_headers 必须是 dict 且值必须全为字符串，否则抛 ValueError: header values must be strings（marshal.rs#L87-L104）；
• timeout_seconds 只有满足“有限且 > 0”才转换为 Duration，NaN/负值/无穷大一律视为未设置（marshal.rs#L77-L85）。

测试进一步要求校验顺序确定：按参数声明从左到右报错（先 messages 再 optional_params 再 extra_headers），见 definition.rs 的 route_input_validation_preserves_left_to_right_order 测试。这意味着 Rust 路径的报错信息可以稳定地与 Python 旧路径对齐，是 rollout 期间排查问题的基础。

2.3 Python 拥有 rollout 状态与回退，Rust 只负责“返回错误”

规则文档的核心条款是：“Python owns rollout state and fallback. Rust should return errors; Python decides whether to raise or fall back.”并且要求 Python 侧接口保持极简（“well under 100 lines per route”），只做两件事——marshal 入参、调用 Rust。

Python 侧的对应物是 litellm/rust_bridge/ 包。加载器 loader.py 用一个哨兵值缓存 _native 扩展模块的导入结果：导入成功则缓存模块，ImportError 则缓存 None，后续查询零成本。bindings.py 中的 NativeBinding 再包一层“可重置的测试 override”——测试可以 override(None) 模拟模块缺失、reset() 恢复真实状态，这正是 CLAUDE.md 测试要求中“module-missing fallback behavior”可被可靠测试的前提。

对于“已有 Python 参考实现”的路由（如 chat completions），回退语义实现在 chat_completions.py：_reraise_or_decline 区分两种 Rust 异常——

• 命中 RustBridgeDeclined：请求尚未触达 Provider，回退到 Python 路径（打 debug 日志后返回，由调用方走原实现）；
• 命中 RustUpstreamError：Provider 已处理过该请求，不能再回退（否则二次计费），转成携带上游 status 的 APIError（status_code=int(status) or 500）向上抛出。

规则文档同时定义了另一种情形：“For a rust-only provider/route (no Python reference), the Python side is a thin dispatch that calls Rust and raises when the bridge is unavailable, with no fallback.”——纯 Rust 路由没有 Python 参考实现，Python 侧只是一层薄分发，bridge 不可用时直接抛错，不做回退。两条路径（有参考实现 → 可回退；无参考实现 → 薄分发无回退）共同构成了 LiteLLM 渐进式 Rust 化的 rollout 策略。

3. 错误契约：Rust 错误如何变成 Python 异常

errors.rs 用 pyo3::create_exception! 定义了两个 bridge 专属异常，其文档字符串本身就是契约：

• RustBridgeDeclined：“The route declined before calling the provider, so the host may retry on its own path.”（路由在调用 Provider 前被拒绝，宿主可以在自己的路径上重试。）
• RustUpstreamError：“The provider call was already issued and failed. Args are (status, message); status is 0 when there was no HTTP response.”（Provider 调用已发出且失败；参数为 (status, message)，无 HTTP 响应时 status 为 0。）

通用映射 core_error_to_pyerr（errors.rs#L19-L28）保持简单：Auth/InvalidProvider/InvalidRequest/InvalidType/MissingField → ValueError，其余 → RuntimeError。而 chat completions 路由使用专门的 chat_completions_error_to_pyerr（errors.rs#L36-L55），把“请求是否已离开本机”作为分界线：

Rust 错误	是否已触达 Provider	映射结果
Unsupported / Auth / InvalidProvider / InvalidRequest / InvalidType / MissingField / Routing / Connect	否	RustBridgeDeclined（宿主可安全回退 Python 路径）
Http { status, body }	是	RustUpstreamError((status, "{status}: {body}"))
Network / InvalidResponse	是（无 HTTP 状态码）	RustUpstreamError((0, message))

源码注释直接给出了动机：“anything after it is not [safe to retry], because the provider has already done the work and billed for it”——这与 2.3 节 Python 侧 _reraise_or_decline 的双分支处理是同一份契约的两端。OCR 路由还有 ocr_error_to_pyerr（errors.rs#L63-L71），把 MissingField("document_url" | "image_url") 归一为面向用户的 "Document URL is required"，其单测（errors.rs#L73-L99）验证 429 场景下 (429, body) 元组原样保留给 Python 侧。

4. 执行器：GIL 释放、信号处理与 panic 边界

“delegate GIL handling to litellm-python-interop”在 execution.rs 中体现为对 release_gil 的调用。同步路径 run_sync_on（execution.rs#L31-L50）有三个关键行为，均有对应测试佐证：

1. 拒绝嵌套 Tokio 上下文：若当前已在 Tokio 运行时内（Handle::try_current().is_ok()），直接报 RuntimeError: synchronous native routes cannot run from a Tokio context; use the async route，避免 block_on 嵌套运行时死锁；
2. 等待期间释放 GIL：release_gil(py, || runtime.block_on(...))，测试 sync_runner_releases_gil_while_waiting 验证了等待中其他 Python 线程可以正常获取 GIL；
3. 轮询 Python 信号：wait_for_sync_result（execution.rs#L88-L105）以 50ms 间隔调用 py.check_signals()，保证同步阻塞调用能被 Ctrl-C 打断，且用 MissedTickBehavior::Delay 避免追赶式补发。

异步路径 run_async 通过 pyo3_async_runtimes::tokio::future_into_py 把 Rust future 直接交给 Python 事件循环。两条路径都把 Rust panic 收敛为 PanicException：future 侧用 catch_unwind 包裹（catch_future_panic），错误映射器侧用 catch_unwind(AssertUnwindSafe(...)) 包裹，测试 execution.rs#L272-L314 分别验证了 future panic、mapper panic 和序列化器 panic 三种情形都会变成 Python 异常而非进程崩溃。

5. 数据处理的三条安全红线

CLAUDE.md 的“Data Handling”一节针对 OCR/音频这类大 payload 路由提出三条约束，源码中的印证如下：

• 不落日志：“OCR payloads can contain personal data and large base64 images. Do not log payloads or provider responses.”这与仓库顶层 AGENTS.md 的通用日志纪律一致；
• 控制拷贝次数：当前实现是 JSON 往返（Python dict → serde_json::Value → Rust 结构），文档明确承认这是“acceptable for the first scaffold”，并要求“future performance work should evaluate direct PyO3 conversion before expanding Rust coverage to image-heavy paths”。也就是说，在把 Rust 覆盖面扩大到更多图像类路由之前，必须先评估用 Pythonized 直接转换替代 JSON round-trip；
• 错误不泄内容：“Do not expose raw Rust errors that include document contents or upstream bodies。”ocr_error_to_pyerr 对字段缺失只输出固定文案 "Document URL is required" 而不回显输入，Http 错误体也只按 (status, body) 元组结构化传递，由宿主决定呈现粒度。

6. 测试纪律：cargo test --workspace 与三态 Python 测试

规则文档的“Tests”一节是验收标准：

1. cargo test --workspace must compile this crate——PyO3 crate 的编译本身就是契约的一部分（Python 解释器、链接、feature 组合）；
2. Python tests must cover bridge disabled, bridge enabled, and module-missing fallback behavior for every exposed route——每条暴露的路由都必须有“bridge 禁用 / bridge 启用 / 原生模块缺失时回退”三态覆盖。

这两条要求对应的测试设施都已存在于仓库：Rust 侧的 tests/marshal_boundary.rs 与 lib.rs、errors.rs、execution.rs、definition.rs 内嵌的集成测试（其中大量测试通过 py.run 执行真实 Python 代码验证异常类型、asyncio 取消语义、__text_signature__ 签名）；Python 侧则依靠 bindings.py 的 NativeBinding.override/reset 机制模拟“模块缺失”，跨语言行为回归集中在 tests/rust-python-harness/ 目录下维护。module_registration_preserves_the_public_surface 这类“公开面快照”测试，加上 lib.rs#L158-L220 中 ResponsesWebSocketConnection 的 WebSocket 端到端往返测试（connect → send_text → recv_text → close，全程经 Python 调用），共同保证了这条薄桥的接口演进是显式、可审查的。

7. 小结：一份可直接执行的“薄桥”检查清单

把 CLAUDE.md 的规则与源码证据合并，向 python-bridge 增加一条路由时应当满足：

1. 用 bridge_route! 生成成对的 sync/async 方法（a 前缀），prepare 只做请求组装，分发调用落在 litellm-core 对应路由模块；
2. 入参校验复用 marshal.rs 的 required_value/optional_object/marshal_headers/optional_timeout，保持左到右的报错顺序；
3. 错误映射区分“未触达 Provider（可回退）”与“已触达 Provider（必须上抛）”；若宿主 Python 路径已存在，回退决策放在 litellm/rust_bridge/ 或 litellm/llms/<provider>/<route>/ 的薄分发类中，且不超过百行；
4. 更新 lib.rs 的公开面快照测试与签名测试；为 bridge disabled / enabled / module-missing 三态补齐 Python 测试；
5. 不记录 payload 与上游响应，不在错误中回显文档内容；
6. 确保 cargo test --workspace 通过。

这套规则的实质，是把“Rust 化”做成可随时拨回的灰度：Rust 只承诺“要么没调用 Provider（可重试），要么如实上报上游失败（不可重试）”，而是否回退、如何计费、何时全量，全部由 Python 侧在可见的测试边界内决定。