企业官网建设流程全解析

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_ascii=False) return str(value)

这里有几个细节很值得玩味。_format_value里对 None 的处理是返回空字符串，而不是抛异常。为什么？因为很多模板变量是可选的，没有值的时候，就应该安静地渲染成空白。但对另外一些必填变量，模板定义里会打上required=True标记，这类变量缺失时必须抛错，宁可请求失败也不能把错误提示发给模型。

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, ttl=600)

注意_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 快速排查速查表

6. 性能优化与后续扩展空间

6.1 渲染性能调优的三个方向

第一是模板预编译。Hermes 的模板在加载时会做语法检查，并且转换成内部节点树。如果每次渲染都走字符串解析，开销会大得多。预编译之后，渲染只需要遍历节点树，性能能提升五到十倍。

第二是变量懒求值。很多模板里定义了变量，但具体渲染时可能走不到那个分支。Hermes 支持把变量声明成懒加载，只有实际用到时才从数据源拉取。这在数据源是远程接口的场景下收益巨大，省掉大量无效 IO 开销。

第三是渲染结果复用。对于纯静态类型的系统消息，模板里没有任何变量的节点，渲染结果永远不变。这类消息可以在加载模板时就完成渲染，后续直接复用。

6.2 从“提示缓存”到“语义缓存”

目前缓存模块做的是完全匹配，键完全一致才命中。再往上走一步就是语义缓存——用向量化的方式判断两个提示文本是否等价，等价就复用结果。这个方向成本高、收益也不一定正向，因为语义等价和模型输出等价之间没有严格保证。我更倾向于把语义缓存用在对成本敏感的场景，比如大批量离线打分任务，而不太建议用在高实时交互场景。

6.3 与可观测体系的结合

提示组装这个环节非常值得埋点。至少应该记录四个指标：组装耗时、缓存命中率、渲染耗时、模板变量缺失事件数量。这四个指标能直接反映系统的健康状况。组装耗时突然上涨，可能是某个变量取值耗时变大；缓存命中率下跌，可能是模板频繁变更，也可能是变量分布过于分散。

我在实际项目里见过一次有意思的排查：线上提示组装耗时从 5 毫秒涨到 80 毫秒，查了半天发现是一个模板里引用了远程接口拉取数据，而那个接口最近响应变慢。模板本身没变，变量懒求值机制把这个远程调用延迟到了渲染阶段。如果没有这个指标监控，这个问题可能要在用户反馈超时之后才能暴露。

7. 写在最后的实操心得

这套提示组装和缓存机制，我前后在好几个项目里落地过。踩过几次坑之后，我的体会是：提示组装框架的价值不在“能拼字符串”，而在“拼的过程可观测、可复用、可预测”。

给正准备做类似模块的同学三个建议。第一，从第一天就把模板做成结构化节点树，别用纯字符串模板，后面扩展条件块和循环块会省太多事。第二，缓存键的拆分粒度一定要把“影响文本的变量”和“影响请求的元信息”分开，这是缓存命中率的分水岭。第三，调试模式一定要做，渲染树打印功能在排查问题时能救你无数次。

最后再分享一个小技巧：缓存不仅是性能工具，也是很好的排障工具。当你怀疑某个请求的提示被拼错了，第一反应不应该是“重新渲染一次看看”，而是先查缓存里存的是什么样的消息序列。因为缓存里存的是上一次实际渲染的完整结果，是真正发到模型手里的东东，比任何日志都可靠。