{
"canonical_name": "567-labs/instructor",
"compilation_id": "pack_2dbeaf02ad1e4a21a974869173f3d952",
"created_at": "2026-05-13T07:09:39.726229+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install instructor` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install instructor",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_bc8f33535fcf4adbb769870bbfc43e42"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_528487c0c621cd07d9ed7826966a6d71",
"canonical_name": "567-labs/instructor",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/567-labs/instructor",
"slug": "instructor",
"source_packet_id": "phit_f92be39d2ca741d4aead75b3be47c61d",
"source_validation_id": "dval_8e661cfaee704158990079c366c444a8"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 chatgpt的用户",
"github_forks": 1037,
"github_stars": 12953,
"one_liner_en": "structured outputs for llms",
"one_liner_zh": "structured outputs for llms",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "instructor",
"title_zh": "instructor 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-extraction",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"type": "selection_signal"
}
]
},
"packet_id": "phit_f92be39d2ca741d4aead75b3be47c61d",
"page_model": {
"artifacts": {
"artifact_slug": "instructor",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install instructor",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/567-labs/instructor#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"节点式流程编排",
"开源工具"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "structured outputs for llms"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess.",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Documentation (at least Google-related) is an outdated mess.",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.13.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.12.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.14.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.14.3",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.14.4",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.15.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.14.2",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Catching IncompleteOutputException : not possible as presently documented / tested.",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_dc0f4256859740f8a4cacd1731514783 | https://github.com/567-labs/instructor/issues/2273 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Catching IncompleteOutputException : not possible as presently documented / tested.",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b982358c78a346bfaa26b428e00968bb | https://github.com/567-labs/instructor/issues/2291 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bump lightllm upper bound for recent vulnerabililties",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_2ae9c53479204c778e56a8b4b3feb404 | https://github.com/567-labs/instructor/issues/2290 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：bump lightllm upper bound for recent vulnerabililties",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：logger.debug in response.py leaks api_key verbatim via new_kwargs",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_2076a35fb27a4c119141e9f57acdf9bc | https://github.com/567-labs/instructor/issues/2265 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：logger.debug in response.py leaks api_key verbatim via new_kwargs",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Documentation (at least Google-related) is an outdated mess.。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 250,
"forks": 1037,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 12953
},
"source_url": "https://github.com/567-labs/instructor",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "structured outputs for llms",
"title": "instructor 能力包",
"trial_prompt": "# instructor - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 instructor 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: structured outputs for llms 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-providers：提供商集成。围绕“提供商集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-providers\n输入：用户提供的“提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-providers：Step 5 必须围绕“提供商集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/567-labs/instructor\n- https://github.com/567-labs/instructor#readme\n- README.md\n- instructor/__init__.py\n- mkdocs.yml\n- pyproject.toml\n- requirements.txt\n- docs/installation.md\n- examples/simple-extraction/user.py\n- docs/getting-started.md\n- docs/learning/getting_started/first_extraction.md\n- instructor/core/client.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 instructor 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Documentation (at least Google-related) is an outdated mess.（https://github.com/567-labs/instructor/issues/2289）；github/github_issue: Tool: NEXUS structured financial data（https://github.com/567-labs/instructor/issues/2302）；github/github_issue: Catching IncompleteOutputException : not possible as presently documente（https://github.com/567-labs/instructor/issues/2273）；github/github_issue: bump lightllm upper bound for recent vulnerabililties（https://github.com/567-labs/instructor/issues/2290）；github/github_issue: reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUse（https://github.com/567-labs/instructor/issues/2277）；github/github_issue: logger.debug in response.py leaks api_key verbatim via new_kwargs（https://github.com/567-labs/instructor/issues/2265）；github/github_issue: RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)（https://github.com/567-labs/instructor/issues/2291）；github/github_release: v1.15.1（https://github.com/567-labs/instructor/releases/tag/v1.15.1）；github/github_release: v1.15.0（https://github.com/567-labs/instructor/releases/tag/v1.15.0）；github/github_release: v1.14.5（https://github.com/567-labs/instructor/releases/tag/v1.14.5）；github/github_release: v1.14.4（https://github.com/567-labs/instructor/releases/tag/v1.14.4）；github/github_release: v1.14.3（https://github.com/567-labs/instructor/releases/tag/v1.14.3）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Documentation (at least Google-related) is an outdated mess.",
"url": "https://github.com/567-labs/instructor/issues/2289"
},
{
"kind": "github_issue",
"source": "github",
"title": "Tool: NEXUS structured financial data",
"url": "https://github.com/567-labs/instructor/issues/2302"
},
{
"kind": "github_issue",
"source": "github",
"title": "Catching IncompleteOutputException : not possible as presently documente",
"url": "https://github.com/567-labs/instructor/issues/2273"
},
{
"kind": "github_issue",
"source": "github",
"title": "bump lightllm upper bound for recent vulnerabililties",
"url": "https://github.com/567-labs/instructor/issues/2290"
},
{
"kind": "github_issue",
"source": "github",
"title": "reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUse",
"url": "https://github.com/567-labs/instructor/issues/2277"
},
{
"kind": "github_issue",
"source": "github",
"title": "logger.debug in response.py leaks api_key verbatim via new_kwargs",
"url": "https://github.com/567-labs/instructor/issues/2265"
},
{
"kind": "github_issue",
"source": "github",
"title": "RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)",
"url": "https://github.com/567-labs/instructor/issues/2291"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.15.1",
"url": "https://github.com/567-labs/instructor/releases/tag/v1.15.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.15.0",
"url": "https://github.com/567-labs/instructor/releases/tag/v1.15.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.14.5",
"url": "https://github.com/567-labs/instructor/releases/tag/v1.14.5"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.14.4",
"url": "https://github.com/567-labs/instructor/releases/tag/v1.14.4"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.14.3",
"url": "https://github.com/567-labs/instructor/releases/tag/v1.14.3"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "structured outputs for llms",
"effort": "安装已验证",
"forks": 1037,
"icon": "code",
"name": "instructor 能力包",
"risk": "可发布",
"slug": "instructor",
"stars": 12953,
"tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"节点式流程编排",
"开源工具"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/567-labs/instructor 项目说明书\n\n生成时间：2026-05-13 06:51:33 UTC\n\n## 目录\n\n- [项目概览](#page-overview)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [提供商集成](#page-providers)\n- [响应模型](#page-response-models)\n- [验证机制](#page-validation)\n- [流式输出](#page-streaming)\n- [批处理](#page-batch-processing)\n- [钩子系统](#page-hooks)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n- [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)\n- [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md)\n- [examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md)\n- [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md)\n- [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)\n- [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)\n \n\n# 项目概览\n\n## 什么是 Instructor\n\nInstructor 是一个用于从大语言模型（LLM）获取**结构化输出**的 Python 库。它通过将 Pydantic 模型与 LLM API 结合，使模型输出自动经过验证和类型转换，开发者无需编写繁琐的 JSON 解析和手动验证代码。\n\n核心价值在于简化 LLM 应用开发中的数据提取和验证流程，让开发者专注于业务逻辑而非底层实现。\n\n资料来源：[README.md:1-30]()\n\n## 核心功能特性\n\n### 多provider统一API\n\nInstructor 支持多种主流 LLM 服务商，通过统一的接口访问不同 provider：\n\n| Provider | 模型示例 | 特性 |\n|----------|----------|------|\n| OpenAI | gpt-4o, gpt-4-turbo, gpt-3.5-turbo | 参考实现 |\n| Anthropic | claude-3-5-sonnet, claude-3-opus | Beta API支持 |\n| Google | gemini-pro, gemini-2.0-flash | 模拟模式可用 |\n| Ollama | llama3.2 (本地部署) | 支持本地运行 |\n| Groq | llama-3.1-8b-instant | 高速推理 |\n\n所有 provider 使用相同的 API 调用方式，切换时只需修改 provider 名称和模型名称。\n\n资料来源：[README.md:50-80]()\n\n### 响应模型与自动验证\n\n使用 `response_model` 参数指定 Pydantic 模型作为输出格式：\n\n```python\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n name: str\n age: int\n\nclient = instructor.from_provider(\"openai/gpt-4o\")\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\nInstructor 自动处理 JSON 解析、类型转换和验证失败时的重试逻辑。\n\n资料来源：[README.md:35-45]()\n\n### 自动重试机制\n\n当验证失败时，Instructor 会自动将错误信息反馈给 LLM 并重试请求：\n\n```python\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n\n# 自动重试直到验证通过或达到最大重试次数\nuser = client.chat.completions.create(\n response_model=User,\n max_retries=2,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n资料来源：[README.md:90-110]()\n\n## 系统架构\n\n### 组件结构\n\nInstructor 的代码组织结构如下：\n\n```\ninstructor/\n├── providers/ # LLM provider 适配器\n│ ├── anthropic/ # Anthropic 实现\n│ ├── openai/ # OpenAI 实现\n│ ├── gemini/ # Google Gemini 实现\n│ ├── groq/ # Groq 实现\n│ ├── vertexai/ # Vertex AI 实现\n│ └── ... # 其他 provider\n└── __init__.py # 核心导出\n```\n\n每个 provider 目录下包含：\n- `__init__.py` - 模块初始化\n- `client.py` - provider 特定的客户端工厂函数（可选）\n- `utils.py` - provider 特定的响应处理工具（可选）\n\n资料来源：[instructor/providers/README.md:1-25]()\n\n### Provider 实现模式\n\n| 类型 | Provider 列表 | 说明 |\n|------|---------------|------|\n| 完整实现 | anthropic, bedrock, gemini, mistral 等 | 包含 client.py 和 utils.py |\n| 简化实现 | genai, groq, vertexai | 仅 client.py，使用核心处理逻辑 |\n| 特殊实现 | openai | 仅 utils.py，from_openai() 在核心模块定义 |\n\nOpenAI 作为参考实现，其工厂函数定义在 `core/client.py` 中，其他 provider 基于此模式扩展。\n\n资料来源：[instructor/providers/README.md:25-40]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[创建 Client] --> B[调用 chat.completions.create]\n B --> C[发送请求到 LLM]\n C --> D[接收响应]\n D --> E[JSON 解析]\n E --> F[Pydantic 模型验证]\n F --> G{验证通过?}\n G -->|是| H[返回结构化对象]\n G -->|否| I[提取错误信息]\n I --> J[重试请求]\n J --> C\n J --> K[达到最大重试]\n K --> L[抛出异常]\n```\n\n## 高级功能\n\n### 验证器（Validators）\n\nInstructor 支持多种验证方式，确保 LLM 输出符合预期：\n\n#### Pydantic 字段验证器\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n```\n\n#### LLM 验证器\n\n使用 `llm_validator` 对输出内容进行语义级验证：\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BeforeValidator\n\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"don't say objectionable things\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md:1-80]()\n\n### 批处理 API\n\nInstructor 提供统一的批处理接口，支持多个 provider：\n\n```bash\n# 使用 CLI 创建批处理任务\ninstructor batch create \\\n --messages-file messages.jsonl \\\n --model \"openai/gpt-4o-mini\" \\\n --response-model \"User\"\n```\n\n支持的功能：\n- 批量消息创建\n- 批处理状态查询\n- 结果文件导出\n- Provider 自动检测\n\n支持的批处理模型：\n- OpenAI: gpt-4o-mini, gpt-4o, gpt-4-turbo\n- Anthropic: claude-3-5-sonnet, claude-3-opus, claude-3-haiku\n- Google: gemini-2.0-flash-001, gemini-pro\n\n资料来源：[examples/batch_api/README.md:1-60]()\n\n### 钩子系统（Hooks）\n\nInstructor 的钩子系统允许在请求生命周期中插入自定义逻辑：\n\n```mermaid\ngraph LR\n A[请求开始] --> B[on_request 钩子]\n B --> C[LLM 调用]\n C --> D[on_response 钩子]\n D --> E{验证成功?}\n E -->|是| F[on_success 钩子]\n E -->|否| G[on_retry 钩子]\n G --> C\n F --> H[返回结果]\n E -->|最终失败| I[on_failure 钩子]\n I --> J[抛出异常]\n```\n\n支持的钩子事件：\n| 钩子类型 | 触发时机 | 典型用途 |\n|----------|----------|----------|\n| on_request | 请求发送前 | 添加日志、修改参数 |\n| on_response | 收到响应后 | 记录 token 使用 |\n| on_success | 验证通过后 | 统计指标 |\n| on_retry | 重试前 | 记录重试原因 |\n| on_failure | 最终失败后 | 错误告警 |\n\n资料来源：[examples/hooks/README.md:1-40]()\n\n### 模型蒸馏（Distillation）\n\nInstructor 支持使用日志功能生成微调数据集：\n\n```python\n# 运行脚本生成训练数据\npython three_digit_mul.py\n\n# 创建微调任务\ninstructor jobs create-from-file math_finetunes.jsonl\n\n# 可选：使用验证集\ninstructor jobs create-from-file math_finetunes.jsonl \\\n --n-epochs 4 \\\n --validation-file math_finetunes_val.jsonl\n```\n\n此功能允许开发者用 Instructor 生成高质量的训练数据，用于微调更小、更快的模型。\n\n资料来源：[examples/distilations/readme.md:1-50]()\n\n### 引用提取（Citations）\n\nInstructor 支持从上下文中提取引用并标注来源：\n\n```bash\ncurl -X POST 'http://localhost:8000/extract' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer ' \\\n -d '{\n \"context\": \"Jason Liu 出生于中国...\",\n \"query\": \"作者在哪里出生?\"\n }'\n```\n\n返回格式包含：\n- `body`: 提取的事实\n- `spans`: 原文中的位置\n- `citation`: 引用的文本片段\n\n资料来源：[examples/citation_with_extraction/README.md:1-50]()\n\n## 安装与配置\n\n### 快速安装\n\n```bash\npip install instructor\n```\n\n或使用其他包管理器：\n\n```bash\nuv add instructor\npoetry add instructor\n```\n\n### 初始化客户端\n\n```python\n# 基本用法（需设置环境变量）\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# 直接传入 API Key\nclient = instructor.from_provider(\n \"anthropic/claude-3-5-sonnet\",\n api_key=\"sk-ant-...\"\n)\n\n# 使用任意支持格式\nclient = instructor.from_provider(\"groq/llama-3.1-8b-instant\")\n```\n\n资料来源：[README.md:40-70]()\n\n## 与传统方式对比\n\n```mermaid\ngraph LR\n subgraph \"传统方式\"\n A1[手动定义 schema] --> A2[调用 API]\n A2 --> A3[解析 JSON]\n A3 --> A4[手动验证数据]\n A4 --> A5[处理边界情况]\n end\n\n subgraph \"使用 Instructor\"\n B1[定义 Pydantic 模型] --> B2[调用 create 方法]\n B2 --> B3[自动验证返回]\n B3 --> B4[获得类型安全对象]\n end\n\n A5 -.->|繁琐| B4\n```\n\n| 方面 | 传统方式 | Instructor |\n|------|----------|------------|\n| 代码量 | 多 | 少 |\n| 错误处理 | 手动 | 自动重试 |\n| 类型安全 | 无 | Pydantic 保证 |\n| Provider 切换 | 需重写 | 改参数即可 |\n| 验证逻辑 | 手动编写 | 声明式定义 |\n\n## 适用场景\n\nInstructor 适用于以下场景：\n\n1. **数据提取**：从非结构化文本中提取结构化数据\n2. **信息检索**：基于上下文的问答系统\n3. **内容审核**：验证 LLM 输出符合规范\n4. **批量处理**：大规模自动化数据处理任务\n5. **模型微调**：生成高质量训练数据集\n6. **多Provider切换**：统一管理不同 LLM 服务商\n\n## 技术栈\n\n- **Python**: 3.9+\n- **Pydantic**: 数据验证和类型转换\n- **OpenAI SDK**: API 通信\n- **Tenacity**: 重试逻辑\n\nInstructor 设计为轻量级依赖，核心功能仅需 Pydantic 即可运行。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目概览](#page-overview), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n- [pyproject.toml](https://github.com/567-labs/instructor/blob/main/pyproject.toml)\n- [scripts/README.md](https://github.com/567-labs/instructor/blob/main/scripts/README.md)\n- [examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md)\n- [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md)\n \n\n# 安装指南\n\n本页面详细介绍 Instructor 库的安装方法、环境配置以及不同平台的依赖要求。Instructor 是一个支持多种 LLM 提供商的 Python 库，专注于结构化输出和响应验证。\n\n## 安装方式\n\nInstructor 提供了多种安装方式，开发者可根据项目需求选择最适合的方法。\n\n### 使用 pip 安装\n\n最简捷的安装方式是通过 Python 包管理器 pip 安装稳定版本：\n\n```bash\npip install instructor\n```\n\n### 使用 uv 安装\n\n对于使用 uv 作为包管理器的项目：\n\n```bash\nuv add instructor\n```\n\n### 使用 Poetry 安装\n\n使用 Poetry 进行依赖管理的项目：\n\n```bash\npoetry add instructor\n```\n\n资料来源：[README.md:1-30](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 环境要求\n\nInstructor 对运行环境有以下基本要求：\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Python | 3.9+ | 推荐使用 Python 3.9 或更高版本 |\n| Pydantic | 2.x | 用于数据验证和模型定义 |\n| LLM 提供商 SDK | 最新版本 | 根据使用的提供商安装相应 SDK |\n\n### 核心依赖\n\nInstructor 的核心功能依赖于以下 Python 包：\n\n```toml\n# pyproject.toml 中的核心依赖\ndependencies = [\n \"pydantic>=2.0\",\n \"anyio>=4.0\",\n]\n```\n\n资料来源：[pyproject.toml](https://github.com/567-labs/instructor/blob/main/pyproject.toml)\n\n## LLM 提供商配置\n\nInstructor 支持多个主流 LLM 提供商，每个提供商需要单独配置 API 密钥。\n\n### 支持的提供商\n\n| 提供商 | 模型示例 | 必需环境变量 |\n|--------|----------|--------------|\n| OpenAI | gpt-4o, gpt-4o-mini | `OPENAI_API_KEY` |\n| Anthropic | claude-3-5-sonnet | `ANTHROPIC_API_KEY` |\n| Google | gemini-pro, gemini-2.0-flash | `GOOGLE_API_KEY` |\n| Ollama | llama3.2 (本地部署) | 无需 API 密钥 |\n| Groq | llama-3.1-8b-instant | `GROQ_API_KEY` |\n\n### 初始化客户端\n\n使用 `from_provider()` 方法创建客户端：\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n```\n\n### 直接传递 API 密钥\n\n在某些场景下，可能需要直接传递 API 密钥而不依赖环境变量：\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\", api_key=\"sk-ant-...\")\n\n# Groq\nclient = instructor.from_provider(\"groq/llama-3.1-8b-instant\", api_key=\"gsk_...\")\n```\n\n资料来源：[README.md:50-80](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 依赖安装流程\n\n### 基本安装步骤\n\n1. **创建虚拟环境（推荐）**\n\n```bash\npython -m venv venv\nsource venv/bin/activate # Linux/macOS\nvenv\\Scripts\\activate # Windows\n```\n\n2. **安装 Instructor**\n\n```bash\npip install instructor\n```\n\n3. **安装提供商 SDK（根据需要）**\n\n```bash\n# OpenAI\npip install openai\n\n# Anthropic\npip install anthropic\n\n# Google Gemini\npip install google-generativeai\n```\n\n### 示例项目依赖安装\n\n某些示例项目可能需要额外依赖：\n\n```bash\n# 示例：citation_with_extraction 项目\npip install -r requirements.txt\n```\n\n资料来源：[examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md)\n\n## 高级功能依赖\n\n### 批处理功能\n\n使用批处理 API 时需要安装以下依赖：\n\n| 依赖包 | 用途 |\n|--------|------|\n| openai | OpenAI API 客户端 |\n| typer | CLI 命令行界面 |\n| rich | 终端美化输出 |\n| tenacity | 重试机制 |\n| pyyaml | YAML 配置文件处理 |\n\n安装命令：\n\n```bash\nuv add openai typer rich tenacity pyyaml\n```\n\n资料来源：[scripts/README.md](https://github.com/567-labs/instructor/blob/main/scripts/README.md)\n\n### 微调功能\n\n进行模型微调时需要：\n\n1. 配置日志记录功能\n2. 准备训练数据格式（JSONL）\n3. 使用 Instructor CLI 提交微调任务\n\n```bash\ninstructor jobs create-from-file math_finetunes.jsonl\n```\n\n资料来源：[examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)\n\n## 验证安装\n\n安装完成后，可通过以下方式验证 Instructor 是否正确安装：\n\n```python\nimport instructor\n\n# 验证版本\nprint(instructor.__version__)\n\n# 测试基本功能\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\nprint(\"Instructor 安装成功！\")\n```\n\n## 安装问题排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| ImportError | 未正确安装或虚拟环境未激活 | 重新安装并检查 Python 环境 |\n| API 密钥错误 | 环境变量未设置或值错误 | 设置正确的 API 密钥 |\n| 版本不兼容 | Python 版本过低 | 升级到 Python 3.9+ |\n\n### 验证 API 密钥\n\n确保 API 密钥已正确配置：\n\n```bash\n# 检查环境变量（Linux/macOS）\necho $OPENAI_API_KEY\n\n# 检查环境变量（Windows）\necho %OPENAI_API_KEY%\n```\n\n## 项目结构与模块\n\nInstructor 采用模块化设计，主要结构如下：\n\n```\ninstructor/\n├── providers/ # LLM 提供商实现\n│ ├── openai/ # OpenAI 提供商\n│ ├── anthropic/ # Anthropic 提供商\n│ ├── gemini/ # Google Gemini 提供商\n│ └── ...\n├── core/ # 核心功能模块\n└── ...\n```\n\n每个提供商都有独立的子模块，包含初始化工厂函数和响应处理工具：\n\n```\nproviders/\n├── provider_name/\n│ ├── __init__.py\n│ ├── client.py # 提供商特定客户端\n│ └── utils.py # 响应处理工具\n```\n\n资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)\n\n## 快速开始工作流\n\n以下流程图展示了从安装到首次使用的完整过程：\n\n```mermaid\ngraph TD\n A[开始] --> B[安装 Instructor]\n B --> C{选择提供商}\n C -->|OpenAI| D[设置 OPENAI_API_KEY]\n C -->|Anthropic| E[设置 ANTHROPIC_API_KEY]\n C -->|Google| F[设置 GOOGLE_API_KEY]\n C -->|Ollama| G[配置本地 Ollama]\n D --> H[创建客户端]\n E --> H\n F --> H\n G --> H\n H --> I[定义响应模型]\n I --> J[调用 API]\n J --> K[获取结构化输出]\n```\n\n## 许可证\n\nInstructor 采用 MIT 许可证开源发布，可自由使用、修改和分发。\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/LICENSE)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概览](#page-overview), [响应模型](#page-response-models), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/simple-extraction/user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/user.py)\n- [docs/getting-started.md](https://github.com/567-labs/instructor/blob/main/docs/getting-started.md)\n- [docs/learning/getting_started/first_extraction.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/first_extraction.md)\n- [README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n- [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)\n \n\n# 快速开始\n\n本页面为 Instructor 项目的入门指南，旨在帮助开发者快速了解并上手使用 Instructor 进行结构化数据提取。Instructor 是一个简化大语言模型（LLM）响应的 Python 库，它与 Pydantic 深度集成，让开发者能够轻松地从 LLM 响应中提取类型安全的结构化数据。\n\n## 什么是 Instructor\n\nInstructor 是 567 Labs 开发的一个开源库，它通过与 Pydantic 的深度集成，将 LLM 的非结构化输出转换为结构化的 Python 对象。与传统的工具调用方式相比，Instructor 提供了更简洁的 API 和自动验证机制。\n\n传统的 LLM 调用需要手动解析 tool_call 中的 arguments，手动进行 JSON 解析和验证，而使用 Instructor 只需要定义 Pydantic 模型并调用 `client.create()` 即可获得完整的类型安全验证结果。\n\n## 安装 Instructor\n\nInstructor 支持多种安装方式，开发者可以根据项目需求选择合适的方式。\n\n### 使用 pip 安装\n\n```bash\npip install instructor\n```\n\n### 使用包管理器安装\n\nInstructor 也支持其他主流 Python 包管理器：\n\n```bash\n# 使用 uv\nuv add instructor\n\n# 使用 poetry\npoetry add instructor\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 基本概念\n\n### 核心组件\n\nInstructor 的核心架构包含以下几个关键组件：\n\n| 组件 | 说明 |\n|------|------|\n| `Instructor` | 主客户端类，负责与 LLM 提供商交互 |\n| `response_model` | Pydantic 模型，用于定义期望的输出结构 |\n| `from_provider()` | 工厂函数，用于创建 Instructor 客户端实例 |\n\n### 支持的 LLM 提供商\n\nInstructor 与多个主流 LLM 提供商兼容，包括 OpenAI、Anthropic、Google、Ollama 等。\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 创建客户端\n\n在使用 Instructor 之前，需要先创建客户端实例。Instructor 提供了 `from_provider()` 工厂函数来简化这一过程。\n\n### 基本用法\n\n```python\nimport instructor\nfrom pydantic import BaseModel\n\n# 从 OpenAI 创建客户端\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\n```\n\n### 支持的提供商示例\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n\n# 直接传入 API Key\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 第一个提取示例\n\n本节通过一个简单的用户信息提取示例，帮助开发者快速上手 Instructor。\n\n### 定义数据模型\n\n首先，使用 Pydantic 定义要提取的数据结构：\n\n```python\nfrom pydantic import BaseModel\n\n\nclass User(BaseModel):\n name: str\n age: int\n email: str\n address: str = None # 可选字段\n```\n\n资料来源：[examples/simple-extraction/user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/user.py)\n\n### 执行提取\n\n定义好模型后，即可使用 Instructor 进行结构化数据提取：\n\n```python\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\n\n# 定义提取模型\nclass User(BaseModel):\n name: str\n age: int\n email: str\n address: str = None\n\n\n# 提取数据\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n response_model=User,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"张三, 30岁, 邮箱是 zhangsan@example.com\"\n }\n ],\n)\n\nprint(user)\n# User(name='张三', age=30, email='zhangsan@example.com', address=None)\n```\n\n资料来源：[docs/getting-started.md](https://github.com/567-labs/instructor/blob/main/docs/getting-started.md)\n\n## 工作流程\n\nInstructor 的数据提取流程如下：\n\n```mermaid\ngraph TD\n A[定义 Pydantic 模型] --> B[创建 Instructor 客户端]\n B --> C[调用 client.chat.completions.create]\n C --> D[发送请求到 LLM]\n D --> E[接收 LLM 响应]\n E --> F[Pydantic 模型验证]\n F --> G{验证是否通过}\n G -->|通过| H[返回结构化对象]\n G -->|失败| I[自动重试并返回错误]\n I --> C\n```\n\n### 流程说明\n\n1. **定义模型**：开发者定义 Pydantic 模型来描述期望的输出结构\n2. **创建客户端**：使用 `from_provider()` 创建与指定 LLM 提供商的连接\n3. **调用 API**：使用 `client.chat.completions.create()` 发送请求\n4. **自动验证**：Instructor 自动对 LLM 输出进行 Pydantic 验证\n5. **自动重试**：如果验证失败，Instructor 会自动重试并将错误信息反馈给 LLM\n\n资料来源：[docs/learning/getting_started/first_extraction.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/first_extraction.md)\n\n## 自动重试机制\n\nInstructor 内置了强大的自动重试机制。当 Pydantic 验证失败时，系统会自动重试并向 LLM 传递错误信息。\n\n### 添加自定义验证\n\n可以使用 Pydantic 的 `field_validator` 装饰器添加自定义验证逻辑：\n\n```python\nfrom pydantic import BaseModel, field_validator\n\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n\n\n# 当年龄为负数时，Instructor 会自动重试\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"用户年龄为-5岁\"}],\n)\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n### LLM 验证器\n\n除了传统的字段验证器，Instructor 还支持使用 `llm_validator` 进行基于 LLM 的文本验证：\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BaseModel, BeforeValidator\nfrom instructor import llm_validator\n\n\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"不要说不恰当的话\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)\n\n## 嵌套对象处理\n\nInstructor 支持自动处理嵌套对象的提取，无需额外配置。\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Optional\n\n\nclass Address(BaseModel):\n street: str\n city: str\n country: str\n\n\nclass User(BaseModel):\n name: str\n email: str\n address: Optional[Address] = None\n\n\nuser = client.chat.completions.create(\n response_model=User,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"李四, 邮箱是 lisi@example.com, 住在北京市朝阳区建国路88号\"\n }\n ],\n)\n\nprint(user.address)\n# Address(street='建国路88号', city='北京市', country='中国')\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 完整示例代码\n\n以下是使用 Instructor 进行用户信息提取的完整示例：\n\n```python\nfrom pydantic import BaseModel\nimport instructor\n\n# 创建客户端\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\n\n\nclass User(BaseModel):\n name: str\n age: int\n email: str\n address: str = None\n\n\n# 提取结构化数据\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n response_model=User,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"张三, 30岁, 邮箱是 zhangsan@example.com\"\n }\n ],\n)\n\n# user 已经是完全验证的 User 对象\nprint(f\"姓名: {user.name}\")\nprint(f\"年龄: {user.age}\")\nprint(f\"邮箱: {user.email}\")\n```\n\n资料来源：[examples/simple-extraction/user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/user.py)\n\n## 下一步\n\n完成快速入门后，建议继续学习以下内容：\n\n| 主题 | 说明 |\n|------|------|\n| [数据验证](/concepts/validators) | 深入了解如何使用 Pydantic 验证器进行复杂验证 |\n| [钩子系统](/concepts/hooks) | 学习如何在请求/响应过程中插入自定义逻辑 |\n| [批处理](/concepts/batch) | 了解如何批量处理提取任务 |\n| [多模态提取](/examples/multimodal) | 学习如何从图像等多模态内容中提取数据 |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[提供商集成](#page-providers), [响应模型](#page-response-models), [验证机制](#page-validation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/core/client.py](https://github.com/567-labs/instructor/blob/main/instructor/core/client.py)\n- [instructor/processing/response.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/response.py)\n- [instructor/processing/function_calls.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/function_calls.py)\n- [instructor/processing/validators.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/validators.py)\n- [docs/architecture.md](https://github.com/567-labs/instructor/blob/main/docs/architecture.md)\n \n\n# 系统架构\n\n## 概述\n\nInstructor 是一个用于从大语言模型（LLM）获取结构化输出的 Python 库。它通过统一 API 连接多种 LLM 提供商，并使用 Pydantic 模型进行响应验证和类型转换。该库的核心设计理念是简化 LLM 函数调用与结构化数据提取的复杂性，使开发者能够以声明式方式定义期望的输出格式，同时自动处理验证、重试和错误恢复。\n\nInstructor 的架构采用分层设计，核心层负责客户端管理、响应处理和验证逻辑，而 providers 层则负责与不同 LLM 提供商的适配。这种分层设计确保了代码的可维护性和可扩展性，同时保持了统一的接口体验。资料来源：[README.md:1-15]()\n\n## 核心架构组件\n\n### 分层架构概览\n\nInstructor 的系统架构可分为三个主要层次：应用接口层、核心处理层和提供商适配层。\n\n```mermaid\ngraph TD\n A[应用层 - 用户代码] --> B[核心层 - Instructor Client]\n B --> C[处理层 - Response/FunctionCall]\n C --> D[验证层 - Validators]\n D --> E[提供商适配层 - Providers]\n \n E --> F[OpenAI]\n E --> G[Anthropic]\n E --> H[Google Gemini]\n E --> I[Ollama]\n E --> J[Groq]\n \n style A fill:#e1f5fe\n style B fill:#b3e5fc\n style C fill:#81d4fa\n style D fill:#4fc3f7\n style E fill:#29b6f6\n```\n\n### 核心层（Core Layer）\n\n核心层是 Instructor 的心脏，负责创建客户端实例、管理 API 调用和协调处理流程。该层的核心组件位于 `instructor/core/client.py` 文件中，提供了统一的客户端工厂函数 `from_provider()`。资料来源：[instructor/core/client.py:1-50]()\n\n核心层的主要职责包括：\n\n- **客户端工厂**：通过 `from_provider()` 函数根据提供商名称创建适配的客户端实例\n- **请求调度**：将用户的结构化请求转换为特定提供商的 API 格式\n- **响应路由**：将提供商的原始响应分发到相应的处理模块\n\n### 处理层（Processing Layer）\n\n处理层负责将 LLM 的原始输出转换为 Pydantic 模型实例。该层包含三个关键模块：\n\n#### 响应处理模块\n\n`response.py` 模块负责解析 LLM 返回的文本响应，并将其映射到预定义的 Pydantic 模型。当 LLM 直接返回文本而非函数调用时，此模块执行必要的数据提取和转换。资料来源：[instructor/processing/response.py:1-30]()\n\n#### 函数调用处理模块\n\n`function_calls.py` 模块处理 LLM 的函数调用输出。当模型选择调用特定函数时，此模块负责：\n\n- 解析函数名称和参数\n- 验证参数类型和格式\n- 提取结构化数据填充到 Pydantic 模型\n\n资料来源：[instructor/processing/function_calls.py:1-40]()\n\n#### 验证器模块\n\n`validators.py` 模块实现了一套完整的验证机制，确保 LLM 输出符合预定义的约束条件。验证器包括：\n\n| 验证器类型 | 功能描述 | 典型用途 |\n|-----------|---------|---------|\n| `field_validator` | Pydantic 原生字段验证 | 类型检查、范围验证 |\n| `llm_validator` | LLM 驱动的语义验证 | 拒绝不当内容、检查语义一致性 |\n| `BeforeValidator` | 前置验证钩子 | 数据预处理、格式规范化 |\n\n资料来源：[instructor/processing/validators.py:1-50]()\n\n### 提供商适配层（Providers Layer）\n\nProvider 层为不同的 LLM 服务提供商提供统一的适配接口。每个提供商都有独立的子目录，采用标准化的目录结构。资料来源：[instructor/providers/README.md:1-20]()\n\n## 提供商架构\n\n### 提供商组织结构\n\nInstructor 支持多种 LLM 提供商，采用统一的目录结构和适配模式：\n\n```\nproviders/\n├── provider_name/\n│ ├── __init__.py\n│ ├── client.py # 提供商特定客户端工厂\n│ └── utils.py # 提供商特定工具函数\n```\n\n### 提供商分类\n\n根据实现复杂度，Provider 可分为以下几类：\n\n| 类别 | 提供商 | 特点 |\n|------|--------|------|\n| 完整实现 | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | 包含 client.py 和 utils.py |\n| 简化实现 | genai, groq, vertexai | 仅包含 client.py，使用核心标准处理 |\n| 参考实现 | openai | 仅包含 utils.py，client 在核心层定义 |\n\n资料来源：[instructor/providers/README.md:8-15]()\n\n### 提供商工厂模式\n\nInstructor 使用统一的工厂模式创建客户端实例：\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n```\n\n所有客户端使用相同的 API 调用方式，底层的提供商差异被完全抽象：\n\n```python\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n资料来源：[README.md:45-65]()\n\n## 请求处理流程\n\n### 完整请求生命周期\n\nInstructor 的请求处理遵循标准化的生命周期流程：\n\n```mermaid\ngraph TD\n A[创建客户端 from_provider] --> B[调用 create 方法]\n B --> C[构建 API 请求]\n C --> D{提供商类型检测}\n D -->|OpenAI| E[使用标准工具调用格式]\n D -->|Anthropic| F[使用 Beta Messages API]\n D -->|其他| G[使用提供商特定格式]\n E --> H[发送请求到 LLM]\n F --> H\n G --> H\n H --> I{解析响应}\n I -->|函数调用| J[调用 function_calls 处理]\n I -->|文本响应| K[调用 response 处理]\n J --> L{运行验证器}\n K --> L\n L -->|验证失败| M[重试并提供错误信息]\n L -->|验证成功| N[返回 Pydantic 模型]\n M --> H\n```\n\n### Hooks 系统架构\n\nInstructor 提供了强大的钩子系统，允许开发者在请求处理的不同阶段插入自定义逻辑。钩子系统支持拦截请求发送前和响应处理后的流程。资料来源：[examples/hooks/README.md:1-30]()\n\nHook 事件类型包括：\n\n| 事件类型 | 触发时机 | 用途示例 |\n|---------|---------|---------|\n| `on_request` | 发送请求前 | 日志记录、请求修改 |\n| `on_response` | 收到响应后 | 响应日志、使用量统计 |\n| `on_retry` | 重试前 | 错误日志、重试策略调整 |\n| `on_parse_error` | 解析失败时 | 错误处理、调试信息 |\n| `on_completion_error` | 完成错误时 | 错误处理、告警通知 |\n\n## 验证与重试机制\n\n### 自动重试机制\n\nInstructor 的核心特性之一是自动重试机制。当 Pydantic 验证失败时，系统会自动重试并携带错误信息，让 LLM 有机会修正输出。资料来源：[README.md:80-95]()\n\n```mermaid\ngraph LR\n A[首次请求] --> B{验证通过?}\n B -->|是| C[返回结果]\n B -->|否| D[提取验证错误]\n D --> E[携带错误信息重试]\n E --> A\n C --> F[最多重试 max_retries 次]\n F -->|失败| G[抛出异常]\n```\n\n### 验证器链\n\n验证器可以链式使用，形成多层次的验证策略：\n\n```python\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"don't say objectionable things\", allow_override=True)\n ),\n ]\n```\n\n这种设计允许组合使用 Pydantic 原生验证和 LLM 驱动的语义验证。资料来源：[examples/validators/readme.md:30-50]()\n\n## 批处理架构\n\n### BatchProcessor 组件\n\nInstructor 提供了统一的批处理 API，支持多个提供商：\n\n```python\nfrom instructor import BatchProcessor\n\nprocessor = BatchProcessor()\nbatch_id = processor.create_batch(\n model=\"openai/gpt-4o-mini\",\n messages=messages,\n response_model=User,\n)\n```\n\n资料来源：[examples/batch_api/README.md:1-40]()\n\n### 支持的提供商\n\n| 提供商 | 模型示例 | 批处理支持 |\n|--------|---------|-----------|\n| OpenAI | gpt-4o-mini, gpt-4o, gpt-4-turbo | 完整支持 |\n| Anthropic | claude-3-5-sonnet, claude-3-opus | Beta Messages API |\n| Google | gemini-2.0-flash-001, gemini-pro | 模拟模式 |\n\n## 扩展机制\n\n### 插件式架构\n\nInstructor 的架构设计支持插件扩展，主要扩展点包括：\n\n1. **自定义 Provider**：通过实现 provider 适配接口添加新提供商\n2. **自定义 Validator**：通过扩展 validators 模块添加新的验证策略\n3. **Hook 钩子**：通过注册事件处理器扩展处理流程\n\n### 添加新 Provider 的标准流程\n\n1. 在 `providers/` 下创建新的提供商子目录\n2. 添加 `__init__.py` 文件（可为空或包含导入）\n3. 如需自定义处理逻辑，添加 `utils.py` 文件\n4. 如需自定义客户端工厂，添加 `client.py` 文件\n5. 更新提供商注册表\n\n资料来源：[instructor/providers/README.md:18-25]()\n\n## 关键设计模式\n\n### 统一接口模式\n\nInstructor 采用统一接口模式，隐藏底层提供商差异：\n\n- **客户端统一**：所有提供商客户端实现相同的 `chat.completions.create` 接口\n- **响应统一**：无论来源如何，所有响应都转换为 Pydantic 模型实例\n- **错误统一**：验证错误和 API 错误采用一致的异常格式\n\n### 声明式配置模式\n\n开发者通过声明式方式定义期望的输出结构：\n\n```python\nclass User(BaseModel):\n name: str\n age: int\n \n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n\nuser = client.chat.completions.create(\n response_model=User,\n messages=[...],\n)\n```\n\n这种模式将验证逻辑与业务逻辑分离，提高了代码的可读性和可维护性。\n\n### 工厂模式\n\n`from_provider()` 工厂函数是整个系统的入口点，根据提供商标识符动态创建适当的客户端实例。这种模式简化了客户端管理，同时支持运行时提供商切换。\n\n## 总结\n\nInstructor 的系统架构围绕三个核心目标设计：简化 LLM 结构化输出、保证输出质量、支持多提供商。其分层架构确保了关注点分离，而统一的接口模式提供了无缝的跨提供商体验。验证和重试机制的深度集成使得系统能够在 LLM 输出不符合预期时自动恢复，极大地提高了生产环境的稳定性。资料来源：[docs/architecture.md:1-30]()\n\n---\n\n\n\n## 提供商集成\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/providers/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/providers/__init__.py)\n- [instructor/providers/anthropic/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/providers/anthropic/__init__.py)\n- [instructor/providers/gemini/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/providers/gemini/__init__.py)\n- [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)\n- [docs/integrations/index.md](https://github.com/567-labs/instructor/blob/main/docs/integrations/index.md)\n \n\n# 提供商集成\n\n## 概述\n\nInstructor 的提供商集成（Provider Integration）模块为开发者提供了统一的接口，用于对接多种大型语言模型（LLM）提供商。通过 `instructor.from_provider()` 工厂方法，开发者可以使用相同的代码结构访问 OpenAI、Anthropic、Google、Ollama 等不同提供商的模型，无需关心底层 API 的差异。\n\n该模块位于 `instructor/providers/` 目录下，每个提供商都有独立的子目录和实现文件，采用一致的目录结构但根据提供商复杂度灵活配置。\n\n## 核心架构\n\n### 目录结构\n\n```\ninstructor/providers/\n├── __init__.py\n├── provider_name/\n│ ├── __init__.py\n│ ├── client.py # 提供商特定的客户端工厂（可选）\n│ └── utils.py # 提供商特定的工具函数（可选）\n```\n\n资料来源：[instructor/providers/README.md]()\n\n### 提供商分类\n\nInstructor 根据实现复杂度将提供商分为三类：\n\n| 类型 | 提供商列表 | 特征 |\n|------|-----------|------|\n| 完整实现 | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | 包含 `client.py` 和 `utils.py`，需要自定义响应处理逻辑 |\n| 简化实现 | genai, groq, vertexai | 仅包含 `client.py`，使用核心模块的标准响应处理 |\n| 特殊实现 | openai | 仅包含 `utils.py`（`from_openai()` 定义在 `core/client.py` 中） |\n\n资料来源：[instructor/providers/README.md]()\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[用户调用 from_provider] --> B{提供商类型判断}\n B -->|OpenAI| C[core/client.py 处理]\n B -->|Anthropic| D[anthropic/client.py]\n B -->|Gemini| E[gemini/client.py]\n B -->|其他| F[对应 provider/client.py]\n \n D --> G[provider/utils.py 响应处理]\n E --> G\n C --> H[统一响应格式化]\n F --> G\n G --> H\n```\n\n## 快速开始\n\n### 基础用法\n\n使用 `from_provider()` 方法创建客户端：\n\n```python\nimport instructor\n\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地部署)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n```\n\n资料来源：[README.md]()\n\n### 使用 API Key\n\n所有提供商使用统一的 API：\n\n```python\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n name: str\n age: int\n\n# 直接传递 API Key\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\", api_key=\"sk-ant-...\")\n\n# 使用统一接口\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n## 支持的提供商\n\n### OpenAI\n\nOpenAI 是 Instructor 的参考实现，`from_openai()` 函数定义在 `core/client.py` 中。其他提供商的实现都基于此模式。\n\n**支持模型：**\n\n| 模型 | 说明 |\n|------|------|\n| gpt-4o | 最新多模态旗舰模型 |\n| gpt-4-turbo | 高性能 GPT-4 变体 |\n| gpt-4 | 标准 GPT-4 模型 |\n| gpt-3.5-turbo | 快速响应模型 |\n\n### Anthropic\n\nAnthropic 提供商位于 `instructor/providers/anthropic/`，包含完整的 `client.py` 和 `utils.py` 实现。\n\n**支持模型：**\n\n| 模型 | 说明 |\n|------|------|\n| claude-3-5-sonnet-20241022 | 最新 Sonnet 模型 |\n| claude-3-opus-20240229 | 高性能 Opus 模型 |\n| claude-3-haiku-20240307 | 轻量级 Haiku 模型 |\n\n### Google Gemini\n\nGoogle Gemini 提供商位于 `instructor/providers/gemini/`，使用 `gemini-pro` 等模型。\n\n**支持模型：**\n\n| 模型 | 说明 |\n|------|------|\n| gemini-2.0-flash-001 | 快速响应模型 |\n| gemini-pro | 标准 Gemini 模型 |\n| gemini-pro-vision | 多模态支持 |\n\n### 其他提供商\n\nInstructor 还支持以下提供商，采用简化实现：\n\n| 提供商 | 说明 |\n|--------|------|\n| groq | Groq LPU 推理加速 |\n| vertexai | Google Cloud Vertex AI |\n| genai | 通用生成式 AI 接口 |\n| ollama | 本地模型部署 |\n\n## 批量处理集成\n\n每个提供商都支持批量 API 调用，通过 `BatchProcessor` 类实现统一的批量处理接口。\n\n### 批量处理工作流\n\n```mermaid\ngraph LR\n A[准备消息列表] --> B[BatchProcessor]\n B --> C{提供商检测}\n C -->|OpenAI| D[生成 batch JSON]\n C -->|Anthropic| E[使用 beta API]\n C -->|Google| F[模拟模式/GCS]\n D --> G[提交批量任务]\n E --> G\n F --> G\n G --> H[返回 Batch ID]\n```\n\n### 支持的批量操作\n\n```bash\n# 创建批量任务\ninstructor batch create \\\n --messages-file messages.jsonl \\\n --model \"openai/gpt-4o-mini\" \\\n --response-model \"User\"\n\n# 从文件提交批量任务\ninstructor batch create-from-file \\\n --file-path batch_requests.jsonl \\\n --model \"openai/gpt-4o-mini\"\n```\n\n资料来源：[examples/batch_api/README.md]()\n\n## 新增提供商\n\n### 添加步骤\n\n当需要添加新的提供商时，按照以下流程操作：\n\n1. 在 `instructor/providers/` 下创建新的子目录\n2. 添加 `__init__.py` 文件（可为空）\n3. 根据复杂度添加 `client.py` 和/或 `utils.py`\n\n```mermaid\ngraph TD\n A[创建 providers/newprovider/] --> B[添加 __init__.py]\n B --> C{需要自定义处理?}\n C -->|是| D[创建 client.py 和 utils.py]\n C -->|否| E[仅创建 client.py]\n D --> F[实现 from_newprovider 工厂函数]\n E --> F\n F --> G[导出到 providers/__init__.py]\n```\n\n### 实现要求\n\n| 组件 | 必需 | 说明 |\n|------|------|------|\n| `__init__.py` | 是 | 模块初始化文件 |\n| `client.py` | 视情况 | 包含 `from_()` 工厂函数 |\n| `utils.py` | 视情况 | 包含响应处理程序、重试函数、消息格式化工具 |\n\n资料来源：[instructor/providers/README.md]()\n\n## 配置与认证\n\n### 环境变量\n\n| 环境变量 | 提供商 | 说明 |\n|----------|--------|------|\n| `OPENAI_API_KEY` | OpenAI | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | Anthropic | Anthropic API 密钥 |\n| `GOOGLE_API_KEY` | Google | Google AI API 密钥 |\n| `GROQ_API_KEY` | Groq | Groq API 密钥 |\n\n### 初始化参数\n\n`from_provider()` 方法支持以下参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | str | 模型标识符，格式为 `provider/model-name` |\n| `api_key` | str, 可选 | 直接传递 API 密钥，覆盖环境变量 |\n| `base_url` | str, 可选 | 自定义 API 端点 |\n| `max_retries` | int, 可选 | 最大重试次数，默认 3 |\n| `timeout` | float, 可选 | 请求超时时间（秒） |\n\n## 与旧版 API 的兼容性\n\nInstructor 提供了模式转换脚本，用于将旧版 API 调用迁移到新版本：\n\n### API 模式变更\n\n| 旧版模式 | 新版模式 |\n|----------|----------|\n| `client.chat.completions.create` | `client.create` |\n| `client.chat.completions.create_partial` | `client.create_partial` |\n| `client.chat.completions.create_iterable` | `client.create_iterable` |\n| `client.chat.completions.create_with_completion` | `client.create_with_completion` |\n\n### 审计工具\n\n使用 `audit_patterns.py` 脚本检查文档中的旧模式：\n\n```bash\n# 详细报告\npython scripts/audit_patterns.py\n\n# 仅摘要\npython scripts/audit_patterns.py --summary\n\n# 检查单个文件\npython scripts/audit_patterns.py --file docs/index.md\n```\n\n资料来源：[scripts/README.md]()\n\n## 最佳实践\n\n### 提供商选择指南\n\n```mermaid\ngraph TD\n A[选择提供商] --> B{场景类型}\n B -->|生产环境| C{预算考虑}\n C -->|充足| D[OpenAI GPT-4]\n C -->|有限| E[OpenAI GPT-4o-mini 或 Groq]\n B -->|本地部署| F[Ollama]\n B -->|高精度| G[Anthropic Claude Opus]\n B -->|多模态| H[Google Gemini Pro Vision]\n```\n\n### 错误处理\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| API Key 未设置 | 设置对应的环境变量 |\n| 无效模型格式 | 使用 `provider/model-name` 格式 |\n| 不支持的提供商 | 使用支持的提供商列表 |\n| 速率限制 | 配置 `max_retries` 参数 |\n\n## 总结\n\nInstructor 的提供商集成模块通过统一的抽象层，简化了多提供商 LLM 的使用流程。开发者只需掌握 `from_provider()` 工厂方法，即可无缝切换不同的模型提供商，同时保持代码的一致性和可维护性。\n\n---\n\n\n\n## 响应模型\n\n### 相关页面\n\n相关主题：[验证机制](#page-validation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/processing/schema.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/schema.py)\n- [docs/concepts/models.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/models.md)\n- [docs/learning/getting_started/response_models.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/response_models.md)\n- [examples/simple-extraction/maybe_user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/maybe_user.py)\n \n\n# 响应模型\n\n响应模型（Response Model）是 Instructor 库的核心功能，它允许开发者使用 Pydantic 模型定义 LLM 输出的期望结构，实现自动类型验证和解析。\n\n## 概述\n\n在传统的 LLM API 调用中，返回的响应是原始文本或 JSON 字符串，需要开发者手动解析和验证。这种方式不仅繁琐，还容易引入错误。响应模型通过将 Pydantic 模型作为 `response_model` 参数传递，让 Instructor 自动完成以下工作：\n\n| 功能 | 说明 |\n|------|------|\n| 结构提取 | 从 LLM 输出中自动提取 JSON 结构 |\n| 类型转换 | 将字符串转换为 Pydantic 模型定义的类型 |\n| 验证处理 | 执行 Pydantic 验证器，自动重试失败的请求 |\n| 错误处理 | 捕获验证错误并生成有意义的反馈 |\n\n资料来源：[README.md:1-30]()\n\n## 基本用法\n\n### 安装与初始化\n\n```python\npip install instructor\n\n# 从 OpenAI 初始化客户端\nclient = instructor.from_provider(\"openai/gpt-4o\")\n```\n\n资料来源：[README.md:45-50]()\n\n### 定义响应模型\n\n响应模型基于 Pydantic 的 `BaseModel` 构建：\n\n```python\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n name: str\n age: int\n```\n\n### 调用 API\n\n使用 `response_model` 参数指定期望的响应模型：\n\n```python\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"Extract: Jason, 28 years old\"}],\n)\n\n# user 已经是验证通过的 User 实例\nprint(user.name) # Jason\nprint(user.age) # 28\n```\n\n资料来源：[README.md:35-45]()\n\n## 工作原理\n\nInstructor 的响应模型处理流程如下：\n\n```mermaid\ngraph TD\n A[用户请求] --> B[创建 API 调用]\n B --> C{传入 response_model}\n C -->|是| D[发送请求到 LLM]\n C -->|否| E[返回原始响应]\n D --> F[解析 LLM 输出为 JSON]\n F --> G[Pydantic 验证]\n G --> H{验证通过?}\n H -->|是| I[返回模型实例]\n H -->|否| J[生成错误信息]\n J --> K{重试次数 < max_retries?}\n K -->|是| D\n K -->|否| L[抛出 ValidationError]\n```\n\n## 自动重试机制\n\n当 Pydantic 验证失败时，Instructor 会自动将错误信息反馈给 LLM 并重试请求：\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n\n# Instructor 自动处理重试\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n max_retries=3, # 默认值，可自定义\n)\n```\n\n资料来源：[README.md:75-95]()\n\n### 重试流程图\n\n```mermaid\ngraph LR\n A[验证失败] --> B[提取错误信息]\n B --> C[构造修正提示]\n C --> D[重新发送请求]\n D --> E{再次验证}\n E -->|通过| F[返回结果]\n E -->|失败| G{重试次数剩余?}\n G -->|是| A\n G -->|否| H[抛出异常]\n```\n\n## 高级用法\n\n### 使用 BeforeValidator 进行自定义验证\n\n使用 `llm_validator` 实现基于 LLM 的文本验证：\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BeforeValidator\n\nclass QuestionAnswer(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"不要发表不当言论\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md:50-60]()\n\n### 处理验证异常\n\n```python\ntry:\n qa = client.chat.completions.create(\n response_model=QuestionAnswerNoEvil,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n )\nexcept Exception as e:\n print(f\"验证失败: {e}\")\n```\n\n资料来源：[examples/validators/readme.md:80-90]()\n\n### 设置最大重试次数\n\n```python\nqa = client.chat.completions.create(\n model=\"gpt-3.5-turbo\",\n response_model=QuestionAnswerNoEvil,\n max_retries=2, # 允许最多 2 次重试\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n资料来源：[examples/validators/readme.md:100-110]()\n\n## 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `response_model` | Type[BaseModel] | 必需 | 响应的 Pydantic 模型类 |\n| `max_retries` | int | 3 | 最大重试次数 |\n| `validation_context` | dict | None | 传递给验证器的额外上下文 |\n| `strict_response_validation` | bool | False | 是否启用严格验证模式 |\n\n## 与传统方式的对比\n\n| 特性 | 传统方式 | 使用响应模型 |\n|------|----------|--------------|\n| JSON 解析 | 手动解析 | 自动完成 |\n| 类型验证 | 手动检查 | Pydantic 自动验证 |\n| 错误处理 | 复杂的条件判断 | 自动重试和异常 |\n| 代码行数 | 15-20 行 | 3-5 行 |\n\n资料来源：[README.md:1-20]()\n\n## 完整示例\n\n```python\nfrom pydantic import BaseModel, field_validator\nimport instructor\n\n# 初始化客户端\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# 定义响应模型\nclass User(BaseModel):\n name: str\n age: int\n email: str | None = None\n\n @field_validator('age')\n @classmethod\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n\n# 使用响应模型\nuser = client.chat.completions.create(\n model=\"gpt-4o\",\n response_model=User,\n messages=[\n {\"role\": \"system\", \"content\": \"你是一个数据提取助手\"},\n {\"role\": \"user\", \"content\": \"从以下文本提取用户信息：张三，35岁，邮箱 zhangsan@example.com\"}\n ],\n)\n\nprint(f\"姓名: {user.name}\")\nprint(f\"年龄: {user.age}\")\nprint(f\"邮箱: {user.email}\")\n```\n\n## 支持的模型类型\n\n响应模型支持所有 Pydantic v2 的特性：\n\n- 基本类型：`str`、`int`、`float`、`bool`\n- 可选类型：`Optional[T]` 或 `T | None`\n- 列表类型：`List[T]`\n- 嵌套模型：嵌套的 `BaseModel`\n- 联合类型：`Union[A, B]` 或 `A | B`\n- 枚举类型：`Enum`\n- 验证器：`@field_validator`、`@model_validator`\n\n## 最佳实践\n\n1. **始终定义类型注解**：让 Pydantic 正确推断类型\n2. **使用验证器**：在模型中定义业务规则验证\n3. **设置合理的 max_retries**：默认为 3，根据复杂程度调整\n4. **使用 Optional 处理可选字段**：避免验证失败\n5. **保持模型简洁**：复杂逻辑使用嵌套模型分离\n\n## 下一步\n\n- [验证器使用指南](https://instructor-ai.github.io/instructor/concepts/validators/)\n- [钩子系统](https://instructor-ai.github.io/instructor/concepts/hooks/)\n- [批量处理](https://instructor-ai.github.io/instructor/concepts/batch/)\n\n---\n\n\n\n## 验证机制\n\n### 相关页面\n\n相关主题：[响应模型](#page-response-models), [钩子系统](#page-hooks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/dsl/validators.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/validators.py)\n- [instructor/validation/llm_validators.py](https://github.com/567-labs/instructor/blob/main/instructor/validation/llm_validators.py)\n- [instructor/core/retry.py](https://github.com/567-labs/instructor/blob/main/instructor/core/retry.py)\n- [docs/concepts/validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/validation.md)\n- [docs/concepts/reask_validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/reask_validation.md)\n- [examples/validators/field_validator.py](https://github.com/567-labs/instructor/blob/main/examples/validators/field_validator.py)\n \n\n# 验证机制\n\n## 概述\n\nInstructor 的验证机制是确保 LLM（大语言模型）输出结构化数据正确性的核心系统。该机制构建在 Pydantic 框架之上，提供自动验证、错误处理、重试逻辑和 LLM 级语义验证能力。\n\nInstructor 的验证流程采用多层架构设计：\n\n```mermaid\ngraph TD\n A[LLM 响应] --> B[响应解析]\n B --> C[Pydantic 模型验证]\n C --> D{验证通过?}\n D -->|是| E[返回结构化数据]\n D -->|否| F[收集验证错误]\n F --> G{重试次数 < max_retries?}\n G -->|是| H[提取错误信息]\n H --> I[构建重试提示]\n I --> J[重新发送给 LLM]\n J --> A\n G -->|否| K[抛出异常]\n```\n\n资料来源：[docs/concepts/reask_validation.md:1-20]()\n\n## 核心验证流程\n\n### Pydantic BaseModel 集成\n\nInstructor 使用 Pydantic 的 `BaseModel` 作为响应模型的基础。当定义响应模型时，Instructor 自动将模型转换为 LLM 可理解的 JSON Schema，并在验证失败时生成精确的错误提示。\n\n资料来源：[README.md:1-30]()\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n```\n\n资料来源：[README.md:60-75]()\n\n### 字段验证器（Field Validators）\n\n字段验证器允许在字段级别添加自定义验证逻辑。通过 Pydantic 的 `@field_validator` 装饰器，可以对单个字段进行类型检查、范围验证和格式校验。\n\n| 验证器类型 | 说明 | 示例 |\n|-----------|------|------|\n| 类型验证 | 确保字段值符合声明类型 | `age: int` |\n| 范围验证 | 检查值是否在有效范围内 | `0 <= age <= 150` |\n| 格式验证 | 验证字符串格式 | 邮箱、电话号码 |\n| 自定义验证 | 使用 `@field_validator` | 自定义业务逻辑 |\n\n资料来源：[examples/validators/field_validator.py:1-50]()\n\n## LLM 级语义验证\n\n### llm_validator 机制\n\n`llm_validator` 是 Instructor 提供的特殊验证器，用于执行 LLM 级别的语义验证。它允许开发者定义自然语言约束条件，由 LLM 判断输出是否符合预期语义。\n\n资料来源：[instructor/validation/llm_validators.py:1-30]()\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BeforeValidator\nfrom instructor import llm_validator\n\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"不要说出不当言论\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md:1-50]()\n\n### llm_validator 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| constraint | str | 是 | 自然语言约束条件 |\n| allow_override | bool | 否 | 是否允许通过特殊标记覆盖验证 |\n| validation_context | dict | 否 | 额外的验证上下文信息 |\n| max_retries | int | 否 | 最大验证重试次数 |\n\n资料来源：[instructor/validation/llm_validators.py:30-60]()\n\n## 自动重试机制\n\n### 重试工作流程\n\n当验证失败时，Instructor 自动将错误信息提取并附加到下一轮对话中，引导 LLM 修正错误。这一过程无需手动干预。\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant I as Instructor\n participant LLM as LLM API\n participant V as 验证器\n \n U->>I: 调用 create(response_model=User)\n I->>LLM: 发送初始请求\n LLM-->>I: 返回响应\n I->>V: 执行 Pydantic 验证\n V-->>I: 验证失败: age < 0\n I->>I: 生成重试提示\n I->>LLM: 发送修正请求 + 错误信息\n LLM-->>I: 返回修正响应\n I->>V: 再次验证\n V-->>I: 验证通过\n I-->>U: 返回 User 对象\n```\n\n资料来源：[instructor/core/retry.py:1-80]()\n\n### 重试配置\n\n通过 `max_retries` 参数控制重试次数，默认行为由 Instructor 内部配置决定。\n\n```python\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n max_retries=3, # 最多重试3次\n)\n```\n\n资料来源：[README.md:75-85]()\n\n### 重试策略\n\nInstructor 采用指数退避策略处理重试，避免在瞬时错误时过度调用 API。每次重试之间会有适当延迟。\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| max_retries | 最大重试次数 | 3 |\n| retry_on | 触发重试的错误类型 | ValidationError |\n| backoff_factor | 退避因子 | 1.0 |\n\n资料来源：[instructor/core/retry.py:80-120]()\n\n## 错误处理\n\n### 验证错误捕获\n\n验证失败时会抛出 `ValidationError` 异常，可通过标准的 Python 异常处理机制捕获。\n\n```python\ntry:\n qa = client.chat.completions.create(\n response_model=QuestionAnswerNoEvil,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n )\nexcept Exception as e:\n print(f\"验证失败: {e}\")\n```\n\n资料来源：[examples/validators/readme.md:100-120]()\n\n### 错误响应格式\n\n验证错误包含详细的字段级错误信息：\n\n```\n1 validation error for QuestionAnswerNoEvil\nanswer\n Assertion failed, 陈述包含不当言论\n```\n\n资料来源：[examples/validators/readme.md:70-75]()\n\n## 流式验证\n\n### Partial 模型支持\n\nInstructor 支持流式输出验证，使用 `Partial[T]` 类型在生成过程中逐步验证和返回部分结果。\n\n```python\nfrom instructor import Partial\n\nfor partial_user in client.chat.completions.create(\n response_model=Partial[User],\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n stream=True,\n):\n print(partial_user)\n # 输出演变过程:\n # User(name=None, age=None)\n # User(name=\"张三\", age=None)\n # User(name=\"张三\", age=25)\n```\n\n资料来源：[README.md:90-105]()\n\n### 流式验证流程\n\n```mermaid\ngraph LR\n A[开始生成] --> B[解析部分响应]\n B --> C[执行部分验证]\n C --> D[返回部分对象]\n D --> E{生成完成?}\n E -->|否| B\n E -->|是| F[最终验证]\n F --> G[返回完整对象]\n```\n\n## 嵌套对象验证\n\n### 复杂数据结构\n\nInstructor 自动处理嵌套的 Pydantic 模型，支持多层级的结构化数据验证。\n\n```python\nfrom typing import List\n\nclass Address(BaseModel):\n street: str\n city: str\n country: str\n\nclass User(BaseModel):\n name: str\n age: int\n addresses: List[Address]\n```\n\n资料来源：[README.md:110-125]()\n\n### 嵌套验证特性\n\n| 特性 | 说明 |\n|------|------|\n| 递归验证 | 自动验证嵌套层级的所有字段 |\n| 深度限制 | 避免无限嵌套导致的性能问题 |\n| 上下文保持 | 保持嵌套对象间的引用关系 |\n\n## 自定义验证器\n\n### 创建自定义验证器\n\n可通过继承和组合的方式创建领域特定的验证器。\n\n```python\nfrom pydantic import BeforeValidator\nfrom typing import Any\n\ndef custom_validator(value: Any) -> Any:\n # 自定义验证逻辑\n if isinstance(value, str) and len(value) > 100:\n raise ValueError(\"字符串长度不能超过100\")\n return value\n\nclass MyModel(BaseModel):\n content: Annotated[str, BeforeValidator(custom_validator)]\n```\n\n资料来源：[instructor/dsl/validators.py:1-40]()\n\n### 验证器组合\n\n多个验证器可以组合使用，形成链式验证：\n\n```python\nclass ValidatedString(BaseModel):\n value: Annotated[\n str,\n BeforeValidator(validator1),\n BeforeValidator(validator2),\n BeforeValidator(validator3),\n ]\n```\n\n资料来源：[instructor/dsl/validators.py:40-60]()\n\n## 最佳实践\n\n### 验证设计原则\n\n1. **渐进式验证**：从简单类型验证开始，逐步增加复杂规则\n2. **错误消息清晰**：自定义错误消息应明确指出问题所在\n3. **合理设置重试次数**：根据场景调整 `max_retries` 值\n4. **使用 LLM 验证器**：对于语义相关的验证，优先使用 `llm_validator`\n\n### 性能考虑\n\n| 场景 | 建议 |\n|------|------|\n| 大量字段验证 | 使用 `model_validator` 替代多个 `field_validator` |\n| 复杂嵌套结构 | 设置合理的嵌套深度限制 |\n| 高频调用 | 考虑启用验证结果缓存 |\n\n## 相关资源\n\n- Pydantic 官方文档：[https://docs.pydantic.dev/](https://docs.pydantic.dev/)\n- Instructor 验证概念文档：[docs/concepts/validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/validation.md)\n- 重试机制文档：[docs/concepts/reask_validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/reask_validation.md)\n\n---\n\n\n\n## 流式输出\n\n### 相关页面\n\n相关主题：[响应模型](#page-response-models), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/dsl/partial.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/partial.py)\n- [instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py)\n- [docs/concepts/partial.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/partial.md)\n- [docs/concepts/iterable.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/iterable.md)\n- [examples/partial_streaming/run.py](https://github.com/567-labs/instructor/blob/main/examples/partial_streaming/run.py)\n \n\n# 流式输出\n\n## 概述\n\n流式输出（Streaming）是 Instructor 库中用于处理大型语言模型（LLM）响应的核心功能之一。当模型生成较长文本或复杂结构化数据时，流式输出允许开发者逐步获取模型的生成结果，而无需等待完整响应生成完毕。这种方式显著改善了用户体验，特别是在需要实时反馈的应用场景中，如聊天机器人、长文本生成工具和交互式数据分析系统。\n\nInstructor 提供了两种主要的流式输出模式：第一种是部分模式（Partial），用于接收正在构建中的结构化数据；第二种是可迭代模式（Iterable），用于处理需要逐步验证的长序列数据。这两种模式都基于 Pydantic 模型进行类型安全保证，确保流式输出的数据始终符合预期的数据结构。\n\n流式输出的核心优势在于其能够将模型的增量生成与验证逻辑紧密结合。当模型逐 token 生成内容时，Instructor 能够实时解析这些部分内容并填充到 Pydantic 模型字段中，开发者可以在每个增量更新时访问当前已验证的部分数据。这种实时解析和验证的能力使得 Instructor 的流式输出不仅提供了流畅的用户体验，还确保了数据结构的完整性和类型安全。\n\n## 架构设计\n\n### 核心组件关系\n\nInstructor 的流式输出系统由多个关键组件协同工作，这些组件共同实现了从模型生成到结构化数据解析的完整流程。理解这些组件之间的关系对于正确使用流式输出功能至关重要。\n\n```mermaid\ngraph TD\n A[LLM 模型] --> B[流式响应]\n B --> C[响应处理器]\n C --> D[Partial 模式]\n C --> E[Iterable 模式]\n D --> F[Pydantic BaseModel]\n E --> G[迭代器接口]\n F --> H[实时验证]\n G --> I[延迟验证]\n H --> J[增量更新回调]\n I --> J\n```\n\n从架构层面来看，Instructor 的流式输出系统采用了分层设计模式。最底层是模型提供者（Provider）无关的通用接口，中间层是针对不同输出模式的处理逻辑，顶层则是面向开发者的简洁 API。这种分层设计确保了代码的可维护性和扩展性，同时也为支持新的 LLM 提供者提供了便利。\n\n### 数据流处理\n\n流式输出的数据处理流程可以分为几个关键阶段，每个阶段都有明确的职责和接口定义。在数据生成的初始阶段，模型以流式方式返回 token 序列，这些 token 会被实时拼接成部分完成的文本或 JSON 结构。Instructor 的响应处理器负责识别当前接收到的内容是否构成完整的语义单元，并将这些内容路由到相应的处理模块。\n\n```mermaid\nsequenceDiagram\n participant LLM as LLM 模型\n participant Handler as 响应处理器\n participant Parser as 部分解析器\n participant Validator as 验证器\n participant App as 应用程序\n \n LLM->>Handler: 发送增量 token\n Handler->>Parser: 解析部分内容\n Parser->>Validator: 验证当前数据\n Validator-->>Parser: 验证结果\n Parser-->>Handler: 更新状态\n Handler-->>App: 推送部分更新\n App-->>LLM: 请求下一批 token\n```\n\n## Partial 模式\n\n### 功能说明\n\nPartial 模式是 Instructor 流式输出体系中的核心组件，专门设计用于处理结构化数据的增量生成。在传统的非流式调用中，开发者必须等待模型完整生成所有内容后才能获得最终的结构化数据。然而，在许多应用场景中，用户希望能够实时看到正在生成的数据，例如在表单填充、实时分析或交互式问答系统中。\n\nPartial 模式通过维护一个持续更新的 Pydantic 模型实例来实现这一功能。每当模型生成新的 token 并被解析后，对应的模型字段会立即更新，开发者可以访问这些部分填充的字段内容。这种设计确保了数据的即时可用性，同时保持了 Pydantic 模型提供的类型安全和验证功能。\n\nPartial 模式的核心实现位于 `instructor/dsl/partial.py` 文件中，该文件定义了处理部分响应的基础架构和工具函数。这些实现支持多种 LLM 提供者，并提供了灵活的配置选项以适应不同的使用场景。\n\n### 使用示例\n\n使用 Partial 模式需要从 Instructor 导入必要的组件，并定义一个继承自 `BaseModel` 的响应模型。以下是一个典型的工作流程示例，展示了如何配置和使用流式输出来实时获取结构化数据：\n\n```python\nfrom instructor import from_provider\nfrom pydantic import BaseModel\n\n# 初始化 Instructor 客户端\nclient = from_provider(\"openai/gpt-4o\")\n\n# 定义响应模型\nclass UserProfile(BaseModel):\n name: str\n bio: str\n skills: list[str]\n\n# 使用 create_partial 方法进行流式输出\nresponse = client.chat.completions.create_partial(\n model=\"gpt-4o\",\n response_model=UserProfile,\n messages=[\n {\"role\": \"user\", \"content\": \"生成一个用户画像，包含姓名、简介和技能列表\"}\n ]\n)\n\n# 迭代处理部分响应\nfor partial in response:\n print(f\"当前进度 - 姓名: {partial.name}\")\n if partial.bio:\n print(f\"简介: {partial.bio}\")\n if partial.skills:\n print(f\"技能: {partial.skills}\")\n```\n\n上述示例演示了 Partial 模式的基本用法。在实际应用中，开发者可以根据需求添加更复杂的验证逻辑、错误处理机制或用户界面更新代码。关键在于 `create_partial` 方法返回一个可迭代对象，每次迭代都会产生当前已验证的部分数据。\n\n### API 签名\n\n`create_partial` 方法是 Instructor 流式输出 API 的核心入口，其参数设计兼顾了灵活性和易用性。该方法的签名与标准聊天补全 API 保持高度一致，同时添加了专门用于控制流式行为的参数。\n\n| 参数名称 | 类型 | 必需 | 默认值 | 说明 |\n|---------|------|------|--------|------|\n| `response_model` | `type[BaseModel]` | 是 | 无 | Pydantic 模型类，定义期望的输出结构 |\n| `messages` | `List[Dict]` | 是 | 无 | 聊天消息列表，格式同 OpenAI API |\n| `model` | `str` | 是 | 无 | 模型标识符，如 \"gpt-4o\" |\n| `max_retries` | `int` | 否 | 3 | 验证失败时的最大重试次数 |\n| `validation_context` | `Dict` | 否 | None | 传递给验证器的额外上下文 |\n| `tool_choice` | `str` | 否 | None | 强制模型使用特定工具 |\n| `stream` | `bool` | 否 | True | 启用流式输出模式 |\n| `**kwargs` | `Any` | 否 | None | 传递给底层 API 的其他参数 |\n\n方法的返回值是一个生成器对象，每次迭代产生当前已填充的响应模型实例。当模型生成新内容并通过验证时，该实例会更新相应字段的值。\n\n## Iterable 模式\n\n### 功能说明\n\nIterable 模式是 Instructor 提供的另一种流式输出实现，专门针对需要生成多个结构化对象的场景。与 Partial 模式不同，Iterable 模式允许模型生成一个序列中的多个项目，每个项目独立验证并在生成后立即可用。这种模式特别适合处理列表生成、批量提取、连续问答等任务。\n\n在 Iterable 模式的工作流程中，模型可以逐步输出多个对象，每个对象都是完整的 Pydantic 模型实例。当第一个对象完成生成并通过验证后，它会被立即返回给调用者，同时模型继续生成后续对象。这种方式的优势在于解耦了对象的生成顺序和可用性，允许应用程序在等待完整列表生成的同时处理已生成的项目。\n\nIterable 模式的核心实现位于 `instructor/dsl/iterable.py` 文件中，该实现处理了迭代器协议的所有复杂性，包括状态管理、错误恢复和生成终止条件的判断。开发者无需关心这些底层细节，只需专注于处理生成的对象。\n\n### 使用示例\n\n以下示例展示了如何使用 Iterable 模式从文本中提取多个实体信息：\n\n```python\nfrom instructor import from_provider\nfrom pydantic import BaseModel\nfrom typing import List\n\n# 初始化 Instructor 客户端\nclient = from_provider(\"openai/gpt-4o\")\n\n# 定义单个实体的数据模型\nclass ExtractedEntity(BaseModel):\n name: str\n entity_type: str\n confidence: float\n\n# 使用 create_iterable 方法处理多实体提取\nresponse = client.chat.completions.create_iterable(\n model=\"gpt-4o\",\n response_model=ExtractedEntity,\n messages=[\n {\"role\": \"user\", \"content\": \"从以下文本中提取所有提到的组织和人员：...\"}\n ]\n)\n\n# 处理每个提取的实体\nfor entity in response:\n print(f\"提取实体: {entity.name}\")\n print(f\"类型: {entity.entity_type}\")\n print(f\"置信度: {entity.confidence}\")\n```\n\n这个示例演示了 Iterable 模式在信息提取任务中的应用。在实际部署中，开发者可以实现更复杂的处理逻辑，如将提取的实体存储到数据库、实时更新用户界面或进行后续的关联分析。\n\n### 与 Partial 模式的对比\n\nPartial 和 Iterable 模式虽然都是流式输出功能，但它们的设计目标和适用场景有显著差异。理解这些差异有助于开发者选择最适合特定应用需求的模式。\n\n| 特性 | Partial 模式 | Iterable 模式 |\n|------|-------------|---------------|\n| 输出结构 | 单个模型实例逐步更新 | 多个独立模型实例序列 |\n| 适用场景 | 长文本、复杂嵌套结构 | 列表生成、批量提取 |\n| 数据可用性 | 字段级实时更新 | 对象级完成后可用 |\n| 模型消耗 | 较低（共享单个请求） | 取决于对象数量 |\n| 验证时机 | 部分内容即时验证 | 完整对象生成后验证 |\n\n## 实现原理\n\n### 部分模型（Partial Model）\n\nInstructor 的流式输出系统建立在 Pydantic 的部分模型（Partial Model）概念之上。部分模型是 Pydantic `BaseModel` 的一个特殊变体，它允许模型字段在完全填充之前就存在实例。这种设计支持增量数据填充场景，与传统的需要完整数据才能实例化的模型形成对比。\n\n部分模型的实现利用了 Python 的类型注解和描述符协议。当模型实例被创建但某些字段尚未赋值时，这些字段保持为特殊的占位状态。Instructor 的响应处理器会追踪哪些字段已被填充，哪些仍在等待数据，并在每次新的数据到达时更新实例状态。\n\n这种实现方式的一个关键优势是它与 Pydantic 的验证系统完全兼容。即使只有部分字段被填充，Instructor 仍然会对已填充的字段执行验证逻辑，确保数据的有效性和一致性。如果某个字段的验证失败，系统会触发相应的错误处理流程，可能是重试当前字段或跳过该字段继续处理其他内容。\n\n### 验证与重试机制\n\n流式输出中的验证机制面临着独特的挑战，因为部分数据可能不符合完整的验证规则，但这些数据在最终完成时将是有效的。为了处理这种情况，Instructor 实现了智能化的验证策略，在严格性和灵活性之间取得平衡。\n\n```mermaid\ngraph TD\n A[接收增量数据] --> B{字段完整？}\n B -->|是| C[执行完整验证]\n B -->|否| D[检查必填字段]\n C --> E{验证通过？}\n E -->|是| F[更新模型实例]\n E -->|否| G{重试次数<限制？}\n G -->|是| H[发送修正请求]\n G -->|否| I[抛出验证异常]\n D --> F\n H --> A\n```\n\n验证过程首先检查已填充的字段是否满足其约束条件。对于可选字段，即使没有数据也会通过验证；对于必填字段，系统会等待足够的数据到达后才进行验证。一旦所有必填字段都被填充且通过验证，部分模型就可以被安全地传递给应用程序。\n\n重试机制是流式输出可靠性的重要保障。当验证失败且错误表明是暂时性问题（如格式不完整或内容不符合约束）时，Instructor 会自动重试请求，并在重试时附带错误信息作为上下文，帮助模型修正之前的错误输出。\n\n## 高级用法\n\n### 与钩子（Hooks）集成\n\nInstructor 的钩子系统与流式输出功能深度集成，提供了在处理流程的各个阶段插入自定义逻辑的能力。钩子允许开发者在响应处理、数据验证、错误处理等关键时刻执行自定义代码，实现日志记录、性能监控、内容过滤等辅助功能。\n\n流式输出场景下的钩子使用方式与非流式场景基本一致，但钩子接收的参数可能因部分数据的性质而有所不同。例如，一个用于记录进度的钩子可能在每次部分更新时被调用，并接收当前已更新的字段列表作为参数。以下是一个集成钩子的示例：\n\n```python\nfrom instructor import from_provider, Hooks\n\ndef on_partial_update(partial_data):\n print(f\"部分更新接收 - 已填充字段: {list(partial_data.model_dump(exclude_none=True).keys())}\")\n\n# 定义钩子配置\nhooks = Hooks(on_partial_update=on_partial_update)\n\n# 在流式调用中使用钩子\nresponse = client.chat.completions.create_partial(\n model=\"gpt-4o\",\n response_model=UserProfile,\n messages=[...],\n hooks=hooks\n)\n```\n\n### 错误处理策略\n\n流式输出中的错误处理需要考虑实时性和上下文相关性特点。与批处理模式不同，流式场景下的错误通常需要在数据仍在生成时被捕获和处理，否则可能导致用户体验的中断或数据丢失。Instructor 提供了多层次的错误处理机制，以适应不同的故障场景。\n\n在验证错误的情况下，如果设置了 `max_retries` 参数，Instructor 会自动尝试修复问题并继续生成过程。这种自动修复能力依赖于底层模型的上下文理解能力，当错误信息被作为上下文反馈给模型时，模型通常能够理解问题所在并生成更符合要求的输出。如果重试次数耗尽仍未通过验证，系统会抛出异常，应用程序应准备好捕获并优雅地处理这些异常。\n\n对于网络错误或服务不可用等外部问题，Instructor 利用 tenacity 库实现的重试逻辑来处理。这些错误通常是暂时性的，通过指数退避策略进行重试可以有效提高请求成功率。开发者在配置重试策略时应考虑应用场景的实时性要求，在可靠性和响应速度之间做出权衡。\n\n## 最佳实践\n\n### 性能优化建议\n\n在使用 Instructor 流式输出功能时，遵循一定的性能优化实践可以显著提升应用的响应速度和资源利用效率。首先，应该根据实际需求选择合适的流式模式：对于需要实时看到部分结果的场景使用 Partial 模式，对于可以等待完整对象生成后再处理的场景使用 Iterable 模式。\n\n模型选择对性能有直接影响。较大的模型通常能生成更准确的结果，但响应速度和成本也相应增加。在需要高吞吐量的场景中，可以考虑使用较小但足够准确的模型，或者先使用小模型进行快速验证，再在必要时切换到大模型进行精调。\n\n网络连接质量对流式输出的用户体验至关重要。建议使用可靠的连接并进行适当的超时配置。对于需要处理不稳定网络环境的应用，可以实现连接重试逻辑和断点续传机制，确保在网络中断后能够快速恢复处理。\n\n### 常见陷阱与规避\n\n流式输出实现中的常见陷阱之一是在处理部分数据时过早地假设数据完整性。开发者应该始终检查字段是否为 `None` 或使用 Pydantic 的 `model_dump(exclude_none=True)` 方法来获取已填充的数据。忽略这些检查可能导致应用程序在使用未完成的字段值时出现错误。\n\n另一个常见问题是未能正确处理验证失败的情况。在流式场景中，模型可能在首次尝试时生成不符合验证规则的内容，这并不一定表示系统故障。通过设置合理的 `max_retries` 值并实现适当的回退逻辑，可以有效处理这些情况，同时保持良好的用户体验。\n\n资源管理也是需要关注的问题。长时间运行的流式请求会占用网络连接和内存资源，如果应用程序同时处理大量并发请求，可能会导致资源耗尽。建议实现适当的请求限制机制，并确保在使用完毕后正确关闭流式连接。\n\n## 参考资料\n\n本页面内容基于 Instructor 项目的源码和文档生成，以下是主要参考资料：\n\n- 部分模式实现源码：`instructor/dsl/partial.py` 资料来源：[instructor/dsl/partial.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/partial.py)\n- 可迭代模式实现源码：`instructor/dsl/iterable.py` 资料来源：[instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py)\n- 部分模式文档：`docs/concepts/partial.md` 资料来源：[docs/concepts/partial.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/partial.md)\n- 可迭代模式文档：`docs/concepts/iterable.md` 资料来源：[docs/concepts/iterable.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/iterable.md)\n- 流式输出示例代码：`examples/partial_streaming/run.py` 资料来源：[examples/partial_streaming/run.py](https://github.com/567-labs/instructor/blob/main/examples/partial_streaming/run.py)\n- 钩子系统文档：`examples/hooks/README.md` 资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md)\n\n---\n\n\n\n## 批处理\n\n### 相关页面\n\n相关主题：[提供商集成](#page-providers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/batch/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/__init__.py)\n- [instructor/batch/processor.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/processor.py)\n- [instructor/batch/providers/openai.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/providers/openai.py)\n- [instructor/batch/providers/anthropic.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/providers/anthropic.py)\n- [docs/concepts/batch.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/batch.md)\n- [examples/batch_api/run_batch_test.py](https://github.com/567-labs/instructor/blob/main/examples/batch_api/run_batch_test.py)\n \n\n# 批处理\n\n## 概述\n\n批处理（Batching）是 Instructor 库提供的一项高级功能，允许用户将多个 LLM 请求批量提交到各大模型提供商，从而显著提升大规模数据处理的效率。与实时交互式 API 调用不同，批处理作业会在后台异步执行，适用于需要对大量数据进行结构化提取、转换或分类的场景。Instructor 通过统一的 `BatchProcessor` 接口抽象了不同提供商（OpenAI、Anthropic、Google）的批处理实现，开发者无需关心底层细节即可完成跨平台批处理任务。资料来源：[examples/batch_api/README.md](examples/batch_api/README.md)\n\n## 核心架构\n\n### 组件结构\n\nInstructor 的批处理系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责说明 |\n|------|----------|----------|\n| BatchProcessor | `instructor/batch/__init__.py` | 统一的批处理入口，负责路由到具体 Provider |\n| OpenAI Batch Provider | `instructor/batch/providers/openai.py` | 处理 OpenAI 平台的批处理逻辑 |\n| Anthropic Batch Provider | `instructor/batch/providers/anthropic.py` | 处理 Anthropic 平台的批处理逻辑 |\n| run_batch_test.py | `examples/batch_api/run_batch_test.py` | 批处理功能测试脚本 |\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[用户创建批处理请求] --> B[BatchProcessor 接收请求]\n B --> C{Provider 检测}\n C -->|OpenAI| D[OpenAI Batch Provider]\n C -->|Anthropic| E[Anthropic Batch Provider]\n C -->|Google| F[Google Batch Provider]\n D --> G[生成 Provider 特定格式]\n E --> G\n F --> G\n G --> H[提交批处理作业]\n H --> I[保存 Batch ID]\n I --> J[返回控制权给用户]\n J --> K[用户轮询状态]\n K --> L[获取结果]\n```\n\n## BatchProcessor 核心功能\n\n### 主要特性\n\nBatchProcessor 提供了以下核心能力：\n\n- **统一 API 设计**：通过 `instructor.from_provider()` 自动检测提供商类型\n- **异步执行**：批处理作业在后台异步运行，不阻塞主线程\n- **Provider 检测**：自动识别 `provider/model-name` 格式中的提供商\n- **批量文件生成**：根据不同 Provider 生成符合其规范的 JSONL 格式文件\n- **任务状态管理**：保存批处理 ID 供后续状态查询使用\n\n### 使用示例\n\n```python\nfrom instructor.batch import BatchProcessor\nfrom openai import OpenAI\n\n# 初始化客户端和批处理器\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\nbatch_processor = BatchProcessor(client=client)\n\n# 创建批处理作业\nbatch_job = batch_processor.create(\n model=\"openai/gpt-4o-mini\",\n messages=test_messages,\n response_model=User\n)\n\n# 保存 Batch ID\nwith open(\"openai_batch_id.txt\", \"w\") as f:\n f.write(batch_job.id)\n```\n\n## 支持的模型提供商\n\n### OpenAI\n\n| 模型名称 | 资源来源 |\n|----------|----------|\n| `openai/gpt-4o-mini` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `openai/gpt-4o` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `openai/gpt-4-turbo` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n\n### Anthropic\n\n| 模型名称 | 资源来源 |\n|----------|----------|\n| `anthropic/claude-3-5-sonnet-20241022` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `anthropic/claude-3-opus-20240229` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `anthropic/claude-3-haiku-20240307` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n\n### Google\n\n| 模型名称 | 资源来源 |\n|----------|----------|\n| `google/gemini-2.0-flash-001` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `google/gemini-pro` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `google/gemini-pro-vision` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n\n## Provider 特定实现\n\n### OpenAI Batch Provider\n\nOpenAI 的批处理采用 `client.beta.batch` 端点，生成符合 OpenAI 规范的批处理文件格式。处理流程包括：\n\n1. 接收消息列表和响应模型\n2. 将每个消息转换为 OpenAI Batch API 的 JSONL 格式\n3. 提交批处理作业到 OpenAI 端点\n4. 返回包含批处理 ID 的响应对象\n\n资料来源：[instructor/batch/providers/openai.py](instructor/batch/providers/openai.py)\n\n### Anthropic Batch Provider\n\nAnthropic 的批处理使用 `client.beta.messages.batches` 端点，属于 Beta API 范畴。需要特别注意：\n\n- 必须拥有 Anthropic API 访问权限\n- 可能存在地区可用性限制\n- 批处理速率限制与常规 API 分离\n\n资料来源：[instructor/batch/providers/anthropic.py](instructor/batch/providers/anthropic.py)\n\n### Google Batch Provider\n\nGoogle Gemini 的批处理目前默认为模拟模式运行。完整实现需要：\n\n- 配置 Google Cloud Storage (GCS)\n- 设置适当的 GCS 认证\n- 创建实际的 GCS 存储桶用于输入/输出\n\n资料来源：[examples/batch_api/README.md](examples/batch_api/README.md)\n\n## 命令行接口\n\nInstructor CLI 提供了便捷的批处理操作命令：\n\n```bash\n# 创建批处理作业\ninstructor batch create \\\n --messages-file messages.jsonl \\\n --model \"openai/gpt-4o-mini\" \\\n --response-model \"examples.User\" \\\n --output-file batch_requests.jsonl\n\n# 从文件提交批处理\ninstructor batch create-from-file \\\n --file-path batch_requests.jsonl \\\n --model \"openai/gpt-4o-mini\"\n```\n\n资料来源：[examples/batch_api/README.md](examples/batch_api/README.md)\n\n## 环境配置\n\n### API 密钥要求\n\n| 提供商 | 环境变量 | 必需性 |\n|--------|----------|--------|\n| OpenAI | `OPENAI_API_KEY` | 必须设置 |\n| Anthropic | `ANTHROPIC_API_KEY` | 必须设置 |\n| Google | `GOOGLE_API_KEY` | 必须设置 |\n\n### 直接传递密钥\n\n除了环境变量方式，Instructor 也支持在代码中直接传递 API 密钥：\n\n```python\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\", api_key=\"sk-ant-...\")\nclient = instructor.from_provider(\"groq/llama-3.1-8b-instant\", api_key=\"gsk_...\")\n```\n\n## 常见错误处理\n\n### Provider 格式错误\n\n```\n❌ Error: Model must be in format 'provider/model-name'\n```\n\n**解决方案**：使用 `provider/model-name` 格式，例如 `openai/gpt-4o-mini`\n\n### 不支持的 Provider\n\n```\n❌ Unsupported provider: xyz\n```\n\n**解决方案**：当前仅支持 `openai`、`anthropic` 和 `google` 作为 Provider\n\n### 密钥未设置\n\n```\n❌ OPENAI_API_KEY is not set\n```\n\n**解决方案**：设置相应的环境变量或通过参数传递 API 密钥\n\n## 测试与验证\n\n### 测试脚本\n\n`examples/batch_api/run_batch_test.py` 提供完整的批处理功能测试：\n\n```bash\n# 测试 OpenAI\nexport OPENAI_API_KEY=\"your-openai-api-key\"\npython run_batch_test.py create --model \"openai/gpt-4o-mini\"\n\n# 测试 Anthropic\nexport ANTHROPIC_API_KEY=\"your-anthropic-api-key\"\npython run_batch_test.py create --model \"anthropic/claude-3-5-sonnet-20241022\"\n\n# 测试 Google (模拟模式)\npython run_batch_test.py create --model \"google/gemini-2.0-flash-001\"\n```\n\n### 查看支持模型\n\n```bash\npython run_batch_test.py list-models\n```\n\n## 与其他功能的集成\n\n### 与 Retries 的结合\n\n批处理支持 Instructor 的自动重试机制，当验证失败时会自动重试：\n\n```python\nbatch_job = batch_processor.create(\n model=\"openai/gpt-4o-mini\",\n messages=test_messages,\n response_model=User,\n max_retries=3 # 启用自动重试\n)\n```\n\n### 与 Validators 的结合\n\n批处理可以配合 Pydantic 验证器使用，确保输出符合预期结构：\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n\nbatch_job = batch_processor.create(\n model=\"openai/gpt-4o-mini\",\n messages=test_messages,\n response_model=User\n)\n```\n\n## 最佳实践\n\n1. **批量大小控制**：根据 Provider 的速率限制调整批处理大小\n2. **响应模型设计**：使用清晰的 Pydantic 模型定义期望的输出结构\n3. **错误处理**：实现健壮的错误捕获和重试逻辑\n4. **状态监控**：定期轮询批处理状态以获取最新结果\n5. **成本优化**：选择合适的模型（如 gpt-4o-mini）以平衡成本和性能\n\n---\n\n\n\n## 钩子系统\n\n### 相关页面\n\n相关主题：[验证机制](#page-validation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n- [instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n- [docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n- [examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n \n\n# 钩子系统\n\n## 概述\n\nInstructor 的钩子系统是一个强大的事件监听与回调机制，允许开发者在 LLM 请求的完整生命周期中插入自定义逻辑。通过钩子，开发者可以监控请求状态、记录日志、统计 token 使用量、处理解析错误、捕获完成错误以及跟踪重试尝试。\n\n钩子系统的主要作用包括：\n\n- **请求监控**：在请求发送前获取完整的请求详情\n- **使用量统计**：追踪输入/输出 token 数量和成本\n- **错误处理**：捕获并处理解析错误和完成错误\n- **重试跟踪**：记录自动重试的次数和状态变化\n- **自定义扩展**：在任意生命周期节点插入业务逻辑\n\n资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md)\n\n## 架构设计\n\n### 钩子类型体系\n\nInstructor 的钩子系统采用分层架构设计，主要包含以下钩子类型：\n\n```mermaid\ngraph TD\n A[Hook 基类] --> B[HookStatistics]\n A --> C[HookBase]\n B --> D[TokenUsageHook]\n B --> E[RetryHook]\n C --> F[ParseErrorHook]\n C --> G[CompletionErrorHook]\n C --> H[RequestHook]\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n### 请求生命周期钩子流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Hooks as 钩子系统\n participant LLM as LLM API\n participant Validator as 验证器\n \n Client->>Hooks: 1. 触发 on_request 钩子\n Hooks->>Hooks: 记录请求详情和模型信息\n Client->>LLM: 2. 发送请求\n LLM-->>Client: 返回响应\n Client->>Hooks: 3. 触发 on_new_token 钩子\n Hooks->>Hooks: 记录 token 使用量\n Client->>Validator: 4. 验证响应\n alt 验证成功\n Client->>Hooks: 5. 触发 on_success 钩子\n else 验证失败\n Client->>Hooks: 5a. 触发 on_retry 钩子\n Client->>LLM: 6. 重试请求\n loop 直到成功或达到最大重试次数\n LLM-->>Client: 返回新响应\n Client->>Validator: 重新验证\n end\n alt 最终成功\n Client->>Hooks: 触发 on_success\n else 最终失败\n Client->>Hooks: 触发 on_parse_error 或 on_completion_error\n end\n end\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n## 核心钩子类型详解\n\n### 1. 请求钩子 (RequestHook)\n\n请求钩子允许在每次 API 调用时执行自定义逻辑，可用于日志记录、请求追踪等场景。\n\n**事件触发时机**：在请求发送到 LLM API 之前触发。\n\n```python\nfrom instructor.hooks import RequestHook\n\ndef my_request_hook(\n completion: Any,\n prompt: Union[str, List[Dict]],\n model: str,\n **kwargs: Any,\n) -> None:\n \"\"\"自定义请求钩子\"\"\"\n print(f\"请求发送至模型: {model}\")\n print(f\"提示词长度: {len(str(prompt))} 字符\")\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 2. Token 使用量钩子 (TokenUsageHook)\n\nToken 使用量钩子用于统计和记录 API 调用消耗的 token 数量及预估成本。\n\n**事件触发时机**：在收到响应后、解析完成前触发。\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| completion | Any | 原始 API 响应对象 |\n| prompt_tokens | int | 输入 prompt 消耗的 token 数 |\n| completion_tokens | int | 输出 completion 消耗的 token 数 |\n| total_tokens | int | 总 token 消耗量 |\n\n```python\nfrom instructor.hooks import TokenUsageHook\n\nclass MyTokenTracker(TokenUsageHook):\n def __init__(self):\n self.total_input_tokens = 0\n self.total_output_tokens = 0\n self.cost_per_1k_input = 0.0015 # GPT-4o 价格\n self.cost_per_1k_output = 0.002\n\n def __call__(\n self,\n completion: Any,\n prompt_tokens: int,\n completion_tokens: int,\n total_tokens: int,\n **kwargs: Any,\n ) -> None:\n self.total_input_tokens += prompt_tokens\n self.total_output_tokens += completion_tokens\n estimated_cost = (\n prompt_tokens * self.cost_per_1k_input / 1000 +\n completion_tokens * self.cost_per_1k_output / 1000\n )\n print(f\"预估成本: ${estimated_cost:.4f}\")\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n### 3. 解析错误钩子 (ParseErrorHook)\n\n解析错误钩子在响应无法被解析为目标 Pydantic 模型时触发。\n\n**事件触发时机**：当模型验证失败或响应格式不符合预期时触发。\n\n```python\nfrom instructor.hooks import ParseErrorHook\n\ndef handle_parse_error(\n completion: Any,\n response_model: Type[BaseModel],\n error: ValidationError,\n attempt: int,\n **kwargs: Any,\n) -> None:\n \"\"\"处理解析错误\"\"\"\n print(f\"解析错误 (尝试 {attempt}/{max_retries})\")\n print(f\"错误详情: {error}\")\n # 可选: 记录到监控系统\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 4. 完成错误钩子 (CompletionErrorHook)\n\n完成错误钩子在 LLM API 调用本身失败时触发，如网络错误、超时、API 限流等。\n\n**事件触发时机**：当 API 调用抛出异常时触发。\n\n```python\nfrom instructor.hooks import CompletionErrorHook\n\ndef handle_completion_error(\n completion: Optional[Any],\n error: Exception,\n attempt: int,\n **kwargs: Any,\n) -> None:\n \"\"\"处理 API 完成错误\"\"\"\n print(f\"API 错误 (尝试 {attempt}/{max_retries})\")\n print(f\"错误类型: {type(error).__name__}\")\n print(f\"错误信息: {str(error)}\")\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 5. 重试钩子 (RetryHook)\n\n重试钩子在触发自动重试时调用，可用于追踪重试行为和性能监控。\n\n**事件触发时机**：在每次重试开始前触发。\n\n```python\nfrom instructor.hooks import RetryHook\n\ndef track_retry(\n attempt: int,\n exception: Exception,\n **kwargs: Any,\n) -> None:\n \"\"\"追踪重试行为\"\"\"\n print(f\"触发重试 #{attempt}\")\n print(f\"原因: {type(exception).__name__}: {exception}\")\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n## 使用指南\n\n### 基础使用方式\n\n#### 方式一：使用装饰器注册钩子\n\n```python\nfrom instructor import from_openai\nfrom instructor.hooks import Hooks, hook\n\nclient = from_openai(OpenAI())\n\n@hook\ndef my_hooks(\n on_request: bool = True,\n on_success: bool = True,\n on_retry: bool = True,\n on_error: bool = True,\n **kwargs,\n) -> Hooks:\n # 每次请求时打印统计信息\n print(f\"Request sent to {kwargs.get('model', 'unknown')}\")\n return Hooks(\n on_new_token=lambda token, **kw: print(f\"Token: {token}\"),\n on_success=lambda response, **kw: print(\"Success!\"),\n )\n\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n response_model=User,\n hooks=my_hooks, # 传入钩子函数\n)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n#### 方式二：创建 Hooks 实例\n\n```python\nfrom instructor import Instructor\nfrom instructor.hooks import Hooks\n\ndef request_handler(completion, **kwargs):\n print(f\"📏 近似输入 Token 数量: {kwargs.get('estimated_tokens', 0)}\")\n\ndef success_handler(response, **kwargs):\n print(\"✅ 成功响应\")\n print(f\"响应类型: {type(response)}\")\n\nhooks = Hooks(\n on_request=request_handler,\n on_success=success_handler,\n)\n\nclient = Instructor(\n model=\"gpt-4o-mini\",\n hooks=hooks,\n)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n### 客户端级钩子配置\n\n在创建客户端时配置全局钩子：\n\n```python\nfrom instructor import from_openai\n\n# 全局钩子实例\nglobal_hooks = Hooks(\n on_request=lambda **kw: log_request(**kw),\n on_new_token=lambda token, **kw: track_token(token, **kw),\n on_success=lambda response, **kw: log_success(**kw),\n on_retry=lambda attempt, **kw: log_retry(attempt, **kw),\n on_parse_error=lambda error, **kw: alert_parse_error(error, **kw),\n on_completion_error=lambda error, **kw: alert_completion_error(error, **kw),\n)\n\nclient = from_openai(\n OpenAI(),\n hooks=global_hooks,\n)\n```\n\n资料来源：[docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n\n### 请求级钩子覆盖\n\n单个请求可以覆盖客户端级钩子：\n\n```python\nfrom instructor.hooks import Hooks\n\nrequest_hooks = Hooks(\n on_request=lambda **kw: print(f\"此请求使用模型: {kw.get('model')}\"),\n)\n\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"Extract user info\"}],\n response_model=User,\n hooks=request_hooks, # 仅此请求使用\n)\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n## 高级用法\n\n### 多钩子组合\n\n```python\nfrom instructor.hooks import Hooks\n\nclass StatisticsCollector:\n \"\"\"统计收集器\"\"\"\n def __init__(self):\n self.request_count = 0\n self.success_count = 0\n self.error_count = 0\n self.total_retries = 0\n\n def on_request(self, **kwargs):\n self.request_count += 1\n print(f\"📊 请求 #{self.request_count}\")\n\n def on_success(self, **kwargs):\n self.success_count += 1\n print(f\"✅ 成功 #{self.success_count}\")\n\n def on_retry(self, attempt, **kwargs):\n self.total_retries += 1\n print(f\"🔄 重试 #{attempt} (总计: {self.total_retries})\")\n\n def on_parse_error(self, error, **kwargs):\n self.error_count += 1\n print(f\"⚠️ 解析错误 #{self.error_count}: {error}\")\n\n# 创建收集器实例\nstats = StatisticsCollector()\n\nhooks = Hooks(\n on_request=stats.on_request,\n on_success=stats.on_success,\n on_retry=stats.on_retry,\n on_parse_error=stats.on_parse_error,\n)\n\n# 使用钩子\nclient = from_openai(OpenAI(), hooks=hooks)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n### 钩子与重试机制集成\n\n钩子系统与 Instructor 的自动重试机制深度集成：\n\n```mermaid\ngraph LR\n A[请求发送] --> B{验证成功?}\n B -->|是| C[触发 on_success]\n B -->|否| D{还有重试次数?}\n D -->|是| E[触发 on_retry]\n E --> F[重新发送请求]\n F --> A\n D -->|否| G{错误类型}\n G -->|解析错误| H[触发 on_parse_error]\n G -->|API错误| I[触发 on_completion_error]\n```\n\n```python\nfrom instructor.hooks import Hooks\n\ndef retry_logger(attempt, exception, **kwargs):\n \"\"\"记录重试详情\"\"\"\n print(f\"🔄 重试 #{attempt}\")\n print(f\" 异常类型: {type(exception).__name__}\")\n print(f\" 异常信息: {str(exception)[:100]}\")\n\nhooks = Hooks(\n on_retry=retry_logger,\n)\n\n# Instructor 会自动使用钩子在重试时通知\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n response_model=User,\n max_retries=3, # 启用自动重试\n hooks=hooks,\n)\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n### 条件性钩子执行\n\n```python\nfrom instructor.hooks import Hooks\nfrom functools import partial\n\ndef log_if_error(error, **kwargs):\n \"\"\"仅在错误发生时记录\"\"\"\n print(f\"⚠️ 错误: {error}\")\n\ndef log_every_request(model, **kwargs):\n \"\"\"记录所有请求\"\"\"\n print(f\"📤 请求: {model}\")\n\ndef conditional_hooks_factory(condition: bool):\n \"\"\"根据条件返回不同的钩子\"\"\"\n if condition:\n return Hooks(\n on_request=log_every_request,\n on_error=log_if_error,\n )\n return Hooks()\n\n# 根据业务逻辑选择钩子\nhooks = conditional_hooks_factory(debug_mode=True)\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n## Hooks 类 API 参考\n\n### 构造函数参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| on_request | Callable | None | 请求发送前调用的钩子 |\n| on_new_token | Callable | None | 每个新 token 生成时调用 |\n| on_success | Callable | None | 验证成功时调用 |\n| on_retry | Callable | None | 触发重试时调用 |\n| on_parse_error | Callable | None | 解析错误时调用 |\n| on_completion_error | Callable | None | API 完成错误时调用 |\n\n### on_request 钩子参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| completion | Any | 响应对象 |\n| prompt | Union[str, List[Dict]] | 发送的提示词 |\n| model | str | 使用的模型名称 |\n| **kwargs | Any | 其他扩展参数 |\n\n### on_success 钩子参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| response | BaseModel | 解析后的响应模型实例 |\n| completion | Any | 原始响应对象 |\n| **kwargs | Any | 其他扩展参数 |\n\n### on_retry 钩子参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| attempt | int | 当前重试次数 |\n| exception | Exception | 导致重试的异常对象 |\n| **kwargs | Any | 其他扩展参数 |\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n## 最佳实践\n\n### 1. 钩子函数应保持轻量\n\n```python\n# ✅ 推荐：轻量级钩子\ndef quick_log(**kwargs):\n logger.info(f\"Model: {kwargs.get('model')}\")\n\n# ❌ 避免：重量级操作在钩子中\ndef heavy_hook(**kwargs):\n # 不要在钩子中进行复杂计算或网络请求\n result = some_external_api_call() # 这会影响性能\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n### 2. 使用类封装状态\n\n```python\nclass HookManager:\n \"\"\"钩子管理器 - 封装状态和逻辑\"\"\"\n \n def __init__(self, output_path: str):\n self.output_path = output_path\n self.metrics = []\n \n def create_hooks(self) -> Hooks:\n return Hooks(\n on_request=self._handle_request,\n on_success=self._handle_success,\n on_error=self._handle_error,\n )\n \n def _handle_request(self, **kwargs):\n self.metrics.append({\"type\": \"request\", **kwargs})\n \n def _handle_success(self, response, **kwargs):\n self.metrics.append({\"type\": \"success\"})\n \n def _handle_error(self, error, **kwargs):\n self.metrics.append({\"type\": \"error\", \"error\": str(error)})\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 3. 分离关注点\n\n```python\n# 不同的关注点使用不同的钩子处理器\nclass RequestLogger:\n def __call__(self, **kwargs):\n logging.info(f\"Request: {kwargs}\")\n\nclass MetricsCollector:\n def __call__(self, **kwargs):\n prometheus.counter(\"instructor_requests\").inc()\n\nclass AlertManager:\n def __call__(self, error, **kwargs):\n sentry.capture_exception(error)\n\n# 组合使用\nhooks = Hooks(\n on_request=RequestLogger(),\n on_success=MetricsCollector(),\n on_error=AlertManager(),\n)\n```\n\n资料来源：[docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n\n### 4. 异常安全\n\n```python\ndef safe_hook(func):\n \"\"\"包装钩子以确保异常安全\"\"\"\n def wrapper(*args, **kwargs):\n try:\n func(*args, **kwargs)\n except Exception as e:\n # 记录错误但不阻止流程\n logging.error(f\"Hook error: {e}\")\n return wrapper\n\nhooks = Hooks(\n on_request=safe_hook(my_request_hook),\n on_success=safe_hook(my_success_hook),\n)\n```\n\n## 常见应用场景\n\n### 场景一：API 使用量监控\n\n```python\nfrom instructor.hooks import Hooks\n\nclass UsageMonitor:\n def __init__(self):\n self.total_tokens = {\"prompt\": 0, \"completion\": 0}\n \n def __call__(self, **kwargs):\n self.total_tokens[\"prompt\"] += kwargs.get(\"prompt_tokens\", 0)\n self.total_tokens[\"completion\"] += kwargs.get(\"completion_tokens\", 0)\n print(f\"累计: 输入={self.total_tokens['prompt']}, 输出={self.total_tokens['completion']}\")\n\nhooks = Hooks(\n on_new_token=UsageMonitor(),\n)\n```\n\n### 场景二：调试响应内容\n\n```python\ndef debug_hook(response, completion, **kwargs):\n \"\"\"调试钩子：打印响应详情\"\"\"\n print(\"=\" * 50)\n print(f\"响应类型: {type(response)}\")\n print(f\"原始响应: {completion}\")\n print(\"=\" * 50)\n\nhooks = Hooks(\n on_success=debug_hook,\n)\n```\n\n### 场景三：性能追踪\n\n```python\nimport time\n\nclass PerformanceTracker:\n def __init__(self):\n self.start_time = None\n \n def on_request(self, **kwargs):\n self.start_time = time.time()\n \n def on_success(self, response, **kwargs):\n elapsed = time.time() - self.start_time\n print(f\"⏱️ 响应时间: {elapsed:.2f}秒\")\n \n def on_retry(self, attempt, **kwargs):\n print(f\"🔄 第 {attempt} 次重试...\")\n\nhooks = Hooks(\n on_request=PerformanceTracker().on_request,\n on_success=PerformanceTracker().on_success,\n on_retry=PerformanceTracker().on_retry,\n)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n## 总结\n\nInstructor 的钩子系统提供了一套完整的事件监听机制，覆盖了 LLM 请求的完整生命周期。通过合理使用钩子，开发者可以实现：\n\n- **可观测性**：监控请求、响应、错误和性能指标\n- **可追溯性**：记录详细的操作日志用于审计\n- **自愈能力**：结合重试机制自动处理临时性故障\n- **业务扩展**：在任意生命周期节点插入自定义逻辑\n\n钩子系统设计简洁、API 清晰，与 Instructor 的核心功能深度集成，是构建生产级 LLM 应用不可或缺的组件。\n\n资料来源：[docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：567-labs/instructor\n\n摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Documentation (at least Google-related) is an outdated mess.。\n\n## 1. 安装坑 · 来源证据：Documentation (at least Google-related) is an outdated mess.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess.\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v1.13.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 配置坑 · 来源证据：v1.12.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：v1.14.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v1.14.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v1.14.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：v1.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：v1.14.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Catching IncompleteOutputException : not possible as presently documented / tested.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Catching IncompleteOutputException : not possible as presently documented / tested.\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc0f4256859740f8a4cacd1731514783 | https://github.com/567-labs/instructor/issues/2273 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b982358c78a346bfaa26b428e00968bb | https://github.com/567-labs/instructor/issues/2291 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：bump lightllm upper bound for recent vulnerabililties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bump lightllm upper bound for recent vulnerabililties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ae9c53479204c778e56a8b4b3feb404 | https://github.com/567-labs/instructor/issues/2290 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：logger.debug in response.py leaks api_key verbatim via new_kwargs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：logger.debug in response.py leaks api_key verbatim via new_kwargs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2076a35fb27a4c119141e9f57acdf9bc | https://github.com/567-labs/instructor/issues/2265 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry m…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry message\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ab343e8383b4d89bbe8eeea25cc69d8 | https://github.com/567-labs/instructor/issues/2277 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.14.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.14.5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e73ef57918504fe88cf0af969c414ca1 | https://github.com/567-labs/instructor/releases/tag/v1.14.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：v1.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef102fc17ae84e319f80cfd4cc306eaa | https://github.com/567-labs/instructor/releases/tag/v1.15.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | release_recency=unknown\n\n\n",
"markdown_key": "instructor",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:653589102",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/567-labs/instructor"
},
{
"evidence_id": "art_011c606e51c94959817c7bc10ccb55af",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/567-labs/instructor#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "instructor 说明书",
"toc": [
"https://github.com/567-labs/instructor 项目说明书",
"目录",
"项目概览",
"什么是 Instructor",
"核心功能特性",
"自动重试直到验证通过或达到最大重试次数",
"系统架构",
"高级功能",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "5e8e2d57e791ed505c9637c0e215b10a5441b66a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"requirements.txt",
"docs/why.md",
"docs/architecture.md",
"docs/contributing.md",
"docs/newsletter.md",
"docs/debugging.md",
"docs/index.md",
"docs/api.md",
"docs/repository-overview.md",
"docs/getting-started.md",
"docs/api-docstring-assessment.md",
"docs/installation.md",
"docs/modes-comparison.md",
"docs/start-here.md",
"docs/faq.md",
"docs/help.md",
"docs/jobs.md",
"docs/AGENT.md",
"docs/cli/finetune.md",
"docs/cli/index.md",
"docs/cli/batch.md",
"docs/cli/usage.md",
"docs/blog/index.md",
"docs/blog/.authors.yml",
"docs/hooks/hide_lines.py",
"docs/concepts/iterable.md",
"docs/concepts/typeadapter.md",
"docs/concepts/lists.md",
"docs/concepts/philosophy.md",
"docs/concepts/prompt_caching.md",
"docs/concepts/index.md",
"docs/concepts/dictionary_operations.md",
"docs/concepts/prompting.md",
"docs/concepts/reask_validation.md",
"docs/concepts/templating.md",
"docs/concepts/citation.md",
"docs/concepts/logging.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# instructor - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 instructor 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install instructor` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86\n- `pip install -r requirements-doc.txt` 证据：`CLAUDE.md` Claim：`clm_0004` supported 0.86\n- `pip install \"instructor[anthropic]\"` 证据：`CLAUDE.md` Claim：`clm_0005` supported 0.86\n- `pip install \"instructor[google-generativeai]\"` 证据：`CLAUDE.md` Claim：`clm_0006` supported 0.86\n- `pip install \"instructor[groq]\"` 证据：`CLAUDE.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`CLAUDE.md`, `README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：712\n- 重要文件覆盖：40/712\n- 证据索引条目：79\n- 角色 / Skill 条目：79\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 instructor 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 instructor 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 instructor 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 79 个角色 / Skill / 项目文档条目。\n\n- **Contributing to Instructor**（project_doc）：Join us in enhancing the Instructor library with evals, report issues, and submit pull requests on GitHub. Collaborate and contribute! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/contributing.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **Instructor: Structured Outputs for LLMs**（project_doc）：Instructor: Structured Outputs for LLMs 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Scripts Directory**（project_doc）：This directory contains utility scripts for maintaining and improving the Instructor documentation and project structure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`scripts/README.md`\n- **Cursor Rules**（project_doc）：Cursor rules are configuration files that help guide AI-assisted development in the Cursor IDE. They provide structured instructions for how the AI should behave in specific contexts or when working with certain types of files. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.cursor/rules/readme.md`\n- **Batch API Examples**（project_doc）：This directory contains examples and test scripts for Instructor's batch processing capabilities, including both traditional file-based and new in-memory processing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/batch_api/README.md`\n- **Instructor Caching Prototype**（project_doc）：This example demonstrates the new built-in caching functionality in Instructor. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/caching_prototype/README.md`\n- **Introduction**（project_doc）：This is a simple example which shows how to perform Chain Of Density summarization using GPT-3.5 and utilise the generated output to fine-tune a 3.5 model for production usage. All of our data referenced in this file is located here https://huggingface.co/datasets/ivanleomk/gpt4-chain-of-density on hugging face 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/chain-of-density/Readme.md`\n- **Citation with Extraction**（project_doc）：This repository contains a FastAPI application that uses GPT-4 to answer questions based on a given context and extract relevant facts with correct and exact citations. The extracted facts are returned as JSON events using Server-Sent Events SSE . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/citation_with_extraction/README.md`\n- **FastAPI Code Generator**（project_doc）：Generates FastAPI application code from API path, task name, JSON schema path, and Jinja2 prompt template. Also creates a models.py file for Pydantic models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/codegen-from-schema/readme.md`\n- **What to Expect**（project_doc）：What to Expect This script demonstrates how to use the Instructor library for fine-tuning a Python function that performs three-digit multiplication. It uses Pydantic for type validation and logging features to generate a fine-tuning dataset. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/distilations/readme.md`\n- **Instructor Hooks Example**（project_doc）：This example demonstrates how to use the Hooks system in the Instructor library to monitor, log, and debug your LLM interactions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/hooks/README.md`\n- **Instructions**（project_doc）：1. Create a virtual environment and install all of the packages inside requirements.txt 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/logfire-fastapi/Readme.md`\n- **Read first to correctly work with the provided examples**（project_doc）：Read first to correctly work with the provided examples 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/open_source_examples/README.md`\n- **Using llm validator with OpenAI's GPT-3.5 Turbo and Pydantic for Text Validation with Output Examples**（project_doc）：Using llm validator with OpenAI's GPT-3.5 Turbo and Pydantic for Text Validation with Output Examples 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/validators/readme.md`\n- **Providers Directory Structure**（project_doc）：This directory contains implementations for all supported LLM providers in the instructor library. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`instructor/providers/README.md`\n- **Contributing to Instructor**（project_doc）：Thank you for considering contributing to Instructor! This document provides guidelines and instructions to help you contribute effectively. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Core Provider Tests**（project_doc）：This directory contains unified tests that run across all core providers : OpenAI, Anthropic, Google Gemini , Cohere, xAI, Mistral, Cerebras, Fireworks, Writer, and Perplexity. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/llm/test_core_providers/README.md`\n- **AGENT.md - Documentation**（project_doc）：Internal guide for maintaining and improving Instructor documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/AGENT.md`\n- **API Docstring Quality Assessment**（project_doc）：This document assesses the quality and completeness of docstrings for all API items referenced in the expanded API documentation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api-docstring-assessment.md`\n- **API Reference**（project_doc）：Explore the comprehensive API reference with details on instructors, validation, iteration, and function calls. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api.md`\n- **Architecture Overview**（project_doc）：Learn about the internal architecture and design decisions of the Instructor library 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture.md`\n- **Debugging**（project_doc）：Learn how to debug Instructor applications with hooks, logging, and exception handling. Practical techniques for inspecting inputs, outputs, and retries. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/debugging.md`\n- **Frequently Asked Questions**（project_doc）：Common questions and answers about using Instructor 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/faq.md`\n- **Getting Started with Instructor**（project_doc）：A step-by-step guide to getting started with Instructor for structured outputs from LLMs 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/getting-started.md`\n- **Getting help with Instructor**（project_doc）：Explore key resources for getting help with Instructor, including Discord, blog, concepts, cookbooks, and GitHub discussions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/help.md`\n- **Instructor: Top Multi-Language Library for Structured LLM Outputs**（project_doc）：Get structured, validated data from any LLM with Instructor - the 1 library for LLM data extraction. Supports 15+ providers OpenAI, Anthropic, Google, Ollama, DeepSeek in 6 languages. Built on type-safe schemas with automatic retries, streaming, and nested object support. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Installation**（project_doc）：Learn how to install Instructor and its dependencies using pip for Python 3.9+. Simple setup guide included. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/installation.md`\n- **Jobs**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/jobs.md`\n- **Instructor Mode Comparison Guide**（project_doc）：Compare different modes available in Instructor and understand when to use each 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/modes-comparison.md`\n- **Instructor Newsletter**（project_doc）：Get notified about AI tips, blog posts, and research. Stay informed with Instructor's latest features and community insights. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/newsletter.md`\n- **Repository Overview**（project_doc）：Learn the structure of the Instructor repository and the purpose of each major directory. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/repository-overview.md`\n- **Start Here: Instructor for Beginners**（project_doc）：A beginner-friendly introduction to using Instructor for structured outputs from LLMs 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/start-here.md`\n- **Why use Instructor?**（project_doc）：Discover why Instructor is the simplest, most reliable way to get structured outputs from LLMs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/why.md`\n- **Subscribe to our Newsletter for Updates and Tips**（project_doc）：Subscribe to our Newsletter for Updates and Tips 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/index.md`\n- **AI Engineer Keynote: Pydantic is all you need**（project_doc）：Explore insights on utilizing Pydantic for effective prompt engineering 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/aisummit-2023.md`\n- **Structured Outputs for Gemini now supported**（project_doc）：Introducing structured outputs for Gemini tool calling support in the 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/announcing-gemini-tool-calling-support.md`\n- **Announcing Responses API support**（project_doc）：Take advantage of OpenAI's latest offerings with the new responses API 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/announcing-instructor-responses-support.md`\n- **What is from provider ?**（project_doc）：Switch between different models and providers with a single string! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/announcing-unified-provider-interface.md`\n- **Why should I use prompt caching?**（project_doc）：Discover how prompt caching with Anthropic can improve response times 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/anthropic-prompt-caching.md`\n- **Using Anthropic's Web Search with Instructor for Real-Time Data**（project_doc）：Using Anthropic's Web Search with Instructor for Real-Time Data 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/anthropic-web-search-structured.md`\n- **Structured Outputs with Anthropic**（project_doc）：Learn how to integrate Anthropic's powerful language models into your projects using Instructor, with step-by-step guidance on installation, client setup, and creating structured outputs with Pydantic models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/anthropic.md`\n- **Bad Schemas could break your LLM Structured Outputs**（project_doc）：Discover how response models impact LLM performance, focusing on structured 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/bad-schemas-could-break-llms.md`\n- **Why Instructor is the Best Library for Structured LLM Outputs**（project_doc）：Discover how the Instructor library simplifies structured LLM outputs 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/best_framework.md`\n- **Advanced Caching Strategies for Python LLM Applications Validated & Tested ✅**（project_doc）：Master advanced Python caching strategies for LLM applications using functools, diskcache, and Redis. Learn how to optimize OpenAI API costs, reduce response times, and implement efficient caching for Pydantic models in production environments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/caching.md`\n- **Smarter Summaries w/ Finetuning GPT-3.5 and Chain of Density**（project_doc）：Learn to implement Chain of Density with GPT-3.5 for improved summarization, 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/chain-of-density.md`\n- **PDF Processing with Structured Outputs with Gemini**（project_doc）：Learn how to use Google's Gemini model with Instructor to process PDFs and extract structured information 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/chat-with-your-pdf-with-gemini.md`\n- **Verifying LLM Citations with Pydantic**（project_doc）：Explore how Pydantic enhances LLM citation verification, improving data 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/citations.md`\n- **Consistent Stories with GPT-4o**（project_doc）：Generating complex DAGS with gpt-4o 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/consistent-stories.md`\n- **Free course on Weights and Biases**（project_doc）：Discover a free one-hour course on Weights and Biases covering essential 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/course.md`\n- **Instructor Adopting Cursor Rules**（project_doc）：AI-assisted coding is changing how we use version control. Many developers now use what I call \"vibe coding\" - coding with AI help. This creates new challenges with Git. Today I'll share how we're using Cursor rules in Instructor to solve these problems. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/cursor-rules.md`\n- **Enhancing Python Functions with Instructor: A Guide to Fine-Tuning and Distillation**（project_doc）：Explore Instructor for fine-tuning language models with Python, simplifying 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/distilation-part1.md`\n- **Consistent Stories with GPT-4o**（project_doc）：Generating complex DAGS with gpt-4o 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/extract-model-looks.md`\n- **Why Image Metadata is useful**（project_doc）：Structured Extraction makes working with images easy, in this post we'll see how to use it to extract metadata from images 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/extracting-model-metadata.md`\n- **Simple Synthetic Data Generation**（project_doc）：Learn to generate synthetic data using Pydantic and OpenAI's models with 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/fake-data.md`\n- **Why Logfire is a perfect fit for FastAPI + Instructor**（project_doc）：Discover how Logfire enhances FastAPI applications with OpenTelemetry 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/full-fastapi-visibility.md`\n- **Eliminating Hallucinations with Structured Outputs using Gemini**（project_doc）：Generate accurate citations and eliminate hallucinations with structured outputs using Gemini. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/generating-pdf-citations.md`\n- **Generators and LLM Streaming**（project_doc）：Explore Python generators and their role in enhancing LLM streaming for 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/generator.md`\n- **Do I Still Need Instructor with Google's New OpenAI Integration?**（project_doc）：Learn why Instructor remains essential even with Google's new OpenAI-compatible client for Gemini 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/google-openai-client.md`\n- **Introducing structured outputs with Cerebras Inference**（project_doc）：Introducing structured outputs with Cerebras Inference 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/introducing-structured-outputs-with-cerebras-inference.md`\n- **Should I Be Using Structured Outputs?**（project_doc）：Explore the challenges of OpenAI's Structured Outputs and how 'instructor 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/introducing-structured-outputs.md`\n- **Generating Structured Output / JSON from LLMs**（project_doc）：Learn how Pydantic simplifies working with LLMs and structured JSON outputs 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/introduction.md`\n- **Instructor Proposal: Integrating Jinja Templating**（project_doc）：Explore the integration of Jinja templating in the Instructor for enhanced 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/jinja-proposal.md`\n- **Seamless Support with Langsmith**（project_doc）：Explore how LangSmith enhances OpenAI clients with seamless LLM observability 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/langsmith.md`\n- **Mastering Python asyncio.gather and asyncio.as completed for LLM Processing**（project_doc）：Master Python asyncio.gather and asyncio.as completed for efficient concurrent LLM processing with Instructor. Learn async programming patterns, rate limiting, and performance optimization for AI applications. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/learn-async.md`\n- **Building an LLM-based Reranker for your RAG pipeline**（project_doc）：Learn how to use Instructor and Pydantic to create an LLM-based reranker for improving search results relevance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/llm-as-reranker.md`\n- **Instructor Adopts llms.txt: Making Documentation AI-Friendly**（project_doc）：Instructor Adopts llms.txt: Making Documentation AI-Friendly 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/llms-txt-adoption.md`\n- **Instructor Now Supports llms.txt**（project_doc）：We've added automatic llms.txt generation to Instructor's documentation using the mkdocs-llmstxt https://github.com/pawamoy/mkdocs-llmstxt plugin. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/llms-txt-support.md`\n- **Introduction**（project_doc）：Explore Logfire, an observability platform to enhance application performance 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/logfire.md`\n- **London Stock Exchange Group Powers Market Surveillance with Instructor**（project_doc）：London Stock Exchange Group uses Instructor in production for AI-powered market surveillance, achieving 100% precision in detecting price-sensitive news 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/lseg-market-surveillance.md`\n- **Matching Language in Multilingual Summarization Tasks**（project_doc）：Explore techniques to ensure language models generate summaries that 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/matching-language.md`\n- **Why we migrated to uv**（project_doc）：How we migrated from poetry to uv 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/migrating-to-uv.md`\n- **Automating llms.txt Generation with mkdocs-llmstxt Plugin**（project_doc）：Automating llms.txt Generation with mkdocs-llmstxt Plugin 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/mkdocs-llmstxt-plugin-integration.md`\n- **Structured Outputs with Multimodal Gemini**（project_doc）：Learn how to use Google's Gemini model for multimodal structured extraction of YouTube videos, extracting structured recommendations for tourist destinations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/multimodal-gemini.md`\n- **Native Caching in Instructor v1.9.1: Zero-Configuration Performance Boost**（project_doc）：Instructor v1.9.1 introduces native caching support for all providers. Learn how to drastically reduce API costs and improve response times with built-in cache adapters. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/native_caching.md`\n- **Structured Output for Open Source and Local LLMs**（project_doc）：Discover how Instructor integrates with OpenAI and local LLMs for structured 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/open_source.md`\n- **OpenAI API Model Distillation with Instructor**（project_doc）：Learn how to use OpenAI's API Model Distillation with Instructor to create 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/openai-distilation-store.md`\n- **Audio Support in OpenAI's Chat Completions API**（project_doc）：Explore the new audio capabilities in OpenAI's Chat Completions API using the gpt-4o-audio-preview model. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/openai-multimodal.md`\n- **Building a Pairwise LLM Judge with Instructor and Pydantic**（project_doc）：Explore how to use Instructor and Pydantic to create a pairwise LLM judge for evaluating text relevance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/posts/pairwise-llm-judge.md`\n\n## 证据索引\n\n- 共索引 79 条证据。\n\n- **Contributing to Instructor**（documentation）：We welcome contributions to Instructor! This page covers the different ways you can help improve the library. 证据：`docs/contributing.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **Instructor: Structured Outputs for LLMs**（documentation）：Instructor: Structured Outputs for LLMs 证据：`README.md`\n- **Scripts Directory**（documentation）：This directory contains utility scripts for maintaining and improving the Instructor documentation and project structure. 证据：`scripts/README.md`\n- **Cursor Rules**（documentation）：Cursor rules are configuration files that help guide AI-assisted development in the Cursor IDE. They provide structured instructions for how the AI should behave in specific contexts or when working with certain types of files. 证据：`.cursor/rules/readme.md`\n- **Batch API Examples**（documentation）：This directory contains examples and test scripts for Instructor's batch processing capabilities, including both traditional file-based and new in-memory processing. 证据：`examples/batch_api/README.md`\n- **Instructor Caching Prototype**（documentation）：This example demonstrates the new built-in caching functionality in Instructor. 证据：`examples/caching_prototype/README.md`\n- **Introduction**（documentation）：This is a simple example which shows how to perform Chain Of Density summarization using GPT-3.5 and utilise the generated output to fine-tune a 3.5 model for production usage. All of our data referenced in this file is located here https://huggingface.co/datasets/ivanleomk/gpt4-chain-of-density on hugging face 证据：`examples/chain-of-density/Readme.md`\n- **Citation with Extraction**（documentation）：This repository contains a FastAPI application that uses GPT-4 to answer questions based on a given context and extract relevant facts with correct and exact citations. The extracted facts are returned as JSON events using Server-Sent Events SSE . 证据：`examples/citation_with_extraction/README.md`\n- **FastAPI Code Generator**（documentation）：Generates FastAPI application code from API path, task name, JSON schema path, and Jinja2 prompt template. Also creates a models.py file for Pydantic models. 证据：`examples/codegen-from-schema/readme.md`\n- **What to Expect**（documentation）：What to Expect This script demonstrates how to use the Instructor library for fine-tuning a Python function that performs three-digit multiplication. It uses Pydantic for type validation and logging features to generate a fine-tuning dataset. 证据：`examples/distilations/readme.md`\n- **Instructor Hooks Example**（documentation）：This example demonstrates how to use the Hooks system in the Instructor library to monitor, log, and debug your LLM interactions. 证据：`examples/hooks/README.md`\n- **Instructions**（documentation）：1. Create a virtual environment and install all of the packages inside requirements.txt 证据：`examples/logfire-fastapi/Readme.md`\n- **Read first to correctly work with the provided examples**（documentation）：Read first to correctly work with the provided examples 证据：`examples/open_source_examples/README.md`\n- **Using llm validator with OpenAI's GPT-3.5 Turbo and Pydantic for Text Validation with Output Examples**（documentation）：Using llm validator with OpenAI's GPT-3.5 Turbo and Pydantic for Text Validation with Output Examples 证据：`examples/validators/readme.md`\n- **Providers Directory Structure**（documentation）：This directory contains implementations for all supported LLM providers in the instructor library. 证据：`instructor/providers/README.md`\n- **Contributing to Instructor**（documentation）：Thank you for considering contributing to Instructor! This document provides guidelines and instructions to help you contribute effectively. 证据：`CONTRIBUTING.md`\n- **Core Provider Tests**（documentation）：This directory contains unified tests that run across all core providers : OpenAI, Anthropic, Google Gemini , Cohere, xAI, Mistral, Cerebras, Fireworks, Writer, and Perplexity. 证据：`tests/llm/test_core_providers/README.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **AGENT.md - Documentation**（documentation）：Commands - Serve docs locally: uv run mkdocs serve - Build docs: ./build mkdocs.sh or uv run mkdocs build - Install doc deps: uv pip install -e \". docs \" - Test examples: uv run pytest docs/ --examples 证据：`docs/AGENT.md`\n- **API Docstring Quality Assessment**（documentation）：This document assesses the quality and completeness of docstrings for all API items referenced in the expanded API documentation. 证据：`docs/api-docstring-assessment.md`\n- **API Reference**（documentation）：Core modes are the recommended default. Legacy provider-specific modes still work but are deprecated and will show warnings. See the Mode Migration Guide concepts/mode-migration.md for details. 证据：`docs/api.md`\n- **Architecture Overview**（documentation）：This page explains the core execution flow and where to plug in or debug. It highlights the minimal sync/async code paths and how streaming, partial, and parallel modes integrate. 证据：`docs/architecture.md`\n- **Debugging**（documentation）：This guide shows how to quickly inspect inputs/outputs, capture retries, and reproduce failures when working with Instructor. It focuses on practical techniques using hooks, logging, and exception data. 证据：`docs/debugging.md`\n- **Frequently Asked Questions**（documentation）：This page answers common questions about using Instructor with various LLM providers. 证据：`docs/faq.md`\n- **Getting Started with Instructor**（documentation）：This guide will walk you through the basics of using Instructor to extract structured data from language models. By the end, you'll understand how to: 证据：`docs/getting-started.md`\n- **Getting help with Instructor**（documentation）：If you need help getting started with Instructor or with advanced usage, the following sources may be useful. 证据：`docs/help.md`\n- **Instructor: Top Multi-Language Library for Structured LLM Outputs**（documentation）：Instructor: Top Multi-Language Library for Structured LLM Outputs 证据：`docs/index.md`\n- **Installation**（documentation）：- openai https://pypi.org/project/openai/ : OpenAI's Python client. - typer https://pypi.org/project/typer/ : Build great CLIs. Easy to code. Based on Python type hints. - docstring-parser https://pypi.org/project/docstring-parser/ : A parser for Python docstrings, to improve the experience of working with docstrings in jsonschema. - pydantic https://pypi.org/project/pydantic/ : Data validation and settings management using python type annotations. 证据：`docs/installation.md`\n- **Instructor Mode Comparison Guide**（documentation）：Instructor uses core modes that work across providers. Provider-specific modes still work, but they are deprecated and will show warnings. 证据：`docs/modes-comparison.md`\n- **Instructor Newsletter**（documentation）：If you want to be notified of tips, new blog posts, and research, subscribe to our newsletter. Here's what you can expect: 证据：`docs/newsletter.md`\n- **Repository Overview**（documentation）：This page explains the layout of the Instructor codebase and what each key directory contains. 证据：`docs/repository-overview.md`\n- **Start Here: Instructor for Beginners**（documentation）：Start Here: Instructor for Beginners 证据：`docs/start-here.md`\n- **Why use Instructor?**（documentation）：You've built something with an LLM, but 15% of the time it returns garbage. Parsing JSON is a nightmare. Different providers have different APIs. There has to be a better way. 证据：`docs/why.md`\n- **Subscribe to our Newsletter for Updates and Tips**（documentation）：Subscribe to our Newsletter for Updates and Tips 证据：`docs/blog/index.md`\n- **AI Engineer Keynote: Pydantic is all you need**（documentation）：AI Engineer Keynote: Pydantic is all you need 证据：`docs/blog/posts/aisummit-2023.md`\n- **Structured Outputs for Gemini now supported**（documentation）：Structured Outputs for Gemini now supported 证据：`docs/blog/posts/announcing-gemini-tool-calling-support.md`\n- **Announcing Responses API support**（documentation）：We're excited to announce Instructor's integration with OpenAI's new Responses API. This integration brings a more streamlined approach to working with structured outputs from OpenAI models. Let's see what makes this integration special and how it can improve your LLM applications. 证据：`docs/blog/posts/announcing-instructor-responses-support.md`\n- **What is from provider ?**（documentation）：We are pleased to introduce a significant enhancement to Instructor: the from provider function. While Instructor has always focused on providing robust structured outputs, we've observed that many users work with multiple LLM providers. This often involves repetitive setup for each client. 证据：`docs/blog/posts/announcing-unified-provider-interface.md`\n- **Why should I use prompt caching?**（documentation）：Developers often face two key challenges when working with large context - Slow response times and high costs. This is especially true when we're making multiple of these calls over time, severely impacting the cost and latency of our applications. With Anthropic's new prompt caching feature, we can easily solve both of these issues. 证据：`docs/blog/posts/anthropic-prompt-caching.md`\n- **Using Anthropic's Web Search with Instructor for Real-Time Data**（documentation）：Using Anthropic's Web Search with Instructor for Real-Time Data 证据：`docs/blog/posts/anthropic-web-search-structured.md`\n- **Structured Outputs with Anthropic**（documentation）：A special shoutout to Shreya https://twitter.com/shreyaw for her contributions to the anthropic support. As of now, all features are operational with the exception of streaming support. 证据：`docs/blog/posts/anthropic.md`\n- **Bad Schemas could break your LLM Structured Outputs**（documentation）：Bad Schemas could break your LLM Structured Outputs 证据：`docs/blog/posts/bad-schemas-could-break-llms.md`\n- **Why Instructor is the Best Library for Structured LLM Outputs**（documentation）：Why Instructor is the Best Library for Structured LLM Outputs 证据：`docs/blog/posts/best_framework.md`\n- **Advanced Caching Strategies for Python LLM Applications Validated & Tested ✅**（documentation）：Advanced Caching Strategies for Python LLM Applications Validated & Tested ✅ 证据：`docs/blog/posts/caching.md`\n- **Smarter Summaries w/ Finetuning GPT-3.5 and Chain of Density**（documentation）：Smarter Summaries w/ Finetuning GPT-3.5 and Chain of Density 证据：`docs/blog/posts/chain-of-density.md`\n- **PDF Processing with Structured Outputs with Gemini**（documentation）：PDF Processing with Structured Outputs with Gemini 证据：`docs/blog/posts/chat-with-your-pdf-with-gemini.md`\n- **Verifying LLM Citations with Pydantic**（documentation）：Verifying LLM Citations with Pydantic 证据：`docs/blog/posts/citations.md`\n- **Consistent Stories with GPT-4o**（documentation）：Language Models struggle to generate consistent graphs that have a large number of nodes. Often times, this is because the graph itself is too large for the model to handle. This causes the model to generate inconsistent graphs that have invalid and disconnected nodes among other issues. 证据：`docs/blog/posts/consistent-stories.md`\n- **Free course on Weights and Biases**（documentation）：I just released a free course on wits and biases. It goes over the material from tutorial ../../tutorials/1-introduction.ipynb . Check it out at wandb.courses https://www.wandb.courses/courses/steering-language-models its free and open to everyone and just under an hour long! 证据：`docs/blog/posts/course.md`\n- **Instructor Adopting Cursor Rules**（documentation）：AI-assisted coding is changing how we use version control. Many developers now use what I call \"vibe coding\" - coding with AI help. This creates new challenges with Git. Today I'll share how we're using Cursor rules in Instructor to solve these problems. 证据：`docs/blog/posts/cursor-rules.md`\n- **Enhancing Python Functions with Instructor: A Guide to Fine-Tuning and Distillation**（documentation）：Enhancing Python Functions with Instructor: A Guide to Fine-Tuning and Distillation 证据：`docs/blog/posts/distilation-part1.md`\n- **Consistent Stories with GPT-4o**（documentation）：Language Models struggle to generate consistent graphs that have a large number of nodes. Often times, this is because the graph itself is too large for the model to handle. This causes the model to generate inconsistent graphs that have invalid and disconnected nodes among other issues. 证据：`docs/blog/posts/extract-model-looks.md`\n- **Why Image Metadata is useful**（documentation）：Multimodal Language Models like gpt-4o excel at processing multimodal, enabling us to extract rich, structured metadata from images. 证据：`docs/blog/posts/extracting-model-metadata.md`\n- **Simple Synthetic Data Generation**（documentation）：What that people have been using instructor for is to generate synthetic data rather than extracting data itself. We can even use the J-Schemo extra fields to give specific examples to control how we generate data. 证据：`docs/blog/posts/fake-data.md`\n- **Why Logfire is a perfect fit for FastAPI + Instructor**（documentation）：Why Logfire is a perfect fit for FastAPI + Instructor 证据：`docs/blog/posts/full-fastapi-visibility.md`\n- **Eliminating Hallucinations with Structured Outputs using Gemini**（documentation）：Eliminating Hallucinations with Structured Outputs using Gemini 证据：`docs/blog/posts/generating-pdf-citations.md`\n- **Generators and LLM Streaming**（documentation）：Latency is crucial, especially in eCommerce and newer chat applications like ChatGPT. Streaming is the solution that enables us to enhance the user experience without the need for faster response times. 证据：`docs/blog/posts/generator.md`\n- **Do I Still Need Instructor with Google's New OpenAI Integration?**（documentation）：Do I Still Need Instructor with Google's New OpenAI Integration? 证据：`docs/blog/posts/google-openai-client.md`\n- **Introducing structured outputs with Cerebras Inference**（documentation）：Introducing structured outputs with Cerebras Inference 证据：`docs/blog/posts/introducing-structured-outputs-with-cerebras-inference.md`\n- 其余 19 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/contributing.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/contributing.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, instructor/__init__.py, mkdocs.yml\n- **安装指南**：importance `high`\n - source_paths: pyproject.toml, requirements.txt, docs/installation.md\n- **快速开始**：importance `high`\n - source_paths: examples/simple-extraction/user.py, docs/getting-started.md, docs/learning/getting_started/first_extraction.md\n- **系统架构**：importance `high`\n - source_paths: instructor/core/client.py, instructor/processing/response.py, instructor/processing/function_calls.py, instructor/processing/validators.py, docs/architecture.md\n- **提供商集成**：importance `high`\n - source_paths: instructor/providers/__init__.py, instructor/providers/anthropic/__init__.py, instructor/providers/gemini/__init__.py, instructor/providers/README.md, docs/integrations/index.md\n- **响应模型**：importance `high`\n - source_paths: instructor/processing/schema.py, docs/concepts/models.md, docs/learning/getting_started/response_models.md, examples/simple-extraction/maybe_user.py\n- **验证机制**：importance `high`\n - source_paths: instructor/dsl/validators.py, instructor/validation/llm_validators.py, instructor/core/retry.py, docs/concepts/validation.md, docs/concepts/reask_validation.md\n- **流式输出**：importance `medium`\n - source_paths: instructor/dsl/partial.py, instructor/dsl/iterable.py, docs/concepts/partial.md, docs/concepts/iterable.md, examples/partial_streaming/run.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `5e8e2d57e791ed505c9637c0e215b10a5441b66a`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `requirements.txt`, `docs/why.md`, `docs/architecture.md`, `docs/contributing.md`, `docs/newsletter.md`, `docs/debugging.md`, `docs/index.md`, `docs/api.md`, `docs/repository-overview.md`, `docs/getting-started.md`, `docs/api-docstring-assessment.md`, `docs/installation.md`, `docs/modes-comparison.md`, `docs/start-here.md`, `docs/faq.md`, `docs/help.md`, `docs/jobs.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Documentation (at least Google-related) is an outdated mess.\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess.\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：v1.13.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v1.12.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v1.14.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v1.14.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.14.4\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.15.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v1.14.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：567-labs/instructor\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Documentation (at least Google-related) is an outdated mess.（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v1.13.0（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.12.0（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.14.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.14.3（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/567-labs/instructor 项目说明书\n\n生成时间：2026-05-13 06:51:33 UTC\n\n## 目录\n\n- [项目概览](#page-overview)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [提供商集成](#page-providers)\n- [响应模型](#page-response-models)\n- [验证机制](#page-validation)\n- [流式输出](#page-streaming)\n- [批处理](#page-batch-processing)\n- [钩子系统](#page-hooks)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n- [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)\n- [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md)\n- [examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md)\n- [examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md)\n- [examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)\n- [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)\n \n\n# 项目概览\n\n## 什么是 Instructor\n\nInstructor 是一个用于从大语言模型（LLM）获取**结构化输出**的 Python 库。它通过将 Pydantic 模型与 LLM API 结合，使模型输出自动经过验证和类型转换，开发者无需编写繁琐的 JSON 解析和手动验证代码。\n\n核心价值在于简化 LLM 应用开发中的数据提取和验证流程，让开发者专注于业务逻辑而非底层实现。\n\n资料来源：[README.md:1-30]()\n\n## 核心功能特性\n\n### 多provider统一API\n\nInstructor 支持多种主流 LLM 服务商，通过统一的接口访问不同 provider：\n\n| Provider | 模型示例 | 特性 |\n|----------|----------|------|\n| OpenAI | gpt-4o, gpt-4-turbo, gpt-3.5-turbo | 参考实现 |\n| Anthropic | claude-3-5-sonnet, claude-3-opus | Beta API支持 |\n| Google | gemini-pro, gemini-2.0-flash | 模拟模式可用 |\n| Ollama | llama3.2 (本地部署) | 支持本地运行 |\n| Groq | llama-3.1-8b-instant | 高速推理 |\n\n所有 provider 使用相同的 API 调用方式，切换时只需修改 provider 名称和模型名称。\n\n资料来源：[README.md:50-80]()\n\n### 响应模型与自动验证\n\n使用 `response_model` 参数指定 Pydantic 模型作为输出格式：\n\n```python\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n name: str\n age: int\n\nclient = instructor.from_provider(\"openai/gpt-4o\")\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\nInstructor 自动处理 JSON 解析、类型转换和验证失败时的重试逻辑。\n\n资料来源：[README.md:35-45]()\n\n### 自动重试机制\n\n当验证失败时，Instructor 会自动将错误信息反馈给 LLM 并重试请求：\n\n```python\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n\n# 自动重试直到验证通过或达到最大重试次数\nuser = client.chat.completions.create(\n response_model=User,\n max_retries=2,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n资料来源：[README.md:90-110]()\n\n## 系统架构\n\n### 组件结构\n\nInstructor 的代码组织结构如下：\n\n```\ninstructor/\n├── providers/ # LLM provider 适配器\n│ ├── anthropic/ # Anthropic 实现\n│ ├── openai/ # OpenAI 实现\n│ ├── gemini/ # Google Gemini 实现\n│ ├── groq/ # Groq 实现\n│ ├── vertexai/ # Vertex AI 实现\n│ └── ... # 其他 provider\n└── __init__.py # 核心导出\n```\n\n每个 provider 目录下包含：\n- `__init__.py` - 模块初始化\n- `client.py` - provider 特定的客户端工厂函数（可选）\n- `utils.py` - provider 特定的响应处理工具（可选）\n\n资料来源：[instructor/providers/README.md:1-25]()\n\n### Provider 实现模式\n\n| 类型 | Provider 列表 | 说明 |\n|------|---------------|------|\n| 完整实现 | anthropic, bedrock, gemini, mistral 等 | 包含 client.py 和 utils.py |\n| 简化实现 | genai, groq, vertexai | 仅 client.py，使用核心处理逻辑 |\n| 特殊实现 | openai | 仅 utils.py，from_openai() 在核心模块定义 |\n\nOpenAI 作为参考实现，其工厂函数定义在 `core/client.py` 中，其他 provider 基于此模式扩展。\n\n资料来源：[instructor/providers/README.md:25-40]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[创建 Client] --> B[调用 chat.completions.create]\n B --> C[发送请求到 LLM]\n C --> D[接收响应]\n D --> E[JSON 解析]\n E --> F[Pydantic 模型验证]\n F --> G{验证通过?}\n G -->|是| H[返回结构化对象]\n G -->|否| I[提取错误信息]\n I --> J[重试请求]\n J --> C\n J --> K[达到最大重试]\n K --> L[抛出异常]\n```\n\n## 高级功能\n\n### 验证器（Validators）\n\nInstructor 支持多种验证方式，确保 LLM 输出符合预期：\n\n#### Pydantic 字段验证器\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n```\n\n#### LLM 验证器\n\n使用 `llm_validator` 对输出内容进行语义级验证：\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BeforeValidator\n\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"don't say objectionable things\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md:1-80]()\n\n### 批处理 API\n\nInstructor 提供统一的批处理接口，支持多个 provider：\n\n```bash\n# 使用 CLI 创建批处理任务\ninstructor batch create \\\n --messages-file messages.jsonl \\\n --model \"openai/gpt-4o-mini\" \\\n --response-model \"User\"\n```\n\n支持的功能：\n- 批量消息创建\n- 批处理状态查询\n- 结果文件导出\n- Provider 自动检测\n\n支持的批处理模型：\n- OpenAI: gpt-4o-mini, gpt-4o, gpt-4-turbo\n- Anthropic: claude-3-5-sonnet, claude-3-opus, claude-3-haiku\n- Google: gemini-2.0-flash-001, gemini-pro\n\n资料来源：[examples/batch_api/README.md:1-60]()\n\n### 钩子系统（Hooks）\n\nInstructor 的钩子系统允许在请求生命周期中插入自定义逻辑：\n\n```mermaid\ngraph LR\n A[请求开始] --> B[on_request 钩子]\n B --> C[LLM 调用]\n C --> D[on_response 钩子]\n D --> E{验证成功?}\n E -->|是| F[on_success 钩子]\n E -->|否| G[on_retry 钩子]\n G --> C\n F --> H[返回结果]\n E -->|最终失败| I[on_failure 钩子]\n I --> J[抛出异常]\n```\n\n支持的钩子事件：\n| 钩子类型 | 触发时机 | 典型用途 |\n|----------|----------|----------|\n| on_request | 请求发送前 | 添加日志、修改参数 |\n| on_response | 收到响应后 | 记录 token 使用 |\n| on_success | 验证通过后 | 统计指标 |\n| on_retry | 重试前 | 记录重试原因 |\n| on_failure | 最终失败后 | 错误告警 |\n\n资料来源：[examples/hooks/README.md:1-40]()\n\n### 模型蒸馏（Distillation）\n\nInstructor 支持使用日志功能生成微调数据集：\n\n```python\n# 运行脚本生成训练数据\npython three_digit_mul.py\n\n# 创建微调任务\ninstructor jobs create-from-file math_finetunes.jsonl\n\n# 可选：使用验证集\ninstructor jobs create-from-file math_finetunes.jsonl \\\n --n-epochs 4 \\\n --validation-file math_finetunes_val.jsonl\n```\n\n此功能允许开发者用 Instructor 生成高质量的训练数据，用于微调更小、更快的模型。\n\n资料来源：[examples/distilations/readme.md:1-50]()\n\n### 引用提取（Citations）\n\nInstructor 支持从上下文中提取引用并标注来源：\n\n```bash\ncurl -X POST 'http://localhost:8000/extract' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer ' \\\n -d '{\n \"context\": \"Jason Liu 出生于中国...\",\n \"query\": \"作者在哪里出生?\"\n }'\n```\n\n返回格式包含：\n- `body`: 提取的事实\n- `spans`: 原文中的位置\n- `citation`: 引用的文本片段\n\n资料来源：[examples/citation_with_extraction/README.md:1-50]()\n\n## 安装与配置\n\n### 快速安装\n\n```bash\npip install instructor\n```\n\n或使用其他包管理器：\n\n```bash\nuv add instructor\npoetry add instructor\n```\n\n### 初始化客户端\n\n```python\n# 基本用法（需设置环境变量）\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# 直接传入 API Key\nclient = instructor.from_provider(\n \"anthropic/claude-3-5-sonnet\",\n api_key=\"sk-ant-...\"\n)\n\n# 使用任意支持格式\nclient = instructor.from_provider(\"groq/llama-3.1-8b-instant\")\n```\n\n资料来源：[README.md:40-70]()\n\n## 与传统方式对比\n\n```mermaid\ngraph LR\n subgraph \"传统方式\"\n A1[手动定义 schema] --> A2[调用 API]\n A2 --> A3[解析 JSON]\n A3 --> A4[手动验证数据]\n A4 --> A5[处理边界情况]\n end\n\n subgraph \"使用 Instructor\"\n B1[定义 Pydantic 模型] --> B2[调用 create 方法]\n B2 --> B3[自动验证返回]\n B3 --> B4[获得类型安全对象]\n end\n\n A5 -.->|繁琐| B4\n```\n\n| 方面 | 传统方式 | Instructor |\n|------|----------|------------|\n| 代码量 | 多 | 少 |\n| 错误处理 | 手动 | 自动重试 |\n| 类型安全 | 无 | Pydantic 保证 |\n| Provider 切换 | 需重写 | 改参数即可 |\n| 验证逻辑 | 手动编写 | 声明式定义 |\n\n## 适用场景\n\nInstructor 适用于以下场景：\n\n1. **数据提取**：从非结构化文本中提取结构化数据\n2. **信息检索**：基于上下文的问答系统\n3. **内容审核**：验证 LLM 输出符合规范\n4. **批量处理**：大规模自动化数据处理任务\n5. **模型微调**：生成高质量训练数据集\n6. **多Provider切换**：统一管理不同 LLM 服务商\n\n## 技术栈\n\n- **Python**: 3.9+\n- **Pydantic**: 数据验证和类型转换\n- **OpenAI SDK**: API 通信\n- **Tenacity**: 重试逻辑\n\nInstructor 设计为轻量级依赖，核心功能仅需 Pydantic 即可运行。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目概览](#page-overview), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n- [pyproject.toml](https://github.com/567-labs/instructor/blob/main/pyproject.toml)\n- [scripts/README.md](https://github.com/567-labs/instructor/blob/main/scripts/README.md)\n- [examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md)\n- [examples/batch_api/README.md](https://github.com/567-labs/instructor/blob/main/examples/batch_api/README.md)\n \n\n# 安装指南\n\n本页面详细介绍 Instructor 库的安装方法、环境配置以及不同平台的依赖要求。Instructor 是一个支持多种 LLM 提供商的 Python 库，专注于结构化输出和响应验证。\n\n## 安装方式\n\nInstructor 提供了多种安装方式，开发者可根据项目需求选择最适合的方法。\n\n### 使用 pip 安装\n\n最简捷的安装方式是通过 Python 包管理器 pip 安装稳定版本：\n\n```bash\npip install instructor\n```\n\n### 使用 uv 安装\n\n对于使用 uv 作为包管理器的项目：\n\n```bash\nuv add instructor\n```\n\n### 使用 Poetry 安装\n\n使用 Poetry 进行依赖管理的项目：\n\n```bash\npoetry add instructor\n```\n\n资料来源：[README.md:1-30](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 环境要求\n\nInstructor 对运行环境有以下基本要求：\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Python | 3.9+ | 推荐使用 Python 3.9 或更高版本 |\n| Pydantic | 2.x | 用于数据验证和模型定义 |\n| LLM 提供商 SDK | 最新版本 | 根据使用的提供商安装相应 SDK |\n\n### 核心依赖\n\nInstructor 的核心功能依赖于以下 Python 包：\n\n```toml\n# pyproject.toml 中的核心依赖\ndependencies = [\n \"pydantic>=2.0\",\n \"anyio>=4.0\",\n]\n```\n\n资料来源：[pyproject.toml](https://github.com/567-labs/instructor/blob/main/pyproject.toml)\n\n## LLM 提供商配置\n\nInstructor 支持多个主流 LLM 提供商，每个提供商需要单独配置 API 密钥。\n\n### 支持的提供商\n\n| 提供商 | 模型示例 | 必需环境变量 |\n|--------|----------|--------------|\n| OpenAI | gpt-4o, gpt-4o-mini | `OPENAI_API_KEY` |\n| Anthropic | claude-3-5-sonnet | `ANTHROPIC_API_KEY` |\n| Google | gemini-pro, gemini-2.0-flash | `GOOGLE_API_KEY` |\n| Ollama | llama3.2 (本地部署) | 无需 API 密钥 |\n| Groq | llama-3.1-8b-instant | `GROQ_API_KEY` |\n\n### 初始化客户端\n\n使用 `from_provider()` 方法创建客户端：\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n```\n\n### 直接传递 API 密钥\n\n在某些场景下，可能需要直接传递 API 密钥而不依赖环境变量：\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\", api_key=\"sk-ant-...\")\n\n# Groq\nclient = instructor.from_provider(\"groq/llama-3.1-8b-instant\", api_key=\"gsk_...\")\n```\n\n资料来源：[README.md:50-80](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 依赖安装流程\n\n### 基本安装步骤\n\n1. **创建虚拟环境（推荐）**\n\n```bash\npython -m venv venv\nsource venv/bin/activate # Linux/macOS\nvenv\\Scripts\\activate # Windows\n```\n\n2. **安装 Instructor**\n\n```bash\npip install instructor\n```\n\n3. **安装提供商 SDK（根据需要）**\n\n```bash\n# OpenAI\npip install openai\n\n# Anthropic\npip install anthropic\n\n# Google Gemini\npip install google-generativeai\n```\n\n### 示例项目依赖安装\n\n某些示例项目可能需要额外依赖：\n\n```bash\n# 示例：citation_with_extraction 项目\npip install -r requirements.txt\n```\n\n资料来源：[examples/citation_with_extraction/README.md](https://github.com/567-labs/instructor/blob/main/examples/citation_with_extraction/README.md)\n\n## 高级功能依赖\n\n### 批处理功能\n\n使用批处理 API 时需要安装以下依赖：\n\n| 依赖包 | 用途 |\n|--------|------|\n| openai | OpenAI API 客户端 |\n| typer | CLI 命令行界面 |\n| rich | 终端美化输出 |\n| tenacity | 重试机制 |\n| pyyaml | YAML 配置文件处理 |\n\n安装命令：\n\n```bash\nuv add openai typer rich tenacity pyyaml\n```\n\n资料来源：[scripts/README.md](https://github.com/567-labs/instructor/blob/main/scripts/README.md)\n\n### 微调功能\n\n进行模型微调时需要：\n\n1. 配置日志记录功能\n2. 准备训练数据格式（JSONL）\n3. 使用 Instructor CLI 提交微调任务\n\n```bash\ninstructor jobs create-from-file math_finetunes.jsonl\n```\n\n资料来源：[examples/distilations/readme.md](https://github.com/567-labs/instructor/blob/main/examples/distilations/readme.md)\n\n## 验证安装\n\n安装完成后，可通过以下方式验证 Instructor 是否正确安装：\n\n```python\nimport instructor\n\n# 验证版本\nprint(instructor.__version__)\n\n# 测试基本功能\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\nprint(\"Instructor 安装成功！\")\n```\n\n## 安装问题排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| ImportError | 未正确安装或虚拟环境未激活 | 重新安装并检查 Python 环境 |\n| API 密钥错误 | 环境变量未设置或值错误 | 设置正确的 API 密钥 |\n| 版本不兼容 | Python 版本过低 | 升级到 Python 3.9+ |\n\n### 验证 API 密钥\n\n确保 API 密钥已正确配置：\n\n```bash\n# 检查环境变量（Linux/macOS）\necho $OPENAI_API_KEY\n\n# 检查环境变量（Windows）\necho %OPENAI_API_KEY%\n```\n\n## 项目结构与模块\n\nInstructor 采用模块化设计，主要结构如下：\n\n```\ninstructor/\n├── providers/ # LLM 提供商实现\n│ ├── openai/ # OpenAI 提供商\n│ ├── anthropic/ # Anthropic 提供商\n│ ├── gemini/ # Google Gemini 提供商\n│ └── ...\n├── core/ # 核心功能模块\n└── ...\n```\n\n每个提供商都有独立的子模块，包含初始化工厂函数和响应处理工具：\n\n```\nproviders/\n├── provider_name/\n│ ├── __init__.py\n│ ├── client.py # 提供商特定客户端\n│ └── utils.py # 响应处理工具\n```\n\n资料来源：[instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)\n\n## 快速开始工作流\n\n以下流程图展示了从安装到首次使用的完整过程：\n\n```mermaid\ngraph TD\n A[开始] --> B[安装 Instructor]\n B --> C{选择提供商}\n C -->|OpenAI| D[设置 OPENAI_API_KEY]\n C -->|Anthropic| E[设置 ANTHROPIC_API_KEY]\n C -->|Google| F[设置 GOOGLE_API_KEY]\n C -->|Ollama| G[配置本地 Ollama]\n D --> H[创建客户端]\n E --> H\n F --> H\n G --> H\n H --> I[定义响应模型]\n I --> J[调用 API]\n J --> K[获取结构化输出]\n```\n\n## 许可证\n\nInstructor 采用 MIT 许可证开源发布，可自由使用、修改和分发。\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/LICENSE)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概览](#page-overview), [响应模型](#page-response-models), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/simple-extraction/user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/user.py)\n- [docs/getting-started.md](https://github.com/567-labs/instructor/blob/main/docs/getting-started.md)\n- [docs/learning/getting_started/first_extraction.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/first_extraction.md)\n- [README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n- [examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)\n \n\n# 快速开始\n\n本页面为 Instructor 项目的入门指南，旨在帮助开发者快速了解并上手使用 Instructor 进行结构化数据提取。Instructor 是一个简化大语言模型（LLM）响应的 Python 库，它与 Pydantic 深度集成，让开发者能够轻松地从 LLM 响应中提取类型安全的结构化数据。\n\n## 什么是 Instructor\n\nInstructor 是 567 Labs 开发的一个开源库，它通过与 Pydantic 的深度集成，将 LLM 的非结构化输出转换为结构化的 Python 对象。与传统的工具调用方式相比，Instructor 提供了更简洁的 API 和自动验证机制。\n\n传统的 LLM 调用需要手动解析 tool_call 中的 arguments，手动进行 JSON 解析和验证，而使用 Instructor 只需要定义 Pydantic 模型并调用 `client.create()` 即可获得完整的类型安全验证结果。\n\n## 安装 Instructor\n\nInstructor 支持多种安装方式，开发者可以根据项目需求选择合适的方式。\n\n### 使用 pip 安装\n\n```bash\npip install instructor\n```\n\n### 使用包管理器安装\n\nInstructor 也支持其他主流 Python 包管理器：\n\n```bash\n# 使用 uv\nuv add instructor\n\n# 使用 poetry\npoetry add instructor\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 基本概念\n\n### 核心组件\n\nInstructor 的核心架构包含以下几个关键组件：\n\n| 组件 | 说明 |\n|------|------|\n| `Instructor` | 主客户端类，负责与 LLM 提供商交互 |\n| `response_model` | Pydantic 模型，用于定义期望的输出结构 |\n| `from_provider()` | 工厂函数，用于创建 Instructor 客户端实例 |\n\n### 支持的 LLM 提供商\n\nInstructor 与多个主流 LLM 提供商兼容，包括 OpenAI、Anthropic、Google、Ollama 等。\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 创建客户端\n\n在使用 Instructor 之前，需要先创建客户端实例。Instructor 提供了 `from_provider()` 工厂函数来简化这一过程。\n\n### 基本用法\n\n```python\nimport instructor\nfrom pydantic import BaseModel\n\n# 从 OpenAI 创建客户端\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\n```\n\n### 支持的提供商示例\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n\n# 直接传入 API Key\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 第一个提取示例\n\n本节通过一个简单的用户信息提取示例，帮助开发者快速上手 Instructor。\n\n### 定义数据模型\n\n首先，使用 Pydantic 定义要提取的数据结构：\n\n```python\nfrom pydantic import BaseModel\n\n\nclass User(BaseModel):\n name: str\n age: int\n email: str\n address: str = None # 可选字段\n```\n\n资料来源：[examples/simple-extraction/user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/user.py)\n\n### 执行提取\n\n定义好模型后，即可使用 Instructor 进行结构化数据提取：\n\n```python\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\n\n# 定义提取模型\nclass User(BaseModel):\n name: str\n age: int\n email: str\n address: str = None\n\n\n# 提取数据\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n response_model=User,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"张三, 30岁, 邮箱是 zhangsan@example.com\"\n }\n ],\n)\n\nprint(user)\n# User(name='张三', age=30, email='zhangsan@example.com', address=None)\n```\n\n资料来源：[docs/getting-started.md](https://github.com/567-labs/instructor/blob/main/docs/getting-started.md)\n\n## 工作流程\n\nInstructor 的数据提取流程如下：\n\n```mermaid\ngraph TD\n A[定义 Pydantic 模型] --> B[创建 Instructor 客户端]\n B --> C[调用 client.chat.completions.create]\n C --> D[发送请求到 LLM]\n D --> E[接收 LLM 响应]\n E --> F[Pydantic 模型验证]\n F --> G{验证是否通过}\n G -->|通过| H[返回结构化对象]\n G -->|失败| I[自动重试并返回错误]\n I --> C\n```\n\n### 流程说明\n\n1. **定义模型**：开发者定义 Pydantic 模型来描述期望的输出结构\n2. **创建客户端**：使用 `from_provider()` 创建与指定 LLM 提供商的连接\n3. **调用 API**：使用 `client.chat.completions.create()` 发送请求\n4. **自动验证**：Instructor 自动对 LLM 输出进行 Pydantic 验证\n5. **自动重试**：如果验证失败，Instructor 会自动重试并将错误信息反馈给 LLM\n\n资料来源：[docs/learning/getting_started/first_extraction.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/first_extraction.md)\n\n## 自动重试机制\n\nInstructor 内置了强大的自动重试机制。当 Pydantic 验证失败时，系统会自动重试并向 LLM 传递错误信息。\n\n### 添加自定义验证\n\n可以使用 Pydantic 的 `field_validator` 装饰器添加自定义验证逻辑：\n\n```python\nfrom pydantic import BaseModel, field_validator\n\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n\n\n# 当年龄为负数时，Instructor 会自动重试\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"用户年龄为-5岁\"}],\n)\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n### LLM 验证器\n\n除了传统的字段验证器，Instructor 还支持使用 `llm_validator` 进行基于 LLM 的文本验证：\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BaseModel, BeforeValidator\nfrom instructor import llm_validator\n\n\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"不要说不恰当的话\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md](https://github.com/567-labs/instructor/blob/main/examples/validators/readme.md)\n\n## 嵌套对象处理\n\nInstructor 支持自动处理嵌套对象的提取，无需额外配置。\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Optional\n\n\nclass Address(BaseModel):\n street: str\n city: str\n country: str\n\n\nclass User(BaseModel):\n name: str\n email: str\n address: Optional[Address] = None\n\n\nuser = client.chat.completions.create(\n response_model=User,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"李四, 邮箱是 lisi@example.com, 住在北京市朝阳区建国路88号\"\n }\n ],\n)\n\nprint(user.address)\n# Address(street='建国路88号', city='北京市', country='中国')\n```\n\n资料来源：[README.md](https://github.com/567-labs/instructor/blob/main/README.md)\n\n## 完整示例代码\n\n以下是使用 Instructor 进行用户信息提取的完整示例：\n\n```python\nfrom pydantic import BaseModel\nimport instructor\n\n# 创建客户端\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\n\n\nclass User(BaseModel):\n name: str\n age: int\n email: str\n address: str = None\n\n\n# 提取结构化数据\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n response_model=User,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"张三, 30岁, 邮箱是 zhangsan@example.com\"\n }\n ],\n)\n\n# user 已经是完全验证的 User 对象\nprint(f\"姓名: {user.name}\")\nprint(f\"年龄: {user.age}\")\nprint(f\"邮箱: {user.email}\")\n```\n\n资料来源：[examples/simple-extraction/user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/user.py)\n\n## 下一步\n\n完成快速入门后，建议继续学习以下内容：\n\n| 主题 | 说明 |\n|------|------|\n| [数据验证](/concepts/validators) | 深入了解如何使用 Pydantic 验证器进行复杂验证 |\n| [钩子系统](/concepts/hooks) | 学习如何在请求/响应过程中插入自定义逻辑 |\n| [批处理](/concepts/batch) | 了解如何批量处理提取任务 |\n| [多模态提取](/examples/multimodal) | 学习如何从图像等多模态内容中提取数据 |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[提供商集成](#page-providers), [响应模型](#page-response-models), [验证机制](#page-validation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/core/client.py](https://github.com/567-labs/instructor/blob/main/instructor/core/client.py)\n- [instructor/processing/response.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/response.py)\n- [instructor/processing/function_calls.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/function_calls.py)\n- [instructor/processing/validators.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/validators.py)\n- [docs/architecture.md](https://github.com/567-labs/instructor/blob/main/docs/architecture.md)\n \n\n# 系统架构\n\n## 概述\n\nInstructor 是一个用于从大语言模型（LLM）获取结构化输出的 Python 库。它通过统一 API 连接多种 LLM 提供商，并使用 Pydantic 模型进行响应验证和类型转换。该库的核心设计理念是简化 LLM 函数调用与结构化数据提取的复杂性，使开发者能够以声明式方式定义期望的输出格式，同时自动处理验证、重试和错误恢复。\n\nInstructor 的架构采用分层设计，核心层负责客户端管理、响应处理和验证逻辑，而 providers 层则负责与不同 LLM 提供商的适配。这种分层设计确保了代码的可维护性和可扩展性，同时保持了统一的接口体验。资料来源：[README.md:1-15]()\n\n## 核心架构组件\n\n### 分层架构概览\n\nInstructor 的系统架构可分为三个主要层次：应用接口层、核心处理层和提供商适配层。\n\n```mermaid\ngraph TD\n A[应用层 - 用户代码] --> B[核心层 - Instructor Client]\n B --> C[处理层 - Response/FunctionCall]\n C --> D[验证层 - Validators]\n D --> E[提供商适配层 - Providers]\n \n E --> F[OpenAI]\n E --> G[Anthropic]\n E --> H[Google Gemini]\n E --> I[Ollama]\n E --> J[Groq]\n \n style A fill:#e1f5fe\n style B fill:#b3e5fc\n style C fill:#81d4fa\n style D fill:#4fc3f7\n style E fill:#29b6f6\n```\n\n### 核心层（Core Layer）\n\n核心层是 Instructor 的心脏，负责创建客户端实例、管理 API 调用和协调处理流程。该层的核心组件位于 `instructor/core/client.py` 文件中，提供了统一的客户端工厂函数 `from_provider()`。资料来源：[instructor/core/client.py:1-50]()\n\n核心层的主要职责包括：\n\n- **客户端工厂**：通过 `from_provider()` 函数根据提供商名称创建适配的客户端实例\n- **请求调度**：将用户的结构化请求转换为特定提供商的 API 格式\n- **响应路由**：将提供商的原始响应分发到相应的处理模块\n\n### 处理层（Processing Layer）\n\n处理层负责将 LLM 的原始输出转换为 Pydantic 模型实例。该层包含三个关键模块：\n\n#### 响应处理模块\n\n`response.py` 模块负责解析 LLM 返回的文本响应，并将其映射到预定义的 Pydantic 模型。当 LLM 直接返回文本而非函数调用时，此模块执行必要的数据提取和转换。资料来源：[instructor/processing/response.py:1-30]()\n\n#### 函数调用处理模块\n\n`function_calls.py` 模块处理 LLM 的函数调用输出。当模型选择调用特定函数时，此模块负责：\n\n- 解析函数名称和参数\n- 验证参数类型和格式\n- 提取结构化数据填充到 Pydantic 模型\n\n资料来源：[instructor/processing/function_calls.py:1-40]()\n\n#### 验证器模块\n\n`validators.py` 模块实现了一套完整的验证机制，确保 LLM 输出符合预定义的约束条件。验证器包括：\n\n| 验证器类型 | 功能描述 | 典型用途 |\n|-----------|---------|---------|\n| `field_validator` | Pydantic 原生字段验证 | 类型检查、范围验证 |\n| `llm_validator` | LLM 驱动的语义验证 | 拒绝不当内容、检查语义一致性 |\n| `BeforeValidator` | 前置验证钩子 | 数据预处理、格式规范化 |\n\n资料来源：[instructor/processing/validators.py:1-50]()\n\n### 提供商适配层（Providers Layer）\n\nProvider 层为不同的 LLM 服务提供商提供统一的适配接口。每个提供商都有独立的子目录，采用标准化的目录结构。资料来源：[instructor/providers/README.md:1-20]()\n\n## 提供商架构\n\n### 提供商组织结构\n\nInstructor 支持多种 LLM 提供商，采用统一的目录结构和适配模式：\n\n```\nproviders/\n├── provider_name/\n│ ├── __init__.py\n│ ├── client.py # 提供商特定客户端工厂\n│ └── utils.py # 提供商特定工具函数\n```\n\n### 提供商分类\n\n根据实现复杂度，Provider 可分为以下几类：\n\n| 类别 | 提供商 | 特点 |\n|------|--------|------|\n| 完整实现 | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | 包含 client.py 和 utils.py |\n| 简化实现 | genai, groq, vertexai | 仅包含 client.py，使用核心标准处理 |\n| 参考实现 | openai | 仅包含 utils.py，client 在核心层定义 |\n\n资料来源：[instructor/providers/README.md:8-15]()\n\n### 提供商工厂模式\n\nInstructor 使用统一的工厂模式创建客户端实例：\n\n```python\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n```\n\n所有客户端使用相同的 API 调用方式，底层的提供商差异被完全抽象：\n\n```python\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n资料来源：[README.md:45-65]()\n\n## 请求处理流程\n\n### 完整请求生命周期\n\nInstructor 的请求处理遵循标准化的生命周期流程：\n\n```mermaid\ngraph TD\n A[创建客户端 from_provider] --> B[调用 create 方法]\n B --> C[构建 API 请求]\n C --> D{提供商类型检测}\n D -->|OpenAI| E[使用标准工具调用格式]\n D -->|Anthropic| F[使用 Beta Messages API]\n D -->|其他| G[使用提供商特定格式]\n E --> H[发送请求到 LLM]\n F --> H\n G --> H\n H --> I{解析响应}\n I -->|函数调用| J[调用 function_calls 处理]\n I -->|文本响应| K[调用 response 处理]\n J --> L{运行验证器}\n K --> L\n L -->|验证失败| M[重试并提供错误信息]\n L -->|验证成功| N[返回 Pydantic 模型]\n M --> H\n```\n\n### Hooks 系统架构\n\nInstructor 提供了强大的钩子系统，允许开发者在请求处理的不同阶段插入自定义逻辑。钩子系统支持拦截请求发送前和响应处理后的流程。资料来源：[examples/hooks/README.md:1-30]()\n\nHook 事件类型包括：\n\n| 事件类型 | 触发时机 | 用途示例 |\n|---------|---------|---------|\n| `on_request` | 发送请求前 | 日志记录、请求修改 |\n| `on_response` | 收到响应后 | 响应日志、使用量统计 |\n| `on_retry` | 重试前 | 错误日志、重试策略调整 |\n| `on_parse_error` | 解析失败时 | 错误处理、调试信息 |\n| `on_completion_error` | 完成错误时 | 错误处理、告警通知 |\n\n## 验证与重试机制\n\n### 自动重试机制\n\nInstructor 的核心特性之一是自动重试机制。当 Pydantic 验证失败时，系统会自动重试并携带错误信息，让 LLM 有机会修正输出。资料来源：[README.md:80-95]()\n\n```mermaid\ngraph LR\n A[首次请求] --> B{验证通过?}\n B -->|是| C[返回结果]\n B -->|否| D[提取验证错误]\n D --> E[携带错误信息重试]\n E --> A\n C --> F[最多重试 max_retries 次]\n F -->|失败| G[抛出异常]\n```\n\n### 验证器链\n\n验证器可以链式使用，形成多层次的验证策略：\n\n```python\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"don't say objectionable things\", allow_override=True)\n ),\n ]\n```\n\n这种设计允许组合使用 Pydantic 原生验证和 LLM 驱动的语义验证。资料来源：[examples/validators/readme.md:30-50]()\n\n## 批处理架构\n\n### BatchProcessor 组件\n\nInstructor 提供了统一的批处理 API，支持多个提供商：\n\n```python\nfrom instructor import BatchProcessor\n\nprocessor = BatchProcessor()\nbatch_id = processor.create_batch(\n model=\"openai/gpt-4o-mini\",\n messages=messages,\n response_model=User,\n)\n```\n\n资料来源：[examples/batch_api/README.md:1-40]()\n\n### 支持的提供商\n\n| 提供商 | 模型示例 | 批处理支持 |\n|--------|---------|-----------|\n| OpenAI | gpt-4o-mini, gpt-4o, gpt-4-turbo | 完整支持 |\n| Anthropic | claude-3-5-sonnet, claude-3-opus | Beta Messages API |\n| Google | gemini-2.0-flash-001, gemini-pro | 模拟模式 |\n\n## 扩展机制\n\n### 插件式架构\n\nInstructor 的架构设计支持插件扩展，主要扩展点包括：\n\n1. **自定义 Provider**：通过实现 provider 适配接口添加新提供商\n2. **自定义 Validator**：通过扩展 validators 模块添加新的验证策略\n3. **Hook 钩子**：通过注册事件处理器扩展处理流程\n\n### 添加新 Provider 的标准流程\n\n1. 在 `providers/` 下创建新的提供商子目录\n2. 添加 `__init__.py` 文件（可为空或包含导入）\n3. 如需自定义处理逻辑，添加 `utils.py` 文件\n4. 如需自定义客户端工厂，添加 `client.py` 文件\n5. 更新提供商注册表\n\n资料来源：[instructor/providers/README.md:18-25]()\n\n## 关键设计模式\n\n### 统一接口模式\n\nInstructor 采用统一接口模式，隐藏底层提供商差异：\n\n- **客户端统一**：所有提供商客户端实现相同的 `chat.completions.create` 接口\n- **响应统一**：无论来源如何，所有响应都转换为 Pydantic 模型实例\n- **错误统一**：验证错误和 API 错误采用一致的异常格式\n\n### 声明式配置模式\n\n开发者通过声明式方式定义期望的输出结构：\n\n```python\nclass User(BaseModel):\n name: str\n age: int\n \n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n\nuser = client.chat.completions.create(\n response_model=User,\n messages=[...],\n)\n```\n\n这种模式将验证逻辑与业务逻辑分离，提高了代码的可读性和可维护性。\n\n### 工厂模式\n\n`from_provider()` 工厂函数是整个系统的入口点，根据提供商标识符动态创建适当的客户端实例。这种模式简化了客户端管理，同时支持运行时提供商切换。\n\n## 总结\n\nInstructor 的系统架构围绕三个核心目标设计：简化 LLM 结构化输出、保证输出质量、支持多提供商。其分层架构确保了关注点分离，而统一的接口模式提供了无缝的跨提供商体验。验证和重试机制的深度集成使得系统能够在 LLM 输出不符合预期时自动恢复，极大地提高了生产环境的稳定性。资料来源：[docs/architecture.md:1-30]()\n\n---\n\n\n\n## 提供商集成\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/providers/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/providers/__init__.py)\n- [instructor/providers/anthropic/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/providers/anthropic/__init__.py)\n- [instructor/providers/gemini/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/providers/gemini/__init__.py)\n- [instructor/providers/README.md](https://github.com/567-labs/instructor/blob/main/instructor/providers/README.md)\n- [docs/integrations/index.md](https://github.com/567-labs/instructor/blob/main/docs/integrations/index.md)\n \n\n# 提供商集成\n\n## 概述\n\nInstructor 的提供商集成（Provider Integration）模块为开发者提供了统一的接口，用于对接多种大型语言模型（LLM）提供商。通过 `instructor.from_provider()` 工厂方法，开发者可以使用相同的代码结构访问 OpenAI、Anthropic、Google、Ollama 等不同提供商的模型，无需关心底层 API 的差异。\n\n该模块位于 `instructor/providers/` 目录下，每个提供商都有独立的子目录和实现文件，采用一致的目录结构但根据提供商复杂度灵活配置。\n\n## 核心架构\n\n### 目录结构\n\n```\ninstructor/providers/\n├── __init__.py\n├── provider_name/\n│ ├── __init__.py\n│ ├── client.py # 提供商特定的客户端工厂（可选）\n│ └── utils.py # 提供商特定的工具函数（可选）\n```\n\n资料来源：[instructor/providers/README.md]()\n\n### 提供商分类\n\nInstructor 根据实现复杂度将提供商分为三类：\n\n| 类型 | 提供商列表 | 特征 |\n|------|-----------|------|\n| 完整实现 | anthropic, bedrock, cerebras, cohere, fireworks, gemini, mistral, perplexity, writer, xai | 包含 `client.py` 和 `utils.py`，需要自定义响应处理逻辑 |\n| 简化实现 | genai, groq, vertexai | 仅包含 `client.py`，使用核心模块的标准响应处理 |\n| 特殊实现 | openai | 仅包含 `utils.py`（`from_openai()` 定义在 `core/client.py` 中） |\n\n资料来源：[instructor/providers/README.md]()\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[用户调用 from_provider] --> B{提供商类型判断}\n B -->|OpenAI| C[core/client.py 处理]\n B -->|Anthropic| D[anthropic/client.py]\n B -->|Gemini| E[gemini/client.py]\n B -->|其他| F[对应 provider/client.py]\n \n D --> G[provider/utils.py 响应处理]\n E --> G\n C --> H[统一响应格式化]\n F --> G\n G --> H\n```\n\n## 快速开始\n\n### 基础用法\n\n使用 `from_provider()` 方法创建客户端：\n\n```python\nimport instructor\n\n# OpenAI\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# Anthropic\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\")\n\n# Google\nclient = instructor.from_provider(\"google/gemini-pro\")\n\n# Ollama (本地部署)\nclient = instructor.from_provider(\"ollama/llama3.2\")\n```\n\n资料来源：[README.md]()\n\n### 使用 API Key\n\n所有提供商使用统一的 API：\n\n```python\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n name: str\n age: int\n\n# 直接传递 API Key\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\", api_key=\"sk-ant-...\")\n\n# 使用统一接口\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n## 支持的提供商\n\n### OpenAI\n\nOpenAI 是 Instructor 的参考实现，`from_openai()` 函数定义在 `core/client.py` 中。其他提供商的实现都基于此模式。\n\n**支持模型：**\n\n| 模型 | 说明 |\n|------|------|\n| gpt-4o | 最新多模态旗舰模型 |\n| gpt-4-turbo | 高性能 GPT-4 变体 |\n| gpt-4 | 标准 GPT-4 模型 |\n| gpt-3.5-turbo | 快速响应模型 |\n\n### Anthropic\n\nAnthropic 提供商位于 `instructor/providers/anthropic/`，包含完整的 `client.py` 和 `utils.py` 实现。\n\n**支持模型：**\n\n| 模型 | 说明 |\n|------|------|\n| claude-3-5-sonnet-20241022 | 最新 Sonnet 模型 |\n| claude-3-opus-20240229 | 高性能 Opus 模型 |\n| claude-3-haiku-20240307 | 轻量级 Haiku 模型 |\n\n### Google Gemini\n\nGoogle Gemini 提供商位于 `instructor/providers/gemini/`，使用 `gemini-pro` 等模型。\n\n**支持模型：**\n\n| 模型 | 说明 |\n|------|------|\n| gemini-2.0-flash-001 | 快速响应模型 |\n| gemini-pro | 标准 Gemini 模型 |\n| gemini-pro-vision | 多模态支持 |\n\n### 其他提供商\n\nInstructor 还支持以下提供商，采用简化实现：\n\n| 提供商 | 说明 |\n|--------|------|\n| groq | Groq LPU 推理加速 |\n| vertexai | Google Cloud Vertex AI |\n| genai | 通用生成式 AI 接口 |\n| ollama | 本地模型部署 |\n\n## 批量处理集成\n\n每个提供商都支持批量 API 调用，通过 `BatchProcessor` 类实现统一的批量处理接口。\n\n### 批量处理工作流\n\n```mermaid\ngraph LR\n A[准备消息列表] --> B[BatchProcessor]\n B --> C{提供商检测}\n C -->|OpenAI| D[生成 batch JSON]\n C -->|Anthropic| E[使用 beta API]\n C -->|Google| F[模拟模式/GCS]\n D --> G[提交批量任务]\n E --> G\n F --> G\n G --> H[返回 Batch ID]\n```\n\n### 支持的批量操作\n\n```bash\n# 创建批量任务\ninstructor batch create \\\n --messages-file messages.jsonl \\\n --model \"openai/gpt-4o-mini\" \\\n --response-model \"User\"\n\n# 从文件提交批量任务\ninstructor batch create-from-file \\\n --file-path batch_requests.jsonl \\\n --model \"openai/gpt-4o-mini\"\n```\n\n资料来源：[examples/batch_api/README.md]()\n\n## 新增提供商\n\n### 添加步骤\n\n当需要添加新的提供商时，按照以下流程操作：\n\n1. 在 `instructor/providers/` 下创建新的子目录\n2. 添加 `__init__.py` 文件（可为空）\n3. 根据复杂度添加 `client.py` 和/或 `utils.py`\n\n```mermaid\ngraph TD\n A[创建 providers/newprovider/] --> B[添加 __init__.py]\n B --> C{需要自定义处理?}\n C -->|是| D[创建 client.py 和 utils.py]\n C -->|否| E[仅创建 client.py]\n D --> F[实现 from_newprovider 工厂函数]\n E --> F\n F --> G[导出到 providers/__init__.py]\n```\n\n### 实现要求\n\n| 组件 | 必需 | 说明 |\n|------|------|------|\n| `__init__.py` | 是 | 模块初始化文件 |\n| `client.py` | 视情况 | 包含 `from_()` 工厂函数 |\n| `utils.py` | 视情况 | 包含响应处理程序、重试函数、消息格式化工具 |\n\n资料来源：[instructor/providers/README.md]()\n\n## 配置与认证\n\n### 环境变量\n\n| 环境变量 | 提供商 | 说明 |\n|----------|--------|------|\n| `OPENAI_API_KEY` | OpenAI | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | Anthropic | Anthropic API 密钥 |\n| `GOOGLE_API_KEY` | Google | Google AI API 密钥 |\n| `GROQ_API_KEY` | Groq | Groq API 密钥 |\n\n### 初始化参数\n\n`from_provider()` 方法支持以下参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | str | 模型标识符，格式为 `provider/model-name` |\n| `api_key` | str, 可选 | 直接传递 API 密钥，覆盖环境变量 |\n| `base_url` | str, 可选 | 自定义 API 端点 |\n| `max_retries` | int, 可选 | 最大重试次数，默认 3 |\n| `timeout` | float, 可选 | 请求超时时间（秒） |\n\n## 与旧版 API 的兼容性\n\nInstructor 提供了模式转换脚本，用于将旧版 API 调用迁移到新版本：\n\n### API 模式变更\n\n| 旧版模式 | 新版模式 |\n|----------|----------|\n| `client.chat.completions.create` | `client.create` |\n| `client.chat.completions.create_partial` | `client.create_partial` |\n| `client.chat.completions.create_iterable` | `client.create_iterable` |\n| `client.chat.completions.create_with_completion` | `client.create_with_completion` |\n\n### 审计工具\n\n使用 `audit_patterns.py` 脚本检查文档中的旧模式：\n\n```bash\n# 详细报告\npython scripts/audit_patterns.py\n\n# 仅摘要\npython scripts/audit_patterns.py --summary\n\n# 检查单个文件\npython scripts/audit_patterns.py --file docs/index.md\n```\n\n资料来源：[scripts/README.md]()\n\n## 最佳实践\n\n### 提供商选择指南\n\n```mermaid\ngraph TD\n A[选择提供商] --> B{场景类型}\n B -->|生产环境| C{预算考虑}\n C -->|充足| D[OpenAI GPT-4]\n C -->|有限| E[OpenAI GPT-4o-mini 或 Groq]\n B -->|本地部署| F[Ollama]\n B -->|高精度| G[Anthropic Claude Opus]\n B -->|多模态| H[Google Gemini Pro Vision]\n```\n\n### 错误处理\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| API Key 未设置 | 设置对应的环境变量 |\n| 无效模型格式 | 使用 `provider/model-name` 格式 |\n| 不支持的提供商 | 使用支持的提供商列表 |\n| 速率限制 | 配置 `max_retries` 参数 |\n\n## 总结\n\nInstructor 的提供商集成模块通过统一的抽象层，简化了多提供商 LLM 的使用流程。开发者只需掌握 `from_provider()` 工厂方法，即可无缝切换不同的模型提供商，同时保持代码的一致性和可维护性。\n\n---\n\n\n\n## 响应模型\n\n### 相关页面\n\n相关主题：[验证机制](#page-validation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/processing/schema.py](https://github.com/567-labs/instructor/blob/main/instructor/processing/schema.py)\n- [docs/concepts/models.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/models.md)\n- [docs/learning/getting_started/response_models.md](https://github.com/567-labs/instructor/blob/main/docs/learning/getting_started/response_models.md)\n- [examples/simple-extraction/maybe_user.py](https://github.com/567-labs/instructor/blob/main/examples/simple-extraction/maybe_user.py)\n \n\n# 响应模型\n\n响应模型（Response Model）是 Instructor 库的核心功能，它允许开发者使用 Pydantic 模型定义 LLM 输出的期望结构，实现自动类型验证和解析。\n\n## 概述\n\n在传统的 LLM API 调用中，返回的响应是原始文本或 JSON 字符串，需要开发者手动解析和验证。这种方式不仅繁琐，还容易引入错误。响应模型通过将 Pydantic 模型作为 `response_model` 参数传递，让 Instructor 自动完成以下工作：\n\n| 功能 | 说明 |\n|------|------|\n| 结构提取 | 从 LLM 输出中自动提取 JSON 结构 |\n| 类型转换 | 将字符串转换为 Pydantic 模型定义的类型 |\n| 验证处理 | 执行 Pydantic 验证器，自动重试失败的请求 |\n| 错误处理 | 捕获验证错误并生成有意义的反馈 |\n\n资料来源：[README.md:1-30]()\n\n## 基本用法\n\n### 安装与初始化\n\n```python\npip install instructor\n\n# 从 OpenAI 初始化客户端\nclient = instructor.from_provider(\"openai/gpt-4o\")\n```\n\n资料来源：[README.md:45-50]()\n\n### 定义响应模型\n\n响应模型基于 Pydantic 的 `BaseModel` 构建：\n\n```python\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n name: str\n age: int\n```\n\n### 调用 API\n\n使用 `response_model` 参数指定期望的响应模型：\n\n```python\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"Extract: Jason, 28 years old\"}],\n)\n\n# user 已经是验证通过的 User 实例\nprint(user.name) # Jason\nprint(user.age) # 28\n```\n\n资料来源：[README.md:35-45]()\n\n## 工作原理\n\nInstructor 的响应模型处理流程如下：\n\n```mermaid\ngraph TD\n A[用户请求] --> B[创建 API 调用]\n B --> C{传入 response_model}\n C -->|是| D[发送请求到 LLM]\n C -->|否| E[返回原始响应]\n D --> F[解析 LLM 输出为 JSON]\n F --> G[Pydantic 验证]\n G --> H{验证通过?}\n H -->|是| I[返回模型实例]\n H -->|否| J[生成错误信息]\n J --> K{重试次数 < max_retries?}\n K -->|是| D\n K -->|否| L[抛出 ValidationError]\n```\n\n## 自动重试机制\n\n当 Pydantic 验证失败时，Instructor 会自动将错误信息反馈给 LLM 并重试请求：\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n\n# Instructor 自动处理重试\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n max_retries=3, # 默认值，可自定义\n)\n```\n\n资料来源：[README.md:75-95]()\n\n### 重试流程图\n\n```mermaid\ngraph LR\n A[验证失败] --> B[提取错误信息]\n B --> C[构造修正提示]\n C --> D[重新发送请求]\n D --> E{再次验证}\n E -->|通过| F[返回结果]\n E -->|失败| G{重试次数剩余?}\n G -->|是| A\n G -->|否| H[抛出异常]\n```\n\n## 高级用法\n\n### 使用 BeforeValidator 进行自定义验证\n\n使用 `llm_validator` 实现基于 LLM 的文本验证：\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BeforeValidator\n\nclass QuestionAnswer(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"不要发表不当言论\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md:50-60]()\n\n### 处理验证异常\n\n```python\ntry:\n qa = client.chat.completions.create(\n response_model=QuestionAnswerNoEvil,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n )\nexcept Exception as e:\n print(f\"验证失败: {e}\")\n```\n\n资料来源：[examples/validators/readme.md:80-90]()\n\n### 设置最大重试次数\n\n```python\nqa = client.chat.completions.create(\n model=\"gpt-3.5-turbo\",\n response_model=QuestionAnswerNoEvil,\n max_retries=2, # 允许最多 2 次重试\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n)\n```\n\n资料来源：[examples/validators/readme.md:100-110]()\n\n## 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `response_model` | Type[BaseModel] | 必需 | 响应的 Pydantic 模型类 |\n| `max_retries` | int | 3 | 最大重试次数 |\n| `validation_context` | dict | None | 传递给验证器的额外上下文 |\n| `strict_response_validation` | bool | False | 是否启用严格验证模式 |\n\n## 与传统方式的对比\n\n| 特性 | 传统方式 | 使用响应模型 |\n|------|----------|--------------|\n| JSON 解析 | 手动解析 | 自动完成 |\n| 类型验证 | 手动检查 | Pydantic 自动验证 |\n| 错误处理 | 复杂的条件判断 | 自动重试和异常 |\n| 代码行数 | 15-20 行 | 3-5 行 |\n\n资料来源：[README.md:1-20]()\n\n## 完整示例\n\n```python\nfrom pydantic import BaseModel, field_validator\nimport instructor\n\n# 初始化客户端\nclient = instructor.from_provider(\"openai/gpt-4o\")\n\n# 定义响应模型\nclass User(BaseModel):\n name: str\n age: int\n email: str | None = None\n\n @field_validator('age')\n @classmethod\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n\n# 使用响应模型\nuser = client.chat.completions.create(\n model=\"gpt-4o\",\n response_model=User,\n messages=[\n {\"role\": \"system\", \"content\": \"你是一个数据提取助手\"},\n {\"role\": \"user\", \"content\": \"从以下文本提取用户信息：张三，35岁，邮箱 zhangsan@example.com\"}\n ],\n)\n\nprint(f\"姓名: {user.name}\")\nprint(f\"年龄: {user.age}\")\nprint(f\"邮箱: {user.email}\")\n```\n\n## 支持的模型类型\n\n响应模型支持所有 Pydantic v2 的特性：\n\n- 基本类型：`str`、`int`、`float`、`bool`\n- 可选类型：`Optional[T]` 或 `T | None`\n- 列表类型：`List[T]`\n- 嵌套模型：嵌套的 `BaseModel`\n- 联合类型：`Union[A, B]` 或 `A | B`\n- 枚举类型：`Enum`\n- 验证器：`@field_validator`、`@model_validator`\n\n## 最佳实践\n\n1. **始终定义类型注解**：让 Pydantic 正确推断类型\n2. **使用验证器**：在模型中定义业务规则验证\n3. **设置合理的 max_retries**：默认为 3，根据复杂程度调整\n4. **使用 Optional 处理可选字段**：避免验证失败\n5. **保持模型简洁**：复杂逻辑使用嵌套模型分离\n\n## 下一步\n\n- [验证器使用指南](https://instructor-ai.github.io/instructor/concepts/validators/)\n- [钩子系统](https://instructor-ai.github.io/instructor/concepts/hooks/)\n- [批量处理](https://instructor-ai.github.io/instructor/concepts/batch/)\n\n---\n\n\n\n## 验证机制\n\n### 相关页面\n\n相关主题：[响应模型](#page-response-models), [钩子系统](#page-hooks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/dsl/validators.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/validators.py)\n- [instructor/validation/llm_validators.py](https://github.com/567-labs/instructor/blob/main/instructor/validation/llm_validators.py)\n- [instructor/core/retry.py](https://github.com/567-labs/instructor/blob/main/instructor/core/retry.py)\n- [docs/concepts/validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/validation.md)\n- [docs/concepts/reask_validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/reask_validation.md)\n- [examples/validators/field_validator.py](https://github.com/567-labs/instructor/blob/main/examples/validators/field_validator.py)\n \n\n# 验证机制\n\n## 概述\n\nInstructor 的验证机制是确保 LLM（大语言模型）输出结构化数据正确性的核心系统。该机制构建在 Pydantic 框架之上，提供自动验证、错误处理、重试逻辑和 LLM 级语义验证能力。\n\nInstructor 的验证流程采用多层架构设计：\n\n```mermaid\ngraph TD\n A[LLM 响应] --> B[响应解析]\n B --> C[Pydantic 模型验证]\n C --> D{验证通过?}\n D -->|是| E[返回结构化数据]\n D -->|否| F[收集验证错误]\n F --> G{重试次数 < max_retries?}\n G -->|是| H[提取错误信息]\n H --> I[构建重试提示]\n I --> J[重新发送给 LLM]\n J --> A\n G -->|否| K[抛出异常]\n```\n\n资料来源：[docs/concepts/reask_validation.md:1-20]()\n\n## 核心验证流程\n\n### Pydantic BaseModel 集成\n\nInstructor 使用 Pydantic 的 `BaseModel` 作为响应模型的基础。当定义响应模型时，Instructor 自动将模型转换为 LLM 可理解的 JSON Schema，并在验证失败时生成精确的错误提示。\n\n资料来源：[README.md:1-30]()\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('年龄必须为正数')\n return v\n```\n\n资料来源：[README.md:60-75]()\n\n### 字段验证器（Field Validators）\n\n字段验证器允许在字段级别添加自定义验证逻辑。通过 Pydantic 的 `@field_validator` 装饰器，可以对单个字段进行类型检查、范围验证和格式校验。\n\n| 验证器类型 | 说明 | 示例 |\n|-----------|------|------|\n| 类型验证 | 确保字段值符合声明类型 | `age: int` |\n| 范围验证 | 检查值是否在有效范围内 | `0 <= age <= 150` |\n| 格式验证 | 验证字符串格式 | 邮箱、电话号码 |\n| 自定义验证 | 使用 `@field_validator` | 自定义业务逻辑 |\n\n资料来源：[examples/validators/field_validator.py:1-50]()\n\n## LLM 级语义验证\n\n### llm_validator 机制\n\n`llm_validator` 是 Instructor 提供的特殊验证器，用于执行 LLM 级别的语义验证。它允许开发者定义自然语言约束条件，由 LLM 判断输出是否符合预期语义。\n\n资料来源：[instructor/validation/llm_validators.py:1-30]()\n\n```python\nfrom typing_extensions import Annotated\nfrom pydantic import BeforeValidator\nfrom instructor import llm_validator\n\nclass QuestionAnswerNoEvil(BaseModel):\n question: str\n answer: Annotated[\n str,\n BeforeValidator(\n llm_validator(\"不要说出不当言论\", allow_override=True)\n ),\n ]\n```\n\n资料来源：[examples/validators/readme.md:1-50]()\n\n### llm_validator 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| constraint | str | 是 | 自然语言约束条件 |\n| allow_override | bool | 否 | 是否允许通过特殊标记覆盖验证 |\n| validation_context | dict | 否 | 额外的验证上下文信息 |\n| max_retries | int | 否 | 最大验证重试次数 |\n\n资料来源：[instructor/validation/llm_validators.py:30-60]()\n\n## 自动重试机制\n\n### 重试工作流程\n\n当验证失败时，Instructor 自动将错误信息提取并附加到下一轮对话中，引导 LLM 修正错误。这一过程无需手动干预。\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant I as Instructor\n participant LLM as LLM API\n participant V as 验证器\n \n U->>I: 调用 create(response_model=User)\n I->>LLM: 发送初始请求\n LLM-->>I: 返回响应\n I->>V: 执行 Pydantic 验证\n V-->>I: 验证失败: age < 0\n I->>I: 生成重试提示\n I->>LLM: 发送修正请求 + 错误信息\n LLM-->>I: 返回修正响应\n I->>V: 再次验证\n V-->>I: 验证通过\n I-->>U: 返回 User 对象\n```\n\n资料来源：[instructor/core/retry.py:1-80]()\n\n### 重试配置\n\n通过 `max_retries` 参数控制重试次数，默认行为由 Instructor 内部配置决定。\n\n```python\nuser = client.chat.completions.create(\n response_model=User,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n max_retries=3, # 最多重试3次\n)\n```\n\n资料来源：[README.md:75-85]()\n\n### 重试策略\n\nInstructor 采用指数退避策略处理重试，避免在瞬时错误时过度调用 API。每次重试之间会有适当延迟。\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| max_retries | 最大重试次数 | 3 |\n| retry_on | 触发重试的错误类型 | ValidationError |\n| backoff_factor | 退避因子 | 1.0 |\n\n资料来源：[instructor/core/retry.py:80-120]()\n\n## 错误处理\n\n### 验证错误捕获\n\n验证失败时会抛出 `ValidationError` 异常，可通过标准的 Python 异常处理机制捕获。\n\n```python\ntry:\n qa = client.chat.completions.create(\n response_model=QuestionAnswerNoEvil,\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n )\nexcept Exception as e:\n print(f\"验证失败: {e}\")\n```\n\n资料来源：[examples/validators/readme.md:100-120]()\n\n### 错误响应格式\n\n验证错误包含详细的字段级错误信息：\n\n```\n1 validation error for QuestionAnswerNoEvil\nanswer\n Assertion failed, 陈述包含不当言论\n```\n\n资料来源：[examples/validators/readme.md:70-75]()\n\n## 流式验证\n\n### Partial 模型支持\n\nInstructor 支持流式输出验证，使用 `Partial[T]` 类型在生成过程中逐步验证和返回部分结果。\n\n```python\nfrom instructor import Partial\n\nfor partial_user in client.chat.completions.create(\n response_model=Partial[User],\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n stream=True,\n):\n print(partial_user)\n # 输出演变过程:\n # User(name=None, age=None)\n # User(name=\"张三\", age=None)\n # User(name=\"张三\", age=25)\n```\n\n资料来源：[README.md:90-105]()\n\n### 流式验证流程\n\n```mermaid\ngraph LR\n A[开始生成] --> B[解析部分响应]\n B --> C[执行部分验证]\n C --> D[返回部分对象]\n D --> E{生成完成?}\n E -->|否| B\n E -->|是| F[最终验证]\n F --> G[返回完整对象]\n```\n\n## 嵌套对象验证\n\n### 复杂数据结构\n\nInstructor 自动处理嵌套的 Pydantic 模型，支持多层级的结构化数据验证。\n\n```python\nfrom typing import List\n\nclass Address(BaseModel):\n street: str\n city: str\n country: str\n\nclass User(BaseModel):\n name: str\n age: int\n addresses: List[Address]\n```\n\n资料来源：[README.md:110-125]()\n\n### 嵌套验证特性\n\n| 特性 | 说明 |\n|------|------|\n| 递归验证 | 自动验证嵌套层级的所有字段 |\n| 深度限制 | 避免无限嵌套导致的性能问题 |\n| 上下文保持 | 保持嵌套对象间的引用关系 |\n\n## 自定义验证器\n\n### 创建自定义验证器\n\n可通过继承和组合的方式创建领域特定的验证器。\n\n```python\nfrom pydantic import BeforeValidator\nfrom typing import Any\n\ndef custom_validator(value: Any) -> Any:\n # 自定义验证逻辑\n if isinstance(value, str) and len(value) > 100:\n raise ValueError(\"字符串长度不能超过100\")\n return value\n\nclass MyModel(BaseModel):\n content: Annotated[str, BeforeValidator(custom_validator)]\n```\n\n资料来源：[instructor/dsl/validators.py:1-40]()\n\n### 验证器组合\n\n多个验证器可以组合使用，形成链式验证：\n\n```python\nclass ValidatedString(BaseModel):\n value: Annotated[\n str,\n BeforeValidator(validator1),\n BeforeValidator(validator2),\n BeforeValidator(validator3),\n ]\n```\n\n资料来源：[instructor/dsl/validators.py:40-60]()\n\n## 最佳实践\n\n### 验证设计原则\n\n1. **渐进式验证**：从简单类型验证开始，逐步增加复杂规则\n2. **错误消息清晰**：自定义错误消息应明确指出问题所在\n3. **合理设置重试次数**：根据场景调整 `max_retries` 值\n4. **使用 LLM 验证器**：对于语义相关的验证，优先使用 `llm_validator`\n\n### 性能考虑\n\n| 场景 | 建议 |\n|------|------|\n| 大量字段验证 | 使用 `model_validator` 替代多个 `field_validator` |\n| 复杂嵌套结构 | 设置合理的嵌套深度限制 |\n| 高频调用 | 考虑启用验证结果缓存 |\n\n## 相关资源\n\n- Pydantic 官方文档：[https://docs.pydantic.dev/](https://docs.pydantic.dev/)\n- Instructor 验证概念文档：[docs/concepts/validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/validation.md)\n- 重试机制文档：[docs/concepts/reask_validation.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/reask_validation.md)\n\n---\n\n\n\n## 流式输出\n\n### 相关页面\n\n相关主题：[响应模型](#page-response-models), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/dsl/partial.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/partial.py)\n- [instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py)\n- [docs/concepts/partial.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/partial.md)\n- [docs/concepts/iterable.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/iterable.md)\n- [examples/partial_streaming/run.py](https://github.com/567-labs/instructor/blob/main/examples/partial_streaming/run.py)\n \n\n# 流式输出\n\n## 概述\n\n流式输出（Streaming）是 Instructor 库中用于处理大型语言模型（LLM）响应的核心功能之一。当模型生成较长文本或复杂结构化数据时，流式输出允许开发者逐步获取模型的生成结果，而无需等待完整响应生成完毕。这种方式显著改善了用户体验，特别是在需要实时反馈的应用场景中，如聊天机器人、长文本生成工具和交互式数据分析系统。\n\nInstructor 提供了两种主要的流式输出模式：第一种是部分模式（Partial），用于接收正在构建中的结构化数据；第二种是可迭代模式（Iterable），用于处理需要逐步验证的长序列数据。这两种模式都基于 Pydantic 模型进行类型安全保证，确保流式输出的数据始终符合预期的数据结构。\n\n流式输出的核心优势在于其能够将模型的增量生成与验证逻辑紧密结合。当模型逐 token 生成内容时，Instructor 能够实时解析这些部分内容并填充到 Pydantic 模型字段中，开发者可以在每个增量更新时访问当前已验证的部分数据。这种实时解析和验证的能力使得 Instructor 的流式输出不仅提供了流畅的用户体验，还确保了数据结构的完整性和类型安全。\n\n## 架构设计\n\n### 核心组件关系\n\nInstructor 的流式输出系统由多个关键组件协同工作，这些组件共同实现了从模型生成到结构化数据解析的完整流程。理解这些组件之间的关系对于正确使用流式输出功能至关重要。\n\n```mermaid\ngraph TD\n A[LLM 模型] --> B[流式响应]\n B --> C[响应处理器]\n C --> D[Partial 模式]\n C --> E[Iterable 模式]\n D --> F[Pydantic BaseModel]\n E --> G[迭代器接口]\n F --> H[实时验证]\n G --> I[延迟验证]\n H --> J[增量更新回调]\n I --> J\n```\n\n从架构层面来看，Instructor 的流式输出系统采用了分层设计模式。最底层是模型提供者（Provider）无关的通用接口，中间层是针对不同输出模式的处理逻辑，顶层则是面向开发者的简洁 API。这种分层设计确保了代码的可维护性和扩展性，同时也为支持新的 LLM 提供者提供了便利。\n\n### 数据流处理\n\n流式输出的数据处理流程可以分为几个关键阶段，每个阶段都有明确的职责和接口定义。在数据生成的初始阶段，模型以流式方式返回 token 序列，这些 token 会被实时拼接成部分完成的文本或 JSON 结构。Instructor 的响应处理器负责识别当前接收到的内容是否构成完整的语义单元，并将这些内容路由到相应的处理模块。\n\n```mermaid\nsequenceDiagram\n participant LLM as LLM 模型\n participant Handler as 响应处理器\n participant Parser as 部分解析器\n participant Validator as 验证器\n participant App as 应用程序\n \n LLM->>Handler: 发送增量 token\n Handler->>Parser: 解析部分内容\n Parser->>Validator: 验证当前数据\n Validator-->>Parser: 验证结果\n Parser-->>Handler: 更新状态\n Handler-->>App: 推送部分更新\n App-->>LLM: 请求下一批 token\n```\n\n## Partial 模式\n\n### 功能说明\n\nPartial 模式是 Instructor 流式输出体系中的核心组件，专门设计用于处理结构化数据的增量生成。在传统的非流式调用中，开发者必须等待模型完整生成所有内容后才能获得最终的结构化数据。然而，在许多应用场景中，用户希望能够实时看到正在生成的数据，例如在表单填充、实时分析或交互式问答系统中。\n\nPartial 模式通过维护一个持续更新的 Pydantic 模型实例来实现这一功能。每当模型生成新的 token 并被解析后，对应的模型字段会立即更新，开发者可以访问这些部分填充的字段内容。这种设计确保了数据的即时可用性，同时保持了 Pydantic 模型提供的类型安全和验证功能。\n\nPartial 模式的核心实现位于 `instructor/dsl/partial.py` 文件中，该文件定义了处理部分响应的基础架构和工具函数。这些实现支持多种 LLM 提供者，并提供了灵活的配置选项以适应不同的使用场景。\n\n### 使用示例\n\n使用 Partial 模式需要从 Instructor 导入必要的组件，并定义一个继承自 `BaseModel` 的响应模型。以下是一个典型的工作流程示例，展示了如何配置和使用流式输出来实时获取结构化数据：\n\n```python\nfrom instructor import from_provider\nfrom pydantic import BaseModel\n\n# 初始化 Instructor 客户端\nclient = from_provider(\"openai/gpt-4o\")\n\n# 定义响应模型\nclass UserProfile(BaseModel):\n name: str\n bio: str\n skills: list[str]\n\n# 使用 create_partial 方法进行流式输出\nresponse = client.chat.completions.create_partial(\n model=\"gpt-4o\",\n response_model=UserProfile,\n messages=[\n {\"role\": \"user\", \"content\": \"生成一个用户画像，包含姓名、简介和技能列表\"}\n ]\n)\n\n# 迭代处理部分响应\nfor partial in response:\n print(f\"当前进度 - 姓名: {partial.name}\")\n if partial.bio:\n print(f\"简介: {partial.bio}\")\n if partial.skills:\n print(f\"技能: {partial.skills}\")\n```\n\n上述示例演示了 Partial 模式的基本用法。在实际应用中，开发者可以根据需求添加更复杂的验证逻辑、错误处理机制或用户界面更新代码。关键在于 `create_partial` 方法返回一个可迭代对象，每次迭代都会产生当前已验证的部分数据。\n\n### API 签名\n\n`create_partial` 方法是 Instructor 流式输出 API 的核心入口，其参数设计兼顾了灵活性和易用性。该方法的签名与标准聊天补全 API 保持高度一致，同时添加了专门用于控制流式行为的参数。\n\n| 参数名称 | 类型 | 必需 | 默认值 | 说明 |\n|---------|------|------|--------|------|\n| `response_model` | `type[BaseModel]` | 是 | 无 | Pydantic 模型类，定义期望的输出结构 |\n| `messages` | `List[Dict]` | 是 | 无 | 聊天消息列表，格式同 OpenAI API |\n| `model` | `str` | 是 | 无 | 模型标识符，如 \"gpt-4o\" |\n| `max_retries` | `int` | 否 | 3 | 验证失败时的最大重试次数 |\n| `validation_context` | `Dict` | 否 | None | 传递给验证器的额外上下文 |\n| `tool_choice` | `str` | 否 | None | 强制模型使用特定工具 |\n| `stream` | `bool` | 否 | True | 启用流式输出模式 |\n| `**kwargs` | `Any` | 否 | None | 传递给底层 API 的其他参数 |\n\n方法的返回值是一个生成器对象，每次迭代产生当前已填充的响应模型实例。当模型生成新内容并通过验证时，该实例会更新相应字段的值。\n\n## Iterable 模式\n\n### 功能说明\n\nIterable 模式是 Instructor 提供的另一种流式输出实现，专门针对需要生成多个结构化对象的场景。与 Partial 模式不同，Iterable 模式允许模型生成一个序列中的多个项目，每个项目独立验证并在生成后立即可用。这种模式特别适合处理列表生成、批量提取、连续问答等任务。\n\n在 Iterable 模式的工作流程中，模型可以逐步输出多个对象，每个对象都是完整的 Pydantic 模型实例。当第一个对象完成生成并通过验证后，它会被立即返回给调用者，同时模型继续生成后续对象。这种方式的优势在于解耦了对象的生成顺序和可用性，允许应用程序在等待完整列表生成的同时处理已生成的项目。\n\nIterable 模式的核心实现位于 `instructor/dsl/iterable.py` 文件中，该实现处理了迭代器协议的所有复杂性，包括状态管理、错误恢复和生成终止条件的判断。开发者无需关心这些底层细节，只需专注于处理生成的对象。\n\n### 使用示例\n\n以下示例展示了如何使用 Iterable 模式从文本中提取多个实体信息：\n\n```python\nfrom instructor import from_provider\nfrom pydantic import BaseModel\nfrom typing import List\n\n# 初始化 Instructor 客户端\nclient = from_provider(\"openai/gpt-4o\")\n\n# 定义单个实体的数据模型\nclass ExtractedEntity(BaseModel):\n name: str\n entity_type: str\n confidence: float\n\n# 使用 create_iterable 方法处理多实体提取\nresponse = client.chat.completions.create_iterable(\n model=\"gpt-4o\",\n response_model=ExtractedEntity,\n messages=[\n {\"role\": \"user\", \"content\": \"从以下文本中提取所有提到的组织和人员：...\"}\n ]\n)\n\n# 处理每个提取的实体\nfor entity in response:\n print(f\"提取实体: {entity.name}\")\n print(f\"类型: {entity.entity_type}\")\n print(f\"置信度: {entity.confidence}\")\n```\n\n这个示例演示了 Iterable 模式在信息提取任务中的应用。在实际部署中，开发者可以实现更复杂的处理逻辑，如将提取的实体存储到数据库、实时更新用户界面或进行后续的关联分析。\n\n### 与 Partial 模式的对比\n\nPartial 和 Iterable 模式虽然都是流式输出功能，但它们的设计目标和适用场景有显著差异。理解这些差异有助于开发者选择最适合特定应用需求的模式。\n\n| 特性 | Partial 模式 | Iterable 模式 |\n|------|-------------|---------------|\n| 输出结构 | 单个模型实例逐步更新 | 多个独立模型实例序列 |\n| 适用场景 | 长文本、复杂嵌套结构 | 列表生成、批量提取 |\n| 数据可用性 | 字段级实时更新 | 对象级完成后可用 |\n| 模型消耗 | 较低（共享单个请求） | 取决于对象数量 |\n| 验证时机 | 部分内容即时验证 | 完整对象生成后验证 |\n\n## 实现原理\n\n### 部分模型（Partial Model）\n\nInstructor 的流式输出系统建立在 Pydantic 的部分模型（Partial Model）概念之上。部分模型是 Pydantic `BaseModel` 的一个特殊变体，它允许模型字段在完全填充之前就存在实例。这种设计支持增量数据填充场景，与传统的需要完整数据才能实例化的模型形成对比。\n\n部分模型的实现利用了 Python 的类型注解和描述符协议。当模型实例被创建但某些字段尚未赋值时，这些字段保持为特殊的占位状态。Instructor 的响应处理器会追踪哪些字段已被填充，哪些仍在等待数据，并在每次新的数据到达时更新实例状态。\n\n这种实现方式的一个关键优势是它与 Pydantic 的验证系统完全兼容。即使只有部分字段被填充，Instructor 仍然会对已填充的字段执行验证逻辑，确保数据的有效性和一致性。如果某个字段的验证失败，系统会触发相应的错误处理流程，可能是重试当前字段或跳过该字段继续处理其他内容。\n\n### 验证与重试机制\n\n流式输出中的验证机制面临着独特的挑战，因为部分数据可能不符合完整的验证规则，但这些数据在最终完成时将是有效的。为了处理这种情况，Instructor 实现了智能化的验证策略，在严格性和灵活性之间取得平衡。\n\n```mermaid\ngraph TD\n A[接收增量数据] --> B{字段完整？}\n B -->|是| C[执行完整验证]\n B -->|否| D[检查必填字段]\n C --> E{验证通过？}\n E -->|是| F[更新模型实例]\n E -->|否| G{重试次数<限制？}\n G -->|是| H[发送修正请求]\n G -->|否| I[抛出验证异常]\n D --> F\n H --> A\n```\n\n验证过程首先检查已填充的字段是否满足其约束条件。对于可选字段，即使没有数据也会通过验证；对于必填字段，系统会等待足够的数据到达后才进行验证。一旦所有必填字段都被填充且通过验证，部分模型就可以被安全地传递给应用程序。\n\n重试机制是流式输出可靠性的重要保障。当验证失败且错误表明是暂时性问题（如格式不完整或内容不符合约束）时，Instructor 会自动重试请求，并在重试时附带错误信息作为上下文，帮助模型修正之前的错误输出。\n\n## 高级用法\n\n### 与钩子（Hooks）集成\n\nInstructor 的钩子系统与流式输出功能深度集成，提供了在处理流程的各个阶段插入自定义逻辑的能力。钩子允许开发者在响应处理、数据验证、错误处理等关键时刻执行自定义代码，实现日志记录、性能监控、内容过滤等辅助功能。\n\n流式输出场景下的钩子使用方式与非流式场景基本一致，但钩子接收的参数可能因部分数据的性质而有所不同。例如，一个用于记录进度的钩子可能在每次部分更新时被调用，并接收当前已更新的字段列表作为参数。以下是一个集成钩子的示例：\n\n```python\nfrom instructor import from_provider, Hooks\n\ndef on_partial_update(partial_data):\n print(f\"部分更新接收 - 已填充字段: {list(partial_data.model_dump(exclude_none=True).keys())}\")\n\n# 定义钩子配置\nhooks = Hooks(on_partial_update=on_partial_update)\n\n# 在流式调用中使用钩子\nresponse = client.chat.completions.create_partial(\n model=\"gpt-4o\",\n response_model=UserProfile,\n messages=[...],\n hooks=hooks\n)\n```\n\n### 错误处理策略\n\n流式输出中的错误处理需要考虑实时性和上下文相关性特点。与批处理模式不同，流式场景下的错误通常需要在数据仍在生成时被捕获和处理，否则可能导致用户体验的中断或数据丢失。Instructor 提供了多层次的错误处理机制，以适应不同的故障场景。\n\n在验证错误的情况下，如果设置了 `max_retries` 参数，Instructor 会自动尝试修复问题并继续生成过程。这种自动修复能力依赖于底层模型的上下文理解能力，当错误信息被作为上下文反馈给模型时，模型通常能够理解问题所在并生成更符合要求的输出。如果重试次数耗尽仍未通过验证，系统会抛出异常，应用程序应准备好捕获并优雅地处理这些异常。\n\n对于网络错误或服务不可用等外部问题，Instructor 利用 tenacity 库实现的重试逻辑来处理。这些错误通常是暂时性的，通过指数退避策略进行重试可以有效提高请求成功率。开发者在配置重试策略时应考虑应用场景的实时性要求，在可靠性和响应速度之间做出权衡。\n\n## 最佳实践\n\n### 性能优化建议\n\n在使用 Instructor 流式输出功能时，遵循一定的性能优化实践可以显著提升应用的响应速度和资源利用效率。首先，应该根据实际需求选择合适的流式模式：对于需要实时看到部分结果的场景使用 Partial 模式，对于可以等待完整对象生成后再处理的场景使用 Iterable 模式。\n\n模型选择对性能有直接影响。较大的模型通常能生成更准确的结果，但响应速度和成本也相应增加。在需要高吞吐量的场景中，可以考虑使用较小但足够准确的模型，或者先使用小模型进行快速验证，再在必要时切换到大模型进行精调。\n\n网络连接质量对流式输出的用户体验至关重要。建议使用可靠的连接并进行适当的超时配置。对于需要处理不稳定网络环境的应用，可以实现连接重试逻辑和断点续传机制，确保在网络中断后能够快速恢复处理。\n\n### 常见陷阱与规避\n\n流式输出实现中的常见陷阱之一是在处理部分数据时过早地假设数据完整性。开发者应该始终检查字段是否为 `None` 或使用 Pydantic 的 `model_dump(exclude_none=True)` 方法来获取已填充的数据。忽略这些检查可能导致应用程序在使用未完成的字段值时出现错误。\n\n另一个常见问题是未能正确处理验证失败的情况。在流式场景中，模型可能在首次尝试时生成不符合验证规则的内容，这并不一定表示系统故障。通过设置合理的 `max_retries` 值并实现适当的回退逻辑，可以有效处理这些情况，同时保持良好的用户体验。\n\n资源管理也是需要关注的问题。长时间运行的流式请求会占用网络连接和内存资源，如果应用程序同时处理大量并发请求，可能会导致资源耗尽。建议实现适当的请求限制机制，并确保在使用完毕后正确关闭流式连接。\n\n## 参考资料\n\n本页面内容基于 Instructor 项目的源码和文档生成，以下是主要参考资料：\n\n- 部分模式实现源码：`instructor/dsl/partial.py` 资料来源：[instructor/dsl/partial.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/partial.py)\n- 可迭代模式实现源码：`instructor/dsl/iterable.py` 资料来源：[instructor/dsl/iterable.py](https://github.com/567-labs/instructor/blob/main/instructor/dsl/iterable.py)\n- 部分模式文档：`docs/concepts/partial.md` 资料来源：[docs/concepts/partial.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/partial.md)\n- 可迭代模式文档：`docs/concepts/iterable.md` 资料来源：[docs/concepts/iterable.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/iterable.md)\n- 流式输出示例代码：`examples/partial_streaming/run.py` 资料来源：[examples/partial_streaming/run.py](https://github.com/567-labs/instructor/blob/main/examples/partial_streaming/run.py)\n- 钩子系统文档：`examples/hooks/README.md` 资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md)\n\n---\n\n\n\n## 批处理\n\n### 相关页面\n\n相关主题：[提供商集成](#page-providers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/batch/__init__.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/__init__.py)\n- [instructor/batch/processor.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/processor.py)\n- [instructor/batch/providers/openai.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/providers/openai.py)\n- [instructor/batch/providers/anthropic.py](https://github.com/567-labs/instructor/blob/main/instructor/batch/providers/anthropic.py)\n- [docs/concepts/batch.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/batch.md)\n- [examples/batch_api/run_batch_test.py](https://github.com/567-labs/instructor/blob/main/examples/batch_api/run_batch_test.py)\n \n\n# 批处理\n\n## 概述\n\n批处理（Batching）是 Instructor 库提供的一项高级功能，允许用户将多个 LLM 请求批量提交到各大模型提供商，从而显著提升大规模数据处理的效率。与实时交互式 API 调用不同，批处理作业会在后台异步执行，适用于需要对大量数据进行结构化提取、转换或分类的场景。Instructor 通过统一的 `BatchProcessor` 接口抽象了不同提供商（OpenAI、Anthropic、Google）的批处理实现，开发者无需关心底层细节即可完成跨平台批处理任务。资料来源：[examples/batch_api/README.md](examples/batch_api/README.md)\n\n## 核心架构\n\n### 组件结构\n\nInstructor 的批处理系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责说明 |\n|------|----------|----------|\n| BatchProcessor | `instructor/batch/__init__.py` | 统一的批处理入口，负责路由到具体 Provider |\n| OpenAI Batch Provider | `instructor/batch/providers/openai.py` | 处理 OpenAI 平台的批处理逻辑 |\n| Anthropic Batch Provider | `instructor/batch/providers/anthropic.py` | 处理 Anthropic 平台的批处理逻辑 |\n| run_batch_test.py | `examples/batch_api/run_batch_test.py` | 批处理功能测试脚本 |\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[用户创建批处理请求] --> B[BatchProcessor 接收请求]\n B --> C{Provider 检测}\n C -->|OpenAI| D[OpenAI Batch Provider]\n C -->|Anthropic| E[Anthropic Batch Provider]\n C -->|Google| F[Google Batch Provider]\n D --> G[生成 Provider 特定格式]\n E --> G\n F --> G\n G --> H[提交批处理作业]\n H --> I[保存 Batch ID]\n I --> J[返回控制权给用户]\n J --> K[用户轮询状态]\n K --> L[获取结果]\n```\n\n## BatchProcessor 核心功能\n\n### 主要特性\n\nBatchProcessor 提供了以下核心能力：\n\n- **统一 API 设计**：通过 `instructor.from_provider()` 自动检测提供商类型\n- **异步执行**：批处理作业在后台异步运行，不阻塞主线程\n- **Provider 检测**：自动识别 `provider/model-name` 格式中的提供商\n- **批量文件生成**：根据不同 Provider 生成符合其规范的 JSONL 格式文件\n- **任务状态管理**：保存批处理 ID 供后续状态查询使用\n\n### 使用示例\n\n```python\nfrom instructor.batch import BatchProcessor\nfrom openai import OpenAI\n\n# 初始化客户端和批处理器\nclient = instructor.from_provider(\"openai/gpt-4o-mini\")\nbatch_processor = BatchProcessor(client=client)\n\n# 创建批处理作业\nbatch_job = batch_processor.create(\n model=\"openai/gpt-4o-mini\",\n messages=test_messages,\n response_model=User\n)\n\n# 保存 Batch ID\nwith open(\"openai_batch_id.txt\", \"w\") as f:\n f.write(batch_job.id)\n```\n\n## 支持的模型提供商\n\n### OpenAI\n\n| 模型名称 | 资源来源 |\n|----------|----------|\n| `openai/gpt-4o-mini` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `openai/gpt-4o` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `openai/gpt-4-turbo` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n\n### Anthropic\n\n| 模型名称 | 资源来源 |\n|----------|----------|\n| `anthropic/claude-3-5-sonnet-20241022` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `anthropic/claude-3-opus-20240229` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `anthropic/claude-3-haiku-20240307` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n\n### Google\n\n| 模型名称 | 资源来源 |\n|----------|----------|\n| `google/gemini-2.0-flash-001` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `google/gemini-pro` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n| `google/gemini-pro-vision` | 资料来源：[examples/batch_api/README.md](examples/batch_api/README.md) |\n\n## Provider 特定实现\n\n### OpenAI Batch Provider\n\nOpenAI 的批处理采用 `client.beta.batch` 端点，生成符合 OpenAI 规范的批处理文件格式。处理流程包括：\n\n1. 接收消息列表和响应模型\n2. 将每个消息转换为 OpenAI Batch API 的 JSONL 格式\n3. 提交批处理作业到 OpenAI 端点\n4. 返回包含批处理 ID 的响应对象\n\n资料来源：[instructor/batch/providers/openai.py](instructor/batch/providers/openai.py)\n\n### Anthropic Batch Provider\n\nAnthropic 的批处理使用 `client.beta.messages.batches` 端点，属于 Beta API 范畴。需要特别注意：\n\n- 必须拥有 Anthropic API 访问权限\n- 可能存在地区可用性限制\n- 批处理速率限制与常规 API 分离\n\n资料来源：[instructor/batch/providers/anthropic.py](instructor/batch/providers/anthropic.py)\n\n### Google Batch Provider\n\nGoogle Gemini 的批处理目前默认为模拟模式运行。完整实现需要：\n\n- 配置 Google Cloud Storage (GCS)\n- 设置适当的 GCS 认证\n- 创建实际的 GCS 存储桶用于输入/输出\n\n资料来源：[examples/batch_api/README.md](examples/batch_api/README.md)\n\n## 命令行接口\n\nInstructor CLI 提供了便捷的批处理操作命令：\n\n```bash\n# 创建批处理作业\ninstructor batch create \\\n --messages-file messages.jsonl \\\n --model \"openai/gpt-4o-mini\" \\\n --response-model \"examples.User\" \\\n --output-file batch_requests.jsonl\n\n# 从文件提交批处理\ninstructor batch create-from-file \\\n --file-path batch_requests.jsonl \\\n --model \"openai/gpt-4o-mini\"\n```\n\n资料来源：[examples/batch_api/README.md](examples/batch_api/README.md)\n\n## 环境配置\n\n### API 密钥要求\n\n| 提供商 | 环境变量 | 必需性 |\n|--------|----------|--------|\n| OpenAI | `OPENAI_API_KEY` | 必须设置 |\n| Anthropic | `ANTHROPIC_API_KEY` | 必须设置 |\n| Google | `GOOGLE_API_KEY` | 必须设置 |\n\n### 直接传递密钥\n\n除了环境变量方式，Instructor 也支持在代码中直接传递 API 密钥：\n\n```python\nclient = instructor.from_provider(\"openai/gpt-4o\", api_key=\"sk-...\")\nclient = instructor.from_provider(\"anthropic/claude-3-5-sonnet\", api_key=\"sk-ant-...\")\nclient = instructor.from_provider(\"groq/llama-3.1-8b-instant\", api_key=\"gsk_...\")\n```\n\n## 常见错误处理\n\n### Provider 格式错误\n\n```\n❌ Error: Model must be in format 'provider/model-name'\n```\n\n**解决方案**：使用 `provider/model-name` 格式，例如 `openai/gpt-4o-mini`\n\n### 不支持的 Provider\n\n```\n❌ Unsupported provider: xyz\n```\n\n**解决方案**：当前仅支持 `openai`、`anthropic` 和 `google` 作为 Provider\n\n### 密钥未设置\n\n```\n❌ OPENAI_API_KEY is not set\n```\n\n**解决方案**：设置相应的环境变量或通过参数传递 API 密钥\n\n## 测试与验证\n\n### 测试脚本\n\n`examples/batch_api/run_batch_test.py` 提供完整的批处理功能测试：\n\n```bash\n# 测试 OpenAI\nexport OPENAI_API_KEY=\"your-openai-api-key\"\npython run_batch_test.py create --model \"openai/gpt-4o-mini\"\n\n# 测试 Anthropic\nexport ANTHROPIC_API_KEY=\"your-anthropic-api-key\"\npython run_batch_test.py create --model \"anthropic/claude-3-5-sonnet-20241022\"\n\n# 测试 Google (模拟模式)\npython run_batch_test.py create --model \"google/gemini-2.0-flash-001\"\n```\n\n### 查看支持模型\n\n```bash\npython run_batch_test.py list-models\n```\n\n## 与其他功能的集成\n\n### 与 Retries 的结合\n\n批处理支持 Instructor 的自动重试机制，当验证失败时会自动重试：\n\n```python\nbatch_job = batch_processor.create(\n model=\"openai/gpt-4o-mini\",\n messages=test_messages,\n response_model=User,\n max_retries=3 # 启用自动重试\n)\n```\n\n### 与 Validators 的结合\n\n批处理可以配合 Pydantic 验证器使用，确保输出符合预期结构：\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass User(BaseModel):\n name: str\n age: int\n\n @field_validator('age')\n def validate_age(cls, v):\n if v < 0:\n raise ValueError('Age must be positive')\n return v\n\nbatch_job = batch_processor.create(\n model=\"openai/gpt-4o-mini\",\n messages=test_messages,\n response_model=User\n)\n```\n\n## 最佳实践\n\n1. **批量大小控制**：根据 Provider 的速率限制调整批处理大小\n2. **响应模型设计**：使用清晰的 Pydantic 模型定义期望的输出结构\n3. **错误处理**：实现健壮的错误捕获和重试逻辑\n4. **状态监控**：定期轮询批处理状态以获取最新结果\n5. **成本优化**：选择合适的模型（如 gpt-4o-mini）以平衡成本和性能\n\n---\n\n\n\n## 钩子系统\n\n### 相关页面\n\n相关主题：[验证机制](#page-validation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n- [instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n- [docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n- [examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n \n\n# 钩子系统\n\n## 概述\n\nInstructor 的钩子系统是一个强大的事件监听与回调机制，允许开发者在 LLM 请求的完整生命周期中插入自定义逻辑。通过钩子，开发者可以监控请求状态、记录日志、统计 token 使用量、处理解析错误、捕获完成错误以及跟踪重试尝试。\n\n钩子系统的主要作用包括：\n\n- **请求监控**：在请求发送前获取完整的请求详情\n- **使用量统计**：追踪输入/输出 token 数量和成本\n- **错误处理**：捕获并处理解析错误和完成错误\n- **重试跟踪**：记录自动重试的次数和状态变化\n- **自定义扩展**：在任意生命周期节点插入业务逻辑\n\n资料来源：[examples/hooks/README.md](https://github.com/567-labs/instructor/blob/main/examples/hooks/README.md)\n\n## 架构设计\n\n### 钩子类型体系\n\nInstructor 的钩子系统采用分层架构设计，主要包含以下钩子类型：\n\n```mermaid\ngraph TD\n A[Hook 基类] --> B[HookStatistics]\n A --> C[HookBase]\n B --> D[TokenUsageHook]\n B --> E[RetryHook]\n C --> F[ParseErrorHook]\n C --> G[CompletionErrorHook]\n C --> H[RequestHook]\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n### 请求生命周期钩子流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Hooks as 钩子系统\n participant LLM as LLM API\n participant Validator as 验证器\n \n Client->>Hooks: 1. 触发 on_request 钩子\n Hooks->>Hooks: 记录请求详情和模型信息\n Client->>LLM: 2. 发送请求\n LLM-->>Client: 返回响应\n Client->>Hooks: 3. 触发 on_new_token 钩子\n Hooks->>Hooks: 记录 token 使用量\n Client->>Validator: 4. 验证响应\n alt 验证成功\n Client->>Hooks: 5. 触发 on_success 钩子\n else 验证失败\n Client->>Hooks: 5a. 触发 on_retry 钩子\n Client->>LLM: 6. 重试请求\n loop 直到成功或达到最大重试次数\n LLM-->>Client: 返回新响应\n Client->>Validator: 重新验证\n end\n alt 最终成功\n Client->>Hooks: 触发 on_success\n else 最终失败\n Client->>Hooks: 触发 on_parse_error 或 on_completion_error\n end\n end\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n## 核心钩子类型详解\n\n### 1. 请求钩子 (RequestHook)\n\n请求钩子允许在每次 API 调用时执行自定义逻辑，可用于日志记录、请求追踪等场景。\n\n**事件触发时机**：在请求发送到 LLM API 之前触发。\n\n```python\nfrom instructor.hooks import RequestHook\n\ndef my_request_hook(\n completion: Any,\n prompt: Union[str, List[Dict]],\n model: str,\n **kwargs: Any,\n) -> None:\n \"\"\"自定义请求钩子\"\"\"\n print(f\"请求发送至模型: {model}\")\n print(f\"提示词长度: {len(str(prompt))} 字符\")\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 2. Token 使用量钩子 (TokenUsageHook)\n\nToken 使用量钩子用于统计和记录 API 调用消耗的 token 数量及预估成本。\n\n**事件触发时机**：在收到响应后、解析完成前触发。\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| completion | Any | 原始 API 响应对象 |\n| prompt_tokens | int | 输入 prompt 消耗的 token 数 |\n| completion_tokens | int | 输出 completion 消耗的 token 数 |\n| total_tokens | int | 总 token 消耗量 |\n\n```python\nfrom instructor.hooks import TokenUsageHook\n\nclass MyTokenTracker(TokenUsageHook):\n def __init__(self):\n self.total_input_tokens = 0\n self.total_output_tokens = 0\n self.cost_per_1k_input = 0.0015 # GPT-4o 价格\n self.cost_per_1k_output = 0.002\n\n def __call__(\n self,\n completion: Any,\n prompt_tokens: int,\n completion_tokens: int,\n total_tokens: int,\n **kwargs: Any,\n ) -> None:\n self.total_input_tokens += prompt_tokens\n self.total_output_tokens += completion_tokens\n estimated_cost = (\n prompt_tokens * self.cost_per_1k_input / 1000 +\n completion_tokens * self.cost_per_1k_output / 1000\n )\n print(f\"预估成本: ${estimated_cost:.4f}\")\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n### 3. 解析错误钩子 (ParseErrorHook)\n\n解析错误钩子在响应无法被解析为目标 Pydantic 模型时触发。\n\n**事件触发时机**：当模型验证失败或响应格式不符合预期时触发。\n\n```python\nfrom instructor.hooks import ParseErrorHook\n\ndef handle_parse_error(\n completion: Any,\n response_model: Type[BaseModel],\n error: ValidationError,\n attempt: int,\n **kwargs: Any,\n) -> None:\n \"\"\"处理解析错误\"\"\"\n print(f\"解析错误 (尝试 {attempt}/{max_retries})\")\n print(f\"错误详情: {error}\")\n # 可选: 记录到监控系统\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 4. 完成错误钩子 (CompletionErrorHook)\n\n完成错误钩子在 LLM API 调用本身失败时触发，如网络错误、超时、API 限流等。\n\n**事件触发时机**：当 API 调用抛出异常时触发。\n\n```python\nfrom instructor.hooks import CompletionErrorHook\n\ndef handle_completion_error(\n completion: Optional[Any],\n error: Exception,\n attempt: int,\n **kwargs: Any,\n) -> None:\n \"\"\"处理 API 完成错误\"\"\"\n print(f\"API 错误 (尝试 {attempt}/{max_retries})\")\n print(f\"错误类型: {type(error).__name__}\")\n print(f\"错误信息: {str(error)}\")\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 5. 重试钩子 (RetryHook)\n\n重试钩子在触发自动重试时调用，可用于追踪重试行为和性能监控。\n\n**事件触发时机**：在每次重试开始前触发。\n\n```python\nfrom instructor.hooks import RetryHook\n\ndef track_retry(\n attempt: int,\n exception: Exception,\n **kwargs: Any,\n) -> None:\n \"\"\"追踪重试行为\"\"\"\n print(f\"触发重试 #{attempt}\")\n print(f\"原因: {type(exception).__name__}: {exception}\")\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n## 使用指南\n\n### 基础使用方式\n\n#### 方式一：使用装饰器注册钩子\n\n```python\nfrom instructor import from_openai\nfrom instructor.hooks import Hooks, hook\n\nclient = from_openai(OpenAI())\n\n@hook\ndef my_hooks(\n on_request: bool = True,\n on_success: bool = True,\n on_retry: bool = True,\n on_error: bool = True,\n **kwargs,\n) -> Hooks:\n # 每次请求时打印统计信息\n print(f\"Request sent to {kwargs.get('model', 'unknown')}\")\n return Hooks(\n on_new_token=lambda token, **kw: print(f\"Token: {token}\"),\n on_success=lambda response, **kw: print(\"Success!\"),\n )\n\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n response_model=User,\n hooks=my_hooks, # 传入钩子函数\n)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n#### 方式二：创建 Hooks 实例\n\n```python\nfrom instructor import Instructor\nfrom instructor.hooks import Hooks\n\ndef request_handler(completion, **kwargs):\n print(f\"📏 近似输入 Token 数量: {kwargs.get('estimated_tokens', 0)}\")\n\ndef success_handler(response, **kwargs):\n print(\"✅ 成功响应\")\n print(f\"响应类型: {type(response)}\")\n\nhooks = Hooks(\n on_request=request_handler,\n on_success=success_handler,\n)\n\nclient = Instructor(\n model=\"gpt-4o-mini\",\n hooks=hooks,\n)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n### 客户端级钩子配置\n\n在创建客户端时配置全局钩子：\n\n```python\nfrom instructor import from_openai\n\n# 全局钩子实例\nglobal_hooks = Hooks(\n on_request=lambda **kw: log_request(**kw),\n on_new_token=lambda token, **kw: track_token(token, **kw),\n on_success=lambda response, **kw: log_success(**kw),\n on_retry=lambda attempt, **kw: log_retry(attempt, **kw),\n on_parse_error=lambda error, **kw: alert_parse_error(error, **kw),\n on_completion_error=lambda error, **kw: alert_completion_error(error, **kw),\n)\n\nclient = from_openai(\n OpenAI(),\n hooks=global_hooks,\n)\n```\n\n资料来源：[docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n\n### 请求级钩子覆盖\n\n单个请求可以覆盖客户端级钩子：\n\n```python\nfrom instructor.hooks import Hooks\n\nrequest_hooks = Hooks(\n on_request=lambda **kw: print(f\"此请求使用模型: {kw.get('model')}\"),\n)\n\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"Extract user info\"}],\n response_model=User,\n hooks=request_hooks, # 仅此请求使用\n)\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n## 高级用法\n\n### 多钩子组合\n\n```python\nfrom instructor.hooks import Hooks\n\nclass StatisticsCollector:\n \"\"\"统计收集器\"\"\"\n def __init__(self):\n self.request_count = 0\n self.success_count = 0\n self.error_count = 0\n self.total_retries = 0\n\n def on_request(self, **kwargs):\n self.request_count += 1\n print(f\"📊 请求 #{self.request_count}\")\n\n def on_success(self, **kwargs):\n self.success_count += 1\n print(f\"✅ 成功 #{self.success_count}\")\n\n def on_retry(self, attempt, **kwargs):\n self.total_retries += 1\n print(f\"🔄 重试 #{attempt} (总计: {self.total_retries})\")\n\n def on_parse_error(self, error, **kwargs):\n self.error_count += 1\n print(f\"⚠️ 解析错误 #{self.error_count}: {error}\")\n\n# 创建收集器实例\nstats = StatisticsCollector()\n\nhooks = Hooks(\n on_request=stats.on_request,\n on_success=stats.on_success,\n on_retry=stats.on_retry,\n on_parse_error=stats.on_parse_error,\n)\n\n# 使用钩子\nclient = from_openai(OpenAI(), hooks=hooks)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n### 钩子与重试机制集成\n\n钩子系统与 Instructor 的自动重试机制深度集成：\n\n```mermaid\ngraph LR\n A[请求发送] --> B{验证成功?}\n B -->|是| C[触发 on_success]\n B -->|否| D{还有重试次数?}\n D -->|是| E[触发 on_retry]\n E --> F[重新发送请求]\n F --> A\n D -->|否| G{错误类型}\n G -->|解析错误| H[触发 on_parse_error]\n G -->|API错误| I[触发 on_completion_error]\n```\n\n```python\nfrom instructor.hooks import Hooks\n\ndef retry_logger(attempt, exception, **kwargs):\n \"\"\"记录重试详情\"\"\"\n print(f\"🔄 重试 #{attempt}\")\n print(f\" 异常类型: {type(exception).__name__}\")\n print(f\" 异常信息: {str(exception)[:100]}\")\n\nhooks = Hooks(\n on_retry=retry_logger,\n)\n\n# Instructor 会自动使用钩子在重试时通知\nuser = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"...\"}],\n response_model=User,\n max_retries=3, # 启用自动重试\n hooks=hooks,\n)\n```\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n### 条件性钩子执行\n\n```python\nfrom instructor.hooks import Hooks\nfrom functools import partial\n\ndef log_if_error(error, **kwargs):\n \"\"\"仅在错误发生时记录\"\"\"\n print(f\"⚠️ 错误: {error}\")\n\ndef log_every_request(model, **kwargs):\n \"\"\"记录所有请求\"\"\"\n print(f\"📤 请求: {model}\")\n\ndef conditional_hooks_factory(condition: bool):\n \"\"\"根据条件返回不同的钩子\"\"\"\n if condition:\n return Hooks(\n on_request=log_every_request,\n on_error=log_if_error,\n )\n return Hooks()\n\n# 根据业务逻辑选择钩子\nhooks = conditional_hooks_factory(debug_mode=True)\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n## Hooks 类 API 参考\n\n### 构造函数参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| on_request | Callable | None | 请求发送前调用的钩子 |\n| on_new_token | Callable | None | 每个新 token 生成时调用 |\n| on_success | Callable | None | 验证成功时调用 |\n| on_retry | Callable | None | 触发重试时调用 |\n| on_parse_error | Callable | None | 解析错误时调用 |\n| on_completion_error | Callable | None | API 完成错误时调用 |\n\n### on_request 钩子参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| completion | Any | 响应对象 |\n| prompt | Union[str, List[Dict]] | 发送的提示词 |\n| model | str | 使用的模型名称 |\n| **kwargs | Any | 其他扩展参数 |\n\n### on_success 钩子参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| response | BaseModel | 解析后的响应模型实例 |\n| completion | Any | 原始响应对象 |\n| **kwargs | Any | 其他扩展参数 |\n\n### on_retry 钩子参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| attempt | int | 当前重试次数 |\n| exception | Exception | 导致重试的异常对象 |\n| **kwargs | Any | 其他扩展参数 |\n\n资料来源：[instructor/core/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/core/hooks.py)\n\n## 最佳实践\n\n### 1. 钩子函数应保持轻量\n\n```python\n# ✅ 推荐：轻量级钩子\ndef quick_log(**kwargs):\n logger.info(f\"Model: {kwargs.get('model')}\")\n\n# ❌ 避免：重量级操作在钩子中\ndef heavy_hook(**kwargs):\n # 不要在钩子中进行复杂计算或网络请求\n result = some_external_api_call() # 这会影响性能\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n### 2. 使用类封装状态\n\n```python\nclass HookManager:\n \"\"\"钩子管理器 - 封装状态和逻辑\"\"\"\n \n def __init__(self, output_path: str):\n self.output_path = output_path\n self.metrics = []\n \n def create_hooks(self) -> Hooks:\n return Hooks(\n on_request=self._handle_request,\n on_success=self._handle_success,\n on_error=self._handle_error,\n )\n \n def _handle_request(self, **kwargs):\n self.metrics.append({\"type\": \"request\", **kwargs})\n \n def _handle_success(self, response, **kwargs):\n self.metrics.append({\"type\": \"success\"})\n \n def _handle_error(self, error, **kwargs):\n self.metrics.append({\"type\": \"error\", \"error\": str(error)})\n```\n\n资料来源：[instructor/hooks.py](https://github.com/567-labs/instructor/blob/main/instructor/hooks.py)\n\n### 3. 分离关注点\n\n```python\n# 不同的关注点使用不同的钩子处理器\nclass RequestLogger:\n def __call__(self, **kwargs):\n logging.info(f\"Request: {kwargs}\")\n\nclass MetricsCollector:\n def __call__(self, **kwargs):\n prometheus.counter(\"instructor_requests\").inc()\n\nclass AlertManager:\n def __call__(self, error, **kwargs):\n sentry.capture_exception(error)\n\n# 组合使用\nhooks = Hooks(\n on_request=RequestLogger(),\n on_success=MetricsCollector(),\n on_error=AlertManager(),\n)\n```\n\n资料来源：[docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n\n### 4. 异常安全\n\n```python\ndef safe_hook(func):\n \"\"\"包装钩子以确保异常安全\"\"\"\n def wrapper(*args, **kwargs):\n try:\n func(*args, **kwargs)\n except Exception as e:\n # 记录错误但不阻止流程\n logging.error(f\"Hook error: {e}\")\n return wrapper\n\nhooks = Hooks(\n on_request=safe_hook(my_request_hook),\n on_success=safe_hook(my_success_hook),\n)\n```\n\n## 常见应用场景\n\n### 场景一：API 使用量监控\n\n```python\nfrom instructor.hooks import Hooks\n\nclass UsageMonitor:\n def __init__(self):\n self.total_tokens = {\"prompt\": 0, \"completion\": 0}\n \n def __call__(self, **kwargs):\n self.total_tokens[\"prompt\"] += kwargs.get(\"prompt_tokens\", 0)\n self.total_tokens[\"completion\"] += kwargs.get(\"completion_tokens\", 0)\n print(f\"累计: 输入={self.total_tokens['prompt']}, 输出={self.total_tokens['completion']}\")\n\nhooks = Hooks(\n on_new_token=UsageMonitor(),\n)\n```\n\n### 场景二：调试响应内容\n\n```python\ndef debug_hook(response, completion, **kwargs):\n \"\"\"调试钩子：打印响应详情\"\"\"\n print(\"=\" * 50)\n print(f\"响应类型: {type(response)}\")\n print(f\"原始响应: {completion}\")\n print(\"=\" * 50)\n\nhooks = Hooks(\n on_success=debug_hook,\n)\n```\n\n### 场景三：性能追踪\n\n```python\nimport time\n\nclass PerformanceTracker:\n def __init__(self):\n self.start_time = None\n \n def on_request(self, **kwargs):\n self.start_time = time.time()\n \n def on_success(self, response, **kwargs):\n elapsed = time.time() - self.start_time\n print(f\"⏱️ 响应时间: {elapsed:.2f}秒\")\n \n def on_retry(self, attempt, **kwargs):\n print(f\"🔄 第 {attempt} 次重试...\")\n\nhooks = Hooks(\n on_request=PerformanceTracker().on_request,\n on_success=PerformanceTracker().on_success,\n on_retry=PerformanceTracker().on_retry,\n)\n```\n\n资料来源：[examples/hooks/run.py](https://github.com/567-labs/instructor/blob/main/examples/hooks/run.py)\n\n## 总结\n\nInstructor 的钩子系统提供了一套完整的事件监听机制，覆盖了 LLM 请求的完整生命周期。通过合理使用钩子，开发者可以实现：\n\n- **可观测性**：监控请求、响应、错误和性能指标\n- **可追溯性**：记录详细的操作日志用于审计\n- **自愈能力**：结合重试机制自动处理临时性故障\n- **业务扩展**：在任意生命周期节点插入自定义逻辑\n\n钩子系统设计简洁、API 清晰，与 Instructor 的核心功能深度集成，是构建生产级 LLM 应用不可或缺的组件。\n\n资料来源：[docs/concepts/hooks.md](https://github.com/567-labs/instructor/blob/main/docs/concepts/hooks.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：567-labs/instructor\n\n摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Documentation (at least Google-related) is an outdated mess.。\n\n## 1. 安装坑 · 来源证据：Documentation (at least Google-related) is an outdated mess.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess.\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v1.13.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 配置坑 · 来源证据：v1.12.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：v1.14.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v1.14.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v1.14.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：v1.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：v1.14.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Catching IncompleteOutputException : not possible as presently documented / tested.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Catching IncompleteOutputException : not possible as presently documented / tested.\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc0f4256859740f8a4cacd1731514783 | https://github.com/567-labs/instructor/issues/2273 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b982358c78a346bfaa26b428e00968bb | https://github.com/567-labs/instructor/issues/2291 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：bump lightllm upper bound for recent vulnerabililties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bump lightllm upper bound for recent vulnerabililties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ae9c53479204c778e56a8b4b3feb404 | https://github.com/567-labs/instructor/issues/2290 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：logger.debug in response.py leaks api_key verbatim via new_kwargs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：logger.debug in response.py leaks api_key verbatim via new_kwargs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2076a35fb27a4c119141e9f57acdf9bc | https://github.com/567-labs/instructor/issues/2265 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry m…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry message\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ab343e8383b4d89bbe8eeea25cc69d8 | https://github.com/567-labs/instructor/issues/2277 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.14.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.14.5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e73ef57918504fe88cf0af969c414ca1 | https://github.com/567-labs/instructor/releases/tag/v1.14.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：v1.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef102fc17ae84e319f80cfd4cc306eaa | https://github.com/567-labs/instructor/releases/tag/v1.15.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：567-labs/instructor\n\n摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Documentation (at least Google-related) is an outdated mess.。\n\n## 1. 安装坑 · 来源证据：Documentation (at least Google-related) is an outdated mess.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess.\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v1.13.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 配置坑 · 来源证据：v1.12.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：v1.14.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v1.14.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v1.14.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：v1.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：v1.14.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Catching IncompleteOutputException : not possible as presently documented / tested.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Catching IncompleteOutputException : not possible as presently documented / tested.\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc0f4256859740f8a4cacd1731514783 | https://github.com/567-labs/instructor/issues/2273 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b982358c78a346bfaa26b428e00968bb | https://github.com/567-labs/instructor/issues/2291 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：bump lightllm upper bound for recent vulnerabililties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bump lightllm upper bound for recent vulnerabililties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ae9c53479204c778e56a8b4b3feb404 | https://github.com/567-labs/instructor/issues/2290 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：logger.debug in response.py leaks api_key verbatim via new_kwargs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：logger.debug in response.py leaks api_key verbatim via new_kwargs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2076a35fb27a4c119141e9f57acdf9bc | https://github.com/567-labs/instructor/issues/2265 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry m…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry message\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ab343e8383b4d89bbe8eeea25cc69d8 | https://github.com/567-labs/instructor/issues/2277 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.14.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.14.5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e73ef57918504fe88cf0af969c414ca1 | https://github.com/567-labs/instructor/releases/tag/v1.14.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：v1.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef102fc17ae84e319f80cfd4cc306eaa | https://github.com/567-labs/instructor/releases/tag/v1.15.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# instructor - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 instructor 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: structured outputs for llms 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-providers：提供商集成。围绕“提供商集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-providers\n输入：用户提供的“提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-providers：Step 5 必须围绕“提供商集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/567-labs/instructor\n- https://github.com/567-labs/instructor#readme\n- README.md\n- instructor/__init__.py\n- mkdocs.yml\n- pyproject.toml\n- requirements.txt\n- docs/installation.md\n- examples/simple-extraction/user.py\n- docs/getting-started.md\n- docs/learning/getting_started/first_extraction.md\n- instructor/core/client.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 instructor 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：567-labs/instructor\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install instructor\n```\n\n来源：https://github.com/567-labs/instructor#readme\n\n## 来源\n\n- repo: https://github.com/567-labs/instructor\n- docs: https://github.com/567-labs/instructor#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_8e661cfaee704158990079c366c444a8"
}