ContextBuilder 上下文构建全解析：分层架构、动态预算与裁剪策略

1. 从零理解 ContextBuilder 到底在解决什么问题

1.1 一个真实场景引发的思考

假设你正在开发一个智能体系统，用户问了一句“帮我查一下上个月的销售数据，然后生成一份报告”。这句话背后涉及多少信息？用户的身份、权限、历史对话记录、当前时间、可用的工具列表、数据库连接信息、报告模板格式……如果把这些全部塞进一次请求里，上下文窗口瞬间就被撑爆了。

我在实际项目中遇到过更极端的情况：一个客服智能体需要同时处理用户画像、订单历史、产品知识库、对话记忆和工具调用结果。最初的做法是“能塞就塞”，结果就是每次请求的 token 消耗高得离谱，响应速度慢，而且模型经常被无关信息干扰，回答质量反而下降。

ContextBuilder 要解决的核心问题就是：在有限的上下文窗口内，动态组装出最相关、最精简、最有效的上下文信息。它不是简单的字符串拼接，而是一套有策略、有优先级、有裁剪逻辑的上下文管理机制。

1.2 ContextBuilder 在 Hello-Agents 中的定位

Hello-Agents 是一个智能体开发框架，它的设计哲学是“让开发者专注于业务逻辑，把上下文管理这种脏活累活交给框架”。ContextBuilder 就是这个哲学的具体体现。

你可以把它理解成一个“上下文装配车间”：原材料是各种来源的信息（系统提示词、对话历史、工具描述、外部知识、用户画像等），经过分拣、筛选、排序、裁剪、格式化等一系列工序，最终产出一个可以直接送给大模型的上下文对象。

这个组件的重要性在于，它直接决定了智能体的“智商上限”。上下文给得好，模型就能做出准确判断；上下文给得差，再强的模型也会胡言乱语。我见过太多项目把精力花在换模型、调温度上，却忽略了上下文构建这个真正的瓶颈。

1.3 谁需要关注这个组件

如果你正在做以下任何事情，ContextBuilder 的设计思路都值得你仔细研究：

• 开发多轮对话系统，需要管理对话历史
• 构建 RAG 应用，需要把检索结果和用户问题合理组合
• 做工具调用型智能体，需要动态注入工具描述和调用结果
• 优化 token 成本，希望在保证效果的前提下减少输入长度
• 处理长文档问答，需要在超长文本中提取关键片段

哪怕你不用 Hello-Agents 这个框架，理解 ContextBuilder 的设计原理也能帮你更好地设计自己的上下文管理模块。

2. ContextBuilder 的核心设计思路拆解

2.1 分层架构：为什么不能一锅炖

ContextBuilder 最核心的设计决策是分层。它把上下文信息按照来源和性质分成不同的层，每层有独立的构建逻辑和优先级。

我最初自己实现上下文管理时，就是简单地把所有信息拼成一个字符串。这种做法在简单场景下能用，但一旦信息源超过三个，就会变得难以维护。更麻烦的是，当上下文超长需要裁剪时，你根本不知道该砍哪部分。

Hello-Agents 的分层思路大致是这样的：

这个分层不是随便定的。系统层和工具层是智能体正常工作的基础，砍掉它们智能体就“失忆”了；对话层和知识层虽然重要，但可以根据 token 预算灵活调整；临时层的信息往往在下一轮就失效了，优先级最低。

注意：分层的关键不是层数多少，而是每层的“不可替代性”是否明确。如果你的系统里有两层信息可以互相替代，那说明分层设计有问题。

2.2 优先级与预算分配：token 到底该怎么花

有了分层，接下来要解决的是“每层分多少 token”的问题。ContextBuilder 采用了一种动态预算分配的策略。

具体来说，它会先计算一个总预算（比如模型上下文窗口的 80%，留 20% 给模型输出），然后按照优先级依次分配。系统层和工具层先拿够，剩下的再按比例分给对话层和知识层。

这里有个细节值得注意：预算分配不是静态的。如果当前轮次用户问的是一个需要大量知识检索的问题，知识层的预算就会自动增加；如果只是闲聊，对话层的预算就会更多。

我在自己的项目里借鉴了这个思路，实现了一个简单的动态调整逻辑：

def allocate_budget(total_budget, query_type): base_allocation = { "system": 0.15, "tools": 0.10, "memory": 0.15, "dialogue": 0.30, "knowledge": 0.30 } if query_type == "knowledge_heavy": base_allocation["knowledge"] += 0.15 base_allocation["dialogue"] -= 0.15 elif query_type == "chat": base_allocation["dialogue"] += 0.10 base_allocation["knowledge"] -= 0.10 return {k: int(total_budget * v) for k, v in base_allocation.items()}

这个逻辑虽然简单，但效果立竿见影。之前固定分配时，知识型问题的回答质量波动很大，改成动态分配后稳定了很多。

2.3 裁剪策略：砍掉什么比保留什么更难

当所有信息加起来超过预算时，就必须裁剪。ContextBuilder 的裁剪策略遵循几个原则：

第一，整段裁剪优于截断。一条对话记录要么完整保留，要么整条删除，不要保留半条。半条对话会让模型产生误解，以为用户只说了半句话。

第二，按时间倒序裁剪。对话历史从最旧的开始删，因为最近几轮对话通常和当前问题最相关。

第三，保留关键节点。如果对话历史中有工具调用记录，这些记录即使比较旧也要尽量保留，因为它们包含了事实性信息。

第四，知识片段按相关性分数裁剪。检索回来的知识片段通常带有相关性分数，分数低的先删。

我踩过的一个坑是：早期我按字符数截断，结果把一条工具调用记录截成了两半，模型看到残缺的 JSON 直接崩溃了。后来改成整段裁剪，问题就解决了。

2.4 格式化输出：让模型看得懂才是好格式

ContextBuilder 最后一步是把组装好的上下文格式化成模型能理解的格式。这里有几个讲究：

• 角色标记要清晰：system、user、assistant 的边界必须明确
• 工具描述用结构化格式：JSON Schema 比自然语言描述更不容易被误解
• 知识片段加来源标记：让模型知道哪些是检索来的，哪些是对话内容
• 重要信息前置：把最关键的指令放在最前面，避免被长文本淹没

我实测下来，同样的内容，格式化方式不同，模型的理解准确率能差 20% 以上。特别是工具调用场景，用 JSON Schema 描述工具参数比用自然语言描述，调用成功率明显更高。

3. 核心细节解析与实操要点

3.1 系统提示词的构建技巧

系统提示词是 ContextBuilder 输出的第一层，也是最重要的一层。它决定了智能体的“人设”和能力边界。

在 Hello-Agents 中，系统提示词的构建不是简单写一段话，而是由多个模块拼装而成：

1. 角色定义：你是谁，你擅长什么
2. 能力声明：你能调用哪些工具，有什么限制
3. 行为规范：遇到什么情况该怎么处理
4. 输出格式要求：回答的结构和风格

我建议把系统提示词拆成独立的模板文件，而不是硬编码在代码里。这样修改起来方便，也便于做 A/B 测试。

SYSTEM_PROMPT_TEMPLATE = """ 你是一个{role}，专精于{domain}。 ## 你的能力 {capabilities} ## 行为规范 {guidelines} ## 输出要求 {output_format} """

填充这些变量时，要注意具体优于笼统。比如“你是一个助手”就不如“你是一个电商客服助手，专门处理退换货和物流查询问题”来得有效。

实操心得：系统提示词的长度控制在 500-800 token 比较合适。太短了约束力不够，太长了会挤占其他层的预算，而且模型对超长系统提示词的遵循度会下降。

3.2 对话历史的压缩与摘要

对话历史是最占 token 的部分，也是最需要压缩的部分。ContextBuilder 提供了几种压缩策略：

滑动窗口：只保留最近 N 轮对话。简单粗暴但有效，适合大多数场景。

摘要压缩：把较早的对话用模型总结成一段摘要。这个策略省 token，但摘要本身需要调用模型，有额外成本。

关键信息提取：从对话中提取实体、意图、槽位等结构化信息，丢弃原始对话。这个策略最省 token，但实现复杂度最高。

我在实际项目中用的是混合策略：最近 5 轮保留原文，5-15 轮做摘要，15 轮以上只保留提取出的关键信息。这样既保证了近期对话的完整性，又控制了总长度。

def compress_dialogue(history, recent_n=5, summary_n=15): recent = history[-recent_n:] to_summarize = history[-summary_n:-recent_n] to_extract = history[:-summary_n] summary = summarize(to_summarize) if to_summarize else "" key_info = extract_key_info(to_extract) if to_extract else "" return { "key_info": key_info, "summary": summary, "recent": recent }

3.3 工具描述的动态注入

工具调用型智能体有一个特殊需求：工具描述必须准确、完整地出现在上下文中，否则模型无法正确调用。

ContextBuilder 处理工具描述时，会做几件事：

• 按需注入：不是所有工具都一次性注入，而是根据当前对话意图筛选相关工具
• 格式统一：所有工具描述用统一的 JSON Schema 格式
• 示例补充：给每个工具配一个调用示例，降低模型的理解成本

我见过一个常见错误：工具描述写得太简略，比如“查询天气”四个字就完事了。模型根本不知道这个工具需要什么参数、返回什么格式。正确的做法是：

{ "name": "query_weather", "description": "查询指定城市的当前天气情况", "parameters": { "city": { "type": "string", "description": "城市名称，如'北京'、'上海'", "required": true }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius", "description": "温度单位" } } }

3.4 知识检索结果的去重与排序

RAG 场景下，检索回来的知识片段经常有重复或高度相似的内容。ContextBuilder 会做一轮去重和重排序。

去重用的是简单的文本相似度计算，相似度超过阈值的只保留分数最高的那条。重排序则是综合考虑检索分数、内容新鲜度、来源可信度等因素。

这里有个容易忽略的点：知识片段之间要有明确的分隔。如果直接把多段知识拼在一起，模型可能会把它们当成一段连续文本，导致理解偏差。我通常会用这样的格式：

[知识片段 1 | 来源：产品手册 | 相关度：0.92] 退换货政策规定，商品签收后 7 天内可无理由退货... [知识片段 2 | 来源：FAQ | 相关度：0.87] 退货时需要保持商品原包装完整...

来源标记不仅帮助模型区分不同片段，还能让模型在回答时引用来源，提升可信度。

4. 实操过程与核心环节实现

4.1 环境准备与基础配置

在 Hello-Agents 中使用 ContextBuilder，首先需要完成基础配置。假设你已经安装好了框架，接下来要做的是定义上下文层的配置。

from hello_agents import ContextBuilder, ContextLayer builder = ContextBuilder( max_tokens=8000, reserve_for_output=1500, layers=[ ContextLayer(name="system", priority=100, min_tokens=300), ContextLayer(name="tools", priority=90, min_tokens=200), ContextLayer(name="memory", priority=70, min_tokens=100), ContextLayer(name="dialogue", priority=60, min_tokens=500), ContextLayer(name="knowledge", priority=50, min_tokens=300), ] )

这里的max_tokens是模型上下文窗口大小，reserve_for_output是留给模型生成回答的空间。min_tokens是每层的最低保障，即使总预算不够，也要优先满足这些最低值。

配置完成后，你需要为每层注册数据源。数据源可以是一个函数、一个对象，或者一个静态值。

builder.register_source("system", lambda ctx: get_system_prompt(ctx.agent_role)) builder.register_source("tools", lambda ctx: get_tool_descriptions(ctx.available_tools)) builder.register_source("dialogue", lambda ctx: get_dialogue_history(ctx.session_id))

4.2 完整构建流程的代码实现

下面是一个完整的上下文构建流程，我把它拆成了几个关键步骤，方便你理解和复现。

第一步：收集原始信息

def collect_raw_context(builder, context): raw = {} for layer in builder.layers: source = builder.sources.get(layer.name) if source: raw[layer.name] = source(context) return raw

第二步：计算各层预算

def calculate_budgets(builder, raw_context, query_type): total = builder.max_tokens - builder.reserve_for_output budgets = {} # 先满足最低保障 remaining = total for layer in sorted(builder.layers, key=lambda l: -l.priority): budgets[layer.name] = min(layer.min_tokens, remaining) remaining -= budgets[layer.name] # 剩余预算按优先级和查询类型分配 if remaining > 0: weights = get_weights(query_type) for layer in builder.layers: extra = int(remaining * weights.get(layer.name, 0)) budgets[layer.name] += extra return budgets

第三步：按预算裁剪每层内容

def trim_layer_content(content, budget, layer_name): if layer_name == "dialogue": return trim_dialogue(content, budget) elif layer_name == "knowledge": return trim_knowledge(content, budget) else: return trim_generic(content, budget)

第四步：格式化并组装

def format_and_assemble(trimmed_context): parts = [] if "system" in trimmed_context: parts.append({"role": "system", "content": trimmed_context["system"]}) # 工具描述和知识片段合并到系统消息或单独的用户消息中 if "tools" in trimmed_context: parts.append({"role": "system", "content": format_tools(trimmed_context["tools"])}) # 对话历史按角色展开 for turn in trimmed_context.get("dialogue", []): parts.append({"role": turn["role"], "content": turn["content"]}) # 知识片段作为额外的上下文注入 if "knowledge" in trimmed_context: knowledge_text = format_knowledge(trimmed_context["knowledge"]) parts.insert(-1, {"role": "user", "content": knowledge_text}) return parts

4.3 参数调优的实操记录

上面这些代码看起来简单，但真正跑起来之后，参数调优才是重头戏。我记录了一次典型的调优过程。

初始配置：max_tokens=8000，各层 min_tokens 设置得比较平均。

问题：知识型问题的回答质量不稳定，有时候很好，有时候答非所问。

排查：打印了每次构建后的各层实际 token 占用，发现知识层经常被对话层挤占，实际分配到的 token 不到 200。

调整：把知识层的 min_tokens 从 300 提高到 800，同时把对话层的 min_tokens 从 500 降到 300。

结果：知识型问题的回答准确率明显提升，但闲聊场景下对话连贯性略有下降。

再调整：引入查询类型判断，知识型问题给知识层加权，闲聊给对话层加权。

最终配置：

这套配置在我的场景下跑了两周，效果稳定。当然，你的场景可能需要不同的参数，关键是理解调优的思路：先保证底线，再按场景动态分配。

4.4 与智能体主循环的集成

ContextBuilder 最终要集成到智能体的主循环中。在 Hello-Agents 里，这个集成点通常在每次调用模型之前。

class MyAgent: def __init__(self): self.context_builder = ContextBuilder(...) self.llm = LLMClient(...) def run(self, user_input, session_id): # 更新对话历史 self.memory.add_user_message(session_id, user_input) # 判断查询类型 query_type = classify_query(user_input) # 构建上下文 context = self.context_builder.build( session_id=session_id, query_type=query_type, agent_role=self.role, available_tools=self.tools ) # 调用模型 response = self.llm.chat(context) # 处理工具调用 if response.has_tool_call: tool_result = self.execute_tool(response.tool_call) self.memory.add_tool_result(session_id, tool_result) # 递归调用，把工具结果纳入上下文 return self.run(user_input, session_id) self.memory.add_assistant_message(session_id, response.content) return response.content

这个集成方式的关键点是：每次模型调用前都重新构建上下文，而不是复用上一次的。因为对话历史、工具结果、检索知识都可能发生变化，复用会导致信息不一致。

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

5.1 上下文超长导致的截断问题

现象：模型回答突然变得不完整，或者忽略了系统提示词中的关键指令。

原因：上下文总长度超过了模型窗口，ContextBuilder 的裁剪逻辑把重要信息砍掉了。

排查步骤：

1. 打印构建后的上下文总 token 数，确认是否接近或超过 max_tokens
2. 打印各层的实际 token 占用，找出哪一层超了
3. 检查该层的裁剪逻辑是否合理

解决方案：

• 如果是对话层超了，调整滑动窗口大小或启用摘要压缩
• 如果是知识层超了，降低检索返回的片段数量或提高相关性阈值
• 如果是系统层超了，精简系统提示词，去掉冗余描述

我遇到过一次比较隐蔽的情况：工具描述层超了，因为某个工具的 JSON Schema 写得特别详细，光参数说明就占了 500 token。后来把参数说明精简了一半，问题解决。

5.2 模型忽略工具描述不调用工具

现象：明明在上下文中注入了工具描述，模型却直接回答而不调用工具。

原因：工具描述的位置或格式不对，模型没有“注意到”它。

排查技巧：

• 检查工具描述是否在系统消息中，而不是在用户消息中
• 检查工具描述的格式是否统一，有没有混用自然语言和 JSON Schema
• 检查工具描述是否被其他长文本“淹没”了

我的经验：工具描述最好放在系统提示词的最后部分，紧挨着对话历史。这样模型在生成回答时，工具描述还在它的“注意力范围”内。如果放在最前面，经过几千 token 的对话历史后，模型可能已经“忘了”有哪些工具可用。

5.3 知识检索结果与对话历史冲突

现象：模型回答时混淆了检索到的知识和对话中提到的信息，给出了矛盾的回答。

原因：知识片段和对话历史没有明确区分，模型把它们当成了同一来源。

解决方案：

• 给知识片段加上明确的前缀标记，如“以下是从知识库检索到的信息”
• 在系统提示词中说明：当知识库信息与对话历史冲突时，以知识库为准（或反之）
• 如果冲突频繁，考虑在检索前先做一轮对话历史的关键信息提取，用提取结果去检索

5.4 常见问题速查表

5.5 几个容易被忽略的细节

细节一：token 计算要用模型对应的 tokenizer。不同模型的 tokenizer 不一样，用 GPT 的 tokenizer 算 Claude 的 token 数会有偏差。Hello-Agents 支持配置 tokenizer，建议按实际使用的模型来配。

细节二：预留输出空间要足够。我一开始只预留了 500 token 给输出，结果模型回答到一半就被截断了。后来改成预留 1500-2000 token，问题解决。具体留多少，取决于你的场景需要多长的回答。

细节三：空层也要占位。如果某一层没有内容（比如没有检索到知识），不要直接跳过，而是注入一个空标记或默认值。这样模型能感知到“这一层是空的”，而不是“这一层不存在”。

细节四：定期清理长期记忆。长期记忆层如果只增不减，迟早会撑爆预算。建议设置一个过期策略，比如 30 天前的记忆自动归档或删除。

6. 进阶优化与扩展思路

6.1 基于反馈的动态调优

ContextBuilder 的参数不是一次调好就完事了。我在项目中加了一个简单的反馈收集机制：每次模型回答后，用一个轻量级的评分模型给回答质量打分，然后把分数和当时的上下文配置关联起来。

积累几百条数据后，就能看出哪些配置组合效果更好。比如我发现，当知识层 token 占比超过 40% 时，回答质量反而下降，可能是因为知识片段太多导致模型“选择困难”。后来把知识层的上限设在了 35%。

6.2 多模态上下文的扩展

如果你的智能体需要处理图片、音频等多模态输入，ContextBuilder 的分层架构也能扩展。只需要增加一个多模态层，在里面管理图片描述、音频转写文本等信息的注入。

关键点是：多模态信息的 token 消耗通常比纯文本高得多，所以预算分配要更谨慎。我的做法是，多模态层默认只保留最近 1-2 个模态输入，更早的只保留文本摘要。

6.3 缓存机制的引入

ContextBuilder 的构建过程有一定的计算开销，特别是涉及摘要生成和相关性排序时。如果同一个 session 在短时间内多次调用，可以考虑缓存构建结果。

缓存的失效条件要设计好：对话历史变化、工具列表变化、检索知识变化时，缓存都要失效。我通常用 session_id + 最后一轮对话的 hash 作为缓存 key。

这个内容后续还可以这样扩展：把 ContextBuilder 的构建日志接入监控系统，实时观察各层的 token 占用和裁剪情况，及时发现配置问题。我在生产环境里就是这么做的，效果很好，好几次在用户反馈之前就发现了上下文配置的异常。