1. 从一条消息的诞生说起很多人第一次翻Hermes这类推理框架的源码注意力都放在模型加载、算子调度、KV Cache管理这些重环节上觉得提示组装无非就是字符串拼接没什么好看的。我一开始也是这么想的直到有一次线上排查一个诡异问题同样的输入两次请求模型返回的质量差异明显日志里prompt看起来一模一样但token数却对不上。顺着调用栈一路挖下去才发现问题出在提示组装这一层——模板渲染时对特殊字符的处理不一致导致tokenizer切出来的序列不同。从那以后我就养成了一个习惯看推理框架先看它的prompt是怎么拼出来的。这篇是Hermes源码解析系列的第二篇专门聊**提示组装Prompt Assembly和提示缓存Prompt Cache**这两块。第一篇我们过了一遍整体架构和请求生命周期这一篇往深里走聚焦一个具体问题一条用户请求进来经过哪些步骤变成最终喂给模型的token序列中间有哪些容易被忽略的细节缓存又是怎么在拼这个环节上做文章的内容会以代码走读为主穿插我自己的理解和踩坑记录。适合两类人看一是正在用Hermes做二次开发、需要定制prompt逻辑的工程师二是想理解推理框架内部机制、准备自己写类似系统的开发者。读之前最好对Transformer的基本推理流程有个概念知道什么是prefill、什么是decode不然有些地方会卡住。不过我会尽量把关键概念用大白话解释清楚基础薄弱也能跟下来。需要说明的是下面涉及的代码结构和函数命名是基于这类推理框架的常见实现方式做的合理还原具体到某个版本可能有出入但核心思路是通用的。你对照自己手上的代码看应该能对上号。2. 提示组装的整体设计思路2.1 为什么不能简单做字符串拼接刚接触这块的人最容易犯的错就是把提示组装理解成system_prompt user_input这么简单。真到生产环境你会发现事情远没这么单纯。第一个问题是多轮对话的上下文管理。用户可能连续问了五轮每轮都要把历史消息带上但历史不能无限增长得按token预算裁剪。裁剪的时候又不能把一轮对话从中间切断否则模型看到半截问答会懵。这就需要一个结构化的消息表示而不是一坨字符串。第二个问题是模板的多样性。不同模型对prompt格式的要求不一样有的要求用特定的角色标记有的对system message的位置有讲究有的在工具调用场景下需要插入特殊token。如果把这些逻辑硬编码在业务代码里换个模型就得改一遍维护成本极高。所以框架层面需要抽象出一层模板系统。第三个问题是性能。多轮对话场景下每轮请求的prompt有大量重复前缀system prompt、历史消息。如果每次都从头tokenize一遍纯属浪费。这就引出了提示缓存的需求——把已经处理过的部分缓存起来只处理新增部分。Hermes在这块的设计思路我总结成一句话把消息和token两个层面分开处理消息层负责语义和结构token层负责性能和缓存。这个分层是理解整个模块的钥匙。2.2 消息层的抽象从Message到Conversation先看消息层。框架内部通常用一个Message结构体表示单条消息核心字段就几个class Message: role: str # system / user / assistant / tool content: str # 文本内容 name: Optional[str] # 可选的发送者标识 tool_calls: Optional[list] # 工具调用信息这个结构看起来平平无奇但role字段的设计有讲究。它不只是个标签而是决定了这条消息在最终prompt里的位置和包裹方式。比如system消息通常放在最前面且只出现一次assistant消息可能带有特殊的起始和结束标记tool消息需要和前面的tool_call对应上。多条Message组成一个Conversation这才是真正传给组装器的对象。Conversation上会挂一些元信息比如max_tokens、template_name、cache_enabled这些。我见过有的实现把Conversation直接做成list简单是简单但扩展性差加个字段就得改一堆函数签名不推荐。提示如果你在二次开发时要扩展消息类型比如加个system_note角色改Message的role枚举只是第一步更关键的是要同步更新模板渲染逻辑和缓存key的计算方式否则会出现缓存命中但内容不对的诡异问题。2.3 token层的抽象TokenizedPrompt与缓存槽位消息层处理完进入token层。这一步的核心产物是一个TokenizedPrompt里面装着最终的token id序列以及一些辅助信息class TokenizedPrompt: input_ids: list[int] # 最终token序列 cache_slots: list[int] # 每个token对应的缓存槽位用于后续KV Cache复用 prefix_len: int # 可复用的前缀长度 new_token_start: int # 新增token的起始位置cache_slots这个字段是性能优化的关键。它记录了每个token在KV Cache里的位置这样在prefill阶段就能直接复用之前算好的KV不用重算。prefix_len告诉你前多少个token是缓存命中的new_token_start告诉你从哪开始是新的。这两个抽象层之间的转换就是提示组装的核心工作。转换过程分三步模板渲染、tokenize、缓存匹配。下面逐个拆。3. 模板渲染把消息变成文本3.1 模板系统的选型考量模板渲染这块业界有几种常见做法。最简单的是字符串格式化f{role}: {content}这种优点是快缺点是没法处理复杂逻辑比如条件插入、循环。稍微复杂点用Jinja2这类模板引擎灵活性强但渲染开销大而且模板文件管理起来麻烦。还有一种是代码化的模板函数每个模型对应一个Python函数直接写逻辑。Hermes走的是第三条路我猜是出于性能和可控性的考虑。模板函数的好处是渲染逻辑就是普通代码调试方便性能也好坏处是加新模型得写新函数。不过对于推理框架来说支持的模型数量是有限的这个代价可以接受。模板函数通常长这样def render_llama_style(conv: Conversation) - str: parts [] for msg in conv.messages: if msg.role system: parts.append(fSYS\n{msg.content}\n/SYS\n) elif msg.role user: parts.append(f[INST] {msg.content} [/INST]) elif msg.role assistant: parts.append(f{msg.content} /s) return .join(parts)注意这里的角色标记是模型特定的不同模型差别很大。有的用|im_start|有的用[INST]有的干脆就是纯文本加换行。写模板函数的时候这些标记必须和模型训练时用的格式严格一致差一个空格都可能影响效果。3.2 特殊token的处理陷阱模板渲染里最容易出问题的地方是特殊token的处理。所谓特殊token就是tokenizer里有专门id的那些标记比如s、/s、|endoftext|这些。坑在于这些标记在模板里是以字符串形式出现的但tokenize的时候你希望它们被识别成单个特殊token而不是被拆成普通字符。举个例子s如果被当成普通文本tokenize可能变成、s、三个token那就完全错了。解决办法是在tokenize时传入allowed_special参数或者用tokenizer提供的专门接口。但这里又有个细节不同tokenizer对特殊token的处理方式不一样。有的需要你显式声明哪些是特殊token有的会自动识别。我踩过的坑是某个tokenizer默认不识别模板里的特殊标记导致渲染出来的prompt token数比预期多了十几个模型效果直接崩了。注意写完模板函数后一定要做一次渲染-tokenize-反tokenize的往返测试确认特殊token被正确识别。这个测试能提前发现90%的格式问题。3.3 多轮对话的拼接顺序多轮对话的拼接顺序看似简单其实有讲究。标准顺序是system在前然后user/assistant交替最后以user结尾因为要等模型回复。但实际场景里会有变体system消息的位置大多数模型要求system在最前面但也有模型支持在对话中间插入system消息来动态调整行为。如果你的模板函数不支持这种遇到这类需求就得改代码。连续同角色消息有时候会出现连续两条user消息比如用户补充说明这时候要不要合并合并的话用什么分隔符不合并的话模型会不会困惑我的经验是除非模型明确支持否则最好在业务层就避免连续同角色或者在模板里加个分隔标记。空消息的处理偶尔会有content为空的消息比如纯tool_call的assistant消息模板函数要能正确处理不能渲染出奇怪的东西。这些细节在文档里通常不会写但线上跑起来就会暴露。建议在模板函数里加一些断言比如检查消息序列是否合法提前把问题拦下来。4. Tokenize与缓存匹配的协同4.1 缓存的基本原理前缀复用提示缓存的核心思想是前缀复用。多轮对话里第N轮的prompt 第N-1轮的prompt 新一轮的问答。前面那一大段是完全一样的只有末尾是新增的。如果能把前面那段的KV Cache存下来第N轮只需要计算新增部分的KVprefill时间能大幅缩短。实现上框架会维护一个缓存池每个缓存项记录一段token序列及其对应的KV。新请求进来时拿它的token序列去缓存池里找最长匹配前缀。找到后复用那部分的KV只对剩余部分做prefill。这里的关键数据结构是前缀树Trie。把所有缓存过的序列组织成Trie查找最长匹配前缀就变成了一次树遍历效率很高。Hermes这类框架通常会用带引用计数的Trie因为多个请求可能共享同一段前缀得知道什么时候可以真正释放。4.2 缓存key怎么算才靠谱缓存匹配的准确性取决于key怎么算。最直接的做法是拿token序列本身当key但这样有个问题序列太长比较起来慢。所以实际实现里通常会对序列做哈希用哈希值当key。哈希的坑在于碰撞。两个不同的序列哈希到同一个值就会错误命中缓存导致输出错乱。解决办法是用足够强的哈希比如SHA-256或者哈希后再做一次完整比较。我倾向于后者虽然多一次比较但能彻底杜绝碰撞问题而且比较操作很快对性能影响可以忽略。还有一个细节缓存key要不要包含模板信息答案是必须包含。因为同样的消息用不同模板渲染出来的token序列是不同的。如果key里不带模板标识A模板的缓存可能被B模板的请求命中结果就是灾难。所以key的构成通常是hash(template_id token_sequence)。4.3 缓存失效与淘汰策略缓存不能无限增长得有淘汰机制。常见的策略有几种策略原理适用场景缺点LRU淘汰最久未使用的通用场景长对话可能被短请求挤掉LFU淘汰使用频率最低的热点集中的场景新请求难积累频率TTL超时淘汰时效性强的场景时间阈值难定引用计数LRU有引用的不淘汰其余按LRU多请求共享前缀实现复杂Hermes这类框架通常用引用计数LRU的组合。正在被请求使用的缓存项引用计数大于0不会被淘汰引用计数为0的按LRU顺序淘汰。这样既保证了活跃请求的缓存不被误删又能及时释放冷数据。淘汰时机的选择也有讲究。有的实现在每次插入新缓存时触发淘汰检查有的用后台线程定期清理。前者实时性好但可能影响请求延迟后者对请求无影响但内存峰值可能偏高。我实测下来对于延迟敏感的场景后台清理更稳。提示调试缓存问题时可以在缓存项上加个命中次数计数器观察哪些前缀被频繁复用。如果发现某个长前缀从来没被命中过说明缓存策略有问题或者请求模式和你预期的不一样。5. 完整走读一条请求的组装全过程5.1 入口函数与参数校验假设请求从API层进来经过一系列中间件后到达组装模块。入口函数大概长这样def assemble_prompt( conversation: Conversation, tokenizer: Tokenizer, cache: PromptCache, template: TemplateFunc, ) - TokenizedPrompt: # 1. 参数校验 validate_conversation(conversation) # 2. 模板渲染 rendered_text template(conversation) # 3. Tokenize input_ids tokenizer.encode( rendered_text, allowed_specialtokenizer.special_tokens, ) # 4. 缓存匹配 prefix_len, cache_slots cache.match(input_ids) # 5. 组装结果 return TokenizedPrompt( input_idsinput_ids, cache_slotscache_slots, prefix_lenprefix_len, new_token_startprefix_len, )参数校验这步别小看。我见过因为没校验导致的问题conversation为空、消息role非法、content超长、token数超过模型上限等等。这些在入口拦下来比在后面某处崩掉要好排查得多。5.2 渲染与tokenize的衔接细节渲染和tokenize之间的衔接有个容易被忽略的点渲染结果的末尾处理。有的模板函数会在末尾加一个触发模型开始生成的标记比如|assistant|有的不加靠调用方补。这个不一致会导致tokenize出来的序列差几个token进而影响缓存匹配。我的做法是在模板函数的契约里明确规定渲染结果必须包含完整的、可直接tokenize的文本包括所有必要的起始和结束标记。调用方不再做任何拼接。这样职责清晰不容易出错。另一个细节是空白字符的处理。模板里经常有换行和缩进这些在tokenize时会产生额外的token。如果模板函数写得随意可能引入一堆无意义的空白token浪费上下文窗口。建议在渲染后做一次规范化把连续空白压缩成单个换行或空格但要小心别把有意义的格式比如代码块里的缩进也压掉了。5.3 缓存匹配的完整流程缓存匹配是性能关键路径值得展开讲。假设缓存池用Trie组织匹配流程如下从根节点开始逐token遍历input_ids。每走一步检查当前节点是否有对应的子节点。有就继续没有就停。记录最后一个有效节点的位置。有效节点是指该节点对应的缓存项引用计数大于0或者KV数据还在。遍历结束后prefix_len就是有效节点的深度。为匹配到的前缀增加引用计数防止在本次请求完成前被淘汰。返回prefix_len和对应的cache_slots。这里有个性能优化点匹配过程可以提前终止。如果当前节点的所有子节点都不存在后面的token就不用比了直接返回。对于长序列这个优化能省不少时间。还有个正确性细节匹配到的前缀必须是完整的。什么意思如果缓存里存的是[1,2,3,4,5]你的输入是[1,2,3]匹配到3就停了这没问题。但如果缓存里存的是[1,2,3]你的输入是[1,2,3,4,5]匹配到3prefix_len3也没问题。问题出在缓存项可能被部分淘汰——比如[1,2,3,4,5]的KV只保留了前3个那匹配到3之后虽然Trie里有4和5的节点但KV没了不能复用。所以匹配逻辑里要检查KV的可用性不能只看Trie结构。5.4 组装结果的交付与后续使用组装完成后TokenizedPrompt交给推理引擎。引擎拿到后根据prefix_len决定prefill的范围前prefix_len个token的KV直接从缓存取从new_token_start开始的token做prefill计算。计算完成后新的KV会被写回缓存同时更新Trie结构。这里有个写回时机的问题。是在prefill完成后立即写回还是等整个请求包括decode完成后再写回立即写回的好处是后续请求能更快命中坏处是如果请求中途失败缓存里可能留下不完整的KV。等请求完成再写回更安全但缓存利用率低一些。Hermes的选择通常是前者因为推理请求失败的概率很低而且即使失败不完整的KV在下次匹配时会被检测出来通过长度校验不会造成错误。写回时还要注意引用计数的更新。新写入的缓存项引用计数初始为1被当前请求持有请求完成后减1。如果减到0就进入待淘汰队列。这个计数逻辑必须严格配对多减一次会导致缓存被提前释放少减一次会导致内存泄漏。我调试过的一个bug就是异常路径下忘了减引用计数跑了一天内存就爆了。6. 常见问题与排查技巧实录6.1 缓存命中率低的排查思路缓存命中率低是最常见的问题。排查时按这个顺序来第一步确认缓存是否开启。听起来很蠢但我真的见过配置里cache_enabledFalse但没人注意的情况。检查配置和运行时日志。第二步看请求模式。如果每个请求的prompt都完全不同比如单轮问答没有历史那命中率低是正常的缓存本来就不适用。缓存的价值在多轮对话和共享system prompt的场景。第三步检查模板一致性。如果同一个对话两次请求用了不同的模板比如一次带system一次不带token序列不同自然匹配不上。确认模板选择逻辑是否稳定。第四步看缓存容量。如果缓存池太小频繁淘汰命中率也上不去。观察缓存项的淘汰速率如果淘汰很频繁考虑扩容。第五步检查tokenize的一致性。这是最隐蔽的。如果两次tokenize同样的文本得到不同的结果比如特殊token处理不一致缓存永远匹配不上。用往返测试验证。6.2 缓存命中但结果错误的排查比命中率低更可怕的是命中错误。表现是模型输出莫名其妙或者和预期完全不符。排查思路检查缓存key是否包含模板标识。这是最常见的错误来源。检查哈希碰撞。虽然概率低但如果用的哈希函数不够强长序列碰撞是有可能的。加一次完整比较能排除。检查KV的完整性。如果缓存项被部分淘汰但Trie节点还在可能匹配到不完整的KV。确认匹配逻辑检查了KV可用性。检查引用计数。如果引用计数算错可能导致正在使用的缓存被淘汰KV被覆盖。我遇到过一次诡异问题某个对话的第二轮开始输出乱码。查了半天发现是缓存key只用了token序列的哈希没带模板id而那个对话恰好切换过模板。加上模板id后问题消失。6.3 性能问题的定位方法组装环节的性能问题通常表现为请求延迟高或者吞吐上不去。定位方法先看profile。用cProfile或py-spy抓一下看时间花在哪。通常大头在tokenize和缓存匹配。tokenize慢可能是文本太长或者特殊token处理逻辑复杂。考虑用更快的tokenizer实现或者对长文本做分块处理。缓存匹配慢可能是Trie太大遍历深度深。考虑限制Trie深度或者用更紧凑的数据结构。锁竞争。如果缓存池用全局锁保护高并发下会成为瓶颈。考虑分片每个分片独立加锁。下面这张表是我整理的常见问题速查现象可能原因排查方法解决方向命中率低模板不一致对比两次请求的token序列统一模板选择逻辑命中率低缓存太小观察淘汰频率扩容或优化淘汰策略命中但结果错key缺模板标识检查key构成key加入模板id命中但结果错KV不完整检查匹配逻辑匹配时校验KV可用性延迟高tokenize慢profile换tokenizer或优化文本延迟高锁竞争观察并发下的等待时间缓存分片内存涨引用计数泄漏监控缓存项数量检查异常路径的计数更新6.4 几个我踩过的坑坑一特殊token被拆散。前面提过模板里的s被tokenize成三个token。解决办法是显式声明特殊token。这个坑的隐蔽性在于模型可能还能工作只是效果差一点不容易发现。坑二空白字符累积。模板函数里用了多行字符串每行末尾的换行和缩进都进了prompt。跑久了发现上下文窗口被浪费了不少。后来加了规范化处理。坑三缓存写回时机。早期实现是prefill完立即写回结果遇到一个请求prefill到一半被取消缓存里留了半截KV。后续请求匹配到这段用了不完整的KV输出错乱。改成写回前校验完整性后解决。坑四多线程下的Trie更新。Trie的插入和查询如果没加锁并发下可能读到中间状态。用读写锁或者无锁数据结构解决。这个坑在压测时才暴露单线程测试完全正常。提示组装模块的测试要覆盖异常路径比如空对话、超长输入、非法role、缓存满、并发请求。正常路径的测试只能保证功能对异常路径的测试才能保证线上稳。7. 一些延伸思考提示组装和缓存这块往深了挖还有不少可做的。比如动态模板——根据对话内容自动选择最合适的模板而不是固定一个。再比如缓存的分层——把system prompt这种全局共享的前缀单独放一层对话历史放另一层分别管理命中率能更高。还有个方向是跨请求的缓存共享。现在缓存通常是进程内的如果多个推理实例部署在同一台机器上能不能共享缓存技术上可行但涉及跨进程通信和一致性问题复杂度不低。我了解到有些团队在做这块思路是用共享内存存KV用中心化的Trie管理元数据。另外缓存的压缩也值得关注。KV Cache占内存很大如果能压缩存储同样内存能缓存更多前缀。量化、稀疏化都是可选方向但要注意压缩后的KV精度损失对输出的影响。这些方向我自己也只探索了一部分有些还在试验阶段。如果你在做类似的事情欢迎交流。源码走读这种事一个人看容易钻牛角尖多几个人对着代码聊很多想不通的地方就通了。最后分享一个我调试这类系统的小习惯在组装模块的关键路径上加详细的trace日志记录每次请求的token序列哈希、匹配到的前缀长度、缓存命中情况。这些日志平时看着冗余但出问题时就是救命稻草。我靠这些日志定位过好几次缓存相关的诡异bug比断点调试高效多了。 
长河君 · 2026/10/20 5:23:20 · 阅读 1.2k Hermes源码解析：提示组装与缓存机制深度剖析
1. 从一条消息的诞生说起很多人第一次翻Hermes这类推理框架的源码注意力都放在模型加载、算子调度、KV Cache管理这些重环节上觉得提示组装无非就是字符串拼接没什么好看的。我一开始也是这么想的直到有一次线上排查一个诡异问题同样的输入两次请求模型返回的质量差异明显日志里prompt看起来一模一样但token数却对不上。顺着调用栈一路挖下去才发现问题出在提示组装这一层——模板渲染时对特殊字符的处理不一致导致tokenizer切出来的序列不同。从那以后我就养成了一个习惯看推理框架先看它的prompt是怎么拼出来的。这篇是Hermes源码解析系列的第二篇专门聊**提示组装Prompt Assembly和提示缓存Prompt Cache**这两块。第一篇我们过了一遍整体架构和请求生命周期这一篇往深里走聚焦一个具体问题一条用户请求进来经过哪些步骤变成最终喂给模型的token序列中间有哪些容易被忽略的细节缓存又是怎么在拼这个环节上做文章的内容会以代码走读为主穿插我自己的理解和踩坑记录。适合两类人看一是正在用Hermes做二次开发、需要定制prompt逻辑的工程师二是想理解推理框架内部机制、准备自己写类似系统的开发者。读之前最好对Transformer的基本推理流程有个概念知道什么是prefill、什么是decode不然有些地方会卡住。不过我会尽量把关键概念用大白话解释清楚基础薄弱也能跟下来。需要说明的是下面涉及的代码结构和函数命名是基于这类推理框架的常见实现方式做的合理还原具体到某个版本可能有出入但核心思路是通用的。你对照自己手上的代码看应该能对上号。2. 提示组装的整体设计思路2.1 为什么不能简单做字符串拼接刚接触这块的人最容易犯的错就是把提示组装理解成system_prompt user_input这么简单。真到生产环境你会发现事情远没这么单纯。第一个问题是多轮对话的上下文管理。用户可能连续问了五轮每轮都要把历史消息带上但历史不能无限增长得按token预算裁剪。裁剪的时候又不能把一轮对话从中间切断否则模型看到半截问答会懵。这就需要一个结构化的消息表示而不是一坨字符串。第二个问题是模板的多样性。不同模型对prompt格式的要求不一样有的要求用特定的角色标记有的对system message的位置有讲究有的在工具调用场景下需要插入特殊token。如果把这些逻辑硬编码在业务代码里换个模型就得改一遍维护成本极高。所以框架层面需要抽象出一层模板系统。第三个问题是性能。多轮对话场景下每轮请求的prompt有大量重复前缀system prompt、历史消息。如果每次都从头tokenize一遍纯属浪费。这就引出了提示缓存的需求——把已经处理过的部分缓存起来只处理新增部分。Hermes在这块的设计思路我总结成一句话把消息和token两个层面分开处理消息层负责语义和结构token层负责性能和缓存。这个分层是理解整个模块的钥匙。2.2 消息层的抽象从Message到Conversation先看消息层。框架内部通常用一个Message结构体表示单条消息核心字段就几个class Message: role: str # system / user / assistant / tool content: str # 文本内容 name: Optional[str] # 可选的发送者标识 tool_calls: Optional[list] # 工具调用信息这个结构看起来平平无奇但role字段的设计有讲究。它不只是个标签而是决定了这条消息在最终prompt里的位置和包裹方式。比如system消息通常放在最前面且只出现一次assistant消息可能带有特殊的起始和结束标记tool消息需要和前面的tool_call对应上。多条Message组成一个Conversation这才是真正传给组装器的对象。Conversation上会挂一些元信息比如max_tokens、template_name、cache_enabled这些。我见过有的实现把Conversation直接做成list简单是简单但扩展性差加个字段就得改一堆函数签名不推荐。提示如果你在二次开发时要扩展消息类型比如加个system_note角色改Message的role枚举只是第一步更关键的是要同步更新模板渲染逻辑和缓存key的计算方式否则会出现缓存命中但内容不对的诡异问题。2.3 token层的抽象TokenizedPrompt与缓存槽位消息层处理完进入token层。这一步的核心产物是一个TokenizedPrompt里面装着最终的token id序列以及一些辅助信息class TokenizedPrompt: input_ids: list[int] # 最终token序列 cache_slots: list[int] # 每个token对应的缓存槽位用于后续KV Cache复用 prefix_len: int # 可复用的前缀长度 new_token_start: int # 新增token的起始位置cache_slots这个字段是性能优化的关键。它记录了每个token在KV Cache里的位置这样在prefill阶段就能直接复用之前算好的KV不用重算。prefix_len告诉你前多少个token是缓存命中的new_token_start告诉你从哪开始是新的。这两个抽象层之间的转换就是提示组装的核心工作。转换过程分三步模板渲染、tokenize、缓存匹配。下面逐个拆。3. 模板渲染把消息变成文本3.1 模板系统的选型考量模板渲染这块业界有几种常见做法。最简单的是字符串格式化f{role}: {content}这种优点是快缺点是没法处理复杂逻辑比如条件插入、循环。稍微复杂点用Jinja2这类模板引擎灵活性强但渲染开销大而且模板文件管理起来麻烦。还有一种是代码化的模板函数每个模型对应一个Python函数直接写逻辑。Hermes走的是第三条路我猜是出于性能和可控性的考虑。模板函数的好处是渲染逻辑就是普通代码调试方便性能也好坏处是加新模型得写新函数。不过对于推理框架来说支持的模型数量是有限的这个代价可以接受。模板函数通常长这样def render_llama_style(conv: Conversation) - str: parts [] for msg in conv.messages: if msg.role system: parts.append(fSYS\n{msg.content}\n/SYS\n) elif msg.role user: parts.append(f[INST] {msg.content} [/INST]) elif msg.role assistant: parts.append(f{msg.content} /s) return .join(parts)注意这里的角色标记是模型特定的不同模型差别很大。有的用|im_start|有的用[INST]有的干脆就是纯文本加换行。写模板函数的时候这些标记必须和模型训练时用的格式严格一致差一个空格都可能影响效果。3.2 特殊token的处理陷阱模板渲染里最容易出问题的地方是特殊token的处理。所谓特殊token就是tokenizer里有专门id的那些标记比如s、/s、|endoftext|这些。坑在于这些标记在模板里是以字符串形式出现的但tokenize的时候你希望它们被识别成单个特殊token而不是被拆成普通字符。举个例子s如果被当成普通文本tokenize可能变成、s、三个token那就完全错了。解决办法是在tokenize时传入allowed_special参数或者用tokenizer提供的专门接口。但这里又有个细节不同tokenizer对特殊token的处理方式不一样。有的需要你显式声明哪些是特殊token有的会自动识别。我踩过的坑是某个tokenizer默认不识别模板里的特殊标记导致渲染出来的prompt token数比预期多了十几个模型效果直接崩了。注意写完模板函数后一定要做一次渲染-tokenize-反tokenize的往返测试确认特殊token被正确识别。这个测试能提前发现90%的格式问题。3.3 多轮对话的拼接顺序多轮对话的拼接顺序看似简单其实有讲究。标准顺序是system在前然后user/assistant交替最后以user结尾因为要等模型回复。但实际场景里会有变体system消息的位置大多数模型要求system在最前面但也有模型支持在对话中间插入system消息来动态调整行为。如果你的模板函数不支持这种遇到这类需求就得改代码。连续同角色消息有时候会出现连续两条user消息比如用户补充说明这时候要不要合并合并的话用什么分隔符不合并的话模型会不会困惑我的经验是除非模型明确支持否则最好在业务层就避免连续同角色或者在模板里加个分隔标记。空消息的处理偶尔会有content为空的消息比如纯tool_call的assistant消息模板函数要能正确处理不能渲染出奇怪的东西。这些细节在文档里通常不会写但线上跑起来就会暴露。建议在模板函数里加一些断言比如检查消息序列是否合法提前把问题拦下来。4. Tokenize与缓存匹配的协同4.1 缓存的基本原理前缀复用提示缓存的核心思想是前缀复用。多轮对话里第N轮的prompt 第N-1轮的prompt 新一轮的问答。前面那一大段是完全一样的只有末尾是新增的。如果能把前面那段的KV Cache存下来第N轮只需要计算新增部分的KVprefill时间能大幅缩短。实现上框架会维护一个缓存池每个缓存项记录一段token序列及其对应的KV。新请求进来时拿它的token序列去缓存池里找最长匹配前缀。找到后复用那部分的KV只对剩余部分做prefill。这里的关键数据结构是前缀树Trie。把所有缓存过的序列组织成Trie查找最长匹配前缀就变成了一次树遍历效率很高。Hermes这类框架通常会用带引用计数的Trie因为多个请求可能共享同一段前缀得知道什么时候可以真正释放。4.2 缓存key怎么算才靠谱缓存匹配的准确性取决于key怎么算。最直接的做法是拿token序列本身当key但这样有个问题序列太长比较起来慢。所以实际实现里通常会对序列做哈希用哈希值当key。哈希的坑在于碰撞。两个不同的序列哈希到同一个值就会错误命中缓存导致输出错乱。解决办法是用足够强的哈希比如SHA-256或者哈希后再做一次完整比较。我倾向于后者虽然多一次比较但能彻底杜绝碰撞问题而且比较操作很快对性能影响可以忽略。还有一个细节缓存key要不要包含模板信息答案是必须包含。因为同样的消息用不同模板渲染出来的token序列是不同的。如果key里不带模板标识A模板的缓存可能被B模板的请求命中结果就是灾难。所以key的构成通常是hash(template_id token_sequence)。4.3 缓存失效与淘汰策略缓存不能无限增长得有淘汰机制。常见的策略有几种策略原理适用场景缺点LRU淘汰最久未使用的通用场景长对话可能被短请求挤掉LFU淘汰使用频率最低的热点集中的场景新请求难积累频率TTL超时淘汰时效性强的场景时间阈值难定引用计数LRU有引用的不淘汰其余按LRU多请求共享前缀实现复杂Hermes这类框架通常用引用计数LRU的组合。正在被请求使用的缓存项引用计数大于0不会被淘汰引用计数为0的按LRU顺序淘汰。这样既保证了活跃请求的缓存不被误删又能及时释放冷数据。淘汰时机的选择也有讲究。有的实现在每次插入新缓存时触发淘汰检查有的用后台线程定期清理。前者实时性好但可能影响请求延迟后者对请求无影响但内存峰值可能偏高。我实测下来对于延迟敏感的场景后台清理更稳。提示调试缓存问题时可以在缓存项上加个命中次数计数器观察哪些前缀被频繁复用。如果发现某个长前缀从来没被命中过说明缓存策略有问题或者请求模式和你预期的不一样。5. 完整走读一条请求的组装全过程5.1 入口函数与参数校验假设请求从API层进来经过一系列中间件后到达组装模块。入口函数大概长这样def assemble_prompt( conversation: Conversation, tokenizer: Tokenizer, cache: PromptCache, template: TemplateFunc, ) - TokenizedPrompt: # 1. 参数校验 validate_conversation(conversation) # 2. 模板渲染 rendered_text template(conversation) # 3. Tokenize input_ids tokenizer.encode( rendered_text, allowed_specialtokenizer.special_tokens, ) # 4. 缓存匹配 prefix_len, cache_slots cache.match(input_ids) # 5. 组装结果 return TokenizedPrompt( input_idsinput_ids, cache_slotscache_slots, prefix_lenprefix_len, new_token_startprefix_len, )参数校验这步别小看。我见过因为没校验导致的问题conversation为空、消息role非法、content超长、token数超过模型上限等等。这些在入口拦下来比在后面某处崩掉要好排查得多。5.2 渲染与tokenize的衔接细节渲染和tokenize之间的衔接有个容易被忽略的点渲染结果的末尾处理。有的模板函数会在末尾加一个触发模型开始生成的标记比如|assistant|有的不加靠调用方补。这个不一致会导致tokenize出来的序列差几个token进而影响缓存匹配。我的做法是在模板函数的契约里明确规定渲染结果必须包含完整的、可直接tokenize的文本包括所有必要的起始和结束标记。调用方不再做任何拼接。这样职责清晰不容易出错。另一个细节是空白字符的处理。模板里经常有换行和缩进这些在tokenize时会产生额外的token。如果模板函数写得随意可能引入一堆无意义的空白token浪费上下文窗口。建议在渲染后做一次规范化把连续空白压缩成单个换行或空格但要小心别把有意义的格式比如代码块里的缩进也压掉了。5.3 缓存匹配的完整流程缓存匹配是性能关键路径值得展开讲。假设缓存池用Trie组织匹配流程如下从根节点开始逐token遍历input_ids。每走一步检查当前节点是否有对应的子节点。有就继续没有就停。记录最后一个有效节点的位置。有效节点是指该节点对应的缓存项引用计数大于0或者KV数据还在。遍历结束后prefix_len就是有效节点的深度。为匹配到的前缀增加引用计数防止在本次请求完成前被淘汰。返回prefix_len和对应的cache_slots。这里有个性能优化点匹配过程可以提前终止。如果当前节点的所有子节点都不存在后面的token就不用比了直接返回。对于长序列这个优化能省不少时间。还有个正确性细节匹配到的前缀必须是完整的。什么意思如果缓存里存的是[1,2,3,4,5]你的输入是[1,2,3]匹配到3就停了这没问题。但如果缓存里存的是[1,2,3]你的输入是[1,2,3,4,5]匹配到3prefix_len3也没问题。问题出在缓存项可能被部分淘汰——比如[1,2,3,4,5]的KV只保留了前3个那匹配到3之后虽然Trie里有4和5的节点但KV没了不能复用。所以匹配逻辑里要检查KV的可用性不能只看Trie结构。5.4 组装结果的交付与后续使用组装完成后TokenizedPrompt交给推理引擎。引擎拿到后根据prefix_len决定prefill的范围前prefix_len个token的KV直接从缓存取从new_token_start开始的token做prefill计算。计算完成后新的KV会被写回缓存同时更新Trie结构。这里有个写回时机的问题。是在prefill完成后立即写回还是等整个请求包括decode完成后再写回立即写回的好处是后续请求能更快命中坏处是如果请求中途失败缓存里可能留下不完整的KV。等请求完成再写回更安全但缓存利用率低一些。Hermes的选择通常是前者因为推理请求失败的概率很低而且即使失败不完整的KV在下次匹配时会被检测出来通过长度校验不会造成错误。写回时还要注意引用计数的更新。新写入的缓存项引用计数初始为1被当前请求持有请求完成后减1。如果减到0就进入待淘汰队列。这个计数逻辑必须严格配对多减一次会导致缓存被提前释放少减一次会导致内存泄漏。我调试过的一个bug就是异常路径下忘了减引用计数跑了一天内存就爆了。6. 常见问题与排查技巧实录6.1 缓存命中率低的排查思路缓存命中率低是最常见的问题。排查时按这个顺序来第一步确认缓存是否开启。听起来很蠢但我真的见过配置里cache_enabledFalse但没人注意的情况。检查配置和运行时日志。第二步看请求模式。如果每个请求的prompt都完全不同比如单轮问答没有历史那命中率低是正常的缓存本来就不适用。缓存的价值在多轮对话和共享system prompt的场景。第三步检查模板一致性。如果同一个对话两次请求用了不同的模板比如一次带system一次不带token序列不同自然匹配不上。确认模板选择逻辑是否稳定。第四步看缓存容量。如果缓存池太小频繁淘汰命中率也上不去。观察缓存项的淘汰速率如果淘汰很频繁考虑扩容。第五步检查tokenize的一致性。这是最隐蔽的。如果两次tokenize同样的文本得到不同的结果比如特殊token处理不一致缓存永远匹配不上。用往返测试验证。6.2 缓存命中但结果错误的排查比命中率低更可怕的是命中错误。表现是模型输出莫名其妙或者和预期完全不符。排查思路检查缓存key是否包含模板标识。这是最常见的错误来源。检查哈希碰撞。虽然概率低但如果用的哈希函数不够强长序列碰撞是有可能的。加一次完整比较能排除。检查KV的完整性。如果缓存项被部分淘汰但Trie节点还在可能匹配到不完整的KV。确认匹配逻辑检查了KV可用性。检查引用计数。如果引用计数算错可能导致正在使用的缓存被淘汰KV被覆盖。我遇到过一次诡异问题某个对话的第二轮开始输出乱码。查了半天发现是缓存key只用了token序列的哈希没带模板id而那个对话恰好切换过模板。加上模板id后问题消失。6.3 性能问题的定位方法组装环节的性能问题通常表现为请求延迟高或者吞吐上不去。定位方法先看profile。用cProfile或py-spy抓一下看时间花在哪。通常大头在tokenize和缓存匹配。tokenize慢可能是文本太长或者特殊token处理逻辑复杂。考虑用更快的tokenizer实现或者对长文本做分块处理。缓存匹配慢可能是Trie太大遍历深度深。考虑限制Trie深度或者用更紧凑的数据结构。锁竞争。如果缓存池用全局锁保护高并发下会成为瓶颈。考虑分片每个分片独立加锁。下面这张表是我整理的常见问题速查现象可能原因排查方法解决方向命中率低模板不一致对比两次请求的token序列统一模板选择逻辑命中率低缓存太小观察淘汰频率扩容或优化淘汰策略命中但结果错key缺模板标识检查key构成key加入模板id命中但结果错KV不完整检查匹配逻辑匹配时校验KV可用性延迟高tokenize慢profile换tokenizer或优化文本延迟高锁竞争观察并发下的等待时间缓存分片内存涨引用计数泄漏监控缓存项数量检查异常路径的计数更新6.4 几个我踩过的坑坑一特殊token被拆散。前面提过模板里的s被tokenize成三个token。解决办法是显式声明特殊token。这个坑的隐蔽性在于模型可能还能工作只是效果差一点不容易发现。坑二空白字符累积。模板函数里用了多行字符串每行末尾的换行和缩进都进了prompt。跑久了发现上下文窗口被浪费了不少。后来加了规范化处理。坑三缓存写回时机。早期实现是prefill完立即写回结果遇到一个请求prefill到一半被取消缓存里留了半截KV。后续请求匹配到这段用了不完整的KV输出错乱。改成写回前校验完整性后解决。坑四多线程下的Trie更新。Trie的插入和查询如果没加锁并发下可能读到中间状态。用读写锁或者无锁数据结构解决。这个坑在压测时才暴露单线程测试完全正常。提示组装模块的测试要覆盖异常路径比如空对话、超长输入、非法role、缓存满、并发请求。正常路径的测试只能保证功能对异常路径的测试才能保证线上稳。7. 一些延伸思考提示组装和缓存这块往深了挖还有不少可做的。比如动态模板——根据对话内容自动选择最合适的模板而不是固定一个。再比如缓存的分层——把system prompt这种全局共享的前缀单独放一层对话历史放另一层分别管理命中率能更高。还有个方向是跨请求的缓存共享。现在缓存通常是进程内的如果多个推理实例部署在同一台机器上能不能共享缓存技术上可行但涉及跨进程通信和一致性问题复杂度不低。我了解到有些团队在做这块思路是用共享内存存KV用中心化的Trie管理元数据。另外缓存的压缩也值得关注。KV Cache占内存很大如果能压缩存储同样内存能缓存更多前缀。量化、稀疏化都是可选方向但要注意压缩后的KV精度损失对输出的影响。这些方向我自己也只探索了一部分有些还在试验阶段。如果你在做类似的事情欢迎交流。源码走读这种事一个人看容易钻牛角尖多几个人对着代码聊很多想不通的地方就通了。最后分享一个我调试这类系统的小习惯在组装模块的关键路径上加详细的trace日志记录每次请求的token序列哈希、匹配到的前缀长度、缓存命中情况。这些日志平时看着冗余但出问题时就是救命稻草。我靠这些日志定位过好几次缓存相关的诡异bug比断点调试高效多了。