Jean's Blog

一个专注软件测试开发技术的个人博客

0%

RAG组件--数据导入之结构化文本的读取

发表于 分类于
学习大模型RAG系统学习笔记第五讲

使用LangChain的JSON Loader

  • 结构化文档特点：JSON、网页、Markdown等文档具有数据结构，解析时应尽量保留原有结构信息
  • 基本用法：通过JSONLoader加载JSON文件，配合jq_schema指定解析规则
  • 输出格式：解析结果包含metadata和page_content两部分，metadata记录来源信息，page_content包含提取的字段内容

代码示例：

1
2
3
4
5
6
from langchain_community.document_loaders import TextLoader

print("=== TextLoader 加载结果 ===")
text_loader = TextLoader("../data/灭神纪/人物角色.json")
text_documents = text_loader.load()
print(text_documents)

执行结果，输出内容：

1
2
=== TextLoader 加载结果 ===
[Document(metadata={'source': '../data/灭神纪/人物角色.json'}, page_content='{\n  "gameTitle": "西游记",\n  "basicInfo": { "engine": "虚幻引擎5", "releaseDate": "2024-08-20", "genre": "动作角色扮演", "platforms": ["PC", "PS5", "Xbox Series X/S"], "supportedLanguages": ["简体中文", "繁体中文", "英语", "日语", "韩语"] },\n  "mainCharacter": { "name": "孙悟空", "backstory": "混沌初开之时，盘古开天辟地，天地灵气凝结成仙石，其中孕育出一只石猴。这只石猴拜师菩提老祖，修得一身本领，后被赐名孙悟空。", "abilities": ["七十二变", "筋斗云", "火眼金睛", "金刚不坏之身"], "weapons": ["如意金箍棒", "法器", "神通符咒"], "combatStyle": "基于变身系统的高速格斗，结合中国传统神话元素的技能组合" },\n  "supportCharacters": [\n    { "name": "白龙马", "identity": "八部天龙之一", "background": "原为西海龙王三太子敖烈，因冒犯天条被贬为马，后随唐僧西行取经，成为孙悟空的伙伴", "abilities": ["水遁", "腾云驾雾", "变化"] },\n    { "name": "红孩儿", "identity": "圣婴大王", "background": "牛魔王与铁扇公主之子，修炼火焰三昧，掌握三昧真火", "abilities": ["三昧真火", "火眼", "战斗形态"] },\n    { "name": "六耳猕猴", "identity": "孙悟空分身", "background": "天地间与美猴王最像的存在，有着与孙悟空相似的能力", "abilities": ["七十二变", "法术", "分身术"] }\n  ],\n  "gameFeatures": { "worldSetting": "基于西游记神话背景，融合虚构的玄幻世界", "combatSystem": "独特的变身战斗系统，结合高难度动作玩法", "progression": "技能树发展系统，解锁新的战斗技能和变身形态", "exploration": "开放式地图探索，丰富的支线任务和隐藏剧情", "graphics": "采用虚幻引擎5, 实现高质量画面表现和实时光线追踪" }\n}\n')]
  • 文件结构：包含gameTitle、basicInfo、mainCharacter、supportCharacters等结构化字段
  • 解析目标：需要分门别类提取主角信息和配角信息
  • 局限性：将所有内容堆叠在同一个page_content中，无法区分不同字段
  • 问题：需要手动解析字符串，难以准确定位特定字段内容

json loader与jq schema

由于上述问题，我们需要进行数据处理，因此使用jq schema：

  • jq schema作用：指定需要提取的字段及其格式
  • 优势：
    • 自动将不同角色解析为独立document
    • 保留sequence number等元数据
    • 实现数据切片功能

安装包

1
pip install -qU jq

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from langchain_community.document_loaders import JSONLoader

print("=== JSONLoader 加载结果 ===")
print("1. 主角信息：")
main_loader = JSONLoader(
    file_path="../data/灭神纪/人物角色.json",
    jq_schema='.mainCharacter | "姓名：" + .name + "，背景：" + .backstory',
    text_content=True
)
main_char = main_loader.load()
print(main_char)

print("\n2. 支持角色信息：")
support_loader = JSONLoader(
    file_path="../data/灭神纪/人物角色.json",
    jq_schema='.supportCharacters[] | "姓名：" + .name + "，背景：" + .background',
    text_content=True
)
support_chars = support_loader.load()
print(support_chars)

执行结果，输出内容：

1
2
3
4
5
6
=== JSONLoader 加载结果 ===
1. 主角信息：
[Document(metadata={'source': '/Users/jinglv/PycharmProjects/llm-rag-system/data/灭神纪/人物角色.json', 'seq_num': 1}, page_content='姓名：孙悟空，背景：混沌初开之时，盘古开天辟地，天地灵气凝结成仙石，其中孕育出一只石猴。这只石猴拜师菩提老祖，修得一身本领，后被赐名孙悟空。')]

2. 支持角色信息：
[Document(metadata={'source': '/Users/jinglv/PycharmProjects/llm-rag-system/data/灭神纪/人物角色.json', 'seq_num': 1}, page_content='姓名：白龙马，背景：原为西海龙王三太子敖烈，因冒犯天条被贬为马，后随唐僧西行取经，成为孙悟空的伙伴'), Document(metadata={'source': '/Users/jinglv/PycharmProjects/llm-rag-system/data/灭神纪/人物角色.json', 'seq_num': 2}, page_content='姓名：红孩儿，背景：牛魔王与铁扇公主之子，修炼火焰三昧，掌握三昧真火'), Document(metadata={'source': '/Users/jinglv/PycharmProjects/llm-rag-system/data/灭神纪/人物角色.json', 'seq_num': 3}, page_content='姓名：六耳猕猴，背景：天地间与美猴王最像的存在，有着与孙悟空相似的能力')]

使用LangChain的网页加载器

image-20250806093810747

  • WebBaseLoader：基于urllib和BeautifulSoup，适合基本网页抓取
  • UnstructuredLoader：支持复杂网页结构，保留元素间关系
  • RecursiveURLLoader：递归抓取子链接，适合大规模站点
  • SitemapLoader：通过站点地图快速获取所有页面
  • FirecrawlLoader：API服务，适合实时抓取应用

WebBaseLoader

  • 基本用法：指定URL即可抓取网页内容
  • 优化技巧：
    • 使用bs4.SoupStrainer限定解析范围（如只解析bodyContent）
    • 调整bs_get_text_kwargs参数控制输出格式
  • 输出内容：包含source、title、language等metadata

示例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import bs4
from langchain_community.document_loaders import WebBaseLoader

page_url = "https://zh.wikipedia.org/wiki/黑神话：悟空"
# loader = WebBaseLoader(web_paths=[page_url])
# docs = []
# docs = loader.load()
# assert len(docs) == 1
# doc = docs[0]
# print(f"{doc.metadata}\n")
# print(doc.page_content.strip()[:3000])


# 只解析文章的主体部分
loader = WebBaseLoader(
    web_paths=[page_url],
    bs_kwargs={
        "parse_only": bs4.SoupStrainer(id="bodyContent"),
    },
    # bs_get_text_kwargs={"separator": " | ", "strip": True},
)
docs = []
docs = loader.load()
assert len(docs) == 1
doc = docs[0]
print(f"{doc.metadata}\n")
print(doc.page_content)

执行结果，输出内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{'source': 'https://zh.wikipedia.org/wiki/黑神话：悟空'}






维基百科，自由的百科全书



黑神话：悟空类型動作角色扮演[1]平台Microsoft WindowsPlayStation 5Xbox Series X/S（暂未发售）开发商游戏科学发行商全球：游戏科学臺灣：4Divinity制作人冯骥、杨奇编剧冯骥美术杨奇[2]、王怡新[3]音乐8082 Audio引擎虚幻引擎5[4]模式单人游戏发行日
2024年8月20日
Microsoft Windows全球：2024年8月20日PlayStation 5全球：2024年8月20日臺灣：2024年11月1日全球：2024年12月（實體豪華版）中国大陆：2025年6月18日Xbox Series X/S全球：2025年8月20日

《黑神话：悟空》是一款由游戏科学开发和发行的动作角色扮演游戏，被新华社称为中国首款“3A游戏”[5]，游戏于2024年8月20日登入Windows（Steam、Epic Games、WeGame）及PlayStation 5平台，Xbox Series X/S版预定2025年8月20日发售。
游戏内容改编自中国四大名著之一的《西游记》[6]，在正式发布前，游戏已获得业界媒体与评论家们的普遍好评，称赞其在战斗系统、视觉设计以及世界观方面的构建。游戏上线后迅速登顶多个平台的销量榜首，官方宣布首发3天内全球销量超过1000万份[7]，发售后一个月内全球销量超过2000万份[8]，成为有史以来销售速度最快的游戏之一。[9]


玩法[编辑]
《黑神话：悟空》是一款动作角色扮演游戏，[10]采用单人模式和第三人称视角。尽管在游戏发布前因為本作借鑒了不少魂类遊戲要素，曾有人讨论其是否属于魂类游戏，但其开发商游戏科学并不认为它属于这一类型[11]，许多评论者也认为该游戏并不完全符合“魂类”游戏的定义。[12][13]
游戏的设计灵感源于中国四大名著之一——古典神魔小說《西游记》，玩家将操控一位名为“天命人”的花果山灵明石猴。主角的主要武器是如意金箍棒等棍棒类武器，能在战斗中伸缩自如。游戏的战斗系统包括三种主要棍法：劈棍、戳棍和立棍，为战斗提供多样化选择。战斗还涉及资源管理，玩家可以积累气力值，用于连招或蓄力重击。冲刺、闪避和攻击都会消耗气力值。[14][15]
除了物理战斗，玩家还可以使用“奇术”、“身法”、“毫毛”和“变化”等四类法术。[16]这些法术有冷却时间并消耗法力值。各类法术按技能可再细分，例如：“定身”奇术可以在短时间内定住敌人；“聚形散气”身法可散气遁走并留下假身，聚形时可再行突袭，造成更高的伤害；“身外身法”的毫毛法术能召唤多个分身协助战斗，而各种变化法术允许主角变形为不同的游戏内角色，并拥有独特的招式和生命值。[12]此外，玩家可以通过击败强大的敌人获得“精魄”技能，这些技能类似于一次性的变身，例如，“幽魂”精魄可以让玩家进行头锤攻击。[17]
游戏的进程大多是线性的，亦有较为宽阔的区域供玩家探索。玩家会遇到各种妖怪和头目作为敌人。玩家的检查点是世界各地的神龛（土地庙）。游戏地图无法由玩家调整，但会随游戏进展而变化。[18]
此外，游戏也支持多周目模式，为玩家提供“再入轮回”的玩法和彩蛋。[19]例如，进入二周目可以解锁“救命”的毫毛法术，在战斗中死亡可以立即复活；[20]三周目怪物变强；四周目敌人强度大幅提升，并触发四段棍势彩蛋等。[21][22]一至六周目游戏难度（敌人伤害）逐渐提升，第七周目起游戏难度不再变化。
...

检索自“https://zh.wikipedia.org/w/index.php?title=黑神话：悟空&oldid=88025374”
分类：​2024年電子遊戲2024年中国作品中国大陆开发电子游戏原生中文游戏Windows游戏PlayStation 5游戏Xbox Series X/S游戏动作角色扮演游戏虚幻引擎5游戏西遊記題材電子遊戲单人电子游戏魂系遊戲金摇杆奖年度游戏得主遊戲大獎得主孙悟空隐藏分类：​CS1英语来源 (en)引文格式1错误：日期CS1泰语来源 (th)CS1美国英语来源 (en-us)有蓝链却未移除内部链接助手模板的页面使用多个图像且自动缩放的页面自2025年1月缺少重要資訊的條目VG Reviews模板使用單平台模式的條目

UnstructuredLoader

  • 核心功能：解析网页元素类型（Title、ListItem等）和父子关系
  • 关键应用：
    • 通过parent_id保持内容与标题的关联
    • 避免信息切片时丢失上下文关系
  • 典型场景：处理参考资料列表时确保每个条目与”参考资料”标题保持关联

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
from langchain_unstructured import UnstructuredLoader
from typing import List
from langchain_core.documents import Document

page_url = "https://zh.wikipedia.org/wiki/黑神话：悟空"

def _get_setup_docs_from_url(url: str) -> List[Document]:
    loader = UnstructuredLoader(web_url=url)
    setup_docs = []
    # parent_id = None  # 初始化 parent_id
    # current_parent = None  # 用于存储当前父元素
    for doc in loader.load():
        # 检查是否是 Title 或 Table
        if doc.metadata["category"] == "Title" or doc.metadata["category"] == "Table":
            parent_id = doc.metadata["element_id"]
            current_parent = doc  # 更新当前父元素
            setup_docs.append(doc)
        elif doc.metadata.get("parent_id") == parent_id:
            setup_docs.append((current_parent, doc))  # 将父元素和子元素一起存储
    return setup_docs   
    
docs = _get_setup_docs_from_url(page_url)

for item in docs:
    if isinstance(item, tuple):
        parent, child = item
        print(f'父元素 - {parent.metadata["category"]}: {parent.page_content}')
        print(f'子元素 - {child.metadata["category"]}: {child.page_content}')
    else:
        print(f'{item.metadata["category"]}: {item.page_content}')
    print("-" * 80)

执行结果，输出内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
Title: 黑神话：悟空
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: العربية
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: مصرى
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: Azərbaycanca
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: Беларуская (тарашкевіца)
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: Català
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: 閩東語 / Mìng-dĕ̤ng-ngṳ̄
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: Deutsch
--------------------------------------------------------------------------------
父元素 - Title: 黑神话：悟空
子元素 - ListItem: English
...
子元素 - ListItem: 官方网站
--------------------------------------------------------------------------------
Table: 查 论 编 《 西游记 》 可能作者： 吴承恩 · 丘处机 起源 《 大唐三藏取經詩話 》 《 杂剧西游记 》 《 大唐西域記 》 登場角色 主要角色 唐三藏 孙悟空 猪八戒 沙僧 白龙马 主要配角 如来佛祖 观音菩萨 玉皇大帝 太上老君 太白金星 菩提祖师 二郎神 托塔天王 哪吒 木吒 毗蓝婆菩萨 主要反派 混世魔王 白骨精 牛魔王 鐵扇公主 大鵬金翅鵰 地涌夫人 紅孩兒 蜘蛛精 六耳獼猴 蝎子精 青牛怪 作中事物 法寶 如意金箍棒 筋斗雲 九齿钉耙 降妖寶杖 芭蕉扇 七十二变 紧箍咒 地點 東勝神洲 西牛賀洲 傲来国 花果山 火焰山 盘丝洞 西天 續書和相关著作 《 後西遊記 》 《 续西游记 》 《 西遊補 》 《 四遊記 》 《 東遊記 》 《 南遊記 》 《 北遊記 》 电视剧 《 西游记 》（1982） 《 西遊記 》（1996） 《 西遊記（貳） 》（1998） 《 西游记后传 》（2000） 《 齊天大聖孫悟空 》（2002） 《 西游记 》（2006） 《 西游记 》（2010） 《 西游记 》（2011） 《 新美猴王传奇 （ 英语 ： The New Legends of Monkey ） 》（2018） 电影 《 大闹天宫 》（1961） 《 西行平妖 》（1991） 《 西遊記第壹佰零壹回之月光寶盒 》（1995） 《 西遊記大結局之仙履奇緣 》（1995） 《 西游记：失落的帝国 》（2001） 《 西遊記之大鬧天宮 》（2014） 《 西游记之孙悟空三打白骨精 》（2016） 《 西游记·女儿国 》（2018） 游戏 《 中華大仙 （ 日语 ： 中華大仙 ） 》（1988） 《 西游释厄传 》（1997） 《 西遊記 (日本光荣株式会社游戏) （ 日语 ： 西遊記 (ゲーム) ） 》（1999） 《 大话西游Online 》（2001） 《 夢幻西遊 》（2003） 《 西游记之大圣归来 》（2019） 《 黑神话：悟空 》（2024） 改編作品和事物 西遊記的衍生作品列表 淮安西游乐园 东方神曲 唐僧喇嘛传 相关 {{ 中国神话 }} · {{ 佛教主题 }} · {{ 中國文學名著 }}
--------------------------------------------------------------------------------

……

Markdown文档的解析—UnstructuredMarkdownLoader

  • 解析模式：使用mode=”elements”参数解析文档结构
  • 关键metadata：
    • category_depth：标题层级深度
    • parent_id：父元素标识
    • element_id：当前元素唯一标识
  • 重要性：保持标题与内容的关联关系，确保检索结果不丢失上下文

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from langchain_community.document_loaders import UnstructuredMarkdownLoader
from langchain_core.documents import Document

markdown_path = "../data/黑悟空/黑悟空版本介绍.md"
loader = UnstructuredMarkdownLoader(markdown_path)

data = loader.load()
print(data[0].page_content[:250])

loader = UnstructuredMarkdownLoader(markdown_path, mode="elements")
data = loader.load()
print(f"Number of documents: {len(data)}\n")
for document in data:
    print(f"{document}\n")

执行结果，输出内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
黑神话：悟空 🐵

黑神话：悟空 是由中国游戏开发团队制作的一款备受瞩目的动作冒险游戏，以《西游记》为背景，重新演绎了经典故事，带来了极具冲击力的视觉和游戏体验。

游戏版本介绍

1. 数字标准版 💻

包含基础游戏

2. 数字豪华版 🎶

包括基础游戏

额外的游戏内内容和精选数字原声音乐

兵器“铜云棒” 🏹

披挂“百戏傩面、百戏衬钱衣、百戏护手、百戏吊腿” 🛡️

珍玩“风铎” 🎐

3. 实体豪华版 📦

包含数字豪华版的启动码和一系列实体收藏品
...
page_content='文化再现：重现了中国传统文化中的神话和传奇故事。' metadata={'source': '../data/黑悟空/黑悟空版本介绍.md', 'category_depth': 1, 'emphasized_text_contents': ['文化再现'], 'emphasized_text_tags': ['b'], 'languages': ['zho'], 'file_directory': '../data/黑悟空', 'filename': '黑悟空版本介绍.md', 'filetype': 'text/markdown', 'last_modified': '2025-07-16T19:30:42', 'parent_id': 'd7374cb94107a8ff0101f1776a058022', 'category': 'ListItem', 'element_id': '222a4b25bb6bd3e6d7f9d695ec706876'}

page_content='提示：关注游戏的官方网站和社交媒体，获取最新的开发进度和发布信息。 📅' metadata={'source': '../data/黑悟空/黑悟空版本介绍.md', 'emphasized_text_contents': ['提示'], 'emphasized_text_tags': ['b'], 'languages': ['zho'], 'file_directory': '../data/黑悟空', 'filename': '黑悟空版本介绍.md', 'filetype': 'text/markdown', 'last_modified': '2025-07-16T19:30:42', 'parent_id': 'd7374cb94107a8ff0101f1776a058022', 'category': 'UncategorizedText', 'element_id': '8832006fc109f9b62a5a03e2d7b71b10'}

……