facebookresearch/fastText · 上手攻略

• 仓库：facebookresearch/fastText
• 链接：https://github.com/facebookresearch/fastText · 官网 https://fasttext.cc/ · 预训练向量 https://fasttext.cc/docs/en/english-vectors.html
• 分类：ai（经典词向量 + 文本分类 C++ 库）
• 作者：spark
• 更新：2026-08-17

⚠️ fastText 上游自 2020 年 v0.9.2 之后无重大功能更新；最近一次有意义动作是 2024-06 Piwheels 上的 0.9.3（仍为存量维护）。如果遇到 NumPy ≥ 2.0 编译崩，社区提供了 fasttext-numpy2 分支，下文会点名。

1. 是什么

fastText 是 Facebook AI Research 2016 年开源的 C++ 库，做两件事：

1. Word representation learning——训练带 subword（字符 n-gram）信息的词向量，对 OOV（训练时没见过的词）也能给向量；论文 Enriching Word Vectors with Subword Information。
2. Text classification——快速（单机 CPU 几亿词几分钟训完）训出多分类模型；论文 Bag of Tricks for Efficient Text Classification。

C++ 11 实现，提供 fasttext CLI 与 Python bindings（pybind11）。预训练模型覆盖 157 种语言的 Wikipedia + Common Crawl 向量，以及语言识别、监督分类模型。

它是"老派 NLP"时代的代表作：训练快、部署简单、CPU 友好。在 2025 年的当下有了更新、更强的替代品（见 §7），但作为"小数据 + 低资源 + 静态向量"的基线，仍然非常好用。

2. 解决什么问题

• 大量文本快速分类（垃圾评论、意图识别、客服标签、情感分析），没有 GPU 也想训练；
• 需要 subword 信息，让罕见词、形变词、拼写错误的词也能有合理向量；
• 需要预训练词向量当 NumPy/PyTorch 项目的 embedding 初始化；
• CPU 部署模型，模型文件几百 MB 都嫌大——quantize 后可压到几 MB。

如果你的目标是"百万级样本、CPU 训练、分钟级交付、Recall 要求不极致"——fastText 是这类需求里最稳的 C++ 工具链。

3. 快速安装

3.1 C++ CLI（推荐用预编译 release）

wget https://github.com/facebookresearch/fastText/archive/v0.9.2.zip
unzip v0.9.2.zip
cd fastText-0.9.2
make            # 产物是当前目录下 ./fasttext 二进制

要求：g++ ≥ 4.7.2 或 clang ≥ 3.3，需要支持 C++11。

3.2 CMake 安装（含 shared / static / PIC）

git clone https://github.com/facebookresearch/fastText.git
cd fastText
mkdir build && cd build
cmake ..
make && make install

3.3 Python bindings

官方 PyPI：

pip install fasttext

依赖：Python ≥ 3.4（实测要求是 3.4+，但 Piwheels 的 wheel 覆盖到 3.13）、NumPy、SciPy、pybind11。

⚠️ NumPy ≥ 2.0 时 pip install fasttext 会因 python/fasttext_module/fasttext 路径找不到而 metadata generation 失败。这是社区 2024 年起多次报告的硬问题。规避：

# 临时方案 A：锁 NumPy < 2
pip install "numpy<2" "fasttext"

# 临时方案 B：用社区补丁包
pip install fasttext-numpy2

alternatively messense/fasttext-wheel 提供预编译跨平台 wheel（包括 macOS / Windows / Linux），也可以 pip install fasttext-wheel（最新 0.9.2，截至 2026-08 仍为这个版本）。

4. 核心用法

4.1 训练词向量（skipgram）

数据格式：UTF-8 纯文本，每行一句 / 一段。

./fasttext skipgram -input data.txt -output model
# 产出 model.bin（带字典与超参的二进制）和 model.vec（纯文本，每行一个向量）

默认 subword 长度是 3-6 字符 n-grams。

OOV 词向量：

./fasttext print-word-vectors model.bin < queries.txt
# 也可以：cat queries.txt | ./fasttext print-word-vectors model.bin

4.2 训练文本分类器

数据格式：每行 __label__类别 文本内容，例如：

__label__positive this movie is great
__label__negative the plot is boring

./fasttext supervised -input train.txt -output model
./fasttext test     model.bin test.txt 1      # P@1、R@1
./fasttext predict  model.bin test.txt 1      # 单标签
./fasttext predict-prob model.bin test.txt 3  # top-3 带概率

4.3 模型压缩（quantize）

分类模型可量化成 .ftz，体积小一个数量级，性能损失有限：

./fasttext quantize -input train.txt -output model_q
./fasttext test model_q.ftz test.txt 1

Python bindings 里：

import fasttext

model = fasttext.train_supervised('data.train.txt')

def print_results(N, p, r):
    print(f"N\t{N}\nP@1\t{p:.3f}\nR@1\t{r:.3f}")

print_results(*model.test('test.txt'))
print(model.predict("Which baking dish is best to bake a banana bread?", k=3))

# 量化
model.quantize(input='data.train.txt', retrain=True)
model.save_model("model_compressed.ftz")

⚠️ 所有训练/推理文本必须 UTF-8；Python 2 用 unicode，Python 3 用 str。大写敏感：'Hello' / 'hello' / 'hello!' 被视作不同词。生产用法先做 lowercase + 标点空格化等 normalization。

4.4 预训练资源（157 语言 + 英文大表）

直接下载用：

5. 典型适用场景

• 短文本多分类（评论情感、工单标签、意图识别）几百万样本、CPU 机器跑得动、可解释（fastTextLine 的 word n-gram）；
• 轻量语言识别——fastText 的 langdetect 模型在 Hugging Face 上仍是公开基线之一；
• 冷启动 embedding——小模型 pretrained vector 直接当 PyTorch / sklearn 流水线的初始化；
• 边缘部署——.ftz 几 MB 到几十 MB，IoT、移动端、嵌入式都可以塞；
• 给 LLM/Retriever 当兜底——某些场景需要 1ms 内返回候选词向量，fastText 仍是首选 C++ 实现。

6. 坑与注意

• 大写敏感：默认全靠字符完全匹配，记得自己做 lowercase；
• 不平衡标签：多标签时给稀有类加 -minCount 限制，并考虑 -loss hs（hierarchical softmax）替代默认 softmax；
• OOV 不存在只是"向量合理"：fastText 通过 subword 拼接给 OOV 向量，但仅是字符 n-gram 平均，无语义深度；
• 多语种混合要小心：默认语料混合训练会让低资源语种被淹没，建议分语种训练；
• 量化会让 P@1 掉 0.5%-2%：-cutoff 100000、-dsoc 等调参能找回一些，但要先评估；
• NumPy ≥ 2 时 Python bindings 编译失败：见 §3.3；
• ./fasttext CLI vs Python 行为差异：CLI 的 bucket、minn、maxn 参数在 Python 里同名；-label __label__ 在 Python 里改 label_prefix；
• 2017 年后的论文与基线比较：当你在论文里用 fastText 当 baseline，记得引 Bag of Tricks 原论文；
• 数据格式严格：训练分类时换行得是 \n，不能用 \r\n —— Windows 文件要 dos2unix。

7. 与同类对比（2025-2026 视角）

第三方对比（Minish Lab 2025-07-28 的 MTEB 测试）：

⚠️ 数字来自 Minish Lab 博客（web_search 2026-08-17），单一评测，建议在自己的数据集上复测。结论倾向一致：除了 WordSim，Model2Vec 在 MTEB 大多数子任务上明显好。

结论：如果当年上线的项目还在跑 fastText，现在做"成本 / 质量"两端对比，确实可以认真评估 Model2Vec 或 sentence-transformers；但如果你只是想要"几分训练 + 几分推理 + CPU 可跑 + 几 MB 大小"的工程管线，fastText 仍是第一选择。

8. 一句话推荐

fastText 是"老派 NLP 工具链里至今仍然值得装"的 C++ 库：词向量、文本分类、CPU 部署、二进制压缩四件套对中小数据非常趁手；但 2026 年起当 embedding baseline 用，建议同时跑一遍 Model2Vec / sentence-transformers 确认收益再彻底切换。

来源

• README：https://github.com/facebookresearch/fastText（web_fetch, 2026-08-17）
• Python bindings：https://github.com/facebookresearch/fastText/blob/master/python/README.md（web_fetch, 2026-08-17）
• Piwheels / PyPI 历史版本号与日期：https://www.piwheels.org/project/fasttext （web_search, 2026-08-17）
• NumPy 2 兼容性讨论：https://groups.google.com/g/fasttext-library/c/4EOM0-S6xHU （web_search, 2026-08-17）
• modern alternatives 评测：https://minish.ai/blog/2025-07-28-fasttext（web_search, 2026-08-17）

⚠️ MTEB 对比数字仅来自 Minish Lab 单方评测，方法学与数据集未独立验证；qwen3.5:35b 等模型名在前两篇攻略中标 ⚠️；本文第三节命令在 macOS / Ubuntu LTS 上未亲身复现到 v0.9.2。