LlamaIndex WeaviateReader 实战指南从 Weaviate 向量数据库加载文档的两种核心方式【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文聚焦 LlamaIndex 官方集成包llama-index-readers-weaviate中的核心组件WeaviateReader完整讲解如何通过向量查询从 Weaviate 向量数据库中将已有数据加载为 LlamaIndex 的Document对象。读完本文你将掌握WeaviateReader的安装与初始化方法、基于class_nameproperties的结构化加载方式、基于原生 GraphQL Get 查询的灵活加载方式以及separate_documents参数对输出文档粒度的影响并能深入理解其底层实现原理与调用链。一、WeaviateReader 是什么WeaviateReader是 LlamaIndex 官方提供的 Weaviate 数据加载器Reader位于集成包llama-index-readers-weaviate中。它的职责非常聚焦从 Weaviate 向量数据库通过向量查询vector lookup检索文档并把检索结果转换为 LlamaIndex 的Document对象供后续索引构建、检索与问答流程使用。从源码结构看WeaviateReader继承自llama_index.core.readers.base.BaseReader见 base.py实现了标准 Reader 接口可以无缝融入 LlamaIndex 的加载管线。包内的测试用例 test_readers_weaviate.py 验证了这一点WeaviateReader的 MRO方法解析顺序中确实包含BaseReader。该 Reader 适用于以下典型场景已有数据存放在 Weaviate 中希望将其加载回 LlamaIndex 进行索引重建或二次处理通过 Weaviate 的向量检索能力做相似度召回后将结果直接作为 LLM 上下文的候选文档在 Agent 工具链中将 Weaviate 作为外部知识库用 Reader 封装数据访问逻辑。二、安装与依赖pip install llama-index-readers-weaviate从包的 pyproject.toml 可以看到它的核心依赖依赖包版本约束说明weaviate-client3.26.2,4Weaviate 官方 Python 客户端v3 系列llama-index-core0.13.0,0.15LlamaIndex 核心库提供Document与BaseReader基类包的import_path为llama_index.readers.weaviate见 pyproject.toml安装后直接通过该路径导入即可。值得注意的是weaviate-client并非随包自动安装的硬依赖而是采用延迟导入策略在WeaviateReader.__init__中才执行import weaviate若未安装会抛出明确的错误提示weaviatepackage not found, please run pip install weaviate-client见 base.py。因此如果环境缺失客户端可单独补装pip install weaviate-client三、初始化 WeaviateReaderWeaviateReader的构造函数只有两个参数见 base.py参数类型是否必填说明hoststr是Weaviate 服务地址auth_client_secretOptional[weaviate.auth.AuthCredentials]否认证凭证如 API Key、用户名密码等默认Nonefrom llama_index.readers.weaviate import WeaviateReader # 无认证场景 reader WeaviateReader(hosthttp://localhost:8080) # 带认证场景以 API Key 为例具体凭证类型取决于 Weaviate 服务端配置 reader WeaviateReader( hosthttp://localhost:8080, auth_client_secretyour-api-key, )初始化时__init__内部会基于host和auth_client_secret直接构造weaviate.Client实例并保存在self.client上见 base.py。这意味着一旦WeaviateReader构建成功底层客户端即已就绪后续load_data调用直接复用该连接。注意auth_client_secret的类型为Optional[Any]见 base.py实际应传入weaviate.auth.AuthCredentials体系下的凭证对象具体请以 Weaviate 服务端启用的认证方式为准。四、加载数据的两种核心方式load_data是WeaviateReader的核心方法支持两种互斥的查询来源见 base.py方式传入参数适用场景结构化加载class_nameproperties简单场景按类名和字段列表全量/部分拉取原生 GraphQLgraphql_query复杂场景需要过滤、向量相似度排序等高级查询能力方法的完整签名如下def load_data( self, class_name: Optional[str] None, properties: Optional[List[str]] None, graphql_query: Optional[str] None, separate_documents: Optional[bool] True, ) - List[Document]:4.1 方式一class_name properties 结构化加载这是最直观的用法指定 Weaviate 中的类Class名与要取回的属性Property列表Reader 会自动拼接成 GraphQL Get 查询并执行。# 1) 使用 class_name 和 properties 加载数据 documents reader.load_data( class_nameclass_name, properties[property1, property2, ...], separate_documentsTrue, )从源码实现看见 base.py当class_name与properties同时提供时Reader 内部会构造如下 GraphQL 查询并调用self.client.query.raw(graphql_query){ Get { class_name { property1 property2 } } }也就是说方式一本质上是方式二在只需按属性取回数据时的语法糖。4.2 方式二原生 GraphQL 查询当需要更精细的控制如where过滤、向量相似度排序、limit限制等时直接传入完整的 GraphQL Get 查询字符串。# 2) 示例 GraphQL 查询 query { Get { class_name( limit: 10 ) { property1 property2 } } } documents reader.load_data( graphql_queryquery, separate_documentsTrue, )源码中明确注释传入graphql_query时假定该查询是Get 查询见 base.py。执行后 Reader 会校验响应若返回体包含errors字段或缺少Get键将抛出ValueError见 base.py。4.3 参数校验规则源码明确规定了三种入参组合的合法性见 base.pyclass_name与properties同时提供自动生成查询仅提供graphql_query直接使用该查询两者都未提供抛出ValueError提示 Eitherclass_nameandpropertiesmust be specified, orgraphql_querymust be specified.五、separate_documents控制输出文档粒度separate_documents参数决定返回结果的聚合方式默认值为True见 base.py。默认行为separate_documentsTrueWeaviate 返回的每一条记录entry都会转换为一个独立的Document对象。对每条记录Reader 遍历其字段将非_additional的字段拼接为key: value形式并以换行分隔组成文本若_additional.vector存在则将其作为该文档的embedding一并写入Document见 base.py。# 默认一条 Weaviate 记录 → 一个 Document documents reader.load_data( class_nameAuthor, properties[name, description], separate_documentsTrue, )合并行为separate_documentsFalse所有记录先各自转成Document再将所有文本用\n\n连接最终合并为单个Document见 base.py。# 合并全部记录 → 单个 Document documents reader.load_data( class_nameAuthor, properties[name, description], separate_documentsFalse, )选择建议若后续需要按条目精细检索、保留每条的独立语义用True若只是想把整批数据作为一段完整上下文交给 LLM用False更省 token 与节点数。六、底层原理从查询到 Document 的完整链路WeaviateReader的调用链可以概括为一条清晰的流水线全部实现见 base.py查询构造L66-L83根据入参组合生成 GraphQL Get 查询字符串原生执行L85self.client.query.raw(graphql_query)直接通过 weaviate-client v3 的query.raw接口发送 GraphQL 请求响应校验L86-L91检查errors字段与Get键保证响应形态合法类名推断L93-L95若只传了graphql_query则从响应data.Get的第一个键推断实际查询的类名字段扁平化L98-L111逐条记录将k: v拼接成纯文本_additional.vector单独抽取为 embedding文档聚合L113-L117依据separate_documents决定保留多文档还是合并为单文档产出返回List[Document]每个Document同时携带text与可选的embedding。从集成包的设计看WeaviateReader与同目录下的向量存储集成llama-index-vector-stores-weaviate职责分离前者负责读入数据后者负责写入与检索。二者配合即可构成写入 Weaviate → 从 Weaviate 读回 LlamaIndex的完整数据闭环。仓库中的 Notebook 示例 weaviate_existing_data.ipynb 展示了如何在已有 Weaviate 数据上使用 Reader 加载现有数据可作为组合实践的参考。七、常见问题与注意事项1. 未安装 weaviate-client 报错WeaviateReader采用延迟导入未安装时会提示运行pip install weaviate-client见 base.py。同时注意包依赖限定了weaviate-client3.26.2,4请勿直接安装 v4 版本客户端见 pyproject.toml。2. 查询响应报 Invalid query, got errors说明 GraphQL 查询本身有误类名、属性名拼写或语法问题Weaviate 返回了errors字段Reader 会直接抛出ValueError并携带原始错误信息见 base.py。3. 报 Invalid query response, must be a Get query.说明查询结果中没有Get键——本 Reader 只支持 Get 查询不支持 Aggregate、Explore 等其他 GraphQL 查询类型见 base.py。4. 想带过滤条件加载使用方式二在 GraphQL 查询中自行编写where、limit、nearVector等子句Reader 会原样透传给 Weaviate 执行。5. embedding 如何保留只有在查询中显式请求_additional { vector }时返回记录才会携带_additional.vectorReader 才会把它写入Document.embedding。若你的查询未包含该字段文档的 embedding 将为None。八、小结WeaviateReader是一个轻量、专注的 Weaviate 数据加载器一条host完成初始化两种入参组合覆盖从简单按类取数到复杂 GraphQL 检索的全部需求一个separate_documents开关控制输出文档粒度。它继承自BaseReader、产出标准Document可以无缝接入 LlamaIndex 的索引与检索流程是将 Weaviate 中沉淀的向量数据回灌到 LlamaIndex 生态的首选入口。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex WeaviateReader 实战指南：从 Weaviate 向量数据库加载文档的两种核心方式
LlamaIndex WeaviateReader 实战指南从 Weaviate 向量数据库加载文档的两种核心方式【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文聚焦 LlamaIndex 官方集成包llama-index-readers-weaviate中的核心组件WeaviateReader完整讲解如何通过向量查询从 Weaviate 向量数据库中将已有数据加载为 LlamaIndex 的Document对象。读完本文你将掌握WeaviateReader的安装与初始化方法、基于class_nameproperties的结构化加载方式、基于原生 GraphQL Get 查询的灵活加载方式以及separate_documents参数对输出文档粒度的影响并能深入理解其底层实现原理与调用链。一、WeaviateReader 是什么WeaviateReader是 LlamaIndex 官方提供的 Weaviate 数据加载器Reader位于集成包llama-index-readers-weaviate中。它的职责非常聚焦从 Weaviate 向量数据库通过向量查询vector lookup检索文档并把检索结果转换为 LlamaIndex 的Document对象供后续索引构建、检索与问答流程使用。从源码结构看WeaviateReader继承自llama_index.core.readers.base.BaseReader见 base.py实现了标准 Reader 接口可以无缝融入 LlamaIndex 的加载管线。包内的测试用例 test_readers_weaviate.py 验证了这一点WeaviateReader的 MRO方法解析顺序中确实包含BaseReader。该 Reader 适用于以下典型场景已有数据存放在 Weaviate 中希望将其加载回 LlamaIndex 进行索引重建或二次处理通过 Weaviate 的向量检索能力做相似度召回后将结果直接作为 LLM 上下文的候选文档在 Agent 工具链中将 Weaviate 作为外部知识库用 Reader 封装数据访问逻辑。二、安装与依赖pip install llama-index-readers-weaviate从包的 pyproject.toml 可以看到它的核心依赖依赖包版本约束说明weaviate-client3.26.2,4Weaviate 官方 Python 客户端v3 系列llama-index-core0.13.0,0.15LlamaIndex 核心库提供Document与BaseReader基类包的import_path为llama_index.readers.weaviate见 pyproject.toml安装后直接通过该路径导入即可。值得注意的是weaviate-client并非随包自动安装的硬依赖而是采用延迟导入策略在WeaviateReader.__init__中才执行import weaviate若未安装会抛出明确的错误提示weaviatepackage not found, please run pip install weaviate-client见 base.py。因此如果环境缺失客户端可单独补装pip install weaviate-client三、初始化 WeaviateReaderWeaviateReader的构造函数只有两个参数见 base.py参数类型是否必填说明hoststr是Weaviate 服务地址auth_client_secretOptional[weaviate.auth.AuthCredentials]否认证凭证如 API Key、用户名密码等默认Nonefrom llama_index.readers.weaviate import WeaviateReader # 无认证场景 reader WeaviateReader(hosthttp://localhost:8080) # 带认证场景以 API Key 为例具体凭证类型取决于 Weaviate 服务端配置 reader WeaviateReader( hosthttp://localhost:8080, auth_client_secretyour-api-key, )初始化时__init__内部会基于host和auth_client_secret直接构造weaviate.Client实例并保存在self.client上见 base.py。这意味着一旦WeaviateReader构建成功底层客户端即已就绪后续load_data调用直接复用该连接。注意auth_client_secret的类型为Optional[Any]见 base.py实际应传入weaviate.auth.AuthCredentials体系下的凭证对象具体请以 Weaviate 服务端启用的认证方式为准。四、加载数据的两种核心方式load_data是WeaviateReader的核心方法支持两种互斥的查询来源见 base.py方式传入参数适用场景结构化加载class_nameproperties简单场景按类名和字段列表全量/部分拉取原生 GraphQLgraphql_query复杂场景需要过滤、向量相似度排序等高级查询能力方法的完整签名如下def load_data( self, class_name: Optional[str] None, properties: Optional[List[str]] None, graphql_query: Optional[str] None, separate_documents: Optional[bool] True, ) - List[Document]:4.1 方式一class_name properties 结构化加载这是最直观的用法指定 Weaviate 中的类Class名与要取回的属性Property列表Reader 会自动拼接成 GraphQL Get 查询并执行。# 1) 使用 class_name 和 properties 加载数据 documents reader.load_data( class_nameclass_name, properties[property1, property2, ...], separate_documentsTrue, )从源码实现看见 base.py当class_name与properties同时提供时Reader 内部会构造如下 GraphQL 查询并调用self.client.query.raw(graphql_query){ Get { class_name { property1 property2 } } }也就是说方式一本质上是方式二在只需按属性取回数据时的语法糖。4.2 方式二原生 GraphQL 查询当需要更精细的控制如where过滤、向量相似度排序、limit限制等时直接传入完整的 GraphQL Get 查询字符串。# 2) 示例 GraphQL 查询 query { Get { class_name( limit: 10 ) { property1 property2 } } } documents reader.load_data( graphql_queryquery, separate_documentsTrue, )源码中明确注释传入graphql_query时假定该查询是Get 查询见 base.py。执行后 Reader 会校验响应若返回体包含errors字段或缺少Get键将抛出ValueError见 base.py。4.3 参数校验规则源码明确规定了三种入参组合的合法性见 base.pyclass_name与properties同时提供自动生成查询仅提供graphql_query直接使用该查询两者都未提供抛出ValueError提示 Eitherclass_nameandpropertiesmust be specified, orgraphql_querymust be specified.五、separate_documents控制输出文档粒度separate_documents参数决定返回结果的聚合方式默认值为True见 base.py。默认行为separate_documentsTrueWeaviate 返回的每一条记录entry都会转换为一个独立的Document对象。对每条记录Reader 遍历其字段将非_additional的字段拼接为key: value形式并以换行分隔组成文本若_additional.vector存在则将其作为该文档的embedding一并写入Document见 base.py。# 默认一条 Weaviate 记录 → 一个 Document documents reader.load_data( class_nameAuthor, properties[name, description], separate_documentsTrue, )合并行为separate_documentsFalse所有记录先各自转成Document再将所有文本用\n\n连接最终合并为单个Document见 base.py。# 合并全部记录 → 单个 Document documents reader.load_data( class_nameAuthor, properties[name, description], separate_documentsFalse, )选择建议若后续需要按条目精细检索、保留每条的独立语义用True若只是想把整批数据作为一段完整上下文交给 LLM用False更省 token 与节点数。六、底层原理从查询到 Document 的完整链路WeaviateReader的调用链可以概括为一条清晰的流水线全部实现见 base.py查询构造L66-L83根据入参组合生成 GraphQL Get 查询字符串原生执行L85self.client.query.raw(graphql_query)直接通过 weaviate-client v3 的query.raw接口发送 GraphQL 请求响应校验L86-L91检查errors字段与Get键保证响应形态合法类名推断L93-L95若只传了graphql_query则从响应data.Get的第一个键推断实际查询的类名字段扁平化L98-L111逐条记录将k: v拼接成纯文本_additional.vector单独抽取为 embedding文档聚合L113-L117依据separate_documents决定保留多文档还是合并为单文档产出返回List[Document]每个Document同时携带text与可选的embedding。从集成包的设计看WeaviateReader与同目录下的向量存储集成llama-index-vector-stores-weaviate职责分离前者负责读入数据后者负责写入与检索。二者配合即可构成写入 Weaviate → 从 Weaviate 读回 LlamaIndex的完整数据闭环。仓库中的 Notebook 示例 weaviate_existing_data.ipynb 展示了如何在已有 Weaviate 数据上使用 Reader 加载现有数据可作为组合实践的参考。七、常见问题与注意事项1. 未安装 weaviate-client 报错WeaviateReader采用延迟导入未安装时会提示运行pip install weaviate-client见 base.py。同时注意包依赖限定了weaviate-client3.26.2,4请勿直接安装 v4 版本客户端见 pyproject.toml。2. 查询响应报 Invalid query, got errors说明 GraphQL 查询本身有误类名、属性名拼写或语法问题Weaviate 返回了errors字段Reader 会直接抛出ValueError并携带原始错误信息见 base.py。3. 报 Invalid query response, must be a Get query.说明查询结果中没有Get键——本 Reader 只支持 Get 查询不支持 Aggregate、Explore 等其他 GraphQL 查询类型见 base.py。4. 想带过滤条件加载使用方式二在 GraphQL 查询中自行编写where、limit、nearVector等子句Reader 会原样透传给 Weaviate 执行。5. embedding 如何保留只有在查询中显式请求_additional { vector }时返回记录才会携带_additional.vectorReader 才会把它写入Document.embedding。若你的查询未包含该字段文档的 embedding 将为None。八、小结WeaviateReader是一个轻量、专注的 Weaviate 数据加载器一条host完成初始化两种入参组合覆盖从简单按类取数到复杂 GraphQL 检索的全部需求一个separate_documents开关控制输出文档粒度。它继承自BaseReader、产出标准Document可以无缝接入 LlamaIndex 的索引与检索流程是将 Weaviate 中沉淀的向量数据回灌到 LlamaIndex 生态的首选入口。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考