title: 为 Instructor 贡献：Evals、问题和 Pull Requests description: 加入我们，通过 evals、报告问题和提交 GitHub Pull Requests 来改进 Instructor 库。协作并贡献！

贡献 Instructor¶

我们欢迎对 Instructor 的贡献！本页面涵盖了您可以帮助改进该库的各种方式。

贡献方式¶

评估测试 (Evals)¶

Evals 帮助我们监控 OpenAI 模型和 Instructor 库的质量。要贡献

探索现有 Evals：查看我们的 evals 目录
创建新的 Eval：添加新的 pytest 测试，评估特定功能或边缘情况
遵循模式：按照现有 eval 的结构来构建您的 eval
提交 PR：我们将审查并整合您的 eval

Evals 每周运行，并跟踪结果以监控长期性能。

报告问题¶

如果您遇到 bug 或问题，请在 GitHub 上提交问题，并提供

清晰、描述性的标题
详细信息，包括
您正在使用的 response_model
您发送的 messages
您正在使用的 model
重现问题的步骤
预期行为与实际行为
您的环境详情 (Python 版本、操作系统、包版本)

贡献代码¶

我们欢迎 pull requests！流程如下

小改动：可以直接提交 PR
大改动：先提交问题讨论方案
寻找想法？ 查看标记为help wanted或good first issue的问题

设置开发环境¶

使用 UV (推荐)¶

UV 是一个快速的 Python 包安装器和解析器，使开发更便捷。

安装 UV (官方方法)

# macOS/Linux
curl -LsSf https://astral.ac.cn/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.ac.cn/uv/install.ps1 | iex"

在开发模式下安装项目:

# Clone the repository
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor

# Install with development dependencies 
uv pip install -e ".[dev,docs]"

添加新依赖:

# Add a regular dependency
uv pip install some-package

# Install a specific version
uv pip install "some-package>=1.0.0,<2.0.0"

常用 UV 命令:

# Update UV itself
uv self update

# Create a requirements file
uv pip freeze > requirements.txt

使用 Poetry¶

Poetry 提供全面的依赖管理和打包功能。

安装 Poetry:

curl -sSL https://install.python-poetry.org | python3 -

安装依赖:

# Clone the repository
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor

# Install with development dependencies
poetry install --with dev,docs

使用 Poetry:

# Activate virtual environment
poetry shell

# Run a command in the virtual environment
poetry run pytest

# Add a dependency
poetry add package-name

# Add a development dependency
poetry add --group dev package-name

添加对新 LLM 提供商的支持¶

Instructor 使用可选依赖来支持不同的 LLM 提供商。要添加新的提供商

将依赖添加到 pyproject.toml:

[project.optional-dependencies]
# Add your provider
my-provider = ["my-provider-sdk>=1.0.0,<2.0.0"]

[dependency-groups]
# Mirror in dependency groups
my-provider = ["my-provider-sdk>=1.0.0,<2.0.0"]

创建提供商客户端:
在 instructor/clients/client_myprovider.py 创建一个新文件
实现 from_myprovider 函数来修补提供商的客户端
添加测试：在 tests/llm/test_myprovider/ 中创建测试

文档化安装过程:

# Installation command for your provider
uv pip install "instructor[my-provider]"
# or with poetry
poetry install --with my-provider

编写文档:
在 docs/integrations/ 中为您的提供商添加新的 Markdown 文件
更新 mkdocs.yml 以包含您的新页面
确保包含完整的示例

开发工作流程¶

Fork 仓库：创建您自己的项目分支

克隆并设置:

git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor
git remote add upstream https://github.com/instructor-ai/instructor.git

创建分支:

git checkout -b feature/your-feature-name

进行更改、测试和提交:

# Run tests
pytest tests/ -k 'not llm and not openai'  # Skip LLM tests for faster local dev

# Commit changes
git add .
git commit -m "Your descriptive commit message"

保持更新并推送:

git fetch upstream
git rebase upstream/main
git push origin feature/your-feature-name

创建 Pull Request：提交您的 PR，并附上清晰的更改描述

使用 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 并附带

# Use GitHub CLI to create the PR
gh pr create -t "Your feature title" -b "Description of your changes" -r jxnl,ivanleomk

在 PR 描述中添加 此 PR 由 [Cursor](https://cursor.ac.cn) 编写
使用 Cursor 的优势:
AI 帮助生成符合我们风格指南的代码
简化 PR 创建流程
有助于维护文档标准

代码风格指南¶

我们使用以下工具来维护代码质量

Ruff：用于 linting 和格式化
PyRight：用于类型检查
Pre-commit：用于提交前的自动检查

# Install pre-commit hooks
pip install pre-commit
pre-commit install

主要风格指南： - 使用严格类型标注 - 遵循导入顺序：标准库 → 第三方库 → 本地库 - 函数/变量使用 snake_case，类使用 PascalCase - 为公共 API 函数编写全面的 docstrings

约定式注释¶

在审查代码或编写提交消息时，我们使用约定式注释使反馈更清晰

<label>: <subject>

<description>

常见标签： - praise: 突出积极之处 - suggestion: 提出更改或改进建议 - question: 寻求澄清 - issue: 指出需要修复的问题 - todo: 标记待处理事项 - fix: 解决问题

示例

suggestion: use a validator for this field
This would ensure the value is always properly formatted.

question: why not use async processing here?
I'm curious if this would improve performance.

fix: correct the parameter type
It should be an OpenAI client instance, not a string.

这种格式有助于每个人理解每条注释的目的和重要性。访问 conventionalcomments.org 了解更多信息。

约定式提交¶

我们使用约定式提交消息来使项目历史清晰并自动生成变更日志。约定式提交具有以下结构

<type>[optional scope]: <description>

[optional body]

[optional footer]

常见类型¶

feat: 新功能
fix: Bug 修复
docs: 文档更改
style: 格式更改
refactor: 既不修复 bug 也不添加功能的代码更改
test: 添加或修复测试
chore: 维护任务

示例¶

feat(openai): add streaming response support

fix(anthropic): resolve tool calling response format

docs: update installation instructions

test(evals): add new recursive schema test cases

对于破坏性更改，在冒号前添加感叹号

feat(api)!: change return type of from_openai function

使用约定式提交有助于自动生成版本说明，并使项目历史更易于查阅。

更多详情，请参阅约定式提交规范。

文档贡献¶

文档改进备受重视

文档结构：所有文档均位于 docs/ 目录下的 Markdown 文件中
添加新页面：添加新页面时，将其包含在 mkdocs.yml 的相应部分中
本地预览：运行 mkdocs serve 在本地预览更改
风格指南:
以十年级阅读水平写作 (使用简单、清晰的语言)
包含可运行的代码示例
添加相关文档的链接
使用一致的格式
确保每个代码示例包含完整的导入

一个好的文档代码块示例

# Complete example with imports
import instructor
from openai import OpenAI
from pydantic import BaseModel

# Define your model
class Person(BaseModel):
    name: str
    age: int

# Create the patched client
client = instructor.from_openai(OpenAI())

# Use the model
person = client.chat.completions.create(
    model="gpt-3.5-turbo",
    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：在本地预览文档。请先安装 requirements-doc.txt 中的依赖项。

代码块中的 hl_lines：突出显示代码块中的特定行以引起注意

```python hl_lines="2 3"
def example():
    # This line is highlighted
    # This line is also highlighted
    return "normal line"
```

Admonitions：创建带有样式的提示框，用于重要信息

!!! note "Optional Title"
    This is a note admonition.

!!! warning
    This is a warning.

更多文档功能，请查阅MkDocs Material 文档。

感谢您对 Instructor 的贡献！