一、操作场景
你需要在此创建和管理压缩场景，并为模型 API 绑定场景以开启压缩。压缩场景统一定义压缩器、压缩消息范围与高级参数，可被多个模型 API 复用；系统提供三个开箱即用的预设场景，也支持自由组合压缩维度新建自定义场景。典型适用场景包括：Agent 执行多步骤任务时工具结果不断累积、编程助手单次请求携带大量代码或配置文件、运维排障类应用把大段日志或调用链数据提交给模型分析。
这篇说说如何查看与新建压缩场景、为模型 API 开启压缩策略，以及查看压缩效果。
注意：说明：
注意：Token 压缩目前处于免费体验阶段，后续将开放付费购买。Token 压缩不保证无损，压缩率、回答质量和时延变化取决于业务内容，建议先用真实请求在测试环境验证效果，再在生产环境开启。请求中工具结果、日志等长文本越多，压缩收益越明显；可压缩内容不足 500 Token 的请求不会压缩。
二、前置条件
·AI 网关实例处于运行中状态，且实例版本为 3.9.8 及以上。实例版本低于 3.9.8 或压缩相关组件未就绪时，页面不提供 Token 压缩入口。
·已创建对话类模型 API，客户端使用 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 协议调用。模型服务使用 Bedrock、Gemini、Vertex AI、Cohere 等供应商原生协议时，不支持 Token 压缩。
·客户端使用 OpenAI Responses 协议，且场景开启了原文取回（预设场景默认开启）时，请求需设置 store=false，否则不会压缩。
·如需在压缩看板中查看压缩效果，实例需已开启 LLM 访问日志投递到日志服务 CLS。
·如需查看预估节省成本，需先在成本管理中配置对应模型的单价，详情请参见 模型单价配置。
三、查看压缩场景
1. 登录 AI 网关控制台 ，左侧导航栏选择 AI 网关 > 实例管理，进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的"ID"，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击 Token 压缩，然后单击压缩配置页签。
4. 在预设场景（推荐）页签中查看系统预置的三个场景。
| 场景名称 | 开关组合 | 描述 |
| 原始日志 / Trace | 日志压缩 | 处理重复日志、调用链和堆栈内容 |
| 重复 JSON / API 列表 | JSON 数据压缩 | 处理多页、重复结构的 JSON 或 API 列表 |
| 长列表 / 多步骤流程 | 搜索结果压缩 + JSON 数据压缩 | 处理多轮工具调用中的长列表和流程结果 |
列表同时展示每个场景的"引用数"，即当前引用该场景的模型 API 数量。
注意：说明：
注意：预设场景不可修改或删除，其余参数均使用默认值：仅压缩工具调用结果，压缩超时时间 5000 毫秒，开启压缩前原文取回且最多取回 3 次，压缩失败时使用原文。建议先选用与业务内容匹配的预设场景，确认压缩效果后再按需新建自定义场景。
5. 单击自定义场景子页签，可查看已创建的自定义场景，列表字段为：场景名称、开关组合、描述、引用数、操作（编辑/删除）。页面右上角提供搜索框，支持按场景名称搜索。
四、新建自定义压缩场景
1. 登录 AI 网关控制台 ，左侧导航栏选择 AI 网关 > 实例管理，进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的"ID"，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击 Token 压缩，然后单击压缩配置页签，切换至自定义场景子页签。
4. 单击新建，在新建自定义压缩场景窗口中完成基础配置。
| 参数 | 是否必填 | 说明 |
| 场景名称 | 是 | 输入此场景的名称。2-60 个字符，支持中英文大小写、数字及分隔符（"-"、"_"），不能以数字和分隔符开头，不能以分隔符结尾。 |
| 压缩开关组合 | 是 | 至少打开一项压缩器开关。各压缩器的适用内容见下表。 |
可选的压缩器如下：
| 压缩器 | 说明 |
| 搜索结果压缩 | 针对 grep / ripgrep 等包含文件路径、行号和匹配内容的搜索结果，筛选并精简重复或低价值匹配，适用于代码搜索、文件检索等工具调用结果；不适用于语义检索（RAG）或联网搜索结果。 |
| JSON 数据压缩 | 对 JSON 对象、数组及重复结构化列表进行精简，去除冗余键值与重复结构，适用于批量任务、重复 JSON / API 列表等场景。 |
| 日志压缩 | 识别请求中日志 / 调用链（Trace）内容的重复字段模式与冗余上下文并压缩，适用于把日志、Trace、告警详情交给模型排查分析的场景。 |
| 代码压缩 | 精简带明确语言标注的代码块，支持 Python、JavaScript、TypeScript、Go、Rust、Java、C、C++、C#、PHP；未标注语言或无法识别的代码保持原样。 |
| 代码差异压缩 | 精简 Git diff / patch 内容，适用于代码评审、变更分析等阅读场景；压缩结果不能直接当补丁应用。 |
| 表格压缩 | 精简 CSV、TSV、Markdown 表格，保留列名和单元格边界；解析不准的表格保持原样。 |
| 配置文件压缩 | 精简 YAML、TOML、INI 配置文件里的冗余内容，保护多行值和语法结构。 |
| 长文本压缩 | 对普通自然语言长文本做抽取式精简和去重，可能省略部分细节。 |
注意：说明：
注意：选择多个压缩器时，同一段内容只采用一种压缩结果，不会叠加压缩。内容不匹配任何已选压缩器或压缩没有收益时，保留原文。
5. 如需调整压缩范围与失败处理方式，单击高级配置（可选），完成配置。不展开时各项使用默认值。
| 参数 | 是否必填 | 说明 |
| 压缩消息范围 | 是 | 选择参与压缩的消息类型，支持多选：系统消息、开发者消息、用户消息、工具调用结果。默认仅勾选“工具调用结果”。仅压缩输入内容，模型回复不参与压缩；工具定义、调用参数等非文本内容始终不参与压缩。 |
| 压缩超时时间 | 是 | 单次压缩的最长等待时间。取值范围 100-30000 ms，默认 5000 ms；超时按“压缩失败策略”处理。 |
| 压缩失败策略 | 否 | 压缩服务超时、出错或繁忙，以及请求中可压缩的文本段超过 1024 个时的处理方式。使用原文（默认）：跳过压缩，用原始请求调用模型；返回错误：不调用模型，直接返回错误响应。 |
| 启用压缩前原文取回 | 否 | 默认开启。开启后被省略的内容替换为取回标记，模型需要时可以查看原文，适合对细节准确性要求较高的任务。关闭后只做压缩，模型无法查看被省略的内容。 |
| 最大取回次数 | 是 | 仅开启原文取回时可配置。取值范围 1-10，默认 3；达到上限时将发起一次不压缩的完整原文请求。 |
| 取回失败策略 | 否 | 仅开启原文取回时可配置。模型要求查看原文但取回失败时的处理方式，支持重试并使用原文与返回错误。 |
注意：说明：
注意：1. 开启原文取回会带来以下影响：请求被压缩时，流式响应不再逐段返回，网关等模型生成完毕后一次性返回全部内容，首段内容的等待时间明显增加；模型每取回一次，网关就多调用一次模型，产生额外的 Token 费用；原文只在当前请求处理期间保存在网关内存中，请求结束即释放，无法在后续请求中取回。对首字时延敏感的流式对话，建议关闭原文取回。
注意：2. 选择"重试并使用原文"时，如果模型已调用由模型供应商执行的工具（例如联网搜索），重试可能导致这些工具重复执行，此时仍返回错误。
注意：1. 以下内容始终不会被压缩，也无法通过压缩消息范围放开：工具定义、工具调用及其参数、推理内容（thinking/reasoning）、图片等非文本内容、历史模型回复（assistant 角色的消息）。
注意：2. 客户端与模型服务的协议不同（例如客户端使用 Anthropic Messages 协议调用 OpenAI 协议的模型服务）时，压缩消息范围请勿选择系统消息或开发者消息，否则请求会按压缩失败处理。
注意：3. 取回标记或取回请求校验不通过时，例如模型以非法参数调用取回、压缩结果中的标记校验失败，网关固定返回 403（错误码 context_authorization_failed），不受失败处理策略影响。
6. 单击保存，完成自定义场景的创建。
五、为模型 API 开启压缩策略
1. 登录 AI 网关控制台 ，左侧导航栏选择 AI 网关 > 实例管理，进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的"ID"，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击模型管理，然后单击模型 API 页签，单击目标 API 的"ID/名称"进入详情页面。
4. 单击策略管理页签，然后单击压缩策略子页签。若尚未配置压缩策略，页面展示压缩策略说明页，单击启用策略。
5. 在"配置压缩策略"面板中打开状态开关，然后配置压缩场景。
| 参数 | 是否必填 | 说明 |
| 压缩场景来源 | 是 | 选择场景来源。预设场景（推荐）：系统预置的典型业务场景压缩组合，开箱即用；自定义场景：自由组合压缩维度，多个模型 API 可复用同一场景。 |
| 预设场景 | 是 | 压缩场景来源为"预设场景"时显示。下拉选择"原始日志 / Trace"、"重复 JSON / API 列表"或"长列表 / 多步骤流程"。 |
| 自定义场景 | 是 | 压缩场景来源为"自定义场景"时显示。下拉选择已创建的自定义场景，支持按名称搜索；也可单击 + 新建自定义压缩场景直接创建。 |
| 开关组合 | — | 只读。选择场景后展示该场景启用的压缩器。 |
注意：说明：
注意：压缩器、压缩消息范围及高级参数在所选场景中统一维护，不能在模型 API 上单独修改，如需调整请前往 Token 压缩。一个模型 API 只能关联一个压缩场景。开启后对该模型 API 的全部路由生效，后续新增的路由自动继承该配置。只选择场景、未打开状态开关时，不会压缩。
注意：1. 开启压缩后，受压缩服务性能限制，该模型 API 的请求性能上限为 40 QPS，请结合业务流量峰值评估后再开启。
注意：2. 当路由策略为 Token 长度路由时，先完成路由选型，再对请求执行压缩；其他路由策略不受影响。
注意：3. 实例首次开启 Token 压缩时，网关需要先部署压缩服务，耗时较长。生效前请求不压缩，直接转发给模型。
6. 完成配置后保存。
六、确认生效状态
开启、关闭或切换场景后，需确认配置已下发生效。
1. 登录 AI 网关控制台 ，左侧导航栏选择 AI 网关进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的"ID"，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击 模型管理，然后单击模型 API 页签，单击目标 API 的"ID/名称"进入详情页面。
4. 单击策略管理页签，然后单击压缩策略子页签，在“压缩配置”区域查看状态。
页面同时展示压缩场景来源、压缩场景（可单击跳转至该场景）、开关组合、更新时间，以及"效果看板"的跳转入口。
| 状态 | 含义与处理 |
| 生效中 | 配置已保存，正在部署压缩服务或下发配置，预计 5-10 分钟。页面每 30 秒自动轮询，也可单击刷新状态手动刷新 |
| 已生效 | 当前配置已全部下发 |
| 同步失败 | 部署压缩服务或下发配置失败，页面展示失败原因，系统会在后台自动重试；长时间未恢复时，请联系腾讯云技术支持 |
| 解除中 | 正在解除模型 API 与场景的关联 |
注意：说明：
注意：保存成功不代表已生效，请以已生效状态为准。状态为"生效中"期间，请求不压缩，直接转发给模型。
七、查看压缩效果
1. 登录 AI 网关控制台 ，左侧导航栏选择 AI 网关 > 实例管理，进入实例列表。
2. 在实例列表页面，单击需要配置的网关实例的"ID"，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击 Token 压缩，然后单击压缩看板页签。
4. 在页面上方选择要查看的模型 API，页面展示该 API 所关联的压缩场景与统计周期（默认最近 24 小时）。
看板展示以下内容：
| 看板内容 | 说明 |
| 平均 Token 压缩率 | 逐个请求计算（压缩前 Token − 压缩后 Token）÷ 压缩前 Token，再取平均值 |
| 平均字节压缩率 | 按同样方法计算参与压缩文本的 UTF-8 字节压缩率，不是 gzip 等网络传输压缩 |
| 近 24 小时预估节省成本 | 按压缩前后 Token 差额和模型单价估算的输入成本，单位为元 |
| 平均新增延迟 | 压缩服务处理的平均耗时，单位为毫秒 |
| Token 消耗对比（压缩前 vs 压缩后） | 压缩前后 Token 消耗的对比图 |
| 近 7 日压缩率趋势 | 压缩率随时间的变化 |
| 单条请求压缩明细 | 展示时间、请求 ID、Trace ID、模型 API ID、压缩前 Token、压缩后 Token、压缩率、压缩前字节、压缩后字节、新增延迟。支持按条件过滤 |
注意：说明：
注意：1. 验证压缩是否生效时，可发送一条包含较长工具结果的请求，然后在"单条请求压缩明细"中查看该请求。明细中"未触发"表示该请求 Token 数低于历史对话压缩的触发阈值，仅执行了传输层压缩。
注意：2. 压缩前后 Token 只统计参与压缩的文本，不等于模型账单中的完整输入 Token。预估节省成本只是估算，不代表实际账单；发生原文取回、使用原始请求重试或上游重试的请求，以及未配置模型单价的请求，不参与估算。压缩指标从开启 Token 压缩后开始记录，不回填历史日志。LLM 访问日志未投递到 CLS、日志索引未包含压缩字段或暂无数据时，看板会提示对应状态，压缩率、平均值和成本不显示为 0。
八、不压缩的请求
以下请求会跳过压缩，用原始请求调用模型，不受压缩失败策略影响。
| 请求类型 | 说明 |
| 没有足够的可压缩内容 | 请求中没有符合压缩消息范围的文本，可压缩内容不足 500 Token，或压缩没有收益 |
| 命中 AI 缓存 | 直接返回缓存结果，不再压缩 |
| 依赖服务端保存的会话状态 | 请求携带非空的 previous_response_id、conversation、continuation、continuation_token 或 session_id，或 OpenAI Responses 的 input 中包含 item_reference |
| 引用外部上下文 | 请求使用 prompt 或 prompt_id 提示词模板，或 Anthropic Messages 请求携带 container |
| OpenAI Responses 后台任务 | 请求设置了 background=true |
| 要求精确结果的任务 | 请求中任意文本（包括工具结果和系统提示）出现"字符数""字节数""逐字""逐行比对""应用补丁""精确统计""exact count"等表述，不区分大小写 |
| 请求中已有取回标记 | 请求文本中包含 <<ccr: 或 Retrieve more: hash= 等取回标记 |
| 请求体过大或网关繁忙 | 请求体超过约 8 MiB，或网关同时处理的压缩请求过多 |
| 协议不支持 | 模型服务使用供应商原生协议；或模型 API 开启了跨服务降级，且降级链中有协议不兼容的模型服务 |
开启原文取回时，以下请求也会跳过压缩：
| 请求类型 | 说明 |
| OpenAI Responses 未关闭存储 | 请求未显式设置 store=false |
| OpenAI Chat Completions 要求多条回答 | 请求的 n 不等于 1 |
| 工具名称冲突 | 客户端定义了与网关内部取回工具同名的工具 aigw_headroom_retrieve |
九、与其他功能的关系
·执行顺序：鉴权、配额检查、安全防护和 AI 缓存查询在压缩之前执行，基于原始请求判断。当路由策略为 Token 长度路由时，先完成路由选型，再对请求执行压缩；其他路由策略不受影响。
·用量与计费：Token 用量、配额扣减和成本统计按模型实际返回的用量计算，即压缩后的输入 Token。开启原文取回时，每次模型调用分别计入，返回给客户端的用量为各次调用之和。
·版本回滚：实例回滚到 3.9.8 以下版本前，请先关闭所有模型 API 的 Token 压缩，待状态变为已生效后再回滚。系统不会阻止未关闭压缩的回滚，请务必先关闭。回滚后场景和关联配置会保留，但在重新升级到 3.9.8 及以上版本前，无法修改、解除或删除这些配置。