做AI工具的人应该都有过类似的体验模型回答得“驴唇不对马嘴”你前一句话它还记得隔了几轮它就像失忆了一样。尤其是本地跑大模型、写自动化脚本或者做个人知识库助手的时候这个问题特别明显。我自己维护的一个本地开发辅助工具就卡在这里很久直到我把“上下文怎么组织”这件事彻底重做了一遍做成了一个独立的模块起名就叫context-mode。简单来说它是这套工具里专门负责“决定该让模型看到什么”的模块解决的是上下文窗口有限、历史消息膨胀、多文件项目信息零散这三件最让人头疼的事。这篇文章不打算写成一层层的文档说明我就按实际做这个模块的过程来聊为什么要专门做一个“上下文模式”它的核心设计思路是什么实现的时候哪些环节最容易翻车以及怎么配置、怎么调、怎么排查。不管你是想给自己的AI项目补一段上下文管理逻辑还是单纯好奇这类功能怎么落地这篇都值得顺着往下看。1. 为什么要专门做一个“上下文模式”1.1 上下文不是越多越好而是“越合适越好”很多人一开始的想法特别朴素上下文嘛把对话历史、文件内容、检索结果全部拼在一起扔给模型模型总能找到有用的信息。但真跑过一次就知道这条路根本走不通。大模型的输入窗口虽然越来越大但token是实打实要成本的而且上下文一长模型对关键信息的聚焦能力会明显下降。你塞了一堆代码文件进去它反而抓不住你真正想问的那一段。我最初也踩过这个坑把项目目录下所有源码都读进prompt结果模型开始一本正经地分析无关的配置文件真正要改的逻辑反而没注意到。后来我想明白一个道理context-mode存在的意义不是“无脑多塞上下文”而是“按需选择上下文”。我们需要给对话、工具或代码补全功能一个明确的能力——在不同场景下决定哪些上下文值得进入窗口哪些应该被丢弃或压缩。1.2 没有Context模式时的典型痛点如果不用一个专门的模块来管上下文你会持续遇到几类问题第一会话历史越滚越长直接打到上下文上限。这个问题在本地部署场景尤其致命因为硬件算力本来就有限输入token一多推理速度肉眼可见地变慢。第二Ottoman“旧信息把位置占了新信息进不来”。第三多轮对话中间穿插了代码修改、文件切换后模型完全不知道当前你在做哪个文件。第四不同任务需要不同粒度的上下文比如随手问一句“这个函数在哪个文件”跟“把整个模块重构一遍”需要的上下文完全不是一回事。这些问题光靠调prompt是解决不掉的必须在代码层面建立一个有结构、有策略的上下文管理机制。context-mode的核心就是把“上下文组织策略”抽出来作为一个可配置、可切换的模块让上层应用在不同场景下自动选择最合适的组合方式。1.3 它的适用范围和场景有必要说明一下context-mode不是一个面向终端用户的可视化功能它的定位更接近“底层能力模块”。你可以把它挂在AI编程助手上也可以挂在本地知识库问答系统、命令行工具、自动化脚本里。只要是“把若干来源的信息拼给大模型”的场景它基本都能派上用场。我这边实际使用最频繁的场景是本地开发辅助工具里的三个功能代码问答、文件生成、修改建议。过去三个功能共用一套上下文拼接逻辑效果很一般。后来给它们各自配置了不同的上下文模式才明显感觉到回答质量上了一个台阶。这也是为什么我觉得有必要把它单独做成模块而不是混在主业务里因为它的调整频率和对业务逻辑的独立性比大多数人想象的高得多。2. 整体设计与三个核心模式拆解2.1 设计目标与三层架构开始写代码之前我先明确了context-mode模块的几个设计目标可插拔、可观测、可配置。可插拔意思是上层业务不应该关心上下文怎么拼只调接口传参数就行可观测是说每一次组装上下文之后要能知道用了哪些来源、花了多少token可配置则是说不同场景可以通过配置切换策略不用改业务代码。最终我采用了三层架构第一层是数据源层负责采集所有候选上下文片段包括对话记录、文件内容、检索结果、工具输出等第二层是决策层根据当前模式对候选片段做评分、筛选、排序第三层是组装层按照token预算把筛选出的片段拼成最终prompt。context-mode从外部看就是一个接口输入是一堆候选片段加一个模式标识输出就是拼好的上下文块和对应的token统计。这个架构的好处是每一层都能单独测试。数据源层可以独立验证每个来源抓取是否完整决策层可以单独调评分参数组装层的token截断逻辑可以针对不同模型的计费规则做适配。对后期排查问题来说这种分层真的是省了大劲。2.2 核心模式一auto模式auto模式是这个模块里我最推荐默认开启的模式它的核心思路是“所有候选上下文都参与打分但只有分数够高、相关性够强的片段才进入最终上下文”。这里面的关键就是一个好的评分函数。我最初用的评分逻辑比较简单文本重叠度加上关键词命中数。效果只能说勉强能看最大的问题是遇到同义表述就抓瞎。后来升级成了两步评分先用轻量级的BM25粗筛把明显不相关的片段砍掉再用向量相似度做精排选出最匹配的若干片段。虽然多了一步向量计算的消耗但准确率提升非常明显。auto模式里还有个重要设计叫消息衰减权重。时间越早的对话消息相关度权重越低但不是直接删除。这样既兼顾了最近对话的核心信息又保留了早期可能存在的关键铺垫。你可以在配置里调整衰减系数默认值是0.9意思是每往前一轮权重衰减10%。这个值我觉得对大多数场景是合适的但如果你的项目特别依赖早期交代的规则建议把衰减系数调到0.95以上。2.3 核心模式二replay模式有些场景下光靠“相关性筛选”是不够的。比如你让模型帮忙审查一个前前后后改了三十轮的文件中间涉及大量历史修改原因这种时候必须让模型看到完整上下文轨迹一个片段都不能漏。这就是replay模式存在的意义。replay模式的策略是“按时间线完整回放指定的上下文来源”它不做筛选只做组织和截断。优先保留系统提示词和最先交代的任务目标然后把对话历史、操作记录按时间顺序完整保留最后才考虑附带资源文件。这个模式对token的消耗是最高的所以我做了一个保护机制当历史内容超出预算时不是从头开始截断而是从最早的记录开始压缩。怎么压缩呢分两种情况如果一段历史只有两三轮直接丢弃太可惜就把它变成一个简短的摘要如果摘要本身已经存在就继续摘要旧的、保留完整的新内容。这样能保证模型看到的永远是“完整脉络最新细节”而不是断断续续的碎片。replay模式特别适合三种场景代码审查、长文档校对、多步骤任务执行。如果你发现模型经常“忘记”最开始交代的目标很可能就是因为它一直用的是auto模式的筛选逻辑而这时就应该切到replay模式。2.4 核心模式三global模式第三种模式叫global模式它是专门用来处理“长期稳定信息”的。什么是长期稳定信息比如项目的技术栈、代码风格约定、API使用规范、用户的偏好设置、之前决定过的方案等。这些信息的特点是非常重要、长期不变、但每一次对话都可能用到。我在做global模式的时候参考了RAG的思路但做了很大简化。不搞复杂的向量库因为它本质上是一个频繁读取的静态配置我直接维护了一个按优先级排序的全局上下文库每个条目有固定的优先级和业务标签。比如项目约定的代码风格是优先级最高的标签用户偏好设置排第二常见问题排第三。组装上下文时global模式会先把这些固定片段放进去再根据剩余预算加入会话历史的检索结果。这里有个细节挺重要全局上下文库的内容最好不要直接以原始文本入库而是应该做成“精简条目”。比如“项目使用Python 3.10”这条不要存成“我们在项目里使用Python 3.10版本这是我们之前讨论决定的”而是直接存成结构化条目[tech-stack] python3.10。这样既省token又方便后续程序化处理。我用下来以后发现这种方式比存完整文本的效率高一倍不止。3. 实操过程与核心环节实现3.1 先做配置结构把模式的“开关”立起来context-mode第一步不是写打分逻辑而是先把配置结构定下来。因为这个模块是给多个业务场景复用的每个场景的模式可能不一样如果配置不清晰后面一定乱。我用的配置文件是YAML格式核心结构是一个模式枚举加上每个模式的独立参数context_mode: enabled: true default_mode: auto modes: auto: use_bm25: true use_vector: true top_k: 8 decay_factor: 0.9 min_score: 0.35 replay: max_history_turns: 60 summary_before_truncate: true preserve_first_turns: 3 global: priority_tags: [code_style, user_pref, tech_stack] max_global_entries: 20 retrieve_after_global: true这里每个字段背后都有讲究我挑几个重点说。min_score是auto模式里最低通过分数我一开始没设结果一些相关性不太行但“能沾边”的片段总会被塞进去回答经常跑偏。设了0.35以后整体质量稳定了很多。preserve_first_turns是replay模式里一个容易被忽视的字段作用是不管后面怎么压缩最开始几轮交代的任务目标必须原样保留这个值设为3对我来说是个稳妥的平衡点太少了容易丢失任务起点太多了又浪费token。3.2 实现候选上下文采集与评分数据源层我设计了一个统一的候选片段结构它长这样dataclass class ContextCandidate: source: str # 来源: chat, file, search, tool content: str # 片段内容 timestamp: float # 时间戳 metadata: dict # 额外的元信息如文件路径、消息角色 score: float 0.0 # 打分后的分数默认0不管上层业务传来的是对话消息、文件内容还是搜索结果一律包装成这个结构然后塞进决策层去做统一处理。这样上层代码会非常干净不用知道内部是怎么打分的。打分过程的顺序也很重要。我是先算基础分数再乘时间衰减权重最后结合业务权重调整。基础分数就是前面说的BM25向量相似度融合具体的公式是基础分 0.4 * bm25_score 0.6 * vector_similarity 最终分 基础分 * (decay_factor ** age)这里面有个藏得很深但很关键的点向量相似度在短文本上的表现很不稳定。一个只有十几个字的短消息和一个几百字的长文档用向量相似度对比时短消息经常拿到虚高的分数。我的处理方式是给不同来源加了不同的权重系数文件内容的向量相似度权重高一点对话消息的基础上分权重高一点。这两种数据特征不一样得分逻辑就不该完全一致。3.3 token预算分配与截断逻辑的实现上下文拼装的最后一步是预算分配。每个模型有自己上下文上限通常不能把窗口完全占满因为还要给模型的输出留空间。我的经验是输入token控制在总窗口的50%到60%之间剩余留给输出和临时变量。def assemble_context(candidates, mode, total_budget): if mode auto: ranked sorted(candidates, keylambda c: c.score, reverseTrue) elif mode replay: ranked sorted(candidates, keylambda c: c.timestamp) elif mode global: ranked sort_by_priority_then_score(candidates) else: raise ValueError(funknown mode: {mode}) used 0 result [] for cand in ranked: cost estimate_tokens(cand.content) if used cost total_budget: # 预算不足时尝试截断当前片段而不是直接跳过 trimmed trim_to_fit(cand.content, total_budget - used) if trimmed: result.append(trimmed) break result.append(cand.content) used cost return \n.join(result), used这个实现有意识地解决了两个常见问题。第一个是“预算不足时不要直接跳过当前片段”因为很多场景下这个片段恰恰是最关键的截断一部分内容保留关键开头比彻底丢掉好得多。第二个是“截断必须以语义边界为准”这里的trim_to_fit会优先在段落边界截断其次是句子边界实在不行才在字符级截断。如果直接按固定字符数硬切很容易把代码块、表格、或者markdown语法切成残缺状态模型看到以后轻则格式乱掉重则直接出错。这里还要提一个我自己踩过的坑不同tokenizer对中文的计费差异特别大。有些模型把中文一个字算一个token有些按词切分同样一段内容在不同模型上的token估算差异可能超过50%。所以estimate_tokens不能用统一规则我是在配置里给每个模型预设了一个token_ratio参数相对于英文token数的倍率中文场景基本在1.5到2.0之间。有一段时间我没注意这个问题上下文预算总是莫名其妙的爆掉排查了很久才发现是token估算偏小导致的。3.4 接入业务层的完整调用流程模块内部实现得再漂亮接入方式太复杂也会让业务方不想用。我的做法是把context-mode对外暴露成一个极其简单的调用入口只有两个参数请求类型和原始输入。ctx_response context_mode.process( scenecode_review, # 业务场景自动映射到对应模式 user_input帮我看看auth模块有没有安全问题, candidatescollect_all_candidates(), # 由外部负责采集 ) # 拿到的输出 prompt ctx_response.prompt stat ctx_response.token_usage内部会根据scene自动决定走auto、replay还是global并加载对应的配置参数。业务方完全不需要知道决策逻辑。而采集候选这个动作为什么要放在外部因为不同业务场景下的数据来源完全不同代码问答要读项目文件知识库问答要检索文档这些逻辑本身就应该留在业务侧。接入后我加了一个运行时监控池每完成一次组装都会把候选片段的来源分布、得分情况、最终保留率记录下来。这样后续调参的时候不是靠感觉说“这个模式效果不太好”而是能直接看数据。比如某个场景下发现文件类片段的保留率过低就可以针对性调整文件来源的权重。这种反馈闭环对持续优化特别重要。4. 常见问题与排查技巧实录4.1 模式不生效切了等于没切这个是我接到反馈最多的问题明明在配置里把默认模式改成了replay但跑起来之后感觉跟之前一模一样。排查下来发现大部分人都犯了一个低级错误——改了配置文件但没有触发模块的热加载机制。我的解决方案是两层的。第一层配置文件有变更时可以通过监听文件修改事件自动刷新配置但这需要额外引入watchdog之类的监听库不是所有环境都方便。第二层因为没有全局刷新机制接口每次调用时都会读取配置的mtime做一次快速对比发现有变化就重新加载配置。但如果不支持热重载那就需要主动调用一次context_mode.reload()。在排查问题的时候大概率就是某个场景提前创建了配置对象后续调用一直沿用旧配置所以模式切换没生效。4.2 拼出来的prompt内容破碎或者格式混乱这个问题在代码场景尤其常见。诊断信息显示模型经常收到没有缩进的Python代码块、被拦腰截断的JSON片段、或者结尾缺少闭合括号的SQL。本质上都是截断逻辑过于粗暴导致的。规避的核心办法就是前面说的“语义边界截断”。代码场景要识别代码块边界不能从函数体中间切断文档场景要找段落和换行对话消息要按完整问答对截断不能把回答的中间部分直接暴露给模型。还有一个反直觉的细节有时候主动舍弃一部分上下文比“长截断后再拼上”效果更好。我发现与其保留半个残缺代码块不如干脆把这一轮丢弃让模型明说“相关信息不足”然后由上层去触发检索或追问。这在实践中反而能减少幻觉式的错误回答。另外如果你的候选片段是markdown格式拼入prompt之前建议做一次格式规范。不要求完全统一但至少标题层级要一致代码块语言标识要正确列表缩进不能乱。因为大模型本身依赖格式来推断结构格式乱了理解也会跟着乱。4.3 填了token预算上限模型还是说“信息被截断”这类问题通常不是因为代码里没做截断而是因为estimate_tokens估出来的数字和实际模型计费口径对不上。我在之前提过不同模型中文token差异很大这里实际出现的情况是估算函数说用了4000个token但模型实际消费了6500个token上下文直接超限。解决方法是给每个部署端配置独立的token预估值并通过实际调用日志反向校准。校准公式很简单实际token 模型返回的usage字段中的total_tokens 估算偏差率 (实际token - 估算token) / 估算token把连续多次调用的估算偏差率取平均值然后在代码里做同步修正。我自己的模块上线初期就发生过一次偏差率高达72%的情况修正后上下文超额的问题立竿见影地消失了。4.4 候选片段太多打分耗时过长如果项目规模上来了可能一次问答会采集几十个甚至上百个候选片段逐一打分的时间会有隐患。实测下来纯粹的BM25精排和向量相似度计算在100个片段级别延迟在100毫秒左右但如果在本地用CPU跑向量模型延迟会成倍增长。一种革命性的做法是在数据源层就增加一次轻量预过滤。第一次粗暴过滤掉一半无关内容再进入精细评分。比如先把全部候选按“是否包含当前用户输入中的关键词”过一遍命中规则之外的直接降低优先级这样精细评分阶段需要处理的片段数量大大减少。代价是有极低概率误伤有效内容但对大部分场景来说这个风险是可接受的。4.5 常见问题速查表现象大概率原因处理思路模式切换没效果配置缓存未刷新检查是否调用reload确认配置对象mtimeprompt中代码不完整字符级硬切改用段落/代码块边界截断输入token超限估算口径偏差按模型usage字段反向校准估算系数回答频繁跑题min_score设置过低提高阈值检查是否有低分片段混入上下文组装耗时高候选未做预过滤增加关键词预过滤层压缩精细评分数量早期对话信息丢失衰减系数过小调高decay_factor或切换到replay模式5. 一点实操心得什么才是一个好用的上下文模式如果让我提炼一句做context-mode最重要的经验我会说上下文管理的本质是预算管理和信息分层你不可能把所有信息都塞进去但你可以让真正重要的信息始终在窗口里。模式的意义就是让这个过程感知到场景差异自动调整策略。实际做下来以后有几点心得值得分享。一是别追求“通用最优”auto模式确实能覆盖大多数情况但代码审查和长文档处理这类场景必须切replay基础问答才适合auto。二是上下文模块的日志和监控一定要从第一天就接上没有监控的话你怎么调参数都是盲猜。三是宁可少放一个片段也不要把片段截成半截子丢给模型这个教训花的代价挺大。如果你正在做类似的功能完全可以参考我上面讲的三种模式和那套三层架构先把候选采集、决策筛选、组装截断这三层逻辑搭出来再逐步丰富模式细节。配置参数的调整没有标准答案建议你先在auto模式下用默认参数跑上一段时间收集一些实际案例再针对性地做调整。我现在的方案也是这么迭代出来的每个参数背后都有一次真实问题的支撑。最后顺手补充一个很多人不太注意的小细节context-mode在设计时候还留了一个“强制保留区”的概念可以手动指定某些片段无论如何都必须在prompt里。这个功能在我处理紧急bug排查时特别好用——比如某个崩溃日志已经定位到了后面无论聊什么它都会固定出现在上下文里模型不会突然忘记它。如果你也经常和长会话打交道建议在你的实现里把这个保留机制加上它救场的频率比你想象得高。