上下文管理

当多轮对话的历史消息超出模型上下文窗口时，Responses API 提供了自动截断和上下文压缩两种策略，无需手动处理 token 溢出问题。

备注

上下文管理功能仅在使用 Responses API 协议时可用。如需了解协议详情，请参阅 API 协议介绍。

自动截断（Truncation）

通过 truncation 参数控制上下文超限时的处理策略：

值	行为
"disabled"	不进行截断，上下文超限时返回错误（默认）
"auto"	自动从对话开头丢弃最早的消息，直到内容能装入模型上下文窗口

使用方式

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3",
    "previous_response_id": "resp_xxxxx",
    "truncation": "auto",
    "input": "请继续我们之前的讨论"
  }'

设置 truncation: "auto" 后，即使对话积累了大量历史，API 也会自动滑动窗口，保留最近的对话内容。

工作原理

完整对话历史（可能超出窗口）
  ├── 第 1 轮（最早）  ← 超限时优先丢弃
  ├── 第 2 轮
  ├── ...
  ├── 第 N-1 轮
  └── 第 N 轮（最近）  ← 始终保留

上下文压缩（Compaction）

与截断不同，压缩不是简单丢弃早期消息，而是通过摘要来保留关键信息的同时减少 token 消耗。

手动压缩

对已有的响应调用压缩接口：

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/responses/{{RESPONSE_ID}}/compact" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3"
  }'

API 会对该响应关联的对话历史进行摘要压缩，返回一个新的压缩后响应 ID，后续对话可基于该 ID 继续。

自动压缩

通过 context_management 参数设置自动触发压缩的 token 阈值：

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3",
    "previous_response_id": "resp_xxxxx",
    "context_management": {
      "type": "compaction",
      "compact_threshold": 80000
    },
    "input": "请继续我们之前的讨论"
  }'

当对话历史的 token 总量达到 compact_threshold（本例为 80000）时，系统自动执行压缩，无需手动调用。

截断 vs 压缩

特性	自动截断（Truncation）	上下文压缩（Compaction）
处理方式	直接丢弃最早的对话项	通过摘要压缩对话历史
信息保留	早期信息完全丢失	通过摘要保留关键信息
触发方式	每次请求自动检测	手动调用或设置 token 阈值自动触发
适用场景	对早期对话不敏感的场景	需要保留全局上下文的长对话
延迟影响	无额外延迟	压缩过程需要额外时间

适用场景

场景	推荐策略	说明
客服对话	截断 auto	只需关注最近几轮，早期问题已解决
长文档协作编辑	压缩	需要保留全局理解，不能丢失早期上下文
代码助手	压缩	保留项目结构和之前的决策信息
闲聊/短对话	不需要	对话不会超出窗口

注意事项

• 使用 previous_response_id 串联对话时，被引用的响应必须以 store: true 创建
• 截断和压缩可以组合使用：先设置 context_management 自动压缩，再设置 truncation: "auto" 作为兜底
• 压缩产生的摘要本身也会消耗 token，适合对话已经较长（数万 token）时使用