1. 项目动机与整体设计思路1.1 为什么这个几乎看不见名字的模块决定了整个项目的成败context-mode字面意思就是“上下文模式”。最开始接到这个需求时我一度觉得它就是个花架子——给对话系统加一个开关让它决定“要不要记住前几轮说什么”。真正动手做了一段时间之后我才意识到这个看似不起眼的模块几乎是所有对话类 AI 应用里最容易被低估、又最直接影响体验的部分。你想想看现在不管是接 OpenAI、Claude 还是各种国产模型接口用户对“AI 是否记得我刚才说了什么”这件事极其敏感。上一轮说“帮我写个周报开头”下一轮说“把语气再正式一点”如果模型完全不记得前一句话体验直接崩盘。但反过来如果上下文无限制地堆叠又会遇到两个更现实的问题一是太烧钱每次请求都在为越来越多的历史 Token 付费二是模型输入太长后响应变慢、注意力涣散反而更笨。所以我做这个项目时给自己定了个目标把“上下文”从一个隐含的、不可控的黑盒拆成一个显式的、可配置的、可观测的模式模块。它解决的核心问题也不是“要不要记忆”而是“在什么场景下用什么样的记忆策略最划算、最稳定、最不容易让模型跑偏”。这个项目适合正在做聊天机器人、Agent 工具、RAG 问答系统或者任何需要跟 LLM 长时间交互的开发者参考。哪怕你是新手读完也能在自己项目里复制一套不踩坑的上下文管理方案。1.2 技术选型为什么我不直接用一个现成的对话框架当时摆在我面前的有两条路一条是直接上 LangChain、LlamaIndex 这类框架靠它们的 memory 模块另一条是自己做一套轻量的 context-mode 系统。我选了后者原因很直接——框架封装的 memory 模块虽然开箱即用但实际调起来很痛苦。它们的抽象层级太高处理长对话时你很难精确控制哪一段是系统提示词、哪一段是历史摘要、哪一段是用户刚问的问题出了问题也很难排查。自己设计 context-mode 并不是说要从零写模型而是把“上下文管理”当成一个独立的、有清晰接口的组件来做。比如我用一个统一的配置结构来描述当前对话处于什么模式再通过一个状态对象把模式、历史消息、Token 预算、摘要缓存这些信息串起来。这样做的好处是以后不管底层模型换成什么这套上下文逻辑都不用重写只改适配器。而且每次请求进入模型之前我都能把最终拼装出来的 prompt 完整地存一份日志这对调试和复盘太重要了。1.3 模式定义与适用场景表在设计过程中我并没有一上来就追求“一个模式打天下”而是把常见使用场景拆成了五个模式每个模式对应一套不同的上下文组织策略。这五个模式也成了整个 context-mode 模块的核心骨架。模式名称核心策略适合场景主要特点raw完全不带历史上下文单轮问答、翻译、关键词抽取零干扰、零额外成本sliding-window只保留最近 N 条消息常规多轮对话、客服咨询实现简单、响应稳定summary历史摘要 最近完整消息长文档写作、深度问答兼顾长期记忆与细节rag检索结果 当前问题 最近历史知识库问答、企业内部查询需要外挂检索器agent角色设定 工具调用记录Agent 工具调用、多步任务结构最复杂、控制最难刚开始我觉得 raw 模式就是凑数的但后来发现很多内部接口调用根本不需要历史比如用模型做数据清洗时带上一大堆无关历史反而容易把格式抽歪。所以模式不是越多越好而是每种都要有明确的适用边界。2. 核心实现与参数细节2.1 消息结构设计一切从一条统一的消息格式开始context-mode 的第一步不是写各种 if-else而是先定义一套统一的消息结构。不管用户输入、系统提示词、历史对话、检索文档还是摘要文本在我这里都被归一化成同一种对象格式。瞄一眼这个结构你就明白它本质上就是把模型输入的最小组件拆清楚了{ role: user, content: 请帮我总结一下这份文档的要点, meta: { mode: rag, msg_id: msg_1024, timestamp: 1720000000, token_count: 128, source: direct_input } }role 表示消息角色content 是正文meta 里记录了这条消息是从哪来的、属于什么模式、估算多少 Token。之所以要带这么多元信息是因为我在实际调试中发现只有 message 本身还不够你还得知道这条消息是什么时候进来的、当时处于什么模式否则后面做日志回放的时候根本没法还原现场。token_count 这个字段尤其重要。我在消息进入 context 时就会做一次 Token 预估算存储下来。这样动态调整窗口时不需要反复把整段历史送到 tokenizer 里重新算直接累加 meta 里的数值就行性能差距非常明显。2.2 Token 预算与窗口计算把每一分钱都花在刀刃上上下文管理的本质就是预算管理。每个模型都有 context window 上限比如 8K、32K、128K但你可不能真的把它占满因为模型还要留一部分空间用来生成回复。如果请求发过去上下文就已经占了 99%那模型只挤得出一两句话体验很差。我常用的预算是这样定的max_input_tokens model_context_limit - max_output_tokens - safety_margin拿 gpt-4o-mini 举例context limit 是 128Kmax_output_tokens 我通常设置成 2048safety_margin 留 1024。那这轮请求最多允许上下文输入就是 128000 - 2048 - 1024 124928 Token。这个 margin 是为了应对 tokenizer 估算误差和系统提示词本身的波动别贪这最后的 1000 个 Token关键时刻能保命。接下来就是把可用预算分配给各个部分。我用的分配优先级是系统提示词 最近用户意图 检索到的相关信息 历史摘要 最早的历史细节。因为越靠近当前问题、越靠近系统约束的内容对模型输出的影响越大而最容易牺牲的就是那些最早、最细节的历史对话。具体实现上滑窗模式会维护一个“双端队列”新消息进来时从尾部追加同时累加 Token如果总 Token 超过 max_input_tokens就从头部弹出旧消息直到预算合适。核心逻辑大致长这样from collections import deque class SlidingWindowContext: def __init__(self, max_tokens: int): self.max_tokens max_tokens self.messages deque() self.current_tokens 0 def add_message(self, msg: dict): self.messages.append(msg) self.current_tokens msg[meta][token_count] while self.current_tokens self.max_tokens and len(self.messages) 1: evicted self.messages.popleft() self.current_tokens - evicted[meta][token_count]注意 while 循环里我保留了至少一条消息避免窗口被全部清空导致用户当前问题都没地方放。这个看似不起眼的细节在极端场景下特别容易踩坑。2.3 摘要模式的实现逻辑三层结构保记忆滑窗虽然简单但有个致命问题如果对话很长早期的重要信息比如用户一开始说过“我是销售部的预算审批要找经理”会被直接弹出窗口模型后续就“失忆”了。所以 1.3 节里的 summary 模式更靠谱它把历史拆成三层第一层全局摘要用独立调用把前面所有对话浓缩成 400 字以内的要点。第二层最近 N 轮完整消息保留最近的细节和语言风格。第三层当前用户问题完整保留一个字不砍。全局摘要是整个 summary 模式的核心。我实现了一段滚动摘要逻辑每累计 6 轮对话就触发一次摘要更新把旧的摘要加上新增加的对话内容一起交给模型重新压缩生成一份新摘要。你仔细推敲就会明白这么做比“每轮都摘要”省太多钱也比“最后一次性摘要”更能抵抗长上下文的信息遗忘。摘要在拼装时有个顺序问题。我踩过好几次坑才确认摘要必须放在系统提示词之后、最近对话之前。因为模型读文本的时候前面部分会作为“全局背景”中间部分当作“过程细节”最后紧跟的才是“当前需要回应的内容”。这个顺序一旦搞反模型经常会把历史摘要当成当前任务回答方向就歪了。2.4 配置文件让模式切换成为复用资产所有模式定义和参数我最后都收敛到了一个 JSON 配置里。这样后续不管开新项目还是做新功能直接把配置拷贝过去微调就行。context-mode 的配置大致长这样{ mode: summary, max_output_tokens: 2048, safety_margin: 1024, window: { keep_recent_messages: 6, summary_trigger_rounds: 6, summary_max_tokens: 400 }, rag: { retrieve_top_k: 5, max_doc_tokens: 1500, doc_reorder: true }, agent: { tool_history_rounds: 4, include_system_tool_schema: true } }配置化的价值等到后面接不同模型的时候才充分体现出来。不同厂家模型的上下文大小、对长文本的容忍度都不一样我只需要提供一个环境变量指定加载哪份配置就能在同一个服务里适配多种模型。这要比在代码里硬编码优雅得多也方便测试团队做对比实验。3. 实操过程与核心环节实现3.1 从单轮对话到滑动窗口我的第一步并不顺利最初版本特别简单context-mode 只有一个 raw 模式每次请求直接把用户输入拼到 system prompt 后面发给模型返回结果完事。很快我就被业务方吐槽了“用户在对话框里连续问了三次问题每次 AI 都像失忆了一样完全不知道前文在讲什么。”于是我开始做 sliding-window。第一版实现就是对历史消息做长度截断超过 2000 个字符直接砍掉老的。结果测试的时候又出幺蛾子Python 字符串的字符数跟 Token 数根本不是一回事中英文混合场景下2000 字符可能已经爆掉 3000 Token也可能只有 1000 Token。更尴尬的是中文会按字符被硬生生截断模型收到后半句残文直接胡言乱语。这个阶段最大的教训就是绝对不要用字符数来管理窗口一定用 Token。后来我引入了 tiktoken 做离线估算消息入库时就计算并保存 token_count所有窗口逻辑都基于 Token 来跑。改完之后窗口控制的准确度明显上升再也没有出现过超限报错。3.2 摘要模式的开发理想很丰满实现处处是坑做完滑窗后业务方又提出新需求用户希望 AI 能记住更早之前提到的关键信息哪怕隔了 20 轮。滑窗模型解决不了这个问题我被迫上了 summary 模式。我用了一个很经典的实现方案在消息队列之外额外维护一个 summary 字段。每次达到触发轮数就把当前 summary 连同最近几轮消息一起丢给模型让模型生成新的 summary 并覆盖旧值。这么做很快遇到了两个棘手的问题。第一个是摘要失真。模型天生有“平滑化”倾向会把一些细节细节丢失或“脑补”。比如用户说过“预算 5000 以内”摘要可能被概括成“预算有限”之后模型审批逻辑就全错了。后来我做了一件事摘要生成的提示词里强制要求保留所有数字、日期、人名、金额并规定摘要是“提取关键信息而非润色改写”失真的情况才明显好转。第二个是摘要延迟。摘要生成本身也要调用一次模型接口如果放在用户请求的路径上同步执行用户会明显感觉变卡。我的解决办法是异步化每轮对话正常完成回复后在后台任务里检查是否需要触发摘要如果需要就在响应返回给用户之后、系统空闲时去生成下次对话时再读取最新 summary。用户感知不到摘要耗时记忆却能持续更新。3.3 RAG 混合模式检索与历史的拼接顺序是关键RAG 模式是我在 context-mode 里投入时间最多的部分因为它的组件最多拼接顺序的影响也最大。我参考了大量线上测试结论最终确定的顺序是system prompt 检索到的文档按相关度从高到低 全局摘要如果有 最近对话历史 当前用户问题这个顺序不是随便定的。检索文档放在最前面、紧跟系统提示词是为了让模型优先知道“知识范围在哪”当前问题放在最后是为了让模型明确“现在要回答什么”。如果你把所有内容混在一起排模型经常分不清哪些是参考材料、哪些是要处理的任务。具体检索参数上我最初设 top_k 8结果经常出现文档过多、把对话历史挤没的情况。后来我把 top_k 调成 5同时给每条文档设 max_doc_tokens 上限1500一旦超过就先做文档切块和截断。这里又有一个细节切块时优先保留包含用户关键词的高亮片段而不要机械地从头开始取。很多时候用户问的问题在文档后半部分机械截断反而把关键内容漏掉了。3.4 压测与效果对比数据证明模式调优的价值整套系统完成之后我把四个模式在同样的 30 轮长对话测试集上跑了一遍结果非常有意思。raw 模式因为不带任何历史平均响应时间最快、Token 成本最低但用户对连续性评价打分只有 1.8 分满分 5 分基本等于不可用。sliding-window 模式把最近 8 轮完整保留连续性打分提升到 3.6 分Token 成本比 raw 高出一截但还在可控范围。summary 模式最让我惊喜它把连续性打分拉到了 4.3 分因为早期关键信息能被摘要保住而且 Token 成本只比滑窗高一点。RAG 模式在知识类问题上的准确率优势明显但在连续多轮闲聊场景下因为检索噪音干扰打分反而略低于 summary。这组数据让我彻底明白了一个道理不存在绝对最优的模式只有最适合当前场景的模式。后来我在系统里加了一个非常实用的功能——按轮次自动降级。比如前 4 轮使用 raw 或 sliding-window超过 6 轮自动切到 summary如果检测到用户问题包含明显的查询性指令再临时切到 rag。这套动态切换逻辑成了 context-mode 里最受团队欢迎的能力。4. 常见问题与排查技巧实录4.1 高频问题与解决方案速查表开发过程中我建了一个文档专门记录各种翻车案例。这里挑几个最典型的整理成表格希望你能照着少走弯路。问题现象根本原因解决方案模型突然忘记用户早期信息滑动窗口把早期消息弹出了换 summary 模式把关键信息压缩进全局摘要请求反复报上下文超限忘了算 max_output_tokens 和 safety_margin用公式 max_input_tokens limit - output - margin摘要之后模型回答变“官方”摘要提示词未要求保留数字和专有名词在摘要任务中明确“提取实体、数字、日期、金额”RAG 模式下回答知识陈旧检索文档占位太大把最近对话挤没了调低 top_k限制每条文档 Token 上限文档切块后再拼接模式切换后模型理解错乱切换时没有清理上一模式的系统指令每次切换模式重置 system prompt 与消息队列状态异步摘要导致并发重复多条请求同时触发摘要更新用用户会话 ID 作为锁同一会话同时只允许一个摘要任务摘要太冗长消耗预算摘要任务没有设置 max_tokenssummary_max_tokens 调到 300~500超出内容会被自动截断用户说“你刚才不是说过吗”但回复完全对不上历史消息里混入了检索文档模型把文档当成了对话消息 meta.source 字段明确标注 system_summary、retrieved_doc、history4.2 排查手段学会给每次请求拍一张“X光片”上下文问题最大的难点在于它不是每次都稳定复现有时候可能连续三次正常第四次就突然“失忆”。如果只盯着代码看很难定位问题。我的习惯是给每次进出模型的请求都写一份完整的 context 快照日志记录这次请求最终拼装出来的完整 prompt包含所有系统提示词、摘要、历史、检索文档以及当时的模式、Token 数和模型回复。这样一旦出问题我可以直接打开日志像看 X 光片一样看到模型收到的那份完整输入。很多你觉得“模型怎么这么蠢”的场景翻日志才发现根本不是模型笨是系统把一段无关的旧内容塞进了上下文或者把摘要放在了错误的位置。日志回放的价值怎么强调都不过分。另外我建议在测试阶段做一个“上下文盲测”脚本把每次请求的最终 prompt 转成纯文本去掉模型回复人工阅读一遍判断信息是否连贯、是否有冲突。很多上下文污染问题在这个步骤就能肉眼发现不用等到上线后让真实用户来骂。4.3 我最后留下的小经验先做减法再做加法复盘整个 context-mode 的开发过程我最想分享的一条经验是先做减法再做加法。很多人一上来就想把所有历史都塞给模型觉得“信息越全越聪明”但实际效果往往是预算烧得飞快模型还更容易被噪音干扰。我当时做的最正确的一个决定是给所有历史消息按“重要程度”打了一个标签。来自系统提示词的内容重要度最高用户明确提出的约束条件次之闲聊寒暄最低。当 Token 预算不够时优先丢弃低重要度的内容而不是按时间先后粗暴淘汰。这样一个简单的优先级机制就让摘要模式的记忆能力又上了一个台阶。还有一点是关于可观测性。context-mode 模块从第一天起就强制要求所有消息带有 meta 信息和 msg_id所有组装前和组装后都打日志。这个习惯前期会浪费一点时间但在后续排查问题、对比模式效果时回报率实在太高了。我见过太多项目上下文管理做成一个黑盒出了问题只能靠猜那基本就是在给自己埋雷。