请求选项透传与覆写

通过请求头控制单次查询的路由、归属、会话黏附、追踪、原始报文可见性、内容记录与上游透传——平台前缀 x-lq-* 选项的完整参考与生效约束

数据平面统一查询入口在标准的 OpenAI 兼容请求体之外，还支持一组请求选项，用于控制单次查询的路由、归属、会话黏附、追踪、原始报文可见性、内容记录与上游透传等行为。这些选项以平台前缀 x-lq-* 的请求头携带，逐请求生效，互不影响请求体本身。

本页给出选项的完整参考与生效约束。各选项都是可选的——不携带时按平台或子账户的默认策略处理。

1. 选项一览

请求头	类型	用途
`x-lq-key-id`	字符串	显式指定承接本次请求的接入密钥标识（覆写默认密钥选择）
`x-lq-session-id`	字符串	会话黏附标识：同一会话的请求黏附同一把接入密钥
`x-lq-session-ttl`	时长	会话黏附绑定的缓存时长（如 `30m`、`1h`，或秒数）
`x-request-id`	字符串	自定义请求追踪标识；不传则平台自动生成
`x-lq-send-back-raw-request`	布尔	在响应中附带发往上游的原始请求报文
`x-lq-send-back-raw-response`	布尔	在响应中附带上游返回的原始响应报文
`x-lq-store-raw`	布尔	把原始请求/响应报文持久化到逐条调用记录
`x-lq-disable-content-logging`	布尔	单次请求级覆写内容记录开关（脱敏敏感请求）
`x-lq-passthrough-extra-params`	布尔	透传请求体中平台未识别的额外参数给上游
`x-lq-dim-*`	字符串	单次请求维度标签，随逐条记录与监控落账
`x-lq-fwd-*`	字符串	转发给上游的自定义请求头（前缀剥离后透传）
`x-lq-cache-key`	字符串	缓存检查点的自定义缓存键
`x-lq-cache-ttl`	时长	缓存命中条目的留存时长
`x-lq-cache-threshold`	浮点（0.0–1.0）	语义相似度匹配的相似度阈值
`x-lq-cache-no-store`	布尔	禁止本次请求/响应进入缓存

2. 路由与归属

2.1 显式指定接入密钥

默认情况下，路由中间件在选定上游后会自动择优一把接入密钥。携带 x-lq-key-id 可显式钉住某把密钥，用于密钥级排障或固定承接：

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-key-id: <接入密钥标识>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

2.2 会话黏附

把一个会话绑定到固定的接入密钥，使同一会话标识的请求一致地命中同一把密钥——用于可预测的限速桶、按会话归集成本、同会话内一致的模型路由。

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-session-id: <会话标识>" \
  -H "x-lq-session-ttl: 30m" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

会话黏附与重试、故障转移的衔接：

情形	行为
重试	黏附跨重试保持——请求失败重试时仍用同一把黏附密钥
故障转移	降级到另一上游时黏附失效，为新上游另选密钥，以保证可用性
绑定时长	由 `x-lq-session-ttl` 控制，缺省 1 小时；每次请求刷新 TTL，活跃会话不过期

3. 追踪与可观测

x-request-id 设置自定义请求追踪标识，贯穿一次请求（含流式全部数据块）始终一致，便于把多次后置处理归并到同一条逐条记录；不传则平台自动生成。

x-lq-dim-* 为单次请求附加维度标签（前缀剥离后取剩余部分为标签名），随逐条调用记录与监控汇总落账，便于按环境、业务线等维度聚合查询。

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-request-id: <自定义追踪标识>" \
  -H "x-lq-dim-environment: production" \
  -H "x-lq-dim-business-line: <业务线>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

维度标签不承载敏感信息。 x-lq-dim-* 的值会传播到逐条记录与监控视图，不应在其中放置个人信息或凭证；x-request-id 等保留标识不可被维度标签覆盖。

4. 原始报文可见性

平台对外统一返回规整后的响应。若需排障，可让响应额外附带与上游交互的原始报文，或把它们持久化到日志。三个开关相互正交，可任意组合：

开关	作用	落点
`x-lq-send-back-raw-request`	在响应里回带发往上游的原始请求	响应 `extra_fields.raw_request`
`x-lq-send-back-raw-response`	在响应里回带上游返回的原始响应	响应 `extra_fields.raw_response`
`x-lq-store-raw`	把原始请求/响应持久化到逐条记录	逐条调用记录

{
  "choices": [ ... ],
  "usage": { ... },
  "extra_fields": {
    "routed_provider": "<本次承接的上游>",
    "raw_request": { "...": "发往上游的原始请求" },
    "raw_response": { "...": "上游返回的原始响应" }
  }
}

默认关闭，需先放开。 单次请求级覆写默认禁用——须先在「平台设置 · 日志策略」中开启对应的逐请求覆写许可，上述请求头才生效。"回带给调用方"（send-back）与"持久化到日志"（store）相互独立：开 store 不会把原始报文回给调用方，开 send-back 也不会把它写进日志；二者都开才同时生效。

5. 内容记录覆写

x-lq-disable-content-logging 用于单次请求级覆写全局的内容记录策略：

置 true：本次请求的消息、参数与原始报文从逐条记录中略去（用于脱敏含敏感信息的请求）；
置 false：即使全局关闭内容记录，本次仍记录内容。

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-disable-content-logging: true" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ { "role": "user", "content": "<含敏感信息的内容>" } ] }'

该开关只影响写入逐条记录的内容字段（消息、参数、原始报文）。词元用量、时延、计费金额、路由元数据等始终照常落账，不受此开关影响。同样需先在日志策略中放开逐请求覆写许可，否则以全局策略为准。

6. 额外参数透传

x-lq-passthrough-extra-params 置 true 时，请求体中平台未识别的顶层字段会被直接合并进发往上游的请求，用于使用上游特有的请求参数：

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-passthrough-extra-params: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型中性名>",
    "messages": [ { "role": "user", "content": "你好" } ],
    "custom_param": "value",
    "nested_param": { "a": "value", "b": 123 }
  }'

透传约束：仅对 JSON 请求生效（不含 multipart/form-data）；平台已处理的标准参数不会重复透传；嵌套参数与既有结构递归合并。

7. 转发自定义请求头

x-lq-fwd-* 把自定义请求头转发给上游（前缀 x-lq-fwd- 剥离后透传）。例如 x-lq-fwd-tracking-id: trace-456 会以 tracking-id: trace-456 抵达上游：

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-fwd-tracking-id: <追踪标识>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

安全屏蔽名单。 平台维护一份永不转发给上游的请求头名单（无论如何配置），包括 host、cookie、content-length、connection、transfer-encoding，以及平台自身的鉴权头（Authorization、x-lq-key-id 等）。试图借 x-lq-fwd-* 转发这些头会被静默丢弃，避免凭证与连接控制头泄漏到上游。

8. 缓存选项

缓存检查点中间件支持以下逐请求选项，调节命中行为：

请求头	作用
`x-lq-cache-key`	自定义缓存键，用于精确控制命中分组
`x-lq-cache-ttl`	缓存条目的留存时长（如 `5m`，或秒数）
`x-lq-cache-threshold`	语义相似度匹配的相似度阈值（0.0–1.0，越高越严格）
`x-lq-cache-no-store`	置 `true` 时禁止本次请求/响应进入缓存

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-lq-cache-threshold: 0.85" \
  -H "x-lq-cache-ttl: 300" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

语义相似度匹配以嵌入相似度判定两条查询是否足够接近以复用上一条结果；阈值越高，要求两条查询越相似才命中。缓存检查点的短路语义与对称收尾详见中间件管道与扩展点 SDK §2.4。上游模型供应商侧的缓存是否命中以上游返回为准，与本节的检查点缓存相互独立。

下一步

路由规则：本页的请求头（如分级头）可作为路由规则条件表达式的输入变量。
模型别名与映射：把应用发送的模型名解耦为上游实际标识。
性能与故障转移调优：超时、重试、健康检查与加权恢复的调优口径。
API 参考：数据平面统一查询入口的完整字段契约。

请求选项透传与覆写

On this page