> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/practices/routing-and-transform · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 请求改写与路由：怎么选

网关改写请求/路由请求有三种手段：`request_payload` 声明式规则、`switch-route` 结构化路由、JavaScript 脚本。性能从高到低、表达力从低到高。本页是这三者的唯一选型权威。

## 三种手段的边界

| 手段 | 改 body? | 性能 | 表达力 | 内存 |
|------|---------|------|--------|------|
| `request_payload` 规则 | 是（翻译后） | 最好（声明式，无脚本引擎序列化） | 字段级增删改、注入 | 不读入内存 |
| `switch-route` 规则 | 否（只判定+改投） | 好（只做结构/小值检查） | 字段存在性、小值相等 | 不读入内存 |
| 脚本（before/after 槽） | 是 | 一般（有序列化开销） | 任意逻辑、跨字段计算 | after 槽会读入内存 |

## 决策表

| 场景 | 推荐手段 |
|------|---------|
| 简单字段增删改（`temperature`、`max_tokens`、`response_format`） | `request_payload` 规则 |
| 按结构判定切模型（有图片走强模型、有联网走联网模型） | `switch-route` 规则 |
| 注入 system prompt / 追加消息（不存在时才加） | `request_payload` 的 `inject-system-prompt` / `append-if-missing` |
| 跨字段计算 / 条件分支 / 复杂判定 | 脚本（before 槽读客户端原始格式） |
| 响应内容脱敏 / 注入元数据 | 响应脚本（`response_transform`） |

一句话：`request_payload` 覆盖约 90% 的简单场景，`switch-route` 处理纯路由决策，脚本处理剩下的复杂逻辑。

## 同协议路由决策优先用规则

只要目标与当前路由**同协议**，纯路由决策（「检测图片/联网 → 切模型」）就**优先用 `switch-route` 规则**，不要用脚本。原因见 [脚本性能与内存](/zh-CN/practices/script-performance.md) 的反模式一节——after 槽脚本会把整段 body（含内联 base64）读入脚本引擎内存，多模态大对话易 OOM；`switch-route` 的谓词只做结构/小值检查、永不读取二进制内容字节，大请求体的磁盘暂存保持开启。

## 什么时候必须用脚本

- 切换是**跨协议**且判定超出结构检查能表达的范围（`switch-route` 支持跨协议，但谓词只做存在性/小值相等）。
- 需要**读/改 body 内容**（不只是路由决策），如按 message 内容做条件改写、按 access key 分组注入不同参数。
- 需要**响应改写**（`switch-route` / `request_payload` 只作用于请求）。

跨协议场景把脚本放 **before 槽**读客户端原始格式，详见 [用脚本做协议翻译](/zh-CN/howto/script-protocol-translate.md)。

## 挂在上游还是模型

- 上游级规则/脚本：经过此上游的所有模型共享。适合协议适配、公共字段注入。
- 模型级规则/脚本：仅此模型。模型级覆盖上游级。

详见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)。

## 常见问题

**Q：switch-route 和 request_payload 的 switch-route 是同一个吗？**
是。`switch-route` 是 `request_payload` 规则的一个 `mode`，但它不修改 body、在协议翻译前按客户端形状评估。见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 的模式一览。

**Q：before 槽触发了 useModel 切换后，原路由的 after 槽还跑吗？**
不跑。一旦 before 槽触发立即 `useModel` 切换路由，整套 pipeline 换成目标路由的，原路由的 after 槽不执行。所以原路由和目标路由上的 `request_payload` 规则要各配一份。

**下一步**：[脚本性能与内存](/zh-CN/practices/script-performance.md) 看性能与反模式；[写第一个脚本变换](/zh-CN/howto/write-script-transform.md) 看脚本入门；[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 看字段。