LEANN 贡献指南从 uv 开发环境搭建到 PR 合入的完整工程实践【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANNLEANNLocal Embedding-based Approximate Nearest Neighbor是一个面向个人设备的私有化 RAG 引擎核心代码分布在 packages 下的 leann-core、HNSW/DiskANN/FlashLib 等多个子包中并配有 apps 应用层、benchmarks 基准评测与 tests 测试套件。本文以仓库根目录的 docs/CONTRIBUTING.md 为主干结合pyproject.toml、.pre-commit-config.yaml与.github/workflows中的真实配置完整讲解贡献者从零搭建开发环境、接入 pre-commit 质量门禁、编写与运行测试、遵循 ruff 代码风格到发起 Pull Request 并通过 CI 的全过程。读完本文你将具备向 LEANN 提交高质量代码贡献的完整实操能力并理解该仓库本地 lint 与 CI 完全一致的工程约束。一、参与方式不只写代码LEANN 欢迎各种形式的贡献参与方式并不局限于提交代码Bug 报告发现问题时通过 .github/ISSUE_TEMPLATE/bug_report.yml 提供的模板提交模板会引导你描述复现步骤、期望行为与实际行为功能建议通过 .github/ISSUE_TEMPLATE/feature_request.yml 提交说明你的使用场景与期望能力代码贡献欢迎各种水平的 PR从修一个文档笔误到新增一个检索后端都可以文档仓库的 docs 目录下有faq.md、configuration-guide.md、features.md、roadmap.md等大量指南改进它们同样是重要贡献基准评测分享你的性能测试结果benchmarks 目录中已有 BM25/DiskANN 基线、Enron 邮件、FinanceBench、LAION 等评测脚本可供参考与扩展。无论以哪种方式参与仓库都强调由社区构建、为社区服务的理念任何规模的贡献都会被认真对待。二、开发环境搭建基于 uv 的一站式构建LEANN 使用 uv快速 Python 包管理器与项目构建工具管理依赖与虚拟环境这是官方推荐的唯一环境入口请勿混用 pip/conda。2.1 安装 uvcurl -LsSf https://astral.sh/uv/install.sh | sh安装完成后uv命令即可用必要时重启终端或 source shell 配置。2.2 克隆仓库并初始化子模块LEANN 的后端依赖大量第三方 C/C 库如 HNSW、DiskANN、faiss、libzmq 等它们以 git submodule 形式引用因此克隆后必须递归初始化git clone https://gitcode.com/GitHub_Trending/le/LEANN.git leann git submodule update --init --recursive cd leann这一步很关键packages/leann-backend-hnsw/third_party、packages/leann-backend-diskann/third_party等目录下存放着构建所需的三方源码若跳过--recursive会导致后续uv sync编译失败。2.3 安装系统级依赖C 后端与 Python 绑定的编译需要若干系统库。仓库按平台给出两套安装命令macOSbrew install llvm libomp boost protobuf zeromq pkgconfUbuntu/Debiansudo apt-get install libomp-dev libboost-all-dev protobuf-compiler \ libabsl-dev libmkl-full-dev libaio-dev libzmq3-dev这些库对应 LEANN 各后端的真实需求libomp提供 OpenMP 并行支持boost与protobuf服务于 DiskANN/HNSW 的构建libzmq3-dev是 ZeroMQ 通信层packages/leann-backend-hnsw/third_party中即内嵌了cppzmq、libzmq、msgpack-c等。不同平台、不同架构x86_64 用 Intel MKLARM64 用 OpenBLAS的差异可以在 .github/workflows/build-reusable.yml 的 CI 步骤中找到对应实现作为参考。2.4 从源码构建# macOS需要显式指定 llvm 的 clang 作为编译器 CC$(brew --prefix llvm)/bin/clang CXX$(brew --prefix llvm)/bin/clang uv sync # Ubuntu/Debian uv syncuv sync会依据根目录 pyproject.toml 创建虚拟环境并安装全部依赖。值得注意的一点是该项目采用path-based 工作区方式组织多包结构[tool.uv.sources]将leann-core、leann-backend-diskann、leann-backend-hnsw、leann-backend-flashlib、leann-backend-flashlib-ivf、astchunk都指向packages/下的本地目录并以 editable 模式安装见 pyproject.toml。这意味着你在packages/leann-core/src/leann下的改动会立即生效无需重新安装。此外pyproject.toml还声明了 Python 版本要求requires-python 3.10见 pyproject.toml并提供了若干可选依赖组diskann、flashlib、flashlib-ivfGPU 加速后端、documentsPDF/Word/Excel 文档处理。如果只想跑核心功能基础uv sync即可需要 GPU 精确/近似近邻检索时再按需uv sync --extra flashlib等。三、Pre-commit 钩子提交前的第一道质量门禁LEANN 使用 pre-commit 在每次git commit前自动执行一系列检查确保代码质量与风格一致性。3.1 安装与使用# 1. 安装 lint 工具链仅安装 lint 组依赖不安装项目运行时依赖 uv sync --group lint # 2. 将钩子安装到当前 git 仓库 pre-commit install # 3. 可选手动对全仓库执行一次检查 uv run pre-commit run --all-files对应到配置文件 pyproject.tomllint依赖组固定为pre-commit3.5.0与ruff0.12.7。注意ruff 版本被精确锁定注释里明确写着Fixed version to ensure consistent formatting across all environments——这是为了避免不同机器上 ruff 版本漂移导致格式化结果不一致进而在 CI 中产生本地过了、远程挂了的尴尬。3.2 检查项明细打开根目录的 .pre-commit-config.yaml可以看到两个 hook 仓库、共 8 项检查pre-commit-hooksv5.0.0——通用仓库卫生检查Hook ID作用trailing-whitespace移除行尾多余空白end-of-file-fixer确保文件末尾有且仅有一个换行符check-yaml校验 YAML 文件语法check-added-large-files阻止误提交超大文件防止把模型权重、二进制数据塞进 gitcheck-merge-conflict检测残留的冲突标记等debug-statements检测print/pdb/breakpoint等调试语句ruff-pre-commitv0.12.7——Python 代码格式化与 lintHook ID作用ruff带--fix --exit-non-zero-on-fix运行 linter 并自动修复若有无法自动修复的问题则以非零退出码提示ruff-format按 ruff 格式化规范重排代码其中ruff钩子的--exit-non-zero-on-fix参数值得留意即使 ruff 成功自动修复了代码钩子也会返回非零退出码从而阻止这次 commit迫使你重新审视被修改的内容——这正是自动修复但不过度自动提交的工程取舍。3.3 与 CI 的一致性pre-commit 与 CI 使用完全相同的命令保证本地检查结果可复现于远端。在 CI 的 lint 任务中见 .github/workflows/build-reusable.yml实际执行的是uv run --frozen --only-group lint pre-commit run --all-files --show-diff-on-failure--only-group lint意味着 CI 只安装 lint 依赖组即可跑完所有检查无需拉取 torch、sglang 等重型运行时依赖大幅缩短 CI 时间--show-diff-on-failure则在检查失败时直接展示格式化差异方便定位问题。四、代码风格ruff 既当裁判又当教练LEANN 的代码风格统一由 ruff 负责lint 与格式化都在 pyproject.toml 的[tool.ruff]段集中配置。4.1 常用命令# 格式化所有文件 ruff format # 仅检查格式、不修改文件 ruff format --check # 运行 linter 并自动修复 ruff check --fix # 仅检查、不修复 ruff checkCI 中使用的是全仓库级检查见 .github/workflows/build-reusable.ymlruff check . ruff format --check .4.2 仓库级规则速览从 pyproject.toml 可以看到项目的风格基线目标版本target-version py39语法兼容到 Python 3.9尽管运行时要求 3.10保证代码写法对旧版本解析器友好行宽line-length 100排除目录extend-exclude排除了third_party与两个多模态示例脚本这些是引用的上游代码不纳入本地风格约束启用的 lint 规则Epycodestyle 错误、Wpycodestyle 警告、Fpyflakes、Iisort 导入排序、Bflake8-bugbear、C4flake8-comprehensions、UPpyupgrade、Npep8-naming、RUFruff 专属规则显式忽略E501行长交给 formatter 处理、B008、B904、N812、N806、RUF012等易误报规则格式化风格quote-style double统一双引号、indent-style space、line-ending auto。4.3 风格守则除工具强制项外贡献者还需遵守以下约定遵循 PEP 8 约定变量名要有描述性在合适位置添加类型注解所有公开函数与类都要编写 docstring函数保持单一职责、短小聚焦。这些约定与 CI 中的类型检查相呼应CI 的type-check任务使用 Astral 的快速类型检查器ty检查packages/leann-core/src、apps、tests见 .github/workflows/build-reusable.yml其规则配置同样位于 pyproject.toml。五、测试从命令行到测试套件5.1 运行测试# 仅安装测试工具链不安装项目运行时依赖 uv sync --group test # 运行全部测试 uv run pytest # 运行指定测试文件 uv run pytest tests/test_filename.py # 带覆盖率运行 uv run pytest --covleanntest依赖组定义在 pyproject.toml包含pytest9.0、pytest-cov、pytest-xdist并行、pytest-timeout、python-dotenv。5.2 测试目录与命名约定原文档建议将测试放在test/目录并使用test_*.py命名在当前仓库中测试的实际位置是tests/目录这一路径在 pyproject.toml 的 pytest 配置中显式声明testpaths [tests]pytest 默认只扫描该目录python_files [test_*.py]文件名以test_开头python_classes [Test*]、python_functions [test_*]类名与函数名的命名模式markers定义了slow慢测试可用-m not slow跳过、openai需要 OpenAI API Key、integration需要 Ollama、LM Studio 等真实服务三类标记且开启了--strict-markers防止拼错标记名timeout 300单个测试最长 5 分钟防止挂死拖垮 CIaddopts [-v, --tbshort, --strict-markers, --disable-warnings]默认输出详细结果与短回溯env默认注入HF_HUB_DISABLE_SYMLINKS1与TOKENIZERS_PARALLELISMfalse规避 HuggingFace 与 tokenizers 在多进程下的已知问题。5.3 现有测试样本tests/下的测试覆盖了 LEANN 的核心能力可作为编写新测试的模板基础构建与检索test_basic.py、test_build_from_arrays.py、test_readme_examples.py后端相关test_diskann_partition.py、test_flashlib_ivf_backend.py、test_hnsw_rebuild_fallback.py检索与过滤test_hybrid_search.py、test_metadata_filtering.py、test_fts5_bm25.pyCLI 与服务器test_cli_ask.py、test_cli_daemon_workflow.py、test_embedding_server_manager.py集成与协议test_mcp_integration.py、test_llamaindex_integration.py、test_react_dual_source.py。5.4 编写测试的要求放在tests/目录下命名遵循test_*.py测试名要有描述性能直接说明被测行为同时包含正向用例与负向用例例如既验证匹配到预期文档也验证无关查询返回空结果涉及外部服务的测试记得打上integration或openai标记避免默认运行被拖慢。六、CI/CD提交后的全自动质量保障LEANN 的 CI 在每次 push 到main或发起 PR 时自动运行。入口工作流 .github/workflows/build-and-publish.yml 复用了 .github/workflows/build-reusable.yml并支持workflow_dispatch手动触发。整个流水线包含四个环节6.1 Lint 与类型检查前置门槛lint 任务ubuntu-latest上运行使用uv run --frozen --only-group lint pre-commit run --all-files --show-diff-on-failure与本地 pre-commit 完全一致type-check 任务安装ty0.0.17后执行ty check packages/leann-core/src apps tests对核心包、应用层与测试代码做静态类型检查。这两步通过后才会进入构建阶段needs: [lint, type-check]。6.2 多平台、多版本构建矩阵构建矩阵在 .github/workflows/build-reusable.yml 中定义覆盖面包括操作系统Ubuntu 22.04x86_64 与 ARM64、macOS 14/15含 Intel 变体、macOS 26beta、Windows 2022Python 版本3.10、3.11、3.12、3.13、3.14对应矩阵中的python字段需要注意原文档所述 Python 3.9-3.13 已随仓库演进当前pyproject.toml要求3.10CI 实际矩阵为 3.10–3.14工作流注释中还说明了约束原因例如Python 3.13 无 macOS x86_64 PyTorch wheel故 Intel Mac 矩阵止步于 3.12。构建顺序为leann-core→leann-backend-hnsw→leann-backend-diskann→leann-backend-ivf→ 元包leann构建产物随后在 Linux 上用auditwheel、macOS 上用delocate、Windows 上用delvewheel进行 wheel 修复修补动态库依赖确保 wheel 可分发。6.3 全量测试与 Arch Linux 冒烟测试构建完成后CI 会安装本次构建出的 wheel 并执行pytest tests/ -v --tbshort环境变量中固定OMP_NUM_THREADS1、MKL_NUM_THREADS1以保证线程行为可复现。此外还有一个独立的arch-smoke任务在 Arch Linux 容器中安装全部 wheel并运行一段迷你脚本验证LeannBuilder构建索引、LeannSearcher检索的最小闭环见 .github/workflows/build-reusable.yml确保发布产物在真实 Linux 发行版上可用。七、Pull Request 流程提交代码贡献的推荐流程如下Fork 仓库并从main创建特性分支git checkout -b feature/your-feature-name实现改动编写干净、有文档的代码为新功能补充测试按需更新文档。运行 pre-commit 检查pre-commit run --all-files运行测试uv run pytest使用描述性信息提交并遵循 Conventional Commits 规范git commit -m feat: add new search algorithm常用的提交前缀包括feat:新功能、fix:缺陷修复、docs:文档、test:测试、refactor:重构、perf:性能优化。推送并创建 PR在 PR 描述中清楚说明改动内容关联相关 issue如适用附上示例或截图。八、文档与发布配套如果改动涉及新功能或行为变更请同步更新docs 下的相关指南如 docs/faq.md、docs/configuration-guide.md、docs/features.md新函数/类的 docstring根目录 README.md如需包含使用示例涉及版本变更时可参考 docs/CHANGELOG.md 与 docs/RELEASE.md 的维护方式。仓库还提供了额外的质量保障uv.lock锁定全部依赖版本保证环境可复现.github/workflows/link-check.yml 使用 lychee 对文档链接做周期性与 CI 内检查相关配置[tool.lychee]也在 pyproject.toml 中因此提交文档时请确保内部相对链接指向真实存在的文件。九、获取帮助与许可遇到问题时先查阅 docs/faq.md 与 docs/roadmap.md在 Issues 中搜索是否已有相同问题没有则新建 Issue 并附上复现信息一般性问题可在 Discussions 中讨论。根据 LICENSE项目采用 MIT 协议通过提交贡献即表示你同意你的贡献在相同协议MIT下授权。仓库本身欢迎社区参与任何规模的贡献——从修正一个 typo 到实现一个新的检索后端——都会让 LEANN 变得更好。小结LEANN 的贡献链路是一条本地工具链与远端 CI 完全对齐的流水线uv负责环境一致性pre-commit ruff 负责提交前的代码卫生pytest 负责行为验证GitHub Actions 矩阵负责跨平台构建与发布质量。对贡献者而言只要在本地严格走完uv sync --group lint→pre-commit run --all-files→uv run pytest再按 Conventional Commits 提交并附上清晰的 PR 描述就能顺畅地融入这个项目。【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考