instructor 项目协作开发指南：从命令、架构到发布的全流程规范

instructor 项目协作开发指南从命令、架构到发布的全流程规范【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本文档仓库根目录的 AGENT.md是 instructor 项目面向人类贡献者与 AI Agent如 Cursor的协作说明书覆盖开发环境的安装与测试命令、项目架构地图、代码风格约束、Conventional Commits 的 PR 规范以及完整的版本发布流程。读完本文你将能独立完成一个从「环境准备 → 代码修改 → 提交 PR → 更新 CHANGELOG → 发布新版本」的完整贡献闭环并理解 instructor 当前 v1/v2 双轨架构与统一的from_provider()客户端工厂背后的设计意图。一、环境准备与高频开发命令AGENT.md 将日常开发命令集中放在文档开头作为任何贡献者的第一站。instructor 采用uv作为主要包管理器同时兼容 PoetryPython 版本要求为3.9,4.0见 pyproject.toml。1.1 安装开发环境uv pip install -e .[dev] # 或使用 Poetry poetry install --with dev其中dev是一组可选的开发依赖见 pyproject.toml包括pytest、pytest-asyncio、coverage、jsonref、pytest-xdist、pre-commit、ty以及固定的anthropic0.93.0、xmltodict等用于跑测试、类型检查与静态分析。1.2 运行测试项目在 pyproject.toml 中注册了三类 pytest marker分别对应不同粒度的测试unit快速单元测试无外部依赖integration集成测试可能要求配置 API Keyllm真实调用 LLM 的测试会消耗额度。由此派生出以下测试命令# 运行全部测试 uv run pytest tests/ # 运行单个测试按路径与用例名精确定位 uv run pytest tests/path_to_test.py::test_name # 跳过 LLM 与 OpenAI 相关测试日常本地开发的默认姿势 uv run pytest tests/ -k not llm and not openai如果需要为某次运行临时引入依赖不改动环境AGENT.md 推荐使用uv run --withuv run --with pytest-asyncio --with anthropic pytest tests/...这与 AGENT.md 中不要 mock测试使用真实 API 调用的约定相辅相成——-k not llm的存在正是为了让没有 API Key 的贡献者也能快速跑通大部分测试。仓库中大量用例正是这样组织的例如 tests/v2/test_genai_config_reuse.py 这类确定性回归测试不需要真实调用即可验证配置复用语义。1.3 类型检查、Lint 与格式化# 类型检查使用 ty配置见 ty.toml / ty-tests.toml uv run ty check # Lint对源码、示例与测试统一检查 uv run ruff check instructor examples tests # 格式化Ruff 采用 Black 风格约定 uv run ruff format instructor examples testsAGENT.md 明确要求严格类型标注ty是仓库选定的类型检查器且ty0.0.44被固定进 dev 依赖。Lint/Format 的检查范围同时覆盖instructor库代码、examples示例与tests测试三处。1.4 构建文档# 本地热更新预览 uv run mkdocs serve # 生产构建正式发布文档 ./build_mkdocs.sh仓库根目录的 mkdocs.yml 是文档站配置docs 目录含concepts/、integrations/、examples/、blog/等即 mkdocs 的源内容build_mkdocs.sh负责生产环境的构建与部署。1.5 关于等待AGENT.md 特别提示当需要显式等待例如 CI 等待或等待外部进程完成时使用sleep seconds而不是其他非标准的挂起方式——这是给 Agent 的明确行为约定保证命令可预测、可审计。二、架构地图十分钟读懂 instructorAGENT.md 用极简篇幅勾勒出项目的架构骨架理解它能让后续的代码修改事半功倍。2.1 核心目录与职责Core核心instructor/本身即基于 Pydantic 的 LLM 结构化输出库。注意当前实现大量委托给 v2例如 instructor/core/client.py 仅有兼容导出真正的Instructor与AsyncInstructor位于 instructor/v2/core/client.py同样 instructor/auto_client.py 也只是把from_provider转发到 instructor/v2/auto_client.py。基类Instructor与AsyncInstructor同步/异步两种客户端定义于client.py。Provider 层instructor/providers/ 下为 OpenAI、Anthropic、Gemini、Cohere、Bedrock、Mistral、Groq、Writer、xAI 等各家的客户端文件client_*.py而 instructor/v2/providers/ 则承载 v2 架构下按 provider 拆分的 handler 与 client 实现并以 instructor/v2/core/provider_specs.py 中的ProviderSpec作为 provider 能力支持/不支持的模式、别名、SDK 模块、legacy 模式映射的唯一事实来源。工厂模式from_provider()负责自动识别 provider见下文。DSL 扩展instructor/dsl/ 提供 Partial流式局部结果、Iterable迭代输出、Maybe可空结果、Citation引用等扩展v2 对应实现位于 instructor/v2/dsl/。关键模块patch.py客户端打补丁、process_response.py响应解析v2 为v2/core/response.py、function_calls.py生成 schemav2 为v2/core/function_calls.py。2.2 懒加载导出__init__.py的工程设计从 instructor/init.py 可以看到顶层导出并非在 import 时立即加载而是维护了一张_LAZY_IMPORTS表通过模块级__getattr__按需导入如Instructor、from_provider、Mode、Partial等并在_add_optional_export中依据依赖包是否安装来条件暴露from_anthropic、from_gemini、from_bedrock等可选入口。这解释了 AGENT.md 中客户端创建统一走from_provider()的动机大量 provider 入口是可选依赖统一工厂可避免强依赖某一家的 SDK。2.3 统一客户端工厂from_provider()AGENT.md 明确约定永远使用instructor.from_provider(provider_name/model_name)而不是 provider 专属的from_openai()、from_anthropic()等方法。源码佐证如下instructor/v2/auto_client.pyclient instructor.from_provider(openai/gpt-4) client instructor.from_provider(anthropic/claude-3-sonnet) # 异步客户端 async_client instructor.from_provider(openai/gpt-4, async_clientTrue) # 携带缓存适配器AutoCache/RedisCache 等透明响应缓存 cache AutoCache(maxsize1000) client instructor.from_provider(openai/gpt-4, cachecache)其行为要点模型串格式必须为provider/model-nameprovider 与模型名缺一不可否则抛出ConfigurationError错误类型定义于 instructor/v2/core/errors.py支持通过api_key显式传 Key也支持在 kwargs 中透传 provider 专属选项若 provider 未注册会报出支持列表supported_providers取自ALIAS_TO_PROVIDER见 instructor/v2/core/provider_specs.py未安装对应 SDK 时会抛出带安装提示的ImportError/ConfigurationError。2.4 Mode 体系结构化输出的实现方式AGENT.md 虽未展开 Mode但它是理解 provider 差异的关键。在 instructor/v2/core/mode.py 中Mode枚举定义了全部结构化模式并归类为工具调用类tool_modes()TOOLS、TOOLS_STRICT、PARALLEL_TOOLS、ANTHROPIC_TOOLS、GEMINI_TOOLS、BEDROCK_TOOLS、COHERE_TOOLS、RESPONSES_TOOLS等JSON 类json_modes()JSON、JSON_SCHEMA、MD_JSON、ANTHROPIC_JSON、GEMINI_JSON、COHERE_JSON_SCHEMA、PERPLEXITY_JSON等另有 xAI、Mistral、Vertex AI 等专属模式以及被标记为 deprecated 的FUNCTIONS。不同 provider 的ProviderSpec会声明各自supported_modes/unsupported_modes与legacy_modes映射例如 OpenAI 兼容系将废弃的FUNCTIONS映射到TOOLS这是同一套 API 抽象多 provider的底层支撑。2.5 GenAI 请求所有权约定AGENT.md 特别记录了一条实现事实GenAI 请求参数的所有权——_clone_kwargs会在 mode handler 合并并翻译采样选项之前先深拷贝嵌套的generation_config以保证调用方传入的配置对象可复用、不会被 handler 原地修改对应回归测试在 tests/v2/test_genai_config_reuse.py。这提醒贡献者在处理 provider 请求参数时复制后再合并避免污染调用方对象。三、代码风格约定类型标注所有函数/方法要求严格类型标注结构化输出模型统一继承BaseModelPydantic v2。导入顺序标准库 → 第三方 → 本地模块三段式排列。格式化Ruff遵循 Black 风格ruff format可直接收敛。错误处理优先使用 instructor/exceptions.py 中的自定义异常v2 侧在 instructor/v2/core/exceptions.py并借助 Pydantic 校验仓库还有专门的向后兼容测试 tests/core/test_exception_backwards_compat.py。命名函数/变量snake_case类PascalCase。禁止 Mock测试一律使用真实 API 调用也因此要用-k not llm做本地过滤。客户端创建一律instructor.from_provider(provider/model)禁止 provider 专属工厂方法详见 2.3 节。仓库中的集成测试即遵循该约定例如 tests/llm/test_new_client.py 等。四、Pull Request 规范4.1 PR 标题Conventional CommitsPR 标题即 squash merge 的提交信息必须采用type(scope): short summary格式尽量控制在 70 字符以内使用祈使语气add、fix、update不以句号结尾若含破坏性变更在 type 或 scope 后加!如feat(api)!:。好的示例fix(openai): handle empty tool_calls in streaming feat(retry): add backoff for JSON parse failures docs(agents): add conventional commit PR title guidelines test(schema): cover nested union edge cases ci(ruff): enforce formatting in pre-commit常用 type 一览来自 AGENT.mdtype含义feat新功能fix缺陷修复docs仅文档改动refactor非修复非新功能的代码调整perf性能优化test新增/更新测试build构建系统或依赖变更ciCI 流水线变更chore维护性工作推荐的 scope就近选择Provideropenai、anthropic、gemini、vertexai、bedrock、mistral、groq、writer核心core、patch、process_response、function_calls、retry、dsl仓库层面docs、examples、tests、ci、build。4.2 PR 描述模板PR 描述保持精简、便于评审What1–3 句话说明改了什么Why为什么需要这次改动尽量关联 issueChanges3–7 条要点列出主要编辑Testing运行了什么测试或为什么没有运行。若 PR 由 Cursor 撰写须在描述中注明 This PR was written by Cursor。4.3 CHANGELOG 强制要求任何改变行为的 PR 都必须更新CHANGELOG.mdCHANGELOG.md 位于仓库根目录。规则如下在## [Unreleased]或进行中的版本小节下追加条目条目格式- **Area**: Short description of the change (#PR_NUMBER)按Security、Fixed、Added、Changed、Deprecated、Removed、Tests / CI分组纯文档或纯示例改动除非修复了用户可见问题不必写 CHANGELOG。五、版本发布流程AGENT.md 以v1.15.0为例给出了可执行的发布 SOP仓库当前版本号为1.17.1pyproject.toml确保 CI 通过在 merge 进 staging 前staging PR 的 CI 必须全绿合并通过 GitHub PR 将 staging 合并到 main提升版本号修改 pyproject.toml 中version X.Y.Z随后更新锁文件uv lock提交并打 tagtag 使用小写v前缀git add pyproject.toml uv.lock git commit -m chore(release): vX.Y.Z git tag vX.Y.Z git push origin main --tags创建 GitHub Release对 tag 创建 Release 会触发.github/workflows/python-publish.yml利用PYPI_TOKENsecret 自动构建并发布到 PyPI。版本号升档规则依据距上个 tag 以来的提交类型feat!:/fix!:/BREAKING→major主版本feat:→minor次版本fix:/chore:及其他 →patch补丁版本这解释了 4.1 节中破坏性变更必须加!的硬性要求——它直接驱动发布工具的版本决策。此外 scripts/prepare_release.py 与配套测试 tests/test_prepare_release.py 也在仓库中承担发布前的自动化检查职责。六、总结AGENT.md 虽短却是 instructor 仓库人机协作的枢纽文档它以一条命令清单覆盖了开发、测试、质检与文档构建的完整工具链以一张架构地图交代了 Core/v2、Provider、DSL、工厂模式与关键模块的分工以一份风格与 PR 规范保证了多贡献者包括 AI Agent产出的可评审性并以一套版本发布 SOP 将 Conventional Commits、CHANGELOG 与自动发布流水线串成闭环。对想要为 instructor 贡献代码或深入理解其工程治理的开发者来说这份文档就是最好的起点——按图索骥即可在 AGENT.md、pyproject.toml、instructor/v2/auto_client.py、instructor/v2/core/provider_specs.py 与 tests/ 之间自由穿行。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考