跳到内容

如何贡献 🏗️

哪些贡献？

  • 文档贡献对我们非常有价值！
  • 示例。向我们展示您使用 Outlines 做了什么 :)
  • 在 issue tracker 中提交附带最小工作示例的错误报告
  • 错误修复总是乐于评审的。
  • 新功能。请先发起新的 讨论，或先与我们聊天！

请注意，issue tracker 仅用于可操作项。如有疑问，请发起 讨论 或 与我们交流。

如何贡献？

设置

首先，在 GitHub 上 派生仓库，然后将派生仓库克隆到本地

git clone git@github.com/YourUserName/outlines.git
cd outlines

创建新的虚拟环境

如果您使用 uv:

uv venv
source .venv/bin/activate
alias pip="uv pip" # ... or just remember to prepend any pip command with uv in the rest of this guide

如果您使用 venv:

python -m venv .venv
source .venv/bin/activate

如果您使用 conda:

conda env create -f environment.yml

然后以可编辑模式安装依赖项，并安装 pre-commit 钩子

pip install -e ".[test]"
pre-commit install
如果您有 GPU 并希望运行 vLLM 测试，则需要运行

pip install -e ".[test-gpu]"

代替。

Outlines 为不同的受支持后端提供了可选依赖项，您可以使用以下命令安装

pip install ".[vllm]"

受支持的可选依赖项列表可在安装指南中找到。

使用 VSCode DevContainer / GitHub Codespaces

如果您需要一个完全预配置的开发环境，您可以使用 VSCode DevContainers 或 GitHub Codespaces。

VSCode DevContainer

  1. 确保您的机器上正在运行 Docker daemon。
  2. 在 VSCode 中安装 Dev Containers 扩展。
  3. 在 VSCode 中打开 Outlines 仓库。当提示时，选择在容器中重新打开（或按 F1 并选择“Remote-Containers: Reopen in Container”）。
  4. 运行常规设置步骤。您的环境将不会因缺少系统依赖项而报错！

GitHub Codespaces

  1. 导航到 GitHub 上的 Outlines 仓库。
  2. 点击Code按钮并选择Codespaces选项卡。
  3. 点击Create codespace on main（或您正在使用的其他分支）。
  4. GitHub 将启动一个预配置的云开发环境。

您将无法访问 GPU，但您可以在使用功能齐全的基于 Web 的 IDE 的同时，随时随地对项目进行基本贡献。

推送代码前

运行测试

pytest

并运行代码风格检查

pre-commit run --all-files

基准测试

Outlines 使用 asv 进行自动化基准测试。在合并拉取请求之前会自动运行基准测试，以防止性能下降。

您可以在本地使用以下命令运行基准测试套件

asv run --config benchmarks/asv.conf.json

注意事项

  • 如果您在配备 CUDA 的设备上，必须添加参数 --launch-method spawn
  • 未提交的代码不会进行基准测试，您必须先提交您的更改。

运行特定测试

asv run --config benchmarks/asv.conf.json -b bench_json_schema.JsonSchemaBenchmark.time_json_schema_to_fsm

分析特定测试

asv run --config benchmarks/asv.conf.json --profile -b bench_json_schema.JsonSchemaBenchmark.time_json_schema_to_fsm

与 origin/main 比较

get fetch origin
asv continuous origin/main HEAD --config benchmarks/asv.conf.json

ASV PR 行为

  • 查看 ASV 基准测试结果： 打开 workflow，查看 BENCHMARK RESULTS 部分。
  • 除非对最新提交运行了基准测试，否则无法合并。
  • 如果任何单个基准测试的性能下降超过 10%，则基准测试失败。
  • “Benchmark PR” workflow 在手动触发时运行，或者如果在 PR 中添加了 run_benchmarks 标签，则对每个提交都运行。

贡献文档

要处理文档，您需要安装相关的依赖项

pip install -r requirements-doc.txt

要在本地构建文档并提供服务，请在仓库根文件夹中运行以下命令

mkdocs serve

按照说明操作，您将能够在本地查看文档。每次您进行更改时，文档都会更新。

打开拉取请求

在您的派生仓库上创建新分支，提交并推送更改

git checkout -b new-branch
git add .
git commit -m "Changes I made"
git push origin new-branch

然后您可以在 GitHub 上 打开拉取请求。它应该会提示您这样做。您在分支上进行的后续每次更改都会更新拉取请求。

在您的贡献准备好之前，请随时打开草稿 PR，特别是如果您有问题和/或需要反馈。如果您需要帮助，请在 Discord 上告诉我们。