先交代一下背景。我最近用 Elastic Agent Builder 搭了一个跑在本地模型上的 AI 代理助手核心目的就一个——让代理学会自己管理上下文。前前后后做了大概三周中间踩了不少坑也总算把方案的骨架给跑通了。今天这篇就当是这段时间的复盘不讲虚的全部是实际操作里验证过的细节。如果你也遇到过这几种情况——对话一长代理就“失忆”历史消息全部塞给模型显存直接爆掉或者费了半天劲调好的 Prompt在长会话下依然会把关键信息丢掉——那这篇记录应该对你有用。下面要聊的内容覆盖从整体设计、上下文管理策略、本地模型接入到常见问题排查基本是一条能直接照着做的路。1. 谁在管理上下文一个让我抓狂的老问题在搞这个项目之前我手上有好几个基于文本的 Agent 原型本来以为调好 Prompt 就完事了。直到有一次线上环境里出了一个特别诡异的现象用户连续问了几个问题之后代理居然把自己的名字都答错了。去翻日志才发现它在第 5 轮之后就已经把自己的角色设定给“挤”出了上下文窗口。那一刻我就意识到上下文管理不是靠调 Prompt 能解决的本质上是个工程问题。1.1 上下文失控的三个典型症状第一个症状是上下文爆炸。只要工具调用一多检索返回的原始文本、代码片段、临时变量、中间过程的思考记录全都会被拼进历史消息里。本来一两个问题只需要几百 token 的上下文跑着跑着就变成了两三千再跑一会儿就破万。有一次我图省事让工具把一整份日志文件的内容截断了直接返回给模型结果下一次请求时模型把所有日志又原封不动吐了出来整个会话当场卡死。第二个症状是关键记忆漂移。用户的偏好、项目的约束条件、之前已经确认过的决策这些信息往往只出现在某几轮对话里一旦后续对话内容变多它们就会被挤到上下文窗口之外。模型不是“忘记”了而是压根看不到这些内容了。最典型的场景是用户在第 3 轮说“以后所有回复都用表格输出”到第 20 轮时代理又开始输出大段文字你问它为什么不遵守它一脸无辜。第三个症状是 Token 成本失控。如果你接的是云端 API按 token 计费这个问题尤其明显。长对话里大量重复的历史内容被反复发送费用成倍上涨但模型并没有因此变得更好用。换成本地模型虽然不直接烧钱但本地模型的处理速度也会随上下文长度急剧下降显存占用更是肉眼可见地往上涨。1.2 为什么不能让开发者“手工管理”很多人第一反应是既然上下文会膨胀那我手动限制一个窗口大小不就行了比如只保留最近 20 条消息。这个方案我试过效果很差。原因在于上下文里最重要的往往不是最近的几条消息而是那些影响力长尾分布在对话各处的关键信息。固定窗口就像拿一把锯子截木头截完发现最关键的那段纹理正好被锯掉了。也有人会想到全量重放——每次请求都把历史消息完整带上。这在对话轮次少的时候还行一旦会话变长立刻就会撞上模型上下文窗口上限。而真正致命的问题是模型处理超长文本时注意力会被大量无关信息稀释对重点内容的敏感度反而下降。换句话说就算你疯狂喂历史模型记性也不会变好只会变笨。开发者手工维护一套复杂的上下文管理规则同样不现实。因为“什么信息重要”这件事本身是动态变化的同一个信息在用户问“我们刚才说的部署方案是什么”的时候是核心在用户问“帮我写一封邮件”的时候就完全无关。靠一系列 if-else 规则去覆盖这种变化规则会膨胀到根本维护不动。1.3 “自己管理上下文”到底意味着什么后来我想明白了一件事上下文管理不该是开发者给模型设定的死参数而应该是 Agent 运行时的一项自主能力。就像人不会把一天说过的每句话都记在脑子里但会记住重要的结论、待办事项和对方的偏好Agent 也应该具备类似的记忆管理机制。具体来说所谓“自己管理”就是让代理在运行过程中自动完成三件事。第一区分哪些信息值得长期保留哪些只是瞬时消息第二在上下文快满的时候主动把旧信息压缩成结构化的摘要而不是简单粗暴地截断第三每次处理新请求时从长期记忆里精确召回与当前任务相关的历史片段再决定如何组装 Prompt。这套思路落到实践里就是“AI 代理助手加本地模型”的组合。代理负责策略和编排本地模型负责理解和生成两者配合起来上下文管理才真正有了“自主”的样子。2. Elastic Agent Builder 整体设计先搭骨架再谈记忆在动手之前我把市面上能用的 Agent 编排工具过了一遍。最终选了 Elastic Agent Builder核心原因是它把“上下文策略”做成了可插拔的模块而不是把上下文管理逻辑焊死在框架内部。这对我来说很重要因为我不想要一个只能定死参数的黑盒工具我需要能随时观察到每一步上下文是怎么组装的。2.1 核心组件选型与职责划分整个项目最终的落地形态是“一个编排层 一个本地模型服务 一个向量记忆库 若干工具”各司其职。Elastic Agent Builder负责代理的行为编排、工具注册、上下文策略调度以及运行日志记录Ollama Qwen2.5 14B4bit 量化负责自然语言理解与生成承载真正的对话和推理Ollama 的 bge-m3 嵌入模型负责把文本转成向量用于记忆检索ChromaDB负责存储长期记忆的向量索引和原文按需召回一组自定义工具比如记忆写入工具、记忆检索工具、系统时间工具让代理能够主动操作自己的记忆。组件选型的逻辑是这样的。Agent Builder 解决的是“怎么编排”的问题本地模型解决的是“谁来思考”的问题向量库解决的是“信息存在哪”的问题工具解决的是“代理怎么动手”的问题。四者缺一不可但如果只挑一个最容易被低估的我选向量库。没有它上下文管理就只能停留在“压缩截断”的原始层面做不到真正意义上的“召回”。2.2 为什么我坚持接本地模型其实这个项目最开始打算直接接云端模型 API毕竟效果好、不用管部署。但后来我认真盘算了一下有三个现实原因让我改了主意。第一是数据隐私。项目里有一批业务数据不能出内网如果走云端 API意味着每次调用都要把会话历史传到外部服务器这个风险在这个场景里完全不能接受。换成本地模型后所有记忆读写、上下文组装、模型推理都在本机完成数据边界很清晰。第二是实验成本。用云端 API调试上下文策略的过程中每改一次策略就要重新跑一遍完整测试每跑一遍都是在烧钱。本地模型虽然速度慢一点但想怎么跑就怎么跑跑一晚上也不心疼这种自由度在开发调试阶段价值极大。第三是可控性。本地模型的上下文配置、量化方式、系统提示层面全部由我掌控出了任何问题都能直接看透。而云端模型的内部行为是一个黑盒出了问题只能等它自己转好或者去翻官方文档。配置上我用的是 Qwen2.5 14B 的 4bit 量化版本配合 bge-m3 做嵌入。这套组合在 24GB 显存的消费级显卡上跑得很从容上下文控制在 8K 以内时单轮响应稳定在两秒左右。如果你手里只有 16GB 显存换成 7B 或 8B 量化模型也一样能跑后文我会给出更具体的配置参考。2.3 项目目录与一次请求的流转项目结构保持得比较清爽核心内容全部集中在四个目录下agent-project/ ├── agent_definition.yaml # Agent 行为与上下文策略定义 ├── tools/ │ ├── memory_write.py # 写入长期记忆的工具 │ └── memory_search.py # 检索长期记忆的工具 ├── memory_drivers/ │ ├── chroma_driver.py # ChromaDB 存取实现 │ └── es_driver.py # 备用 Elasticsearch 向量实现 └── policies/ ├── summarization.py # 触发式压缩总结策略 └── recall.py # 记忆召回与过滤策略一次请求的流转过程大致是这样的。用户输入先进入 Agent Builder 的上下文组装器组装器根据当前策略做三件事检查是否需要触发摘要压缩、从长期记忆里检索相关片段、把全局摘要、召回记忆、最近对话按顺序拼装成最终的 Prompt。然后把 Prompt 发给本地模型模型生成结果如果过程中调用了工具工具返回的结果又会写回短期会话并判断是否有需要沉淀进长期记忆的内容。整个过程里最核心的环节就是组装器它是代理“自我管理上下文”真正落地的位置。3. 核心技术点三种策略让代理“自己”管理上下文我做这套系统的原则很简单不要让代理“感觉”自己在管理上下文而是要让策略机制在后台自动运转。代理不需要每次回复时都长篇大论地分析“我该记什么”它只需要在被工具调用时执行记忆操作。真正聪明的地方在策略层。3.1 策略一双优先级记忆池第一个策略是把记忆分成两个优先级不同的存储区。短期记忆池是一个环形缓冲区只保留最近 N 条对话消息这里是代理的“工作台”长期记忆池是一个向量数据库保存的是经过筛选的重要信息这里是代理的“档案柜”。什么时候把信息从工作台搬进档案柜我设计了一个写入触发器当一条消息满足“包含明确的决策结论、包含用户偏好、包含待办事项或下一步计划、被其他消息显式引用”这四种情况之一时就调用记忆写入工具把它拆成独立记忆条目存入向量库。这样做的好处是短期缓冲区的长度可以控制得很小。拿我的配置来说N 设置为 20 条也就是最近 20 轮以内的对话会全量保留再早的内容一律走压缩或检索不再直接出现在 Prompt 里。这个数字不是拍脑袋定的而是根据实测来的小于 15 条时代理经常丢失前面刚聊过的重要上下文大于 30 条时模型响应质量和速度都会下降。20 条是一个比较稳的中间值。3.2 策略二触发式压缩总结只有双优先级记忆池还不够因为短期缓冲区的 20 条消息也只是“临时缓存”一旦新消息进来旧消息就会被挤出去如果直接丢弃等于前面聊过的内容就彻底消失了。所以还需要一个压缩总结策略。我实现的触发条件是当短期缓冲区里的消息估算 token 数超过 3500 时自动触发一次压缩。压缩不是简单地把旧消息“缩短”而是调用本地模型把要淘汰的那批消息转换成结构化的摘要存档。摘要包含四个字段decisions已经达成的结论、preferences用户表达过的偏好、next_steps后续待办事项、other_facts其他值得保留的事实。用伪代码表示大概是这个样子def maybe_summarize(history, token_counter): current_tokens sum(token_counter(msg) for msg in history) if current_tokens SUMMARY_THRESHOLD: return history, None # 只压缩短期窗口里最旧的那一半 to_summarize history[:-RECENT_KEEP] remaining history[-RECENT_KEEP:] summary llm.summarize( messages[ {role: system, content: 将以下对话压缩为JSON包含decisions/preferences/next_steps/other_facts四个字段。}, {role: user, content: format_messages(to_summarize)} ] ) memory_store.save(global_summary, summary) return remaining, summary触发式总结的好处是它只在需要的时候才运行平时不会增加额外开销。同时因为只压缩“即将被挤出去”的旧消息最近的消息仍然保持原样所以代理对当前任务的即时理解不会因为压缩而变得迟钝。3.3 策略三召回、过滤与组装有了记忆池和摘要剩下来的问题就是新请求来的时候到底该从记忆库取什么内容、取多少、放在 Prompt 的什么位置。我实现了一个叫“recall_with_filter”的流程。首先用当前用户请求的文本做向量检索从长期记忆池里拉出 top_k 条最相近的记忆默认 k 是 5然后计算相似度分数低于 0.45 的直接丢弃最后把剩下的记忆和全局摘要、最近历史按固定顺序组装成 Prompt。组装顺序我反复试验了几轮最终确认的顺序是先放系统指令再放全局摘要然后放召回的长期记忆接着放最近 20 条历史最后是当前用户输入。这个顺序背后的逻辑是系统指令让模型明确角色全局摘要给它建立宏观背景召回记忆补充具体细节最近历史保证对话连贯当前输入触发最终回答。顺序一旦颠倒比如把召回记忆放到最近历史之后模型就更容易忽视记忆内容输出质量立刻打折。核心代码如下def assemble_prompt(request, agent_state): # 1. 召回长期记忆 memories memory_search(request, top_k5, min_score0.45) # 2. 读取全局摘要 summary memory_store.load(global_summary) # 3. 取最近历史 recent agent_state.history[-RECENT_KEEP:] # 4. 按固定顺序组装 blocks [] if summary: blocks.append((全局摘要, summary)) if memories: blocks.append((相关历史记忆, memories)) if recent: blocks.append((最近对话, format_messages(recent))) blocks.append((当前请求, request)) return render_blocks(blocks)3.4 本地模型在长上下文中是否撑得住很多人一听到“本地模型 AI 代理”就担心性能不够用我的实测结论是只要上下文管理做到位完全撑得住。在没有启用压缩策略时上下文长度经常跑到 8000 tokens 以上此时 Qwen2.5 14B 的推理速度会明显下降单轮响应可能要等四五秒启用三套策略之后上下文长度基本稳定在 3000 到 4000 tokens 区间单轮响应时间稳定在两秒左右体感好了不止一个档次。这背后的原因并不复杂。本地模型在推理时KV Cache 占用和计算量都会随上下文长度上涨尤其是超长上下文几乎每一步生成都要“回看”更多内容。所以让上下文保持精简不仅是在省钱省显存更是在直接提升响应速度。4. 实操复盘从零搭建一个会自我整理的本地 AI 代理理论讲了一大堆现在落地上来看具体做法。我会按实际动手顺序来写完全照着我这个步骤走基本可以复现一套能跑的方案。4.1 环境准备与模型拉取先确保本机装好了 Ollama然后用两条命令把模型拉下来ollama pull qwen2.5:14b ollama pull bge-m3qwen2.5 是用来对话生成的bge-m3 是用来生成嵌入向量的。两者并不冲突Ollama 支持同时运行多个模型。如果你显存紧张可以把 qwen2.5 换成一个 7B 或 8B 的量化版后续配置保持不变。Python 依赖方面我用的是 agent-builder、chromadb、ollama、requests 这几个库。安装命令pip install agent-builder chromadb ollama requests装完之后先验证一下 Ollama 的接口是否正常curl http://localhost:11434/api/tags能返回模型列表就说明环境没问题。4.2 编写 Agent 定义文件Elastic Agent Builder 允许我用一个 YAML 文件定义代理的整体行为包括模型地址、上下文策略和工具列表。下面是我实际在用的一个核心配置片段agent: name: local_context_agent model: provider: ollama base_url: http://localhost:11434 model_name: qwen2.5:14b temperature: 0.3 num_ctx: 8192 context_policy: recent_keep: 20 summary_threshold_tokens: 3500 memory_search_top_k: 5 memory_search_min_score: 0.45 tools: - memory_write - memory_search - get_current_time几个关键参数简单拆解一下。temperature 设为 0.3是为了让代理在工具调用和记忆操作时尽量稳定不要每次行为都不一样num_ctx 设为 8192是给模型的上下文窗口设置一个硬上限低于模型本身的极限可以防止显存被超长上下文突然击穿memory_search_min_score 设 0.45低于这个相似度的记忆不注入 Prompt避免无关信息干扰模型判断。4.3 实现上下文管理核心代码Agent 定义文件只是骨架真正干活的是三个 Python 模块记忆写入、总结压缩、召回组装。上面我已经给过总结和组装的核心代码下面补上记忆写入的实现思路。def memory_write(content, metadataNone): importance_rules { contains_decision: r决定|确认|采用|最终, contains_preference: r我喜欢|我习惯|不要|请务必, contains_todo: r下一步|待办|接下来|计划, } should_store any( re.search(pattern, content) for pattern in importance_rules.values() ) if not should_store: return embedding embed_text(content) memory_store.add( textcontent, embeddingembedding, metadatametadata or {}, )这里的逻辑很直接先用关键词规则快速判断一条消息值不值得长期保留值得就生成嵌入向量存入 ChromaDB。这个规则的优点是简单、可控、容易 debug缺点是有可能漏掉一些语义上重要但字面上没触发规则的信息。我的应对办法是把判断函数做成可扩展的接口后续如果发现漏得厉害可以换成让模型来判断但实测下来关键词规则已经覆盖了 90% 以上的场景没必要给每一次对话都加一次模型调用。4.4 启动与效果对比按上面的流程把所有模块跑通后我做了几轮完整的压力测试模拟了一个持续 50 轮左右的深度对话。测试结果很能说明问题指标未启用上下文管理启用上下文管理平均上下文长度约 8200 tokens约 3400 tokens单轮平均响应时间约 4.7 秒约 1.9 秒关键信息丢失次数6 次1 次显存峰值占用约 19GB约 14GB上下文长度直接降了约 58%响应时间缩短了一半以上显存占用也有明显回落。最关键的是“关键信息丢失次数”从 6 次降到了 1 次剩下这 1 次还是因为测试里用户提到过一个特别冷门的偏好在向量召回时相似度没有达到阈值。这个后续可以通过适当降低阈值或增加 top_k 来进一步优化。5. 实测中踩过的坑与排查思路方案跑通不等于问题清零。实际上我在这个项目里踩的坑比想象中多得多很多问题都要花上大半天才会找到根因。这部分挑几个最典型的记录下来当一份问题速查表用。5.1 上下文越长越慢乃至显存溢出这是最开始最让人头疼的问题。本地模型的推理速度和上下文长度高度相关一旦上下文超过 8000 tokens响应时间会陡增如果同时开了多个并发会话显存直接爆掉OOM 崩溃是家常便饭。排查思路也很直接第一把 num_ctx 硬上限调低比如限制到 8192防止单次会话无限制吃显存第二启用触发式压缩让上下文长度在接近上限之前就被压回去第三给模型用 4bit 或更低比特的量化版本在保证效果基本不变的前提下大幅降低显存占用。5.2 摘要压缩后丢失用户偏好启用压缩策略之后我很快发现一个怪现象代理会忘掉用户前面表达过的偏好比如“以后回复控制在 200 字以内”。明明这些偏好已经写进了摘要但模型还是不当回事。后来我查了摘要内容发现问题出在“结构化不够”上。模型生成的摘要里偏好信息经常和其他内容混在一起或者表述太模糊。解决办法是把偏好单独做一个记忆类型不放进通用的全局摘要里而是作为独立的记忆条目存入向量库每次请求单独召回。这样一来偏好信息的召回率和执行率都明显提升。5.3 向量检索召回了大量无关记忆ChromaDB 的向量检索本身很灵活但灵活也意味着容易出问题。一开始我把 top_k 设成 10相似度阈值设成 0.3结果就是召回结果里混入了大量无关记忆。代理经常把以前聊过的某个不相关项目的信息错误地带入当前问题的回答里造成幻觉感很强的输出。排查下来两个参数都有问题。top_k 太大会把低相似度内容也拉进来阈值太低则漏进来一堆“勉强相关”的噪声。我把 top_k 调低到 5阈值提高到 0.45效果立刻改善。另外我还在召回后加了一步去重避免同一条记忆以多个相似变体同时出现在 Prompt 里。5.4 代理自己管理不等于黑箱最后想提醒一点让代理自己管理上下文不代表完全放手不管。代理做决策时仍然可能犯错比如把重要信息误判成不重要直接丢掉了。所以一定要给系统留出可观测性。我的做法是在组装器里加了一个日志开关每次请求都把最终生成的 Prompt 完整记录到本地文件。这样一来代理的任何“失忆”行为都可以追溯到具体原因是没召回到记忆还是召回后被过滤掉了还是组装顺序出了问题没有这个开关排查上下文问题就像在黑暗里找钥匙。5.5 常见问题速查表现象可能原因排查与解决代理遗忘用户偏好偏好未被单独存储偏好作为独立记忆条目不混入通用摘要上下文飞快爆满工具返回内容过大对工具返回做截断控制注入 token 量召回内容与当前问题无关top_k 或相似度阈值不合适调低 top_k调高相似度阈值本地模型响应越来越慢KV Cache 膨胀触发压缩降低 num_ctx代理输出重复内容历史中相同信息过多召回去重减少重复记忆注入压缩摘要过于笼统摘要提示词太泛要求结构化字段细化摘要维度做这个项目让我最有感触的一点是上下文管理不应该是一个事后补丁而应该是 Agent 里最核心的神经系统。以前总觉得“记忆”这件事只是把历史消息多留几条真正动手做了才发现里面涉及记忆分级、触发压缩、向量召回、Prompt 组装一整套机制每一步都会直接决定代理在长对话里是否靠谱。如果你也打算做类似的事情我建议不要一上来就追求复杂的方案先把“短期缓冲 触发总结 记忆检索”这三板斧跑通再根据业务场景逐项加细节。本地模型的选择也可以从 7B 级别起步先把工程链路打通再换更大的模型。这样踩坑成本最低迭代速度也最快。