【Bug已解决】Related to #31887 (custom header pattern support) 解决方案一、现象长什么样在用 LangChain 的某些聊天模型/LLM 客户端这一支与 issue #31887 关联对接需要自定义请求头的模型服务时发现客户端不允许注入自定义 header或者只允许极少数写死的 header导致# 想给请求加一个自定义鉴权/路由 header但客户端不支持 chat_model ChatX(api_key..., extra_headers{X-Custom-Route: eu}) # 实际发出的 HTTP 请求里没有 X-Custom-Route - 服务端拒绝/走错区 # 或 E LangChain: ChatX does not accept arbitrary custom headers具体表现部分模型服务商要求特定自定义头比如按 header 做区域路由、按 header 传租户 ID、或某种非标准的 API key 位置LangChain 客户端不支持调用直接失败或行为不对。客户端要么硬编码了固定的一组 header如只放行Authorization要么完全不暴露extra_headers参数。想用“header 模式pattern”批量匹配并注入一类头例如所有X-*头也不行只能一个个改源码。与 #31887 关联该 issue 讨论的就是“支持自定义 header pattern”即让用户声明一个模式/前缀客户端在拼请求时把匹配的自定义头带上去。关键特征LLM 客户端对请求头是“白名单/写死”的用户无法按服务端要求注入自定义 header对接非标准鉴权/路由的 provider 时受阻。二、背景LangChain 的聊天模型客户端在发起 HTTP 请求调用模型 API 时会构造一组请求头通常包括Authorization、Content-Type等标准头。但现实中的模型服务商五花八门有的用Authorization: Bearer标准鉴权有的要求把 key 放在自定义头X-Api-Key有的用 header 做区域/租户路由X-Region: eu、X-Tenant: abc有的要求带某种trace / session头用于审计。如果一个客户端把 header 写死或只允许Authorization用户就没法把这些必要的自定义头带上于是服务端要么拒绝401/403要么因为缺路由头走到了错误的部署。issue #31887 提出的“custom header pattern support”意思是客户端应支持用户声明一个header 模式pattern——比如“允许所有X-开头的头”或“允许X-Custom-*并按正则匹配”客户端在组装请求时把用户提供的、符合模式的自定义头原样注入。这样既能灵活对接各种 provider又不会无脑地把任意头都放出去避免误带敏感头。三、根因根因是LLM 客户端对请求头的处理是“硬编码白名单/不暴露扩展点”没有支持用户按模式声明并注入自定义 headerheader 写死客户端请求构造里只设了Authorization/Content-Type等固定头没有extra_headers参数也没有“把用户给的头合并进去”的逻辑。无 pattern 机制即使有extra_headers也不支持“按模式批量放行”比如X-*用户得逐个指定碰到一组相关头就很麻烦。合并缺失请求最终组装时用户提供的自定义头没有被合并进requests/httpx的 headers导致发不出去。与 #31887 脱节该 issue 明确要“custom header pattern”但实现没跟上于是需要自定义头的 provider 全卡住。一句话客户端请求头是封闭的用户无法按模式注入自定义 header对接非标准鉴权/路由的模型服务时请求缺失关键头调用失败。四、最小可运行复现下面用 Python 模拟“请求头合并 模式过滤”的机理复现“不支持自定义头”vs“支持 pattern”from typing import Dict def build_headers_buggy(base: Dict, user_headers: Dict) - Dict: 错误只用固定头忽略用户自定义头。 out dict(base) # {Authorization: ..., Content-Type: ...} # 用户头被完全丢弃 return out def build_headers_fixed(base: Dict, user_headers: Dict, patternNone) - Dict: 修复合并用户头并按 pattern如 X- 前缀过滤放行。 out dict(base) for k, v in user_headers.items(): if pattern is None or k.startswith(pattern): out[k] v return out base {Authorization: Bearer xxx, Content-Type: application/json} user {X-Custom-Route: eu, X-Tenant: abc, Bad-Header: secret} print(buggy:, build_headers_buggy(base, user)) # {Authorization:..., Content-Type:...} - 自定义头丢失 print(fixed:, build_headers_fixed(base, user, patternX-)) # 含 X-Custom-Route、X-Tenant且可按 pattern 控制范围buggy把用户自定义头丢得一干二净fixed按X-模式合并进去——正是 #31887 要的“custom header pattern support”。五、解决方案第一层最小直接修复最小修复是在 LLM 客户端暴露extra_headers参数并在组装请求时按声明的 pattern 合并用户自定义头# chat_client.py修复片段 class ChatX(BaseChatModel): def __init__(self, api_key: str, extra_headers: Dict[str, str] | None None, header_pattern: str | None X-, **kwargs): self.api_key api_key self.extra_headers extra_headers or {} self.header_pattern header_pattern def _build_headers(self) - Dict[str, str]: headers { Authorization: fBearer {self.api_key}, Content-Type: application/json, } # 按 pattern 合并用户自定义头 for k, v in self.extra_headers.items(): if self.header_pattern is None or k.startswith(self.header_pattern): headers[k] v return headers这一层让需要自定义头的 provider区域路由、租户 ID、非标准 key 位置能正常对接X-*类头按 pattern 被带上去。六、解决方案第二层结构性改进把“LLM 客户端如何合并/放行自定义请求头”收口成唯一的配置对象LangChainHeaderPatternPolicy所有客户端读它from dataclasses import dataclass from typing import Tuple, Optional dataclass(frozenTrue) class LangChainHeaderPatternPolicy: LLM 客户端自定义请求头模式的单一事实来源。 # 客户端必须暴露 extra_headers 扩展点 support_extra_headers: bool True # 按模式放行如 X- 前缀而不是全放或全禁 pattern_based_allow: bool True # 默认放行前缀可按 provider 调整 default_pattern: Optional[str] X- # 禁止硬编码吞掉用户头 forbid_drop_user_headers: bool True # 代码评审卡点 forbidden_patterns: Tuple[str, ...] ( headers {Authorization, Content-Type} ignore user, no extra_headers param, ) def merge(self, base: dict, user: dict) - dict: out dict(base) for k, v in user.items(): if self.pattern_based_allow: if self.default_pattern and k.startswith(self.default_pattern): out[k] v else: out[k] v return out def describe(self) - str: return 客户端暴露 extra_headers按模式放行自定义请求头 POLICY LangChainHeaderPatternPolicy() def plan_headers(base: dict, user: dict, policy: LangChainHeaderPatternPolicy POLICY) - dict: return policy.merge(base, user)所有 LangChain LLM 客户端都读POLICY自定义头的合并与放行被固化对接各种 provider 不再卡在 header 上。七、解决方案第三层断言 / CI 守护把“支持 extra_headers、按模式放行、不丢弃”做成断言。下面用 pytest 守护import pytest def test_support_extra_headers(policy): assert policy.support_extra_headers is True assert no extra_headers param in policy.forbidden_patterns def test_pattern_allow(policy): assert policy.pattern_based_allow is True out policy.merge({Authorization: x}, {X-Route: eu, Y-Bad: z}) assert out.get(X-Route) eu assert Y-Bad not in out # 不符合模式不放行 def test_no_drop_user_headers(policy): assert policy.forbid_drop_user_headers is True assert (headers {Authorization, Content-Type} ignore user in policy.forbidden_patterns) def test_base_headers_kept(policy): out policy.merge({Authorization: x}, {X-Tenant: abc}) assert out[Authorization] x # 基础头保留 def test_none_pattern_allows_all(policy): p LangChainHeaderPatternPolicy(pattern_based_allowFalse, default_patternNone) out p.merge({Authorization: x}, {Any-Header: v}) assert out.get(Any-Header) v这五组断言锁住(1) 支持 extra_headers(2) 按模式放行(3) 不丢弃(4) 基础头保留(5) 关闭模式时全放行。CI 跑通即代表自定义头支持不会再缺失。八、排查清单遇到 LLM 客户端无法注入自定义 header看是不是 header 写死请求里没有你设的自定义头 → 客户端没合并本题关联 #31887。确认 provider 需求是否服务端要求X-*路由/租户/非标准 key 头。查客户端有没有extra_headers参数组装请求时有没有合并用户头。加 pattern 支持暴露extra_headers按X-等模式放行并合并。统一到LangChainHeaderPatternPolicyCI 断言禁止吞掉用户头。安全边界用 pattern 限制放行范围避免无脑带所有头。端到端发出的 HTTP 请求里确实带上了自定义头provider 调用成功。九、小结Related to #31887 (custom header pattern support)的根因是LangChain 的 LLM 客户端在组装模型 API 的 HTTP 请求时把请求头写死成固定白名单只Authorization/Content-Type既不暴露extra_headers扩展点也不支持“按模式批量放行自定义头”导致需要自定义头区域路由、租户 ID、非标准鉴权位置的模型服务收不到关键头调用失败或被路由错——这正是 issue #31887 要解决的“custom header pattern support”。最小修复是暴露extra_headers并在组装请求时按声明的 pattern如X-前缀合并用户自定义头结构性改进是用唯一的LangChainHeaderPatternPolicy固化头的合并与放行CI 用五组断言守护“支持 extra_headers、按模式放行、不丢弃用户头”。记住LLM 客户端面对的 provider 千差万别请求头必须是可扩展的用 pattern 放行既灵活又不失控。