基于 WordLift GraphQL API 的 LlamaIndex Reader 集成指南：从知识图谱到可检索文档

基于 WordLift GraphQL API 的 LlamaIndex Reader 集成指南：从知识图谱到可检索文档

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

WordLift 是一个面向 SEO 的知识图谱（Knowledge Graph）平台，其 GraphQL API 可以将结构化数据以查询结果的形式暴露出来。本文以仓库中 WordLift Reader 集成包 为核心，系统讲解WordLiftLoader的安装、配置、调用方式与底层实现原理，帮助读者将 WordLift 知识图谱中的实体数据一键拉取、清洗并转换为 LlamaIndex 的Document对象，进而直接接入向量索引与检索问答管线。

一、集成包概览：WordLift 数据如何进入 LlamaIndex

在 LlamaIndex 生态中，Reader（读取器）负责把外部数据源转换为统一的Document结构。WordLift Reader 正是这样一座桥梁：它通过 WordLift GraphQL API 获取知识图谱数据，将其转换为可供索引的文档列表，从而让开发者可以直接在 LlamaIndex 中构建基于 WordLift 语义数据的 RAG 应用。

该集成包位于仓库 llama-index-integrations/readers/llama-index-readers-wordlift 目录下，核心导出类为WordLiftLoader，定义于 base.py，包入口init.py 中通过__all__ = ["WordLiftLoader"]将其作为公共 API 暴露。

从 pyproject.toml 可以看到该包的核心依赖设计：

• llama-index-core>=0.13.0,<0.15：提供BaseReader基类与Document数据结构；
• graphql-core>=3.2.3,<4：用于 GraphQL 查询的解析与改写（分页注入）；
• bs4（BeautifulSoup）：用于 HTML 内容清洗与文本提取；
• langchain>=0.1.4,<0.2：示例代码中用于构建 LLM 查询链路。

包的版本号为 0.5.0，要求 Python 版本>=3.10,<4.0，采用 MIT 许可。

二、安装方式

与 LlamaIndex 其他集成包一致，WordLift Reader 通过 pip 独立安装：

pip install llama-index-readers-wordlift

安装完成后即可通过如下方式导入：

from llama_index.readers.wordlift import WordLiftLoader

三、快速上手：完整调用流程

WordLift 官方文档将WordLiftLoader的使用归纳为四步：配置参数 → 实例化 → 加载数据 → 后续处理。以下示例完整继承自 集成包 README：

import json from llama_index.core import VectorStoreIndex from llama_index.core import Document from langchain.llms import OpenAI from llama_index.readers.wordlift import WordLiftLoader # 第一步：设置必要的配置项 endpoint = "https://api.wordlift.io/graphql" headers = { "Authorization": "<YOUR_WORDLIFT_KEY>", "Content-Type": "application/json", } query = """ # 在这里填写你的 GraphQL 查询 """ fields = "<YOUR_FIELDS>" config_options = { "text_fields": ["<YOUR_TEXT_FIELDS>"], "metadata_fields": ["<YOUR_METADATA_FIELDS>"], } # 第二步：创建 WordLiftLoader 实例 reader = WordLiftLoader(endpoint, headers, query, fields, config_options) # 第三步：加载数据（拉取并转换为 Document 列表） documents = reader.load_data() # 第四步：转换文档并构建索引 converted_doc = [] for doc in documents: converted_doc_id = json.dumps(doc.doc_id) converted_doc.append( Document( text=doc.text, doc_id=converted_doc_id, embedding=doc.embedding, doc_hash=doc.doc_hash, extra_info=doc.extra_info, ) ) # 创建索引与查询引擎 index = VectorStoreIndex.from_documents(converted_doc) query_engine = index.as_query_engine() # 执行查询 result = query_engine.query("<YOUR_QUERY>") # 处理结果 logging.info("Result: %s", result)

其中endpoint指向 WordLift 的 GraphQL 端点，headers中的Authorization字段需要填入你的 WordLift Key（WordLift 平台概念中的 API 密钥）。完成load_data()后得到的Document列表可直接用于VectorStoreIndex.from_documents()构建向量索引。

四、核心 API 与参数语义详解

WordLiftLoader继承自 LlamaIndex 核心的BaseReader（llama_index.core.readers.base），这一点由集成包测试 test_readers_wordlift.py 中的test_class用例通过__mro__继承链断言验证。其构造函数接收五个位置参数：

其中configure_options是决定文档内容与元数据划分的关键：

• text_fields：声明哪些字段应当进入文档正文（Document.text）。transform_data会要求每个数据项必须包含全部text_fields中的键，否则跳过该条记录并输出 warning 日志；
• metadata_fields：声明哪些字段应当进入文档元数据（Document.extra_info）。若某条记录的元数据字段缺失，源码中会以默认值"n.a"填充并记录 warning。

WordLiftLoader对外暴露三个核心方法：

1.fetch_data()—— 拉取 API 数据

内部使用requests.post向endpoint发起 JSON 请求，请求体为{"query": 改写后的查询}。请求前会先调用alter_query()注入分页参数；若响应体中包含errors键，则抛出APICallError。

2.transform_data(data)—— 数据到文档的转换

从响应中取出data键下对应fields的内容，逐条构建Document：

• 文本部分由text_fields中声明的（支持点号嵌套路径）字段拼接而成，拼接前经flatten_list展平嵌套列表；
• 元数据部分遍历metadata_fields，字段值若为 URL 且指向有效 HTML 页面，则保留为可点击的元数据；否则经clean_value清洗后写入；
• 最终文本会移除换行符，并通过正则re.sub("<.*?>", "", text)剥除残留的 HTML 标签，得到纯文本存入Document.text。

3.load_data()—— 一站式加载入口

将fetch_data()与transform_data()串联：先拉取再转换，任何一步抛出APICallError或DataTransformError都会记录错误日志后向上抛出。这也正是 README 示例中直接调用reader.load_data()即可获得文档列表的原因。

五、分页机制：GraphQL 查询的自动改写

WordLiftLoader的一个关键设计是自动分页。其alter_query()方法使用graphql-core将用户提供的查询解析为 AST，定位第一个顶层查询字段，检查其是否已包含page参数：

• 若已存在page参数，则保持原样输出；
• 若不存在，则自动追加page与rows两个参数，默认值分别为DEFAULT_PAGE = 0与DEFAULT_ROWS = 500，即每页最多拉取 500 条记录。

从源码结构可以推断，这一机制让开发者无需在 GraphQL 查询中手动编写分页参数即可获得确定的返回规模，适合知识图谱中实体量较大的场景；同时page/rows约定也为后续通过循环调用load_data进行多页遍历预留了扩展空间。

六、数据清洗链路：URL 抓取与 HTML 文本提取

WordLift 知识图谱的字段值常常是富文本 HTML 或资源 URL，为此源码实现了一套多层次的清洗工具函数（均位于 base.py）：

• is_url(text)：通过urllib.parse.urlparse判断字符串是否为合法 URL（要求同时具备 scheme 与 netloc）；
• is_valid_html(content)：若内容是 URL，则发起 HTTP 请求并用 BeautifulSoup 检查响应是否包含<html>标签；若是普通字符串则直接解析检查，网络异常时返回False；
• clean_value(x)：对非列表标量值调用clean_html清洗；
• clean_html(text)：核心清洗逻辑，按值类型分支处理——URL 则抓取页面正文、本地文件路径则读取文件、普通字符串则直接解析，统一通过 BeautifulSoup 的get_text()提取纯文本；请求异常或解析失败时安全返回空字符串；
• get_separated_value(item, field_keys)：支持点号分隔的嵌套路径取值（如"author.name"），并自动处理列表类型（取首个元素）；
• flatten_list(lst)：递归展平嵌套列表，保证文本拼接时不会出现[['a'], ['b']]之类的嵌套结构。

这套链路保证最终进入Document的文本是干净的纯文本，便于后续分块、嵌入与索引。

七、异常处理体系

源码为集成包定义了三级异常结构（WordLiftLoaderError→APICallError/DataTransformError）：

• WordLiftLoaderError：所有异常的基类；
• APICallError：API 调用阶段的错误，包括网络连接失败（requests.exceptions.RequestException）与 GraphQL 响应中携带errors字段两类情况；
• DataTransformError：数据转换阶段的错误，任何未预期的转换异常都会被包装为该类型抛出。

load_data()只捕获并向上传播这两类具体异常，方便上层应用按阶段进行差异化处理（如重试网络请求、校验查询字段）。

八、工程落地要点

综合以上分析，在实际项目中接入 WordLift Reader 时有几点值得注意：

1. 查询字段与fields必须对应：fields指向 GraphQL 响应中data下的顶层键，text_fields/metadata_fields则指向该键内部的字段，三者需与 GraphQL 查询结果结构严格一致，否则数据项会被跳过或填充默认值；
2. 控制单页规模：默认每页 500 条（DEFAULT_ROWS），若知识图谱实体数量庞大，可通过改造query（提前声明page/rows）或分批加载来控制内存与请求开销；
3. 依赖外部网络：URL 类字段的清洗会发起真实 HTTP 请求（clean_html/is_valid_html），在无外网或目标站点不可达的环境中，相关字段会安全降级为空字符串，不会中断整个加载流程；
4. 与向量索引无缝衔接：load_data()输出的Document列表可直接交给VectorStoreIndex.from_documents()，配合查询引擎即可构建端到端的知识图谱问答应用。

小结

WordLift Reader 通过WordLiftLoader将 GraphQL 查询、自动分页、HTML 清洗、文档转换与异常处理封装为一个可复用的 LlamaIndex Reader，使 WordLift 知识图谱数据能够以标准Document形式进入 LlamaIndex 的索引与检索链路。本文所涉及的源码、测试与配置均可分别参考 base.py、test_readers_wordlift.py 与 pyproject.toml 深入研读。

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