GateLLM

外观

模板变量速查 ​

网关在多个配置处支持 {{变量}} 表达式：在请求时按当前请求上下文替换为实际值，用于把动态信息（访问密钥、请求 ID、会话头、system 提示词哈希等）注入到发往上游的 header 或请求体里，驱动上游日志关联、缓存键、粘性会话绑定等场景。

变量总表 ​

变量来源说明
{{request_access_key_name}}认证访问密钥名匹配的 AccessKey 条目中的名称；未认证时为空
{{request_access_key_group}}访问密钥分组名该密钥所属分组名（多组以逗号连接）；未认证时为空
{{request_id}}z-request-id 请求头客户端 z-request-id 头中的唯一请求 ID
{{access_key_hash}}访问密钥 SHA-256 哈希访问密钥原文 SHA-256 哈希的前 16 字节，base64url 编码（22 字符，确定性）
{{system_prompt_hash}}system 提示词 SHA-256system 提示词内容的 sha256 小写十六进制摘要，协议无关，兼容 Anthropic system、OpenAI messages[role=system]、DashScope input.messages[role=system]、Google system_instruction 四种放置方式
{{header:Key}}客户端请求头客户端 Key 请求头的值，大小写不敏感；头值前后空白视为缺失

可用范围（哪些上下文支持哪些变量） ​

并非每个变量在每个配置处都可用——取决于该处是否持有对应的请求上下文。下表标明各配置处可用的变量：

变量上游/模型 headers·user_agentrequest_payload 的 value负载均衡器 binding_key_template
{{request_access_key_name}}✅✅✅
{{request_access_key_group}}✅✅✅
{{request_id}}✅✅✅
{{access_key_hash}}✅❌（恒空）✅
{{system_prompt_hash}}✅✅❌（恒空）
{{header:Key}}✅✅✅

两个"恒空"的成因是上下文边界，不是 bug：

  • request_payload 的 value 里 access_key_hash 恒空：请求体改写阶段在协议转换之后执行，出于安全不持有访问密钥原文，算不出哈希。需要缓存键兜底时改用 system_prompt_hash。
  • binding_key_template 里 system_prompt_hash 恒空：绑定键解析发生在请求体可用的更早阶段（路由/LB 解析期），此时还没拿到请求体，无法提取 system 提示词。粘性会话的绑定键通常用 access_key_hash 或会话头。

⚠️ 在不支持某变量的上下文里写它，该变量解析为空字符串——若它落在回退链末端且链中其余变量也空，整条链空，该 header/写入被省略（绑定键则回退为原始 API key）。配置加载时模板校验为 warn-don't-block，不会锁死启动。

回退链语法 ​

{{var1|var2|var3}} 用 | 分隔多个候选变量，按顺序取第一个非空的：前一个不可用（未认证 / 头缺失 / 上下文不支持）则试下一个；全部为空则替换为空字符串。{{header:Name}} 也可作为回退链的一员。未知变量（不在总表、非 header: 前缀）在链中被跳过而非报错。

空值处理因配置处而异：

  • header / user_agent：替换值完全为空时该 header 被省略（不发送空字符串）。
  • request_payload 的 value：链全空时本次写入被省略（不创建该字段，不写空字符串常量）。
  • binding_key_template：链全空时回退为原始访问密钥作绑定键（保证每会话唯一，避免所有请求挤进同一个动态绑定会话）。模板含未解析 {{...}} 时同样回退。

典型用法 ​

会话键控的上游缓存键（header，多级回退） ​

在控制台里：打开上游或模型 → 自定义请求头 → 新增标头 X-Conversation-Id，值填 {{header:x-claude-code-session-id|access_key_hash|system_prompt_hash}}。

逐级降级：有会话头→用头（同会话同键，命中上游缓存）；无头但已认证→用 access key 哈希（同用户共享缓存）；两者皆无→用 system 哈希（同 system 提示词同键）。三者皆空时省略该 header。

上游缓存字段注入（request_payload，body 级） ​

在控制台里：打开模型详情（或上游的「默认请求体规则」）→ 请求体规则 → + 添加规则 → 模式选 overwrite → 路径填 prompt_cache_key → 值填 {{header:x-claude-code-session-id|system_prompt_hash}}。

注意此处 access_key_hash 不可用（恒空），缓存键兜底用 system_prompt_hash。规则在协议转换之后应用，写入的上游私有字段不会被翻译丢弃。详见 上游与模型字段 — 请求体修改。

粘性会话绑定键（binding_key_template） ​

在控制台里：打开负载均衡器 → 编辑 → 开启「会话粘性」→「绑定请求头」字段填 {{header:X-Session-Id|access_key_hash}}。

注意此处 system_prompt_hash 不可用（恒空），绑定键兜底用 access_key_hash 或会话头。详见 开启粘性会话。

相关章节 ​