GuidedLDA：基于潜在狄利克雷分配的引导主题建模

.. image:: https://readthedocs.org/projects/guidedlda/badge/?version=latest :target: http://guidedlda.readthedocs.io/en/latest/?badge=latest :alt: 文档状态

.. image:: https://badge.fury.io/py/guidedlda.svg :target: https://badge.fury.io/py/guidedlda :alt: 包版本

GuidedLDA 或 SeededLDA 使用折叠吉布斯采样实现了潜在狄利克雷分配（LDA）。通过为每个主题设置一些种子词，可以引导 GuidedLDA 的主题学习方向，从而使主题向指定方向收敛。

您可以在 文档 <https://guidedlda.readthedocs.io>_ 中了解更多关于 guidedlda 的信息。

我还曾在 freecodecamp Medium 博客 <https://medium.freecodecamp.org/how-we-changed-unsupervised-lda-to-semi-supervised-guidedlda-e36a95f3a164> 上发表了一篇文章，介绍了这一方法。

安装

::

pip install guidedlda

如果使用 pip 安装失败，请尝试下一步：

::

https://github.com/vi3k6i5/GuidedLDA
cd GuidedLDA
sh build_dist.sh
python setup.py sdist
pip install -e .

如果上述步骤仍然无法成功，请在 GitHub 仓库的 Issues 页面 <https://github.com/vi3k6i5/guidedlda/issues>_ 上提交问题，并提供您的工作环境的操作系统版本、Python 版本、架构等详细信息，我会尽力尽快修复。

开始使用

guidedlda.GuidedLDA 实现了潜在狄利克雷分配（LDA）。其接口遵循 scikit-learn_ 中的惯例。

示例代码 <https://github.com/vi3k6i5/GuidedLDA/blob/master/examples/example_seeded_lda.py>_。

以下演示如何检查 NYT 新闻数据集子集的模型。下面的输入 X 是一个文档-词矩阵（支持稀疏矩阵）。

.. code-block:: python

>>> import numpy as np
>>> import guidedlda

>>> X = guidedlda.datasets.load_data(guidedlda.datasets.NYT)
>>> vocab = guidedlda.datasets.load_vocab(guidedlda.datasets.NYT)
>>> word2id = dict((v, idx) for idx, v in enumerate(vocab))

>>> X.shape
(8447, 3012)

>>> X.sum()
1221626
>>> # 无种子的普通 LDA
>>> model = guidedlda.GuidedLDA(n_topics=5, n_iter=100, random_state=7, refresh=20)
>>> model.fit(X)
INFO:guidedlda:n_documents: 8447
INFO:guidedlda:vocab_size: 3012
INFO:guidedlda:n_words: 1221626
INFO:guidedlda:n_topics: 5
INFO:guidedlda:n_iter: 100
WARNING:guidedlda:发现文档-词矩阵中存在全零列
INFO:guidedlda:<0> 对数似然值: -11489265
INFO:guidedlda:<20> 对数似然值: -9844667
INFO:guidedlda:<40> 对数似然值: -9694223
INFO:guidedlda:<60> 对数似然值: -9642506
INFO:guidedlda:<80> 对数似然值: -9617962
INFO:guidedlda:<99> 对数似然值: -9604031

>>> topic_word = model.topic_word_
>>> n_top_words = 8
>>> for i, topic_dist in enumerate(topic_word):
>>>     topic_words = np.array(vocab)[np.argsort(topic_dist)][:-(n_top_words+1):-1]
>>>     print('Topic {}: {}'.format(i, ' '.join(topic_words)))
Topic 0: company percent market business plan pay price increase
Topic 1: game play team win player season second start
Topic 2: life child write man school woman father family
Topic 3: place open small house music turn large play
Topic 4: official state government political states issue leader case

>>> # 带有种子主题的引导 LDA
>>> seed_topic_list = [['game', 'team', 'win', 'player', 'season', 'second', 'victory'],
>>>                    ['percent', 'company', 'market', 'price', 'sell', 'business', 'stock', 'share'],
>>>                    ['music', 'write', 'art', 'book', 'world', 'film'],
>>>                    ['political', 'government', 'leader', 'official', 'state', 'country', 'american','case', 'law', 'police', 'charge', 'officer', 'kill', 'arrest', 'lawyer']]

>>> model = guidedlda.GuidedLDA(n_topics=5, n_iter=100, random_state=7, refresh=20)

>>> seed_topics = {}
>>> for t_id, st in enumerate(seed_topic_list):
>>>     for word in st:
>>>         seed_topics[word2id[word]] = t_id

>>> model.fit(X, seed_topics=seed_topics, seed_confidence=0.15)
INFO:guidedlda:n_documents: 8447
INFO:guidedlda:vocab_size: 3012
INFO:guidedlda:n_words: 1221626
INFO:guidedlda:n_topics: 5
INFO:guidedlda:n_iter: 100
WARNING:guidedlda:发现文档-词矩阵中存在全零列
INFO:guidedlda:<0> 对数似然值: -11486362
INFO:guidedlda:<20> 对数似然值: -9767277
INFO:guidedlda:<40> 对数似然值: -9663718
INFO:guidedlda:<60> 对数似然值: -9624150
INFO:guidedlda:<80> 对数似然值: -9601684
INFO:guidedlda:<99> 对数似然值: -9587803


>>> n_top_words = 10
>>> topic_word = model.topic_word_
>>> for i, topic_dist in enumerate(topic_word):
>>>     topic_words = np.array(vocab)[np.argsort(topic_dist)][:-(n_top_words+1):-1]
>>>     print('Topic {}: {}'.format(i, ' '.join(topic_words)))
Topic 0: game play team win season player second point start victory
Topic 1: company percent market price business sell executive pay plan sale
Topic 2: play life man music place write turn woman old book
Topic 3: official government state political leader states issue case member country
Topic 4: school child city program problem student state study family group

文档-主题分布可以通过 doc_topic = model.transform(X) 获取。

.. code-block:: python

>>> doc_topic = model.transform(X)
>>> for i in range(9):
>>>     print("top topic: {} Document: {}".format(doc_topic[i].argmax(), 
                                                  ', '.join(np.array(vocab)[list(reversed(X[i,:].argsort()))[0:5]])))
top topic: 4 Document: plant, increase, food, increasingly, animal
top topic: 3 Document: explain, life, country, citizen, nation
top topic: 2 Document: thing, solve, problem, machine, carry
top topic: 2 Document: company, authority, opera, artistic, director
top topic: 3 Document: partner, lawyer, attorney, client, indict
top topic: 2 Document: roll, place, soon, treat, rating
top topic: 3 Document: city, drug, program, commission, report
top topic: 1 Document: company, comic, series, case, executive
top topic: 3 Document: son, scene, charge, episode, attack

可选地，可以通过清除额外矩阵来简化模型：

.. code-block:: python

>>> # 下一步将减轻模型对象的负担
>>> # 这一步会删除模型内部的一些矩阵。
>>> # 您仍然可以像之前一样使用 model.transform(X)。
>>> # 但将无法再使用 model.fit_transform(X_new)。
>>> model.purge_extra_matrices()

将模型保存以供生产或后续运行使用：

.. code-block:: python

from six.moves import cPickle as pickle >>> with open('guidedlda_model.pickle', 'wb') as file_handle: >>> pickle.dump(model, file_handle) >>> # 加载模型进行预测 >>> with open('guidedlda_model.pickle', 'rb') as file_handle: >>> model = pickle.load(file_handle) >>> doc_topic = model.transform(X)

要求

需要 Python 2.7 或 Python 3.3 及以上版本。以下软件包是必需的：

• numpy_
• pbr_

注意事项

guidedlda 的目标是引导式 LDA。通常情况下，我们从 LDA 模型中得到的主题并不令人满意。GuidedLDA 可以将主题朝我们希望的方向稍微调整。我们在生产环境中用五十万篇文档训练过该模型（我们有一台性能强大的机器）。我们也对数百万篇文档进行了预测，并手动检查了数千个主题（结果令我们满意）。

如果你处理的是非常大的语料库，可能需要使用更复杂的话题模型，例如 hca_ 和 MALLET_ 中实现的那些。hca_ 完全用 C 语言编写，而 MALLET_ 则是用 Java 编写的。与 guidedlda 不同，hca_ 可以同时利用多个处理器。MALLET_ 和 hca_ 都实现了比标准潜在狄利克雷分配更为稳健的话题模型。

注释

潜在狄利克雷分配在 Blei 等人 (2003)_ 和 Pritchard 等人 (2000)_ 中有描述。使用折叠吉布斯采样的推断方法在 Griffiths 和 Steyvers (2004)_ 中有所介绍。而引导式 LDA 则在 Jagadeesh Jagarlamudi、Hal Daume III 和 Raghavendra Udupa (2012)_ 中有说明。

重要链接

• 文档：http://guidedlda.readthedocs.org
• 源代码：https://github.com/vi3k6i5/guidedlda/
• 问题跟踪器：https://github.com/vi3k6i5/guidedlda/issues

其他实现

• scikit-learn_ 的 LatentDirichletAllocation <http://scikit-learn.org/dev/modules/generated/sklearn.decomposition.LatentDirichletAllocation.html>_（使用在线变分推断）
• gensim <https://pypi.python.org/pypi/gensim>_（使用在线变分推断）

致谢

我要感谢 LDA 项目 <https://github.com/lda-project/lda>_ 的创建者们。我以该 LDA 项目的代码为基础，在其上实现了 GuidedLDA。

特别感谢：Allen Riddell <https://twitter.com/ariddell>_ 和 Tim Hopper <https://twitter.com/tdhopper>_。:)

许可证

guidedlda 采用 Mozilla 公共许可证第 2.0 版本授权。

.. _Python: http://www.python.org/ .. _scikit-learn: http://scikit-learn.org .. _hca: http://www.mloss.org/software/view/527/ .. _MALLET: http://mallet.cs.umass.edu/ .. _numpy: http://www.numpy.org/ .. _pbr: https://pypi.python.org/pypi/pbr .. _Cython: http://cython.org .. _Blei et al. (2003): http://jmlr.org/papers/v3/blei03a.html .. _Pritchard et al. (2000): http://www.genetics.org/content/155/2/945.full .. _Griffiths and Steyvers (2004): http://www.pnas.org/content/101/suppl_1/5228.abstract .. _Jagadeesh Jagarlamudi, Hal Daume III and Raghavendra Udupa (2012): http://www.aclweb.org/anthology/E12-1021

GuidedLDA 快速上手指南

GuidedLDA（也称为 SeededLDA）是一个基于坍缩吉布斯采样（Collapsed Gibbs Sampling）实现的主题模型工具。与传统的无监督 LDA 不同，它允许用户为每个主题指定“种子词”，从而引导模型向预期的方向收敛，生成更符合业务需求的话题分类。

环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 2.7 或 Python 3.3+
• 核心依赖：
  • numpy
  • pbr

安装步骤

推荐使用 pip 进行安装。如果直接安装失败，可尝试从源码构建。

方法一：使用 pip 安装（推荐）

pip install guidedlda

提示：国内用户若下载缓慢，可使用清华或阿里镜像源加速： pip install guidedlda -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：源码安装

如果上述命令无效，请尝试从 GitHub 克隆源码并手动构建：

git clone https://github.com/vi3k6i5/GuidedLDA
cd GuidedLDA
sh build_dist.sh
python setup.py sdist
pip install -e .

基本使用

GuidedLDA 的接口设计遵循 scikit-learn 规范。以下是加载数据、训练普通 LDA 模型以及使用种子词引导训练的完整示例。

1. 导入库与加载数据

import numpy as np
import guidedlda

# 加载示例数据集 (NYT 新闻数据子集)
X = guidedlda.datasets.load_data(guidedlda.datasets.NYT)
vocab = guidedlda.datasets.load_vocab(guidedlda.datasets.NYT)

# 构建单词到 ID 的映射字典
word2id = dict((v, idx) for idx, v in enumerate(vocab))

print(f"文档数量: {X.shape[0]}, 词汇表大小: {X.shape[1]}")

2. 训练普通 LDA 模型（无引导）

首先演示不设置种子词的标准训练过程：

# 初始化模型
model = guidedlda.GuidedLDA(n_topics=5, n_iter=100, random_state=7, refresh=20)
model.fit(X)

# 查看生成的主题关键词
n_top_words = 8
topic_word = model.topic_word_
for i, topic_dist in enumerate(topic_word):
    topic_words = np.array(vocab)[np.argsort(topic_dist)][:-(n_top_words+1):-1]
    print('Topic {}: {}'.format(i, ' '.join(topic_words)))

3. 训练 GuidedLDA 模型（带种子词引导）

这是 GuidedLDA 的核心功能。通过定义 seed_topic_list，我们可以强制模型将特定词汇归类到指定主题中。

# 定义种子词列表，每个子列表代表一个期望的主题方向
seed_topic_list = [
    ['game', 'team', 'win', 'player', 'season', 'second', 'victory'],
    ['percent', 'company', 'market', 'price', 'sell', 'business', 'stock', 'share'],
    ['music', 'write', 'art', 'book', 'world', 'film'],
    ['political', 'government', 'leader', 'official', 'state', 'country', 'american','case', 'law', 'police', 'charge', 'officer', 'kill', 'arrest', 'lawyer']
]

# 重新初始化模型
model = guidedlda.GuidedLDA(n_topics=5, n_iter=100, random_state=7, refresh=20)

# 构建 seed_topics 字典：{word_id: topic_id}
seed_topics = {}
for t_id, st in enumerate(seed_topic_list):
    for word in st:
        # 确保种子词在词汇表中
        if word in word2id:
            seed_topics[word2id[word]] = t_id

# 拟合模型，传入 seed_topics 和置信度 (seed_confidence)
# seed_confidence 越高，种子词对主题形成的影响力越大
model.fit(X, seed_topics=seed_topics, seed_confidence=0.15)

# 查看引导后的主题关键词
n_top_words = 10
topic_word = model.topic_word_
for i, topic_dist in enumerate(topic_word):
    topic_words = np.array(vocab)[np.argsort(topic_dist)][:-(n_top_words+1):-1]
    print('Topic {}: {}'.format(i, ' '.join(topic_words)))

4. 预测与模型保存

训练完成后，可以使用 transform 获取文档 - 主题分布，并支持序列化保存。

# 获取文档的主题分布
doc_topic = model.transform(X)

# 打印前几个文档的主要主题及关键词
for i in range(5):
    top_topic = doc_topic[i].argmax()
    top_words = ', '.join(np.array(vocab)[list(reversed(X[i,:].argsort()))[0:5]])
    print("top topic: {} Document: {}".format(top_topic, top_words))

# (可选) 清理模型内部多余矩阵以减小体积（清理后无法再调用 fit_transform，但可正常 transform）
# model.purge_extra_matrices()

# 保存模型
from six.moves import cPickle as pickle
with open('guidedlda_model.pickle', 'wb') as file_handle:
    pickle.dump(model, file_handle)

# 加载模型
with open('guidedlda_model.pickle', 'rb') as file_handle:
    loaded_model = pickle.load(file_handle)
    
# 使用加载的模型进行预测
# new_doc_topic = loaded_model.transform(new_X)