跳至内容

🚀 为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. 📦 贡献工具、读取器、组件包或数据集#

创建新的Packs、Readers或Tools，简化他人使用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 Reader

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

节点解析器#

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

  • 界面:
  • get_nodes_from_documents: 返回一个Node对象列表。

示例: Hierarchical Node Parser

💡 想法: 为文档中的层级关系添加新的组织结构方式，例如剧本-幕-场景或章节-小节格式。

文本分割器#

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

  • 界面:
  • split_text: 接收一个字符串并返回较小的字符串（块）。

示例: Token Text Splitter

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

向量存储#

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

  • 界面:
  • add, delete, query, get_nodes, delete_nodes, clear

示例: Pinecone Vector Store

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

查询引擎与检索器#

  • 查询引擎 实现了 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. 提交您的更改，然后将它们推送到您的分支。 
    git push origin your-feature-branch
  7. 在GitHub上提交拉取请求

瞧——您的贡献已准备好接受审核！

🧑‍💻 开发指南#

仓库结构#

LlamaIndex采用单体仓库(monorepo)的组织形式，意味着不同包都存放在这个单一代码库中。您可以根据贡献目标专注于特定包：

运行测试#

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

uv run -- pytest

如果您正在与远程系统集成，模拟它以防止外部更改导致测试失败。

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

👥 加入社区#

我们非常期待您的反馈与合作！加入我们的Discord社区，提出问题、分享想法，或与其他开发者交流。

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

🌟 致谢#

感谢您考虑为LlamaIndex做出贡献！无论是代码、文档还是想法，每一个贡献都能让这个项目对所有人变得更好。

编程愉快！😊

优云智算