cdQA：封闭领域问答系统

一个端到端的封闭领域问答（Closed Domain Question Answering）系统。基于 HuggingFace transformers 库构建。

⛔ [不再维护] 此仓库已不再维护，但保留用于教育目的。如果您想要 cdQA 的替代维护版本，请查看：https://github.com/deepset-ai/haystack

cdQA 详解

如果您对了解系统工作原理及其实现感兴趣，我们撰写了一篇 Medium 文章，其中包含高层解释。

我们还参加了由 Feedly 组织的第 9 届 NLP Breakfast 会议并进行了演示。您可以在此处查看 此处。

目录

• 安装
  • 使用 pip
  • 从源码
  • 硬件要求
• 入门指南
  • 准备数据
    • 手动
    • 使用转换器
  • 下载预训练模型和数据
  • 训练模型
  • 进行预测
  • 评估模型
• 笔记本示例
• 部署
  • 手动
• 贡献
• 参考文献
• 许可证

安装

使用 pip

pip install cdqa

从源码

git clone https://github.com/cdqa-suite/cdQA.git
cd cdQA
pip install -e .

硬件要求

实验是在以下环境下进行的：

• CPU 👉 AWS EC2 t2.medium Deep Learning AMI (Ubuntu) Version 22.0
• GPU 👉 AWS EC2 p3.2xlarge Deep Learning AMI (Ubuntu) Version 22.0 + 单张 Tesla V100 16GB。

入门指南

准备数据

手动

要使用 cdQA，您需要创建一个包含以下列的 pandas DataFrame（pandas 数据框）：

title	paragraphs
The Article Title	[Paragraph 1 of Article, ... , Paragraph N of Article]

使用转换器

cdqa 转换器的目标是让您能够轻松地从原始文档数据库创建此 DataFrame。例如，pdf_converter 可以从包含 .pdf 文件的目录创建 cdqa DataFrame：

from cdqa.utils.converters import pdf_converter

df = pdf_converter(directory_path='path_to_pdf_folder')

您需要安装 Java OpenJDK 才能使用此转换器。我们目前拥有以下转换器：

• pdf
• markdown

我们计划在未来改进并添加更多转换器。敬请期待！

下载预训练模型和数据

您可以从 GitHub 发布页面 手动下载模型和数据，或者使用我们的下载函数：

from cdqa.utils.download import download_squad, download_model, download_bnpp_data

directory = 'path-to-directory'

# Downloading data
download_squad(dir=directory)
download_bnpp_data(dir=directory)

# Downloading pre-trained BERT fine-tuned on SQuAD 1.1
download_model('bert-squad_1.1', dir=directory)

# Downloading pre-trained DistilBERT fine-tuned on SQuAD 1.1
download_model('distilbert-squad_1.1', dir=directory)

训练模型

使用预训练的阅读器在您的语料库上拟合管道：

import pandas as pd
from ast import literal_eval
from cdqa.pipeline import QAPipeline

df = pd.read_csv('your-custom-corpus-here.csv', converters={'paragraphs': literal_eval})

cdqa_pipeline = QAPipeline(reader='bert_qa.joblib') # use 'distilbert_qa.joblib' for DistilBERT instead of BERT
cdqa_pipeline.fit_retriever(df=df)

如果您想在自定义的 SQuAD 风格标注数据集上微调阅读器：

cdqa_pipeline = QAPipeline(reader='bert_qa.joblib') # use 'distilbert_qa.joblib' for DistilBERT instead of BERT
cdqa_pipeline.fit_reader('path-to-custom-squad-like-dataset.json')

微调后保存阅读器模型：

cdqa_pipeline.dump_reader('path-to-save-bert-reader.joblib')

进行预测

获取给定输入查询的最佳预测：

cdqa_pipeline.predict(query='your question')

获取 N 个最佳预测：

cdqa_pipeline.predict(query='your question', n_predictions=N)

还可以更改检索器分数与阅读器分数的权重，以计算最终排名分数（默认值为 0.35，这在 SQuAD 1.1-open 的开发集上被证明是最佳权重）

cdqa_pipeline.predict(query='your question', retriever_score_weight=0.35)

评估模型

要在自定义数据集上评估模型，您需要对其进行标注。标注过程可分为 3 个步骤：

1. 将您的 pandas DataFrame 转换为具有 SQuAD 格式的 json 文件：

   from cdqa.utils.converters import df2squad
   
   json_data = df2squad(df=df, squad_version='v1.1', output_dir='.', filename='dataset-name')
   

2. 使用标注工具添加 ground truth（真实值）问题 - 答案对：

   请参阅我们的 cdQA-annotator，这是一个用于带有 SQuAD 格式的封闭域问答数据集的基于 Web 的 annotator（标注工具）。

3. 评估 pipeline（流水线）对象：

   from cdqa.utils.evaluation import evaluate_pipeline
   
   evaluate_pipeline(cdqa_pipeline, 'path-to-annotated-dataset.json')
   

4. 评估 reader（阅读模型）：

   from cdqa.utils.evaluation import evaluate_reader
   
   evaluate_reader(cdqa_pipeline, 'path-to-annotated-dataset.json')
   

Notebook 示例

我们在 examples 目录下准备了一些 Notebook 示例。

您也可以使用 Binder 或 Google Colaboratory 直接运行这些 Notebook 示例：

Notebook	Hardware	Platform
[1] cdQA 入门步骤	CPU 或 GPU
[2] 使用 PDF 转换器	CPU 或 GPU
[3] 在 SQuAD 上训练阅读模型	GPU

Binder 和 Google Colaboratory 提供临时环境，启动可能较慢，但如果您想轻松开始使用 cdQA，我们推荐它们。

部署

手动

您可以通过执行以下命令来部署 cdQA REST API：

export dataset_path=path-to-dataset.csv
export reader_path=path-to-reader-model

FLASK_APP=api.py flask run -h 0.0.0.0

现在您可以发送请求来测试您的 API（此处使用 HTTPie）：

http localhost:5000/api query=='your question here'

如果您希望在 cdQA 系统之上提供用户界面，请遵循 cdQA-ui 的说明，这是为 cdQA 开发的 Web 界面。

贡献

请阅读我们的 贡献指南。

参考文献

类型	标题	作者	年份
:video_camera: 视频	斯坦福 CS224N：自然语言处理 (NLP) 与深度学习 第 10 讲 – 问答系统	Christopher Manning	2019
:newspaper: 论文	阅读维基百科以回答开放域问题	Danqi Chen, Adam Fisch, Jason Weston, Antoine Bordes	2017
:newspaper: 论文	神经阅读理解与超越	Danqi Chen	2018
:newspaper: 论文	BERT：用于语言理解的深度双向 Transformer（变换器）预训练	Jacob Devlin, Ming-Wei Chang, Kenton Lee, Kristina Toutanova	2018
:newspaper: 论文	上下文词表示：一种上下文介绍	Noah A. Smith	2019
:newspaper: 论文	基于 BERTserini 的端到端开放域问答系统	Wei Yang, Yuqing Xie, Aileen Lin, Xingyu Li, Luchen Tan, Kun Xiong, Ming Li, Jimmy Lin	2019
:newspaper: 论文	开放域问答中 BERT 微调 (Fine-Tuning) 的数据增强	Wei Yang, Yuqing Xie, Luchen Tan, Kun Xiong, Ming Li, Jimmy Lin	2019
:newspaper: 论文	基于 BERT 的段落重排序 (Re-ranking)	Rodrigo Nogueira, Kyunghyun Cho	2019
:newspaper: 论文	MRQA：面向问答的机器阅读	Jonathan Berant, Percy Liang, Luke Zettlemoyer	2019
:newspaper: 论文	通过完形填空翻译进行无监督问答	Patrick Lewis, Ludovic Denoyer, Sebastian Riedel	2019
:computer: 框架	Scikit-learn：Python 中的机器学习	Pedregosa et al.	2011
:computer: 框架	PyTorch	Adam Paszke, Sam Gross, Soumith Chintala, Gregory Chanan	2016
:computer: 框架	Transformers：适用于 TensorFlow 2.0 和 PyTorch 的尖端自然语言处理库	Hugging Face	2018

许可证

Apache-2.0

cdQA 快速上手指南

⚠️ 重要提示：该项目已停止维护（Not Maintained），仅保留用于教育目的。如需生产级替代方案，建议查看 Haystack。

1. 环境准备

系统要求

• 操作系统: Linux (Ubuntu 22.0+), macOS, Windows (WSL)
• 硬件:
  • CPU: 支持标准推理 (如 AWS EC2 t2.medium)
  • GPU (推荐): 单卡 Tesla V100 16GB 或更高性能显卡以加速训练与推理
• 依赖:
  • Python 环境
  • Java OpenJDK (仅在使用 PDF 转换器时需要)

2. 安装步骤

方式一：通过 pip 安装 (推荐)

pip install cdqa

方式二：从源码安装

git clone https://github.com/cdqa-suite/cdQA.git
cd cdQA
pip install -e .

3. 基本使用

第一步：准备数据

创建包含 title 和 paragraphs 列的 Pandas DataFrame。

import pandas as pd
from ast import literal_eval

# 示例：读取 CSV 并转换 paragraphs 列为列表
df = pd.read_csv('your-custom-corpus-here.csv', converters={'paragraphs': literal_eval})

注：也可使用内置转换器将 PDF 或 Markdown 文件转换为所需格式。

第二步：下载预训练模型

需手动下载模型文件或运行以下脚本：

from cdqa.utils.download import download_model

directory = 'path-to-directory'
# 下载基于 SQuAD 1.1 微调的 BERT 模型
download_model('bert-squad_1.1', dir=directory)

第三步：初始化管道与预测

加载模型并进行问答预测。

from cdqa.pipeline import QAPipeline

# 初始化管道 (使用 distilbert_qa.joblib 可换取更快速度)
cdqa_pipeline = QAPipeline(reader='bert_qa.joblib')

# 检索器适配 (可选，视数据集大小而定)
cdqa_pipeline.fit_retriever(df=df)

# 进行预测
result = cdqa_pipeline.predict(query='你的问题')
print(result)

进阶：微调阅读模型

若拥有自定义标注数据 (SQuAD 格式)，可进一步微调 Reader：

# 在自定义数据集上微调
cdqa_pipeline.fit_reader('path-to-custom-squad-like-dataset.json')

# 保存微调后的模型
cdqa_pipeline.dump_reader('path-to-save-bert-reader.joblib')

4. 其他资源

• 在线体验: 可通过 Binder 或 Google Colab 直接运行 Notebook 示例。
• API 部署: 支持 Flask 部署 REST API，详见项目文档中的 Deployment 章节。