进阶 python.useinstructor.com 2026-11-15 16:34:59 · 11 阅读

第12章 调试——Instructor 日志、钩子与异常排查指南

第12章:调试

本指南介绍了在使用 Instructor 时,如何快速检查输入/输出、捕获重试操作以及复现故障。内容侧重于利用钩子(hooks)、日志记录(logging)和异常数据等实用技术。

启用日志

快速调试模式(推荐)

在创建 Instructor 客户端之前,在脚本开头使用 Python 的 `logging` 模块:

```python import logging

logging.basicConfig(level=logging.INFO) logging.getLogger("instructor").setLevel(logging.DEBUG) ```

这会启用 Instructor 及其子记录器的调试信息,同时保持其他记录器在 INFO 级别。Instructor 不会读取 `INSTRUCTOR_DEBUG` 环境变量。

手动配置调试

如果希望看到其他库的调试信息,请将根记录器设置为 DEBUG 级别:

```python import logging logging.basicConfig(level=logging.DEBUG) logging.getLogger("instructor").setLevel(logging.DEBUG) ```

你将看到以下信息: - 原始响应(供应商特定的对象) - 处理器/模式选择 - 重试尝试及解析错误 - 重新询问(reask)对消息的调整

提示:设置包含时间戳和模块名称的处理器/格式化器。

使用钩子观察流程

钩子让你无需修改核心代码即可在关键时刻介入:

```python from instructor.core.hooks import HookName

# 附加一个或多个处理器 client.on(HookName.COMPLETION_KWARGS, lambda kw: print("KWARGS:", kw)) client.on(HookName.COMPLETION_RESPONSE, lambda resp: print("RESPONSE:", type(resp))) client.on(HookName.PARSE_ERROR, lambda e: print("PARSE ERROR:", e)) client.on(HookName.COMPLETION_LAST_ATTEMPT, lambda e: print("LAST ATTEMPT:", e)) client.on(HookName.COMPLETION_ERROR, lambda e: print("COMPLETION ERROR:", e)) ```

常见用途: - 捕获传递给供应商的最终 kwargs(包括 mode/tools/response_format)。 - 记录原始响应(例如写入日志或文件),以便离线分析。 - 检查解析错误以及重新询问如何修改下一次尝试。

注意:接受 `kwargs`(或参数名为 `_instructor_meta`)的处理器会收到一个包含以下内容的元数据字典: - `attempt_number`、`correlation_id`、`mode`、`response_model_name`。 在处理器签名中添加 `kwargs` 以访问该元数据:

```python client.on(HookName.COMPLETION_KWARGS, lambda kw: print(kw.get("_instructor_meta"))) ```

检查原始响应

Instructor 返回的大多数解析后的模型都携带了原始供应商响应,便于调试:

```python model = client.create(...) raw = getattr(model, "_raw_response", None) print(raw) ```

这有助于检查供应商元数据,如 token 使用情况、模型版本和供应商特定字段。

处理故障与重试

当所有重试次数耗尽后,会抛出 `InstructorRetryException`。其中包含详细的上下文信息:

```python from instructor.core.exceptions import InstructorRetryException

try: client.create(...) except InstructorRetryException as e: print("Attempts:", e.n_attempts) print("Last completion:", e.last_completion) print("Create kwargs:", e.create_kwargs) # 可复现的输入 print("Failed attempts:", e.failed_attempts) # (attempt, exception, completion) 的列表 # 如果可用,紧凑的跟踪数据包有助于调试 if hasattr(e, "trace_packet") and e.trace_packet: print("Trace packet:", e.trace_packet) ```

使用 `e.create_kwargs` 和 `e.failed_attempts` 来构建最小复现用例。

最小复现模板

```python import openai import instructor from pydantic import BaseModel

class MyModel(BaseModel): # 字段定义... pass

client = instructor.from_provider("openai/gpt-5-nano")

create_kwargs = { # 从 InstructorRetryException.create_kwargs 粘贴过来 }

try: client.create(response_model=MyModel, create_kwargs) except Exception as err: # 检查并迭代 raise ```

这种模式能够捕获触发故障的确切输入。

严格与非严格解析

`strict=True` 强制进行精确的模式匹配,并能及早发现模式漂移(schema drift)。如果供应商有时返回额外字段或类型略有不同(例如整数位置返回浮点数),请尝试使用 `strict=False` 进行非严格验证。

```python client.create(..., response_model=MyModel, strict=True) ```

自定义重试

你可以传入一个整数(尝试次数)或 `tenacity` 的 `retrying` 对象来控制行为:

```python from tenacity import Retrying, stop_after_attempt, stop_after_delay

max_retries = Retrying(stop=stop_after_attempt(3) | stop_after_delay(10)) client.create(..., max_retries=max_retries) ```

这在平衡延迟和健壮性时非常有用。

多模态与消息转换

如果你发送包含图像/音频/PDF 或可能含媒体路径/URI 的文本,Instructor 可以转换消息以适配供应商格式。

在支持的模式下,`processing.multimodal.convert_messages` 会自动运行。如果调试内容问题,请使用上述钩子在转换前后记录消息,并确保媒体类型/URI 有效。

缓存考量

如果你正在使用缓存(`cache=...`),请记住: - 成功解析的响应会被存储;从缓存获取时会跳过供应商调用。 - 如果正在调试实时供应商行为,请暂时禁用缓存或更改缓存键(例如调整消息内容)。

```python model = client.create(..., cache=None) ```

常见故障排查技巧

- 验证 `response_model.model_json_schema()` 是否符合预期供应商返回内容。 - 确认 mode 对你的供应商是否有效;不匹配可能导致解析失败。 - 检查供应商侧限制(最大 token/响应长度);不完整的输出会引发特定异常。 - 如果使用 Markdown JSON (MD_JSON),确保供应商确实返回了 ` ```json ` 代码块。

如果需要更深入的可见性,请添加自定义处理器,将 kwargs/响应/错误写入磁盘,并附带时间戳和相关 ID。

示例:本地调试运行

你可以运行一个最小化的、无网络的示例,该示例使用伪造的供应商函数来测试钩子、日志记录和解析流程:

文件:`examples/debugging/run.py`

运行: ```bash python examples/debugging/run.py ```

此脚本执行以下操作: - 为 `instructor.*` 启用 DEBUG 日志记录 - 使用 `instructor.patch(mode=Mode.JSON)` 修补伪造的供应商 `create` 方法 - 附加钩子处理器以打印 kwargs、响应类型和解析错误 - 将简单的 JSON 负载解析为 Pydantic 模型并打印结果

评论 (0)