Magnitude：一款快速、简单的向量嵌入工具库

      
              

由 Plasticity 开发的多功能 Python 软件包及向量存储文件格式，旨在以快速、高效且简便的方式在机器学习模型中使用向量嵌入。它主要作为 Gensim 的更简单、更快替代方案而设计，但也可用作自然语言处理以外领域的通用键-向量存储。该库提供诸如 未登录词查询 和 通过 HTTP 流式传输大型模型 等独特功能。相关研究成果已发表于 EMNLP 2018，并可在 arXiv 上查阅。

目录

• 安装
• 动机
• 基准测试与特性
• 热门嵌入模型的预转换 Magnitude 格式
• 使用该库
  • 构造 Magnitude 对象
  • 查询
  • 基础未登录词处理
  • 高级未登录词处理
    • 拼写错误与打字错误的处理
  • 多个模型的拼接
  • 附加特征提取（词性等）
  • 将 Magnitude 与机器学习库结合使用
    • Keras
    • PyTorch
    • TFLearn
  • 实用工具
• 并发与并行处理
• 文件格式与转换器
• 远程加载
• 通过 HTTP 远程流式传输
• 其他文档
• 其他语言
• 其他编程语言
• 其他领域
• 贡献
• 路线图
• 其他值得关注的项目
• 引用本仓库
• 许可与署名

安装

您可以通过 pip 安装本软件包：

pip install pymagnitude # Python 2.7
pip3 install pymagnitude # Python 3

由于依赖冲突，Google Colaboratory 在安装 Magnitude 时可能会遇到一些问题。您可以在 Google Colab 中使用以下代码片段来安装 Magnitude：

# 在 Google Colab 上安装 Magnitude
! echo "正在安装 Magnitude.... (请稍候，可能需要一段时间)"
! (curl https://raw.githubusercontent.com/plasticityai/magnitude/master/install-colab.sh | /bin/bash 1>/dev/null 2>/dev/null)
! echo "Magnitude 安装完成。"

动机

向量空间嵌入模型在机器学习中日益普及，传统上主要用于自然语言处理任务。然而，目前仍缺乏一种快速轻量级的工具来高效地使用这些庞大的向量空间嵌入模型。

Magnitude 向量嵌入文件格式（.magnitude）旨在成为一种更高效的通用向量嵌入格式，支持延迟加载以加快开发环境中的冷启动速度，采用 LRU 内存缓存机制以提升生产环境下的性能，支持多键查询、直接为神经网络输入添加特征、高效进行相似度计算，并具备处理未登录词或拼写错误等边缘情况以及合并多个向量模型等功能。此外，该格式还适用于无法完全加载到内存中的大型向量模型。

Magnitude 使用 SQLite，一种快速且流行的嵌入式数据库，作为其底层数据存储。它利用索引实现快速键值查找，并通过内存映射、SIMD 指令和空间索引技术，在磁盘外的向量空间中实现高效的相似度搜索，同时保持良好的内存性能，即使在多个进程之间也能维持高效运行。更重要的是，内存映射会在不同运行之间被缓存，因此即使关闭进程后，性能优势仍然得以保留。

基准测试与特性

指标	轻量级	中量级	重量级	流式传输
首次加载时间	0.7210秒	━ 1	━ 1	7.7550秒
冷启动单键查询	0.0001秒	━ 1	━ 1	1.6437秒
温启动单键查询 (与冷启动查询相同的键)	0.00004秒	━ 1	━ 1	0.0004秒
冷启动多键查询 (n=25)	0.0442秒	━ 1	━ 1	1.7753秒
温启动多键查询 (n=25, 键与冷启动查询相同)	0.00004秒	━ 1	━ 1	0.0001秒
第一次 most_similar 搜索查询 (n=10, 最坏情况)	247.05秒	━ 1	━ 1	-
第一次 most_similar 搜索查询 (n=10, 平均情况, 使用磁盘持久化缓存)	1.8217秒	━ 1	━ 1	-
后续 most_similar 搜索 (n=10, 键与第一次查询不同)	0.2434秒	━ 1	━ 1	-
温启动后续 most_similar 搜索 (n=10, 键与第一次查询相同)	0.00004秒	0.00004秒	0.00004秒	-
第一次 most_similar_approx 搜索查询 (n=10, effort=1.0, 最坏情况)	不适用	不适用	29.610秒	-
第一次 most_similar_approx 搜索查询 (n=10, effort=1.0, 平均情况, 使用磁盘持久化缓存)	不适用	不适用	0.9155秒	-
后续 most_similar_approx 搜索 (n=10, effort=1.0, 键与第一次查询不同)	不适用	不适用	0.1873秒	-
后续 most_similar_approx 搜索 (n=10, effort=0.1, 键与第一次查询不同)	不适用	不适用	0.0199秒	-
温启动后续 most_similar_approx 搜索 (n=10, effort=1.0, 键与第一次查询相同)	不适用	不适用	0.00004秒	-
文件大小	4.21GB	5.29GB	10.74GB	0.00GB
进程内存（RAM）占用	18KB	━ 1	━ 1	1.71MB
执行100次键查询后的进程内存（RAM）占用	168KB	━ 1	━ 1	1.91MB
执行100次键查询及相似度搜索后的进程内存（RAM）占用	342KB2	━ 1	━ 1
完整性检查和测试	✅	✅	✅	✅
支持 word2vec（.txt、.bin）、GloVe（.txt）、fastText（.vec）和 ELMo（.hdf5）之间的通用格式，并配备转换工具	✅	✅	✅	✅
简洁的 Python 式接口	✅	✅	✅	✅
依赖项较少	✅	✅	✅	✅
支持超出内存容量的模型	✅	✅	✅	✅
尽可能采用懒加载以提升速度和性能	✅	✅	✅	✅
针对 threading 和 multiprocessing 进行优化	✅	✅	✅	✅
支持批量和多键查找，包括填充、截断、占位符和特征化功能	✅	✅	✅	✅
可将多个向量模型拼接在一起	✅	✅	✅	✅
基本的未登录词键查找 (字符 n-gram 特征哈希)	✅	✅	✅	✅
高级的未登录词键查找，支持拼写错误 (字符 n-gram 特征哈希映射到相似的已登录词键)	❌	✅	✅	✅
使用 annoy 索引进行近似最相似搜索	❌	❌	✅	✅
内置新模型训练功能	❌	❌	❌	❌

^{1: 与前一列相同
2: 使用 mmap 从磁盘读取，因此在内存可用时操作系统仍会分配内存页，但这些内存页可以在进程间共享，并且对于超大文件来说无需在每个进程中单独管理，从而带来性能优势
*: 所有基准测试均在 Google News 预训练词向量 (GoogleNews-vectors-negative300.bin) 上进行，使用的设备为 MacBook Pro (Retina, 15 英寸，2014 年中旬款)，配备 2.2GHz 四核 Intel Core i7 处理器和 16GB RAM，存储介质为 SSD，在可行的情况下取多次试验的平均值。}

流行嵌入模型的预转换 Magnitude 格式

流行的嵌入模型已被预先转换为 .magnitude 格式，可供立即下载和使用：

贡献者	数据	轻量级 (对未登录词的基本支持)	中量级 (推荐) (对未登录词的高级支持)	重量级 (对未登录词的高级支持以及更快的 most_similar_approx)
Google - word2vec	Google News 100B	300D	300D	300D
Stanford - GloVe	Wikipedia 2014 + Gigaword 5 6B	50D, 100D, 200D, 300D	50D, 100D, 200D, 300D	50D, 100D, 200D, 300D
Stanford - GloVe	Wikipedia 2014 + Gigaword 5 6B (经Plasticity词形还原)	50D, 100D, 200D, 300D	50D, 100D, 200D, 300D	50D, 100D, 200D, 300D
Stanford - GloVe	Common Crawl 840B	300D	300D	300D
Stanford - GloVe	Twitter 27B	25D, 50D, 100D, 200D	25D, 50D, 100D, 200D	25D, 50D, [100D](http://magnitude.plasticity.ai/glove/heavy/glove.twitter.27B.100d.dema…

以下是将任何 .bin、.txt、.vec 或 .hdf5 文件转换为 .magnitude 文件的说明 如下。

使用该库

构建 Magnitude 对象

您可以按以下方式创建一个 Magnitude 对象：

from pymagnitude import *
vectors = Magnitude("/path/to/vectors.magnitude")

如果需要，为了方便起见，您也可以直接使用 Magnitude 打开 .bin、.txt、.vec 或 .hdf5 文件。不过，这种方法效率较低，对于大型模型来说速度非常慢，因为它会在首次运行时将文件转换为临时目录中的 .magnitude 文件。临时目录不一定会保留，并且在计算机重启后也不会保留。通常，为了提高速度，您应该先使用 python -m pymagnitude.converter 将 .bin、.txt、.vec 或 .hdf5 文件预先转换为 .magnitude 格式，但此功能对于一次性使用场景仍然很有用。当直接使用 .bin、.txt、.vec 或 .hdf5 文件实例化 Magnitude 对象时，会生成警告信息。您可以通过将构造函数中的 supress_warnings 参数设置为 True 来抑制这些警告。

---

• ^{默认情况下，惰性加载已启用。您可以向构造函数传递一个可选的 lazy_loading 参数，其值可以是 -1（禁用惰性加载并预加载所有向量到内存中，类似于 Gensim）、0（默认值，启用无限制的内存 LRU 缓存的惰性加载），或大于零的整数 X（启用惰性加载，并使用一个仅保留最近使用过的 X 个向量的 LRU 缓存）。}
• ^{如果您希望在初始化时就提前加载 most_similar 函数所需的数据，请将 eager 参数设置为 True。}
• ^{请注意，即使将 lazy_loading 设置为 -1 或将 eager 设置为 True，数据仍会在后台线程中预加载到内存中，以避免构造函数因大型模型而阻塞几分钟。如果您确实希望阻塞式行为，可以将 blocking 参数设置为 True。}
• ^{默认情况下，返回的是单位长度归一化向量，除非您正在加载 ELMo 模型。如果您希望接收原始的未归一化向量，请将可选参数 normalized 设置为 False。}
• ^{默认情况下，查询结果以 NumPy 数组形式返回。如果您希望接收 Python 列表而不是 NumPy 数组，可以将可选参数 use_numpy 设置为 False。}
• ^{默认情况下，键的查询区分大小写。如果您希望进行不区分大小写的搜索，请将可选参数 case_insensitive 设置为 True。}
• ^{您可以选择包含 pad_to_length 参数，该参数用于指定在传入多个示例时，所有示例应被填充到的长度。超过填充长度的示例将会被截断。}
• ^{如果指定了 pad_to_length，并且某个示例的长度超过了该值，您可以将 truncate_left 参数设置为 True，以截断每个示例中键列表的开头部分，而不是结尾部分。}
• ^{您可以选择将 pad_left 参数设置为 True，使填充出现在列表的开头而不是默认的结尾。}
• ^{您可以选择传递 placeholders 参数，该参数会将每个向量的维度增加 placeholders 的数量，并用零填充这些额外的维度。如果您计划向向量中添加其他值和信息，并希望预先为这些内容分配空间以提高效率，此选项将非常有用。}
• ^{您可以选择传递 language 参数，并提供一个 ISO 639-1 语言代码。如果您将 Magnitude 用于词向量，则此参数可确保库尊重该语言的词干提取和其他特定于语言的功能。默认值为 en，表示英语。如果您不将 Magnitude 用于词向量，也可以将此参数设置为 None。}
• ^{您可以选择传递 dtype 参数，以控制 Magnitude 返回的 NumPy 数组的数据类型。}
• ^{您可以选择传递 devices 参数，以控制底层模型支持 GPU 使用时的 GPU 设备使用情况。该参数应为一个整数列表，其中每个整数代表 GPU 设备编号（0、1 等）。}
• ^{您可以选择传递 temp_dir 参数，以控制 Magnitude 将使用的临时目录的位置。}
• ^{您可以选择传递 log 参数，使 Magnitude 在执行耗时操作时将进度记录到标准错误流中。}

查询

你可以这样查询文件中向量的总数：

len(vectors)

---

你可以这样查询向量的维度：

vectors.dim

---

你可以这样检查某个键是否在词汇表中：

"cat" in vectors

---

你可以这样遍历所有的键和向量：

for key, vector in vectors:
  ...

---

你可以这样查询某个键对应的向量：

vectors.query("cat")

---

你可以通过索引获取第 n 个键和向量：

vectors[42]

---

你可以这样查询多个键的向量：

vectors.query(["I", "read", "a", "book"])

将返回一个二维数组（键对应向量）。

---

你可以这样查询多个例句的向量：

vectors.query([["I", "read", "a", "book"], ["I", "read", "a", "magazine"]])

将返回一个三维数组（例句 × 键 × 向量）。如果未指定 pad_to_length，且每个例句的长度不一致，则会按最长例句的长度进行填充。

---

你可以通过索引获取多个位置的键和向量：

vectors[:42] # 切片表示法
vectors[42, 1337, 2001] # 元组表示法

---

你可以这样查询两个或多个键之间的距离：

vectors.distance("cat", "dog")
vectors.distance("cat", ["dog", "tiger"])

---

你可以这样查询两个或多个键之间的相似度：

vectors.similarity("cat", "dog")
vectors.similarity("cat", ["dog", "tiger"])

---

你可以这样查询给定键与一组键中最相似的键：

vectors.most_similar_to_given("cat", ["dog", "television", "laptop"]) # dog

---

你可以这样查询给定键与一组键中不匹配的键：

vectors.doesnt_match(["breakfast", "cereal", "dinner", "lunch"]) # cereal

---

你可以这样查询最相似的键（近邻）：

vectors.most_similar("cat", topn = 100) # 按键最相似
vectors.most_similar(vectors.query("cat"), topn = 100) # 按向量最相似

你还可以选择性地为 most_similar 传递一个 min_similarity 参数，其值范围为 [-1.0, 1.0]。

---

你也可以通过提供正例和负例来查询最相似的键（这实际上可以解决类比问题）：

vectors.most_similar(positive = ["woman", "king"], negative = ["man"]) # queen

---

类似于 vectors.most_similar，还有一个 vectors.most_similar_cosmul 函数，它使用 Levy and Goldberg 提出的 3CosMul 方法：

vectors.most_similar_cosmul(positive = ["woman", "king"], negative = ["man"]) # queen

---

你还可以使用近似最近邻索引快速查询最相似的键，虽然速度更快，但不能保证完全准确的结果：

vectors.most_similar_approx("cat")
vectors.most_similar_approx(positive = ["woman", "king"], negative = ["man"])

你还可以选择性地为 most_similar_approx 函数传递一个 effort 参数，其值范围为 [0.0, 1.0]，以调整运行时间和准确性。默认值为 1.0，此时耗时最长，但结果最准确。

---

你可以这样查询所有与某个键的距离比另一个键更近的键：

vectors.closer_than("cat", "rabbit") # ["dog", ...]

---

你可以访问模型中所有的底层向量，它们存储在一个大小为 (len(vectors) x vectors.emb_dim) 的大型 numpy.memmap 数组中：

vectors.get_vectors_mmap()

---

你可以清理所有相关资源、打开的文件和数据库连接：

vectors.close()

基本的未登录词处理

对于词向量表示而言，处理未登录词非常重要，这有助于应对训练数据中未出现的新词、拼写错误和打字错误，并总体上提高基于词向量表示模型的鲁棒性。

未登录词的处理方式是为其分配一个随机向量值。然而，这种随机性是确定性的：如果两次遇到 相同 的未登录词，它会被赋予相同的随机向量值，以便能够对这些未登录词进行训练。此外，如果两个未登录词具有相似的字符 n-gram（例如“uberx”和“uberxl”），即使它们都不在词汇表中，也会被放置在彼此附近：

vectors = Magnitude("/path/to/GoogleNews-vectors-negative300.magnitude")
"uberx" in vectors # False
"uberxl" in vectors # False
vectors.query("uberx") # array([ 5.07109939e-02, -7.08248823e-02, -2.74812328e-02, ... ])
vectors.query("uberxl") # array([ 0.04734962, -0.08237578, -0.0333479, -0.00229564, ... ])
vectors.similarity("uberx", "uberxl") # 0.955000000200815

高级的未登录词处理

如果使用支持高级未登录词处理的 Magnitude 文件（Medium 或 Heavy 版本），未登录词还会被嵌入到与其相似的已登录词附近，这些相似性是根据字符串相似度判断的：

vectors = Magnitude("/path/to/GoogleNews-vectors-negative300.magnitude")
"uberx" in vectors # False
"uberification" in vectors # False
"uber" in vectors # True
vectors.similarity("uberx", "uber") # 0.7383483267618451
vectors.similarity("uberification", "uber") # 0.745452837882727

处理拼写错误和打字错误

这也使得 Magnitude 对许多拼写错误具有较强的鲁棒性：

vectors = Magnitude("/path/to/GoogleNews-vectors-negative300.magnitude")
"missispi" in vectors # False
vectors.similarity("missispi", "mississippi") # 0.35961736624824003
"discrimnatory" in vectors # False
vectors.similarity("discrimnatory", "discriminatory") # 0.8309152561753461
"hiiiiiiiiii" in vectors # False
vectors.similarity("hiiiiiiiiii", "hi") # 0.7069775034853861

为了实现未登录词的这一效果，使用了字符 n-gram 技术。该功能的灵感来源于 Facebook AI Research 的论文 Enriching Word Vectors with Subword Information，但与原文不同的是，这里并非在训练时利用字符 n-gram，而是在推理时使用字符 n-gram，从而在一些较旧的模型（如 word2vec 和 GloVe）中部分地复现了这一效果（尽管无法完全复制）。

多模型的拼接

可选地，你可以将多个模型的向量组合起来，以便向机器学习模型提供更丰富的信息，如下所示：

from pymagnitude import *
word2vec = Magnitude("/path/to/GoogleNews-vectors-negative300.magnitude")
glove = Magnitude("/path/to/glove.6B.50d.magnitude")
vectors = Magnitude(word2vec, glove) # 将 word2vec 与 glove 的向量拼接在一起
vectors.query("cat") # 返回一个 350 维的 NumPy 数组（来自 word2vec 的“cat”与来自 glove 的“cat”拼接而成）
vectors.query(("cat", "cats")) # 返回一个 350 维的 NumPy 数组（来自 word2vec 的“cat”与来自 glove 的“cats”拼接而成）

你还可以拼接两个以上的向量模型，只需在构造函数中传入更多参数即可。

额外的特征化（词性等）

你可以使用 FeaturizerMagnitude 类，自动从你可能拥有的额外特征中创建向量，例如词性、句法依存关系或其他任何信息：

from pymagnitude import *
pos_vectors = FeaturizerMagnitude(100, namespace = "PartsOfSpeech")
pos_vectors.dim # 4 - 由 Magnitude 根据 100 这个值自动确定的维度数
pos_vectors.query("NN") # - array([ 0.08040417, -0.71705252,  0.61228951,  0.32322192]) 
pos_vectors.query("JJ") # - array([-0.11681135,  0.10259253,  0.8841201 , -0.44063763])
pos_vectors.query("NN") # - array([ 0.08040417, -0.71705252,  0.61228951,  0.32322192])（由于采用确定性哈希，对于相同的键每次都会返回相同的值）
dependency_vectors = FeaturizerMagnitude(100, namespace = "SyntaxDependencies")
dependency_vectors.dim # 4 - 由 Magnitude 根据 100 这个值自动确定的维度数
dependency_vectors.query("nsubj") # - array([-0.81043793,  0.55401352, -0.10838071,  0.15656626])
dependency_vectors.query("prep") # - array([-0.30862918, -0.44487267, -0.0054573 , -0.84071788])

Magnitude 内部会使用 特征哈希技巧，直接利用特征值的哈希来为该特征值创建唯一的向量。

FeaturizerMagnitude 的第一个参数应为该特征可能取值数量的近似上限。由于 词性标签和 句法依存关系的数量均少于 100 种，因此我们在上述示例中都选择了 100。所选值将决定 Magnitude 自动为特定的 FeaturizerMagnitude 对象分配多少维度，以降低哈希冲突的概率。namespace 参数可以是任何描述你所添加特征的字符串，它是可选的，但强烈建议使用。

随后，你可以将这些特征与标准的 Magnitude 对象拼接在一起，以供使用：

from pymagnitude import *
word2vec = Magnitude("/path/to/GoogleNews-vectors-negative300.magnitude")
pos_vectors = FeaturizerMagnitude(100, namespace = "PartsOfSpeech")
dependency_vectors = FeaturizerMagnitude(100, namespace = "SyntaxDependencies")
vectors = Magnitude(word2vec, pos_vectors, dependency_vectors) # 将 word2vec 与词性和依存关系的向量拼接在一起
vectors.query([
    ("I", "PRP", "nsubj"), 
    ("saw", "VBD", "ROOT"), 
    ("a", "DT", "det"), 
    ("cat", "NN", "dobj"), 
    (".",  ".", "punct")
  ]) # 一个大小为 5 x (300 + 4 + 4)，即 5 x 308 的数组

# 或者为以下句子中的每一个“buffalo”获取唯一的向量：
# “Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo”
# （https://en.wikipedia.org/wiki/Buffalo_buffalo_Buffalo_buffalo_buffalo_buffalo_Buffalo_buffalo）
vectors.query([
    ("Buffalo", "JJ", "amod"), 
    ("buffalo", "NNS", "nsubj"), 
    ("Buffalo", "JJ", "amod"), 
    ("buffalo", "NNS", "nsubj"), 
    ("buffalo",  "VBP", "rcmod"),
    ("buffalo",  "VB", "ROOT"),
    ("Buffalo",  "JJ", "amod"),
    ("buffalo",  "NNS", "dobj")
  ]) # 一个大小为 8 x (300 + 4 + 4)，即 8 x 308 的数组

有了这样的输出，机器学习模型现在不仅可以访问词向量信息，还可以获得词性和句法依存关系等额外信息。在这种情况下，这些额外的信息可以为神经网络提供更强的语义信号，并减少对训练数据的需求。

在机器学习库中使用 Magnitude

Magnitude 通过处理大量预处理代码，将文本数据集（或键）转换为向量，从而使得构建和迭代需要使用向量表示的模型变得非常容易。此外，它还能使这些模型对 未登录词 和 拼写错误 具有更强的鲁棒性。

下面是一些流行的机器学习库中，使用 Magnitude 构建针对 ATIS（航空公司旅行信息系统）数据集（训练集/测试集）的意图分类模型的示例代码。该数据集常用于聊天机器人或对话式界面。

Keras

你可以在这个 Google Colaboratory Python 笔记本中找到使用 Magnitude 与 Keras（支持 TensorFlow、Theano、CNTK）的指南。

PyTorch

PyTorch 指南即将推出。

TFLearn

TFlearn 指南即将推出。

工具类

您可以使用 MagnitudeUtils 类，以便便捷地访问在构建机器学习模型时可能用到的函数。

您可以按如下方式导入 MagnitudeUtils：

  from pymagnitude import MagnitudeUtils

您也可以从远程源下载 Magnitude 模型，如下所示：

  vecs = Magnitude(MagnitudeUtils.download_model('word2vec/heavy/GoogleNews-vectors-negative300'))

默认情况下，download_model 会从 http://magnitude.plasticity.ai 下载文件，并将其保存到自动创建的 ~/.magnitude 文件夹中。如果文件已下载，则不会再次下载。您可以通过可选的 download_dir 参数更改本地下载文件夹的路径。此外，还可以通过可选的 remote_path 参数更改模型的下载域名。

您还可以使用 batchify 创建 X 和 y 数据的批次生成器，如下所示：

  X = [.3, .2, .7, .8, .1]
  y = [0, 0, 1, 1, 0]
  batch_gen = MagnitudeUtils.batchify(X, y, 2)
  for X_batch, y_batch in batch_gen:
    print(X_batch, y_batch)
  # 输出：
  # 第1轮：X_batch = [.3, .2], y_batch = [0, 0]
  # 第2轮：X_batch = [.7, .8], y_batch = [1, 1]
  # 第3轮：X_batch = [.1], y_batch = [0]
  # 后续轮次：无限循环...

您还可以使用 class_encoding 将类别标签编码为整数并解码回标签，如下所示：

  add_class, class_to_int, int_to_class = MagnitudeUtils.class_encoding()
  add_class("cat") # 返回：0
  add_class("dog") # 返回：1
  add_class("cat") # 返回：0
  class_to_int("dog") # 返回：1
  class_to_int("cat") # 返回：0
  int_to_class(1) # 返回：“dog”
  int_to_class(0) # 返回：“cat”

您还可以使用 to_categorical 将带有类别整数的分类数据转换为独热编码的 NumPy 数组，如下所示：

  y = [1, 5, 2]
  MagnitudeUtils.to_categorical(y, num_classes=6) # num_classes 为可选参数
  # 输出：
  # array([[0., 1., 0., 0., 0., 0.],
  #        [0., 0., 0., 0., 0., 1.],
  #        [0., 0., 1., 0., 0., 0.]])

您还可以使用 from_categorical 将独热编码的 NumPy 数组转换回包含类别整数的 1D NumPy 数组，如下所示：

  y_c = [[0., 1., 0., 0., 0., 0.],
         [0., 0., 0., 0., 0., 1.]]
  MagnitudeUtils.from_categorical(y_c)
  # 输出：
  # array([1., 5.])

并发与并行性

该库是线程安全的（每个线程使用不同的底层存储连接），并且是只读的，永远不会向文件写入数据。由于内存占用较低，您也可以在多个进程（或使用 multiprocessing）中运行它，每个进程拥有独立的地址空间，而无需像其他库那样在内存中复制数据，也无需创建多进程共享变量，因为数据是从磁盘读取的，且每个进程维护自己的 LRU 内存缓存。对于较重的操作，例如 most_similar，会创建一个共享内存映射文件，以实现进程间内存共享。

文件格式与转换工具

Magnitude 包采用 .magnitude 文件格式，而不是其他向量模型（如 word2vec、GloVe、fastText 和 ELMo）所使用的 .bin、.txt、.vec 或 .hdf5 格式。该软件包附带了一个命令行工具，用于将 word2vec、GloVe、fastText 和 ELMo 文件转换为 Magnitude 文件。

您可以按如下方式进行转换：

python -m pymagnitude.converter -i <待转换文件路径> -o <Magnitude 文件输出路径>

输入文件的格式将根据其扩展名或内容自动确定。通常只需对某个模型执行一次转换即可。转换完成后，Magnitude 文件格式保持静态，不会被修改或写入，从而确保并发读取的安全性。

pymagnitude.converter 的可用标志如下：

• 使用 -h 标志可获取帮助并列出所有标志。
• 使用 -p <精度> 标志可以指定保留的小数位数（选择较小的数值会生成更小的文件）。实际底层值以整数形式存储，而非浮点数，因此这本质上是一种量化技术，用于减小模型的体积。
• 使用 -a 标志可以为文件添加近似最近邻索引（会增加文件大小），从而启用 most_similar_approx 函数。配合 -a 标志使用时，还可以通过 -t <树的数量> 控制近似最近邻索引中的树数量（树越多，精度越高）。若未指定树的数量，则会自动确定。
• 使用 -s 标志可以禁用向文件中添加子词信息（从而减小文件大小），但同时也会禁用对词汇表外关键词的高级支持。
• 如果要转换的模型没有词汇表（如 ELMo），可以在提供路径的同时使用 -v 标志，并指定一个您希望从中继承词汇表的 Magnitude 文件。

此外，您还可以批量转换文件，只需分别指定输入文件夹和输出文件夹，而无需逐个指定输入和输出文件。输入文件夹中的所有 .txt、.bin、.vec 和 .hdf5 文件都将被转换为输出文件夹中的 .magnitude 文件。在执行批量转换之前，输出文件夹必须已经存在。

远程加载

您可以指示 Magnitude 从其远程仓库下载并打开模型，而无需指定本地文件路径。首次运行时，文件会自动下载到 ~/.magnitude/ 目录下；后续运行时，如果本地已存在该文件，则会跳过下载步骤。

  vecs = Magnitude('http://magnitude.plasticity.ai/word2vec/heavy/GoogleNews-vectors-negative300.magnitude') # 完整 URL
  vecs = Magnitude('word2vec/heavy/GoogleNews-vectors-negative300') # 或者使用 URL 的简写形式

如需更精细地控制远程下载域名和本地下载目录，请参阅如何使用 MagnitudeUtils.download_model。

通过 HTTP 远程流式传输

Magnitude 模型通常是大型文件（多个 GB），会占用大量磁盘空间，尽管 .magnitude 格式使得向量的利用非常快速。Magnitude 提供了一个选项，可以通过 HTTP 流式传输这些大文件。 这与远程加载功能有明显区别，因为模型甚至完全不需要下载。您可以立即开始查询模型，而无需占用任何磁盘空间。

  vecs = Magnitude('http://magnitude.plasticity.ai/word2vec/heavy/GoogleNews-vectors-negative300.magnitude', stream=True) # 完整 URL
  vecs = Magnitude('word2vec/heavy/GoogleNews-vectors-negative300', stream=True) # 或者使用 URL 的简写形式

  vecs.query("king") # 返回结果：即使没有下载本地模型文件，也能快速返回“king”的向量

您可以在 Google Colaboratory Python 笔记本 中体验此演示。

如果您的计算环境资源有限（内存和磁盘空间不足），或者您希望在不下载和设置大型模型文件的情况下快速尝试向量，又或者您正在训练一个小模型，那么此功能将非常有用。 虽然由于数据是流式传输的，会增加一些网络延迟，但 Magnitude 仍会使用由 lazy_loading 构造函数参数指定的内存缓存。由于语言通常遵循 齐夫定律，在缓存被少量查询预热后，网络延迟通常不会成为问题。

它们将直接从静态 HTTP Web 服务器上通过 HTTP Range Request 头进行查询。所有 Magnitude 方法都支持流式传输，然而，most_similar 和 most_similar_approx 可能会较慢，因为它们目前尚未针对流式传输进行优化 [#路线图]。您可以在【基准测试与功能】中查看当前流式模式的性能表现，不过随着我们未来对其进行优化[#路线图]，其速度将会更快！

其他文档

目前暂无其他文档。如果您需要了解某个方法的参数详情或查看所有支持的功能，可以直接查阅源代码文件（注释较为详尽）。

其他语言

目前，本页面仅提供预先转换为 .magnitude 格式的英语词向量模型。不过，您仍然可以使用 Magnitude 来处理其他语言的词向量。Facebook 已经训练了多种语言的 fastText 向量。您可以下载所需语言的 .vec 文件，然后使用【文件格式与转换器】中的工具将其转换为 .magnitude 格式。

其他编程语言

目前，读取 Magnitude 文件仅支持 Python，因为 Python 已成为机器学习领域的事实标准语言。对于大多数应用场景来说，这已经足够。将文件格式扩展到其他语言并不困难，因为 SQLite 有原生的 C 实现，并且在大多数语言中都有绑定。此外，该文件格式以及读取和搜索协议本身也非常简单，只需阅读本仓库的源代码即可理解。

其他领域

目前，自然语言处理是使用预训练向量嵌入模型进行词向量表示的最热门领域。不过，也有一些其他领域，例如计算机视觉，开始使用类似 Deep1B 的预训练向量嵌入模型来表示图像。本库旨在保持对各个领域的中立性，提供一个适用于所有领域的通用键值存储和接口。

贡献

该项目的主要仓库位于 GitLab 上。GitHub 仓库仅为镜像。欢迎在 GitLab 上提交更多测试、改进错误检查、修复 bug、提升性能、完善文档，或添加额外工具/功能的拉取请求。

您可以通过 opensource@plasticity.ai 与我们联系。

路线图

• 对远程流式传输进行速度优化，并公开流式缓存配置选项
• 使 most_similar_approx 也针对流式传输进行优化
• 除了“轻量”、“中量”和“重量”三种规格外，新增“超重量”规格，文件体积更大，但可消除最初 most_similar 查询较慢的限制。
• 添加对 Google BERT 的支持
• 支持 fastText .bin 格式

其他知名项目

• spotify/annoy - 使用随机投影树和分层二均值算法，为 Magnitude 中的 most_similar_approx 提供近似最近邻算法的支持。感谢作者 Erik Bernhardsson 在 Magnitude 与 Annoy 集成细节方面提供的帮助。

引用本仓库

如果您想引用我们在 EMNLP 2018 上发表的论文，请使用以下 BibTeX 引用：

@inproceedings{patel2018magnitude,
  title={Magnitude: 一种快速高效的通用向量嵌入工具包},
  author={Patel, Ajay and Sands, Alexander and Callison-Burch, Chris and Apidianaki, Marianna},
  booktitle={2018 年自然语言处理经验方法会议系统演示文集},
  pages={120--126},
  year={2018}
}

或者访问 Google Scholar 链接 查看其他引用方式。

如果您想引用本仓库，可以使用以下 DOI 徽章：  

点击徽章将跳转至页面，帮助您生成正确的 BibTeX 引用、JSON-LD 引用以及其他引用格式。

许可证与署名

本仓库采用 此处 所列许可证授权。

图标“Seismic”由 JohnnyZi 来自 The Noun Project 创作。

Magnitude 快速上手指南

Magnitude 是一个高性能的向量嵌入（Vector Embedding）实用工具库和文件格式，由 Plasticity 开发。它旨在作为 Gensim 的更轻量、更快速的替代方案，支持懒加载、内存映射和高效的相似度搜索，特别适用于处理大型预训练词向量模型（如 Word2Vec, GloVe, fastText 等）。

环境准备

• 操作系统：Linux, macOS, Windows (支持多进程和内存映射)
• Python 版本：Python 2.7 或 Python 3.x
• 核心依赖：
  • sqlite3 (内置于 Python 标准库，用于底层数据存储)
  • numpy (用于数值计算)
  • scipy (用于空间索引和相似度计算)
  • pymagnitude 包会自动处理大部分依赖安装。

注意：如果在 Google Colaboratory 环境中使用，由于依赖冲突问题，建议使用官方提供的专用安装脚本（见下文安装步骤）。

安装步骤

1. 常规安装 (本地环境)

使用 pip 直接安装：

# Python 2.7
pip install pymagnitude

# Python 3
pip3 install pymagnitude

(国内用户若下载缓慢，可添加清华源加速：pip3 install pymagnitude -i https://pypi.tuna.tsinghua.edu.cn/simple)

2. Google Colab 专用安装

如果在 Google Colab 中遇到依赖问题，请运行以下命令：

# Install Magnitude on Google Colab
! echo "Installing Magnitude.... (please wait, can take a while)"
! (curl https://raw.githubusercontent.com/plasticityai/magnitude/master/install-colab.sh | /bin/bash 1>/dev/null 2>/dev/null)
! echo "Done installing Magnitude."

3. 转换模型格式 (可选)

Magnitude 需要将常见的词向量文件（.txt, .bin, .vec, .hdf5）转换为高效的 .magnitude 格式。安装完成后，可使用命令行工具进行转换：

# 示例：将 GloVe txt 文件转换为 magnitude 格式
magnitude-converter -c glove.txt -o glove.magnitude

基本使用

以下是使用 Magnitude 加载模型并查询向量的最简示例。

1. 加载模型与查询向量

假设你已经拥有一个转换好的 .magnitude 文件（例如 glove.magnitude）：

from pymagnitude import Magnitude

# 初始化对象 (支持懒加载，启动速度极快)
vectors = Magnitude("glove.magnitude")

# 查询单个词的向量
vector = vectors.query("king")
print(vector.shape)  # 输出向量维度，例如 (300,)

# 批量查询多个词
batch_vectors = vectors.query(["king", "queen", "man"])
print(batch_vectors.shape)  # 输出 (3, 300)

2. 相似度搜索

查找与给定词最相似的词：

# 查找与 'king' 最相似的 5 个词
similar_words = vectors.most_similar("king", n=5)

for word, score in similar_words:
    print(f"{word}: {score}")

3. 处理未登录词 (Out-of-Vocabulary)

Magnitude 内置了简单的子词处理机制，可以处理拼写错误或未收录的词：

# 即使 'kng' 不在词典中，也能尝试返回一个基于字符特征的向量
vector = vectors.query("kng") 

4. 与深度学习框架结合 (简要示例)

Magnitude 可以直接作为 Keras 或 PyTorch 的 Embedding 层数据源。

Keras 示例片段：

from pymagnitude.keras import MagnitudeEmbedding

# 在 Keras 模型中直接使用
embedding_layer = MagnitudeEmbedding(vectors, input_length=10, trainable=False)

PyTorch 示例片段：

from pymagnitude.pytorch import MagnitudeDataset, MagnitudeLoader

# 创建 DataLoader
dataset = MagnitudeDataset(vectors, batch_size=32)
loader = MagnitudeLoader(dataset, num_workers=4)