BroadRouter

缓存大模型 API 响应以降低成本:用 Python 实现精确匹配缓存

BroadNet Inference 团队 · 阅读约 8 分钟 · 发布于

把完整请求(模型、消息、temperature、max_tokens、response_format、工具、思考设置以及你的提示词版本)哈希成一个键,把回答存在这个键下并设置过期时间。只对确定性、无副作用的请求返回已存储的回答。先在日志里测一测相同请求重复的频率:这个比例就是精确缓存最多能省下的部分。

每个你发送两次的相同大模型请求,都要付两次钱。响应缓存在第一次时保存回答,下一次直接返回,不计 token,也不用等待。思路很简单。难点在于:怎样才算两个请求“相同”,哪些请求绝不能从存储中返回,以及你的流量重复得够不够多、值不值得做。

本文用 Python 和 SQLite 构建一个小型精确匹配缓存,并在一个模拟的 OpenAI 兼容服务器上做了测试;同时介绍如何在写任何代码之前,先从日志中测出命中率。

响应缓存和提示词缓存是一回事吗?

不是。它们省下的东西不同,而且可以同时使用。

提示词缓存(服务商) 响应缓存(你自己)
复用什么 提示词重复的开头部分 整个回答
谁来运行 API 服务商 你的代码
模型还会运行吗? 会,写出新的回答 不会
省下什么 部分输入费用 输入、输出和思考 token,以及延迟
何时命中 共享前缀、不同的问题 完全相同的请求

缓存输入 token 讲的是服务商这一侧,如何组织提示词以利用缓存介绍了如何安排提示词布局,让前缀被复用。提示词缓存计算器可以为它计价。响应缓存位于这一切之前:一旦命中,就没有任何请求离开你的服务器。

缓存真的能帮你省钱吗?

先测量,再动手。许多缓存教程里的节省百分比来自别人的流量。你的数字只取决于一件事:同一个请求在你的过期窗口内再次出现的频率。

如果你已经像大模型 API 用量日志中那样记录每次调用,就再加一个字段:request_hash,即下文介绍的缓存键。它不保存任何提示词文本,所以适合不记录内容的日志。然后统计重复次数:

import json
from collections import Counter

def potential_hit_rate(log_path: str) -> float:
    """Share of calls whose request_hash was already seen: an upper bound for an exact cache."""
    hashes = [json.loads(line)["request_hash"] for line in open(log_path)]
    seen, repeats = set(), 0
    for h in hashes:
        repeats += h in seen
        seen.add(h)
    print("top repeated requests:", Counter(hashes).most_common(3))
    return repeats / len(hashes) if hashes else 0.0

print(f"potential hit rate: {potential_hit_rate('calls.jsonl'):.1%}")

在一个包含 20 次调用的合成日志上(一个请求出现五次,另一个出现三次,其余十二个各不相同),它输出的潜在命中率为 30.0%。这是一个上限:它忽略了过期时间,并假设每次重复都可以安全地从存储中返回。

然后把命中率换算成金额:

monthly saving = hit rate × requests per month
                 × (input tokens × input price + output tokens × output price) ÷ 1,000,000

输出 token 包括思考。BroadNet 的文档说明,DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考再回答,而且思考计入 max_tokens,所以一次命中省下的 token 中,有一部分你在回复里根本看不到。请从日志记录的 usage 中取 completion_tokens,而不是看回答的长度。

用 token 举个例子:每月 100,000 个请求,每个 1,200 输入、150 输出 token,命中率 30%,可以避免 3,600 万输入 token 和 450 万输出 token。在 DeepSeek V4.1 Flash 上,它们分别按每百万 $0.175 和 $0.52 计费;把你自己的数字填进大模型 API 费用计算器。如果这些输入中的大部分本来就命中了服务商缓存,那么输入部分的节省按更低的缓存价计算(同一模型上每百万 $0.0055),所以关键往往在输出这一侧。

缓存键里放什么?

凡是可能改变回答的东西都放进去,其他的都不要。

  • 包含:model、完整的 messages 列表(含系统提示词)、temperature、top_p、max_tokens、seed、response_format、tools、tool_choice 和 reasoning_effort。
  • 加上一个由你控制的提示词版本,例如 faq-v3。当你修改了请求体中看不出来的提示词模板、检索数据或后处理逻辑时,就升级这个版本。
  • 排除每次调用都会变、但不影响回答的东西:请求 ID、时间戳、追踪头,以及只为防滥用而发送的 user 字段。

每次都用同样的方式序列化键的材料。Python 的 json.dumps 配合 sort_keys=True 和 separators=(",", ":"),无论字典顺序如何,都会得到同一个规范字符串;ensure_ascii=False 会把阿拉伯语等非拉丁文本保留为 UTF-8,而不是转义序列。再用 SHA-256 做哈希。

漏掉字段是最危险的错误。如果 max_tokens 不在键里,一个在小限制下被截断的回复,就会被返回给允许长回答的请求。

缓存实现:SQLite、TTL 和跳过策略

import hashlib, json, sqlite3, time

# Every field that changes the answer belongs in the key.
KEY_FIELDS = ("model", "messages", "temperature", "top_p", "max_tokens", "seed",
              "response_format", "tools", "tool_choice", "reasoning_effort")

def cache_key(params: dict, prompt_version: str) -> str:
    material = {k: params[k] for k in KEY_FIELDS if k in params}
    material["prompt_version"] = prompt_version
    canon = json.dumps(material, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(canon.encode("utf-8")).hexdigest()

class ResponseCache:
    def __init__(self, path="llm_cache.sqlite", ttl_s=7 * 86400):
        self.db, self.ttl = sqlite3.connect(path), ttl_s
        self.db.execute("CREATE TABLE IF NOT EXISTS cache (k TEXT PRIMARY KEY, created REAL,"
                        " body TEXT, prompt_tokens INT, completion_tokens INT)")
        self.hits = self.misses = self.skips = self.saved_in = self.saved_out = 0

    def create(self, client, prompt_version: str, **params):
        if params.get("stream") or params.get("temperature", 1) > 0:
            self.skips += 1                       # not cacheable: call the model directly
            return client.chat.completions.create(**params)
        k = cache_key(params, prompt_version)
        row = self.db.execute("SELECT body, created, prompt_tokens, completion_tokens"
                              " FROM cache WHERE k = ?", (k,)).fetchone()
        if row and time.time() - row[1] < self.ttl:
            self.hits += 1; self.saved_in += row[2]; self.saved_out += row[3]
            return json.loads(row[0])             # a plain dict, not an SDK object
        self.misses += 1
        r = client.chat.completions.create(**params)
        choice = r.choices[0]
        if choice.finish_reason == "stop" and not choice.message.tool_calls:
            self.db.execute("INSERT OR REPLACE INTO cache VALUES (?, ?, ?, ?, ?)",
                            (k, time.time(), r.model_dump_json(),
                             r.usage.prompt_tokens, r.usage.completion_tokens))
            self.db.commit()
        return r.model_dump()

再跑一遍试试:

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
cache = ResponseCache("demo.sqlite", ttl_s=86400)
SYSTEM = {"role": "system", "content": "Answer questions about our refund policy in one sentence."}
questions = ["How long do refunds take?", "Can I refund a gift card?",
             "How long do refunds take?", "How long do refunds take?", "Can I refund a gift card?"]
for q in questions:
    r = cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0,
                     max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": q}])
    print(r["choices"][0]["message"]["content"])
# a personalised, sampled request is never cached
cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0.7,
             messages=[SYSTEM, {"role": "user", "content": "Write me a friendly reminder"}])
# a new prompt version is a new key
cache.create(client, "faq-v4", model="broadnet/deepseek-v4.1-flash", temperature=0,
             max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": "How long do refunds take?"}])
print(f"hits={cache.hits} misses={cache.misses} skipped={cache.skips} "
      f"saved_input={cache.saved_in} saved_output={cache.saved_out}")

我们用 OpenAI Python SDK 3.51.0,针对一个本地模拟服务器运行了这段代码;该服务器会统计上游调用次数,并为每个回复报告 1,200 个提示词 token 和 150 个输出 token(没有调用真实 API)。七个请求产生了四次上游调用。脚本输出 hits=3 misses=3 skipped=1 saved_input=3600 saved_output=450。在同一个数据库文件上再运行一次,六个可缓存的请求全部命中(hits=6 misses=0):SQLite 会在重启之间保留缓存。用相同字段但顺序不同构建的键也能匹配。

关于代码的几点说明:

  • max_tokens=1200 为回答之前的思考留出空间。限制太小,思考模型可能返回空回复(原因)。这类回复不会被保存,因为它的 finish_reason 是 length,而不是 stop。
  • **命中时返回 dict。**未命中时也返回 model_dump(),所以调用方看到的是同一种结构。如果你的代码需要 SDK 对象,就把两者都包装一下。
  • **未设置 temperature 视为采样。**这时服务器会使用自己的默认值,可能大于 0,所以除非你显式设置为 0,否则封装会跳过缓存。
  • **SQLite 适合一个或少数几个进程。**如果有多台服务器,就把同样的键和 TTL 逻辑放到 Redis 或你的数据库里。

哪些内容绝不能从缓存中返回?

  • **采样得到的回复(temperature 大于 0)。**你选择了多样性。缓存会抹掉它,用户点“重新生成”时会得到同样的文本。
  • 个性化的回答,除非用户 ID 在键里。两个用户发送“总结一下我的账户”,他们的账户是不同的。更好的做法是:只缓存消息中不含任何用户个人数据的请求。
  • 工具调用。工具调用是执行操作的指令。从存储中回放“为订单 1182 退款”可能会重复产生副作用,而且正确的下一步取决于当前状态。这个封装拒绝保存任何带有 tool_calls 的回复。
  • **流式回复。**对于 stream=True,封装会绕过缓存。缓存一个流意味着要缓冲它、确认它已结束,再回放出来,对聊天界面来说很少值得。
  • **被截断或失败的回复。**只保存 finish_reason == "stop" 的回复。一个被截断的回答或一个错误被缓存一周,就是一个看起来像模型问题的 bug。
  • 依赖时间的回答。“今天的汇率是多少?”需要很短的 TTL,或者干脆不缓存。

适合缓存的有:对固定输入集合做分类、对需要重新处理的文档做信息抽取、来自固定提示词的 FAQ 回答、需要反复运行的测试套件和评测,以及反复发送同一个请求的开发调试循环。

缓存的回答应该何时过期?

使用三种失效方式:

  1. **TTL。**每个条目的时间限制:稳定的 FAQ 回答可以设几天,读取实时数据的内容设几分钟。
  2. **键中的版本。**系统提示词、检索索引或输出 schema 变化时,修改提示词版本。旧条目将不再匹配,并逐渐过期。
  3. **键中的模型。**它本来就在键里,所以从一个模型换到另一个模型会从一个全新的缓存开始,这正是你在评估是否切换时想要的。

定期删除过期的行(DELETE FROM cache WHERE created < ?),否则文件只会越来越大。

还有一个附带的好处。推理引擎并不保证相同的输入产生相同的输出:vLLM 的文档说它 “does not guarantee the reproducibility of the results by default”(译文:默认不保证结果的可复现性)。在条目有效期内,缓存能让每个用户对同一个问题得到同样的回答。

语义缓存呢?

语义缓存会把每个问题转成嵌入向量,当新问题足够接近时返回已存储的回答,所以“退款要多久?”可以命中“退款需要多长时间?”。GPTCache 是最知名的开源实现。它的 README 说,它使用向量库进行相似度搜索,并用相似度评估器判断是否命中,还提醒 “you may encounter false positives during cache hits and false negatives during cache misses”(译文:缓存命中时可能出现误命中,未命中时可能出现漏命中),并指出关闭嵌入后它就变成了关键词匹配缓存。

有两点很实际。第一,它需要一个嵌入模型和一个向量库。BroadNet Inference 不提供嵌入,所以这一层需要用其他服务商或本地模型;嵌入费用计算器可以为各种选项计价。第二,一次误命中会对另一个问题给出一个看似确定的回答。请使用严格的相似度阈值,用真实的近似问题对来测试,并只把语义缓存用于低风险的回答。无论如何都把精确缓存放在前面:检查它不花钱,而且它对“问的是什么”永远不会判断错。

缓存对隐私意味着什么?

缓存就是一个存放提示词和回答的地方。这改变了你的数据所在的位置。

BroadNet 的推理隐私声明(2026-11-15 查阅)说,其网关不保存提示词、消息、响应或转写文本,但会保留不含内容的流量和用量记录(token 数、费用、耗时)。推理内容不会被保留。必要的账户、计费和安全元数据按该声明所述保留。一旦你加入响应缓存,你的系统就保存了服务商不保存的内容。像对待其他任何用户数据存储一样对待它:

  • 尽可能只缓存不含个人数据的请求,这样还能提高命中率。
  • 设置足够短、符合你保留政策的 TTL,并定期删除。
  • 对文件或数据表进行静态加密,并限制谁可以读取。
  • 如果缓存可能保存用户文本,就把它纳入数据删除请求的处理范围。

向大模型 API 发送敏感数据涵盖了这份清单的其余部分。

缓存与其他成本控制手段如何配合?

缓存消除的是重复调用,对唯一的调用毫无作用,所以它是与其他控制手段并列,而不是取代它们:更短的提示词、服务商的提示词缓存、每个请求的 max_tokens 上限,以及大模型 API 费用控制中的预算和循环限制。对于大型一次性任务,在发送之前先对输入去重;这和缓存是同一个思路,只是做一次。不用 Batch API 处理大型任务介绍了任务这一侧。

在固定价格套餐上,算法就变了。BroadNet 的 DeepSeek 会话不计 token,所以在那里缓存命中不省钱。但它仍然省时间:一个会话一次处理一个请求,所以你每跳过一次重复,会话就能腾出来处理新工作。

BroadNet Inference 适合什么场景

BroadRouter 是 BroadNet 自己的网站。BroadNet Inference 通过 OpenAI 兼容的 /v1/chat/completions 端点提供 DeepSeek V4.1 Flash、GLM 5.3、Qwen3.8 27B 和 Gemma 4 VL 26B,所以只要修改 base URL,上面的封装就能配合 OpenAI Python SDK 使用。它本身没有响应缓存功能;本文中的缓存由你自己负责。根据其 API 参考,服务商侧的缓存命中会在 usage.prompt_tokens_details.cached_tokens 中报告,并按缓存输入价计费。各模型的价格见价格页。

常见问题

提示词缓存和响应缓存有什么区别?

提示词缓存由服务商完成:重复的提示词前缀按较低的缓存输入价计费,模型仍会写出新的回答。响应缓存由你自己完成:你保存完整的回答,遇到相同请求时直接返回,根本不调用模型。

temperature 为 0 时应该缓存大模型响应吗?

如果请求没有副作用,而且对每个发送它的人返回同样的回答都可以接受,那就应该。temperature 为 0 本来也不能保证推理引擎输出完全相同,所以缓存还能让回答保持一致。temperature 大于 0 或未设置时,就不要缓存。

大模型响应缓存能省多少钱?

在你的过期窗口内完全重复的请求所占的比例,乘以这些请求的费用。在你自己的日志里统计重复的请求哈希,就能得到这个比例。开放式聊天可能接近零,固定的 FAQ 或分类输入则可能很高。

语义缓存比精确匹配缓存更好吗?

它命中得更多,因为相似的问题也能匹配,但它可能返回另一个问题的答案。它还需要一个嵌入模型和一个向量库。先从精确缓存开始,只在误命中代价很低的地方再加一层语义缓存。

能缓存流式响应吗?

用本文这个简单的封装不行。你得收集完整的流,确认它正常结束,存下来,之后再以流的形式回放。大多数团队只缓存非流式调用,比如分类、信息抽取和 FAQ 回答。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity