LlamaHub 🦙

[!注意] 此仓库已被归档并设为只读。 随着 LlamaIndex v0.10 的发布，我们将弃用这个 llama_hub 仓库 - 所有集成（数据加载器、工具）和包现已移至核心 llama-index Python 仓库。 LlamaHub 将继续存在。我们正在改版 llamahub.ai，使其指向 llama-index 仓库中可用的所有集成/包/数据集。

原创者：Jesse Zhang (GitHub: emptycrown, Twitter: @thejessezhang)，他慷慨地将此仓库捐赠给了 LlamaIndex！

👥 贡献

有兴趣贡献？请查看下方的贡献部分了解更多详情。

这是一个由社区创建的所有数据加载器/读取器/工具/llama-packs/llama-datasets 的简单库。目标是让大型语言模型能够轻松连接到各种知识源。这些是通用工具，旨在用于 LlamaIndex、LangChain 等项目中。

加载器和读取器允许您轻松导入数据以供大型语言模型搜索和检索，而工具则允许模型读取和写入第三方数据服务和源。最终，这使您能够创建自己的定制数据代理，与您和您的数据智能协作，充分发挥下一代大型语言模型的能力。

有关各种数据代理的示例，请参阅 notebooks 目录。您可以找到创建数据代理的 Jupyter 笔记本示例，这些代理可以从 Google Docs、SQL 数据库、Notion 和 Slack 加载和解析数据，还可以管理您的 Google 日历和 Gmail 收件箱，或读取和使用 OpenAPI 规范。

要更轻松地浏览可用的集成，请查看此网站：https://llamahub.ai/。

<图片>

使用方法（将 llama-hub 作为 PyPI 包使用）

这些通用加载器旨在用作将数据加载到 LlamaIndex 中的方式，并/或随后在 LangChain 中使用。

安装

pip install llama-hub

LlamaIndex

from llama_index import VectorStoreIndex
from llama_hub.google_docs import GoogleDocsReader

gdoc_ids = ['1wf-y2pd9C878Oh-FmLH7Q_BQkljdm6TQal-c1pUfrec']
loader = GoogleDocsReader()
documents = loader.load_data(document_ids=gdoc_ids)
index = VectorStoreIndex.from_documents(documents)
index.query('作者在哪里上的学？')

LlamaIndex 数据代理

from llama_index.agent import OpenAIAgent
import openai
openai.api_key = 'sk-api-key'

from llama_hub.tools.google_calendar import GoogleCalendarToolSpec
tool_spec = GoogleCalendarToolSpec()

agent = OpenAIAgent.from_tools(tool_spec.to_tool_list())
agent.chat('今天日历上的第一件事是什么')
agent.chat("请在明天下午4点创建一个审查拉取请求的事件")

有关创建和使用数据代理的各种示例，请参阅 notebooks 目录。

LangChain

注意：请确保将 Tool 的描述更改为符合您用例的内容。

from llama_index import VectorStoreIndex
from llama_hub.google_docs import GoogleDocsReader
from langchain.llms import OpenAI
from langchain.chains.question_answering import load_qa_chain

# 加载文档
gdoc_ids = ['1wf-y2pd9C878Oh-FmLH7Q_BQkljdm6TQal-c1pUfrec']
loader = GoogleDocsReader()
documents = loader.load_data(document_ids=gdoc_ids)
langchain_documents = [d.to_langchain_format() for d in documents]

# 初始化示例 QA 链
llm = OpenAI(temperature=0)
qa_chain = load_qa_chain(llm)
question="<在此输入查询>"
answer = qa_chain.run(input_documents=langchain_documents, question=question)

加载器使用方法（使用 LlamaIndex 的 download_loader）

您也可以使用 LlamaIndex 的 download_loader 在一行代码中使用加载器。

例如，请参阅下面使用 Google Docs 加载器的代码片段。

from llama_index import VectorStoreIndex, download_loader

GoogleDocsReader = download_loader('GoogleDocsReader')

gdoc_ids = ['1wf-y2pd9C878Oh-FmLH7Q_BQkljdm6TQal-c1pUfrec']
loader = GoogleDocsReader()
documents = loader.load_data(document_ids=gdoc_ids)
index = VectorStoreIndex.from_documents(documents)
index.query('作者在哪里上的学？')

Llama-Pack 使用方法

可以使用 llama-index 附带的 llamaindex-cli 工具下载 Llama-packs：

llamaindex-cli download-llamapack ZephyrQueryEnginePack --download-dir ./zephyr_pack

或直接使用 download_llama_pack 函数：

from llama_index.llama_pack import download_llama_pack

# 下载并安装依赖项
LlavaCompletionPack = download_llama_pack(
  "LlavaCompletionPack", "./llava_pack"
)

Llama-Dataset 使用方法

（注：以下我们展示了使用 RagEvaluatorPack 在 LabelledRagDataset 上生成 RAG 基准的模式。然而，还有其他类型的 llama-datasets，如 LabelledEvaluatorDataset，以及用于在各自任务上生成基准的相应 llama-packs。它们都遵循类似的使用模式。请参阅 README 以了解每种类型的 llama-dataset 的更多信息。）

llama-dataset 的主要用途是评估 RAG 系统的性能。具体来说，它作为一个新的测试集（用传统机器学习的术语来说），用于构建 RAG，进行预测，然后执行评估，比较预测的响应与参考响应。要进行评估，推荐的使用模式涉及应用 RagEvaluatorPack。我们建议阅读"评估"模块的 文档 以了解有关我们所有 llama-dataset 的更多信息。

from llama_index.llama_dataset import download_llama_dataset
from llama_index.llama_pack import download_llama_pack
from llama_index import VectorStoreIndex

# 下载并安装基准数据集的依赖项
rag_dataset, documents = download_llama_dataset(
  "PaulGrahamEssayDataset", "./data"
)

# 构建基本 RAG 系统
index = VectorStoreIndex.from_documents(documents=documents)
query_engine = VectorStoreIndex.as_query_engine()

# 使用 RagEvaluatorPack 进行评估
RagEvaluatorPack = download_llama_pack(
  "RagEvaluatorPack", "./rag_evaluator_pack"
)
rag_evaluator_pack = RagEvaluatorPack(
    rag_dataset=rag_dataset,
    query_engine=query_engine
)
benchmark_df = rag_evaluate_pack.run()  # 也支持异步 arun()

Llama-datasets 也可以直接使用 llamaindex-cli 下载，该工具随 llama-index python 包一起安装：

llamaindex-cli download-llamadataset PaulGrahamEssayDataset --download-dir ./data

从 llamaindex-cli 下载后，您可以检查数据集及其源文件（存储在 /source_files 目录中），然后将它们加载到 Python 中：

from llama_index import SimpleDirectoryReader
from llama_index.llama_dataset import LabelledRagDataset

rag_dataset = LabelledRagDataset.from_json("./data/rag_dataset.json")
documents = SimpleDirectoryReader(
    input_dir="./data/source_files"
).load_data()

如何添加加载器/工具/llama-pack

添加加载器/工具/llama-pack 只需 fork 此仓库并提交拉取请求。当发布新的 llama-hub 版本时，Llama Hub 网站将自动更新。但是，在提交 PR 时，请记住以下准则。

步骤 0：设置虚拟环境，安装 Poetry 和依赖项

创建一个新的 Python 虚拟环境。以下命令在 .venv 中创建一个环境并激活它：

python -m venv .venv
source .venv/bin/activate

如果您使用的是 Windows，请使用以下命令激活虚拟环境：

.venv\scripts\activate

安装 poetry：

pip install poetry

安装所需的依赖项（这也会安装 llama_index）：

poetry install

这将在您的 venv 中创建 llama-hub 的可编辑安装。

步骤 1：创建新目录

对于加载器，在 llama_hub 中创建一个新目录；对于工具，在 llama_hub/tools 中创建目录；对于 llama-packs，在 llama_hub/llama_packs 中创建目录。它可以嵌套在另一个目录中，但请为其命名一个唯一的名称，因为目录名将成为您的加载器的标识符（例如 google_docs）。在新目录中，创建一个 __init__.py 文件，使用 __all__ 指定模块的公共接口，创建一个 base.py 文件，其中包含您的加载器实现，如果需要，创建一个 requirements.txt 文件列出加载器的包依赖项。当使用您的加载器时，这些包将自动安装，所以您不需要再担心这个问题！

如果您愿意，可以通过在 llama_hub 目录中运行以下脚本来创建新目录和文件。只需记得将依赖项放入 requirements.txt 文件中。

./add_loader.sh [新目录名称]

步骤 2：编写 README

在新目录中，创建一个 README.md，模仿现有的 README。它应该包含您的加载器或工具的功能摘要、输入以及如何在 LlamaIndex 和 LangChain 的上下文中使用它。

步骤 3：将加载器添加到 library.json 文件

最后，将您的加载器添加到 llama_hub/library.json 文件中（或 tools/ 或 llama-packs/ 下的等效 library.json），以便其他人可以使用。如当前文件所示，添加加载器或工具的类名，以及其 ID、作者等。Llama Hub 网站和 LlamaIndex 中的下载功能会引用此文件。

步骤 4：提交拉取请求！

对主分支创建一个 PR。我们通常会在一天内审核 PR。为了帮助加快流程，在 PR 中或直接在 README 中提供截图可能会有所帮助！展示您的数据加载器或工具的运行情况！

如何添加 llama-dataset

添加 llama-dataset 的过程与添加工具/加载器/llama-pack 类似，也需要 fork 本仓库并提交 Pull Request。但对于 llama-dataset，只有其元数据会被检入本仓库。实际的数据集及其源文件会被检入另一个 Github 仓库，即 llama-datasets 仓库。除了 fork 和克隆本仓库外，你还需要 fork 和克隆那个仓库。

请确保在克隆 llama-datasets 仓库时，在执行 git clone 命令之前设置环境变量 GIT_LFS_SKIP_SMUDGE：

# 对于 bash
GIT_LFS_SKIP_SMUDGE=1 git clone git@github.com:<你的GitHub用户名>/llama-datasets.git  # 使用 ssh
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/<你的GitHub用户名>/llama-datasets.git  # 使用 https

# 对于 Windows，需要两个命令
set GIT_LFS_SKIP_SMUDGE=1  
git clone git@github.com:<你的GitHub用户名>/llama-datasets.git  # 使用 ssh

set GIT_LFS_SKIP_SMUDGE=1  
git clone https://github.com/<你的GitHub用户名>/llama-datasets.git  # 使用 https

添加 llama-dataset 的高级步骤如下：

1. 创建 LabelledRagDataset（llama-hub 上提供的第一个 llama-dataset 类）
2. 使用你选择的 RAG 系统在 LabelledRagDataset 上生成基准结果
3. 准备数据集的元数据（card.json 和 README.md）
4. 向本仓库提交 Pull Request 以检入元数据
5. 向 llama-datasets 仓库 提交 Pull Request 以检入 LabelledRagDataset 和源文件

为协助提交过程，我们准备了一个提交模板笔记本，引导你完成上述步骤。我们强烈建议你使用这个模板笔记本。

（注：你可以使用上述过程提交我们支持的其他类型的 llama-datasets，如 LabelledEvaluatorDataset。）

运行测试

python3.9 -m venv .venv
source .venv/bin/activate 
pip3 install -r test_requirements.txt

poetry run make test

更新日志

如果你想跟踪最新版本更新或查看每个版本添加了哪些加载器，请查看我们的完整更新日志！

常见问题

合并前如何测试我的加载器？

download_loader 中有一个名为 loader_hub_url 的参数，默认指向本仓库的主分支。你可以将其设置为你的分支或 fork 来测试新加载器。

我应该向 LlamaHub 还是直接向 LlamaIndex 仓库创建 PR？

如果你有数据加载器 PR，默认情况下请尝试向 LlamaHub 创建！在某些情况下我们会做出例外（例如，如果我们认为该数据加载器应该是 LlamaIndex 仓库的核心）。

对于所有其他与 LlamaIndex 相关的 PR，请直接向 LlamaIndex 仓库 创建。

如何在 LlamaHub 上获得验证徽章？

我们刚开始为贡献者提供徽章。目前，我们主要关注早期采用者和官方合作伙伴，但我们正逐步开放徽章考虑给所有提交。如果你有兴趣被考虑，请查看以下标准，如果一切符合，可以通过社区 Discord 联系我们。

我们仍在完善标准，但以下是我们考虑的一些方面：

质量

• 代码质量，体现在使用编码标准和风格指南。
• 代码可读性和适当的文档。

可用性

• 自包含模块，无外部链接或库，易于运行。
• 模块不应破坏任何现有单元测试。

安全性

• 安全性考虑，如适当的输入验证、避免 SQL 注入和安全处理用户数据。

社区参与度和反馈

• 通过点赞数、下载量等衡量模块对库用户的实用性。
• 模块用户的积极反馈。

注意：

• 我们可能根据上述标准决定仅为你的部分提交授予徽章。
• 成为常规贡献者并不保证获得徽章，我们仍会单独审查每个提交。

其他问题？

欢迎加入社区 Discord 或标记官方 Twitter 账号！