1. 消息组装这件事为什么值得单独拆出来讲如果你自己动手调过大模型接口大概率写过类似这样的代码把系统提示、用户问题和历史对话拼成一个字符串丢给模型。一开始只有两三个变量的时候直接 f-string 拼一拼没什么问题。但等到对话轮次变多、工具定义变复杂、同一个模板要服务不同场景的时候手工拼字符串的痛点就全冒出来了。Hermes 这个项目是某团队内部沉淀下来的大模型消息编排框架核心思路很简单所有发给模型的请求都不允许业务方直接拼字符串必须经过统一的 PromptAssembler 组装器。上一篇讲了整体架构和消息模型的基座这一篇就聚焦在最关键的环节——消息是怎么被一层层拼出来的以及为了让“拼”这个动作不那么昂贵提示缓存又是怎么设计和落地的。这一篇适合正在做 LLM 应用开发的工程师也适合那些已经在用各类编排框架、但想知道底层到底怎么运作的人。看完你会明白一个看似简单的“拼提示”动作背后藏着模板解析、变量作用域、渲染管线、缓存键设计这一整串工程问题。理解了这些你排查线上问题、做性能优化的时候思路会比别人清晰一大截。2. 提示组装的整体设计与思路拆解2.1 为什么不能继续用 f-string先聊一个最基础的问题为什么项目里不能继续用 f-string 拼提示f-string 在 Python 里确实方便但它有几个在工程上绕不过去的缺陷。第一转义问题。提示词里有大量花括号、引号、换行符比如 JSON 格式的工具定义。f-string 里想原样输出一对花括号你得写成{{}}一旦模板变长这种转义几乎无法维护。第二条件逻辑没法表达。真实场景里“如果用户上传了图片就追加图片描述块如果开了联网搜索就追加搜索结果的提示词”这类逻辑用字符串拼接写出来代码会迅速变成一坨 if-else 嵌套读起来非常痛苦。第三多模态消息支持不了。大模型接口早就不是纯文本了图片、音频、工具调用结果都要按特定结构组织。字符串拼接本质上是在拍平结构拍平之后信息就丢了。第四没法做缓存。字符串拼接是“过程式”的每次拼接的结果只存在于局部变量里。你想判断这次请求和上次请求的提示是不是一样得重新拼一遍才能比较成本极高。Hermes 做的最关键一个决定就是把“消息组装”从业务代码里整个剥离出来做成一个独立的渲染管线。业务方只需要声明“我要用哪个模板、传哪些变量”剩下的事情组装器全包了。2.2 组装器的整体架构整个 PromptAssembler 由四个核心组件构成模板仓库TemplateRegistry、渲染引擎TemplateRenderer、变量作用域管理器ScopeManager和消息构建器MessageBuilder。它们各自负责一段职责串起来就是完整流程。模板仓库管的是“有哪些模板可用”。每个模板有一个唯一 ID内部是结构化定义的节点树不是普通字符串。渲染引擎管的则是“模板节点怎么变成真实文本”它拿到变量之后逐个节点求值。变量作用域管理器解决的是变量从哪来的问题尤其是多轮对话场景下系统变量、用户变量、内部变量怎么隔离、怎么覆盖全靠它。消息构建器是最后一步把渲染好的文本按 role 封装成标准消息对象再塞进请求体。这套设计最聪明的地方在于模板是结构化的所以可以静态检查渲染是独立的所以可以单独测试变量作用域是显式的所以不会出现某个变量莫名其妙被改掉的问题。2.3 缓存模块的设计动机提示缓存要回答的问题很简单如果这次要发的消息和上次完全一样能不能不重新渲染一遍有人可能会问渲染一次能有多慢在纯文本场景下可能只有几毫秒。但一旦模板变得复杂比如包含几十个变量、多段条件块、工具定义、历史消息截断逻辑渲染时长会涨到几十毫秒甚至上百毫秒。而大模型应用里一次用户请求可能要多次调用模型——先规划、再执行工具、再总结每一轮都要组装提示。如果每次都全量渲染这部分开销会非常可观。更关键的是缓存的价值不只是在省渲染时间。当你在做 A/B 测试或者调试的时候能确认“这次请求的提示和上次完全一致”排障范围会大幅缩小。Hermes 的缓存模块把“渲染产物”缓存下来键是模板 ID 加变量哈希命中的话直接返回消息对象完全不碰渲染管线。3. 核心细节解析与实操要点3.1 消息模型与模板结构的对应关系在 Hermes 里消息模型是对齐业界标准 OpenAI 风格的核心字段是 role、content、name、tool_calls。模板结构并不是简单对应一个消息而是对应一个“消息序列”。举个例子一个典型模板可能定义成这样先是一条 system 消息里面包含系统设定和当前日期然后根据是否有对话历史插入若干条 user/assistant 消息最后是一条 user 消息放当前问题。模板节点树的根节点下挂多个 MessageNode每个 MessageNode 又包含若干内容节点。这里有个值得注意的设计细节模板里定义的不是“一条消息”而是“一个组”。组在渲染时可以根据变量条件展开成零条或多条消息。这样做的好处是模板可以表达非常复杂的对话结构而不是只能拼一条字符串。3.2 变量作用域的三层隔离变量作用域是提示组装里最容易出 bug 的地方Hermes 用的是标准的三层作用域模型。第一层是系统作用域存放全局常量比如当前日期、系统版本号、环境标识。这些变量由框架注入业务方改不了。第二层是请求作用域存放一次请求内的临时变量比如当前用户 ID、会话 ID、本次请求携带的上下文内容。第三层是模板局部作用域只在渲染某个模板时存在用来存中间计算结果。作用域解析的规则是从内往外找。模板局部作用域里找不到的变量去请求作用域找再找不到去系统作用域找。三层都找不到才会报缺失错误。这个设计核心解决的是变量污染问题。没有作用域隔离的时候很容易出现一个模板里定义的变量被另一个模板意外覆盖的情况。有了隔离之后模板与模板之间是完全独立的渲染结果可预测。3.3 缓存键设计的关键考量缓存键设计是整个缓存模块最核心、也最容易写错的地方。我见过不少项目缓存命中率上不去查到最后都是键设计的问题。Hermes 的缓存键由五个部分拼接而成模板 ID、模板版本号、核心变量哈希、上下文变量哈希、模型参数签名。前两个好理解模板变了缓存必须失效。第三个和第四个的区别在于核心变量是会直接影响提示文本内容的变量比如用户的问题、系统设定里被动态替换的部分上下文变量是身份类信息比如用户 ID、会话 ID。为什么要拆开因为用户 ID 变了不代表提示文本变了但如果把它拼进键里缓存命中率会骤降。模型参数签名同样重要包括 temperature、max_tokens、response_format 这些采样参数。你想想同样的提示文本不同参数下发给模型模型的行为完全不一样。如果把这两类请求的缓存混在一起返回结果就是错的。4. 实操过程与核心环节实现4.1 渲染管线的完整流程实际跑一遍组装流程大概是这样的。业务方调用assemble(request)组装器先检查缓存命中则直接返回未命中则走完整渲染管线。第一步模板仓库按模板 ID 加载模板结构同时做版本校验。第二步渲染引擎把变量注入作用域管理器开始逐节点渲染。第三步渲染引擎产出“中间表示”这是一个纯文本的消息序列还没绑定具体协议。第四步消息构建器把中间表示转换成标准消息对象填充 role、content 等字段。第五步对消息序列做后处理——裁剪超长历史、或者给文本追加截断标记。第六步返回最终消息列表同时把结果写入缓存。这里面每一步都有细节。比如第三步渲染的时候遇到条件块会先求值条件表达式再决定走哪个分支遇到循环块会先确认迭代上限防止变量里塞进一个超长列表导致渲染出一个巨型提示。这些边界情况是提示组装框架和简单字符串拼接的本质区别。4.2 渲染引擎的代码级拆解渲染引擎是 PromptAssembler 的心脏它内部处理的不是干巴巴的字符串而是一套节点树。每个节点都实现同一个接口核心方法就一个render(context)。文本节点直接返回常量文本变量节点从作用域管理器取值条件节点先求值布尔表达式再渲染对应子分支循环节点则遍历集合对每个元素渲染一次子节点。整个引擎的骨架代码类似这样class RenderEngine: def __init__(self, scope_manager): self.scope_manager scope_manager def render_node(self, node, context): if node.type text: return node.content elif node.type variable: value self.scope_manager.resolve(node.name, context) return self._format_value(value, node.format_spec) elif node.type condition: expr_value self._eval_expr(node.expr, context) branch node.if_branch if expr_value else node.else_branch return self._render_children(branch, context) elif node.type loop: items self.scope_manager.resolve(node.collection, context) limited_items items[: node.max_iterations] return .join( self._render_children(node.body, context.enter_loop(item)) for item in limited_items ) return def _format_value(self, value, format_spec): if value is None: return if format_spec json: return json.dumps(value, ensure_asciiFalse) return str(value)这里有几个细节很值得玩味。_format_value里对 None 的处理是返回空字符串而不是抛异常。为什么因为很多模板变量是可选的没有值的时候就应该安静地渲染成空白。但对另外一些必填变量模板定义里会打上requiredTrue标记这类变量缺失时必须抛错宁可请求失败也不能把错误提示发给模型。limit_items[:node.max_iterations]这个循环上限设计是为了防止“模板注入式”的提示膨胀。想象一下如果某个集合变量来自用户输入里面有一万个元素循环块直接全量渲染提示文本可能直接打到几十万 token模型请求直接废掉。4.3 缓存模块的落地实现缓存模块的代码实现不算复杂但工程细节非常多。核心组件是 CacheStore 和 CacheKeyBuilder。CacheKeyBuilder 负责把请求参数变成标准哈希串。它的内部逻辑是先规范化变量字典——把变量按 key 排序JSON 序列化时保证固定顺序——再拼接模板信息最后取 SHA-256 摘要。规范化这一步非常关键Python 字典的插入顺序影响序列化结果如果不排序两个变量相同但插入顺序不同的请求会生成不同的缓存键直接浪费缓存空间。CacheStore 的实现用的是两级架构进程内 LRU 缓存加分布式缓存。进程内缓存用标准 LRU 算法容量默认 1024 条分布式缓存走 Redis键前缀带环境名和版本号。写入策略是写后直写渲染完成拿到结果后同步写进程缓存再异步刷到 Redis。有一点很多人会忽略缓存里的消息对象必须做深拷贝再返回给业务方。因为调用方拿到消息列表后可能会在列表里追加内容、修改 role 字段。如果不做拷贝改的就是缓存里那份共享数据下一次命中缓存的请求会拿到被污染的消息。这个 bug 非常隐蔽排查起来极其痛苦。class PromptCache: def __init__(self, local_store, remote_store): self.local local_store self.remote remote_store def get(self, key): cached self.local.get(key) if cached is not None: self.local.touch(key) return copy.deepcopy(cached) cached self.remote.get(key) if cached is not None: self.local.put(key, cached) return copy.deepcopy(cached) return None def put(self, key, messages): immutable self._freeze(messages) self.local.put(key, immutable) self.remote.set(key, immutable, ttl600)注意_freeze这个动作。写入缓存之前消息对象会被转成不可变的形式通常是元组和冻结字典。这么做的目的和取出时深拷贝是对应的写入时冻结防止内部缓存被意外修改取出时复刻防止外部修改污染共享实例。4.4 消息构建器的后处理逻辑消息构建器的后处理是一个容易被低估的环节。模板渲染出来的消息序列在发给模型之前还要过几道关卡。第一道是长度控制。对话历史可能超过模型的上下文窗口构建器要按照消息级和 token 级两种维度做裁剪。消息级裁剪是简单粗暴的——从最旧的历史消息开始丢直到消息数低于阈值。token 级裁剪则要借助 tokenizer 对文本做估算超长就截断。这里的工程细节是裁剪要优先保底层逻辑最后一条用户消息绝对不能动系统消息原则上不动。第二道是角色合并。连续两条相同 role 的消息可以合并成一条中间用换行符隔开。这个优化一方面减少请求体大小另一方面也让模型更专注。第三道是工具调用结果格式化。工具执行完返回的是结构化 JSON构建器会把 JSON 转成标准文本块再拼到对应 role 的消息里。这个环节出错率最高因为不同模型对工具结果格式的要求不一样模板层的抽象会把差异屏蔽掉构建器层再按目标模型做适配。5. 常见问题与排查技巧实录5.1 缓存命中率为什么一直上不去这是上线之后最常遇到的问题。排查时我一般按顺序查三个地方。先看变量键是不是混入了不必要的维度。比如把 request_id 这种每次请求都不同的字段加到了核心变量里那缓存永远不可能命中。解决方法是检查 CacheKeyBuilder 里到底哪些变量参与哈希那些不直接影响提示文本的变量一律从键里摘掉。再看模板版本是不是频繁变动。如果发版很勤快模板版本号每次都变那缓存基本就是摆设。这种情况建议把模板版本和代码版本解耦模板变更走独立的发布流程尽量集中批量更新而不是每改一个字就升一次版本。最后看作用域解析是否稳定。如果同一个变量在多次请求里解析结果不同缓存键自然不同。最常见的坑是时间类变量模板里直接引用了当前时间。解决办法是把时间格式化操作放到系统作用域里并且按分钟粒度缓存超过一分钟再去取新的。5.2 渲染结果里出现大段转义错误模板里要输出 JSON 示例时很容易出现花括号被错误解析的问题。因为模板语法本身用花括号做变量标记如果想输出一个 JSON 里的花括号就得用转义。排查这个问题的技巧是先在渲染产物的关键位置打点输出渲染后的中间表示不要直接看最终消息。因为消息构建器在后处理时会做角色合并、长度裁剪这些操作会掩盖原始渲染问题。Hermes 提供的调试模式可以打印完整的渲染树——每个节点渲染前的值、渲染后的值、以及变量解析来源。打开这个模式后你很快就能定位到是哪个节点出了问题。5.3 并发场景下缓存击穿某个冷门模板第一次被使用时如果瞬间来了大量并发请求缓存里没有数据所有请求都会同时触发完整渲染造成“缓存击穿”。解决办法是在渲染流程外面套一层进程级互斥锁。同一时间只有一个协程能进入渲染流程其他协程阻塞等待锁释放后重新查缓存。分布式多实例部署时这类互斥锁扛不住所以缓存模块还支持分布式锁后端用 Redis 的 SETNX 实现。另外一个更轻量级的优化是“提前预热”。在服务启动阶段扫描近期常用的模板和典型变量组合预先渲染一遍并写入缓存。预热数据的来源可以从上一周期的线上日志里统计。5.4 快速排查速查表现象可能原因排查方向缓存命中率低于 10%缓存键里混入请求维度字段检查 CacheKeyBuilder 的变量白名单渲染结果里变量显示为空白变量为 None 且未设置 required检查模板定义里的 required 标记同一模板不同模型返回差异大消息构建器适配模型配置不一致检查目标模型的适配器配置偶发性超时分布式缓存热点键打爆 Redis检查缓存键是否过于集中消息内容被截断长度控制策略太激进调整消息级裁剪阈值6. 性能优化与后续扩展空间6.1 渲染性能调优的三个方向第一是模板预编译。Hermes 的模板在加载时会做语法检查并且转换成内部节点树。如果每次渲染都走字符串解析开销会大得多。预编译之后渲染只需要遍历节点树性能能提升五到十倍。第二是变量懒求值。很多模板里定义了变量但具体渲染时可能走不到那个分支。Hermes 支持把变量声明成懒加载只有实际用到时才从数据源拉取。这在数据源是远程接口的场景下收益巨大省掉大量无效 IO 开销。第三是渲染结果复用。对于纯静态类型的系统消息模板里没有任何变量的节点渲染结果永远不变。这类消息可以在加载模板时就完成渲染后续直接复用。6.2 从“提示缓存”到“语义缓存”目前缓存模块做的是完全匹配键完全一致才命中。再往上走一步就是语义缓存——用向量化的方式判断两个提示文本是否等价等价就复用结果。这个方向成本高、收益也不一定正向因为语义等价和模型输出等价之间没有严格保证。我更倾向于把语义缓存用在对成本敏感的场景比如大批量离线打分任务而不太建议用在高实时交互场景。6.3 与可观测体系的结合提示组装这个环节非常值得埋点。至少应该记录四个指标组装耗时、缓存命中率、渲染耗时、模板变量缺失事件数量。这四个指标能直接反映系统的健康状况。组装耗时突然上涨可能是某个变量取值耗时变大缓存命中率下跌可能是模板频繁变更也可能是变量分布过于分散。我在实际项目里见过一次有意思的排查线上提示组装耗时从 5 毫秒涨到 80 毫秒查了半天发现是一个模板里引用了远程接口拉取数据而那个接口最近响应变慢。模板本身没变变量懒求值机制把这个远程调用延迟到了渲染阶段。如果没有这个指标监控这个问题可能要在用户反馈超时之后才能暴露。7. 写在最后的实操心得这套提示组装和缓存机制我前后在好几个项目里落地过。踩过几次坑之后我的体会是提示组装框架的价值不在“能拼字符串”而在“拼的过程可观测、可复用、可预测”。给正准备做类似模块的同学三个建议。第一从第一天就把模板做成结构化节点树别用纯字符串模板后面扩展条件块和循环块会省太多事。第二缓存键的拆分粒度一定要把“影响文本的变量”和“影响请求的元信息”分开这是缓存命中率的分水岭。第三调试模式一定要做渲染树打印功能在排查问题时能救你无数次。最后再分享一个小技巧缓存不仅是性能工具也是很好的排障工具。当你怀疑某个请求的提示被拼错了第一反应不应该是“重新渲染一次看看”而是先查缓存里存的是什么样的消息序列。因为缓存里存的是上一次实际渲染的完整结果是真正发到模型手里的东东比任何日志都可靠。