# 为 PEFT 做贡献

我们非常欢迎对 PEFT 的贡献。如果您计划参与贡献，请阅读以下内容，以便让流程尽可能顺畅。

## 在提交 PR 之前进行讨论并获得批准

在提交拉取请求（包括草稿）之前，请在 [huggingface/peft](https://github.com/huggingface/peft/issues) 中打开或查找一个 issue，并讨论您提议的贡献。如果已存在相关 issue，且有人正在处理、已声明处理意向或已有一个开放的 PR，则您不应提交单独的 PR。请等待 PEFT 维护者或 Hugging Face 成员明确批准该提议。如果您打开了一个 issue，请确保描述的长度和复杂度与 issue 本身的复杂度相匹配。通常，附带复现步骤的简短描述比冗长的描述更有价值。

审批评论包含消息 `/peft-triage approved`。它还可以指定所分配贡献者的名称，例如 `/peft-triage approved username` 或 `/peft-triage approved @username`。如果您针对未分配给您的 issue 打开 PR，该 PR 将会被关闭。

在 PR 描述中，使用 `#123`、`huggingface/peft#123` 或 `https://github.com/huggingface/peft/issues/123` 链接已批准的公开 issue。作为例外，维护者可以指定某些长期讨论，这些讨论可以直接通过其完整的 GitHub URL 引用，而无需单独的批准评论。如果您引用了多个 issue 或讨论，一个有效的引用即可。

自动化工作流会检查 PR 是否关联了已批准的开放 issue 或讨论。未包含有效引用的 PR 将被自动关闭并附上说明。您可以获取 issue 批准、更新 PR 描述并重新打开同一个 PR；请勿创建替代 PR。如果您认为您的 PR 被错误关闭，请在该 PR 中 @ 维护者。

独立的过期机器人仍可能关闭不活跃的项目，即使其被标记为 `triaged`。如果您认为维护者忽略了您的贡献，可以提醒他们，但请勿在两周不活跃期结束前这样做。

## 安装

按照以下步骤开始贡献：

1. 点击仓库页面上的“Fork”按钮，[fork 该仓库](https://github.com/huggingface/peft)。这会在你的 GitHub 用户账户下创建一份代码副本。

2. 将您的 fork 克隆到本地磁盘，并将基础仓库添加为远程仓库。以下命令假设您已将公共 SSH 密钥上传到 GitHub。有关更多[信息](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)，请参阅以下指南。

   ```bash
   git clone git@github.com:<your Github handle>/peft.git
   cd peft
   git remote add upstream https://github.com/huggingface/peft.git
   ```

3. 创建一个新的分支来存放你的开发更改，并且在你处理的每个新 PR 中都这样做。

   首先，将你的 `main` 分支与 `upstream/main` 分支同步（更多详情请参阅 [GitHub 文档](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)）：

   ```bash
   git checkout main
   git fetch upstream
   git merge upstream/main
   ```

   当您的 `main` 分支同步完成后，从该分支创建一个新的分支：

   ```bash
   git checkout -b a-descriptive-name-for-my-changes
   ```

   不要**在** `main` 分支上工作。

4. 在为您创建的用于开发此库的 conda 或虚拟环境中，运行以下命令来设置开发环境：

   ```bash
   pip install -e ".[test]"
   ```

   （如果虚拟环境中已经安装了 PEFT，请在重新安装之前使用 `pip uninstall peft` 将其卸载。）

如果您是首次创建拉取请求，请遵循 GitHub 的 [创建拉取请求](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) 指南。

## 测试和代码质量检查

无论贡献类型如何（除非仅涉及文档），在创建 PR 之前，您都应运行测试和代码质量检查，以确保您的贡献不会破坏任何功能，并符合项目标准。

### 运行测试和检查

我们提供了一个 Makefile 来运行必要的测试。运行以下代码以执行单元测试：

```sh
make test
```

运行以下命令之一，仅检查或检查并修复代码质量和风格：

```sh
make quality  # just check
make style  # check and fix
```

运行 `make quality` 还会检查 PEFT 公共 API 中的所有方法/类（即 `peft.__all__` 中提到的所有内容）是否都在文档中有所提及。这些错误无法通过 `make style` 修复，你需要确保在文档中记录公共 API 中的新条目，才能解决此错误。

您还可以设置 [`pre-commit`](https://pre-commit.com/)，将这些修复作为 Git 提交钩子自动运行。

```bash
$ pip install pre-commit
$ pre-commit install
```

运行所有测试可能需要较长时间，因此在开发过程中，仅[运行与您的更改相关的测试](https://docs.pytest.org/en/6.2.x/usage.html#specifying-tests-selecting-tests)可能更高效，例如通过以下方式：

```sh
pytest tests/<test-file-name> -k <name-of-test>
```

这应该会快得多，从而允许更快的迭代。

### 添加测试

有关添加新测试的通用指南，请查看 `tests/README.md`。

如果你的更改与特定的硬件设置相关（例如，需要 CUDA），请查看 [`tests/test_gpu_examples.py`](https://github.com/huggingface/peft/blob/1c1c7fdaa6e6abaa53939b865dee1eded82ad032/tests/test_gpu_examples.py) 和 [`tests/test_common_gpu.py`](https://github.com/huggingface/peft/blob/1c1c7fdaa6e6abaa53939b865dee1eded82ad032/tests/test_common_gpu.py)，判断是否适合在那里添加测试。如果你的更改可能会影响模型的保存和加载，请使用 `--regression` 标志运行测试以触发回归测试。

## 过时的 PR

在编写 PR 期间，由于其他更改被合并，底层代码库可能会发生变化。如果发生这种情况——尤其是出现合并冲突时——请使用最新更改更新你的分支。这可以是合并（merge）或变基（rebase），待 PR 就绪后，我们将以 squash and merge 的方式合并该 PR。**避免强制推送**，以便更轻松地审查。

## PR 描述

在提交 PR 时，请提供一份关于你所提议更改的清晰描述，并按照上述说明引用已批准的 issue。如果与其他 issue 或 PR 相关，也请一并引用。提供一份良好的描述不仅有助于审阅者更快速、更有效地审查你的代码，还可以作为后续 commit message 的基础，从而有助于项目的长期维护。

请确保 PR 描述的篇幅和复杂度与变更内容相匹配。对于仅涉及一行代码的微小改动，无需撰写十段解释。不要重复描述通过查看 diff 即可明显看出的内容（例如“修复了 'foobaar' 中的拼写错误”）。

如果你的代码进行了一些非平凡的更改，那么添加注释来解释这些更改也是一个好主意。例如，如果你不得不多次迭代你的实现，因为最显而易见的方法不起作用，这就表明需要添加代码注释。

如有必要，请说明您如何测试了该更改，例如展示 `pytest` 测试命令或复现代码。

## 审阅者反馈

提交 PR 后，维护者通常会在几天内给出反馈。如果两周内没有收到任何反馈，您的 PR 可能已被忽略；此时您可以提醒维护者，但请勿提前操作。

如果审阅者提供了行内评论，即使您已处理，也不要将其标记为已解决。请保持这些评论处于打开状态，因为它们有助于审阅者继续其工作。

在根据评审意见完成修改后，请通知评审人，让他们知道该 PR 已准备好接受评审。

## Bug 修复

请描述导致该 bug 的具体情况。如果已存在相关 issue，请提供链接（例如：“Resolves #12345”）。

理想情况下，提供 bug 修复时应附带针对该 bug 的测试。该测试在当前代码下应失败，在应用修复后应通过。请在测试中添加注释，引用相关的 issue 或 PR。如果没有测试，未来将更难防止回归问题。

## 文档改进

我们非常欢迎针对失效链接以及缺失或表述不清的文档的修复。在这个快速变化的环境中，维护示例、确保其保持最新且能正常运行，同样备受赞赏。

请勿提交仅用于*更正*拼写错误的拉取请求，因为这类更改通常带来的工作量大于其节省的工作量。此类更改最好与更实质性的修复（例如修复损坏的链接或扩展/更新文档）合并在一起。

## 添加新的 PEFT 微调方法

新的参数高效微调方法层出不穷。如果您希望向 PEFT 添加一种新颖且前景广阔的方法，请遵循以下步骤。

1. 如果您不是_原始论文_的作者，请检查是否已有现有实现，并与作者确认他们是否计划自行提交 PR。
2. 在开始执行以下列出的核心集成工作之前，请先打开一个提案 issue，并按照上述说明等待明确的批准。
3. 查看最近的提交，了解新添加的 PEFT 方法，以获取灵感。
4. 提案获批后，一旦方法基本可用且初步测试通过，尽早开启一个草稿 PR 并请求反馈会很有帮助。请在草稿 PR 的描述中引用已批准的 issue。

### 新 PEFT 方法的核心集成

- [ ] 在投入过多工作之前，请在 `huggingface/peft` 上提交 issue 并获得明确批准。
- [ ] 链接该方法的来源，通常是最终论文或其他稳定的主要参考文献。我们希望避免仍在审稿中的工作，因为实现应当是稳定的。
- [ ] 在 `src/peft/utils/peft_types.py` 中添加一个新的 `PeftType` 条目。
- [ ] 在 `src/peft/tuners/` 下创建一个新的调优器包，包含你的方法所需的文件（通常包括：`config.py`、`model.py`、`layer.py` 和 `__init__.py`）。
- [ ] 在调优器的 `__init__.py` 中使用 `register_peft_method(...)` 注册该方法。
- [ ] 从 `src/peft/tuners/__init__.py` 和 `src/peft/__init__.py` 中导出新的 config/model。
- [ ] 如果该方法需要为 Transformers 模型提供默认的目标模块，请在 `src/peft/utils/constants.py` 中添加相应的映射。
- [ ] 在 `tests/test_custom_models.py` 的测试矩阵中添加该方法，因为这些测试覆盖范围最广且速度最快。使用 `pytest tests/test_custom_models.py -k <method-name> -v` 检查测试是否通过，如有失败则进行修复。
- [ ] 在推送之前，使用 `make style` 运行样式/质量检查。
- [ ] 在 PR 描述中，说明该方法，附上论文链接，总结权衡取舍，并列出新增内容。

### 用于添加新 PEFT 方法的完整 PR

- [ ] 确保特定于该方法的配置参数命名清晰且解释充分，不要假设用户对该论文了如指掌。
- [ ] 遵循 PEFT 的命名和编码规范。
- [ ] 确保您没有意外提交无关的更改，例如代码格式化工具修改了无关的文件。
- [ ] 如果某些实现选择并非显而易见，请通过代码注释加以说明。
- [ ] 通过将 PEFT 方法添加到测试矩阵中，完成完整的测试套件（`test_config.py`、`test_decoder_models.py` 等）。确保测试通过。
- [ ] 在 `docs/source/package_reference/` 中添加文档，包含简短说明、论文链接、使用示例以及 autodoc 代码块。解释与 LoRA 等其他方法相比的优缺点。在 `docs/source/_toctree.yml` 中注册该文档页面。
- [ ] 在 `examples/` 下添加一个可运行的示例（可以是现有示例的副本），并附上简短的 `README.md`。
- [ ] 检查 `method_comparison/` 中的基准测试，并为你的新方法添加实验设置。这是一个很好的地方，可以验证 PEFT 方法是否按预期进行训练。请包含一到两个合理的基准测试配置（一个默认配置，一个针对该基准测试优化的配置）。
- [ ] 建议：添加通用量化支持。无需为每种量化方法显式添加量化层类型，而是支持通用量化。例如，请查看 [BOFT](https://github.com/huggingface/peft/tree/main/src/peft/tuners/boft) 中的实现方式。通过在其中添加你的 PEFT 方法来扩展 https://github.com/huggingface/peft/blob/main/tests/test_quantization.py。如有需要，可向维护者寻求帮助。

## 对现有 PEFT 方法进行修改

如果您对 PEFT 方法进行了可能改变其输出的修改，从而会使已训练的 checkpoint 失效，我们需要采取额外的预防措施。有关详细信息，请查看 https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md 中的说明。那里的说明同时适用于人类和 AI。

## 添加其他功能

首先，在 GitHub 上提交一个 issue，提出添加新功能的建议，并按照上述说明等待明确的批准。这样，你可以在投入过多时间实现该功能之前，先与维护者讨论添加此功能是否合理。

新功能通常应附带测试以及文档或示例。否则，用户将难以发现您新推出的实用功能。

对代码的修改应以向后兼容的方式实现。例如，在功能合并后，现有代码应继续以相同的方式运行。

