企业官网建设流程全解析

想起前阵子做的一个内部工具，基于大模型的Agent系统，用来处理一堆散落的业务数据查询。最初版本简单到不能再简单：用户问一句，大模型答一句，看起来一切正常。但稍微用久一点就露馅了——用户在一个小时前刚确认过"数据源是内网库A"，隔一会儿再问，Agent已经完全不记得，又把同一个问题问了一遍。这种"金鱼记忆"放在真实使用场景里是致命的，用户会直接判定这个工具"不聪明""不靠谱"，再好的推理能力也救不回来。

后来我把项目演进成了 Easy Data × AI 这样的组合形态，重点就是在Agent开发里补齐了一套完整的分层记忆系统。这篇笔记就是把我在这个过程中的设计思路、代码骨架、踩过的坑，以及最后沉淀下来的调优经验做个梳理，给同样在做Agent开发的朋友一些参考。如果你正在做带多轮对话、工具调用或长期任务的Agent，这篇内容应该能帮你少走不少弯路。

1. 为什么Agent不能只靠大模型对话：记忆缺失的真实痛点

先说一个反直觉的结论：很多人以为大模型有"记忆力"，是因为它在对话里表现得像什么都记得。但实际开发中，大模型本身的API设计是无状态的——每次请求送到模型那边，它看到的只是本次请求里你塞给它的所有文本。它没有任何"上次聊过什么"的天然概念，所谓的记忆，完全要靠开发者在请求里主动拼装。

1.1 一个典型的失败场景

我最早试过最简单粗暴的方案：每次请求都把全部历史消息拼进prompt里。表面看没问题，但用了一周就崩了。场景是这样的：

用户让Agent帮忙分析某块业务报表，中间确认了三次数据口径，比如"最近30天""只统计已支付订单""排除测试账号"。这些确认信息都在对话历史里。当天一切正常，第二天用户继续问"把昨天的分析结论再跑一遍，顺便按渠道拆分"，Agent需要用到前一天确认过的口径。如果历史全量塞进去，它确实能找到；但对话轮数多了之后，上下文长度很快冲到几万token，每次请求的延迟从2秒涨到5秒，费用涨了快三倍。

更麻烦的是，当历史超过模型的上下文窗口上限，旧信息会被直接截断。我遇到过一次非常典型的事故：用户在第40轮对话时调整了统计口径，第50轮时Agent反而采用了更早的旧口径，因为早期消息虽然被截断了一部分，但恰恰留下了那句"按旧口径算"的片段。这种错误非常隐蔽，用户根本不知道是上下文截断导致的，只会觉得这个Agent不可靠。

1.2 上下文窗口不是记忆

很多人会把大模型的上下文窗口理解成"记忆容量"，这其实是个认知误区。上下文窗口更像是一张白板的大小——你在这张白板上能写多少字，模型就能"看到"多少字，但它并不会主动把这张白板保存下来供下次使用。而且窗口越大，模型对远端信息的注意力越弱。我实测过，超过一定长度之后，埋在最前面的约束条件经常被模型"忽略"，不是它不想遵守，而是在注意力机制里，遥远的文本本身的权重就已经衰减得所剩无几。

打个生活化的比方：上下文窗口相当于你办公桌上能摊开的纸张面积。记忆系统要解决的，不是把桌子换大，而是把真正重要的信息整理成"便签"，贴在随时看得见的地方，同时把旧文件归档到抽屉里，需要的时候再去翻找。

1.3 从"对话系统"到"带记忆的Agent"的思维转变

做Easy Data × AI 的时候，我最大的转变是把Agent从"单次问答机制"调整为"带状态的任务执行机制"。这里的关键认知是：Agent的一轮交互，不只是一次大模型调用，而是"感知—决策—执行—记录"的完整循环。

感知阶段，Agent要决定本次需要哪些记忆（用户偏好、历史结论、任务进度）。决策阶段，大模型根据当前输入和召回的记忆，决定调用哪个工具、执行什么动作。执行阶段，工具返回结果并被处理。记录阶段，系统判断本次交互中有哪些新信息值得写入记忆。

这四个环节里，记忆系统至少参与了三个：感知靠记忆召回，决策靠记忆辅助，记录靠记忆写入。所以这不是"加一个缓存"的问题，而是要把记忆当成Agent架构的一等公民来设计。想清楚这一点，后面的所有设计都会顺理成章。

2. Easy Data × AI 的Agent骨架：会话、任务与工具调度的耦合方式

开始写记忆系统之前，我得先把Agent的主干说清楚，因为记忆不是游离在外的辅助模块，它必须跟会话管理和工具调度紧密耦合。Easy Data × AI 的整体结构其实很常规，但有一个地方比较关键：所有外部工具调用都走统一的注册表，这样记忆系统才能完整观察到"Agent做了什么事、结果是什么"。

2.1 Agent主循环：一次完整请求的生命周期

一次用户请求的典型处理链路是这样的：

• 接收用户消息，连同session_id（会话标识）一起交给Agent核心。
• Agent核心向记忆系统发起召回，拉取与本次问题相关的历史记忆、用户偏好、任务状态。
• 构造系统提示词，把召回结果以"记忆卡片"的形式拼进上下文。
• 大模型产出决策，可能是直接回复，也可能是请求调用某个工具。
• 如果是工具调用，由工具注册表找到对应处理器，执行并返回结果。
• 结果再送回大模型继续推理，直到产出最终回复。
• 回复返回用户的同时，记忆系统异步分析本轮的对话内容、工具结果，决定哪些值得写入长期记忆。

伪代码大概长这样：

async def handle_user_message(session_id, user_text): # 1. recall memories memories = await memory_manager.recall( session_id=session_id, query=user_text, top_k=5 ) # 2. build prompt with memory context messages = build_messages(session_id, user_text, memories) # 3. main loop for step in range(MAX_STEPS): response = await llm.chat(messages, tools=TOOL_SCHEMAS) if response.has_tool_calls(): # execute tool outputs = await dispatch_tools(response.tool_calls) messages.append_tool_results(outputs) # 4. observe and write episodic memory await memory_manager.observe_tool_use( session_id, response.tool_calls, outputs ) else: final_reply = response.text break # 5. async write memory await memory_manager.async_extract_and_store(session_id, user_text, final_reply) return final_reply

这里有个容易被低估的点：工具调用的中间结果不能只放在"当次对话"里。如果一个工具调用依赖前一次调用的状态，比如先查用户列表、再查某个用户的订单，而Agent在一轮中只能完成一步操作，那么第二步发起时，第一步的结果必须已经从记忆里能找回来。这个稍后我单独讲，是个大坑。

2.2 工具注册表与任务状态的联动

工具注册表是我给Easy Data × AI 加的第三个核心组件。它的作用不只是"找函数"，更重要的是给每个工具定义元信息：工具名称、入参schema、执行时间预期、副作用等级（只读还是写操作）。这些元信息会被记忆系统用来判断"该记什么"。

举个例子，一个只读的"查询报表"工具，它的执行结果值得进短期记忆，因为用户可能会追问；但不必进长期记忆，除非结果本身形成了某种结论。而一个"修改配置"类的写操作，执行动作本身必须被记录，否则下次用户问"我上次改了什么"，Agent会完全无从答起。

我建议把工具注册表的schema也暴露给大模型，这样模型在决定调用工具时，能同时"看到"工具的语义。Easy Data × AI 用的就是标准函数调用协议，每个schema里除了参数定义，我还加了description和memory_hint字段，前者描述工具的用途，后者告诉记忆系统这个工具的结果倾向于短期还是长期留存。

2.3 记忆系统在链路中的插入点

很多框架把记忆做成"事后补丁"，插在对话之外，这是不对的。我的经验是记忆系统至少要在两个节点上做拦截：

第一个节点是"请求前召回"。这里必须同步阻塞，因为后续的提示词构造依赖召回结果，而一步步工具的继续运行也依赖这些。第二个节点是"请求结束后异步写入"。写入不能阻塞主流程，否则每一次对话都会因为记忆更新而变慢，用户能直观感知到卡顿。

这里有个性能细节可以分享：召回是延迟敏感操作，我最初用的是同步方式，一次召回耗时接近300ms，用户体验明显变差。后来把向量化提前、把召回分成"粗召回+精重排"两段，第一段用一个更快的近似最近邻算法，第二段才是余弦相似度精排，总耗时压到了80ms以内。异步写入则放在消息队列里，即使写入失败也不影响主流程的回复，只会在日志里留一条告警。

3. 记忆系统分层设计：工作记忆、短期记忆与长期记忆的边界划分

Easy Data × AI 的记忆系统最终采用了三层结构：工作记忆、短期记忆、长期记忆。这三层的关系，可以类比成你在写一篇长文章时的三种信息状态：摆在屏幕最前面的当前段落是工作记忆，手边一叠打印出来的参考材料是短期记忆，散落在硬盘深处但随时能搜索回来的备份文件是长期记忆。

3.1 三层记忆的职责与数据形态

工作记忆（Working Memory）只存在于单次请求生命周期里，用来存当前任务的临时状态：本轮对话的原始消息、工具返回的原始结果、正在计算的中间变量。它不需要持久化，请求完成即清空。但要注意的是，如果Agent在单次请求里有多步工具调用，工作记忆必须贯穿整个多步循环，而不是每一步重新初始化。

短期记忆（Short-term Memory）以会话为单位持久化。它存的是最近几轮对话的摘要、最近一次工具调用的输入输出、用户在当前会话里提到的偏好或临时约束。短期记忆的容量有上限，超过上限就做一次"压缩"，把老的内容用大模型总结成要点，腾出空间给新的。这条设计非常关键，它避免了早期那种"全部历史塞进prompt"的做法。

长期记忆（Long-term Memory）跨会话、跨用户实例持久化。它存的是用户的稳定画像、业务领域的固定规则、跨会话的重要结论。比如用户说过"我只看北美区域的数据"这类长期偏好；或者某次分析得出的结论性事实："Q2营收下降主要是欧洲渠道流失导致"。这些内容即使过了一个月，也应该在相关场景下能被召回。

3.2 记忆写入策略：什么该记、什么该丢

记忆系统的核心难题不是"怎么存"，而是"什么值得存"。写多了会污染，写少了会失忆。这是我反复调了很久才摸到门道的地方。

我当时定的写入策略，核心是三条过滤规则：

规则一：临时信息不写长期记忆。工具返回的完整JSON、一次性计算结果、用户随口说但马上改口的说法，都不进长期层。

规则二：结论优先于过程。用户说"以后报表都按自然月统计"，这是一条值得长期记忆的结构化偏好；但"帮我查一下6月的订单量"这种一次性请求，只进短期记忆就够了。

规则三：冲突信息必须标记。新信息和旧信息矛盾时，不能默默覆盖，要有版本标记，保证Agent在发现冲突时能向用户确认。

为了落地这三条规则，我在写入流程里加了一个"记忆提取器"。它不是简单地把整段对话存档，而是用大模型对本次对话做一次结构化提取，输出一个JSON：{"facts": [...], "preferences": [...], "task_state": {...}, "confidence": 0.0~1.0}。只有confidence超过阈值的条目才允许写长期记忆。这样就把"拒收垃圾内容"的负担交给了模型理解力，而不是靠正则和黑名单碰运气。

3.3 记忆冲突处理：新信息与旧记忆打架时怎么办

记忆冲突是我在真实使用中才意识到的问题。举个实际发生的例子：用户周一跟Agent说"以后数据都看最新口径"，周三又说"昨天那个口径不对，还是回归旧口径"。如果Agent不处理冲突，只把周三的话覆盖进去，用户可能遇到一个更隐蔽的问题——Agent在回答"你以前说要看最新口径"时，会把一条已经失效的旧偏好翻出来。

我的做法是给每条长期记忆加三个字段：created_at（创建时间）、source（来源会话）、status（active / superseded / revoked）。写入新记忆时，先用语义相似度把相关旧记忆找出来，如果相似度超过阈值且内容方向矛盾，就把旧记忆标记为superseded，而不是直接删除。召回时只返回status=active的记忆，这样模型不会看到互相矛盾的指令。

这套方案在内部测试里效果不错。唯一要注意的是"语义矛盾"的判断不能全靠向量距离，因为向量相似度高也可能只是话题接近。我在实验里试过，靠相似度判断冲突会有两成左右的误判率，所以现在会再加上一层轻量的规则确认，比如老记忆里如果包含明确的数值或日期，新记忆的相应数值不同，就强制标记为冲突，交给下一次交互时让用户确认。

4. 记忆写入与召回的实现细节：向量化、索引与过期策略

分层架构定了之后，具体实现里的细节才是真正磨人的地方。这一节我把记忆从写入到召回的全链路展开讲，包括向量化怎么做、索引怎么建、召回结果怎么组装成prompt的一部分、过期删除怎么才能不出问题。

4.1 向量化：模型选择与分块策略

向量化的目标是让语义相近的内容在向量空间里有相近的距离。我踩过的第一个坑是：直接用通用向量模型处理业务文本，效果非常差。业务文本里充满专有名词和行业缩写，通用模型对这些词的理解很浅。

我的建议是：如果没有条件训练专用模型，至少做到"分块"和"附带元信息"两步。分块的意思是不把一大段文本整体向量化，而是按语义切块。我用的是按段落切分加最长512字符截断，切出的每块在写入时同时存原文文本和向量。附带元信息的意思是，向量编码的不仅是文本本身，而是"文本 + 标签"的拼接，比如"偏好 | 统计口径 | 用户希望所有报表按自然月统计"。这个拼接能让召回时对"偏好"类信息的定位更准，实测top-5准确率能从70%提到85%以上。

嵌入模型我最初用的是通用型，跑了几天发现对业务查询的召回结果经常答非所问。后来换成了在业务语料上做过微调的版本，效果改善很明显——但这个属于有充足工程资源的情况。如果资源有限，退一步的选择是：不做全量微调，而是维护一个"业务实体同义词表"，在向量化之前把原文里的业务实体替换成标准表述，比如"上个月"统一替换成具体月份，"Q3"替换成"第三季度"。这个小技巧成本极低，但对召回效果的提升非常直接。

4.2 召回流程与上下文组装

召回流程的每一步都有优化空间。我最终稳定的流程是这样的：

1. 用户问题先做一次轻量改写：把指代词（"它""这个""那样"）替换成指代对象，把时间相对词（"昨天""上周"）解析成绝对日期。这一步不经过大模型，用规则加词典就能实现，耗时可忽略。
2. 改写后的文本做向量化，进向量库做近似最近邻搜索，取top-20候选。
3. 对top-20候选做精排，按余弦相似度降序，再叠加一个"时间衰减因子"，一般取score = cosine_sim - 0.1 * age_in_days。这个因子很重要，它是参考了信息衰减的常见规律加上的，能让近期记忆略微排前，防止三个月前的旧结论总是压过昨天的新信息。
4. 取精排后的top-5，格式化成语义连贯的"记忆卡片"文本，拼接到系统提示词的固定位置。

组装格式我调了几版，最后确定下来的是这种带来源和时间的结构：

【记忆卡片 - session: abc123, 3天前】 用户偏好：报表统计口径按自然月，排除测试账号。 来源：会话中用户明确说明。

卡片开头标注时间和来源，是有实际意义的。我最初直接贴原文，模型偶尔会把记忆当成当前对话内容，甚至在引用记忆时混淆时间先后。加了时间和来源标记之后，模型在引用时会更谨慎，幻觉率下降了一个肉眼可见的幅度。

4.3 过期、更新与"遗忘"机制

"遗忘"和记忆同样重要。长期记忆如果只增不减，整体召回质量会不断下降，因为向量库里的冗余信息会干扰最近邻搜索结果。

我设计的过期策略分三层：

• 短期记忆：按会话周期自动清理，会话结束或超过24小时无更新，摘要压缩一次，原始记录保留7天。
• 长期记忆的软过期：每条记忆带last_access_at，超过90天未被召回过的记忆会被打上"低频"标记，召回时优先级降低，但不删除。
• 长期记忆的硬删除：每30天做一次离线清理，把status=superseded且超过180天的记忆从向量库中物理删除。

硬删除有一个细节要提醒：向量库里的记录和关系型数据库里的结构化记录不是一一对应的，删除时要同时删两边的关联记录，否则会出现"向量能搜到、但详情已经没了"的悬浮脏数据。我在第一版就踩了这个坑，现象是召回结果里能看到记忆卡片，但点开卡片详情是空的，前后端都排查了很久才发现是两库不同步。

5. 踩坑记录：上下文膨胀、记忆污染与工具调用状态丢失

不管架构设计得多合理，实际运行里总会碰到设计阶段预想不到的问题。这一节是这篇笔记里最有价值的部分，因为每个坑我都花了不止一个晚上去排查，最后沉淀下来的经验，希望能让你少走弯路。

5.1 上下文膨胀：一次注入上千条记忆导致的效果崩塌

做第一版记忆召回时，我犯了一个冒进的错误：为了让Agent"记得更全"，把召回窗口从top-5加到了top-30。结果效果不但没提升，反而明显变差——模型开始在回答里反复引用互不相关的记忆卡片，甚至出现把A项目的数据结论安到B项目头上的情况。

排查后发现，这不是模型能力问题，而是记忆卡片的相互干扰。top-30里包含了大量只有表面相似、实际主题不同的记忆，模型在上下文里同时看到这么多"相关"信息，注意力被分散了，反而抓不住最关键的那一条。打个比方，你问一个人"昨天下午的会议几点开的"，他手边同时摆着十张时间表，反而更容易看错行。

最终我调整成"top-5硬召回 + 按需扩展"的方案：默认只给模型5张最相关的记忆卡片，只有当前任务确实需要更完整的历史背景时，才通过一次额外的"记忆追问"调用把候选扩展到top-15。这个改动让任务完成准确率回升了十几个百分点，也让我记住了一条铁律：召回数量宁少勿多，先保证精准，再考虑覆盖。

5.2 记忆污染：把临时计算过程写进了长期记忆

记忆污染的问题出在自动提取器上。我在早期版本里让大模型从每轮对话中提取"facts"，但没有严格区分"事实"和"临时过程"。结果很灾难——用户问"前三个月的订单量分别是多少"，提取器把"1月订单量100万、2月订单量85万、3月订单量92万"当成稳定事实写进了长期记忆。三个月后用户再问类似问题时，这些过期数字被当成"历史结论"召回，出现在回答里，用户一看数字不对，直接质疑系统数据源有问题。

修复思路后来我总结成一句话：只有跨多轮被确认过、或者由用户明确表述为"以后都这样"的内容，才值得进长期记忆。单轮出现的具体数字，默认只进短期记忆。我在提取器里加了提示词约束，要求模型区分stable_fact和transient_value两类输出，只有当stable_fact出现时才可以写长期记忆，transient_value一律走短期层。修改后，这类污染基本绝迹。

5.3 工具调用状态丢失：多步任务在记忆断层后的连锁失败

这是我踩过最深的一个坑。场景是Agent需要分三步完成任务：先查用户列表，再根据返回的用户ID查订单，最后汇总成报表。单轮里三步都能走完，看起来没问题。但当任务需要跨轮进行时——比如第一步在第一轮完成，用户在第二轮说"继续"——Agent在第二轮就完全不知道第一轮查出来的用户ID是什么了。

根因在于：工具调用返回的结构化数据默认放在了工作记忆里，而工作记忆在请求结束时就被清空了。短期记忆只存了摘要文本，没有存结构化数据的关键字段。于是第二轮开始时，Agent只知道"上次查了用户列表"，但不知道具体ID。

修复方案是在短期记忆里增加一个"任务状态槽"：工具清点的关键输出字段（如ID、名称、状态码）以结构化JSON的形式写入短期记忆，并且这个状态槽专门独立于对话摘要，不被压缩策略覆盖。实测修完之后，跨轮任务的成功率从不到60%提到90%以上。这个案例也让我意识到，记忆系统的设计不能只想着"记得住"，更要想着"用什么形式记、要不要结构化留存"，这两者的差别在关键时刻能决定系统能不能用。

6. 实测数据与参数调优建议

最后把Easy Data × AI 跑了两个多月的实测数据写出来，包括一组我用内部测试样本测出来的对比数据，以及最终稳定的参数配置。你可以把这些当成一个参考基线，具体数值还需要结合自己的业务场景调整。

6.1 一组有代表性的对比数据

我用内部测试集做了几轮AB对比，测试集包含200个任务样例，分四类：单轮事实查询、多轮偏好跟踪、跨轮多步任务、长期结论召回。结果如下表（数值按比例统计）：

可以看到，记忆系统的主要收益集中在多轮和跨长任务上，而单轮查询和"无记忆"的差距并不大，这也符合预期。如果你的场景单纯是"一问一答"，不必急着上复杂记忆系统；但只要有连续对话、有任务状态延续、有跨会话依赖，这套东西的价值立刻体现出来。

6.2 推荐的参数区间与配置参考

调优过程中参数基本都来回试过，最后稳定下来的是这几个区间：

• 长期记忆召回top-k：5-8，超过10会明显引入干扰。
• 短期记忆保留轮数：最近6-10轮对话，超出就触发摘要压缩。
• 记忆写入置信度阈值：0.75-0.8，低于这个值建议只进短期记忆。设太低了容易写入垃圾信息。
• 时间衰减因子：0.05-0.1/天，具体看业务对时效的敏感程度。金融类场景建议加大到0.15以上，而知识库类场景可以下调到0.02。
• 向量分块长度：256-512 token之间，太短则语义碎片化，太长则单条记忆被稀释。

这些参数不是拍脑袋定的，比如top-k我做了从3到30的阶梯测试，5-8是准确率和覆盖率交叉点的稳定区段。你可以用相似方式在自己的测试集上逐档扫描一遍，选斜率的拐点。

6.3 关于记忆系统的一句话经验复盘

如果只用一句话总结这段时间做Agent和记忆系统的体会，我会说：记忆系统不是一个被动的存储空间，而是Agent决策能力的一部分。设计时永远先问自己三个问题——这条信息如果不记得会发生什么？记住之后会不会误导未来的判断？新旧信息冲突的时候，模型该怎么选？把这三个问题想透了，架构上至少能避掉八成典型坑。

另外还有一件小事，但很实用：所有记忆写入、召回、冲突标记的操作，尽量留结构化日志。记忆系统的问题天然是"慢性的"，不会当场爆雷，而是过几天慢慢浮现。有日志，你在排查每个"模型为什么突然犯傻"的复现问题时，能省下大量翻数据的时间。我自己就是靠日志定位了至少五个隐藏bug，包括前面提到的两库删除不同步、旧记忆压过新信息之类。