使用 llama-index-readers-graphql 的 GraphQLReader 将 GraphQL 查询结果加载为 LlamaIndex 文档-迪斯科星球

使用 llama-index-readers-graphql 的 GraphQLReader 将 GraphQL 查询结果加载为 LlamaIndex 文档

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

导读

本文围绕 LlamaIndex 官方数据连接器llama-index-readers-graphql中的GraphQLReader展开，介绍如何通过一个 GraphQL 端点（Endpoint）执行查询、携带变量与鉴权请求头，并将查询结果自动转换为 LlamaIndex 的Document对象，从而接入后续的索引构建、检索与 Agent 工具链路。读完本文，你将掌握GraphQLReader的安装方式、构造函数与load_data的完整参数语义、返回文档的序列化格式，以及将其与向量索引、Agent 工具集成的实战写法。

GraphQLReader 是什么

GraphQLReader是 LlamaIndex 官方维护的 GraphQL 数据加载器，归属于llama-index-integrations/readers/llama-index-readers-graphql包。它的定位非常明确：把任意 GraphQL 端点的查询结果聚合为 LlamaIndex 的Document列表，供后续索引（Index）、检索器（Retriever）或 Agent 工具消费。

从源码结构看（base.py），它继承自llama_index.core.readers.base.BaseReader，因此天然具备 LlamaIndex 数据加载器的标准接口。核心依赖是 Python 生态中成熟的 gql 库，查询执行、Schema 拉取、变量绑定等底层 HTTP/GraphQL 协议细节都由它承担，GraphQLReader自身专注做"结果 → Document"的转换。

GraphQL 端点 ──(gql Client)──> 查询结果 ──(yaml.dump)──> List[Document] ──> LlamaIndex 索引 / Agent

安装与依赖环境

GraphQLReader以独立集成包的形式发布，安装命令如下：

pip install llama-index-readers-graphql

从该包的 pyproject.toml 可以确认其运行依赖与版本约束：

依赖	版本约束	用途
`gql`	`>=3.5.0,<4`	GraphQL 客户端，负责 Schema 拉取与查询执行
`requests-toolbelt`	`>=1.0.0,<2`	HTTP 传输层辅助（与`gql`的 Requests 传输配合）
`llama-index-core`	`>=0.13.0,<0.15`	提供`Document`、`BaseReader`等核心类型
Python	`>=3.10,<4.0`	解释器版本要求

如果环境中缺少gql，GraphQLReader在初始化或调用加载方法时会抛出ImportError，提示信息为："gql" package not found, please run "pip install gql"（见 base.py）。因此手动安装gql即可满足该集成包的依赖。

构造函数：端点地址与请求头

GraphQLReader的构造函数签名如下（base.py）：

def __init__( self, uri: Optional[str] = None, headers: Optional[Dict] = None, ) -> None:

参数说明：

uri（str，可选）：GraphQL 端点的 URL，例如https://countries.trevorblades.com/。必须提供，否则会抛出ValueError，错误信息为"uri" must be provided.。
headers（Dict，可选）：附加的 HTTP 请求头，例如Authorization、X-API-Key等。缺省时内部会初始化为空字典{}。

构造时内部发生两件事：

使用gql.transport.requests.RequestsHTTPTransport(url=uri, headers=headers)创建基于requests的 HTTP 传输层；
创建gql.Client(transport=transport, fetch_schema_from_transport=True)。注意fetch_schema_from_transport=True意味着客户端会在首次执行查询时自动从端点拉取 GraphQL Schema（内省查询），因此端点必须允许 introspection。

需要特别说明：headers是鉴权的主要入口。对于需要 token 的私有 GraphQL API，典型的初始化方式如下：

from llama_index.readers.graphql import GraphQLReader reader = GraphQLReader( uri="https://api.example.com/graphql", headers={"Authorization": "Bearer YOUR_TOKEN"}, )

load_data：查询、变量与文档生成

数据加载的核心方法是load_data（base.py）：

def load_data(self, query: str, variables: Optional[Dict] = None) -> List[Document]:

参数语义：

query（str）：GraphQL 查询字符串，例如{ continents { code name } }。会通过gql.gql()解析为可执行的查询文档。
variables（Dict，可选）：查询变量（parameters），用于向查询中注入动态值。缺省时内部会归一化为空字典{}。

执行流程分三步：

通过self.client.execute(gql(query), variable_values=variables)执行查询，得到原始 JSON 结果（一个以顶层字段名为键的字典）。
遍历结果字典的每个顶层键：
- 若该键对应的值是一个列表，则对列表中的每个元素分别执行yaml.dump(v)生成一段文本，并各自封装为一个Document；
- 若该键对应的值不是列表（对象、标量等），则对整个值执行yaml.dump(entry)封装为单个Document。
返回List[Document]。

这一设计意味着：查询结果的嵌套结构会被拍平——一个包含多个列表项的查询会生成多个文档，而对象/标量类型的字段则聚合为单个文档。文本统一使用 YAML 序列化（yaml.dump），保证了复杂嵌套结构（对象、数组、标量）都能无损地转成文本表示。

完整使用示例

下面是一个端到端可运行的示例。以公开的 GraphQL 演示端点https://countries.trevorblades.com/为例（该端点由 gql 生态常用于演示，可在浏览器中直接内省测试查询），查询所有大洲的代码与名称：

from llama_index.core import VectorStoreIndex from llama_index.readers.graphql import GraphQLReader # 1. 初始化 reader uri = "https://countries.trevorblades.com/" headers = {} reader = GraphQLReader(uri, headers) # 2. 声明 GraphQL 查询 query = """ query getContinents { continents { code name } } """ # 3. 执行查询，得到 Document 列表 documents = reader.load_data(query, variables={}) print(f"共加载 {len(documents)} 个文档") # 4. 直接喂给 LlamaIndex 构建向量索引 index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine() response = query_engine.query("世界上有哪些大洲？") print(response)

说明：集成包 README.md 中的示例调用了reader.query(query, variables={})，但从当前仓库源码看，该集成实际公开的方法是load_data（query方法并不存在于 base.py 中）。以源码为准，统一使用load_data即可正常加载数据。

带变量的动态查询

很多 GraphQL API 需要查询参数（如按国家代码查询）。通过variables参数注入：

query = """ query getCountry($code: ID!) { country(code: $code) { name capital currency } } """ documents = reader.load_data( query, variables={"code": "CN"}, )

variables会通过variable_values原样透传给gql.Client.execute，因此支持$code: ID!这类强类型 GraphQL 变量声明。

返回文档的数据形态

load_data的返回类型是List[Document]，其中Document来自llama_index.core.schema。每次调用都返回全新的文档对象（代码中每次迭代都会Document(text=...)新建实例），因此连续多次调用不会产生累积或共享状态，每次查询的结果彼此隔离。

序列化格式统一为 YAML。以"查询所有大洲"为例，Document.text的实际内容形如：

code: AF name: Africa

每个大洲对应一个独立Document；若某个顶层字段不是列表，则该字段的整个对象会被 YAML 序列化为单个文档。这一格式便于后续解析，也便于直观阅读。

与 Agent 工具集成

由于GraphQLReader继承自BaseReader，除了喂给VectorStoreIndex等索引结构外，它还可以作为工具接入 LlamaIndex Agent（如 README 所述，该 Loader 设计目标之一是"作为 Agent 的工具使用"）。一个典型的封装方式是用FunctionTool包装查询能力：

from llama_index.core.tools import FunctionTool def query_graphql(query: str, variables: dict) -> str: """对 GraphQL 端点执行查询并返回 YAML 文本结果。""" reader = GraphQLReader(uri, headers) docs = reader.load_data(query, variables=variables or {}) return "\n---\n".join(d.text for d in docs) tool = FunctionTool.from_defaults( fn=query_graphql, name="graphql_reader", description="执行 GraphQL 查询并将结果作为文档文本返回", )

这样 Agent 便可在规划中按需调用 GraphQL 数据源，把实时查询结果注入推理上下文。

源码实现要点

GraphQLReader的实现非常精简（全文约 70 行，base.py），几个关键设计值得注意：

延迟导入依赖：gql.Client、gql.transport.requests.RequestsHTTPTransport与gql.gql均在方法内部try/except ImportError导入，而不是模块顶层导入。这样即使未安装gql，导入llama_index.readers.graphql本身也不会报错，只有真正使用GraphQLReader时才强制依赖。从__init__.py（graphql/init.py）可见该包只导出GraphQLReader一个符号。
客户端复用：Client在__init__中创建一次并保存在self.client，load_data内部复用同一个客户端执行多次查询，避免重复握手开销；fetch_schema_from_transport=True使首次执行时自动完成 Schema 拉取。
文档生成的扁平化策略：列表字段逐元素成文（一个列表项 = 一个 Document），非列表字段整体成文，这种策略保证"结果数量可预测"——文档数量大致等于查询返回的顶层列表项总数。
继承 BaseReader 标准接口：BaseReader在 base.py 中定义了lazy_load_data、load_data、aload_data、load_langchain_documents等约定接口。GraphQLReader直接实现load_data并返回List[Document]，与 LlamaIndex 索引构建、LangChain 文档转换等下游能力兼容。

测试与质量保障

集成包自带单元测试 test_readers_graphql.py，其中test_class断言：

names_of_base_classes = [b.__name__ for b in GraphQLReader.__mro__] assert BaseReader.__name__ in names_of_base_classes

即验证GraphQLReader确实继承自llama_index.core.readers.base.BaseReader，保证其符合 LlamaIndex 数据加载器的类型契约，可安全用于VectorStoreIndex.from_documents等标准流程。

注意事项与使用边界

端点必须允许内省（introspection）：由于客户端以fetch_schema_from_transport=True初始化，私有 API 若关闭 introspection 可能导致执行失败，可考虑先确认端点策略。
查询结果的顶层字段名：load_data以结果字典的顶层键为粒度切分文档，编写查询时请确认顶层字段是期望展开的列表（如continents），避免意外地把整个响应聚合为单个文档。
鉴权信息写入 headers：构造函数中的headers是唯一鉴权入口，请勿在uri中明文拼写凭据；token 类密钥建议从环境变量读取。
文档体积：每个列表项独立成文，若单条记录极大（含大量嵌套子对象），YAML 序列化后的文本可能较长，请在构建索引前结合切分器（Node Parser）进行文本切分。
方法名为load_data：该集成公开的数据加载方法为load_data（当前仓库 base.py 可验证），而非 README 示例中出现的query，编写代码时以源码为准。

小结

GraphQLReader为"把 GraphQL 作为 LlamaIndex 数据源"提供了极低成本的接入路径：两行初始化 + 一次load_data调用即可将任意 GraphQL 查询结果转成标准Document列表，进而构建向量索引、查询引擎或 Agent 工具。其实现依托成熟的gql客户端，整体代码量小、行为可预测，特别适合将已有的 GraphQL 后端服务直接纳入 RAG 数据管线。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析