跳到内容

🚀 贡献 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. 在仓库根目录，运行以下命令设置我们用于 pre-commit 钩子和 linter 的全局虚拟环境：
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 的新超能力！

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

探索下面的不同模块，获取灵感！

新的集成应该与现有的 LlamaIndex 框架组件有意义地集成。LlamaIndex 维护者有权决定是否接受某些集成。

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

创建新的包、读取器或工具，简化其他人与各种平台一起使用 LlamaIndex 的方式。

3. 🧠 添加新功能#

有个想法能让 LlamaIndex 变得更好吗？放手去做吧！我们热爱创新性贡献。

4. 🐛 修复错误#

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

5. 🎉 分享使用示例#

如果您以独特或创造性的方式使用过 LlamaIndex，可以考虑分享指南或 Notebook。这有助于其他开发者从您的经验中学习。

6. 🧪 进行实验#

有个大胆的想法吗？我们对实验性功能持开放态度——尝试一下，然后提交一个 PR！

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

通过改进文档或清理代码库，帮助项目更容易导航。每一个改进都很重要！

🔥 如何扩展 LlamaIndex 的核心模块#

数据加载器#

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

  • 接口:
  • load_data：返回一个 Document 对象列表。
  • lazy_load_data：返回一个 Document 对象迭代器（对于大型数据集很有用）。

示例：MongoDB 读取器

💡 想法：想从尚未支持的源加载数据吗？构建一个新的数据加载器并提交一个 PR！

节点解析器#

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

  • 接口:
  • get_nodes_from_documents：返回一个 Node 对象列表。

示例：层级节点解析器

💡 想法：添加新的方式来构建文档中的层级关系，例如剧本（幕-场-景）或书籍（章-节）格式。

文本分割器#

文本分割器将大文本块分解成更小的块——这对于处理上下文窗口有限的 LLMs 至关重要。

  • 接口:
  • split_text：接受一个字符串，并返回更小的字符串（块）。

示例：Token 文本分割器

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

向量存储#

使用向量存储存储嵌入并通过相似性搜索检索它们。

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

示例：Pinecone 向量存储

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

查询引擎与检索器#

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

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

✨ 贡献步骤#

  1. 在 GitHub 上 Fork 仓库。
  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 组织为一个Monorepo，这意味着不同包位于此单一仓库中。您可以根据您的贡献专注于特定包：

运行测试#

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

uv run -- pytest

如果您正在与远程系统集成，请对其进行模拟 (mock)，以防止因外部更改导致的测试失败。

默认情况下，如果测试覆盖率低于 50%，CICD 将会失败——所以请务必为您的代码添加测试！

👥 加入社区#

我们很乐意听取您的意见并进行协作！加入我们的 Discord 社区提问、分享想法，或者只是与其他开发者聊天。

加入我们的 Discord https://discord.gg/dGcwcsnxhU

🌟 致谢#

感谢您考虑为 LlamaIndex 贡献！每一份贡献——无论是代码、文档还是想法——都有助于让这个项目变得更好。

编码愉快！😊