企业官网建设流程全解析

如果你最近在折腾 AI 应用，大概率见过 context-mode 这个词。它被翻译成“上下文模式”，听起来像是一句废话，但真正落地时你会发现，这个模式决定了你的 AI 是“一个记忆只有几秒的话痨”还是“一个能帮你持续跟进复杂任务的靠谱助手”。我这次做的小项目就是围绕 context-mode 展开的：在一个面向团队内部知识库的 AI 问答助手里面，给对话系统补上一个真正可用的上下文管理模块。本文就把整个项目的设计思路、踩坑过程、核心代码和排查经验完整拆给你看，适合正在做 AI 应用、聊天机器人或者任何需要长期记忆能力的开发者参考。

1. 项目概述：context-mode 到底在解决什么问题

1.1 一个没有上下文的 AI 有多让人抓狂

先说一个最直观的场景。你问 AI“帮我总结一下上季度数据”，它回答得很漂亮，然后你又问“再按部门维度拆一下”，如果这个模型没有上下文模式，它大概率会反问你：“哪个上季度？拆什么数据？”这种体验放在文本对话里只是有点蠢，但如果放在客服机器人、销售陪练、代码辅助工具这类真实业务场景里，就是灾难级的低效。

我在做团队知识库问答助手的时候就遇到了同样的问题。一开始方案很简单：每次请求都只把用户当前这一句话发给大模型，不带任何历史信息。结果内部试运行第一天，就有人抱怨“这个助手像个金鱼”，既记不住之前聊到哪了，也没法结合前面的问题做追问。问题根子很清楚：大模型本身是无状态的，它每次收到的只是一个“文本快照”，你要让它“记得”，就必须在请求里主动携带相关历史信息。这个携带什么、带多少、怎么组织的过程，就是 context-mode 要承担的核心职责。

1.2 context-mode 的核心定位与适用场景

所谓 context-mode，本质上是给无状态的模型请求加一层“情境感知层”。它把对话历史、用户画像、业务知识片段、当前任务目标等信息，按照一定的策略组装进提示词，让模型在生成回答时能够站在“完整上下文”的视角，而不是只盯着当前这一句话。

这个模式在以下场景里几乎是刚需：

• 多轮对话类产品：客服机器人、销售辅助、心理咨询助手等，用户习惯连续追问，上下文断裂会直接导致回答无意义。
• 长文档问答：用户对一份几十页的合同或技术方案连续提问，每一轮都需要把相关段落重新带到上下文里。
• 代码生成与调试辅助：你在 IDE 里让 AI 先看报错，再让它改代码，它需要知道你在改哪个文件、哪个函数。
• 个性化场景：AI 已经跟用户聊了很多轮，记住了用户偏好，后续回答需要持续参考这些信息。

我这次做的知识库问答助手正好覆盖了前两种场景。项目命名为 context-mode，就是想把它做成一个独立的、可复用的上下文管理模块，而不是把一堆历史消息硬拼在一起塞给模型。

2. 整体设计思路与方案选型

2.1 三条设计原则：不过载、不丢失、可追溯

动手写代码之前，我给自己定了三条设计原则。第一是不过载，上下文不是越多越好，模型对提示词的容量有限，塞太多无关信息反而会稀释核心信号，还可能飙升 token 费用；第二是不丢失，关键信息比如用户第一次提出的核心诉求、已经确认过的事实，必须在整场对话中持续保留；第三是可追溯，每一条进入上下文的片段，最好能知道它来自哪轮对话、哪个文档段落，方便后面定位问题。

这三条原则看起来简单，实际上每一条都在后面踩坑时救了我。比如不过载这条，最初我天真地以为把最近 20 轮对话全部带上就行，结果遇到用户聊了几十轮之后，前面真正重要的指令被后面一堆闲聊淹没了，模型开始“忘事”。后来我改成“滑动窗口 + 关键信息持久化”的组合，才把这个问题解决。

2.2 方案选型：原生长上下文 vs 独立上下文管理模块

我评估过两条技术路线。第一条是直接依赖大模型的长上下文能力，比如某些模型支持高达 128K 甚至 200K 的上下文窗口，那我就把所有历史消息一次性全带上。这条路线实现最简单，但也有明显问题：费用高、响应慢、而且当上下文真的接近窗口上限时，模型对中间部分的记忆会明显变差，这个在业内已经有大量实验数据支持。

第二条路线是自建一个独立的上下文管理模块，也就是给系统加一个“记忆层”。这个模块负责决定哪些信息进上下文、哪些信息可以丢弃、哪些老内容需要先做摘要再放回去。这条路线实现复杂度高一些，但收益是可控的：费用可控、响应稳定、而且可以针对业务场景做精细化定制。

我最终选了第二条路线，原因是项目定位是给团队内部长期使用，每天有大量请求，token 成本必须紧绷着算。而且知识库问答这个场景天然需要结合文档检索结果，上下文的组织方式比纯聊天场景更复杂，自建模块的灵活性在这里是刚需。结论是：如果你只是做一个原型 Demo，走第一条路线完全没问题；如果要做长期运营的生产级应用，第二路线值得投入。

3. 核心实现细节与实操要点

3.1 上下文的分层结构与数据模型设计

我实现的 context-mode 把上下文分成四个层次，从核心到外围分别是：任务层、事实层、对话层、知识层。

任务层保存的是用户本次的核心目标，比如“帮我梳理这份产品需求文档里的风险点”，这一层在整个对话期间不会被丢弃，哪怕过了二十轮也要保留。事实层保存的是对话过程中已经确认的关键信息，比如“预算上限是五十万”“上线时间是下个月十五号”，这些信息一旦出现就会单独抽出来持久化。对话层就是最近这几轮的原始消息记录，采用滑动窗口机制控制数量。知识层则是从知识库检索出来的相关文档片段，每轮请求都会重新检索，主要跟着当前问题走。

数据模型我用了一个简单的上下文对象来承载这些信息，核心结构大致是这样：

@dataclass class TurnMessage: role: str # "user" 或 "assistant" content: str timestamp: float turn_id: str metadata: dict # 可附加业务信息，比如来源文档id @dataclass class ContextState: session_id: str task_goal: str | None # 任务层 facts: list[str] # 事实层 dialogue_history: list[TurnMessage] # 对话层 knowledge_snippets: list[dict] # 知识层

这个数据模型的要点是：每一层都是独立维护的，更新时机和淘汰机制各不相同。任务层在会话开始时初始化，中途只在用户明确改变了目标时更新；事实层在每轮解析出关键实体和确认信息时追加；对话层每轮追加新消息，同时按时间或轮次淘汰旧消息；知识层则完全由检索结果实时刷新。

3.2 滑动窗口与 token 预算的计算方法

对话层不能无限增长，所以我给整个 context-mode 设了一个 token 总预算。比如配置为 4000 个 token，其中任务层预留 200，事实层预留 600，知识层预留 1500，剩下的留给对话层。每次构造请求时，先填充任务层和事实层，再填充知识层，最后剩下的空间才分配给对话层。

分配对话层空间时，我采用的是“从最新往最旧填充”的策略。先把最近的一轮消息放进去，如果还有空间就放再往前一轮，直到空间耗尽。这样做的好处是，最新的追问往往关联最新的信息，而真正重要的老信息早就被提炼进事实层了，不需要依赖原始消息去保留。Token 数量的估算不能简单按字符数算，我用的方法是按模型的 tokenizer 对每段文本做真实编码统计，虽然慢一点，但预算控制精确，不会出现“以为塞得下，实际截断了”的问题。

这里有一个非常关键的实操细节：所有文本在放进入口队列之前，必须先把 Markdown 格式剥离、把多余换行压缩，否则这些看不见的字符会白占 token 预算。我第一次上线时没注意这个，结果有一轮对话因为文档里带着大量表格符号，预算直接被格式字符吃掉了四分之一，连核心问题都被截断了。

3.3 关键信息抽取与事实持久化策略

事实层的核心是从用户和模型的对话里自动抽取值得长期记住的信息。我实现了一个轻量版的抽取逻辑：每一轮对话结束后，把模型最近的回复和用户的发言一起交给一个专门的抽取提示词，让它输出结构化的事实列表。抽取规则包括“用户明确提到的约束条件”“双方确认一致的结论”“用户表达的个人偏好或身份信息”三类。

抽取出来的事实不会永远留在内存里，我把它持久化到了一个本地的 SQLite 数据库里，以 session_id 为维度做关联。这样即使服务重启，用户的会话上下文也能恢复，不会因为进程崩溃导致“聊到一半全忘了”。同时我加了一层去重机制，新抽取的事实会跟已有事实做相似度比对，语义重复的就不再重复写入，避免事实层被冗余信息占满。

4. 实操过程与核心代码实现

4.1 基础框架搭建与依赖选择

整个 context-mode 模块是用 Python 写的，框架用了 FastAPI 提供接口，模型调用统一封装在一个 LLMClient 类里，方便切换不同的模型服务。存储层用了 SQLite 加内存缓存双通道：内存缓存保证高频访问的速度，SQLite 保证重启不丢数据。

依赖方面我尽量精简，核心就三个：openai 的客户端库用于调用模型，tiktoken 用来做 token 统计，pydantic 用于数据模型校验。如果你需要用本地模型，也可以把 LLMClient 内部实现换成对应的客户端，接口层面不用动。

4.2 上下文管理模块的完整实现

上下文管理模块的核心是 ContextManager 类，它负责维护一个会话的全部状态，并在每次请求时构造最终的提示词。我先把核心代码贴出来，然后逐段说明关键逻辑。

import time from collections import deque from typing import Optional, Any class ContextManager: def __init__(self, token_budget: int = 4000, max_history_turns: int = 10): self.token_budget = token_budget self.max_history_turns = max_history_turns self.tasks: dict[str, Optional[str]] = {} # session_id -> 核心任务 self.facts: dict[str, list[str]] = {} # session_id -> 持久化事实 self.dialogue: dict[str, deque] = {} # session_id -> 对话消息队列 self.knowledge: dict[str, list[dict]] = {} # session_id -> 知识片段 def create_session(self, session_id: str, task_goal: str) -> None: self.tasks[session_id] = task_goal self.facts[session_id] = [] self.dialogue[session_id] = deque(maxlen=self.max_history_turns) self.knowledge[session_id] = [] def add_message(self, session_id: str, role: str, content: str) -> None: turn = { "role": role, "content": content, "timestamp": time.time(), "turn_id": f"{session_id}-{len(self.dialogue.get(session_id, []))}", } self.dialogue[session_id].append(turn) def extract_facts(self, llm_client: Any, session_id: str, user_text: str, assistant_text: str) -> None: prompt = f"""请从下面的对话中抽取需要长期记住的事实。 只抽取明确表述的信息，每行一条，格式为: 类别|内容。 类别只能是: 约束条件/确认结论/个人偏好/身份信息。 如果没有值得记录的事实，输出: 无。 用户说: {user_text} 助手说: {assistant_text}""" result = llm_client.complete(prompt) for line in result.strip().splitlines(): if line and line != "无" and "|" in line: category, content = line.split("|", 1) new_fact = f"[{category}] {content.strip()}" if new_fact not in self.facts[session_id]: self.facts[session_id].append(new_fact) def set_knowledge(self, session_id: str, snippets: list[dict]) -> None: self.knowledge[session_id] = snippets def build_messages(self, session_id: str, current_query: str) -> list[dict]: messages = [] system_parts = [] task_goal = self.tasks.get(session_id) if task_goal: system_parts.append(f"当前核心任务: {task_goal}") fact_list = self.facts.get(session_id, []) if fact_list: system_parts.append("已知关键信息:" + " | ".join(fact_list)) knowledge_snippets = self.knowledge.get(session_id, []) if knowledge_snippets: ctx_chunks = [] for idx, snip in enumerate(knowledge_snippets[:5], 1): ctx_chunks.append(f"[{idx}] {snip['content']}") system_parts.append("参考资料:\n" + "\n".join(ctx_chunks)) messages.append({"role": "system", "content": "\n\n".join(system_parts)}) for turn in self.dialogue.get(session_id, []): messages.append({"role": turn["role"], "content": turn["content"]}) messages.append({"role": "user", "content": current_query}) return messages

这段代码里有几个细节需要特别解释。第一，dialogue 用了 collections.deque 并设置 maxlen，这样新消息进来时最旧的消息会自动弹出，天然实现了滑动窗口。第二，事实抽取是在每轮对话结束后异步执行的，不阻塞用户当前这一轮的响应，避免增加用户可见的延迟。第三，build_messages 的组装顺序是固定的：先是系统级信息，再是历史对话，最后是当前问题，这个顺序在大多数模型上都比“历史在前、系统在后”的效果更稳定。

4.3 token 预算控制的实际代码

前面提到 token 预算需要精确计算，我单独写了一个函数来做这件事。它会在组装完 messages 之后，逐条统计每条消息的 token 数，如果超出总预算，就优先截断对话层的历史消息，而不是裁掉任务层或事实层的系统信息。

def truncate_messages(messages: list[dict], budget: int, tokenizer) -> list[dict]: system_content = messages[0]["content"] system_tokens = len(tokenizer.encode(system_content)) if system_tokens > int(budget * 0.5): raise ValueError("系统上下文占用超过预算一半，请压缩任务层或事实层内容") remaining = budget - system_tokens history = messages[1:-1] last_user = messages[-1] current_tokens = len(tokenizer.encode(last_user["content"])) remaining -= current_tokens kept_history = [] for turn in reversed(history): turn_tokens = len(tokenizer.encode(turn["content"])) if remaining - turn_tokens >= 0: kept_history.insert(0, turn) remaining -= turn_tokens else: break truncated = [messages[0]] + kept_history + [last_user] return truncated

这段代码的关键在于：当前用户的问题永远不会被截断，系统层的任务与事实永远不会被截断，只允许牺牲中间的历史对话。这样即使预算很小，系统的核心记忆也不会丢。实测下来，这个策略在上下文长度逼近上限时，回答质量下降的幅度远比“直接从头截断”要小。

4.4 效果验证与对比测试方法

项目做完之后，我专门设计了一组对比测试来验证 context-mode 的效果。测试分三组：A 组完全不携带上下文，B 组简单拼接最近 10 轮原始对话，C 组使用我实现的 context-mode 模块。测试问题是同一个“连续追问”场景，包含 6 轮递进式提问，最后问一个依赖早期信息的收尾问题。

结果很直观：A 组在第三轮开始出现答非所问，收尾问题完全答错；B 组前四轮表现良好，但由于早期关键信息被后续闲聊挤出了窗口，收尾问题也只答对了一半；C 组全程稳定，收尾问题完整答对，而且 token 消耗比 B 组少了约 35%。这个对比数据直接证明了我在 3.2 节说的核心观点：无脑堆历史并不是保留记忆的好办法，关键是把重要信息提炼出来单独维护。

5. 常见问题与排查技巧实录

5.1 上下文污染：模型被旧信息带偏

第一个遇到的典型问题是上下文污染。现象是：用户已经切换了话题，但模型还在引用前面话题里的内容回答，导致答非所问。排查下来发现原因有两个。一个是对话层滑动窗口保留的旧消息太多，新话题的消息还没把旧话题挤出去；另一个是事实层抽取太激进，把一次性的临时信息也当成了长期事实。

解决办法是在事实抽取逻辑里加了置信度判断：只有用户主动强调的、或者模型确认过两次以上的信息，才允许写入事实层。同时我把滑动窗口从单纯的“按轮次淘汰”改成了“按话题切换感知淘汰”，当检测到用户问题里的核心实体发生了明显变化时，主动清空对话层里与旧话题无关的消息。这个改动上线后，上下文污染的问题基本消失了。

5.2 响应延迟过高：事实抽取拖慢了整体链路

第二个问题是响应延迟。最初我在每轮对话的同步链路里直接做事实抽取，导致用户每发一条消息，系统都要先调用一次抽取模型，再调用一次回答模型，耗时翻倍。排查后发现这个设计很蠢：事实抽取的结果只影响后续轮次，完全不需要在当前轮等待它完成。

解决方案是引入异步任务队列。用户在收到回答后，事实抽取任务在后台执行，抽取结果写回 ContextManager。这里要注意并发安全，我加了按 session_id 的锁，避免同一个会话的多个并发请求同时写入事实列表导致重复或丢失。改完之后，用户体验回到了单次模型调用的延迟水平，事实抽取对用户完全透明。

5.3 问题排查速查表

我在项目验收阶段整理了一张问题排查速查表，遇到异常时对照着检查能省不少时间，也分享给你。

这张表是实战中总结出来的，每一行都对应一个真实踩过的坑。尤其是并发串扰这个，最开始我把上下文数据存成了模块级全局字典，结果两个用户同时测试时互相“看到”了对方的对话记录，排查了好几个小时才发现是共享字典没有按会话隔离。

5.4 一个值得分享的调试技巧

最后分享一个调试技巧。上下文类问题最麻烦的地方是“不可见”，你看不到模型到底收到了什么。所以我给 ContextManager 加了一个调试模式，会把每次 build_messages 生成的完整请求体落盘保存，文件名带上 session_id 和时间戳。出问题时直接翻这个日志文件，就能看到模型收到的原文到底是什么，问题出在截断、污染还是顺序，一目了然。

这个调试模式一开始我只在测试环境开了，后来生产环境也保留着，但只对指定的测试账号开启，普通用户不受影响。排查上下文相关问题时，这个日志帮我省掉了大量“猜谜”时间，强烈建议你也这么做。

6. 最后说两句实在话

context-mode 这个项目做完，我最大的体会是：上下文管理不是“把历史消息全带上”那么简单，它更像是一个记忆系统，需要区分什么该记、什么该忘、什么该优先保留。滑动窗口解决的是近因问题，事实抽取解决的是长期记忆问题，token 预算解决的是成本问题，这三者缺一不可。如果你也在做类似的应用，我建议不要迷信模型的超长上下文窗口，先想想你的业务里哪些信息是真正需要穿越整场对话保留下来的，然后把精力花在提炼和维护这些信息上。这个方向投入产出比极高，而且做出来的模块可以复用到你后面的每一个 AI 项目里。