使用 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 可以确认其运行依赖与版本约束依赖版本约束用途gql3.5.0,4GraphQL 客户端负责 Schema 拉取与查询执行requests-toolbelt1.0.0,2HTTP 传输层辅助与gql的 Requests 传输配合llama-index-core0.13.0,0.15提供Document、BaseReader等核心类型Python3.10,4.0解释器版本要求如果环境中缺少gqlGraphQLReader在初始化或调用加载方法时会抛出ImportError提示信息为gql package not found, please run pip install gql见 base.py。因此手动安装gql即可满足该集成包的依赖。构造函数端点地址与请求头GraphQLReader的构造函数签名如下base.pydef __init__( self, uri: Optional[str] None, headers: Optional[Dict] None, ) - None:参数说明uristr可选GraphQL 端点的 URL例如https://countries.trevorblades.com/。必须提供否则会抛出ValueError错误信息为uri must be provided.。headersDict可选附加的 HTTP 请求头例如Authorization、X-API-Key等。缺省时内部会初始化为空字典{}。构造时内部发生两件事使用gql.transport.requests.RequestsHTTPTransport(urluri, headersheaders)创建基于requests的 HTTP 传输层创建gql.Client(transporttransport, fetch_schema_from_transportTrue)。注意fetch_schema_from_transportTrue意味着客户端会在首次执行查询时自动从端点拉取 GraphQL Schema内省查询因此端点必须允许 introspection。需要特别说明headers是鉴权的主要入口。对于需要 token 的私有 GraphQL API典型的初始化方式如下from llama_index.readers.graphql import GraphQLReader reader GraphQLReader( urihttps://api.example.com/graphql, headers{Authorization: Bearer YOUR_TOKEN}, )load_data查询、变量与文档生成数据加载的核心方法是load_database.pydef load_data(self, query: str, variables: Optional[Dict] None) - List[Document]:参数语义querystrGraphQL 查询字符串例如{ continents { code name } }。会通过gql.gql()解析为可执行的查询文档。variablesDict可选查询变量parameters用于向查询中注入动态值。缺省时内部会归一化为空字典{}。执行流程分三步通过self.client.execute(gql(query), variable_valuesvariables)执行查询得到原始 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_dataquery方法并不存在于 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, variablesvariables or {}) return \n---\n.join(d.text for d in docs) tool FunctionTool.from_defaults( fnquery_graphql, namegraphql_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__.pygraphql/init.py可见该包只导出GraphQLReader一个符号。客户端复用Client在__init__中创建一次并保存在self.clientload_data内部复用同一个客户端执行多次查询避免重复握手开销fetch_schema_from_transportTrue使首次执行时自动完成 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_transportTrue初始化私有 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），仅供参考