用Jupyter高效调试LLM API：从请求封装到流式响应的完整实践

1. 为什么我折腾了一圈，最后还是留在了Jupyter里调试LLM API

1.1 独立脚本调试的三宗罪

先讲个我最近的真实经历。有段时间我一直在写一个对接大模型服务的脚本，最开始是普通的 .py 文件，写完 python test.py 跑一遍。第一次跑，发现返回结果里没有我想要的字段；改一下 prompt 模板，再跑一次；又发现温度参数设高了，回答风格太飘；再改，再跑。到了第五次，我已经分不清刚才那次报错到底是改 prompt 引入的，还是响应解析函数本身就有 bug。

这就是独立脚本调试 LLM API 的第一宗罪：改一个参数就得重跑整个脚本。脚本虽然小，但每次重跑都要经历"构造请求 → 网络传输 → 模型推理 → 返回解析 → 打印结果"的完整链路，中间任何一环出错，前面所有的中间变量全都没了。第二宗罪是中间变量没法保留。response.json() 拿到手以后，我想看看 usage 字段长什么样，又想知道 choices[0].message.content 里到底有没有多余换行，这些临时探索只能靠 print，打印完就扔。第三宗罪更隐蔽——请求和响应之间的因果关系全靠脑补。一次调用返回异常结果，到底是温度太高、上下文里混进了脏数据、还是系统 prompt 被截断了？如果只看最终输出，根本无从判断。

后来我换成了 Jupyter Notebook 做调试，上述三个痛点立刻缓解了大半：每个 Cell 单独跑，参数改了只重跑对应的 Cell；api_response 这种中间变量就躺在内存里，想怎么查怎么查；还能把请求日志、prompt 原文、响应结果放在同一个 Cell 里并排观察，因果链路一目了然。

1.2 Jupyter 真正解决问题的机制

Jupyter 的核心理念是"交互式计算"，它把代码拆成一个个可以被反复执行的 Cell，并且 Cell 之间共享同一个内核（变量空间）。对 LLM API 调试来说，这个机制几乎是为我们量身定做的。

第一次拿到某个模型服务的接口文档，你可以先在一个 Cell 里写好最基础的请求：

python复制import requests
import json

url = "https://api.example.com/v1/chat/completions"

payload = {
    "model": "your-model-name",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}],
    "temperature": 0.7
}

resp = requests.post(url, json=payload, headers={"Authorization": "Bearer YOUR_API_KEY"})
data = resp.json()

先别急着写解析逻辑，直接在下一个 Cell 里看 data 长什么样：

python复制print(json.dumps(data, ensure_ascii=False, indent=2))

这一步非常关键。很多新手拿到接口第一件事就是按文档写解析代码，结果文档和实际返回字段存在细微差异（比如有的服务把 message 字段叫 completion，有的服务把 content 放在 choices[0].text 里），跑出来全是 None 才发现不对劲。在 Jupyter 里随手打印、随手翻字段结构，是成本最低的接口熟悉方式。

1.3 Jupyter 调试 LLM API 的隐性坑

但 Jupyter 也不是没有代价。我踩过最深的坑有三个：

第一个坑：重复执行同一个请求 Cell，白白烧 Token。 初次接触某个模型接口时，我习惯反复修改 prompt 里的措辞，每次都重跑请求，结果账单比我预期高了不少。后来我养成了习惯，在每个请求 Cell 顶部先打印出本次要发送的 payload，确认无误再执行；同时给封装函数加了缓存开关，测试阶段重复执行直接走缓存，只有确认要观察真实效果时才关闭缓存。

第二个坑：变量被后续 Cell 悄悄覆盖。 我在 Notebook 里同时调试两个模型服务，早期习惯把响应都存成 data，结果后面那个 Cell 一执行，前面的 data 就被覆盖了。等再回头想用第一个服务的结果时，只能重新跑。现在我会给每个调试段落分配专属变量名（比如 resp_platform_a、resp_platform_b），或者干脆用函数封装，不依赖全局变量。

第三个坑：Cell 执行顺序依赖。 如果第 3 个 Cell 用到了第 1 个 Cell 定义的变量，而你单独执行第 3 个 Cell 时第 1 个还没有跑，就会报 NameError。这个问题在调试长流程时尤其烦人。我的解决方案是：每个逻辑闭环（构造请求 → 发起调用 → 解析结果）尽量放在同一组连续 Cell 里，并且保持从上到下顺序执行，不跳跃。

理解了这些之后，我再往下说环境搭建和请求封装，这两步做好了，后续所有调试都会顺畅很多。

2. 调试环境搭建：密钥管理、依赖安装与一次像样的请求封装

2.1 别再把 API Key 直接写死在代码里

我知道很多人调试 LLM API 的第一步，是直接在 Jupyter Cell 里写：

python复制API_KEY = "sk-xxxxxxxxxxxx"

本地测试图省事可以理解，但这个习惯一旦养成，后面第三方协作或者不小心把 Notebook 传到公开仓库，密钥就直接泄露了。而且有些团队的密钥管理系统会定期轮换，写死的密钥过期以后，你还得满仓库找这串字符串，非常痛苦。

我的做法是使用环境变量 + python-dotenv 来管理。先在项目目录建一个 .env 文件：

code复制MODEL_API_KEY=sk-your-key-here
MODEL_API_BASE=https://api.example.com
MODEL_NAME=your-model-name

在 Jupyter 的第一个 Cell 里统一加载：

python复制from dotenv import load_dotenv
import os

load_dotenv()

API_KEY = os.getenv("MODEL_API_KEY")
API_BASE = os.getenv("MODEL_API_BASE")
MODEL_NAME = os.getenv("MODEL_NAME")

print("Key loaded:", bool(API_KEY))
print("API Base:", API_BASE)
print("Model:", MODEL_NAME)

记得把 .env 加进 .gitignore。这里有个容易忽略的细节：.env 文件里如果值包含特殊字符（比如带等号、井号），需要用引号包起来；另外 load_dotenv() 默认不会覆盖已有的同名环境变量，如果担心这点，可以显式传 override=True。

在调试阶段在 Notebook 里打印 bool(API_KEY) 而不是直接打印 Key 本身，防止密钥露出在界面上。这个习惯我现在一直保持。

2.2 封装一个带日志、超时和重试的调用函数

调试过程中我反复修改调用参数，每次都把完整的请求代码重写一遍实在低效。所以我倾向于在 Notebook 里沉淀一个通用的调用函数，这个函数不追求生产级完备，但必须包含三个调试友好特性：可见的日志、合理的超时、基础的异常分类。

python复制import requests
import time
import logging
import json

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
logger = logging.getLogger("llm_debug")

def call_llm(
    messages,
    model=None,
    temperature=0.7,
    max_tokens=None,
    timeout=30,
    retries=2,
    base_url=API_BASE,
    api_key=API_KEY
):
    url = f"{base_url}/chat/completions"
    payload = {
        "model": model or MODEL_NAME,
        "messages": messages,
        "temperature": temperature,
    }
    if max_tokens:
        payload["max_tokens"] = max_tokens

    logger.info("Request payload:\n%s", json.dumps(payload, ensure_ascii=False, indent=2))

    for attempt in range(retries + 1):
        try:
            resp = requests.post(
                url,
                json=payload,
                headers={"Authorization": f"Bearer {api_key}"},
                timeout=timeout
            )
            resp.raise_for_status()
            return resp.json()
        except requests.exceptions.Timeout as e:
            logger.warning("Timeout on attempt %d: %s", attempt + 1, e)
        except requests.exceptions.HTTPError as e:
            logger.warning("HTTP error on attempt %d: %s", attempt + 1, e)
            logger.warning("Response text: %s", resp.text[:500])
            break
        except requests.exceptions.ConnectionError as e:
            logger.warning("Connection error on attempt %d: %s", attempt + 1, e)

        if attempt < retries:
            sleep_time = 2 ** attempt
            logger.info("Sleeping %s seconds before retry", sleep_time)
            time.sleep(sleep_time)
    return None

这里我故意把日志打印做得比较"啰嗦"，因为调试阶段最怕的就是请求不可见。timeout=30 指的是连接后等待响应的总超时时间，可以根据模型实际推理速度调整；retries=2 配合指数退避，2 ** attempt 依次是 1 秒、2 秒，基本能应对临时网络抖动。

这个函数其实还不够格用于生产，因为缺少流式支持、没有上下文自动截断、也没有处理模型服务方特殊返回格式。但它非常适合调试：每次调用前后，你都能清楚知道发送了什么、收到了什么、卡在了哪一步。

3. 请求与响应拆解：如何把一次模型调用"看穿"

3.1 请求侧日志：先确认自己发出去的东西

调试 LLM API 有一个很反直觉的经验：大部分问题不是接口出了问题，而是请求本身就不符合模型服务的预期。比如 messages 列表里的 role 字段写错了、content 里带了不可见字符、temperature 传了 0 和 1 之外的非法值，这些都很容易被忽略。

所以我强烈建议在调试阶段，把请求的前 500 个字符完整打印出来，而不是只打印消息长度。上面那个 call_llm 函数已经做了这件事。这里再补充一个细节：如果请求太大（比如把整本文档塞进上下文），打印 payload 会把 Notebook 刷屏，这是正常的，别慌，可以通过只打印 messages 的摘要来控制显示量：

python复制def summarize_messages(messages):
    parts = []
    for m in messages:
        content = m.get("content", "")
        if len(content) > 100:
            content = content[:100] + "...（截断）"
        parts.append(f"<{m['role']}>: {content}")
    return "\n".join(parts)

这能让你在保持 log 可见的同时，又不至于被全文淹没。另外一个很容易被忽略的请求侧问题是：编码。当 content 里包含特殊 Unicode 字符时，有些老旧的 requests 版本会在传输前发生编码问题。所以我在发送前统一做一次 content.encode("utf-8", errors="replace").decode("utf-8") 的清洗，可以提前排除掉很多诡异的 bug。

3.2 响应结构解析：不要凭文档猜，要以实际返回为准

不同模型服务商的响应结构大同小异，但字段细节经常不一样。最典型的返回结构（以 OpenAI 兼容格式为例）如下：

json复制{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "your-model-name",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是模型生成的文本"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 28,
    "total_tokens": 40
  }
}

在 Jupyter 里，我一般会写一个小工具函数，把响应里最关心的字段抽出来定义成结构体：

python复制from dataclasses import dataclass

@dataclass
class LLMResponse:
    content: str
    finish_reason: str
    prompt_tokens: int
    completion_tokens: int
    total_tokens: int
    raw: dict

def parse_response(data: dict) -> LLMResponse:
    choice = data["choices"][0]
    usage = data.get("usage", {})
    return LLMResponse(
        content=choice["message"]["content"],
        finish_reason=choice["finish_reason"],
        prompt_tokens=usage.get("prompt_tokens", 0),
        completion_tokens=usage.get("completion_tokens", 0),
        total_tokens=usage.get("total_tokens", 0),
        raw=data
    )

这个封装最大的价值在于：后续调试任何与返回内容相关的逻辑，你都可以直接操作 resp_obj.content、resp_obj.finish_reason，而不是反复从嵌套字典里取字段。遇到解析失败（比如返回的是错误信息而不是正常结构），data 可能是 {"error": {...}}，此时 parse_response 会抛 KeyError，这本身就是一种强制失败，让你第一时间注意到接口返回异常。

3.3 Token 用量与成本审计：从"能跑"到"跑得明白"

很多人在调通接口之后就停了，从来不看 usage 字段。但如果你要做的不是一次性 demo，而是批量任务、多轮对话、或者工具调用流程，Token 用量直接决定成本上限。

我在调试阶段会用 pandas 记录每次调用的 token 消耗：

python复制import pandas as pd

cost_records = []

def record_call(session_label, resp_obj):
    cost_records.append({
        "session": session_label,
        "model": resp_obj.raw.get("model"),
        "prompt_tokens": resp_obj.prompt_tokens,
        "completion_tokens": resp_obj.completion_tokens,
        "total_tokens": resp_obj.total_tokens,
        "content_preview": resp_obj.content[:30]
    })

每次实验结束，直接看表格：

python复制df = pd.DataFrame(cost_records)
df

这样你可以直观看到哪一轮 prompt 写得过长、哪一轮生成文本把 max_tokens 撑满了、哪一轮的 finish_reason 从 stop 变成了 length。如果某次调用的 finish_reason 是 length，说明生成内容达到了 max_tokens 上限被强制截断，这通常意味着要么增加 max_tokens，要么压缩 prompt 让模型少废话。

成本估算也不必等到月底账单。如果你的服务按 token 计费，可以按官方单价在 Notebook 里写一个估算函数：

python复制PRICE_PER_1K_PROMPT = 0.002   # 示例价格，按实际服务替换
PRICE_PER_1K_COMPLETION = 0.002

def estimate_cost(resp_obj):
    prompt_cost = resp_obj.prompt_tokens / 1000 * PRICE_PER_1K_PROMPT
    completion_cost = resp_obj.completion_tokens / 1000 * PRICE_PER_1K_COMPLETION
    return prompt_cost + completion_cost

cost_records[-1]["estimated_cost"] = estimate_cost(resp_obj)

这一套做完，你的调试就不再只是"调通"，而是"调明白"——每花一分钱都知道花在哪里。

4. 实战中高频踩坑的异常类型与调试对策

4.1 超时与连接重置：先分清是客户端等太久还是服务端处理慢

我调试时遇到最多的异常是超时。requests.exceptions.Timeout 分为连接超时和读取超时。连接超时说明目标地址连不上（可能网络隔离、域名解析失败、服务临时不可用）；读取超时则往往意味着模型推理时间超过了你的 timeout 设置，尤其是长上下文、大模型或低性能推理环境。

调试思路是分层确认：先用 curl 或 ping 级别的方式确认目标可达，再用一个极小请求（比如只问"你好"）测试接口连通性，最后再逐步增加上下文长度和生成长度。如果小请求很快而大请求超时，那就是处理耗时问题，应该调大 timeout，而不是认为服务挂了。

一个容易被忽略的点：当 max_tokens 设置得很大时，模型可能需要生成很长时间，此时 timeout 要留够余量。例如生成 2000 个 token，有些服务可能需要 60 秒以上。我的习惯是根据预估 token 数乘一个倍数来动态设置超时：

python复制estimated_completion_tokens = 1000
safe_timeout = max(30, int(estimated_completion_tokens / 20) + 30)

这个公式不一定普适，但思路是：生成越长的内容，预留的时间越多。

4.2 限流与并发控制：遇到 429 别只会重试

如果你连续发起多个请求，很容易收到 HTTP 429（Too Many Requests）。很多人的第一反应是加 time.sleep(1)，但这并不总能解决问题，因为不同服务的限流策略差别很大：有按 QPS 限的，有按每分钟 Token 数限的，有按并发数限的。

我建议在调试阶段记录每次请求的响应头，尤其是与限流相关的头字段：

python复制def try_call_with_headers(messages):
    resp = requests.post(
        f"{API_BASE}/chat/completions",
        json={"model": MODEL_NAME, "messages": messages},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30
    )
    return resp.status_code, dict(resp.headers), resp.text

很多服务会在响应头里返回 x-ratelimit-remaining、x-ratelimit-reset 之类的信息。如果某个头显示剩余配额为 0，就该停止重试，等 reset 时间过后再跑。简单的退避重试在这里其实是双刃剑：如果所有客户端都在退避后同时重试，反而会在瞬间制造新的限流峰值，这个称为"惊群效应"。我自己调试时遇到 429，会先把并发实验改成串行，再检查限流头，确认恢复时间后再继续，而不是盲目加大延迟。

4.3 上下文长度超限：理解 Token 计数的"隐藏"消耗

调试多轮对话或文档问答时，经常遇到请求返回类似"context length exceeded"的错误。这个错误的根源不只是你直接发送的 messages 里 content 的长度，还包括系统提示、角色标签、甚至历史对话里每一个换行符和缩进都会消耗 Token。

一个非常容易踩的坑是：你以为只发了一小段文本，但服务端按 Token 计数是按词元切分的，英文一个词大约 1.3 个 Token，中文一个字大约 1~2 个 Token，而且标点符号单独计。同一个字符串，在不同模型的计数规则下开销完全不同。

我的调试应对策略是写一个"上下文预算"检查函数：

python复制def estimate_context_tokens(messages, chars_per_token=2.0):
    total_chars = 0
    for m in messages:
        total_chars += len(m.get("content", ""))
    return int(total_chars / chars_per_token)

这个估算当然不精确，但作为早期预警足够了：当估算值达到模型上下文窗口上限的 80% 时，我就主动对历史消息做截断或摘要，而不是等着服务端报错。截断策略我常用两种：一是保留系统提示和最近 N 轮对话，中间历史做粗粒度摘要；二是把超长文档拆成小块，分批查询后再合并答案。

4.4 异常处理整体框架：让 Notebook 不完全中断

调试阶段另一个常见烦恼是单个请求异常导致整个 Notebook 卡住或中断，后面的对比实验没法继续。我在 Notebook 里不会直接让 requests.post 裸奔，而是用一层"兜底"逻辑：

python复制def safe_call_llm(messages, model=None):
    try:
        resp_obj = parse_response(call_llm(messages, model=model))
        return resp_obj
    except Exception as e:
        print(f"调用失败: {type(e).__name__}: {e}")
        return None

然后在循环批量测试时，单个失败只打印警告，不影响大局：

python复制test_prompts = [
    "你好",
    "写一篇关于猫的短诗",
    "解释什么是量子纠缠"
]

for idx, prompt in enumerate(test_prompts):
    result = safe_call_llm([{"role": "user", "content": prompt}])
    if result is not None:
        print(f"Prompt {idx}: {result.content[:50]}...")

这样即使某个 prompt 因为超时失败，后续 prompt 仍然会继续执行。我在实际调试中靠这个方法保住过大批量的对比测试，不至于因为一个长文本请求超时就把整轮实验作废。

5. 流式调试：让生成过程可见、可停、可统计

5.1 流式响应的底层逻辑

很多模型的 API 默认是"一次性返回完整结果"，即服务端把整个生成文本都算完以后才返回。这有两个问题：一是等待时间很长，二是无法提前判断生成方向是否正确。流式响应（streaming）则把响应切成一串增量片段，客户端逐块接收，可以一边生成一边看到内容。底层通常是 SSE（Server-Sent Events）格式：服务端按行推送以 data: 开头的数据块，最后以 data: [DONE] 结束。

在 Jupyter 里调试流式响应，最大的价值是能实时观察生成过程。比如一个模型在生成代码时突然开始重复某个片段，流式模式下你能在第一分钟就发现，直接中断这次调用，而不是等两分钟拿到完整输出后再看。这个优势在普通请求模式下是完全没有的。

5.2 Notebook 中的流式调试代码

下面是一个兼容多数 OpenAI 风格接口的流式调用封装：

python复制def call_llm_stream(
    messages,
    model=None,
    temperature=0.7,
    timeout=60
):
    url = f"{API_BASE}/chat/completions"
    payload = {
        "model": model or MODEL_NAME,
        "messages": messages,
        "temperature": temperature,
        "stream": True,
    }

    resp = requests.post(
        url,
        json=payload,
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=timeout,
        stream=True
    )
    resp.raise_for_status()

    collected = []
    for raw_line in resp.iter_lines():
        line = raw_line.decode("utf-8", errors="replace")
        if not line.startswith("data:"):
            continue
        data_part = line[len("data:"):].strip()
        if data_part == "[DONE]":
            break
        chunk = json.loads(data_part)
        if chunk.get("choices") and chunk["choices"][0].get("delta"):
            delta_content = chunk["choices"][0]["delta"].get("content", "")
            if delta_content:
                collected.append(delta_content)
                print(delta_content, end="", flush=True)

    print()
    return "".join(collected)

注意 resp.iter_lines() 的用法：stream=True 是必须的，否则 requests 会一次性把整个响应体加载进内存，也就失去了流式的意义。另外，不同服务商对于 delta 内容的字段名可能有差异，有些叫 text 而不是 content，这是调试流式接口时最容易踩的兼容性坑。我在实际调试某个服务时，就遇到过它把增量文本放在 choices[0].delta.text 里，按官方文档写的 content 怎么都取不到。

5.3 流式调试的进阶玩法

除了逐字打印，流式调试还可以做几件普通请求做不到的事：

第一，提前中断观察。 如果发现模型生成的答案明显偏题，可以直接用 KeyboardInterrupt 中断 Cell，此时连接会被关闭，之后再根据已生成的片段调整 prompt。这在调试长文本生成场景中非常省时间。

第二，统计首 token 延迟。 记录发出请求后到收到第一个 content token 的时间差，这个指标对体验影响很大。若首 token 延迟过高，可能是模型排队严重，也可能是网络链路问题。

python复制import time

start = time.time()
received_any = False
for raw_line in resp.iter_lines():
    # ... 解析逻辑
    if delta_content and not received_any:
        received_any = True
        print(f"首 token 延迟: {time.time() - start:.2f}s")

第三，拼接后做完整分析。 流式返回的内容虽然是一个片段一个片段攒起来的，但最终还是要拼成一个完整字符串，才能做关键词提取、格式校验或者长度统计。上面的 call_llm_stream 已经做了拼接，返回的字符串可以直接喂给下游解析逻辑。

这里我想强调一个容易犯的错：不要在每个 chunk 里单独做业务判断。举个例子，如果你想判断模型生成的文本里有没有提到某个关键词，在流式阶段就直接终止整个循环，看似可以省流量，但你可能在一个不完整的中间片段里错过了关键词，导致误判。我一般会先完整收集，再统一做判断。

6. 从 Notebook 到可复用模块：让调试成果不止于"跑通"

6.1 什么时候该从 Jupyter 搬代码

很多人的 Notebook 里躺着一大坨调通了的代码，但始终只是"能跑"状态。判断要不要把代码提取成正式模块，我一般看三个信号：同一段逻辑是否被重复复制粘贴超过三次；是否开始有人（包括未来的自己）要复用这份逻辑；是否涉及需要单元测试的稳定预期（例如响应解析规则）。

提取模块不是简单地把 Cell 里的代码拷进 .py 文件。我会先做一次"去调试化"清理：把打印日志改成 logging 等级控制；把 API_KEY 从全局变量改成构造参数或读取环境变量；把 call_llm、call_llm_stream、parse_response 这些函数放回一个独立的 llm_client.py 模块中。

python复制# llm_client.py
import os
import time
import json
import logging
import requests

logger = logging.getLogger(__name__)

class LLMClient:
    def __init__(self, api_key=None, base_url=None, model=None):
        self.api_key = api_key or os.environ.get("MODEL_API_KEY")
        self.base_url = base_url or os.environ.get("MODEL_API_BASE")
        self.model = model or os.environ.get("MODEL_NAME")

    def chat(self, messages, temperature=0.7, max_tokens=None, **kwargs):
        # 这里复用之前调试中验证过的调用逻辑
        ...

    def chat_stream(self, messages, temperature=0.7, **kwargs):
        # 流式封装
        ...

提取之后，Notebook 里的调试代码会变得非常薄：

python复制from llm_client import LLMClient

client = LLMClient()

resp = client.chat([{"role": "user", "content": "你好"}])
print(resp.content)

这样做最大的好处是：调试现场的分析逻辑和业务逻辑分离了。以后别人要复用你的能力，只需要 pip install 或拷贝模块，不需要顺着你的 Notebook 一步一步重跑。

6.2 基于模拟响应的回归测试：不烧 Token 就能验证行为

调试 LLM API 时还有一个很现实的问题：写测试用例不能每次都真实调用 API，否则测试成本极高，而且网络不稳定会导致测试结果不可复现。我通常的做法是用 responses 或 unittest.mock 拦截 requests 请求，回归测试只验证我们的解析逻辑和异常处理逻辑。

python复制# test_llm_client.py
import unittest
from unittest import mock
from llm_client import LLMClient

class TestLLMClient(unittest.TestCase):
    def test_chat_parse_success(self):
        fake_response = {
            "choices": [{
                "message": {"role": "assistant", "content": "你好，我是测试"},
                "finish_reason": "stop"
            }],
            "usage": {"prompt_tokens": 5, "completion_tokens": 8, "total_tokens": 13}
        }

        with mock.patch("llm_client.requests.post") as mocked_post:
            mocked_post.return_value.status_code = 200
            mocked_post.return_value.json.return_value = fake_response
            client = LLMClient(api_key="test", base_url="http://localhost", model="test-model")
            result = client.chat([{"role": "user", "content": "hi"}])

        self.assertEqual(result.content, "你好，我是测试")
        self.assertEqual(result.completion_tokens, 8)

这个测试没有发生任何真实网络请求。此后你每次改动 LLMClient 的解析逻辑，都可以快速回归，不用担心误改一处导致线上解析崩了。

6.3 我坚持沉淀的三类"调试资产"

最后分享一个我自己的沉淀习惯。除了代码本身，我还会为每个模型服务整理三类调试资产：

第一类是字段对比表。我会在 Notebook 里记录不同模型服务的响应字段差异：哪些是统一的、哪些有别名、哪些返回类型不一致。这张表看起来不起眼，但当我们接到新项目需要切换模型供应商时，它能帮你省掉大量重新调研的时间。例如：

第二类是问题排查清单。我会把调试中遇到过的每个异常类型、可能原因、验证方法、解决建议记成一份 checklist。以后排查新问题时就按清单逐条过一遍，大部分问题都能在十分钟内定位。

第三类是调试模板 Notebook。每个新项目开始时，我都会复制一份模板 Notebook：第一段加载环境变量，第二段封装基础调用函数，第三段放请求/响应解析工具，第四段记录 Token 成本。这样一来，每次调试不用从零开始，专注在业务逻辑本身，效率会明显提升。

说实话，Jupyter 调试 LLM API 这件事，看起来只是环境选择问题，但真正拉开调试效率差距的，是你能不能把一次成功的调试验证变成一套可复用的流程。从第一条请求日志，到字段解析，到异常排查，到流式观察，再到最后的模块化测试，每一步多做一点点沉淀，后面就能少走很多弯路。