LiteLLM Pass-Through Endpoint Guardrail Translation 源码解析与配置实战：让任意上游 API 也走统一护栏流水线-北京尧图网络

LiteLLM Pass-Through Endpoint Guardrail Translation 源码解析与配置实战让任意上游 API 也走统一护栏流水线【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellmLiteLLM Proxy 的「透传端点Pass-Through Endpoint」允许把一个自定义路径原样转发到任意上游 API例如 Cohere/v1/rerank此时请求不再经过 chat/completion 这类标准 LLM 路由护栏Guardrail默认不会生效。本文以仓库中 guardrail_translation/README.md 为骨架结合litellm/llms/下的翻译层实现与 litellm/proxy/pass_through_endpoints 的主流程代码讲解 LiteLLM 如何通过「护栏翻译映射Guardrail Translation Mapping」机制把透传端点的请求/响应纳入统一护栏流水线——包括 JSONPath 字段定向提取、全载荷兜底、双层 handler 分发与 YAML 配置实战。一、这套机制要解决的问题透传端点本质上是一个「透明代理」客户端请求/v1/rerankProxy 把它 1:1 转发给目标上游并原样回传响应。与标准 LLM 请求不同这类端点没有messages、model等 OpenAI 规范字段护栏框架无法复用「从 messages 提取文本」的通用逻辑请求/响应结构完全由上游 API 决定可能是{query: ...}、{documents: [...]}、{results: [...]}等任意形态仍然存在内容安全、敏感信息泄露等风险用户希望护栏在这里同样生效。解决思路在模块 docstring 中写得很清楚见 litellm/llms/pass_through/init.py以配置文件里声明的字段表达式为指引从请求/响应里定向取出需要检查的文本再交给统一的护栏实例执行且透传场景下护栏只做「检查check」而不改写请求文本。二、模块为什么放在litellm/llms/而不是主透传代码里README 首先解释了目录归属问题该模块位于 litellm/llms/pass_through/guardrail_translation/而不是与主透传实现放在一起原因有二自动发现Auto-discoverylitellm/llms/__init__.py中的load_guardrail_translation_mappings()会递归扫描litellm/llms/下所有名为guardrail_translation且含__init__.py的目录把其中导出的guardrail_translation_mappings字典聚合注册一致性Consistency其他 provider 的护栏翻译 handler 都遵循同一目录模式README 举例为openai/chat/guardrail_translation/、anthropic/chat/guardrail_translation/透传端点也照此办理便于统一发现与加载。对应源码位于 litellm/llms/init.py其中核心是三个函数discover_guardrail_translation_mappings()遍历litellm/llms/目录树凡os.path.basename(root) guardrail_translation且有__init__.py的模块都会被导入若模块含guardrail_translation_mappings属性则并入结果集随后还会额外并入 MCP Server 相关映射litellm/llms/init.pyload_guardrail_translation_mappings()带缓存的入口首次调用触发全量发现结果存入全局endpoint_guardrail_translation_mappingsget_guardrail_translation_mapping(call_type)按CallTypes取映射若不存在会抛出异常并列出可用映射清单方便排查「为什么某个透传类型没有护栏翻译 handler」。三、本模块导出的映射注册表模块的init.py 是自动发现机制的直接消费对象它向注册表声明了两个CallTypes的映射guardrail_translation_mappings: Final { CallTypes.pass_through: PassThroughEndpointHandler, CallTypes.allm_passthrough_route: LlmPassthroughRouteHandler, }其中CallTypes.pass_through→ 通用透传端点场景由PassThroughEndpointHandler负责CallTypes.allm_passthrough_route→ LLM 透传路由场景由LlmPassthroughRouteHandler负责。allm_passthrough_route是比通用透传更接近「LLM 调用」的一种透传形态请求体里带custom_llm_provider字段因此需要按 provider 再分发。两个 handler 都继承自 litellm/llms/base_llm/guardrail_translation/base_translation.py 中的抽象基类BaseTranslation后者用abstractmethod规定了两个必须实现的方法base_translation.pyprocess_input_messages(data, guardrail_to_apply, litellm_logging_obj)护栏处理请求入站内容process_output_response(response, guardrail_to_apply, litellm_logging_obj, user_api_key_dict, request_data)护栏处理响应出站内容。换句话说任何希望接入护栏体系的端点类型本质都是实现一个「把任意结构翻译成护栏可检查的GenericGuardrailAPIInputs」的翻译器。四、PassThroughEndpointHandler核心处理逻辑该 handler 的实现集中在 handler.py模块 docstring 明确它「使用 litellm_logging_obj 上的字段定向配置提取指定字段交给护栏处理」。整体分三步1. 读取护栏设置_get_guardrail_settingsdef _get_guardrail_settings(self, litellm_logging_obj, guardrail_name): passthrough_config getattr(litellm_logging_obj, passthrough_guardrails_config, None) if not passthrough_config or not guardrail_name: return None return PassthroughGuardrailHandler.get_settings(passthrough_config, guardrail_name)关键点透传护栏的字段定向配置并不是临时从 YAML 现取的而是由透传主流程在请求进入时把它存到litellm_logging_obj.passthrough_guardrails_config属性上见后文数据流handler 侧通过getattr取回再按护栏名查设置。这就把「配置解析」与「护栏执行」解耦成两个阶段。2. 字段定向或全载荷兜底_extract_text_for_guardraildef _extract_text_for_guardrail(self, data, field_expressions): if field_expressions: text JsonPathExtractor.extract_fields( datadata, jsonpath_expressionsfield_expressions, ) return text # 未配置字段表达式 → 整包检查剔除内部字段 payload_to_check { k: v for k, v in data.items() if not k.startswith(_) and k not in (metadata, litellm_logging_obj) } return safe_dumps(payload_to_check)这里体现了 README 强调的两条设计字段定向Field Targeting若配置了request_fields/response_fieldsJSONPath 表达式列表仅提取命中的字段拼成检查文本降低护栏扫描成本与误报率全载荷兜底Full Payload Fallback若未配置就把整包 JSON 作为检查文本但会剔除三类内部字段——下划线开头的键、metadata、litellm_logging_obj避免把代理自身的审计元数据塞给护栏序列化走 safe_json_dumps保证异常值不会炸掉序列化。3. 组装输入并执行护栏仅检查、不改写process_input_messages与process_output_response的落点一致把提取出的文本包装为GenericGuardrailAPIInputs(texts[text_to_check])若载荷含model字段则一并带上然后调用guardrail_to_apply.apply_guardrail(inputs..., input_typerequest/response, ...)handler.py。三个值得注意的实现细节纯检查语义透传 handler 拿到_guardrailed_inputs后并不用它回填/改写原始data而是原样return data/return response——护栏在这里负责「拦截放行」文本改写由各 provider 自己的翻译器完成响应必须可解析process_output_response开头就检查isinstance(response, dict)非字典响应如流式 chunk、二进制直接跳过handler.py空文本短路提取结果为空时直接跳过护栏No text to check, skipping guardrail避免护栏空跑。响应处理还额外做了上下文补全当request_data为空SDK / 直接调用路径时自建{response: ...}字典并把user_api_key_dict通过基类transform_user_api_key_dict_to_metadata转成user_api_key_前缀键写入litellm_metadata让护栏回调里能拿到密钥/团队身份信息。五、主透传实现litellm/proxy/pass_through_endpoints/README 指出主透传端点实现并不在本模块而在litellm/proxy/pass_through_endpoints/ ├── pass_through_endpoints.py # 核心透传路由逻辑 ├── passthrough_guardrails.py # 护栏收集与字段定向 ├── jsonpath_extractor.py # JSONPath 字段提取工具 └── ...目录下还有streaming_handler.py、success_handler.py、passthrough_endpoint_router.py等共同构成透传子系统。三个与护栏翻译层关系最密切的文件如下。1.passthrough_guardrails.py护栏收集与执行助手PassthroughGuardrailHandler是透传护栏的「总调度」负责四件事passthrough_guardrails.pynormalize_config把配置归一为字典。支持两种写法——简单列表[g1, g2]会被转成{g1: None, g2: None}带设置的字典原样保留is_enabled/get_guardrail_names判空、取名单。模块 docstring 强调透传是opt-in 模型——只有显式配置至少一个护栏才执行绝不隐式启用collect_guardrails在透传启用后合并「端点自己声明的护栏」与「继承自 org/team/key 元数据的护栏」。后者通过_add_guardrails_from_key_or_team_metadata从user_api_key_dict.metadata/team_metadata中提取并去重合并实现「组织/团队/密钥级护栏自动继承」execute主入口把护栏名写成request_data[metadata][guardrails] {name: True}并通过set_passthrough_guardrails_config写入请求级上下文供后续阶段查询上下文读写由 litellm/proxy/pass_through_endpoints/passthrough_context.py 提供。2.jsonpath_extractor.py轻量 JSONPath 引擎字段定向依赖JsonPathExtractor它不引入外部 JSONPath 依赖而是实现了一个极简、够用的子集jsonpath_extractor.py简单键query→data[query]嵌套键foo.bar→data[foo][bar]点号逐层取数组通配documents[*].text/items[*]→ 遍历数组每项递归求值结果扁平合并多点路径表达式列表逐一求值最终所有命中值用换行\n连接成一个字符串。解析实现先把[*]归一为.[*]再按.切分遇到[*]段时判断当前节点是 list取出剩余路径对每个元素递归evaluatejsonpath_extractor.py。单字段求值失败只打 debug 日志、不影响其余字段因此对上游形态变化有不错的容错性。3.pass_through_endpoints.py把护栏挂进透传请求生命周期主路由文件中可看到护栏配置从入参到执行的全过程端点配置里guardrails字段与path、target、headers并列PassThroughGenericEndpoint模型见 litellm/proxy/_types.pyforward_request接收guardrails_config: dict | None进入请求处理时调用PassthroughGuardrailHandler.collect_guardrails(...)把guardrails_to_run写入_parsed_body[metadata][guardrails]随即「初始化 LOGGING OBJECT」并把logging_obj.passthrough_guardrails_config guardrails_config存到日志对象上——这正是第四节PassThroughEndpointHandler._get_guardrail_settings反查配置的数据来源响应侧在response.status_code 400且响应体可 JSON 解析、且存在待运行护栏时重新挂载guardrails见 pass_through_endpoints.py保证 post-call 护栏能看到它们随后才把响应交还客户端。于是整条调用链闭合为请求进入 → collect_guardrails(合并端点org/team/key护栏) → metadata.guardrails 写入 set_passthrough_guardrails_config → logging_obj.passthrough_guardrails_config 缓存 → PassThroughEndpointHandler.process_input_messages → _get_guardrail_settings 反查 request_fields/response_fields → JsonPathExtractor 定向提取 / 全载荷兜底 → apply_guardrail(检查拦截) → 原样放行或抛 HTTPException 阻断六、YAML 配置实战与参数详解README 给出了最小可运行配置这里原样保留并做必要标注passthrough_endpoints: - path: /v1/rerank target: https://api.cohere.com/v1/rerank guardrails: bedrock-pre-guard: request_fields: [query, documents[*].text] response_fields: [results[*].text]逐项拆解path注册到 LiteLLM Proxy 上的对外路由target实际转发目标这里是 Cohere rerank 服务guardrailsopt-in 的护栏声明。名字如bedrock-pre-guard必须在 Proxy 的护栏注册表里存在即配置文件中guardrails:顶层节里定义的预护栏实例透传端点本身不定义护栏只引用request_fieldsPassThroughGuardrailSettings的入站字段定向见 litellm/proxy/_types.py。接收 JSONPath 表达式列表典型值query、documents[*].text、messages[*].content不填则护栏跑整个请求载荷response_fields出站字段定向典型值results[*].text、output不填则护栏跑整个响应载荷。guardrails还支持两种等价写法。PassthroughGuardrailHandler.normalize_config会把列表格式归一为字典格式# 写法 A简单列表无字段定向整包检查 guardrails: [bedrock-pre-guard] # 写法 B字典每个护栏各自的 request_fields / response_fields guardrails: bedrock-pre-guard: request_fields: [query, documents[*].text] response_fields: [results[*].text]使用建议字段定向能显著降低护栏扫描成本并减少误报凡是明确知道敏感/待审内容落在哪个字段的场景都应优先配置数组通配[*]语法只支持到单层数组递归若上游返回嵌套更深的结构数组套数组需要评估该轻量引擎的覆盖范围jsonpath_extractor.py 的实现即唯一事实依据护栏名与字段设置一一对应意味着同一端点可为不同护栏配置不同的扫描面——例如入站文本安全护栏只扫query出站合规护栏只扫results[*].text。七、LlmPassthroughRouteHandler按 provider 二次分发通用透传之外同文件还定义了一个面向 LLM 透传路由的翻译器LlmPassthroughRouteHandlerhandler.py。它本身不做字段提取而是充当分发器内部维护_PROVIDER_HANDLERS注册表目前仅注册{bedrock: BedrockPassthroughGuardrailHandler}provider 专属翻译器位于 litellm/llms/bedrock/passthrough/guardrail_translation/handler.pyprocess_input_messages/process_output_response依据data[custom_llm_provider]响应侧从request_data取选择 provider handler找不到对应 provider 时只打 debug 日志并原样放行保证「未知 provider 不阻塞透传」额外暴露一批事件流SSE辅助静态方法is_event_stream_response、event_stream_media_type、supports_event_stream_de_anonymization、de_anonymize_event_stream等。这些方法委托给 provider handler 的对应实现用于识别并「去匿名化」事件流内容——因为流式响应需要反序列化成可检查形态后才能跑护栏检查完再还原给客户端handler.py。这从源码结构上印证了 README 提到的设计一致性每个端点/provider 形态各写一个guardrail_translationhandler统一通过CallTypes映射注册由统一框架发现和调用。八、与其他 Provider 翻译层的关系透传护栏翻译并不是孤例。README 明确指出所有护栏翻译 handler 遵循同一模式openai/chat/guardrail_translation/、anthropic/chat/guardrail_translation/等它们都继承同一个BaseTranslation抽象基类保证process_input_messages/process_output_response以及可选的流式处理钩子接口一致在各自目录的__init__.py导出guardrail_translation_mappings字典由litellm/llms/__init__.py的自动发现机制统一加载按CallTypes检索。因此接入新形态新 provider 透传、新端点类型时最需要做的是补一个翻译器并注册CallTypes映射而无需改动护栏执行框架本身——这也解释了本模块目录位置的选择是出于框架可扩展性的刻意安排参见 litellm/llms/init.py 的扫描与聚合逻辑。九、小结围绕透传端点护栏这条链路LiteLLM 实际上建立了三层清晰的分工层次位置职责配置层passthrough_endpoints[*].guardrailsYAML与 PassThroughGuardrailSettings声明护栏名、request_fields/response_fieldsJSONPath 定向执行层passthrough_guardrails.py jsonpath_extractor.pyopt-in 收集含 org/team/key 继承、字段提取、写请求元数据翻译层litellm/llms/pass_through/guardrail_translation/handler.py把透传载荷翻译成护栏输入CallTypes→ handler 注册与自动发现透传端点的护栏执行是opt-in、字段可定向、默认全载荷兜底的行为模型不配置就完全不干预转发配置了就在 pre-call 与 post-call 两处对目标字段做纯检查式拦截拦截失败可抛异常阻断通过则 1:1 放行上游响应。对需要「透明转发 Cohere、Bedrock 等非标准 API 又不想失去内容安全能力」的网关部署场景这套翻译机制是值得直接照搬的最小实现范式。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

LiteLLM Pass-Through Endpoint Guardrail Translation 源码解析与配置实战：让任意上游 API 也走统一护栏流水线

相关推荐

【第25期】Python 函数定义与调用详解：参数、返回值、作用域、默认参数和关键字参数

PSequel：macOS 上免费管理 PostgreSQL 的轻量 GUI 工具

MHS“硬件版MCP”解析：AI与工业控制相遇，短期难掀桌但潜力不可忽视

更多资讯

Traefik 官方 compress 中间件完全指南：Gzip / Brotli / Zstandard 响应压缩配置与源码解析

如何快速构建轻量版 Windows 11 系统：tiny11builder 完整指南

mem0-integrate 技能详解：以目标驱动、测试先行的流水线将 Mem0 集成进现有仓库

从Agent任务拆解到机器人路径规划：规划算法的通用内核与实践指南

NSGA-III工业落地实践：多目标优化算法工程化指南

LobeHub 飞书/Lark Bot 端到端测试指南：用 agent-testing-bot 在 macOS 上做真实客户端自动验收

今日更新

能源系统对接碳交易的路径：从碳核算到碳资产运营

智能硬件数据驱动运营：订单日记与预测性维护实践

逆变器下垂控制与虚拟同步机对比：Simulink仿真建模与参数整定

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？