Skip to content

🚀 为 LlamaIndex 贡献代码#

欢迎来到 LlamaIndex！我们非常高兴您想参与贡献并成为我们不断壮大的社区一员。无论您是想构建集成、修复错误还是添加激动人心的新功能，我们都为您提供了便捷的入门方式。

🎯 快速入门指南#

我们使用 uv 作为本仓库中所有 Python 包的管理工具。在贡献之前，请确保已安装 uv。在 macOS 和 Linux 上：

curl -LsSf https://astral.sh/uv/install.sh | sh

在 Windows 上：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

更多安装选项请参阅 uv 的官方文档。

如果您已准备好开始，以下是快速设置指南：

  1. Fork GitHub 仓库，克隆您的 fork 并在 git 仓库根目录 llama_index 打开终端
  2. 在仓库根目录运行以下命令来设置全局虚拟环境（用于预提交钩子和代码检查工具）：
uv sync

如果您修改了文档：

uv run make lint
  1. 导航到您要工作的项目文件夹。例如，如果您想开发 OpenAI LLM 集成：
cd llama-index-integrations/llms/llama-index-llms-openai
  1. uv 会自动为您正在开发的项目创建和设置虚拟环境。例如，运行测试可以执行：
uv run -- pytest
  1. 如果您想显式创建虚拟环境（不通过 uv run 执行命令）：
uv venv
  1. 激活虚拟环境：
source .venv/bin/activate

搞定！ 您正在开发的包已以可编辑模式安装，现在可以修改代码并运行测试了！

熟悉项目后，请查看下方的开发指南获取更多细节。

🛠️ 您可以参与哪些工作？#

贡献方式多种多样——无论您是经验丰富的 Python 开发者还是刚入门，我们都欢迎您的贡献！以下是一些建议：

1. 🆕 扩展核心模块#

通过贡献核心模块来扩展 LlamaIndex 的功能。这就像为 LlamaIndex 解锁新超能力！

  • 新集成（如连接新的 LLM、存储系统或数据源）
  • 数据加载器、向量存储等！

浏览下方模块获取灵感！

新集成应与现有 LlamaIndex 框架组件有意义地结合。LlamaIndex 维护者有权拒绝某些集成。

2. 📦 贡献工具、读取器、包或数据集#

创建新的包、读取器或工具，简化他人使用 LlamaIndex 与各种平台的交互。

3. 🧠 添加新功能#

有能让 LlamaIndex 更好的创意功能？放手去做！我们喜欢创新贡献。

4. 🐛 修复错误#

修复错误是开始贡献的好方式。前往我们的 Github Issues 页面查找标记为 good first issue 的问题。

5. 🎉 分享使用案例#

如果您以独特或创新的方式使用了 LlamaIndex，考虑分享指南或笔记。这能帮助其他开发者从您的经验中学习。

6. 🧪 实验#

有大胆的想法？我们欢迎实验性功能——测试后提交 PR 吧！

7. 📄 改进文档和代码质量#

通过完善文档或清理代码库，让项目更易于使用。每个改进都很重要！

🔥 如何扩展 LlamaIndex 核心模块#

数据加载器#

数据加载器从任何来源获取数据并将其转换为 LlamaIndex 可解析和索引的 Document 对象。

  • 接口：
  • load_data：返回 Document 对象列表
  • lazy_load_data：返回 Document 对象可迭代（适用于大型数据集）

示例：MongoDB 读取器

💡 创意：想加载尚未支持的数据源？构建新数据加载器并提交 PR 吧！

节点解析器#

节点解析器将 Document 对象转换为 Node 对象——LlamaIndex 处理的原子数据块。

  • 接口：
  • get_nodes_from_documents：返回 Node 对象列表

示例：分层节点解析器

💡 创意：为文档添加新的层次结构关系方式，如戏剧-幕-场景或章节-小节格式。

文本分割器#

文本分割器将大文本块分解为小片段——这对处理上下文窗口有限的 LLM 至关重要。

  • 接口：
  • split_text：接收字符串并返回更小的字符串（片段）

示例：令牌文本分割器

💡 创意：为不同类型内容（如代码、对话或密集数据）构建专门的文本分割器！

向量存储#

通过向量存储保存嵌入并通过相似性搜索检索。

  • 接口：
  • add, delete, query, get_nodes, delete_nodes, clear

示例：Pinecone 向量存储

💡 创意：为尚未集成的向量数据库创建支持！

查询引擎和检索器#

  • 查询引擎实现 query 方法返回结构化响应
  • 检索器根据查询检索相关节点

💡 创意：设计结合检索器或添加智能处理层的复杂查询引擎！

✨ 贡献步骤#

  1. Fork 项目仓库到你的 GitHub 账户。
  2. 克隆 你的 fork 到本地机器。 
    git clone https://github.com/your-username/llama_index.git
  3. 创建分支 用于你的工作。 
    git checkout -b your-feature-branch
  4. 配置开发环境 (参照 快速入门指南)。
  5. 开发功能或修复缺陷，确保为代码编写单元测试。
  6. 提交 变更并推送到你的 fork。 
    git push origin your-feature-branch
  7. 在 GitHub 上发起拉取请求。

大功告成——你的贡献已准备好接受审核！

🧑‍💻 开发指南#

仓库结构#

LlamaIndex 采用 单体仓库 结构，不同功能包共存于本仓库中。根据贡献内容可专注特定包：

运行测试#

我们使用 pytest 进行测试。请确保为每个修改的包运行测试：

uv run -- pytest

若涉及远程系统集成，请使用 模拟对象 以避免外部变更导致的测试失败。

默认情况下，当测试覆盖率低于 50% 时 CI/CD 将失败——请务必为你编写的代码添加测试！

👥 加入社区#

我们期待与你交流协作！加入 Discord 社区提问、分享想法或与其他开发者畅聊。

加入 Discord https://discord.gg/dGcwcsnxhU

🌟 致谢#

感谢你考虑为 LlamaIndex 贡献力量！无论是代码、文档还是想法，每个贡献都在让这个项目变得更好。

编码愉快！😊