LLM调用不稳定？48小时构建回放Cassette记录器

为什么你的Prompt调优总在重复付费

同一个Prompt发给大模型，十秒后的回复措辞却变了。采样设置解释一部分，批处理和服务器路由解释剩下的——但这对于判断"改进还是噪声"毫无帮助。这正是许多开发者每天面临的困境：想验证一个新系统提示词是否真的提升了输出质量，却因为缺少冻结的基线，每次对比都要付出一次真实的API调用成本。

一位开发者花了48小时做了一个决定：停止调优Prompt，转而构建一个"回放磁带"（Replay Cassette）。核心逻辑很简单：把你和模型的每一次交互录下来，之后所有测试都离线重放，不再花钱也不受网络抖动影响。据其技术博客记录，整个方案仅用Python标准库实现，可对接任何HTTP模型端点。

三条铁律：回放必须免费，缺失必须报错

动手写代码前，作者先写下了三条契约，因为缓存层一旦契约模糊就会腐化：

1. 回放运行必须零成本——修复解析器里的一个正则时，同一套测试要能跑四十遍，不花一次真实调用。
2. 未命中必须大声报错——录制的响应缺失时，测试框架以退出码2退出并打印指纹，绝不能静默回退到网络请求。
3. 缓存键必须可解释——能在请求旁边打印指纹，并看出究竟是哪个字段变了。

第二条是多数人容易跳过的，却恰恰是把"缓存"变成"测试工具"的关键。一个未命中时偷偷调用网络的缓存，会掩盖你本来要捕获的回归。

核心实现：无依赖的Python Cassette

整个工具用标准库Python写成，它包装的是你自己的调用函数，而不是某个厂商SDK，因此对任何HTTP模型端点都通用。存储格式选了追加式JSONL，比反复重写JSON文件更能扛住硬停机，也方便grep和diff。

关键设计在于缓存键的生成：对请求payload做规范化的SHA-256哈希。但这里埋着第一个坑——作者最初的指纹对原始请求字典直接哈希，导致每次回放都未命中，原因有三个：字典插入顺序不同、消息内容里的尾随空白漂移、以及温度等隐式默认值（{"temperature": 1.0}和{}对服务器是同一请求，对哈希却是两个键）。修复方式是排序键、紧凑分隔符、逐行剥离尾随空格并合并默认值。

作者总结道：缓存键是你与过去的自己签的API契约，要先写规范化函数，用版本字段钉住它，语义一变就升版本。

SHA-256 与规范化哈希

SHA-256 是一种密码学哈希函数，能将任意长度的输入映射为 256 位（64 个十六进制字符）的固定长度摘要，具有雪崩效应——输入哪怕只改变一个比特，输出也会面目全非。这使它天然适合做缓存键：只要请求语义相同，哈希就应一致；语义不同，哈希必须不同。但哈希函数本身不理解“语义”，它只对字节序列敏感。因此“规范化”（canonicalization）成为关键步骤：在哈希之前，必须把逻辑等价的请求整理成唯一的字节表示，例如对字典按键排序、使用紧凑分隔符消除空白差异、合并隐式默认值。否则，两个对服务器而言完全相同的请求会生成不同指纹，导致缓存永远未命中。作者强调的“先写规范化函数并用版本字段钉住它”，正是因为在缓存系统中，键的生成规则一旦变更，所有历史记录的键都会失效，必须通过显式版本号来管理这种演进。

JSONL 追加式存储

JSONL（JSON Lines）是一种每行一个独立 JSON 对象的文本格式，与整体是一个大 JSON 数组的格式相比，它支持逐条追加写入而无需重写整个文件。这对“回放磁带”至关重要：录制过程可能因崩溃或断电中断，追加式写入只损失最后未完成的一行，而重写式存储可能损坏整个文件。此外，JSONL 天然适合 grep、diff 和流式读取，便于人工排查和版本控制。

第27小时的教训：系统提示词从未进入哈希

更隐蔽的bug出现在第27小时：作者改了系统提示词，回放却拿到旧答案，测试全绿。指纹看似正常，问题出在测试框架——系统消息是由一个读取环境变量的薄客户端包装器注入的，所以被哈希的字典里只有用户轮次。两个不同的提示词生成了同一个键，回放自信地返回了第一个答案。

修复用了两个本应在第一天就写的守卫：显式断言消息列表第一条必须是system角色；把提示词文件的字节哈希写入键中。这条经验可以推广到任何项目：绝不要让库替你组装被哈希的请求，自己构建消息列表，断言预期形状。

薄客户端包装器与隐式请求组装

许多模型 SDK 或内部客户端库会提供“便捷”封装：你只传用户消息，库自动从环境变量、配置文件或默认参数中注入系统提示词、温度、最大 token 数等字段。这种设计在正常调用时很省事，但在构建缓存键时极其危险——因为被哈希的字典只包含你显式传入的部分，而真正发给服务器的请求还包含库悄悄添加的内容。两个不同的系统提示词可能生成完全相同的用户消息字典，从而碰撞出同一个缓存键，回放时返回错误的历史响应。修复方式不是去修补包装器，而是彻底绕开它：自己构建完整的消息列表（包括 system 角色），显式断言其形状，并将提示词文件的字节哈希也纳入键中。这条经验适用于任何需要可复现请求的场景：被哈希的对象必须是你完全掌控的、与线上请求逐字节一致的表示。

流式响应：别存分块边界

流式输出是另一个陷阱。作者的第一反应是持久化分块边界，让回放的流看起来与原始字节一致——这是个错误，因为分块只是传输层产物，提供商明天完全可能用不同方式切分。

解析器真正需要的是组装后的文本加上结束原因，通过相同的迭代器接口交付。回放时按固定chunk_size重新切分即可，这样流式路径在每次回放中都被真实执行，解析器能看到真正的部分块。作者的建议很直接：如果你的解析器依赖精确的分块形状，那是解析器的问题，不该藏在fixture里。

传输层产物与解析器契约

流式响应中的“分块”（chunk）是 HTTP 传输层或提供商 API 的实现细节，而不是语义单元。同一个完整回复，提供商可能按字符、按词、按句或按固定字节数切分，甚至在不同版本间改变切分策略。如果测试夹具（fixture）持久化了原始分块边界，解析器就会隐式依赖这些边界，一旦提供商调整切分方式，解析器在真实调用中崩溃，而回放测试却依然通过——这正是“磁带是快照，不是真理”的体现。正确做法是只存储组装后的完整文本和结束原因（finish reason），回放时按固定大小重新切分，并通过与真实流相同的迭代器接口交付。这样每次回放都会真实执行流式解析路径，解析器能 encountering 部分块、空块等边界情况，从而持续锻炼其健壮性。

什么时候录，什么时候直接调

作者给出了一张实战决策表：塑造Prompt或解析器时，录一次、回放多次；只改后处理代码时直接回放；对比两个模型别名时分别录制、按别名做键；想检查提供商当前行为时，必须真实调用多次采样——磁带是快照，不是真理；CI回归门禁用回放并在未命中时退出码2；负载或延迟测试永远用真实调用，因为回放测的是你的磁盘而不是网络。

核心区分：回放回答"我的代码变了吗"，永远不回答"模型今天好不好"。混淆这两个问题，团队就会抱着过时的fixture信上好几个月。

适用边界与不该用的人

磁带是冻结的观察，无法验证质量，提供商在别名背后换了模型它也会愉快通过。不要把包含用户数据的响应存进磁带，除非你有可信的清洗步骤——追加式日志极其擅长永久保存秘密。做持续评估的团队应该用真正的评估流水线，而不是本地磁带。

如果一天只调用一次，或者你唯一反复问的问题是模型当前是否可达，这套工具不值得。当你有十几个用例、每个要跑几十遍时，它大约两小时就能回本。

作者还建议尽早加一个"稳定性探针"：在录制模式下把同一payload发五次，报告返回了几种不同答案。这一个数字就能告诉你，你所谓的改进里有多少是噪声。

常见问题

Q：Cassette和普通的响应缓存有什么区别？ A：普通缓存未命中时回退到网络；Cassette未命中时直接报错退出。前者掩盖回归，后者暴露回归。

Q：能用于生产环境的CI吗？ A：可以，但建议只提交一个小型、清洗过的种子磁带用于smoke套件，完整磁带放在仓库外。

Q：为什么不直接mock掉API调用？ A：mock需要你手写假响应，而Cassette记录的是真实模型的真实输出，包括那些你没想到会出现的格式。