MatchZoo-py

MatchZoo 的 PyTorch 版本。

旨在促进深度文本匹配（deep text matching）模型的设计、比较与共享。
MatchZoo 是一个通用的文本匹配工具包，它旨在方便大家快速地实现、比较以及分享最新的深度文本匹配模型。

MatchZoo 的目标是为深度文本匹配研究（如文档检索、问答系统、对话响应排序和复述识别等任务）提供高质量的代码基础。借助统一的数据处理流程、简化的模型配置以及自动超参数调优等功能，MatchZoo 具有高度的灵活性和易用性。

任务（Tasks）	文本 1（Text 1）	文本 2（Text 2）	目标（Objective）
复述识别（Paraphrase Identification）	字符串 1	字符串 2	分类（classification）
文本蕴含（Textual Entailment）	文本（text）	假设（hypothesis）	分类（classification）
问答（Question Answering）	问题（question）	答案（answer）	分类/排序（classification/ranking）
对话（Conversation）	对话（dialog）	回复（response）	分类/排序（classification/ranking）
信息检索（Information Retrieval）	查询（query）	文档（document）	排序（ranking）

60 秒快速入门

要训练一个 Deep Semantic Structured Model (DSSM)，可以使用 MatchZoo 提供的自定义损失函数和评估指标来定义任务：

import torch
import matchzoo as mz

ranking_task = mz.tasks.Ranking(losses=mz.losses.RankCrossEntropyLoss(num_neg=4))
ranking_task.metrics = [
    mz.metrics.NormalizedDiscountedCumulativeGain(k=3),
    mz.metrics.MeanAveragePrecision()
]

准备输入数据：

train_pack = mz.datasets.wiki_qa.load_data('train', task=ranking_task)
valid_pack = mz.datasets.wiki_qa.load_data('dev', task=ranking_task)

仅需三行代码即可预处理输入数据，并记录需要传入模型的参数：

preprocessor = mz.models.ArcI.get_default_preprocessor()
train_processed = preprocessor.fit_transform(train_pack)
valid_processed = preprocessor.transform(valid_pack)

动态生成成对（pair-wise）训练数据：

trainset = mz.dataloader.Dataset(
    data_pack=train_processed,
    mode='pair',
    num_dup=1,
    num_neg=4,
    batch_size=32
)
validset = mz.dataloader.Dataset(
    data_pack=valid_processed,
    mode='point',
    batch_size=32
)

定义填充回调函数（padding callback）并生成数据加载器（data loader）：

padding_callback = mz.models.ArcI.get_default_padding_callback()

trainloader = mz.dataloader.DataLoader(
    dataset=trainset,
    stage='train',
    callback=padding_callback
)
validloader = mz.dataloader.DataLoader(
    dataset=validset,
    stage='dev',
    callback=padding_callback
)

初始化模型并微调超参数：

model = mz.models.ArcI()
model.params['task'] = ranking_task
model.params['embedding_output_dim'] = 100
model.params['embedding_input_dim'] = preprocessor.context['embedding_input_dim']
model.guess_and_fill_missing_params()
model.build()

使用 Trainer 控制训练流程：

optimizer = torch.optim.Adam(model.parameters())

trainer = mz.trainers.Trainer(
    model=model,
    optimizer=optimizer,
    trainloader=trainloader,
    validloader=validloader,
    epochs=10
)

trainer.run()

参考资料

教程（Tutorials）

英文文档（English Documentation）

如果您对前沿研究进展感兴趣，请查看 awesome neural models for semantic match。

安装

MatchZoo-py 依赖于 PyTorch。有两种方式安装 MatchZoo-py：

从 PyPI 安装 MatchZoo-py：

pip install matchzoo-py

从 GitHub 源码安装 MatchZoo-py：

git clone https://github.com/NTMC-Community/MatchZoo-py.git
cd MatchZoo-py
python setup.py install

模型（Models）

• DRMM：该模型实现了论文《A Deep Relevance Matching Model for Ad-hoc Retrieval》（面向即席检索的深度相关性匹配模型）。
• DRMMTKS：该模型实现了论文《A Deep Top-K Relevance Matching Model for Ad-hoc Retrieval》（面向即席检索的深度 Top-K 相关性匹配模型）。
• ARC-I：该模型实现了论文《Convolutional Neural Network Architectures for Matching Natural Language Sentences》（用于匹配自然语言句子的卷积神经网络架构）。
• ARC-II：该模型实现了论文《Convolutional Neural Network Architectures for Matching Natural Language Sentences》（用于匹配自然 language 句子的卷积神经网络架构）。
• DSSM：该模型实现了论文《Learning Deep Structured Semantic Models for Web Search using Clickthrough Data》（利用点击数据学习用于网络搜索的深度结构化语义模型）。
• CDSSM：该模型实现了论文《Learning Semantic Representations Using Convolutional Neural Networks for Web Search》（使用卷积神经网络学习用于网络搜索的语义表示）。
• MatchLSTM：该模型实现了论文《Machine Comprehension Using Match-LSTM and Answer Pointer》（使用 Match-LSTM 和答案指针的机器阅读理解）。
• DUET：该模型实现了论文《Learning to Match Using Local and Distributed Representations of Text for Web Search》（利用文本的局部和分布式表示进行网络搜索匹配学习）。
• KNRM：该模型实现了论文《End-to-End Neural Ad-hoc Ranking with Kernel Pooling》（基于核池化的端到端神经即席排序）。
• ConvKNRM：该模型实现了论文《Convolutional neural networks for soft-matching n-grams in ad-hoc search》（用于即席搜索中 n-gram 软匹配的卷积神经网络）。
• ESIM：该模型实现了论文《Enhanced LSTM for Natural Language Inference》（用于自然语言推理的增强型 LSTM）。
• BiMPM：该模型实现了论文《Bilateral Multi-Perspective Matching for Natural Language Sentences》（自然语言句子的双边多视角匹配）。
• MatchPyramid：该模型实现了论文《Text Matching as Image Recognition》（将文本匹配视为图像识别）。
• Match-SRNN：该模型实现了论文《Match-SRNN: Modeling the Recursive Matching Structure with Spatial RNN》（Match-SRNN：利用空间 RNN 建模递归匹配结构）。
• aNMM：该模型实现了论文《aNMM: Ranking Short Answer Texts with Attention-Based Neural Matching Model》（aNMM：基于注意力机制的神经匹配模型对短答案文本进行排序）。
• MV-LSTM：该模型实现了论文《A Deep Architecture for Semantic Matching with Multiple Positional Sentence Representations》（基于多重位置句子表示的语义匹配深度架构）。
• DIIN：该模型实现了论文《Natural Language Inference Over Interaction Space》（在交互空间中的自然语言推理）。
• HBMP：该模型实现了论文《Sentence Embeddings in NLI with Iterative Refinement Encoders》（在自然语言推理（NLI）中使用迭代精炼编码器的句子嵌入）。
• BERT：该模型实现了论文《BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding》（BERT：用于语言理解的深度双向 Transformer 预训练）。

引用（Citation）

如果您在研究中使用了 MatchZoo，请引用以下 BibTex 条目：

@inproceedings{Guo:2019:MLP:3331184.3331403,
 author = {Guo, Jiafeng and Fan, Yixing and Ji, Xiang and Cheng, Xueqi},
 title = {MatchZoo: A Learning, Practicing, and Developing System for Neural Text Matching},
 booktitle = {Proceedings of the 42Nd International ACM SIGIR Conference on Research and Development in Information Retrieval},
 series = {SIGIR'19},
 year = {2019},
 isbn = {978-1-4503-6172-9},
 location = {Paris, France},
 pages = {1297--1300},
 numpages = {4},
 url = {http://doi.acm.org/10.1145/3331184.3331403},
 doi = {10.1145/3331184.3331403},
 acmid = {3331403},
 publisher = {ACM},
 address = {New York, NY, USA},
 keywords = {matchzoo, neural network, text matching},
} 

开发团队

​ ​ ​ ​

​ ​ 樊毅星 ​ 核心开发者 中科院计算所 助理教授 ​	陈江贵 ​ 核心开发者 中科院计算所 博士 ​	​ 蔡银琼 核心开发者 中科院计算所 硕士 ​	​ ​ 庞亮 ​ 核心开发者 中科院计算所 助理教授 ​	​ ​ 苏立新 开发者 中科院计算所 博士 ​
​ ​ 熊瑞斌 ​ 开发者 中科院计算所 硕士 ​	​ ​ 丁宇阳 ​ 开发者 中科院计算所 硕士 ​	​ ​ 田俊峰 ​ 开发者 华东师范大学 硕士 ​	​ ​ 王清华 ​ 文档维护 山东大学 学士 ​

贡献

在提交 Pull Request 之前，请务必阅读 贡献指南。如果你有与 MatchZoo 相关的论文/项目/组件/工具，请向 这个 awesome 列表 提交 Pull Request！

感谢所有已经为 MatchZoo 做出贡献的人！

王博, 王泽毅, 杨柳, 王梓臻, 杨洲, 侯建鹏, 陈丽娟, 郑玉坤, 程牛国, 朱云岱, Aneesh Joshi, Zeno Gantner, 黄凯, stanpcf, 常庆峰, Mike Kellogg

项目组织者

• 郭嘉丰
  • 中国科学院计算技术研究所
  • 个人主页
• 兰艳艳
  • 中国科学院计算技术研究所
  • 个人主页
• 程学旗
  • 中国科学院计算技术研究所
  • 个人主页

许可证

Apache-2.0

版权所有 (c) 2019 至今，樊毅星 (faneshion)

MatchZoo-py 快速上手指南

环境准备

• 操作系统：Linux / macOS / Windows（推荐 Linux 或 macOS）
• Python 版本：3.6 或 3.7
• 核心依赖：
  • PyTorch（建议使用国内镜像加速安装）
  • 其他依赖项将随 MatchZoo-py 自动安装

💡 国内用户建议：安装 PyTorch 时可使用清华源或阿里云镜像加速，例如：

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

安装步骤

方法一：从 PyPI 安装（推荐）

pip install matchzoo-py

方法二：从 GitHub 源码安装（获取最新特性）

git clone https://github.com/NTMC-Community/MatchZoo-py.git
cd MatchZoo-py
python setup.py install

🌐 国内用户提示：若 GitHub 克隆较慢，可尝试使用代理或替换为 Gitee 镜像（如有）。

基本使用

以下示例展示如何用 MatchZoo-py 快速训练一个基于 ArcI 的排序模型（使用 WikiQA 数据集）：

import torch
import matchzoo as mz

# 1. 定义任务（排序任务 + 自定义损失与评估指标）
ranking_task = mz.tasks.Ranking(losses=mz.losses.RankCrossEntropyLoss(num_neg=4))
ranking_task.metrics = [
    mz.metrics.NormalizedDiscountedCumulativeGain(k=3),
    mz.metrics.MeanAveragePrecision()
]

# 2. 加载数据
train_pack = mz.datasets.wiki_qa.load_data('train', task=ranking_task)
valid_pack = mz.datasets.wiki_qa.load_data('dev', task=ranking_task)

# 3. 数据预处理
preprocessor = mz.models.ArcI.get_default_preprocessor()
train_processed = preprocessor.fit_transform(train_pack)
valid_processed = preprocessor.transform(valid_pack)

# 4. 构建数据集（支持 pair-wise 训练）
trainset = mz.dataloader.Dataset(
    data_pack=train_processed,
    mode='pair',
    num_dup=1,
    num_neg=4,
    batch_size=32
)
validset = mz.dataloader.Dataset(
    data_pack=valid_processed,
    mode='point',
    batch_size=32
)

# 5. 设置 padding 回调并创建 DataLoader
padding_callback = mz.models.ArcI.get_default_padding_callback()
trainloader = mz.dataloader.DataLoader(dataset=trainset, stage='train', callback=padding_callback)
validloader = mz.dataloader.DataLoader(dataset=validset, stage='dev', callback=padding_callback)

# 6. 初始化并构建模型
model = mz.models.ArcI()
model.params['task'] = ranking_task
model.params['embedding_output_dim'] = 100
model.params['embedding_input_dim'] = preprocessor.context['embedding_input_dim']
model.guess_and_fill_missing_params()
model.build()

# 7. 启动训练
optimizer = torch.optim.Adam(model.parameters())
trainer = mz.trainers.Trainer(
    model=model,
    optimizer=optimizer,
    trainloader=trainloader,
    validloader=validloader,
    epochs=10
)
trainer.run()

✅ 此示例可在约 1 分钟内完成端到端流程，适合快速验证环境与基础功能。
更多模型（如 BERT、ESIM、DSSM 等）和高级用法请参考 官方教程。