LlamaIndex 开发者贡献指南基于 uv 的 Monorepo 开发环境、测试与 Lint 工具链【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇指南基于 LlamaIndex 仓库根目录的 CONTRIBUTING.md 展开系统讲解如何在一个由上百个 Python 包组成的 monorepo 中搭建开发环境、选择可贡献的方向、执行测试与静态检查并顺利通过 CI 门禁。读完后你将掌握从 Fork 到提交 PR 的完整贡献流程并理解仓库中uv、pre-commit、pytest与llama-dev工具链各自承担的角色及其配置细节。一、快速开始uv 全局环境 包级虚拟环境的两级结构LlamaIndex 仓库对所有 Python 包统一使用uv作为包与项目管理器。官方推荐的本地开发流程分为两步分别对应仓库级和包级两个虚拟环境Fork 仓库并克隆到你的本地然后在仓库根目录llama_index下执行uv sync该命令会为仓库根部的 pyproject.toml 创建全局虚拟环境。从该文件的[dependency-groups] dev段可以看到这个环境专门服务于 pre-commit 钩子和各类 linter锁定安装了black[jupyter]、codespell[toml]、mypy1.11.0、pre-commit3.2.0、pylint2.15.10、pytest8.2.1、pytest-asyncio、pytest-mock、ruff0.11.11以及一批types-*类型存根包。安装 pre-commit 钩子让每次提交都自动执行检查uv run pre-commit install任何改动之后确认符合 lint 规则uv run make lint进入你要修改的具体包目录例如 OpenAI LLM 集成cd llama-index-integrations/llms/llama-index-llms-openai在该包目录下运行测试uv run -- pytest关键机制在于uv会自动为当前目录对应的包创建并管理独立的虚拟环境并且包本身以editable可编辑模式安装其中——修改代码后无需重新安装即可直接生效并运行测试。这是 monorepo 贡献体验的核心你不需要手动建 venv、手动pip install -e切换包目录时uv会自动切换到对应包的环境。二、Monorepo 结构与可贡献范围LlamaIndex 是一个 monorepo多个独立发布的 PyPI 包共存于同一仓库。从目录结构可以确认这一组织方式核心包llama-index-core/llama_index/core下约 480 个 Python 文件包含索引、检索器、响应合成器等核心模块与 llama-index-instrumentation/集成层llama-index-integrations/按类别分子目录——llms/100 个 LLM 集成、embeddings/、vector_stores/100 个向量库集成、readers/100 个数据读取器、tools/、postprocessor/、storage/等文档docs/含 API 参考、大量示例 Notebook 与内容源文件开发工具llama-dev/monorepo 测试与发布 CLI、scripts/批量版本号管理、集成健康检查等。CONTRIBUTING.md 对贡献方向给出了明确的政策边界建议贡献的区域方向说明核心模块llama-index-core与llama-index-instrumentation接受重构、Bug 修复与功能扩展文档docs目录改进现有文档并保持更新主流集成llama-index-llms、llama-index-embeddings、llama-index-vector-stores等既有集成的维护重要政策仓库已不再接受新的集成包。新集成应在独立仓库中维护并自行发布到 PyPIPR 中新增pyproject.toml会被自动关闭。这条规则在 CI 中有对应的自动化工作流 .github/workflows/close_new_integration_prs.yml该工作流监听pull_request_target事件当路径命中**/pyproject.toml时用github-script检查 PR 文件列表中 status 为added的pyproject.toml一旦发现就自动在 PR 下留言说明政策并关闭 PR。不建议投入的区域实验性功能llama-index-experimental、Packsllama-index-packs、Finetuningllama-index-finetuning与 CLIllama-index-cli。三、标准贡献流程从 Fork 到 PR官方给出的七步流程# 1. Fork 仓库后克隆你的 fork git clone https://github.com/your-username/llama_index.git # 2. 创建工作分支 git checkout -b your-feature-branch # 3. 按上文 Quick Start 配置环境uv sync / pre-commit install # 4. 开发功能或修复 Bug确保有单元测试覆盖你的改动 # 5. 提交并推送 git push origin your-feature-branch随后在 GitHub 上发起 Pull Request。提交时仓库会自动套用 .github/pull_request_template.md 模板其中包含几个值得注意的检查项是否填写了pyproject.toml的tool.llamahub段、是否为所更新的包做了版本号 bumpllama-index-core除外、是否新增了单元测试以及最后一项——I ranuv run make format; uv run make lintto appease the lint gods。Issue 侧则提供.github/ISSUE_TEMPLATE下的 docs、feature、issue、question 四类表单并有issue_classifier.yml工作流自动分类。四、Lint 工具链深潜Makefile 与 pre-commit 配置CONTRIBUTING.md 要求改动必须通过uv run make lint。这一条最终落到仓库根的 Makefilelint: ## Run linters: pre-commit (black, ruff, codespell) and mypy pre-commit install git ls-files | xargs pre-commit run --show-diff-on-failure --files format: ## Run code autoformatters (black). pre-commit install git ls-files | xargs pre-commit run black --files即make lint会对所有 git 跟踪文件跑 pre-commit 全部钩子并打印失败 diffmake format只执行black别名钩子。CI 中的 lint 检查.github/workflows/lint.yml使用 Python 3.12执行uv run -- pre-commit run -a与本地make lint等价。具体检查项定义在 .pre-commit-config.yaml从源码结构看可以梳理出以下几类钩子版本职责与要点pre-commit-hooksv4.5.0BOM、合并冲突标记、符号链接、TOML/YAML 合法性、私钥检测、行尾/行结束符等基础检查ruffruff-formatv0.11.8Lint 与格式化参数--exit-non-zero-on-fix --fix能自动修的就先修修过仍未通过则失败格式化排除uv.lock、*.ipynb与docsmypyv1.0.1类型检查关键参数--namespace-packages --explicit-package-bases --disallow-untyped-defs --ignore-missing-imports --python-version3.9并注入MYPYPATHllama_index以支持命名空间包路径black-jupyterdocs/examples23.10.1仅格式化docs/与examples/下的 Python 代码块--line-length79blacken-docs1.16.0对 rst/markdown/tex 文档中的代码块做同样的 79 列格式化prettierv3.0.3格式化前端/文档类文件codespellv2.2.6拼写检查跳过各包pyproject.toml与静态资源忽略词表astroid,gallary,momento,narl,ot,rouge,nin,gere,asend,seperatornb-clean3.1.0Notebook 清理--preserve-cell-outputs --remove-empty-cellstoml-sort-fixv0.23.1TOML 排序排除uv.lock根 pyproject.toml 中还包含与之配套的细则配置[tool.codespell]的忽略词表与跳过规则examples、实验目录、*.ipynb等、[tool.mypy]的disallow_untyped_defs true与plugins pydantic.mypy以及一份相当完整的[tool.ruff]规则集——target-version 为py312显式启用 pydocstyle 的 Google 风格 docstring 检查[lint.pydocstyle] convention google。对核心包而言还有独立的 llama-index-core/tests/ruff.toml 等包级配置。实战提示mypy 钩子要求--disallow-untyped-defs意味着新增函数必须带完整类型标注文档目录的 Python 代码块受 79 列限制——写 docs 示例时保持短行是硬性要求。五、测试规范pytest、Mock 与 50% 覆盖率门禁CONTRIBUTING.md 对测试的要求有三条硬约束每个包各自跑测试在包目录内uv run -- pytestMock 远程系统如果你的集成依赖外部服务必须 mock避免测试因外部变化而失败覆盖率下限 50%CI 在覆盖率低于 50% 时直接失败。第 3 条在 .github/workflows/coverage_check.yml 中有完整实现环境变量COV_FAIL_UNDER: 50、并发 worker 数NUM_WORKERS: 8、Python 3.12 运行。CI 并不直接裸跑 pytest而是调用仓库自带的llama-dev工具uv run -- llama-dev \ --repo-root .. test \ --workers 8 \ --base-ref${{ github.event.pull_request.base.ref }} \ --cov \ --cov-fail-under50llama-dev是仓库内 llama-dev/ 定义的官方开发 CLI入口 cli.py提供pkg、test、release三组子命令定位为 The official CLI for development, testing, and automation in the LlamaIndex monorepo。从 test 子命令实现 的源码结构看它会通过get_changed_files/get_changed_packages结合--base-ref计算出被 PR 修改的包及其依赖方get_dependants_packages只对这些包并行调度 pytest为每个包 shelling out 执行 pytest将结果归类为INSTALL_FAILED、TESTS_FAILED、TESTS_PASSED、NO_TESTS、UNSUPPORTED_PYTHON_VERSION、COVERAGE_FAILED等状态其中COVERAGE_FAILED即对应--cov-fail-under门禁用 Rich 表格实时展示各包的通过/失败/跳过进度。也就是说CI 侧的增量语义由llama-dev test --base-ref实现改哪个包及其依赖链就测哪个包而非全仓测试。本地开发时你只需关注自己包的uv run -- pytest但发布前的最终验证应与 CI 对齐。另外根 Makefile 中还保留了基于 pants 的test/test-core/test-integrations目标如pants --no-local-cache test llama-index-core/::从文件共存状态看可以推断仓库正处在 pants 与 uv/llama-dev 两套测试入口的并存/迁移阶段CONTRIBUTING.md 与 CI 工作流当前以uvllama-dev为准本地贡献者按文档执行uv run -- pytest即可。六、AI 辅助贡献的规范CONTRIBUTING.md 单列了一节《How to Use AI when Contributing》欢迎 AI 辅助但要求遵循三项核心原则透明性Transparency在贡献中说明何时何地使用了 AI 生成代码以及你如何验证和校验了它问责性Accountability每项贡献都需要人类监督人类开发者对自己的改动负责——因此不要提交你自己不理解、无法长期维护的变更质量QualityAI 代码与人类代码适用同一质量标准——有文档、有测试、遵循既有模式。工具适用边界适合用 AI重构现有代码、生成样板/重复模式代码、编写测试、改进现有文档、编写简洁的说明性注释、辅助工具函数应避免未充分审查就采用 AI 产出的复杂改动、核心架构变更、一次性提交超大改动AI 几千行代码生成很快但审查成本由维护者承担、生成自己无法理解的代码、冗长或自我解释式的注释/docstring、密钥处理与安全相关代码。官方建议的工作方式是从小改动起步、频繁验证、确保测试通过和质量标准达标然后增量式推进。七、社区与其他可用资源仓库提供 SECURITY.md、CODE_OF_CONDUCT.md 等社区治理文件问题反馈使用.github/ISSUE_TEMPLATE中的分类表单文档体系位于 docs/其构建脚本 docs/scripts/prepare_for_build.py 与 Makefile 中的watch-docs目标sphinx-autobuild监听llama_index/源码变化是维护文档类贡献时可直接利用的入口版本与发布相关RELEASE_HEAD.md 说明发布流程scripts/bulk-version-bump.py 与llama-dev release子命令支持批量版本管理——这也解释了 PR 模板中是否为所改包 bump 版本这一检查项的由来。小结在 LlamaIndex 仓库贡献代码的完整链路是uv sync建根环境 →pre-commit install挂钩子 → 进入目标包目录用uv run -- pytest独立测试外部依赖必须 mock→uv run make format; uv run make lint保证静态检查通过 → 按 PR 模板提交。CI 侧由llama-dev test做增量测试与 50% 覆盖率门禁、pre-commit run -a做 lint、close_new_integration_prs拦截新增集成包 PR。理解这套两级虚拟环境 pre-commit llama-dev 的工具链组合是在这个大型 monorepo 中高效工作的关键。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LlamaIndex 开发者贡献指南基于 uv 的 Monorepo 开发环境、测试与 Lint 工具链【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇指南基于 LlamaIndex 仓库根目录的 CONTRIBUTING.md 展开系统讲解如何在一个由上百个 Python 包组成的 monorepo 中搭建开发环境、选择可贡献的方向、执行测试与静态检查并顺利通过 CI 门禁。读完后你将掌握从 Fork 到提交 PR 的完整贡献流程并理解仓库中uv、pre-commit、pytest与llama-dev工具链各自承担的角色及其配置细节。一、快速开始uv 全局环境 包级虚拟环境的两级结构LlamaIndex 仓库对所有 Python 包统一使用uv作为包与项目管理器。官方推荐的本地开发流程分为两步分别对应仓库级和包级两个虚拟环境Fork 仓库并克隆到你的本地然后在仓库根目录llama_index下执行uv sync该命令会为仓库根部的 pyproject.toml 创建全局虚拟环境。从该文件的[dependency-groups] dev段可以看到这个环境专门服务于 pre-commit 钩子和各类 linter锁定安装了black[jupyter]、codespell[toml]、mypy1.11.0、pre-commit3.2.0、pylint2.15.10、pytest8.2.1、pytest-asyncio、pytest-mock、ruff0.11.11以及一批types-*类型存根包。安装 pre-commit 钩子让每次提交都自动执行检查uv run pre-commit install任何改动之后确认符合 lint 规则uv run make lint进入你要修改的具体包目录例如 OpenAI LLM 集成cd llama-index-integrations/llms/llama-index-llms-openai在该包目录下运行测试uv run -- pytest关键机制在于uv会自动为当前目录对应的包创建并管理独立的虚拟环境并且包本身以editable可编辑模式安装其中——修改代码后无需重新安装即可直接生效并运行测试。这是 monorepo 贡献体验的核心你不需要手动建 venv、手动pip install -e切换包目录时uv会自动切换到对应包的环境。二、Monorepo 结构与可贡献范围LlamaIndex 是一个 monorepo多个独立发布的 PyPI 包共存于同一仓库。从目录结构可以确认这一组织方式核心包llama-index-core/llama_index/core下约 480 个 Python 文件包含索引、检索器、响应合成器等核心模块与 llama-index-instrumentation/集成层llama-index-integrations/按类别分子目录——llms/100 个 LLM 集成、embeddings/、vector_stores/100 个向量库集成、readers/100 个数据读取器、tools/、postprocessor/、storage/等文档docs/含 API 参考、大量示例 Notebook 与内容源文件开发工具llama-dev/monorepo 测试与发布 CLI、scripts/批量版本号管理、集成健康检查等。CONTRIBUTING.md 对贡献方向给出了明确的政策边界建议贡献的区域方向说明核心模块llama-index-core与llama-index-instrumentation接受重构、Bug 修复与功能扩展文档docs目录改进现有文档并保持更新主流集成llama-index-llms、llama-index-embeddings、llama-index-vector-stores等既有集成的维护重要政策仓库已不再接受新的集成包。新集成应在独立仓库中维护并自行发布到 PyPIPR 中新增pyproject.toml会被自动关闭。这条规则在 CI 中有对应的自动化工作流 .github/workflows/close_new_integration_prs.yml该工作流监听pull_request_target事件当路径命中**/pyproject.toml时用github-script检查 PR 文件列表中 status 为added的pyproject.toml一旦发现就自动在 PR 下留言说明政策并关闭 PR。不建议投入的区域实验性功能llama-index-experimental、Packsllama-index-packs、Finetuningllama-index-finetuning与 CLIllama-index-cli。三、标准贡献流程从 Fork 到 PR官方给出的七步流程# 1. Fork 仓库后克隆你的 fork git clone https://github.com/your-username/llama_index.git # 2. 创建工作分支 git checkout -b your-feature-branch # 3. 按上文 Quick Start 配置环境uv sync / pre-commit install # 4. 开发功能或修复 Bug确保有单元测试覆盖你的改动 # 5. 提交并推送 git push origin your-feature-branch随后在 GitHub 上发起 Pull Request。提交时仓库会自动套用 .github/pull_request_template.md 模板其中包含几个值得注意的检查项是否填写了pyproject.toml的tool.llamahub段、是否为所更新的包做了版本号 bumpllama-index-core除外、是否新增了单元测试以及最后一项——I ranuv run make format; uv run make lintto appease the lint gods。Issue 侧则提供.github/ISSUE_TEMPLATE下的 docs、feature、issue、question 四类表单并有issue_classifier.yml工作流自动分类。四、Lint 工具链深潜Makefile 与 pre-commit 配置CONTRIBUTING.md 要求改动必须通过uv run make lint。这一条最终落到仓库根的 Makefilelint: ## Run linters: pre-commit (black, ruff, codespell) and mypy pre-commit install git ls-files | xargs pre-commit run --show-diff-on-failure --files format: ## Run code autoformatters (black). pre-commit install git ls-files | xargs pre-commit run black --files即make lint会对所有 git 跟踪文件跑 pre-commit 全部钩子并打印失败 diffmake format只执行black别名钩子。CI 中的 lint 检查.github/workflows/lint.yml使用 Python 3.12执行uv run -- pre-commit run -a与本地make lint等价。具体检查项定义在 .pre-commit-config.yaml从源码结构看可以梳理出以下几类钩子版本职责与要点pre-commit-hooksv4.5.0BOM、合并冲突标记、符号链接、TOML/YAML 合法性、私钥检测、行尾/行结束符等基础检查ruffruff-formatv0.11.8Lint 与格式化参数--exit-non-zero-on-fix --fix能自动修的就先修修过仍未通过则失败格式化排除uv.lock、*.ipynb与docsmypyv1.0.1类型检查关键参数--namespace-packages --explicit-package-bases --disallow-untyped-defs --ignore-missing-imports --python-version3.9并注入MYPYPATHllama_index以支持命名空间包路径black-jupyterdocs/examples23.10.1仅格式化docs/与examples/下的 Python 代码块--line-length79blacken-docs1.16.0对 rst/markdown/tex 文档中的代码块做同样的 79 列格式化prettierv3.0.3格式化前端/文档类文件codespellv2.2.6拼写检查跳过各包pyproject.toml与静态资源忽略词表astroid,gallary,momento,narl,ot,rouge,nin,gere,asend,seperatornb-clean3.1.0Notebook 清理--preserve-cell-outputs --remove-empty-cellstoml-sort-fixv0.23.1TOML 排序排除uv.lock根 pyproject.toml 中还包含与之配套的细则配置[tool.codespell]的忽略词表与跳过规则examples、实验目录、*.ipynb等、[tool.mypy]的disallow_untyped_defs true与plugins pydantic.mypy以及一份相当完整的[tool.ruff]规则集——target-version 为py312显式启用 pydocstyle 的 Google 风格 docstring 检查[lint.pydocstyle] convention google。对核心包而言还有独立的 llama-index-core/tests/ruff.toml 等包级配置。实战提示mypy 钩子要求--disallow-untyped-defs意味着新增函数必须带完整类型标注文档目录的 Python 代码块受 79 列限制——写 docs 示例时保持短行是硬性要求。五、测试规范pytest、Mock 与 50% 覆盖率门禁CONTRIBUTING.md 对测试的要求有三条硬约束每个包各自跑测试在包目录内uv run -- pytestMock 远程系统如果你的集成依赖外部服务必须 mock避免测试因外部变化而失败覆盖率下限 50%CI 在覆盖率低于 50% 时直接失败。第 3 条在 .github/workflows/coverage_check.yml 中有完整实现环境变量COV_FAIL_UNDER: 50、并发 worker 数NUM_WORKERS: 8、Python 3.12 运行。CI 并不直接裸跑 pytest而是调用仓库自带的llama-dev工具uv run -- llama-dev \ --repo-root .. test \ --workers 8 \ --base-ref${{ github.event.pull_request.base.ref }} \ --cov \ --cov-fail-under50llama-dev是仓库内 llama-dev/ 定义的官方开发 CLI入口 cli.py提供pkg、test、release三组子命令定位为 The official CLI for development, testing, and automation in the LlamaIndex monorepo。从 test 子命令实现 的源码结构看它会通过get_changed_files/get_changed_packages结合--base-ref计算出被 PR 修改的包及其依赖方get_dependants_packages只对这些包并行调度 pytest为每个包 shelling out 执行 pytest将结果归类为INSTALL_FAILED、TESTS_FAILED、TESTS_PASSED、NO_TESTS、UNSUPPORTED_PYTHON_VERSION、COVERAGE_FAILED等状态其中COVERAGE_FAILED即对应--cov-fail-under门禁用 Rich 表格实时展示各包的通过/失败/跳过进度。也就是说CI 侧的增量语义由llama-dev test --base-ref实现改哪个包及其依赖链就测哪个包而非全仓测试。本地开发时你只需关注自己包的uv run -- pytest但发布前的最终验证应与 CI 对齐。另外根 Makefile 中还保留了基于 pants 的test/test-core/test-integrations目标如pants --no-local-cache test llama-index-core/::从文件共存状态看可以推断仓库正处在 pants 与 uv/llama-dev 两套测试入口的并存/迁移阶段CONTRIBUTING.md 与 CI 工作流当前以uvllama-dev为准本地贡献者按文档执行uv run -- pytest即可。六、AI 辅助贡献的规范CONTRIBUTING.md 单列了一节《How to Use AI when Contributing》欢迎 AI 辅助但要求遵循三项核心原则透明性Transparency在贡献中说明何时何地使用了 AI 生成代码以及你如何验证和校验了它问责性Accountability每项贡献都需要人类监督人类开发者对自己的改动负责——因此不要提交你自己不理解、无法长期维护的变更质量QualityAI 代码与人类代码适用同一质量标准——有文档、有测试、遵循既有模式。工具适用边界适合用 AI重构现有代码、生成样板/重复模式代码、编写测试、改进现有文档、编写简洁的说明性注释、辅助工具函数应避免未充分审查就采用 AI 产出的复杂改动、核心架构变更、一次性提交超大改动AI 几千行代码生成很快但审查成本由维护者承担、生成自己无法理解的代码、冗长或自我解释式的注释/docstring、密钥处理与安全相关代码。官方建议的工作方式是从小改动起步、频繁验证、确保测试通过和质量标准达标然后增量式推进。七、社区与其他可用资源仓库提供 SECURITY.md、CODE_OF_CONDUCT.md 等社区治理文件问题反馈使用.github/ISSUE_TEMPLATE中的分类表单文档体系位于 docs/其构建脚本 docs/scripts/prepare_for_build.py 与 Makefile 中的watch-docs目标sphinx-autobuild监听llama_index/源码变化是维护文档类贡献时可直接利用的入口版本与发布相关RELEASE_HEAD.md 说明发布流程scripts/bulk-version-bump.py 与llama-dev release子命令支持批量版本管理——这也解释了 PR 模板中是否为所改包 bump 版本这一检查项的由来。小结在 LlamaIndex 仓库贡献代码的完整链路是uv sync建根环境 →pre-commit install挂钩子 → 进入目标包目录用uv run -- pytest独立测试外部依赖必须 mock→uv run make format; uv run make lint保证静态检查通过 → 按 PR 模板提交。CI 侧由llama-dev test做增量测试与 50% 覆盖率门禁、pre-commit run -a做 lint、close_new_integration_prs拦截新增集成包 PR。理解这套两级虚拟环境 pre-commit llama-dev 的工具链组合是在这个大型 monorepo 中高效工作的关键。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
