# 异文

**Repository Path**: li-wei-blcu/text_variant

## Basic Information

- **Project Name**: 异文
- **Description**: 通过大模型-编辑距离-图神经网络-层次化社区发现来实现不同版本的继承关系挖掘
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-21
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文本变体分析系统
## 项目介绍
本项目旨在对多版本文本（如古籍不同版本）进行变体分析，通过构建文本变体图、计算文本相似度、应用图神经网络学习节点表示，进而实现文本版本的层次化比较和社区发现。

## 项目结构
├── edit_distance.py      # 编辑距离计算与字符关系分析
├── build_graph.py        # 文本变体图构建
├── vgae.py               # 变分图自编码器实现
├── plot.py               # 可视化功能
├── utils.py              # 工具函数
├── agent.py              # 字符关系分析代理
├── community_detection_manual.py   # 手动社区发现
├── community_detection_nx.py       # NetworkX社区发现
├── CleanData.xlsx        # 清洗后的数据集
└── 老子文本比对-llf.xlsx   # 原始数据示例

## 核心功能模块
1. 编辑距离计算 (edit_distance.py)
* 实现动态规划编辑距离算法，支持字符匹配、替换、删除、插入操作
* 计算编辑操作路径并生成操作序列
* 提供字符关系分析功能，通过大模型代理判断特殊字符关系并赋予自定义代价
* 实现带缓存机制的调整编辑距离计算
2. 文本变体图构建 (build_graph.py)
* 定义BookGraph类，负责构建和管理文本变体图
* 支持从DataFrame构建图结构，包含版本、章节、语句三种节点类型
* 计算句子间相似度并添加相似边，支持缓存和进度恢复
* 处理带'%'标记的乱序句子特殊情况
* 提供图信息统计和数据保存/加载功能
3. 图神经网络模型 (vgae.py)
* 实现VGCNEncoder和GCNEncoder类，定义图卷积编码器结构
* 提供WeightedGAE和WeightedVGAE类，支持带权重的图自编码器
* 自定义重构损失函数，支持边权重加权和L1正则化
* 实现模型训练功能，包含KL散度权重调度逻辑
* 提供图数据预处理和负样本生成功能
4. 可视化功能 (plot.py)
* 生成章节版本相似度热力图
* 提供多版本相似度比较图，包含热力图、条形图、网络图和聚类树状图
* 实现总体相似度热力图生成
* 支持图表安全保存和目录创建
5. 工具函数 (utils.py)
* 提取图中所有版本信息
* 获取指定章节的所有版本嵌入，缺失版本用零向量填充
* 计算嵌入间余弦相似度矩阵并映射到[0,1]范围
## 特殊情况处理
* 无法识别的字符：通过字符关系分析智能体(agent)进行处理
* 标点符号：在编辑距离计算中考虑标点符号的特殊权重
* 字符对之间构成的关系：使用大模型判断字符关系并赋予自定义代价
* 虚词：在相似度计算中考虑虚词的影响
* 乱序句子：特别处理带'%'标记的乱序句子

## 文本图详细构建流程
1. 数据准备与初始化
读取 Excel 数据文件，包含不同版本的文本
初始化 BookGraph 实例，设置图结构和版本信息
准备缓存机制，支持从已有缓存恢复
2. 节点构建过程
版本节点：为每个文本版本（如 hj、gd、ba 等）创建节点
章节节点：为每个版本的每个章节创建节点
语句节点：为每个版本的每个章节中的每个语句创建节点
包含关系：建立版本→章节→语句的层次包含关系
3. 相似度计算与边构建
遍历所有语句对，计算跨版本语句相似度
使用调整后的编辑距离算法，考虑特殊字符关系
调用大模型分析字符关系，缓存结果避免重复计算
根据相似度阈值添加相似关系边
4. 特殊情况处理
处理带 '%' 标记的乱序句子
支持缺失字符、私有字符等特殊字符的处理
实现缓存的定期保存和原子性替换

## 相似度计算流程
相似度计算主要通过三个核心函数协同完成，形成一个完整的计算链：

1. 原始编辑距离计算
该阶段计算两个字符串之间的原始编辑距离，并生成详细的操作路径。系统使用动态规划算法构建表格，初始化边界条件，填充表格并计算替换、删除、插入三种操作的最小代价。同时记录每个位置的操作类型（匹配、替换、删除、插入），最后通过回溯生成详细的操作路径。对于特殊字符#进行特殊处理，将其视为替换操作而非匹配操作。

2. 字符关系分析与代价调整
此阶段利用大模型Agent分析字符关系，为不同类型的编辑操作分配不同的代价权重。首先从原始编辑操作中提取需要分析的字符对和字符，然后构建缓存键并检查缓存中是否已存在结果。接着调用Agent分析字符关系（带重试机制，最多3次），获取分析结果，包括同音字对、同义字对、通假字对和虚词列表。将分析结果保存到缓存中后，为每个编辑操作分配相应的代价：匹配操作代价为0，替换操作根据字符关系类型分配不同代价，删除/插入操作根据字符类型分配不同代价。当Agent调用失败时，系统会返回默认代价。

3. 调整后编辑距离计算
这一阶段综合考虑各种因素，计算最终的调整编辑距离。系统首先处理特殊情况：两个字符串都为空返回0.5；只有一个为空返回较大的代价0.9；包含省略号的情况使用最长公共子序列计算相似部分，并根据相似程度调整代价（最小为0.2）；原始距离为0时直接返回0，并为所有操作分配0代价。

### 核心计算流程是：
调用原始编辑距离计算获取操作路径，根据是否有缓存调用字符关系分析获取带代价的操作，计算调整后的编辑距离（所有操作代价之和），并可选择进行长度归一化处理（除以两个字符串的最大长度）。

* 相似度表示与权重配置
* 相似度表示
* 距离值越大，表示相似度越低
* 距离值越小，表示相似度越高
* 范围通常在0-1之间（归一化后）

### 字符关系代价配置

系统支持为不同类型的字符关系设置不同的代价权重：

* 同音字：默认代价0.2，处理发音相同但字形不同的字
* 同义词：默认代价0.3，处理语义相近的字
* 通假字：默认代价0.2，处理古代文献中通用假借的字
* 虚词：默认代价0.1，处理对语义影响较小的辅助词
* 缺失字符：默认代价0.1，处理用特殊符号表示的缺失字符
* 私有字符：默认代价0.3，处理Unicode私有区字符
* 普通替换：代价1.0，处理无特殊关系的字符替换
* 匹配：代价0.0，处理完全相同的字符

### 特殊字符处理

系统专门设计了处理特殊字符的机制，包括缺失字符、私有字符和无法识别的字符。对于这些特殊字符，通过字符关系分析智能体进行处理，确保即使在处理含有罕见或无法识别字符的古代文本时，也能获得准确的相似度计算结果。

## 技术栈
* Python 3.x
* NetworkX（图数据结构）
* PyTorch（深度学习框架）
* PyTorch Geometric（图神经网络库）
* NumPy（数值计算）
* Pandas（数据处理）
* Matplotlib/Seaborn（数据可视化）

## 使用流程
* 数据准备：准备清洗后的文本数据（如CleanData.xlsx）
* 图构建：运行build_graph.py构建文本变体图
* 模型训练：运行vgae.py训练图自编码器模型
* 可视化分析：使用plot.py生成各类可视化结果
* 社区发现：通过community_detection_*.py进行文本版本的社区分析

## 注意事项
* 首次运行时会生成缓存文件，后续运行可利用缓存提高效率
* 图构建过程支持进度恢复，可在中断后从上次保存点继续
* 模型训练参数可根据需要调整，如隐藏层维度、学习率等
* 可视化功能支持自定义输出路径和图表大小
 
## 许可证
本项目采用MIT许可证，详见LICENSE文件。