Agent多轮对话上下文窗口管理

多轮对话跑久了，最常遇到的就是“上下文超长”或“历史记录占满窗口”导致的请求失败。
163.Agent 本身提供了上下文窗口管理能力，其中自动裁剪超长历史就是控制 token 占用、延长连续会话稳定性的关键手段。
本文会从零开始，讲清楚它的适用场景、实现步骤、常见报错和验证方法，即使你没写过相关代码，也能照着配完。

什么时候必须启用自动裁剪

这里先明确一个概念：多轮对话中，每次请求都会把之前的对话历史一起发给模型，历史越长，消耗的上下文窗口越大。
当累计 token 超过模型限制时，轻则报 context length exceeded，重则导致接口长时间无响应。

如果你遇到下面几种情况，就说明需要启用 163.Agent 的自动裁剪功能：

• 对话轮次超过 10 轮后开始频繁报错，错误信息里出现 maximum context length。
• 会话越聊越慢，响应时间明显增长，但模型本身没有性能瓶颈。
• 业务需要长期保存会话，但又不希望历史记录占用全部上下文窗口。

自动裁剪的作用是：当历史 token 超过设定阈值时，优先删除最旧的消息，保留最近的关键内容，让每次请求都稳定落在模型可处理的窗口范围内。

准备环境：需要哪些前置条件

在开始配置前，先确认以下几项，避免做到一半才发现缺依赖：

• 已安装 Python 3.8 以上版本，并能正常执行 pip 命令。
• 已申请 163.Agent 的 API Key，且该接口支持 messages 参数传递多轮历史。
• 当前环境能访问 163.Agent 的 API 地址，如果是内网服务器，需确认网络策略已放行。
• 对于生产环境，建议先准备一个测试会话，不要直接在核心业务上做实验。

如果你的业务部署在云服务器上，建议选择内存和带宽都充裕的实例；
上下文裁剪本身不消耗太多资源，但高频调用对网络稳定性有一定要求。

配置自动裁剪：从策略选择到代码实现

163.Agent 的上下文管理并不是单一参数，而是由“裁剪策略”和“触发条件”两部分组成。
我们可以先确定策略，再写代码接入请求逻辑。

1. 确定裁剪策略

比较常用的策略有三种：

• 按 token 上限裁剪：设定最大 token 数，超过后丢弃最早消息。适合对成本敏感、希望每次请求体积可控的场景。
• 按消息轮数裁剪：只保留最近 N 轮对话。实现简单，适合固定业务节奏。
• 智能保留关键信息：保留系统指令、最近用户输入，以及被标记为重要的消息。适合有特定业务要求的中转层。

对于大多数场景，按 token 上限裁剪最直接，因为模型窗口本身就是以 token 计算的。

2. 获取当前 token 数量

为了判断何时触发裁剪，需要在发送请求前计算历史消息的 token 数。
最稳妥的方式是使用 163.Agent 自带的 tokenizer 接口，避免自行估算不准。
示例请求如下：

curl https://api.163.agent/v1/tokenizer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "你好，请帮我总结今天的工作内容。"}'

返回结果会包含 token_count 字段，将这个值累加到历史所有消息上，就得到当前上下文总 token 数。

3. 编写自动裁剪函数

下面给出一个可直接运行的 Python 示例，它会在 send 请求前检查历史长度，超限时自动裁掉最旧的非系统消息：

import requests

MAX_TOKENS = 4000  # 根据模型实际窗口调整
history = []       # 存放多轮消息，格式为 {"role": "user/assistant", "content": "..."}

def count_tokens(messages):
    total = 0
    for msg in messages:
        resp = requests.post(
            "https://api.163.agent/v1/tokenizer",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            json={"text": msg["content"]}
        )
        total += resp.json().get("token_count", 0)
    return total

def auto_trim(messages, max_tokens=MAX_TOKENS):
    """按 token 上限自动裁剪历史，跳过 system 消息"""
    system_msgs = [m for m in messages if m.get("role") == "system"]
    other_msgs = [m for m in messages if m.get("role") != "system"]
    while other_msgs and count_tokens(system_msgs + other_msgs) > max_tokens:
        other_msgs.pop(0)  # 删除最旧的一条普通消息
    return system_msgs + other_msgs

def send_with_history(user_input):
    global history
    history.append({"role": "user", "content": user_input})
    trimmed = auto_trim(history)
    resp = requests.post(
        "https://api.163.agent/v1/chat/completions",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "model": "your-model-name",
            "messages": trimmed,
            "max_tokens": 1024
        }
    )
    assistant_reply = resp.json()["choices"][0]["message"]["content"]
    history.append({"role": "assistant", "content": assistant_reply})
    return assistant_reply

注意上面示例里每次裁剪都会调用 tokenizer，实际生产建议把 token 数缓存起来，避免频繁请求。

4. 将裁剪逻辑接入中转层

如果你的 163.Agent 请求不是直连，而是经过自建的 API 中转服务，那么裁剪逻辑最好放在中转层。
这样所有调用方都能统一受控，不用各自实现一遍。

在中转服务的请求处理函数中，先对 messages 字段执行 auto_trim()，再转发给 163.Agent 上游接口即可。

关键避坑：裁剪别伤到系统指令和最近输入

自动裁剪看似简单，实际最容易踩到这几个坑：

• 误删系统指令：如果系统指令被当成普通消息裁掉，模型会丢失角色设定，回答完全不靠谱。处理时务必把 role=system 的消息单独保留。
• 剪得太狠：当阈值设得过低，历史很快被清空，模型就“失忆”了。建议阈值控制在窗口上限的 70%-80%，给回复输出预留足够空间。
• 裁剪函数递归调用 tokenizer：如果每次都重新计算全部历史 token，对话较长时会增加额外延迟。更优做法是增量维护一个总 token 数，插入消息时累加，裁剪时减少。
• 忘记处理裁剪后的空列表：如果除系统消息外全部被裁掉，某些模型会报错。可以在函数里加一个判断，至少保留最近一条用户消息。

另外，如果使用第三方中转平台，请确认它是否已经内置“最大上下文”或“超长自动压缩”选项，如果有，可以直接在控制台开启，减少自己写代码的成本。

如何验证裁剪是否生效

配置完成后，不要只看程序不报错就结束，还要确认裁剪确实在按预期工作。

1. 增加日志输出

在 auto_trim 函数执行时打印当前 token 数和被删除的消息数量：

print(f"裁剪前 token={total_before}, 删除 {removed_count} 条, 裁剪后={total_after}")

这样每次触发裁剪都能在日志中看到记录。

2. 构造长对话测试

写一个循环脚本，
连续发送 20 轮“今天天气怎么样”这类消息，
然后检查日志里是否出现裁剪记录，
同时确认系统没有因为上下文溢出而抛 context length exceeded 异常。

3. 核对最终请求体

在发送给模型前，把裁剪后的 messages 打印或存档，检查三点：

• 系统指令是否完整保留。
• 最近一条用户消息一定存在。
• 删除顺序是否从最旧开始。

满足以上条件，说明自动裁剪链路已经生效。

常见问题补充

自动裁剪会影响对话回复质量吗？

会有一定影响，因为被裁掉的历史信息不会再被模型看到。
但相比直接报错，裁剪是更可控的方案。
如果业务非常依赖早期对话内容，建议改用“摘要压缩”方式：把超长历史先交给一个轻量模型生成摘要，用摘要替换旧消息。

裁剪阈值应该怎么定？

先确认你使用的模型上下文窗口大小，比如 8K 或 128K，再把阈值设为窗口的 70% 左右。
这样既能留出足够的输出空间，又不会频繁触发裁剪。

如果 163.Agent API Key 被多个业务共用，裁剪策略能分开吗？

可以。
在调用时按业务线传入不同的 max_tokens 参数，或者在中转层根据请求来源识别不同租户，分别维护裁剪配置。

如果你正在处理 163.Agent多轮对话上下文窗口管理，自动裁剪超长历史，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分，尤其是系统消息保留和阈值设置这两项。
只要裁剪逻辑前置、参数合理，多轮对话的稳定性基本就能得到保障。