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 中系统提示词的构建不是简单写一段话而是由多个模块拼装而成角色定义你是谁你擅长什么能力声明你能调用哪些工具有什么限制行为规范遇到什么情况该怎么处理输出格式要求回答的结构和风格我建议把系统提示词拆成独立的模板文件而不是硬编码在代码里。这样修改起来方便也便于做 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_n5, summary_n15): 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_tokens8000, reserve_for_output1500, layers[ ContextLayer(namesystem, priority100, min_tokens300), ContextLayer(nametools, priority90, min_tokens200), ContextLayer(namememory, priority70, min_tokens100), ContextLayer(namedialogue, priority60, min_tokens500), ContextLayer(nameknowledge, priority50, min_tokens300), ] )这里的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, keylambda 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 parts4.3 参数调优的实操记录上面这些代码看起来简单但真正跑起来之后参数调优才是重头戏。我记录了一次典型的调优过程。初始配置max_tokens8000各层 min_tokens 设置得比较平均。问题知识型问题的回答质量不稳定有时候很好有时候答非所问。排查打印了每次构建后的各层实际 token 占用发现知识层经常被对话层挤占实际分配到的 token 不到 200。调整把知识层的 min_tokens 从 300 提高到 800同时把对话层的 min_tokens 从 500 降到 300。结果知识型问题的回答准确率明显提升但闲聊场景下对话连贯性略有下降。再调整引入查询类型判断知识型问题给知识层加权闲聊给对话层加权。最终配置层级min_tokens基础权重知识型权重闲聊型权重system3000.150.150.15tools2000.100.100.10memory1000.100.100.10dialogue3000.300.200.45knowledge8000.350.450.20这套配置在我的场景下跑了两周效果稳定。当然你的场景可能需要不同的参数关键是理解调优的思路先保证底线再按场景动态分配。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_idsession_id, query_typequery_type, agent_roleself.role, available_toolsself.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 的裁剪逻辑把重要信息砍掉了。排查步骤打印构建后的上下文总 token 数确认是否接近或超过 max_tokens打印各层的实际 token 占用找出哪一层超了检查该层的裁剪逻辑是否合理解决方案如果是对话层超了调整滑动窗口大小或启用摘要压缩如果是知识层超了降低检索返回的片段数量或提高相关性阈值如果是系统层超了精简系统提示词去掉冗余描述我遇到过一次比较隐蔽的情况工具描述层超了因为某个工具的 JSON Schema 写得特别详细光参数说明就占了 500 token。后来把参数说明精简了一半问题解决。5.2 模型忽略工具描述不调用工具现象明明在上下文中注入了工具描述模型却直接回答而不调用工具。原因工具描述的位置或格式不对模型没有“注意到”它。排查技巧检查工具描述是否在系统消息中而不是在用户消息中检查工具描述的格式是否统一有没有混用自然语言和 JSON Schema检查工具描述是否被其他长文本“淹没”了我的经验工具描述最好放在系统提示词的最后部分紧挨着对话历史。这样模型在生成回答时工具描述还在它的“注意力范围”内。如果放在最前面经过几千 token 的对话历史后模型可能已经“忘了”有哪些工具可用。5.3 知识检索结果与对话历史冲突现象模型回答时混淆了检索到的知识和对话中提到的信息给出了矛盾的回答。原因知识片段和对话历史没有明确区分模型把它们当成了同一来源。解决方案给知识片段加上明确的前缀标记如“以下是从知识库检索到的信息”在系统提示词中说明当知识库信息与对话历史冲突时以知识库为准或反之如果冲突频繁考虑在检索前先做一轮对话历史的关键信息提取用提取结果去检索5.4 常见问题速查表问题现象可能原因快速排查方法解决方向回答不完整上下文超长被截断打印 token 数调整预算或压缩内容不调用工具工具描述位置/格式问题检查工具描述位置移到系统消息末尾回答矛盾知识/对话冲突检查是否有冲突信息加来源标记和优先级说明响应变慢上下文过长统计各层 token压缩对话历史或减少检索片段回答跑题系统提示词被淹没检查系统提示词位置精简其他层内容工具调用参数错误工具描述不清晰检查 JSON Schema补充参数说明和示例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 占用和裁剪情况及时发现配置问题。我在生产环境里就是这么做的效果很好好几次在用户反馈之前就发现了上下文配置的异常。 
长河君 · 2026/10/18 20:06:26 · 阅读 1.2k 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 中系统提示词的构建不是简单写一段话而是由多个模块拼装而成角色定义你是谁你擅长什么能力声明你能调用哪些工具有什么限制行为规范遇到什么情况该怎么处理输出格式要求回答的结构和风格我建议把系统提示词拆成独立的模板文件而不是硬编码在代码里。这样修改起来方便也便于做 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_n5, summary_n15): 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_tokens8000, reserve_for_output1500, layers[ ContextLayer(namesystem, priority100, min_tokens300), ContextLayer(nametools, priority90, min_tokens200), ContextLayer(namememory, priority70, min_tokens100), ContextLayer(namedialogue, priority60, min_tokens500), ContextLayer(nameknowledge, priority50, min_tokens300), ] )这里的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, keylambda 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 parts4.3 参数调优的实操记录上面这些代码看起来简单但真正跑起来之后参数调优才是重头戏。我记录了一次典型的调优过程。初始配置max_tokens8000各层 min_tokens 设置得比较平均。问题知识型问题的回答质量不稳定有时候很好有时候答非所问。排查打印了每次构建后的各层实际 token 占用发现知识层经常被对话层挤占实际分配到的 token 不到 200。调整把知识层的 min_tokens 从 300 提高到 800同时把对话层的 min_tokens 从 500 降到 300。结果知识型问题的回答准确率明显提升但闲聊场景下对话连贯性略有下降。再调整引入查询类型判断知识型问题给知识层加权闲聊给对话层加权。最终配置层级min_tokens基础权重知识型权重闲聊型权重system3000.150.150.15tools2000.100.100.10memory1000.100.100.10dialogue3000.300.200.45knowledge8000.350.450.20这套配置在我的场景下跑了两周效果稳定。当然你的场景可能需要不同的参数关键是理解调优的思路先保证底线再按场景动态分配。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_idsession_id, query_typequery_type, agent_roleself.role, available_toolsself.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 的裁剪逻辑把重要信息砍掉了。排查步骤打印构建后的上下文总 token 数确认是否接近或超过 max_tokens打印各层的实际 token 占用找出哪一层超了检查该层的裁剪逻辑是否合理解决方案如果是对话层超了调整滑动窗口大小或启用摘要压缩如果是知识层超了降低检索返回的片段数量或提高相关性阈值如果是系统层超了精简系统提示词去掉冗余描述我遇到过一次比较隐蔽的情况工具描述层超了因为某个工具的 JSON Schema 写得特别详细光参数说明就占了 500 token。后来把参数说明精简了一半问题解决。5.2 模型忽略工具描述不调用工具现象明明在上下文中注入了工具描述模型却直接回答而不调用工具。原因工具描述的位置或格式不对模型没有“注意到”它。排查技巧检查工具描述是否在系统消息中而不是在用户消息中检查工具描述的格式是否统一有没有混用自然语言和 JSON Schema检查工具描述是否被其他长文本“淹没”了我的经验工具描述最好放在系统提示词的最后部分紧挨着对话历史。这样模型在生成回答时工具描述还在它的“注意力范围”内。如果放在最前面经过几千 token 的对话历史后模型可能已经“忘了”有哪些工具可用。5.3 知识检索结果与对话历史冲突现象模型回答时混淆了检索到的知识和对话中提到的信息给出了矛盾的回答。原因知识片段和对话历史没有明确区分模型把它们当成了同一来源。解决方案给知识片段加上明确的前缀标记如“以下是从知识库检索到的信息”在系统提示词中说明当知识库信息与对话历史冲突时以知识库为准或反之如果冲突频繁考虑在检索前先做一轮对话历史的关键信息提取用提取结果去检索5.4 常见问题速查表问题现象可能原因快速排查方法解决方向回答不完整上下文超长被截断打印 token 数调整预算或压缩内容不调用工具工具描述位置/格式问题检查工具描述位置移到系统消息末尾回答矛盾知识/对话冲突检查是否有冲突信息加来源标记和优先级说明响应变慢上下文过长统计各层 token压缩对话历史或减少检索片段回答跑题系统提示词被淹没检查系统提示词位置精简其他层内容工具调用参数错误工具描述不清晰检查 JSON Schema补充参数说明和示例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 占用和裁剪情况及时发现配置问题。我在生产环境里就是这么做的效果很好好几次在用户反馈之前就发现了上下文配置的异常。