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

第16章 为 Instructor 做贡献:评估测试、问题报告与拉取请求指南

title: 为 Instructor 做贡献:评估、问题与拉取请求 description: 加入我们,通过评估、问题报告和拉取请求共同完善 Instructor 库。协作共建,贡献力量! 为 Instructor 做贡献¶ 我们热忱欢迎为 Instructor 做出贡献!本页列出了多种参与改进库的方式。 贡献方式¶ 评估测试(Evals)¶ 评估测试帮助我们监控 OpenAI 模型及 Instructor 库的质量。参与贡献的方法: 浏览现有评估:查看我们的 evals 目录 创建新评估:添加新的 pytest 测试,用于评估特定能力或边缘案例 遵循模式:参照现有评估的结构编写你的测试 提交拉取请求:我们将审查并整合你的评估 评估测试每周运行一次,结果会被追踪以监控长期性能变化。 报告问题¶ 若你遇到 bug 或任何问题,请在 GitHub 上提交 issue,并包含以下信息: 清晰且描述性强的标题 详细信息,包括: 你正在使用的 response_model 你发送的消息 你正在使用的模型 重现该问题的步骤 预期行为与实际行为的对比 你的环境详情(Python 版本、操作系统、包版本) 贡献代码¶ 我们欢迎拉取请求!流程如下: 对于小改动:可以直接提交 PR 对于大改动:先创建一个 issue 来讨论方案 寻找灵感?查看标记为 help wanted 或 good first issue 的 issues 搭建开发环境¶ 使用 UV(推荐)¶ UV 是一个快速的 Python 包安装器和解析器,能简化开发过程。 安装 UV(官方方法): # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" 以开发模式安装项目: # 克隆仓库 git clone https://github.com/YOUR-USERNAME/instructor.git cd instructor

# 安装开发依赖 uv sync --extra dev --extra docs 添加新依赖: # 添加项目依赖并更新 pyproject.toml 及 uv.lock uv add some-package

# 仅安装到当前环境,不更改项目元数据 uv pip install some-package 常用 UV 命令: # 更新 UV 本身 uv self update

# 校验 lock 文件并重新生成提交的需求导出文件 uv lock --check uv pip compile pyproject.toml -o requirements.txt 使用 Poetry¶ Poetry 提供全面的依赖管理和打包功能。 安装 Poetry: curl -sSL https://install.python-poetry.org | python3 - 安装依赖: # 克隆仓库 git clone https://github.com/YOUR-USERNAME/instructor.git cd instructor

# 安装开发依赖 poetry install --with dev,docs 使用 Poetry 工作: # 激活虚拟环境 poetry shell

# 在虚拟环境中运行命令 poetry run pytest

# 添加依赖 poetry add package-name

# 添加开发依赖 poetry add --group dev package-name 支持新的 LLM 提供商¶ 贡献指南列出了每个集成所使用的注册表、客户端和测试。Instructor 使用可选依赖来支持不同的 LLM 提供商。提供商客户端和处理程序位于 instructor/v2/providers/ 目录下。添加新提供商的步骤: 在 pyproject.toml 中添加依赖:当集成需要新软件包时,将其声明为项目额外依赖: [project.optional-dependencies] my-provider = ["my-provider-sdk>=1.0.0,<2.0.0"] 添加提供商标识和客户端:在 instructor/v2/core/providers.py 中的 Provider 添加一个值;如果提供商可以通过其基本 URL 检测,则扩展 get_provider 在 instructor/v2/providers/myprovider/client.py 中实现 from_myprovider,根据情况支持同步/异步 参照现有的提供商包,如 instructor/v2/providers/perplexity/ 实现模式处理程序: 在提供商包中添加 handlers.py,用于请求准备、验证重试和响应解析 使用 instructor/v2/core/decorators.py 中的 register_mode_handler 注册处理程序类 使用 instructor/v2/core/mode.py 中支持的模式;不要假设每个提供商都支持所有模式 声明提供商能力: 在 instructor/v2/core/provider_specs.py 的 PROVIDER_SPECS 中添加条目,包括 SDK 模块、别名、客户端工厂、处理程序模块和支持的模式 HANDLER_SPECS 由此清单派生,并由 instructor/v2/core/registry.py 用于惰性加载处理程序 连接公共工厂和 from_provider: 清单为 instructor/v2/__init__.py 提供 PUBLIC_FACTORY_ATTRS;同时更新 instructor/__init__.py 中的显式导出,保持可选 SDK 导入的惰性 在 instructor/v2/auto_client.py 的 _PROVIDER_BUILDERS 中注册提供商构建器以支持 from_provider。其支持的别名来自 ALIAS_TO_PROVIDER,但必须单独更新构建器映射 添加真实 API 测试和 CI 覆盖: 将提供商/模型、支持的模式、凭据环境变量和 SDK 导入路径添加到 tests/llm/shared_config.py 中的 PROVIDER_CONFIGS。参见 tests/llm/test_core_providers/README.md 了解共享的提取、流式和验证/重试测试 在 tests/llm/test_myprovider/ 中添加测试,覆盖共享套件未涉及的提供商特定行为。使用真实 API 调用,而非模拟的提供商响应 更新 .github/workflows/test.yml 中的凭据作业。对于共享测试,更新相应的作业(如 core-other),包括 secret 导出、PROVIDER_TEST_REQUIREMENTS、凭据跳过/运行条件以及初始/重试 pytest -k 过滤器 对于提供商特定的测试目录,添加一个包含 name、env_key 和 test_path 的 provider-tests 矩阵条目。与维护者协调仓库 secret;因缺少凭据而跳过的测试或未收集的测试不建立提供商覆盖率 记录安装方式: uv add "instructor[my-provider]" # 或使用 poetry uv add "instructor[my-provider]" 编写集成文档:在 docs/integrations/ 中添加页面,包含安装说明、完整示例和支持的模式 将该页面添加到 mkdocs.yml 的导航中 开发工作流¶ 分叉仓库:创建你自己的项目 fork 克隆并设置: git clone https://github.com/YOUR-USERNAME/instructor.git cd instructor git remote add upstream https://github.com/567-labs/instructor.git 创建分支: git checkout -b feature/your-feature-name 修改、测试并提交: # 运行测试 uv run pytest tests/ -k 'not llm and not openai' # 跳过 LLM 测试以加快本地开发

# 提交更改 git add . git commit -m "Your descriptive commit message" 保持更新并推送: git fetch upstream git rebase upstream/main git push origin feature/your-feature-name 创建拉取请求:提交带有清晰更改描述的 PR 实用脚本¶ scripts/ 目录包含有助于维护代码质量和文档的实用脚本。这些脚本已集成到 pre-commit 钩子中,也可手动运行。可用脚本¶ make_clean.py - Markdown 文件清理器¶ 通过移除特殊空白字符并将 em dash 替换为普通破折号来清理 Markdown 文件。 # 清理所有 Markdown 文件 python scripts/make_clean.py

# 预览更改而不修改文件 python scripts/make_clean.py --dry-run check_blog_excerpts.py - 博文章节摘录验证器¶ 确保所有博文章节都包含 标签,以便正确生成摘录。 # 检查所有博文章节 python scripts/check_blog_excerpts.py make_sitemap.py - 增强型文档站点地图生成器¶ 生成带有 AI 驱动内容分析和交叉链接建议的增强型站点地图(sitemap.yaml)。 # 使用默认设置生成站点地图 python scripts/make_sitemap.py

# 自定义设置 python scripts/make_sitemap.py \ --root-dir docs \ --output-file sitemap.yaml \ --max-concurrency 10 站点地图生成的要求: - OpenAI API 密钥(设置为 OPENAI_API_KEY 环境变量) - 额外依赖:openai, typer, rich, tenacity, pyyaml Pre-commit 集成¶ 这些脚本在提交过程中自动运行: Markdown 清理:在包含 docs/ 中 Markdown 文件的提交上运行 博文章节摘录验证:在包含博文章节文件的提交上运行 手动使用¶ 你可以手动运行脚本进行测试或一次性操作: # 测试 Markdown 清理 python scripts/make_clean.py --dry-run

# 检查博文章节摘录 python scripts/check_blog_excerpts.py

# 生成新的站点地图 python scripts/make_sitemap.py 关于每个脚本的详细文档,请参见项目仓库中的 scripts/README.md 文件。 使用 Cursor 构建 PR¶ Cursor 是一款 AI 驱动的代码编辑器,可以帮助你为 Instructor 做出贡献。 开始使用 Cursor: 从 cursor.sh 下载 Cursor 在 Cursor 中打开 Instructor 项目 Cursor 会自动检测 .cursor/rules/ 中的规则 使用 Cursor 规则: new-features-planning:帮助规划和结构化新功能 simple-language:编写清晰文档的准则 documentation-sync:确保文档与代码变更保持同步 使用 Cursor 创建 PR: 使用 Cursor 的 Git 集成创建新分支 借助 AI 辅助进行更改 创建包含以下内容的 PR: # 使用 GitHub CLI 创建 PR gh pr create -t "Your feature title" -b "Description of your changes" -r jxnl,ivanleomk 在 PR 描述中添加 此 PR 由 [Cursor](https://cursor.sh) 编写 使用 Cursor 的好处: AI 帮助生成符合我们样式指南的代码 简化 PR 创建流程 有助于维护文档标准 代码样式指南¶ 我们使用以下工具来维护代码质量: Ruff:用于 Lint 和格式化 ty:用于类型检查 Pre-commit:用于提交前的自动检查 # 安装 pre-commit 钩子 uv run pre-commit install 关键样式指南: - 使用严格类型 - 遵循导入顺序:标准库 → 第三方 → 本地 - 函数/变量使用 snake_case,类使用 PascalCase - 为公共 API 函数编写全面的文档字符串 传统注释¶ 在代码审查或编写提交信息时,我们使用传统注释以使反馈更清晰:

常见标签: - praise:突出积极方面 - suggestion:提出更改或改进建议 - question:请求澄清 - issue:指出需要修复的问题 - todo:记录稍后需处理的事项 - fix:解决某个问题 示例: suggestion: 使用验证器处理此字段 这将确保值始终被正确格式化。

question: 为什么不在这里使用异步处理? 我想知道这是否能提高性能。

fix: 纠正参数类型 它应该是 OpenAI 客户端实例,而不是字符串。 这种格式有助于每个人理解每条评论的目的和重要性。访问 conventionalcomments.org 了解更多信息。 传统提交¶ 我们使用传统提交信息来使项目历史清晰并自动生成变更日志。传统提交的结构如下: [可选 scope]:

[可选 body]

[可选 footer] 常见类型¶ feat:新功能 fix:bug 修复 docs:文档更改 style:格式更改 refactor:既不修复 bug 也不添加新功能的代码更改 test:添加或修复测试 chore:维护任务 示例¶ feat(openai): 添加流式响应支持

fix(anthropic): 解决工具调用响应格式问题

docs: 更新安装说明

test(evals): 添加新的递归 schema 测试用例 对于破坏性更改,在冒号前加感叹号: feat(api)!: 更改 from_openai 函数的返回类型 使用传统提交有助于自动生成发布说明,并使项目历史更易于导航。更多细节请参见 Conventional Commits 规范。 文档贡献¶ 我们高度重视文档改进: 文档结构:所有文档均为 Markdown 格式,位于 docs/ 目录 添加新页面:添加新页面时,将其包含在 mkdocs.yml 的正确部分中 本地预览:运行 mkdocs serve 以本地预览更改 样式指南: 按 10 年级阅读水平撰写(简单、清晰的语言) 包含可运行的代码示例 添加相关链接文档 使用一致的格式 确保每个代码示例完整,包含导入 良好的文档代码块示例: # 包含导入的完整示例 import instructor from pydantic import BaseModel # 定义你的模型 class Person(BaseModel): name: str age: int

# 创建补丁客户端 client = instructor.from_provider("openai/gpt-5-nano")

# 使用模型 person = client.create( model="gpt-5.4-mini", response_model=Person, messages=[ {"role": "user", "content": "Extract: John Doe is 25 years old"} ] )

print(person.name) # "John Doe" print(person.age) # 25 贡献者¶ 文档资源¶ 在处理文档时,以下资源可能有用: mkdocs serve:本地预览文档。在仓库根目录先运行 uv sync --extra docs。 代码块中的 hl_lines:高亮代码块中的特定行以引起注意: ```python hl_lines="2 3" def example(): # 此行被高亮 # 此行也被高亮 return "normal line" ``` Admonitions:为重要信息创建样式化提示框: !!! note "Optional Title" This is a note admonition.

!!! warning This is a warning. 了解更多文档特性,请查阅 MkDocs Material 文档。 感谢你为 Instructor 做出的贡献!

评论 (0)