贡献指南#

感谢您对为 LMCache 贡献的兴趣！我们欢迎并接受各种形式的贡献，无论大小。您可以通过几种方式为项目做出贡献：

  • 识别并报告任何问题或错误

  • 请求或添加对新模型的支持

  • 建议或实现新功能

  • 改进文档或贡献一份操作指南

可以在问题 [Onboarding][Q4] 欢迎贡献者的好第一问题！ 中找到一个全面的好第一问题列表。

如果您想进一步支持我们的社区，回答问题、提供 PR 评审和协助他人也是对 LMCache 产生影响的贡献方式。

最后，您可以通过提高对 LMCache 的认识来支持我们。欢迎分享我们的博客文章，查看我们在 X 上的账号 LMCache，了解我们最新的动态。如果使用 LMCache 在某种程度上帮助了您的项目或产品，您可以通过给我们的代码库加星来表达您的感谢！

许可证#

请参阅 LICENSE 文件以获取详细信息。

行为准则#

本项目遵循 行为准则。参与时，您需要遵守此准则。

贡献指南#

对开源项目的帮助总是受欢迎的，总有一些可以改进的地方。例如，文档（就像您现在正在阅读的文本）总是可以改进，代码总是可以更清晰，变量或函数总是可以重命名或添加注释，并且总是需要更多的测试覆盖率。如果您看到认为应该修复的内容，请主动承担责任！以下是您如何开始的指南。

我该如何贡献？#

在贡献时，首先查看 issues 是很有帮助的。在选择一个问题后，编写代码或更新文档，然后提交一个拉取请求，你的工作将会被审查和合并。如果你要添加新功能或发现错误，最好先 写一个问题 与维护者讨论。

如果您发现安全漏洞，请按照 安全文档 中的说明进行操作。

要为这个仓库贡献代码，您将使用许多开源仓库中常见的分叉和拉取模型。有关此过程的详细信息，请查看 Kubernetes 的 GitHub 工作流程指南。简而言之：

  • 分叉仓库

  • 创建一个分支

  • 运行代码风格检查并修复任何问题

  • 运行单元测试并修复任何损坏的测试

  • 提交包含详细描述的拉取请求

当您的贡献准备好后，您可以创建一个拉取请求。拉取请求通常被称为“PR”。一般来说，我们遵循标准的 GitHub 拉取请求 流程。请按照模板提供有关您的拉取请求的详细信息给维护者。

请尽量对 PR 进行分类，以便于理解更改类型。PR 标题前缀应适当地指示更改类型。请使用以下之一：

  • [Bugfix] 用于错误修复

  • [构建] 用于构建修复和改进

  • [CI] 用于持续集成的修复和改进

  • [核心] 用于核心 LMCache 逻辑的更改（例如，LMCacheEngine，Backend 等）

  • [文档] 用于文档修复和改进

  • [杂项] 用于不符合上述类别的 PR。请谨慎使用。

  • [模型] 用于添加新模型或改进现有模型。模型名称应出现在标题中

  • [Test] 用于单元测试

备注

如果 PR 涉及多个类别，请包含所有相关的前缀。

最好将您的贡献分解为较小的 PR，进行增量更改，并包含对更改的良好描述。我们要求在添加任何新功能时提供新的单元测试，并在用户可见的更改时提供文档。

在发送拉取请求之前，请确保您的更改通过了代码质量检查和单元测试。这些检查将在拉取请求构建时运行。或者，您可以按照 开发 中的说明在本地机器上手动运行检查。

DCO 和签署确认#

When contributing changes to the project, you must agree to the DCO. Commits must include a Signed-off-by header which certifies agreement with the terms of the DCO.

备注

使用 -s 或 --signoff 标志与 git commit 一起将自动添加此标题。如果您忘记为上一个提交签名，这些标志也可以与 --amend 一起使用。

代码审查#

一旦您创建了拉取请求，维护者将审查您的代码，并可能提出建议以在合并之前进行修复。如果您在工作时考虑审查者遵循的标准，您的拉取请求将更容易获得审查。请记住：

  • 对代码进行良好的文档记录，以帮助未来的贡献者和维护者。

  • 遵循项目编码规范，以确保一致性和最佳实践

  • 包含足够的测试以保持代码的健壮性

  • 如果 PR 修改了面向用户的行为，请在 /docs 中添加或更新文档，以帮助使用 LMCache 的人。

  • 运行编码风格检查以确保一致性和正确性

  • 在本地运行测试，确保它们通过并且不会破坏现有代码库。

  • 撰写详细的提交信息，以帮助未来的贡献者和维护者。

  • 将大型更改拆分为一系列逻辑上较小的补丁，这些补丁单独易于理解，并结合起来解决更广泛的问题。

备注

维护者将在此仓库的 PR 上执行“压缩并合并”操作，因此您的 PR 有多少个提交并不重要，因为它们在合并后将变成一个单一的提交。

开发#

设置您的开发环境#

以下先决条件是必需的：

  • 操作系统：Linux

  • GPU: NVIDIA 计算能力 7.0+（例如，V100、T4、RTX20xx、A100、L4、H100 等）

  • CUDA 12.8+

以下工具是必需的：

第一步是安装开发所需的必要 Python 包。执行此操作的命令如下：

# Equivalent to pip install -r requirements/common.txt
pip install -e .

pip install -r requirements/lint.txt
pip install -r requirements/test.txt

在将更改推送到 GitHub 之前，您需要运行如下所示的编码风格检查和单元测试。

编码风格#

LMCache 遵循 Python 的 pep8 编码风格和 C++ 的 Google C++ style guide。我们使用以下工具来强制执行编码风格：

这些工具由 pre-commit 管理。安装方法如下：

pip install -r requirements/lint.txt
pre-commit install

它将在您添加提交时自动运行。您也可以使用以下命令手动在所有文件上运行它：

pre-commit run --all-files

备注

对于所有新增的代码，请使用 sphinx-doc 格式 编写文档字符串。

单元测试#

在进行更改时，请在推送更改之前运行测试。运行单元测试可以确保您的贡献不会破坏现有代码。我们使用 pytest 框架来运行单元测试。该框架已设置为运行 tests 目录中所有以“test”开头或结尾的文件。

运行单元测试非常简单：

pytest

备注

在运行单元测试之前，需要安装 vLLM (pip install vllm) 及 requirements/test.txt 中的依赖项。

默认情况下，将运行测试目录中找到的所有测试。然而，可以通过将文件名、类和/或方法传递给 pytest 来运行特定的单元测试。以下示例调用在 "tests/test_connector.py" 文件中声明的单个测试方法 "test_lm_connector"：

pytest tests/test_connector.py::test_lm_connector

备注

某些单元测试需要 NVIDIA GPU。这意味着在非 Linux NVIDIA GPU 系统上，所有测试将不会全部运行（需要 CUDA 的测试将被跳过）。Buildkite 持续集成（CI）系统会执行所有测试的完整运行。

备注

NVIDIA Inference Xfer Library (NIXL) 单元测试需要安装 NIXL。LMCache 不会安装它，因此需要您单独安装。请按照 NIXL GitHub 仓库中的详细信息进行安装。如果未安装 NIXL 包，则会跳过 NIXL 单元测试。

构建文档#

安装依赖项：

pip install -r requirements/docs.txt

之后，您可以使用 make 从 docs/ 目录构建文档：

make clean
make html

在 http://localhost:8000 本地服务文档页面： python -m http.server -d build/html/

谢谢你#

感谢您为 LMCache 的贡献，使其成为一个更好、更易于访问的框架。