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其运行依赖如下版本约束以仓库当前配置为准依赖版本约束用途metal-sdk2.5.1,3提供与 Metal 向量存储通信的官方 SDK 客户端llama-index-core0.13.0,0.15提供BaseReader基类与Document数据结构包要求的 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定位目标索引的唯一依据。初始化 MetalReaderMetalReader的构造函数签名为def __init__(self, api_key: str, client_id: str, index_id: str):三个参数含义如下参数类型说明api_keystrMetal 平台 API 密钥用于身份认证client_idstrMetal 客户端 ID标识你的租户/应用index_idstrMetal 索引 ID指定要检索的具体向量索引从源码实现看构造时除了做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_keyMetal API Key, client_idMetal Client ID, index_idMetal Index ID, )使用 load_data 检索文档初始化完成后通过load_data方法发起检索。其完整签名如下见 base.pydef 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]:参数说明参数类型默认值说明limitint必填返回结果的最大条数直接透传给 Metal 搜索接口query_embeddingOptional[List[float]]None查询向量用于向量相似度检索不传时依赖 Metal 侧索引配置filtersOptional[Dict[str, Any]]None元数据过滤器按字段精确筛选例如{field: value}separate_documentsboolTrue为True时每条命中记录生成独立Document为False时合并为单个Document**query_kwargsAny—透传给 Metal 搜索接口的附加关键字参数可扩展其他检索选项完整调用示例documents reader.load_data( limit10, # 返回最多 10 条结果 query_embedding[0.1, 0.2, 0.3], # 查询向量 filters{field: value}, # 元数据过滤 separate_documentsTrue, # 每条记录作为独立 Document )底层检索流程load_data的内部实现非常直接可以拆解为三步base.py第一步组装请求负载payload { embedding: query_embedding, filters: filters, } response self.metal_client.search(payload, limitlimit, **query_kwargs)即把查询向量与过滤器打包进 payload连同limit和透传的query_kwargs一起交给 Metal SDK 的search方法。第二步逐条转换为 Documentfor item in response[data]: text item[text] or (item[metadata] and item[metadata][text]) documents.append(Document(texttext))这里体现了 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(texttext)]当separate_documentsFalse时所有命中文本以两个换行符\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_keyMetal API Key, client_idMetal Client ID, index_idMetal Index ID, ) # 2. 按向量与过滤器检索 documents reader.load_data( limit10, 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考