DeepMatcher

.. image:: https://travis-ci.org/anhaidgroup/deepmatcher.svg?branch=master :target: https://travis-ci.org/anhaidgroup/deepmatcher

.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg :target: https://opensource.org/licenses/BSD-3-Clause

DeepMatcher 是一个用于使用深度学习进行实体匹配和文本匹配的 Python 包。 它提供了内置的神经网络和实用工具，使您能够在不到 10 行代码的情况下训练并应用最先进的深度学习模型来进行实体匹配。 这些模型也非常容易定制——模块化的设计允许对任何子组件进行修改或替换为自定义实现。

例如，给定如下带有标签的元组对：

.. image:: https://raw.githubusercontent.com/anhaidgroup/deepmatcher/master/docs/source/_static/match_input_ex.png

DeepMatcher 使用这些带标签的元组对来训练一个神经网络，以执行匹配任务，即预测匹配或不匹配的标签。然后，可以使用训练好的网络为未标记的元组对生成标签。

论文与数据

---

有关所用模型架构的详细信息，请参阅我们的论文 Deep Learning for Entity Matching（SIGMOD '18）。论文中使用的所有公开数据集都可以从 数据集页面 <Datasets.md>_ 下载。

快速入门：30 秒学会使用 DeepMatcher

---

使用 DeepMatcher 主要分为四个步骤：

1. 数据处理：加载并处理带有标签的训练、验证和测试 CSV 数据。

.. code-block:: python

import deepmatcher as dm train, validation, test = dm.data.process(path='data_directory', train='train.csv', validation='validation.csv', test='test.csv')

2. 模型定义：指定神经网络架构。默认使用内置的混合模型（如我们在 论文 <http://pages.cs.wisc.edu/~anhai/papers1/deepmatcher-sigmod18.pdf>__ 第 4.4 节中所述）。也可以根据需要进行自定义。

.. code-block:: python

model = dm.MatchingModel()

3. 模型训练：训练神经网络。

.. code-block:: python

model.run_train(train, validation, best_save_path='best_model.pth')

4. 应用：在测试集上评估模型，并将其应用于未标记的数据。

.. code-block:: python

model.run_eval(test)

unlabeled = dm.data.process_unlabeled(path='data_directory/unlabeled.csv', trained_model=model) model.run_prediction(unlabeled)

安装

---

我们目前仅支持 Python 3.5 及以上版本。推荐使用 pip 进行安装：

.. code-block::

pip install deepmatcher

教程

---

使用 DeepMatcher：

1. 入门指南_: 更深入的指南，帮助您熟悉 DeepMatcher 的基本用法。
2. 数据处理_: 高级指南，介绍数据处理的具体内容以及如何对其进行自定义。
3. 匹配模型_: 高级指南，介绍用于实体匹配的神经网络架构及其自定义方法。

实体匹配工作流：

端到端实体匹配: 一份开发完整实体匹配工作流的指南。该教程讨论了如何将 DeepMatcher 与 Magellan 结合使用，以执行阻塞、采样、标注和匹配操作，从而从两张表中获得匹配的元组对。

DeepMatcher 在其他匹配任务中的应用：

使用 DeepMatcher 进行问答: 一份关于如何使用 DeepMatcher 进行问答任务的教程。具体来说，我们将研究 WikiQA，这是一个用于答案选择任务的基准数据集。

API 参考

---

API 文档 在此_。

支持

---

请查看 常见问题解答 <FAQ.md>__ 以了解常见问题。如果您遇到任何问题或有 FAQ 中未解答的问题，请 提交 GitHub 问题_，我们会尽快处理。

团队

---

DeepMatcher 由威斯康星大学麦迪逊分校的研究生 Sidharth Mudgal 和 Han Li 在 AnHai Doan 教授和 Theodoros Rekatsinas 教授的指导下开发。

.. _Deep Learning for Entity Matching: http://pages.cs.wisc.edu/~anhai/papers1/deepmatcher-sigmod18.pdf .. _AnHai Doan 教授的数据仓库: https://sites.google.com/site/anhaidgroup/useful-stuff/data .. _Magellan: https://sites.google.com/site/anhaidgroup/projects/magellan .. _入门指南: https://nbviewer.jupyter.org/github/anhaidgroup/deepmatcher/blob/master/examples/getting_started.ipynb .. _数据处理: https://nbviewer.jupyter.org/github/anhaidgroup/deepmatcher/blob/master/examples/data_processing.ipynb .. _匹配模型: https://nbviewer.jupyter.org/github/anhaidgroup/deepmatcher/blob/master/examples/matching_models.ipynb .. _端到端实体匹配: https://nbviewer.jupyter.org/github/anhaidgroup/deepmatcher/blob/master/examples/end_to_end_em.ipynb .. _在此: https://anhaidgroup.github.io/deepmatcher/html/ .. _使用 DeepMatcher 进行问答: https://nbviewer.jupyter.org/github/anhaidgroup/deepmatcher/blob/master/examples/question_answering.ipynb .. _WikiQA: https://aclweb.org/anthology/D15-1237 .. _提交 GitHub 问题: https://github.com/anhaidgroup/deepmatcher/issues

DeepMatcher 快速上手指南

DeepMatcher 是一个基于深度学习的 Python 库，专为实体匹配（Entity Matching）和文本匹配任务设计。它内置了先进的神经网络模型，仅需少量代码即可训练出高精度的匹配模型，同时支持高度自定义的模块化架构。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.5 及以上（推荐 3.6+）
• 前置依赖：
  • PyTorch (DeepMatcher 基于 PyTorch 构建)
  • Pandas, NumPy, tqdm 等常用数据科学库（安装 DeepMatcher 时会自动处理大部分依赖）

提示：建议使用 conda 或 venv 创建独立的虚拟环境以避免依赖冲突。

安装步骤

推荐使用 pip 进行安装。国内开发者可使用清华源或阿里源加速下载。

标准安装命令：

pip install deepmatcher

使用国内镜像源加速安装（推荐）：

pip install deepmatcher -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

DeepMatcher 的核心工作流程分为四步：数据处理、模型定义、模型训练、预测应用。以下是基于官方示例的最简代码实现。

1. 数据准备

请准备好三个 CSV 文件（训练集、验证集、测试集），文件中需包含标记好的元组对（tuple pairs）及其匹配标签（match/non-match）。假设文件位于 data_directory 目录下。

2. 代码示例

import deepmatcher as dm

# 第一步：数据处理
# 加载并处理标记好的训练、验证和测试数据
train, validation, test = dm.data.process(
    path='data_directory',
    train='train.csv', 
    validation='validation.csv', 
    test='test.csv'
)

# 第二步：模型定义
# 初始化模型，默认使用混合模型（Hybrid Model），也可自定义架构
model = dm.MatchingModel()

# 第三步：模型训练
# 训练神经网络，并将最佳模型保存为 'best_model.pth'
model.run_train(train, validation, best_save_path='best_model.pth')

# 第四步：模型应用
# 在测试集上评估模型性能
model.run_eval(test)

# 对未标记的数据进行预测
# 首先处理未标记数据文件
unlabeled = dm.data.process_unlabeled(
    path='data_directory/unlabeled.csv', 
    trained_model=model
)
# 运行预测
model.run_prediction(unlabeled)

说明

• 数据格式：输入 CSV 通常包含左右两个实体的属性列以及一个标签列（训练/验证时）。
• 默认模型：dm.MatchingModel() 默认加载论文中提到的 SOTA 混合模型，适合大多数通用匹配场景。
• 扩展性：如需修改网络结构或数据处理逻辑，DeepMatcher 的模块化设计允许您轻松替换任意子组件。