FastText-fastText 文本分类

1. 方法概述

FastText-fastText 文本分类 模块的真实实现位于 core/fasttext_calculator.py。它调用的是官方 Python fasttext 包中的监督学习接口：

$$ \mathrm{fasttext.train\_supervised}(\cdot) \tag{1} $$

因此，这不是 sklearn 的词袋分类器，也不是自写的深度神经网络，而是对 Facebook fastText 监督文本分类流程的工程化封装。

设数据集为

$$ \mathcal{D}=\{(s_i,y_i)\}_{i=1}^{N} \tag{2} $$

其中 \(s_i\) 为文本，\(y_i\) 为类别标签。该模块只支持文本分类，不支持回归。

2. 数据预处理与训练文件构造

2.1 文本清洗

程序会把文本列统一转为字符串，并对每条文本执行轻量清洗：

• 换行符 \n/\r 替换为空格；
• 制表符 \t 替换为空格；
• 多余空白折叠为单个空格；
• 首尾空格删除。

记清洗后的文本为

$$ \tilde{s}_i=\mathrm{Clean}(s_i) \tag{3} $$

若清洗后文本长度为 0，则该样本会被删除。

2.2 标签格式化

fastText 监督训练要求每条样本以 __label__ 前缀开头，因此程序会把原始标签格式化为

$$ \tilde{y}_i=\texttt{\_\_label\_\_} + \psi(y_i) \tag{4} $$

其中 \(\psi(\cdot)\) 会把标签转为字符串，并把空白字符替换为下划线 _。若标签为空字符串，则会被替换成 unknown。

2.3 训练/测试划分

设测试比例为 \(r=\text{test\_size}\)。程序调用 train_test_split() 进行随机切分：

$$ \mathcal{D}_{\mathrm{train}}\cup \mathcal{D}_{\mathrm{test}}=\mathcal{D}',\qquad |\mathcal{D}_{\mathrm{test}}|\approx r|\mathcal{D}'| \tag{5} $$

若类别数量和样本分布允许，切分时会使用分层抽样；否则自动关闭分层并在参数中记录 warning。

这意味着该模块不是按时间顺序留出，而是标准的随机监督学习评估流程。

2.4 fastText 格式训练文件

切分后，训练集和测试集会被写成 fastText 原生文本格式：

$$ \text{line}_i = \tilde{y}_i \; \Vert \; \tilde{s}_i \tag{6} $$

其中 \(\Vert\) 表示“标签 + 空格 + 文本”的拼接。随后分别保存为临时 train.txt 和 test.txt。

3. fastText 监督分类模型

3.1 文本表示

fastText 监督分类的核心思想是：把文本表示为词及词 n-gram 特征的平均嵌入。设文档 \(s\) 提取出的特征集合为

$$ \mathcal{G}(s)=\{g_1,g_2,\ldots,g_m\} \tag{7} $$

其中既可以包含 unigram，也可以包含由 wordNgrams 控制的词级 \(n\)-gram。文档向量可写为

$$ h(s)=\frac{1}{m}\sum_{g\in\mathcal{G}(s)} v_g \tag{8} $$

其中 \(v_g\in\mathbb{R}^{d}\) 为特征嵌入向量，\(d=\text{dim}\)。

3.2 分类输出

文档向量输入线性分类层后得到类别 logits：

$$ z=W h(s)+b \tag{9} $$

若采用 softmax 损失，则类别概率为

$$ p(c\mid s)=\frac{\exp(z_c)}{\sum_{k=1}^{C}\exp(z_k)} \tag{10} $$

预测类别为

$$ \hat{y}=\arg\max_c p(c\mid s) \tag{11} $$

在实际代码中，预测结果由

$$ \mathrm{model.predict}(\tilde{s},k=1) \tag{12} $$

返回，随后再去掉 __label__ 前缀。

3.3 暴露给用户的主要参数

界面中真正传入 fastText 的主要参数包括：

• lr
• epoch
• wordNgrams
• dim
• ws
• minCount
• loss

其中：

$$ \text{loss}\in\{\text{softmax},\text{ns},\text{hs},\text{ova}\} \tag{13} $$

这说明该模块支持标准 softmax，也支持负采样、层次 softmax 和 one-vs-all。

4. 训练、预测与工程细节

4.1 训练调用

训练阶段直接调用：

$$ \mathcal{M}=\mathrm{TrainSupervised}(\mathcal{D}_{\mathrm{train}};\eta,T,n,d,ws,\text{minCount},\text{loss}) \tag{14} $$

其中：

• \(\eta=\text{lr}\)
• \(T=\text{epoch}\)
• \(n=\text{wordNgrams}\)
• \(d=\text{dim}\)

训练完成后，模型会先保存为临时 model.bin，再在导出结果时复制到结果目录下的

<结果文件名>_model.bin

4.2 预测概率

测试集上每条文本都会调用 model.predict(text, k=1)，得到：

$$ (\hat{y}_i,\hat{p}_i)=\mathrm{Predict}(\tilde{s}_i) \tag{15} $$

这里 \(\hat{p}_i\) 是 top-1 标签的预测概率，最终保存到 pred_prob 列。

4.3 NumPy 兼容性补丁

代码中有一个较特殊的工程实现：若 fasttext 在预测阶段触发 NumPy 2.x 的 Unable to avoid copy 异常，则会临时 monkey patch np.array，完成预测后再恢复。这个补丁不改变算法逻辑，但说明该模块为了兼容运行环境，对底层 Python 绑定做了额外处理。

5. 评价指标与输出结果解释

5.1 分类指标

测试集上输出的核心指标包括：

• accuracy
• precision
• recall
• f1_score
• f1_weighted

其中准确率为

$$ \mathrm{Accuracy}=\frac{1}{|\mathcal{D}_{\mathrm{test}}|}\sum_i \mathbf{1}(\hat{y}_i=y_i) \tag{16} $$

加权 F1 可写为

$$ \mathrm{F1}_{\mathrm{weighted}}=\sum_{c=1}^{C}\frac{n_c}{\sum_j n_j}\cdot \mathrm{F1}_c \tag{17} $$

代码中的 precision、recall 和 f1_score 实际都采用 average='weighted' 计算，因此 f1_score 与 f1_weighted 在当前实现中是同一个值。

5.2 混淆矩阵与分类报告

程序会按 label_order 生成混淆矩阵：

$$ \mathrm{CM}_{ab}=\sum_i \mathbf{1}(y_i=a,\hat{y}_i=b) \tag{18} $$

同时还会调用 classification_report() 生成文本版分类报告，并导出到 ClassificationReport 工作表。

5.3 输出结果说明

save_to_excel() 会导出：

• RawData
• ProcessedData
• Predictions
• Metrics
• ConfusionMatrix
• ClassificationReport
• Parameters
• Charts

其中：

• RawData 保存原始输入表；
• ProcessedData 保存 text/label/clean_text；
• Predictions 保存测试集文本、真实标签、预测标签和 pred_prob；
• Charts 记录图表路径；
• 结果目录还会额外复制一份 .bin 模型文件。

5.4 图表输出

当前实现只稳定导出一个主要图表：

• confusion_matrix.png

没有训练损失曲线，也没有验证集曲线，因为官方 fasttext.train_supervised() 的 Python 封装在这里并未暴露逐 epoch 的训练历史。

6. 复现脚本与实现说明

6.1 自动复现脚本

结果页可导出 repro_fasttext_*.py。该脚本会：

1. 尝试把原始数据复制到 repro_inputs/；
2. 重新读取数据；
3. 调用同一个 FastTextCalculator.run()；
4. 再导出一份新的 xlsx 和 .bin。

因此复现逻辑本质上是

$$ \text{repro}=\text{同参数重新训练一遍 fastText} \tag{19} $$

而不是直接加载之前保存好的 .bin 只做推理。

6.2 实现说明与注意事项

结合 core/fasttext_calculator.py、ui/upload_widget.py、ui/results_widget.py 和真实导出的结果文件，可以把该模块总结为：

• 它确实是官方 fastText 监督分类接口的工程封装；
• 只支持文本分类，不支持回归；
• 文本预处理较轻，只做空白规整与空文本剔除；
• 划分方式是随机 train/test split，必要时做分层抽样；
• 指标基于测试集计算，评估流程比 BERT_Finetune 更接近常规机器学习范式；
• 导出层较完整，包含预测表、混淆矩阵、分类报告、参数表和 .bin 模型文件。

因此，在论文说明中更准确的写法应是：该软件实现了一个基于官方 fastText train_supervised 的文本分类模块，采用词/词 n-gram 平均表示与线性分类头，并在随机划分测试集上输出分类性能。

7. 论文写作模板

可在论文“方法部分”中写为：

“本文采用 fastText 监督文本分类方法对文本样本进行自动判别。首先，对原始文本执行清洗、标签整理和训练文件构造，将样本转换为 fastText 所需的监督学习输入格式；其次，利用词级或字符级 \(n\)-gram 表示构建文本特征，并训练 fastText 分类模型；随后，在测试样本上输出类别预测及评价指标，以衡量模型的分类效果；最后，结合预测结果表与混淆矩阵结果，对文本分类性能进行分析。”

8. 单篇终审补充

8.1 图题与表题对齐建议

• RawData 表可写为：表X fastText 原始文本数据表。
• ProcessedData 表可写为：表X fastText 处理后文本数据表。
• Predictions 表可写为：表X fastText 测试集预测结果表。
• Metrics 表可写为：表X fastText 分类指标汇总表。
• ConfusionMatrix 表可写为：表X fastText 混淆矩阵表。
• ClassificationReport 表可写为：表X fastText 分类报告表。
• Parameters 表可写为：表X fastText 参数设置表。
• Charts 表可写为：表X fastText 图表索引与路径清单。
• confusion_matrix.png 建议写为：图X fastText 混淆矩阵图。

8.2 终审说明

• 当前代表性结果目录中的真实主工作簿可采用 fasttext_results_20260329_150706.xlsx，其复现输出为 repro_fasttext_20260329_150706.xlsx。较早期目录如 20260324_001020 还可能缺少 Charts 工作表，因此论文引用结果时应优先绑定较新且结构完整的目录。
• 当前完整工作表口径为 RawData/ProcessedData/Predictions/Metrics/ConfusionMatrix/ClassificationReport/Parameters/Charts。若引用早期目录，应注意它可能只有前 7 张表，没有 Charts。
• 当前稳定实体图文件只有 confusion_matrix.png，并无训练损失曲线或验证曲线。正文若描述图表输出，应避免虚构训练过程图。
• 真实 repro 脚本为 repro_fasttext_*.py，并通过 SRC_FILE = SCRIPT_DIR / 'repro_inputs' / 'fasttext_ui_input.csv' 或 fasttext_repro_input.csv 读取输入副本。附录复现实验说明应保留这种 SCRIPT_DIR / repro_inputs 的相对路径风格。
• 结果目录通常还会附带 .bin 模型文件，但论文若以“可复现实验”为主，仍应以 xlsx + repro_fasttext.py + repro_inputs 作为主要证据链，而不是把 .bin 当作唯一复现依据。

8.3 全量强化补充

• 当前应绑定的真实结果目录为 具体的算法3/NLP基础/FastText-fastText 文本分类/results/FastText-fastText 文本分类分析结果_20260329_150706。
• 该目录首层主工作簿为 fasttext_results_20260329_150706.xlsx，实际工作表为 RawData、ProcessedData、Predictions、Metrics、ConfusionMatrix、ClassificationReport、Parameters、Charts，与正文前文给出的表结构一致。
• 同层同时存在主训练产物 fasttext_results_20260329_150706_model.bin 和主图目录 fasttext_results_20260329_150706_plots/confusion_matrix.png。因此若论文附录讨论“模型落盘”，应同时点明 xlsx + .bin + plots 是一组主运行产物，而不是只保留表格。
• 同一目录首层还存在完整再生产物链：repro_fasttext_20260329_150706.py、repro_fasttext_20260329_150706.xlsx、repro_fasttext_20260329_150706_model.bin、repro_fasttext_20260329_150706_plots/confusion_matrix.png 以及 repro_inputs/fasttext_ui_input.csv。
• 这说明 FastText 当前采用的是“主运行结果与 repro 再生产物共存于同一时间戳目录”的结构，而不是把 repro 放到 results 根目录或独立二级目录。正文若写复现路径，必须区分“主运行前缀 fasttext_results_...”与“复现前缀 repro_fasttext_...”。
• 当前真实图目录名是 *_plots，不是常见的 charts。因此图表说明应写“plots 目录下的 confusion matrix 图”，不宜套用别的 NLP 分类算法使用的 Charts/charts 目录口径。
• Charts 工作表承担的是路径索引作用，但物理图片并不位于 Charts/ 文件夹，而是位于 fasttext_results_20260329_150706_plots/ 和 repro_fasttext_20260329_150706_plots/。正文和附录在解释路径时应按这一真实结构落地。
• 由于当前实盘只有混淆矩阵图，没有训练损失曲线、验证精度曲线或词向量投影图，论文图题和结果解释都不应虚构这些不存在的训练过程可视化。

9. 软件实现核查补充（2026-07）

• 当前实现的主结果目录应写作 具体的算法3/NLP基础/FastText-fastText 文本分类/results/FastText-fastText 文本分类分析结果_20260329_150706，主工作簿以 fasttext_results_20260329_150706.xlsx 为准。
• 正文应围绕 RawData、ProcessedData、Predictions、Metrics、ConfusionMatrix、ClassificationReport、Parameters、Charts 来写，不要把 repro 再生成果当成另一种算法输出。
• 图证应对应 fasttext_results_20260329_150706_plots/confusion_matrix.png，不要虚构训练损失或验证曲线。
• repro_fasttext_20260329_150706.py + repro_inputs/fasttext_ui_input.csv 是标准结果目录内复现口径，.bin 模型文件属于工程产物，正文可提但不必作为主图证。