🏠 总目录📚 本教程 04 · 调用层 ← →

AI全栈 / 04

模型 SDK 外面,还需要包住哪些责任?

超时、重试、记账与缓存集中在调用层,才能给业务代码稳定的边界。

能判断模型结果何时可用、哪些失败可重试,以及一次调用怎样记成本。

核对重试白名单

模型调用层的职责边界业务路由调用自己的模型函数。调用层统一超时、重试、记账和缓存约定,底层可以接供应商 SDK,测试时也可以替换成假客户端。这是职责划分,不表示固定的内部执行顺序。业务路由:调用自己的模型函数调用层:统一调用约定等待与失败:超时、重试条件结果与资源:记账、缓存边界供应商 SDK / 测试假客户端
职责地图,不规定超时、重试、记账与缓存的内部执行顺序;替换假客户端只验证调用边界,不构成真实网络或费用验证。
📑 本页目录(点开跳转)

04 · 调用层

⏱ 约 65 分钟 | ⭐ 把「调模型」包成你自己的一个函数 | 🔨 标记为可直接跑的 Python 演示无需联网


🎯 一句话

client.chat.completions.create() 只是这一层最里面的一行;外面那圈——超时、重试、记账、缓存、可替换——才是它存在的理由。 上一章最后那条规矩「api/ 里不许出现模型 SDK 的名字」,这一章解释为什么。


🧩 一、为什么要在 SDK 外面再包一层

不包也能跑。 下面五件事会在不同时间点分别来找你,每一件都在问同一句话:「调模型」这件事,有没有一个统一的地方?

理由 没包一层时的具体场景
换模型 新模型便宜一半,你要在十几个文件里改调用写法、返回字段解析、错误类型判断
加日志 想回答「哪些请求慢」,得在每个调用点复制一遍计时代码,还总有人忘了加
⭐ 算成本 账单只有一个总数。「聊天花的还是摘要花的」「哪个用户」——问不出来
做缓存 「什么时候能缓存」的判据散在各处,漏判一次就是把 A 的答案发给 B
⭐ 测试替换 CI 每跑一次都真花钱、真联网,上游一抖测试就红——红了还不是你的错

⭐ 五个理由的形状是同一个:都是「每次调用都要做、却和业务无关」的事。 和上一章依赖注入同类,只是那层管进来的边界,这层管出去的边界。

地基是两样东西:一个你自己的返回结构,一个假客户端。

# llm.py —— 调用层的地基:统一返回结构 + 假客户端
import time
import random
from dataclasses import dataclass


@dataclass
class LLMResult:            # ⭐ 业务代码只认这个形状,永远不认某个 SDK 的返回对象
    text: str
    model: str
    in_tokens: int
    out_tokens: int
    latency_ms: int
    cached: bool = False


class FakeLLM:
    """不联网、不花钱、结果可预测。测试、CI、本地开发共用这一个。"""

    def __init__(self, reply="(假模型)收到。", latency=0.05, seed=0):
        self.reply, self.latency = reply, latency
        self.calls = []                  # ⭐ 记下每次调用,测试里可以直接断言
        self._rng = random.Random(seed)

    def complete(self, prompt, model="fake-1", temperature=0.0, timeout=30):
        t0 = time.perf_counter()
        self.calls.append({"prompt": prompt, "temperature": temperature})
        time.sleep(self.latency)
        # ⭐ temperature > 0 就每次不一样 —— 让"不确定性"在测试里也是真的
        text = self.reply if temperature == 0 else self.reply + str(self._rng.randint(100, 999))
        return LLMResult(text, model, len(prompt) // 3 + 1, len(text) // 3 + 1,
                         int((time.perf_counter() - t0) * 1000))


if __name__ == "__main__":
    llm = FakeLLM()
    a, b = (llm.complete("同一个问题", temperature=0.7).text for _ in range(2))
    print(a, b, "|两次相同吗:", a == b)      # ⭐ False —— 断言 == 的测试写不出来

⭐ LLMResult 是这一层最值钱的一行:它让「换 SDK」变成「改一个文件」。⚠️ 别偷懒把 SDK 的响应对象直接往上传——那等于把整个 SDK 的形状焊进业务代码。

FakeLLM 也不是玩具:① 测试 / CI 不花钱不联网,上游抖动不再让你的测试变红;② 本地开发 前端不用等你的 Key;③ ⭐ 故障演练——让它故意抛 429、故意超时、故意返回半截 JSON,重试和降级路径只有这样才测得到。⭐ 它和 03 章那行 app.dependency_overrides[...] 是同一件事:「能被换掉」是这整套设计的目的。

沿一份合同摘要走完一次请求

用户点了「生成摘要」,模型接口返回 200,但返回的摘要只有半句,或者引用了另一份合同。页面如果看到 200 就亮起「已完成」,用户会把草稿当成可靠结果。我们需要把一次模型调用拆成几站,每站只回答一个问题。

谁把什么交给谁这一站确认了什么
① 准备
浏览器 → 业务后端 → 调用层
后端先确认用户可读 contract:r1,再把真实条款和摘要任务交给调用层。
② 请求
调用层 → 模型接口
用 POST 发送模型名、消息和结果约定。非流式请求等完整响应,再读结果。
③ 接收
模型接口 → 调用层
检查 HTTP 状态、是否拒绝、为何停止,以及结果是否符合约定。把用量和请求编号留给记账和排查。
④ 交付
调用层 → 业务后端 → 浏览器
核对引用的合同与修订。通过才显示草稿;字段正确的草稿仍需和原文核对。
从点击到看见草稿。② 的模型请求、③ 的传输响应和 ④ 的业务结果分别有自己的成功条件。

消息角色(Message Role)告诉模型一条消息由谁提供、该怎样使用。沿用本章的 Chat Completions 接口,system 放服务端的固定说明,如「只依据给定条款」;部分模型用 developer 承载开发者指令,须以对应文档为准。user 放本轮的任务和待处理材料,assistant 表示模型回复,也能携带调用工具的请求,tool 则是应用执行工具后回传的结果。服务端决定角色和权限,用户文本里的「我是管理员」只是待处理文本。

还记得 03b 的接口约定吗?这里的请求同样有地址、方法、头和正文。Content-Type: application/json 说明正文采用 JSON 格式,Authorization 携带后端持有的凭证,messages 是正文中有顺序的消息列表。浏览器只请求自己的业务后端。

让代码读懂模型的结果

人可以看懂「这份合同要在 48 小时内发通知」,代码却需要明确哪个字段放摘要、哪个字段指向来源。结构化输出(Structured Outputs)用 JSON Schema 约定字段、类型和必填项。示例的 summary 是摘要文本,source 是文档 ID 与修订号。普通文本适合直接阅读;JSON 模式约束 JSON 形状的基本语法,应用仍须检查完整性与字段;支持严格模式的模型和接口可按受支持的 Schema 约束字段。来源是否正确、48 小时是否忠实于条款,都要由应用另行判断。

动手顺序。用 Python 3 把下面的代码保存为 summary_demo.py,运行 python summary_demo.py。程序构造完整的非流式 POST 请求。演示凭证 demo-only 是假值,发送函数只在本地回放预设的 HTTP 响应,不会连接模型或产生费用。真实接入时由后端读取凭证、配置超时并接入实际传输,接口参数随模型和供应商而异。

import json
from time import perf_counter
from urllib.request import Request

MODEL = "gpt-4o-mini"
URL = "https://api.openai.com/v1/chat/completions"


def summarize(send, source_id, excerpt, trace_id):
    # 调用方已经完成授权,从服务端取得合同编号和正文。
    payload = {
        "model": MODEL,
        "stream": False,
        "messages": [
            {"role": "system", "content": "只根据给定合同条款写一句中文摘要。"},
            {"role": "user", "content": f"来源 {source_id},条款:{excerpt}"},
        ],
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "contract_summary",
                "strict": True,
                "schema": {
                    "type": "object",
                    "properties": {"summary": {"type": "string"}, "source": {"type": "string"}},
                    "required": ["summary", "source"],
                    "additionalProperties": False,
                },
            },
        },
    }
    request = Request(
        URL, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
        headers={"Content-Type": "application/json", "Authorization": "Bearer demo-only"},
        method="POST",
    )
    start = perf_counter()
    status, headers, body = send(request)
    audit = {
        "trace_id": trace_id, "request_id": headers.get("x-request-id"),
        "status": status, "model": MODEL, "usage": None,
        "latency_ms": int((perf_counter() - start) * 1000),
    }
    if status != 200:
        return f"upstream_http_{status}", None, audit

    try:
        response = json.loads(body)  # 外层 HTTP 响应正文
        audit["usage"] = response.get("usage")
        choice = response["choices"][0]
        message = choice["message"]
        if message.get("refusal") or choice["finish_reason"] == "content_filter":
            return "refused", None, audit
        if choice["finish_reason"] != "stop":
            return "unexpected_finish", None, audit
        result = json.loads(message["content"])  # 内层模型生成的 JSON 字符串
    except (ValueError, KeyError, IndexError, TypeError, AttributeError):
        return "invalid_response", None, audit

    if (not isinstance(result, dict) or result.keys() != {"summary", "source"}
            or not all(isinstance(value, str) for value in result.values())
            or not result["summary"].strip()):
        return "invalid_output", None, audit
    if result["source"] != source_id:
        return "source_mismatch", None, audit
    return "draft_ready", result["summary"], audit


def simulated_send(request, mode):
    assert request.get_method() == "POST" and request.full_url == URL
    assert request.get_header("Content-type") == "application/json"
    assert request.get_header("Authorization") == "Bearer demo-only"
    assert [m["role"] for m in json.loads(request.data)["messages"]] == ["system", "user"]
    headers = {"x-request-id": f"req_demo_{mode}"}
    if mode == "unavailable":
        return 503, headers, b'{"error":{"message":"temporarily unavailable"}}'
    source = "other-contract:r1" if mode == "wrong_source" else "contract:r1"
    content = json.dumps({"summary": "发现缺陷后须在48小时内书面通知。", "source": source})
    reason = "length" if mode == "cut_short" else "stop"
    message = {
        "role": "assistant",
        "content": '{"summary":' if mode == "cut_short" else content,
        "refusal": "无法提供摘要" if mode == "refusal" else None,
    }
    return 200, headers, json.dumps({
        "choices": [{"finish_reason": reason, "message": message}],
        "usage": {"prompt_tokens": 80, "completion_tokens": 27, "total_tokens": 107},
    }).encode("utf-8")


if __name__ == "__main__":
    for mode in ("ok", "wrong_source", "cut_short", "refusal", "unavailable"):
        outcome, draft, audit = summarize(
            lambda request: simulated_send(request, mode), "contract:r1",
            "发现缺陷后48小时内须书面通知。", trace_id=f"summary_{mode}",
        )
        print(audit["status"], outcome, draft or "—")

Request 把请求体编码为 UTF-8 字节。发送后先看 HTTP 状态。读完外层响应后,检查模型拒绝和结束原因,再解析 message.content 中的内层 JSON。通过字段校验后,把模型提供的来源和服务端已授权的合同修订做比较。draft_ready 只是允许展示草稿。示例只检查来源和字段,摘要中具体的数字仍需核对原文。

演练输入终端输出页面该怎么处理
匹配 contract:r1200 draft_ready 发现缺陷后须在48小时内书面通知。展示草稿和原文入口。
引用另一份合同200 source_mismatch —字段都齐也要拦下,检查上下文与授权来源。
输出达上限200 unexpected_finish —finish_reason=length 表示输出已截断。检查预算后再决定是否发起新的生成,半段不能入缓存。
模型拒绝200 refused —给出合适的拒绝提示,沿用产品的拒绝处理策略。
上游暂不可用503 upstream_http_503 —此时没有可解析的摘要。是否再试要看重试一节的重放条件。

日志用 trace_id 串起应用侧记录,x-request-id 对应供应商那一次尝试;两者配合能区分同一摘要操作发出的多次调用。记录状态、耗时和返回的用量,缺失用量记为未知。演示里的 token 数是假数据,生产日志只写排查所需字段,避免写入凭证和合同全文。

模型提出工具请求后,谁来查合同

现在假设用户只说「摘要我的合同」,模型需要材料。应用可先声明一个只读函数 read_contract,模型在 tool_calls 里建议参数 {"doc_id":"contract"}。这就是函数调用(Function Calling):模型把想做的操作和参数交给应用处理。

  1. 模型 → 应用。读取工具名、参数和调用 ID。此时只有提议,模型没有读到合同。
  2. 应用 → 业务服务。按允许的工具名和参数检查,用当前登录身份查权限。文档不可读就拒绝;可读才返回例如 contract:r1 的条款。
  3. 应用 → 模型。把执行结果作为 tool 消息送回,tool_call_id 对应原调用。模型可以用结果继续生成摘要;应用仍按上面的流程校验,最后才展示草稿。

模型回复「合同已读取」和业务服务确认读取成功,分别来自哪一站?看应用是否执行了工具并记录结果,就能分清。对会写库、发通知的工具,超时后的重放还要检查重试一节的幂等边界。

接口依据见 Chat Completions 请求和响应、结构化输出与函数调用流程。


⏳ 二、把连接超时和读取超时分开

超时 卡的是什么 该设多大
连接超时 TCP + TLS 握手,请求还没发出去 短,几秒。连不上就是连不上
读取超时 发出请求后,多久没收到新字节 ⚠️ 这个最容易设错,见下

同一个读取超时,在两种响应里碰到的静默不同。它限制客户端等待下一批数据的时间,整体截止时间则限制整次业务请求,包括重试和等待。

⭐ 判据:读取超时要大于「一次合法的静默能有多长」,这个长度会受生成、工具调用和代理缓冲影响。设得过小会截断正常请求,设得过大会占住连接和并发名额。 上游若在静默期发保活帧,字节到达会让客户端继续等。保活只说明这段链路还能收到数据。判断模型是否继续工作,要观察实际内容或进度事件,并用整体截止时间限制等待。自己往前端发的 ping 注释帧(05 章)只验证下游这一段。

💀 不设超时的下场:连接永远挂着不释放,进程里的连接数只增不减。症状是「服务跑几天越来越慢,重启一下就好」——⚠️ 这个症状太温和,通常拖很久才有人去查。

# 🗓️ 未实跑 —— 需要 httpx 和真实网络。要看的是【形状】:两个数分开设。
import httpx

# ⚠️ read 这个数按【最长的一次合法静默】定,不是拍脑袋:流式 + 工具调用时它可能是几十秒
timeout = httpx.Timeout(connect=5.0, read=60.0, write=10.0, pool=5.0)   # ⭐ 分开设
client = httpx.Client(timeout=timeout, limits=httpx.Limits(max_connections=100))

⭐ 形状不过期,参数名会:🗓️ 有的库把两者塞进一个参数,那种库你得自己在外面再补一层。


🔁 三、重试:用白名单,不是黑名单

可进入重试判断 原样再试也解决不了
429 临时限流。按上游协议等待,若提供 Retry-After 就在剩余预算内遵守。额度耗尽要先恢复额度。 400 / 422 参数错、超长:重试一万次还是 400
部分 5xx 暂时故障,例如 503。还要核对请求能否安全重放。 401 / 403:Key 不会因为多试一次就变对
已确认请求未发出的连接故障 内容策略拒绝:这是判断结果,不是故障
⚠️ 发送后读取超时或连接中断:原请求结果未知,重放可能多计费或重复执行。

⚠️ 必须写成白名单:except Exception: retry 会把「prompt 超长」这种确定性错误也重试三遍,让本该 0.2 秒返回的 400 变成 8 秒——而且日志里看起来像上游在抖。

做两次判断。先问错误是否可能短暂,再问重复执行是否可接受。收到 503 只能回答第一问。发送后超时连第一份结果都不知道:只读摘要重发仍可能生成两次、收两笔费用;若工具会建工单,两次提交还可能建出两张工单。

幂等(Idempotency)解决后一个问题。复用 03c 的操作 ID 和服务端去重:同一次「提交合同复核」沿用同一个业务操作 ID;服务端须持久记录操作与结果、原子防重,并拒绝同一个 ID 携带不同输入。请求追踪编号用来查日志,发送一个自定义请求头也只有在服务端明确支持并落实去重时才有效。外部副作用由实际执行方支持查询或去重;结果不明且无法确认时,转入待核对状态。

等待时间也要有预算。示例的第一次重试等 0~0.5 秒,第二次等 0~1 秒,第三次等 0~2 秒。每多失败一次,上限乘 2,到 8 秒封顶;从 0 到当前上限随机选等待时长叫全抖动(Full Jitter)。例如第二次失败用 min(8, 0.5 × 2¹) = 1 秒作为上限。本例只演练按次数退避,实际要另设整体截止时间,识别服务端等待提示,并与 SDK 的内置重试统一,避免两层重试相乘。

# retry.py —— 哪些错该重试、退避怎么算(可直接跑,看得见退避序列)
import random
import time


class RateLimited(Exception):    # 已分类为临时限流且允许重放的 429
    pass


class UpstreamError(Exception):  # 调用方已确认可重放的暂时上游故障
    pass


class BadRequest(Exception):     # 400:参数错、超长、被内容策略拒绝
    pass


class ConnectFailedBeforeSend(Exception):
    pass


# 仅映射可重放的故障。读取超时和结果未知的断连留给业务处理。
RETRIABLE = (RateLimited, UpstreamError, ConnectFailedBeforeSend)


def call_with_retry(fn, tries=4, base=0.5, cap=8.0, sleep=time.sleep, rng=None):
    rng = rng if rng is not None else random.Random()
    for i in range(tries):
        try:
            return fn()
        except RETRIABLE as e:
            if i == tries - 1:
                raise
            wait = rng.uniform(0, min(cap, base * 2 ** i))     # ⭐ 全抖动,别让大家一起回来
            print("  第 %d 次失败(%s),等 %.2f 秒" % (i + 1, type(e).__name__, wait))
            sleep(wait)
        # ⭐ 白名单之外的异常(如 BadRequest)根本不进 except,直接往上抛


if __name__ == "__main__":
    n = [0]

    def flaky():                      # 第一次被限流,第二次上游 5xx —— 两类都在白名单里
        n[0] += 1
        if n[0] == 1:
            raise RateLimited("429")
        if n[0] == 2:
            raise UpstreamError("503 上游故障")
        return "第 %d 次成功" % n[0]

    def always_400():
        raise BadRequest("400 prompt 超长")

    print("可重试:", call_with_retry(flaky, sleep=lambda s: None, rng=random.Random(0)))   # 演示时不真睡
    try:
        call_with_retry(always_400, sleep=lambda s: None)
    except BadRequest as e:
        print("不可重试,一次就抛出来:", e)

⭐ 为什么一定要有抖动:上游抖一下,所有客户端在同一瞬间失败,也就在同一瞬间重试——第二波比第一波更集中,把刚要缓过来的上游又打回去。这叫重试风暴,rng.uniform(0, 退避上限) 就是解药:把大家回来的时间摊开。

三条容易漏的:① 次数要有上限(三四次);② 重试烧的 token 也是钱,所以下一节记账表里有 retries;③ ⭐ 流式首字发出去之后不能再静默重试——用户已经看见字了,重来一遍就是当着他的面推翻自己(05 章第五节)。

HTTP 的自动重放条件见 RFC 9110 §9.2.2。


💰 四、成本记账:不在这层做,之后就没地方做了

层 它知道什么 它不知道什么
云厂商账单 一个总数 谁、哪个功能、哪次请求
业务代码 谁、哪个功能 ⚠️ token 数——它拿到的是一段文本
⭐ 调用层 两边都知道 ——
# cost.py —— 每次调用都记 token 和钱。⚠️ 单价是【占位数字】,用前去官方价格页抄一遍
PRICES = {"small": {"in": 2.0, "out": 8.0},          # 🗓️ 元 / 百万 token
          "big": {"in": 20.0, "out": 60.0}}


def cost_of(model, in_tokens, out_tokens):
    p = PRICES.get(model)
    if p is None:
        return None        # ⭐ 不认识的模型返回 None,别默默算成 0 —— 新模型的账会凭空消失
    return (in_tokens * p["in"] + out_tokens * p["out"]) / 1_000_000


def record(trace_id, user_id, feature, model, in_tok, out_tok, ms, cached=False, retries=0):
    """最小字段集。少任何一个,事后都有一类问题查不了:
    user_id 少了答不出"谁把钱花光的",⭐ feature 少了答不出"哪个功能在烧钱",
    model 少了答不出"换模型省了多少",
    cached 少了算不出缓存省了多少,retries 少了看不见重试烧掉的那笔账。"""
    return {"trace_id": trace_id, "user_id": user_id, "feature": feature, "model": model,
            "in": in_tok, "out": out_tok, "ms": ms, "cached": cached, "retries": retries,
            "cost": cost_of(model, in_tok, out_tok)}


if __name__ == "__main__":
    for m in ("small", "big", "忘了配单价的新模型"):
        print(m, "→", record("t1", "u_9", "摘要", m, 1200, 800, 940)["cost"])

用示例中的 small 手算一次:1,200 个输入 token × 2 元/百万 token,加上 800 个输出 token × 8 元/百万 token,再除以 1,000,000,得到 (2,400 + 6,400) ÷ 1,000,000 = 0.0088 元。一次业务操作有多次模型请求时,应分开记录每次尝试的已知用量;只记最终用量和重试次数,无法算出前几次实际花了多少。缺失的用量等对账时补核。

⚠️ 单价必须是配置,不能是散落在代码里的字面量——🗓️ 它一年变好几次,而且新模型上线时你会忘了加。cost_of 对不认识的模型返回 None 而不是 0,就是为了让「忘了加」在报表里显形,而不是安静地变成一笔零元开销。

⭐ 三个归因维度一个都不能少:user_id(谁)、feature(哪个功能)、model(哪个模型)。 前两个只有业务层知道,所以得由调用方传进来——⚠️ feature 是最常被漏掉的那个,因为它是唯一一个「不传也能跑」的字段。漏了它,本节开头那个问题「聊天花的还是摘要花的」就永远答不出来,而且事后补不回去:历史记录里没有这一列。

⭐ 有了这张表,12 章的配额扣减、15 章的成本看板都只是拿它做聚合——15 章那三条 GROUP BY 正是按天 / 按 feature / 按 user_id。顺序不能反:先有记录,才谈得上限制。


🗄️ 五、缓存:不确定性让它变难了

普通 Web 的缓存判据是「这个资源变没变」。AI 应用多一个前置问题:同样的输入,是不是「应该」得到同样的输出?

能缓存 不能缓存
temperature=0 的调用 temperature > 0 的创作:用户点「换一个」你给他一模一样的,这是 bug 不是优化
⭐ embedding:相同文本在固定模型版本、预处理和参数下常可复用;模型或预处理改变时应失效,不能假设跨版本逐位相同 带工具调用的对话:工具结果随时在变
固定提示词的分类 / 抽取:幂等 流式响应:缓存的是「一整段」,和「边生成边吐」对不上
# cache.py —— key 隔离身份、权限范围和文档修订(可直接跑)
import hashlib
import json


def cacheable(temperature, stream=False, tools=None):
    """相同输入应复用同一结果时才考虑缓存;t=0 也不保证模型逐字确定。"""
    return temperature == 0 and not stream and not tools


def cache_key(*, tenant_id, scope_id, permission_version, model, prompt,
              system="", temperature=0.0, docs=()):
    # 身份与权限字段来自已认证的服务端上下文,不接受模型/请求正文自报。
    # scope_id 标识实际可见范围;docs 是最终上下文顺序的 (doc_id, revision)。
    blob = json.dumps({
        "tenant": tenant_id, "scope": scope_id, "permissions": permission_version,
        "model": model, "system": system, "prompt": prompt,
        "temperature": temperature, "docs": list(docs),
    }, sort_keys=True, ensure_ascii=False)
    return hashlib.sha256(blob.encode("utf-8")).hexdigest()


if __name__ == "__main__":
    base = dict(tenant_id="A", scope_id="reader:u1", permission_version="p1",
                model="s", prompt="这份合同有什么风险", docs=[("contract", "r1")])
    first = cache_key(**base)
    print("同问题、同文档 id,换租户后相同吗:",
          first == cache_key(**(base | {"tenant_id": "B"})))  # False
    print("同租户、同文档 id,修订后相同吗:",
          first == cache_key(**(base | {"docs": [("contract", "r2")]})))  # False
    print("权限版本改变后相同吗:",
          first == cache_key(**(base | {"permission_version": "p2"})))  # False

💀 缓存命中不等于允许返回。 两个租户可以都有 contract,同一文档也会从 r1 更新到 r2;只放 id,就会复用别人的摘要或旧版本答案。上面的三个比较都应为 False。模型、system、温度、最终上下文的内容与顺序也必须反映到 key。

⭐ tenant_id、scope_id 和权限版本由服务端认证与授权结果提供;不同有效可见范围不能共用 scope,授权变化要更新版本。每次命中后仍要按当前 ACL 复验全部引用文档,并检查修订是否有效,再返回缓存答案;撤权或版本失效就丢弃命中,不能只靠 TTL 或旧 key 放行。

如果只在实现本章调用层,可以继续下一节;遇到缓存把数据库拖慢、命中旧答案或 Redis 内存上涨时,再看 可跳过的缓存深入。

可选深入:缓存失效、旧读回填与 Redis 的容量代价

这里讨论的是应用缓存,数据库仍是业务事实来源;上面的身份、权限、文档修订检查继续生效。以下时间线和命令结果是教学推演,未运行 Redis 服务或并发压测。

先找出是哪一种“没命中”

轨迹数据库为什么忙针对它的办法与限制
穿透:请求不存在的文档 X → cache miss → DB 无记录;下一次仍如此不存在的结果没被记住,重复请求都回源校验ID;把“确实不存在”与超时/故障区分,空值短 TTL 可减少重复查询,但新建文档后须失效。先鉴权,不能借负缓存泄漏对象存在性
击穿:一个热 key 到期 → 同时来 100 个读者 → 都回源同一个值被并行重建同 key 的 single-flight 或有期限互斥,让一个请求重建;等待队列要有界、超时可拒绝。进程内合并不覆盖其他实例;旧值兜底也不能越过权限/修订有效性
雪崩:一批 key 同时到期,或缓存服务整体不可用 → 大量不同 key 回源压力同时散到数据库各处批量预热/过期时间错峰,限制回源并发并降级;随机 TTL 不能修复整个缓存宕机,后端保护仍要有

用 8 个位看清 Bloom 的误报

把位编号为 0–7。为便于手算,假设两次哈希得到 A→(1,4)、B→(2,4)、C→(1,2)、D→(0,4)。插入 A、B 后,置 1 的位置是 {1,2,4}。查 D:位 0 为 0,可排除;查 C:两位都是 1,却没插入过 C,这是误报,仍要回源确认。

“没有漏报”的前提是检查的集合确实都已插入、哈希一致、位没有丢失或被误清。新文档已写库却尚未同步过滤器时,不能用旧过滤器的阴性把它永久挡住。普通 Bloom 不能直接清掉 A 的位 4 来删除 A,否则 B 也会受损;删除需要重建或选用支持删除的适当结构。真实容量与误报率要按预计元素量配置,此 8 位例不代表生产误报率。

沿 cache_key 看一次删除仍留下的旧答案

初始:DB=v1,cache缺失(先假设使用不含修订的旧key)
R:读DB得到v1,尚未回填 → 暂停
W:提交DB=v2 → 删除cache(此时仍为空)
R:恢复,把手里的v1写入cache
后续读者命中v1;W已经执行过一次delete,仍然会读旧值

本章 cache_key 把最终文档修订放进 key:R 的 v1 只能写入 r1 的 key,前提是后续请求从可信且足够新的修订来源取得 r2,并在命中时复验。旧版本指针本身若被缓存得过久,换键并不能凭空知道新版本。授权检查与取数据间的并发撤权,也要由业务定义生效边界。

写库提交后再失效缓存,仍有“提交成功、删除前崩溃”和失效投递失败窗口。可用同库事务保存失效意图、后台可靠重试,必要时在同一原子边界核验版本再写缓存;TTL 仅在停止旧回填且过期策略有效时帮助收敛。异步可靠投递通常提供最终一致,不是跨数据库与 Redis 的原子提交;“延迟再删一次”也不能脱离最大读延迟/重试假设作保证。外部副作用的恢复边界见 原有故障恢复节。

按读写形状选值结构,再看编码

类型本应用中的用途别混淆的地方
String一份序列化摘要/embedding缓存;GET/SET整值读写Redis String 可以是二进制字节,不只是人类文字;不能把向量JSON的整值读取当向量检索索引
Hash对象字段,如任务进度或文档元信息,HGET/HSET按字段操作字段结构不自动解决多个字段与源库的事务一致性
Set去重成员、集合交集,如一组候选文档ID无分值排序;成员存在也不能替代当前ACL判断
ZSet唯一成员+数值score,按分数取范围或求名次成员唯一,更新分值会移动位置;排行榜还需要确定并列规则、更新来源与容量目标
可跳过:List怎样保留顺序与重复值?

List是有序、允许重复的字符串序列。LPUSH/RPUSH从左/右端加入,LPOP/RPOP从左/右端取出并移除;LRANGE按位置读取范围,不删除元素,结束下标也包含在范围内。Set成员去重且不承诺这种位置顺序;ZSet成员唯一、按score排序,与List保留重复值不同。

一个顺序明确的预期轨迹(未连接Redis实测):从空key开始,RPUSH demo a b a后为[a,b,a];LPUSH demo x后为[x,a,b,a]。此时LRANGE demo 0 1得到[x,a],列表不变;接着LPOP得到x,RPOP得到a,剩下[a,b]。同端加入/取出可作栈,两端配合可作先进先出队列,顺序取决于所选端。

普通pop不是消费确认。元素移除后、业务处理完成前崩溃,列表不会自动找回它。LMOVE可原子转入处理中列表,但确认、超时重领、持久化配置和业务幂等仍需设计;不能由List推出持久工作流或恰好一次副作用。可靠任务边界继续看长任务与队列原节。

依据:LPUSH / RPUSH、LPOP / RPOP、LRANGE与LMOVE可靠队列模式。

实现旁注只针对 Redis 7.2.0:String 对象可采用整数编码,或基于 SDS 的 embstr/raw;不能说每个值都是同一种底层布局。SDS 保存字节长度(读取长度不靠扫描 NUL)及分配容量,能容纳中间的零字节;长度与容量不是一回事,扩容仍可能分配/拷贝。7.2.0 的小 ZSet 可用紧凑 listpack;较大表示用 dict 按成员找分值,skiplist 维护有序访问/排名。listpack 省空间但查找可能扫描;skiplist 与 dict 组合也要付指针/索引内存。

7.2.0 示例配置的 zset-max-listpack-entries=128、zset-max-listpack-value=64 是该版本可配置的元素数/成员字节长度界限,还受编码安全条件等约束;它们不是所有 Redis 版本或部署的固定规则。排查实际对象要看目标版本与配置,不能仅凭“这是 ZSet”推断它正在使用哪种编码。

同一 Redis 7.2.0,再沿普通非 TLS 客户端请求看一次职责。socket 注册到 ae 的关注集合→收到就绪事件→读入/解析→主线程执行命令→排队回复并写回;ae 按编译平台选择后端,Linux 的 epoll 只是一个例子,就绪不等于业务完成,机制见 03 的原有读操作说明。io-threads=1 使用主线程;配置多 I/O 线程且进入活跃线程路径后可分担写入,读取/解析还需 io-threads-do-reads=yes 并满足相应客户端/运行条件。I/O 线程中的 processInputBuffer 解析到命令后只标记 CLIENT_PENDING_COMMAND,回到主线程再执行,不能把 I/O 并行当成命令任意并行。

后台线程可处理 AOF 同步、异步释放等工作,RDB 后台保存可使用子进程,它们与主命令执行分责;长命令仍可能拖延其他请求。本段只核固定版本的 配置、networking.c / ae.c 及 bio.c / rdb.c 的职责,没有启动 Redis,也不承诺固定 QPS 或多线程加速。

一个三人榜:更新、前两名、自己的名次

# Redis 7.2.0语义的预期结果,未启动服务执行
ZADD rank 10 u1 20 u2 20 u3
ZRANGE rank 0 1 REV WITHSCORES   # u3 20,u2 20
ZADD rank 25 u1                 # 更新已有成员,不新增第二个u1
ZREVRANK rank u1                # 0(零基);页面显示第1名要+1

默认先按 score,再按成员的二进制字节序;REV 同时反转分值和并列次序,因此例中 u3 在 u2 前。它不是“同分共享名次”,也不是按最后更新时间排;这些业务规则需要另外定义。文档给出的常规复杂度是单成员 ZADD、ZRANK/ZREVRANK 为 O(log N),按名次取 K 个为 O(log N+K);小型紧凑编码与输出大小也影响实际耗时。一个大榜仍有内存、热点、更新时效和分片后的全局排名问题,不能据此声称百万用户 SLO 已通过。

可选续读:三人榜怎样检查到百万用户的边界

上一例的member唯一和score更新机制可以保留,但用户数不是每秒更新量。先给出活跃用户、每人更新频率、读Top-K/读个人名次的比例、允许延迟与同分规则。若只是教学假设100万成员、每分钟各更新一次,平均约16667次更新/秒;瞬时集中更新仍会高于平均,这个算术不是Redis吞吐结论。容量要实际测每成员/索引开销及峰值内存,不能只乘用户名长度。

同一业务操作重复上报积分时,用稳定事件ID去重,再按已定义的覆盖/累加规则更新;否则一次重试就可能多加分。默认ZSet同分按成员字节序排序,要不要同分共享名次、按达分时间排,必须另定,别用浮点score随意拼低位字段而丢精度。

一个全局榜key会聚集更新与排名请求;分成多个Redis key/分片会改变全局语义。对同一静态快照,各分片Top-K候选可合并求全局Top-K,但个人精确名次还需知道所有分片领先者数量及并列规则;持续更新时还要定义快照/版本与允许陈旧度。原子性不能无条件跨槽扩展。先验证热点、容量、恢复和最终排序结果,再谈SLO;这里既未搭百万用户服务,也不据一个命令闭合完整系统题。

可跳过:一套假设明确的百万成员榜参考设计

先固定参考配置。同一赛季全局榜以PostgreSQL17保存权威积分,Redis7.2单个ZSet作查询投影。沿用100万成员、每人平均60秒更新一次的教学假设,约16667次更新/秒;再假设Top100查询100次/秒、投影新鲜度目标1秒。速率和目标都是本例选择,不是题面事实或已测能力。

权威更新→可靠事件。业务先按稳定事件ID去重并核对内容;同一数据库事务锁定用户积分行,保存新的绝对积分、单调用户版本,插入outbox。提交后才确认业务接受;并发更新必须序列化或条件重试,不能让两个事件生成同一版本。下游事件带用户ID、绝对分值和版本,重复投递不再累加积分。

投影只接纳新版本。短Lua脚本检查事件、key类型与当前用户版本,仅当incoming_version较新才更新ZSet分值与版本Hash。本例分值/版本限定在可精确表示的整数范围内,不把时间戳塞进小数分数;同版本不同内容应告警。本地写成功才能推进消费进度。

脚本隔离执行不等于任意错误都回滚。本例再设epoch的dirty标记:先拒绝已dirty投影,校验后置dirty,完成分值/版本更新才清除;中途出错保留dirty,后续写入和查询均拒绝该投影,转重建。查询在同一原子读里核对健康状态并取榜,不能先检查、隔很久再读。这个保守门禁也需要实装验证。

同分与Top100。成员用固定格式ASCII用户ID,按分数降序、同分按成员字节序降序;ZRANGE key 0 99 REV WITHSCORES正好采用此规则,不额外拼浮点复合分数。此参考从主节点读,并返回epoch与已应用水位/时间;写库成功不等于投影立即可见,超过新鲜度目标时标为旧榜或暂停查询,不能继续宣称实时。

故障小轨迹:u001先到v2=90,再到v1=100,保持90;v2重投仍为90。v3=110已应用但确认丢失,重投v3也仍为110。合法扣分可降低绝对积分,是否接受取决于版本而非“分数更大”。若同事件ID换内容,拒绝并核查,不能当普通重复吞掉。

重建与切换。保留权威outbox,并使用PostgreSQL逻辑解码配套的一致性快照与日志位置L建立新epoch:快照带用户版本,重放L之后增量,只有连续处理完的提交位置才能推进水位。不能把最大自增ID当已完整提交水位;复制槽重发也靠版本去重。追到切换水位后短暂停投影写,核对成员/版本、样本排名与积压,再原子切换active epoch并续接事件;旧epoch保留到在途读取结束。

部署边界。同一Lua涉及的scores、versions、dirty和active等key用同一{board}哈希标签共槽;Cluster不会把一个全局ZSet自动分散到多节点。副本读有复制陈旧,切主或重启后先置投影不可用,校验/重放或重建后再开放。AOF/RDB策略影响恢复窗口,Redis持久化不替代权威库与可重放事件。

容量与验收。量单成员实际内存、版本Hash、双epoch重建峰值、CPU/网络、热点与更新/Top100的p95及投影lag;保留日志和复制槽也有磁盘上限。若单全局榜预算不满足,再采用前文分区候选并定义快照/陈旧度,不能宣称单节点一定够用。以上是有限设计与逻辑轨迹;百万吞吐、真实Redis/数据库和跨机灾备均未执行。

依据:PostgreSQL17事务 / 行锁 / 逻辑解码快照与重放;Redis的ZRANGE、脚本、共槽、复制与持久化。

TTL、淘汰、大 key、热 key 分别看

TTL 管寿命,maxmemory 淘汰管容量。设置 TTL 不等于永远有足够内存,也不意味着该值在到期前必定保留。7.2.0 中可选择 allkeys/volatile 范围的 LRU、LFU、random,或 volatile-ttl;LRU/LFU 是近似策略,volatile 只在带过期时间的候选中选。noeviction 不主动淘汰来腾空间,会让需要新增内存的相关写入报错,已有数据的读取仍可进行;应用必须处理写缓存失败。

LRU 淘汰最久未被访问的项,命中也会更新最近性。容量为 2,按“最久未用→最近使用”记:访问 A、B 后是 [A,B],再命中 A 变为 [B,A];插入 C 时淘汰 B,留下 [A,C]。FIFO 只按入队先后,同样轨迹可淘汰 A;LFU 依据使用频次,TTL 依据有效期,均不能代替这条最近访问顺序。这是精确 LRU 的概念轨迹,Redis 的采样近似仍按上文边界理解,不是 Redis 实测。

big key 看体积,hot key 看访问率。一个很少读取的超大 Hash 仍可能因全量返回、序列化/传输、删除/遍历成本拖慢请求;一个很小的摘要若每秒被大量访问,也可能形成热 key。先量元素数、字节数、请求频率、返回量和慢命令,再限制单次范围/分页、拆分大对象或合并重复读取;拆 key 会改变原子操作边界。不要在生产高峰为定位问题一次拉全量。这里没有给出可通用的“大”阈值,也没有测量 Redis 延迟。

依据:Cache-Aside 模式、Bloom 官方说明、Redis 淘汰策略、7.2.0 SDS / 对象编码 / ZSet 源码 / 配置;榜单命令见 ZADD、ZRANGE、ZREVRANK。


🔄 六、换个栈怎么对应

概念 Python Node(Express / Hono) Go
HTTP 客户端 httpx / requests fetch / undici net/http 的 Client
连接超时 vs 读取超时 httpx.Timeout(connect=, read=) ⚠️ fetch 只有一个整体超时,要自己拆 DialContext 与 ResponseHeaderTimeout 分开设
取消传播 asyncio 的 CancelledError AbortController ⭐ context.WithTimeout 一路传下去

⭐ 重点在第二行:不是每个栈都替你把「连不上」和「连上了不说话」分开。 分不开的那些栈,你必须自己在外面补——否则你以为设了超时,其实只设了一半。


🔗 这一章连到哪里

去哪 为什么
03 · 后端骨架 那一章最后「api/ 里不许出现 SDK 名字」的规矩,本章第一节就是它的展开
05 · 流式输出 本章 complete() 返回一整段;改成边看边等之后,超时、重试、缓存三件事的含义全都变了
12 · 限流、配额与成本护栏 ⭐ 第四节那张记账表就是它的输入。先有记录才谈得上限制,顺序不能反
智能体工程 16c · 接进真实产品 输出校验失败时带着错误重试——那是「内容重试」,本章是「故障重试」,上限和退避策略都不同
全景导论 07 · 本地部署与开源生态 自建模型时多数推理服务提供 OpenAI 兼容接口——这正是包一层的回报:换上游几乎不用改业务
AI基础设施 20 · 推理服务化 你重试的那个 429,在对面是排队与批处理策略的结果

✅ 检查点

  1. 包一层的五个理由是什么?它们的共同形状是什么?
  2. 连接超时和读取超时分别卡什么?非流式和流式通常各在哪段等待数据?整体截止时间管什么?一直不结束的请求会占用哪些资源?
  3. 为什么重试要写成白名单?except Exception: retry 会造成什么后果?
  4. 退避为什么要加抖动?不加会发生什么?
  5. 为什么成本记账必须在调用层做?账单层和业务层各缺什么?记账表的三个归因维度是哪三个?
  6. cost_of 对不认识的模型为什么返回 None 而不是 0?
  7. 缓存 key 漏掉文档 id 会发生什么?为什么这个 bug 特别危险?
  8. 假客户端的三个用途里,哪一个是别的办法替代不了的?
  9. 接口返回 200,摘要 JSON 格式正确,但来源是别的合同。哪一步会拦下来?可以显示草稿吗?
  10. 提交复核工单后读取超时。先查什么?什么条件下才能重放同一操作?
👀 答案
  1. 换模型、加日志、算成本、做缓存、测试替换。共同形状:都是「每次调用都要做、却和业务无关」的事——和依赖注入同类,只是那层管进来的边界,这层管出去的边界。
  2. 连接超时限制建立连接的等待,读取超时限制等待下一批数据。非流式通常等完整正文,流式在每一段数据之间也可能遇到静默。整体截止时间从业务请求开始算,限制包括重试和退避在内的总等待。一直挂着的请求会占住连接和并发名额。
  3. 黑名单会漏。except Exception: retry 会把 400 这类确定性错误也重试三遍,把本该 0.2 秒的错拖成 8 秒,而且日志里看起来像上游在抖。
  4. 上游抖一下,所有客户端同一瞬间失败、同一瞬间重试,第二波更集中,把刚缓过来的上游又打回去(重试风暴)。抖动把大家回来的时间摊开。
  5. 因为只有这一层同时知道两边:账单层只有一个总数(不知道谁、哪个功能),业务层不知道 token 数(它拿到的是一段文本)。三个归因维度是 user_id(谁)/ feature(哪个功能)/ model(哪个模型)——前两个只有业务层知道,得由调用方传进来,⚠️ feature 最容易漏,而漏了事后补不回去。
  6. 为了让「新模型上线时忘了配单价」在报表里显形,而不是安静地变成一笔零元开销。
  7. B 公司会拿到 A 公司的合同摘要——同一个问题、不同的检索文档,key 却一样。危险在于没有任何报错,而且命中率还会变得很好看。
  8. 故障演练:让替身精确返回 429、超时或半截 JSON,本地可以稳定复现重试和降级路径。
  9. 业务校验会拦下它。HTTP 成功且字段正确,只说明响应可以读;来源必须与服务端授权的合同及修订匹配,之后才可展示草稿。
  10. 用同一操作 ID 查业务服务的结果。能确认尚未执行,或执行方能用同一操作 ID 去重并返回已知结果,才考虑重放;结果不明时先核对。

本节回顾

⚡ 走神救援

调用层 = 把「调模型」包成你自己的一个函数。五个理由(换模型 / 加日志 / 算成本 / 做缓存 / 测试替换)共同的形状是「每次调用都要做、却和业务无关」。

地基两样:自己定的返回结构(让换 SDK 变成改一个文件,⚠️ 别把 SDK 的响应对象直接往上传)和假客户端——⭐ 它唯一不可替代的用途是故障演练:故意抛 429、故意超时、故意返回半截 JSON,重试和降级路径只有这样才测得到。

分开设超时:连接超时卡建立连接,读取超时卡等待下一批数据,整体截止时间限制本次业务操作等待多久。流式仍可能有较长静默,⚠️ 但不能按普通 API 的直觉设成几秒——长上下文和工具调用中几十秒没有字节是正常的,设太短砍掉的不是故障,是你自己最贵最慢的那些正常请求。⚠️ 不设超时的症状是「跑几天越来越慢,重启就好」——太温和,所以没人查。

重试用白名单:临时限流、暂时上游故障、发送前连接失败可以进入判断。再检查重放是否安全;400、401 或内容拒绝需要各自的处理路径——⚠️ except Exception: retry 会把 0.2 秒的错拖成好几秒,还伪装成上游在抖。退避要指数加抖动:否则上游抖一下,所有客户端同时失败、同时重试,第二波比第一波更集中。⭐ 而且首字发出去之后不能静默重试。

成本记账必须在这一层,因为只有它同时知道两边。⭐ 三个归因维度一个都不能少,⚠️ 其中「功能」最容易漏——它是唯一「不传也能跑」的,漏了就永远答不出「聊天花的还是摘要花的」,而且事后补不回去。

看见 200 时再问一次:生成完成了吗?字段能解析吗?来源符合业务规则吗?下一章会把整段响应拆成连续的事件,仍需判断最后有没有真正完成。

下一节 👉 05-流式输出.md

打卡记录保存在你的浏览器里,首页能看到总进度