Magpie 是一款用于多标签文本分类的深度学习工具。它通过训练语料库学习，能够为任意文本分配标签，并可用于对未知数据进行标签预测。该工具由欧洲核子研究中心（CERN）开发，主要用于为高能物理摘要分配主题类别并从中提取关键词。

极简介绍

>>> magpie = Magpie()
>>> magpie.init_word_vectors('/path/to/corpus', vec_dim=100)
>>> magpie.train('/path/to/corpus', ['label1', 'label2', 'label3'], epochs=3)
训练中...
>>> magpie.predict_from_text('嗯，这速度真快！')
[('label1', 0.96), ('label3', 0.65), ('label2', 0.21)]

简介

要训练模型，您需要一个采用 UTF-8 编码的文本格式标注数据语料库。示例语料库可在 data/hep-categories 目录下找到。Magpie 会查找包含待预测文本的 .txt 文件以及对应、每行一个标签的 .lab 文件。标签文件和文本文件应具有相同的文件名，仅扩展名不同，例如：

$ ls data/hep-categories
1000222.lab 1000222.txt 1000362.lab 1000362.txt 1001810.lab 1001810.txt ...

在训练模型之前，您需要为语料库构建合适的词向量表示。理论上，您可以使用其他语料库来训练词向量，或复用已训练好的词向量（教程），不过 Magpie 也支持直接完成这一过程。

from magpie import Magpie

magpie = Magpie()
magpie.train_word2vec('data/hep-categories', vec_dim=100)

接下来，您需要拟合一个缩放矩阵以归一化输入数据，该矩阵与所训练的 Word2Vec 表示密切相关。只需一行代码即可完成：

magpie.fit_scaler('data/hep-categories')

通常，您可以将这两个步骤合并执行，只需运行：

magpie.init_word_vectors('data/hep-categories', vec_dim=100)

如果您计划复用已训练好的词向量表示，可以将其保存下来，并在下次实例化 Magpie 时传入构造函数。然后，只需输入以下内容即可开始训练：

labels = ['引力与宇宙学', '实验-高能物理', '理论-高能物理']
magpie.train('data/hep-categories', labels, test_ratio=0.2, epochs=30)

通过提供 test_ratio 参数，模型会将数据划分为训练集和测试集（本例中为 80/20 的比例），并在每个 epoch 结束后评估自身表现，显示当前的损失值和准确率。test_ratio 的默认值为 0，表示所有数据都将用于训练。

如果您的数据无法完全加载到内存中，也可以使用 magpie.batch_train() 方法，其 API 类似，但更节省内存。

训练好的模型可以通过以下方法进行预测：

>>> magpie.predict_from_file('data/hep-categories/1002413.txt')
[('实验-高能物理', 0.47593361),
 ('引力与宇宙学', 0.055745006),
 ('理论-高能物理', 0.02692855)]

>>> magpie.predict_from_text('史蒂芬·霍金研究黑洞')
[('引力与宇宙学', 0.96627593),
 ('实验-高能物理', 0.64958507),
 ('理论-高能物理', 0.20917746)]

模型的保存与加载

Magpie 对象由三个部分组成：Word2Vec 映射、缩放器和 Keras 模型。为了训练 Magpie，您可以提前提供 Word2Vec 映射和缩放器，也可以让程序根据训练数据自行计算。通常，建议您在完整数据集上独立训练这些组件，并在后续使用中重复利用它们。为此，您可以使用提供的函数：

magpie.save_word2vec_model('/save/my/embeddings/here')
magpie.save_scaler('/save/my/scaler/here', overwrite=True)
magpie.save_model('/save/my/model/here.h5')

当您希望重新初始化已训练好的模型时，可以运行：

magpie = Magpie(
    keras_model='/save/my/model/here.h5',
    word2vec_model='/save/my/embeddings/here',
    scaler='/save/my/scaler/here',
    labels=['猫', '狗', '牛']
)

或者直接传入这些对象！

安装

该软件包尚未发布到 PyPI，但您可以直接从 GitHub 获取：

$ pip install git+https://github.com/inspirehep/magpie.git@v2.1.1

如果在安装过程中遇到任何问题，请确保安装 setup.py 文件中列出的正确版本依赖项。

免责声明与引用

Magpie 中使用的神经网络模型基于 Yoon Kim 的工作，随后又受到 Mark Berger 的影响。

联系方式

如果您有任何问题，欢迎随时提交 issue。我们将竭诚为您提供帮助 :+1:

Magpie 快速上手指南

Magpie 是一款用于多标签文本分类的深度学习工具，由 CERN 开发，主要用于高能物理摘要的主题分类和关键词提取。它基于训练语料学习标签分配，并可对未知文本进行预测。

环境准备

• 系统要求：支持 Python 3 的操作系统（Linux/macOS/Windows）
• 前置依赖：
  • Python 3.x
  • pip 包管理工具
  • 确保已安装 git（用于从 GitHub 安装）
  • 依赖库将在安装时自动解决（包括 keras, gensim, scikit-learn 等，具体版本参考项目 setup.py）

💡 提示：若在国内网络环境下安装较慢，可配置 pip 使用国内镜像源（如清华、阿里云等），例如：

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

安装步骤

由于 Magpie 未发布到 PyPI，需直接从 GitHub 安装指定版本：

pip install git+https://github.com/inspirehep/magpie.git@v2.1.1

如遇安装问题，请检查 setup.py 中列出的依赖版本是否冲突，并手动安装兼容版本。

基本使用

1. 初始化与训练

准备标注数据：每个文本文件（.txt）需对应一个标签文件（.lab），文件名相同仅扩展名不同。例如：

1000222.txt  1000222.lab
1000362.txt  1000362.lab

from magpie import Magpie

# 初始化模型
magpie = Magpie()

# 构建词向量并拟合缩放矩阵（一步完成）
magpie.init_word_vectors('data/hep-categories', vec_dim=100)

# 定义标签列表并开始训练
labels = ['Gravitation and Cosmology', 'Experiment-HEP', 'Theory-HEP']
magpie.train('data/hep-categories', labels, test_ratio=0.2, epochs=30)

test_ratio=0.2 表示将 20% 数据用于验证，其余用于训练；设为 0 则全量训练。

2. 文本预测

训练完成后，可直接对文件或字符串进行预测：

# 从文件预测
results = magpie.predict_from_file('data/hep-categories/1002413.txt')
print(results)
# 输出示例：[('Experiment-HEP', 0.4759), ('Gravitation and Cosmology', 0.0557), ...]

# 从文本字符串预测
results = magpie.predict_from_text('Stephen Hawking studies black holes')
print(results)
# 输出示例：[('Gravitation and Cosmology', 0.9663), ('Experiment-HEP', 0.6496), ...]

3. 模型保存与加载（可选）

训练后可持久化模型组件以便复用：

magpie.save_word2vec_model('/path/to/embeddings')
magpie.save_scaler('/path/to/scaler', overwrite=True)
magpie.save_model('/path/to/model.h5')

重新加载时：

magpie = Magpie(
    keras_model='/path/to/model.h5',
    word2vec_model='/path/to/embeddings',
    scaler='/path/to/scaler',
    labels=['Gravitation and Cosmology', 'Experiment-HEP', 'Theory-HEP']
)

---

现在你已成功使用 Magpie 完成多标签文本分类任务的端到端流程！