LlamaHub 🦙

[!CAUTION]
此仓库已归档，仅供只读访问。
随着 LlamaIndex v0.10 的发布，我们已弃用此 llama_hub 仓库——所有集成（数据加载器、工具）和功能包现已迁移至核心的 llama-index Python 仓库。
LlamaHub 将继续存在。我们正在重构 llamahub.ai，以指向 llama-index 仓库中所有可用的集成/功能包/数据集。

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

👥 贡献

有兴趣参与贡献吗？请跳转至下方的 贡献指南 了解更多详情。

这是一个由社区创建的数据加载器/读取器/工具/llama 功能包/llama 数据集的简易库。其目标是让大型语言模型能够极其便捷地连接到各种知识源。这些是通用工具，旨在用于 LlamaIndex 和 LangChain 等项目。

加载器和读取器允许您轻松地为大型语言模型摄取数据以进行搜索和检索，而工具则允许模型读取和写入第三方数据服务与源。最终，这使您能够创建自己的定制化数据智能体，智能地与您及您的数据协同工作，从而充分释放下一代大型语言模型的全部潜力。

关于数据智能体的各种示例，请参阅 notebooks 目录。您可以找到创建数据智能体的示例 Jupyter 笔记本，这些智能体能够从 Google 文档、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('Where did the author go to school?')

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('what is the first thing on my calendar today')
agent.chat("Please create an event for tomorrow at 4pm to review pull requests")

关于创建和使用数据智能体的各种示例，请参阅 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="<query here>"
answer = qa_chain.run(input_documents=langchain_documents, question=question)

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

您也可以使用 LlamaIndex 的 download_loader 单行代码来使用加载器。

例如，查看下面使用 Google 文档加载器的代码片段。

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('Where did the author go to school?')

Llama 功能包用法

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

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 数据集用法

（注意：以下我们展示了使用 RagEvaluatorPack 在 LabelledRagDataset 上生成 RAG 基准测试的模式。但是，还有其他类型的 llama 数据集，例如 LabelledEvaluatorDataset，以及用于在其各自任务上生成基准测试的相应 llama 功能包。它们都遵循类似的用法模式。请参阅各数据集的 README 以了解更多信息。）

llama 数据集的主要用途是评估 RAG 系统的性能。具体来说，它作为一个新的测试集（用传统机器学习术语来说），供您构建 RAG 系统、进行预测，并随后执行评估，比较预测响应与参考响应。为了执行评估，推荐的用法模式是应用 RagEvaluatorPack。我们建议阅读“评估”模块的 文档，以获取关于我们所有 llama 数据集的更多信息。

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 数据集也可以直接使用 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 功能包

添加加载器/工具/llama 功能包只需 fork 此仓库并提交 Pull Request。当发布新的 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

这将在您的虚拟环境中创建 llama-hub 的可编辑安装。

步骤 1：创建新目录

对于加载器，在 llama_hub 中创建一个新目录；对于工具，在 llama_hub/tools 中创建目录；对于 llama 功能包，在 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：提交 Pull Request！

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

如何添加 llama 数据集

与添加工具/加载器/llama 功能包的过程类似，添加 llama 数据集也需要 fork 此仓库并提交 Pull Request。但是，对于 llama 数据集，只有其元数据会检入此仓库。实际的数据集及其源文件则检入另一个 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 数据集的高级步骤如下：

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

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

（注意：您可以使用上述过程提交我们支持的任何其他类型的 llama 数据集，例如 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 账号！