llama_index 集成指南：使用 MetalReader 从 Metal 向量库加载数据

llama_index 集成指南：使用 MetalReader 从 Metal 向量库加载数据

【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index

导读

本文围绕 llama_index 仓库中docs/api_reference/api_reference/readers/metal.md所对应的 API 参考条目，完整介绍MetalReader这一数据加载器（Data Reader）的定位、安装方式、初始化参数、load_data检索流程及其底层实现原理。读完本文，你将掌握如何用MetalReader从 Metal 向量存储中按向量相似度与元数据过滤器检索文档，并将其转换为 LlamaIndex 的Document对象，为索引构建、查询引擎或 Agent 工具链提供数据输入。

MetalReader 是什么

MetalReader是 llama_index 官方 Readers 集成中的一员，封装在独立分发包llama-index-readers-metal中，源码位于 llama-index-integrations/readers/llama-index-readers-metal/llama_index/readers/metal/base.py。它的核心作用是从 Metal 向量存储（Metal Vector Store）中检索并加载数据：

• 以用户提供的 API Key、Client ID、Index ID 定位到具体的 Metal 索引；
• 基于查询向量（query embedding）执行相似度搜索，并可叠加元数据过滤器；
• 将命中的记录转换为 LlamaIndex 标准Document对象列表返回。

从类继承关系看，MetalReader直接继承自 llama_index 核心模块的BaseReader（见 llama-index-core/llama_index/core/readers/base.py#L19），因此它天然具备 Reader 生态的统一接口约定：load_data返回List[Document]，并可使用lazy_load_data、异步方法aload_data、以及load_langchain_documents等能力。包内测试 tests/test_readers_metal.py 通过检查MetalReader.__mro__验证了BaseReader确实位于其父类链中，保证该 Reader 符合 LlamaIndex 的加载器契约。

安装与前置条件

llama-index-readers-metal是独立的 Python 包，通过 pip 直接安装：

pip install llama-index-readers-metal

根据包的 pyproject.toml，其运行依赖如下（版本约束以仓库当前配置为准）：

包要求的 Python 版本为>=3.10,<4.0。在 base.py 中可以看到，构造MetalReader时会对metal_sdk做一次导入检查，若未安装会抛出提示：

`metal_sdk` package not found, please run `pip install metal_sdk`

使用前提：MetalReader本身只负责"读"，因此在调用前你需要在 Metal 平台侧先创建好对应的向量存储与索引，并拿到三个凭证：API Key、Client ID 与 Index ID。这三个值缺一不可，是MetalReader定位目标索引的唯一依据。

初始化 MetalReader

MetalReader的构造函数签名为：

def __init__(self, api_key: str, client_id: str, index_id: str):

三个参数含义如下：

从源码实现看，构造时除了做metal_sdk的导入校验外，还会实例化底层客户端：

from metal_sdk.metal import Metal self.metal_client = Metal(api_key, client_id, index_id)

即 base.py 将三个凭证直接透传给metal_sdk的Metal客户端对象，后续所有检索请求都经由该客户端发出。

典型初始化示例：

from llama_index.readers.metal import MetalReader reader = MetalReader( api_key="<Metal API Key>", client_id="<Metal Client ID>", index_id="<Metal Index ID>", )

使用 load_data 检索文档

初始化完成后，通过load_data方法发起检索。其完整签名如下（见 base.py）：

def load_data( self, limit: int, query_embedding: Optional[List[float]] = None, filters: Optional[Dict[str, Any]] = None, separate_documents: bool = True, **query_kwargs: Any, ) -> List[Document]:

参数说明

完整调用示例

documents = reader.load_data( limit=10, # 返回最多 10 条结果 query_embedding=[0.1, 0.2, 0.3], # 查询向量 filters={"field": "value"}, # 元数据过滤 separate_documents=True, # 每条记录作为独立 Document )

底层检索流程

load_data的内部实现非常直接，可以拆解为三步（base.py）：

第一步：组装请求负载

payload = { "embedding": query_embedding, "filters": filters, } response = self.metal_client.search(payload, limit=limit, **query_kwargs)

即把查询向量与过滤器打包进 payload，连同limit和透传的query_kwargs一起交给 Metal SDK 的search方法。

第二步：逐条转换为 Document

for item in response["data"]: text = item["text"] or (item["metadata"] and item["metadata"]["text"]) documents.append(Document(text=text))

这里体现了 Metal 检索结果的数据形态：每条记录优先取顶层text字段；若为空，则回退到metadata中的text字段。从源码可以推断，Metal 索引中的文档文本既可以存放在记录顶层，也可以存放在元数据中，MetalReader对两种布局都做了兼容。

第三步：按需合并文档

if not separate_documents: text_list = [doc.get_content() for doc in documents] text = "\n\n".join(text_list) documents = [Document(text=text)]

当separate_documents=False时，所有命中文本以两个换行符\n\n连接，合并为单一Document，适合后续做整体性处理；默认True则保持每条命中一个文档，保留粒度和来源可追溯性。

结合 LlamaIndex 的完整用法

MetalReader通常作为数据摄入阶段的第一步，把检索到的文档喂给 LlamaIndex 做索引构建或检索增强。一个典型的完整流程如下：

from llama_index.readers.metal import MetalReader from llama_index.core import VectorStoreIndex # 1. 初始化 Reader reader = MetalReader( api_key="<Metal API Key>", client_id="<Metal Client ID>", index_id="<Metal Index ID>", ) # 2. 按向量与过滤器检索 documents = reader.load_data( limit=10, query_embedding=[0.1, 0.2, 0.3], filters={"category": "tutorial"}, ) # 3. 用检索结果构建 LlamaIndex 索引 index = VectorStoreIndex.from_documents(documents)

由于MetalReader继承自BaseReader，它还可以无缝参与 LlamaIndex 的异步与惰性加载模式，例如通过aload_data在线程池中异步执行检索（见 base.py），或将文档转换为 LangChain 文档格式供多框架复用。

源码结构速览

本集成包在仓库中的完整布局如下，便于读者按图索骥：

llama-index-integrations/readers/llama-index-readers-metal/ ├── llama_index/readers/metal/ │ ├── __init__.py # 导出 MetalReader（__all__ = ["MetalReader"]） │ └── base.py # MetalReader 核心实现 ├── tests/ │ └── test_readers_metal.py # 继承关系测试 ├── README.md # 官方使用说明 └── pyproject.toml # 包元数据与依赖声明

包入口init.py 仅暴露MetalReader一个公开类，使用from llama_index.readers.metal import MetalReader即可导入。本文对应的 API 参考文档条目位于 docs/api_reference/api_reference/readers/metal.md，其生成的 mkdocstrings 指令members: - MetalReader即指向上述实现类。

小结

MetalReader是一个轻量、职责单一的向量库数据加载器：三个凭证完成初始化，一个load_data完成"向量检索 + 过滤器 + 文档化"的全流程，并在输出层通过separate_documents灵活控制文档粒度。结合本文梳理的 base.py 源码路径与依赖约束，你可以快速将它接入自己的 LlamaIndex 数据管道，作为从 Metal 向量存储回读数据的标准入口。

【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index