概述与项目定位

Instructor 是一个基于 Pydantic 的 Python 库，用于从任意大语言模型中提取可靠的结构化 JSON 输出。它通过类型注解和自动校验，将"自然语言 → 类型化对象"的转换过程标准化，避免用户手写 JSON 解析、错误处理与重试逻辑。资料来源：README.md:1-25。

其核心承诺可以概括为三件事：

• 以 Pydantic 模型声明输出结构，获得 IDE 提示与运行期校验。
• 多 Provider 适配，同一份模型代码可复用到 OpenAI、Anthropic、Gemini、Cohere、Bedrock、Writer、GenAI 等后端。
• 内置重试、流式、Hooks 等工程化能力，无需重复造轮子。

官方 README 明确将 Instructor 与"原始 JSON 模式"以及 LangChain/LlamaIndex 进行对比，强调其专注于"结构化抽取"一件事，更轻量、更易调试。资料来源：README.md:43-50。

安装与最小示例

通过 pip 即可安装：

pip install instructor

安装完成后，仅需三步即可完成一次抽取：定义 Pydantic 模型、创建 Instructor 客户端、调用 chat.completions.create 并传入 response_model。资料来源：README.md:9-25。

import instructor
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "John is 25 years old"}],
)

print(user)  # User(name='John', age=25)

上述代码展示了 Instructor 的"零样板"风格——response_model=User 让库内部自动完成 schema 注入、JSON 解析、字段校验与失败重试。资料来源：README.md:17-25。

多 Provider 接入方式

Instructor 通过分层注册表（v2 Registry）统一管理不同 Provider 的"模式—处理器—客户端"三元组。from_provider 字符串会路由到对应的工厂函数，例如 OpenAI 走 from_openai、Anthropic 走 from_anthropic、Writer 走 from_writer。资料来源：instructor/v2/providers/writer/client.py:1-40。

各 Provider 的客户端工厂通常遵循相同模式：

1. 检查对应 SDK 是否已安装，未安装时抛出 ClientError 并提示安装命令。资料来源：instructor/v2/providers/writer/client.py:55-60。
2. 使用 normalize_mode 将 Provider 特定模式（如 ANTHROPIC_TOOLS）归一化为通用模式（TOOLS）。资料来源：instructor/v2/providers/anthropic/client.py:62-70。
3. 通过 mode_registry.is_registered 校验模式是否在当前 Provider 下注册，否则抛出 ModeError 并列出可用模式。资料来源：instructor/v2/providers/anthropic/client.py:73-82。
4. 调用 patch_v2 将 Provider 客户端与归一化后的模式绑定。资料来源：instructor/v2/providers/writer/client.py:1-20。

为兼容 v1 命名空间，instructor/providers/writer/client.py 仅作为门面（facade）转 re-export v2 实现。资料来源：instructor/providers/writer/client.py:1-5。

Provider 与支持模式速查

社区反馈：Google 正在以 google-genai 取代 google-generativeai，v2 Gemini schema 模块已发出 DeprecationWarning，建议迁移到 google-genai。资料来源：instructor/v2/providers/gemini/schema.py:15-19。

工作原理：Schema 生成与请求注入

Instructor 的核心能力建立在"将 Pydantic 模型转译为各 Provider 的原生结构"之上。generate_openai_schema 接受一个 BaseModel 子类，调用 model.model_json_schema() 拿到 JSON Schema，再结合 docstring_parser 解析的 docstring 把字段描述补全到 schema 中。资料来源：instructor/v2/providers/openai/schema.py:9-45。

对于 Anthropic，复用同一份 OpenAI schema 后，将其包装为 input_schema 字段以匹配 Anthropic 的工具调用格式。资料来源：instructor/v2/providers/anthropic/schema.py:11-19。

以 Writer 的 MD_JSON 模式为例，处理器会把 schema 序列化为 JSON 字符串并作为 system 消息注入到 messages 列表首部，要求模型以 Markdown 代码块形式返回 JSON。资料来源：instructor/v2/providers/writer/handlers.py:30-60。

对于支持模板的用户输入，Instructor 提供轻量级的消息级 Jinja2 处理：process_message 会判断 content 是字符串还是 Content 对象，递归地对文本部分调用 apply_template，非文本部分原样保留。资料来源：instructor/v2/providers/openai/templating.py:9-15、instructor/v2/providers/genai/templating.py:1-15。

常用配套能力

• Hooks 事件：可监听 completion:kwargs、completion:response、completion:error、completion:last_attempt、parse:error，用于埋点、日志与重试策略。资料来源：examples/hooks/README.md:9-18。社区已提出希望把 attempt_number 等重试元数据也注入 completion:error / completion:last_attempt，参见 issue #2222。
• 工具脚本：scripts/make_clean.py 用于清理 Markdown 特殊空白字符，scripts/fix_api_calls.py 统一替换为 client.create 等简化调用形式，可纳入 pre-commit。资料来源：scripts/README.md:7-20与scripts/README.md:55-70`。
• 多语言生态：除 Python 主体外，社区还维护了 TypeScript、Ruby、Go、Elixir、Rust 版本。资料来源：README.md:27-36。

入门建议与常见陷阱

1. 优先使用 Mode.TOOLS：工具/函数调用是各 Provider 推荐的强结构化输出路径，解析最稳定。仅在工具调用不可用时回退到 MD_JSON 或 JSON。资料来源：instructor/v2/providers/anthropic/client.py:62-82`。
2. 留意 Provider 依赖：每个 Provider 的 SDK 是可选依赖，缺失时 from_<provider> 会抛出带安装提示的 ClientError。资料来源：instructor/v2/providers/writer/client.py:55-60。
3. 多模态与 Bedrock 安全约束：v1.15.1 起，_openai_image_part_to_bedrock 拒绝远程 HTTP(S) 图片 URL，PDF.to_bedrock 仅接受 base64 或 s3:// 来源，用于阻断 SSRF 与本地文件泄露。资料来源：README.md release notes v1.15.1。
4. 模板与 Provider 兼容性：使用 Jinja2 模板时，不同 Provider 对 messages / chat_history / Content.parts 结构有差异，建议参考对应 templating.py 实现。资料来源：instructor/v2/providers/genai/templating.py:1-15。

另请参阅

• Hooks 系统与可观测性
• 多 Provider 模式与重试
• Schema 生成与校验
• 项目脚本与文档维护

核心功能：验证、重试、流式输出与钩子

Instructor 的核心价值在于将大语言模型（LLM）的"非结构化文本"自动转换为经过 Pydantic 强类型校验的 Python 对象，并围绕这一目标提供了验证（Validation）、重试（Retries）、流式输出（Streaming） 与钩子（Hooks） 四大支柱能力。这四项能力在 v2 分层注册体系下被统一抽象到每个 Provider 的 Handler 中，跨厂商（OpenAI、Anthropic、Gemini、Writer、Cohere、GenAI 等）保持一致接口。

架构总览

下图展示了客户端一次请求经过四道核心关卡的典型流程：

sequenceDiagram
    participant U as 用户代码
    participant H as Provider Handler
    participant M as LLM API
    participant V as Pydantic 验证
    participant R as Reask 重试
    participant K as 钩子系统

    U->>H: 提交 response_model 与 messages
    H->>M: 构造请求（tools/JSON/md_json）
    M-->>H: 返回原始响应
    H->>V: 解析并 model_validate_json
    V-->>H: 校验通过 / ValidationError
    alt 校验失败
        H->>K: 触发 completion:error
        H->>R: handle_reask 重新打包
        R->>M: 再次调用 LLM
    else 校验通过
        H->>K: 触发 completion:last_attempt
        H-->>U: 返回强类型对象
    end

验证（Validation）

验证是 Instructor 的第一道闸门。Pydantic BaseModel 既作为用户声明的目标类型，也作为运行期验证器；Handler 在解析阶段调用 response_model.model_validate_json 完成强类型转换。资料来源：instructor/v2/providers/openai/schema.py:13-43 中的 generate_openai_schema 会在生成工具描述时把字段级 docstring 注入到 parameters.properties[*].description，让 LLM "看到" 与运行时 Pydantic 一致的约束。

不同 Provider 在验证路径上存在差异：Anthropic 在 JSON_SCHEMA 模式下直接消费 text 块并调用 model_validate_json（资料来源：instructor/v2/providers/anthropic/handlers.py:stop_reason 分支）；Writer 的 MD_JSON Handler 则需要先通过 extract_json_from_codeblock 从 Markdown 代码块中剥离 JSON（资料来源：instructor/v2/providers/writer/handlers.py:MD_JSONHandler）。

用户还可以组合 Annotated[..., BeforeValidator(...)] 注入自定义校验逻辑。资料来源：examples/validators/readme.md:Adding Custom Validation 演示了使用 llm_validator("don't say objectionable things", allow_override=True) 让 LLM 自身充当"二阶段评审员"，典型输出为 1 validation error for QuestionAnswerNoEvil 形式的诊断信息。

重试（Retries）

重试机制与验证是强耦合关系：当 model_validate_json 抛 ValidationError 时，Handler 不会立即把异常抛给调用方，而是调用 handle_reask 将错误信息回填到下一轮请求中。资料来源：instructor/v2/providers/writer/handlers.py:JSONSchemaHandler.handle_reask 展示了 Writer 在 JSON_SCHEMA` 模式下的标准重打包逻辑。

重试次数通常由调用方通过 max_retries 参数控制。在 v1.14.3 发布说明中提到，修复了 "Stream objects crashing reask handlers when using streaming with max_retries"，说明在流式路径上重试与解析的协作曾是一个反复打磨的点（资料来源：v1.14.3 release notes）。社区也反馈希望在 completion:error 钩子中暴露 attempt_number 等元数据（参考 issue #2222），以便用户区分"可重试的中间错误"与"最终失败"。

流式输出（Streaming）

流式输出在大对象或长 JSON 场景下非常关键。Instructor 在 v2 Handler 体系里通过 _register_streaming_from_kwargs 与 _consume_streaming_flag 两个内部方法，把"是否处于流式上下文"注入到响应模型上，资料来源：instructor/v2/providers/writer/handlers.py:WriterMDJSONHandler.parse_response 中可见 if isinstance(response_model, type) and self._consume_streaming_flag(response_model)` 这一判断分支。

Partial DSL 会在解析过程中跳过尚未"结构完整"的 JSON 片段，v1.14.3 引入的 JsonCompleteness 类（位于 instructor/dsl/json_tracker.py）正是为这一目标服务的，它使用"sibling heuristic"判断 JSON 是否已闭合（资料来源：v1.14.3 / v1.14.4 release notes）。v1.14.2 还修复了"自引用模型（TreeNode）在 Partial 中出现无限递归"的问题（#1997）。

钩子（Hooks）

钩子是 v1.15 系列重点新增的扩展点，最显著的两条是 completion:error 与 completion:last_attempt（资料来源：v1.15.1 release notes）。它们分别对应：

需要注意的是，社区指出当前实现只把 Exception 透传给钩子，缺少 attempt_number 等元数据，开发者难以判断"这是中间重试还是最终失败"（参考 issue #2222）。在调用方代码中，使用 from_writer（资料来源：instructor/v2/providers/writer/client.py:from_writer）或等价的 from_anthropic / from_openai` 创建客户端后，可通过统一钩子注册函数订阅上述事件。

公共工具与跨 Provider 一致性

为了让验证、重试、流式、钩子这四件事在所有 Provider 上保持一致，Instructor 把 JSON 提取、消息模板、键值处理等下沉到公共工具。资料来源：instructor/utils/__init__.py:1-60 暴露了 extract_json_from_codeblock、extract_json_from_stream、extract_json_from_stream_async 等函数；Provider 只需按各自消息格式实现 process_message（例如 Anthropic 处理 content 列表中的 text 块，资料来源：instructor/v2/providers/anthropic/templating.py；Cohere 处理 message 字符串键，资料来源：instructor/v2/providers/cohere/templating.py；GenAI 直接转换 Content.parts，资料来源：instructor/v2/providers/genai/templating.py）。

常见失败模式

• 消息缺失导致崩溃：Gemini 在 JSON 模式下会无条件访问 new_kwargs["messages"][0]["role"]，遇到空消息列表时会触发 KeyError 或 IndexError（参考 issue #2335）。
• Cohere 模板 KeyError：当 kwargs 中含 "message" 键却无 "chat_history" 时，handle_templating 抛 KeyError（参考 issue #2331）。
• Image.autodetect 返回 None：仅当 source 是 str 或 Path 时返回有效 Image，否则隐式 return None，调用方随后访问 .source 会得到误导性 AttributeError（参考 issue #2344）。
• 安全相关阻断：v1.15.1 起，Bedrock 不再支持远端 HTTP(S) 图片与 PDF 抓取，仅接受 data: 与 s3://，以防止 SSRF。

See Also

• Providers & Modes — 各厂商 Handler 与 Mode 注册表
• Validation Cookbook — Pydantic + llm_validator 实战
• Streaming & Partial DSL — Partial 与 JsonCompleteness 行为细节
• Hooks & Observability — completion:error / completion:last_attempt 事件订阅

概述

Instructor 通过 v2 分层注册表系统（hierarchical registry）将「Provider 适配」与「Mode 分发」解耦。Provider 表示后端服务厂商（OpenAI、Anthropic、Cohere、Gemini/GenAI、Writer、Bedrock 等），Mode 表示生成结构化输出的具体手段（TOOLS、JSON_SCHEMA、MD_JSON、Responses、GENAI 等）。每一家 Provider 在 instructor/v2/providers/<provider>/ 下都有自己的 client.py（工厂函数）、handlers.py（按 Mode 注册处理器）、schema.py（Pydantic → 厂商 Schema 转换）和 templating.py（消息模板处理）。用户调用顶层 instructor.from_* 工厂方法即可获得一个绑定到指定 Mode 的 Instructor 或 AsyncInstructor 客户端。

v2 注册表与工厂函数

v2 客户端通过装饰器 register_mode_handler(Provider, Mode) 把一个处理器类挂到注册表上，从而实现 Provider × Mode 的二维路由。下面是 Writer 厂商下 MD_JSON 模式的注册示例：

@register_mode_handler(Provider.WRITER, Mode.MD_JSON)
class WriterMDJSONHandler(WriterHandlerBase):
    mode = Mode.MD_JSON

    def prepare_request(
        self,
        response_model: type[BaseModel] | None,
        kwargs: dict[str, Any],
    ) -> tuple[type[BaseModel] | None, dict[str, Any]]:
        ...

资料来源：instructor/v2/providers/writer/handlers.py

工厂函数 from_writer 负责把原生 SDK 客户端包装成 Instructor，同时通过 patch_v2 注入 patch 行为。同步 / 异步客户端通过 @overload 进行类型分流：

@overload
def from_writer(client: Writer, mode: Mode = Mode.TOOLS, ...) -> Instructor: ...
@overload
def from_writer(client: AsyncWriter, mode: Mode = Mode.TOOLS, ...) -> AsyncInstructor: ...

资料来源：instructor/v2/providers/writer/client.py

每家 Provider 工厂函数还会显式 import 对应 Provider 的 handlers 子模块，以确保装饰器能够自动注册：

from instructor.v2.providers.writer import handlers  # noqa: F401

资料来源：instructor/v2/providers/writer/client.py:18-19

下表总结了关键流程节点：

flowchart LR
    User[用户代码] --> Factory[instructor.from_xxx]
    Factory --> Patch[patch_v2 注入]
    Factory --> Reg[(注册表: Provider x Mode)]
    Reg --> H1[TOOLS Handler]
    Reg --> H2[JSON_SCHEMA Handler]
    Reg --> H3[MD_JSON Handler]
    H1 --> S[Provider schema.py]
    H2 --> S
    H3 --> S
    H1 --> T[Provider templating.py]
    H2 --> T
    H3 --> T
    S --> SDK[原生 SDK 客户端]
    T --> SDK

Schema 与 Templating 的差异化处理

不同 Provider 对 Pydantic → API Schema 的转换存在微妙差异。OpenAI 路径用 docstring_parser 解析模型 docstring，将 @param 描述自动注入到对应字段上，并按是否含默认值重算 required 列表：

parameters["required"] = sorted(
    k for k, v in parameters["properties"].items() if "default" not in v
)

资料来源：instructor/v2/providers/openai/schema.py:31-33

Anthropic 复用 OpenAI Schema，但只取 name / description，并把 model.model_json_schema() 整体塞进 input_schema：

return {
    "name": openai_schema["name"],
    "description": openai_schema["description"],
    "input_schema": model.model_json_schema(),
}

资料来源：instructor/v2/providers/anthropic/schema.py:14-20

旧版 Gemini 路径 generate_gemini_schema 已被标记为 DeprecationWarning，并提示用户改用 google-genai，因为 google-generativeai 即将停止维护。资料来源：instructor/v2/providers/gemini/schema.py:18-22

Templating 侧则按 Provider 消息结构差异分派：OpenAI 处理 content: str（openai/templating.py）；Anthropic 处理 content: list[dict]，只替换 type=="text" 的部分（anthropic/templating.py）；Cohere 改写顶层 message 字段（cohere/templating.py）；GenAI 直接构造 google.genai.types.Content 并遍历 parts（genai/templating.py）。

兼容层与社区已知问题

v1 与 v2 路径并存。instructor/providers/_compat.py 提供 make_getattr 与 resolve_provider_attr，让旧的 from instructor.providers.anthropic import X 仍然可以解析到 v2 子模块，按 client → handlers → schema → multimodal → parallel → templating → usage 顺序回退查找：

__getattr__ = make_getattr(
    "anthropic",
    ("client", "handlers", "schema", "multimodal", "parallel", "templating", "usage"),
)

资料来源：instructor/providers/anthropic/__init__.py、instructor/providers/_compat.py

最简形态甚至只是单行转发，例如 instructor/providers/writer/client.py：

from instructor.v2.providers.writer.client import from_writer
__all__ = ["from_writer"]

资料来源：instructor/providers/writer/client.py

社区中与 Provider / Mode 直接相关的若干已知坑值得留意：

• Cohere + Jinja2：handle_templating() 在缺少 chat_history 时抛出 KeyError（issue #2331）。
• Gemini utils：handle_gemini_json 在 messages 缺失或为空时分别抛 KeyError / IndexError（issue #2335）。
• Bedrock 安全（v1.15.1）：_openai_image_part_to_bedrock 禁止远端 HTTP(S) 拉取，PDF.to_bedrock 仅接受 base64 / s3://，以防 SSRF 与本地文件泄露。
• GENAI 与 Responses Mode：v1.15.0 起正式纳入 Mode 枚举；CLI 新增 --full-id 用于显示完整 batch ID。
• OpenAI 强结构化输出：社区长期关注的 feature request #910 已通过 JSON_SCHEMA / Responses 模式部分覆盖。

See Also

• Validation Hooks & Retry Metadata
• Multimodal & Image Autodetect
• Streaming with Partial & JsonCompleteness

Multimodal、Templating、Batch 与常见失败模式

本页面面向使用 Instructor 库进行结构化输出的开发者，重点说明四个相互关联的子系统：多模态输入适配、Provider 级别模板渲染、批处理（Batch）工作流，以及社区中积累的常见失败模式与对应规避策略。

多模态输入适配（Multimodal）

Instructor 的多模态支持在 v2 体系下以 Image、Audio、PDF 等类为核心，作为消息内容的可枚举部分注入对话。多模态工具集中在 instructor/v2/providers/gemini/utils.py 中导出并被各 Provider handler 复用。from google.genai import types 的按需导入确保了在未安装 Google SDK 时不会硬性失败。资料来源：instructor/v2/providers/gemini/utils.py:1-30

不同 Provider 对多模态字段的承载形式不同：OpenAI 风格使用 content 字符串或数组；Anthropic 风格要求 content 为包含 type="text" 的多部分数组；Gemini 使用 parts 字段；GenAI 则使用 google.genai.types.Content 对象。这一点决定了为什么每个 Provider 都需要独立的 process_message 模板处理函数。资料来源：instructor/v2/providers/openai/templating.py:1-20, instructor/v2/providers/anthropic/templating.py:1-22, instructor/v2/providers/gemini/templating.py:1-18

Provider 模板渲染（Templating）

模板函数统一签名

每个 Provider 的 process_message(message, context, apply_template) 函数遵循相同的三参数契约：接收原始消息、模板上下文以及可调用的模板渲染器（如 Jinja2）。v2 注册表在调用请求前会根据 Provider 枚举分派到对应实现。资料来源：instructor/v2/providers/openai/templating.py:8-15, instructor/v2/providers/anthropic/templating.py:9-22, instructor/v2/providers/genai/templating.py:9-23

各 Provider 差异化处理

• OpenAI：当 content 为 str 时直接整段渲染。资料来源：instructor/v2/providers/openai/templating.py:11-15
• Anthropic：遍历 content 列表，仅渲染 type=="text" 的 text 字段，保留图片块不被破坏。资料来源：instructor/v2/providers/anthropic/templating.py:11-22
• Cohere：使用 "message" 键而非 "content"，这是 v1/v2 双轨设计中的重要差异点。资料来源：instructor/v2/providers/cohere/templating.py:11-15
• Gemini：渲染 parts 列表中的字符串片段。资料来源：instructor/v2/providers/gemini/templating.py:11-17
• GenAI：返回 types.Content 包装对象，对 Part.from_text 进行单独模板替换。资料来源：instructor/v2/providers/genai/templating.py:9-23

模板渲染与 Schema 生成的协作

generate_anthropic_schema 通过 lru_cache(maxsize=256) 包装 generate_openai_schema，避免对同一 Pydantic 模型重复构建工具描述。资料来源：instructor/v2/providers/anthropic/schema.py:10-23, instructor/v2/providers/openai/schema.py:9-32

批处理与 CLI 工作流

虽然核心批处理逻辑不在 v2 模板文件中，但 CLI 工具提供了对 Batch ID 的查看能力。--full-id 标志在 v1.15.0 中被加入，用于显示完整的 Batch ID。scripts 目录统一维护文档与代码片段的标准化脚本，例如 fix_api_calls.py 将遗留调用模式 client.chat.completions.create 批量替换为 client.create。资料来源：scripts/README.md:1-50

flowchart LR
    A[用户消息 + Jinja2 Context] --> B[Provider.handle_templating]
    B --> C{Provider 类型}
    C -->|OpenAI| D[渲染 content 字符串]
    C -->|Anthropic| E[遍历 content 列表, 仅渲染 text]
    C -->|Cohere| F[渲染 message 键]
    C -->|Gemini| G[渲染 parts 字符串]
    C -->|GenAI| H[包装为 types.Content]
    D & E & F & G & H --> I[Provider Handler]
    I --> J[response_model 校验与重试]

常见失败模式与规避

下表汇总社区高频报告的 Bug 模式与对应源码位置，便于快速定位问题根源。

总结与选型建议

对于模板渲染，建议优先以 v2 Provider 注册体系为准，避开 v1 中已被 Message 抽象封装的旧路径。多模态输入必须先经过 Image/PDF/Audio 类构造，以避免自动检测分支的 None 隐式返回。Batch 场景下使用 client.create_batch 系列 API 并配合 CLI 的 --full-id 检索完整 ID。最后，对于 v1.15.1 之前已上线的服务，请尽快升级以获得 Bedrock 端 SSRF 防护。

See Also

• README.md — 项目概览与多语言实现矩阵
• scripts/README.md — 文档维护与 API 标准化脚本
• instructor/v2/core/ — v2 核心抽象（Client、Mode、Provider、Templating）
• GitHub Issue #2344 — Image.autodetect 失败模式
• GitHub Issue #2331 — Cohere 模板 KeyError
• GitHub Issue #2335 — Gemini 空消息列表崩溃
• v1.15.1 Release Notes — Bedrock 安全加固变更

Pitfall Log / 踩坑日志

项目：567-labs/instructor

摘要：发现 12 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Expose attempt metadata on completion:error and completion:last_attempt hooks。

1. 安装坑 · 来源证据：Expose attempt metadata on completion:error and completion:last_attempt hooks

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Expose attempt metadata on completion:error and completion:last_attempt hooks
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/567-labs/instructor/issues/2222 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：jsonref package missing in required dependencies

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：jsonref package missing in required dependencies
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/567-labs/instructor/issues/2288 | 来源类型 github_issue 暴露的待验证使用条件。

3. 配置坑 · 来源证据：fix: handle_gemini_json crashes with empty or absent messages list

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：fix: handle_gemini_json crashes with empty or absent messages list
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/567-labs/instructor/issues/2335 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass.

5. 运行坑 · 来源证据：BUG: KeyError when using Cohere provider with Jinja2 template and no chat_history

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：BUG: KeyError when using Cohere provider with Jinja2 template and no chat_history
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/567-labs/instructor/issues/2331 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 运行坑 · 来源证据：Image.autodetect returns None for non-str/non-Path sources, causing a confusing AttributeError

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Image.autodetect returns None for non-str/non-Path sources, causing a confusing AttributeError
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/567-labs/instructor/issues/2344 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：[Feature Request] Memory Poisoning Protection for Instructor via OWASP Agent Memory Guard

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Memory Poisoning Protection for Instructor via OWASP Agent Memory Guard
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/567-labs/instructor/issues/2334 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | release_recency=unknown