用Python、Spring Boot和React构建AI Issue分类助手

从1,000个真实Issue出发

GitHub维护者每天要花大量时间阅读新Issue、判断该打哪个标签、检查是否已有类似报告。一位开发者用机器学习探索如何加速这道"第一遍筛查"，同时把最终决定权留给人。

项目的核心数据来源是GitHub Search API——从pandas-dev/pandas收集了1,000个近期Issue，保存标题、描述、标签、URL和创建时间。用真实公开Issue训练，比拿几十个编造样例要有说服力得多。

但原始标签需要仔细处理。一个Issue可能有很多标签，也可能一个都没有。为了做三分类（Bug / Docs / Enhancement），作者只保留恰好带有这三种标签之一的Issue。这样每个训练样本都有唯一确定的答案，不会把pandas的其他标签硬塞进三分类问题。

另一个容易踩的坑是数据泄漏。Issue标题里常见"BUG:""DOC:""ENH:"这类前缀，如果不清理，模型会直接学会从标题前缀里"抄答案"，而不是从报告内容中学习。训练前去掉这些前缀，是保证模型真正有用的关键一步。

数据泄漏（data leakage） 是机器学习中一个隐蔽但后果严重的陷阱：当训练数据中包含了在真实预测时不可能获得的信息，模型在验证集上会表现得异常好，但上线后一败涂地。文中提到的标题前缀就是典型例子——GitHub 的 Issue 标题常带 BUG:、DOC:、ENH: 前缀，这些前缀几乎直接等于标签。如果不清除，模型只需学会识别前缀就能拿到高准确率，而完全没有学到"从报告内容判断类型"的能力。

类似的泄漏还有很多形式：用未来数据预测过去、把目标变量以某种形式混入特征、在划分训练集和测试集之前就做了全局统计等。防范的核心原则是模拟真实推理场景——问自己"预测时这条信息到底能不能拿到"。文中在训练前剥离标题前缀，正是这一原则的具体应用。

两类文本特征如何结合

分类器同时使用两种文本表示：

• TF-IDF词特征：捕捉关键词和双词短语，比如read_csv、error、documentation，这些都是强信号
• Sentence embeddings：使用all-MiniLM-L6-v2模型生成句向量，捕捉更广泛的语义，即使两份报告用词完全不同也能匹配

两种特征拼接后，训练一个balanced logistic regression分类器。TF-IDF使用标题加最多1,500字符的描述，句向量使用标题加最多1,000字符的描述。

评估结果如何？在1,000个收集的Issue中，有713个恰好带有一个目标标签：459个Bug、144个Docs、110个Enhancement。在143个留出集上，分类器达到0.94准确率，F1分数分别是Bug 0.96、Docs 0.88、Enhancement 0.91。

这些数字衡量的是标签分类在这份数据集上的表现，而不是搜索能否找到真正的重复Issue。当Issue集合刷新时，类别数量和分数都会变化。

TF-IDF（词频-逆文档频率） 是一种经典的文本向量化方法，它将每篇文档表示为一个稀疏向量，每个维度对应词表中的一个词或短语。权重由两部分相乘：词频（该词在当前文档中出现的次数）和逆文档频率（该词在整个语料中出现得越少，权重越高）。这样，像 read_csv、error 这类在少数Issue中集中出现的词会获得高权重，而 the、is 这类到处都有的词权重趋近于零。TF-IDF 的优点是训练和推理都极快、可解释性强，能直接看出哪些词对分类贡献大；缺点是它只匹配字面词汇，无法理解同义词，例如"崩溃"和"crash"在它看来毫无关系。

Sentence embeddings（句向量） 则走另一条路线：使用预训练的语言模型（如文中提到的 all-MiniLM-L6-v2）把整句话编码成一个稠密向量，通常在384维左右。这类模型在海量文本上训练过，学会了把语义相近的句子映射到向量空间中相近的位置，因此即便两份报告用词完全不同，只要意思接近，余弦相似度也会很高。all-MiniLM-L6-v2 是一个经过蒸馏的小型模型，体积小、推理快，适合本地部署。

拼接两种特征 是一种互补策略：TF-IDF提供精确的词汇信号，句向量提供模糊的语义信号，分类器同时利用两者，往往比单独使用任一种更稳健。

相似Issue搜索的边界

搜索功能同样基于向量：为每个已存储Issue生成句向量并归一化，新报告也做同样处理，然后按归一化向量的点积（即余弦相似度）排序，返回最相似的五条，附带原始GitHub链接。

这是相似度搜索，不是经过验证的重复检测器。高相似度只说明两段文本在模型向量空间里靠得近，并不能证明它们描述的是同一个bug。即使两份报告都关于read_csv，也可能涉及完全不同的失败场景。维护者需要打开链接自行判断。

还有一个天然限制：搜索只能返回这1,000条已收集报告中的Issue。如果相关Issue不在集合里，应用找不到它。

余弦相似度 是衡量两个向量方向接近程度的指标，计算公式是两个向量的点积除以它们模长的乘积，取值范围在-1到1之间。在文本检索中，我们通常先对向量做归一化（把模长缩放到1），此时余弦相似度就简化为直接做点积，计算效率更高。余弦相似度只关心方向、不关心长度，因此特别适合比较文本向量——一篇长报告和一篇短报告只要主题相同，向量方向就会接近。

需要注意的是，余弦相似度高并不意味着"同一个问题"。在句向量空间中，"read_csv 读取空表头崩溃"和"read_csv 读取空表头报错但可继续"可能非常接近，而它们其实是不同的行为。因此文中反复强调这是相似度搜索而非重复检测：它按向量距离排序，返回最像的五条，但把"是否真的是同一个bug"的判断留给维护者。这是负责任的设计——把机器擅长的事（快速筛选候选）和人类擅长的事（结合上下文做判断）分开。

Python、Java与React如何串联

本地全栈版本的请求路径非常清晰：

React + Vite → Spring Boot /api/analyze → FastAPI /analyze → Python模型

React页面发送标题和可选描述，Spring Boot转发给FastAPI，Python加载保存的分类器、预测标签、运行相似度搜索，返回两部分结果，React再展示建议标签和链接报告。

加一层Java的目的是练习跨语言服务连接，保持清晰的API边界。这也让请求和响应契约变得重要——浏览器、Java服务和Python服务必须对同一套JSON字段达成一致。

对于公开Demo，作者用Streamlit单独构建了一个界面，直接加载同一个保存好的Python模型和搜索索引。这样用户通过一个链接就能体验，不需要启动三个本地服务。React/Spring Boot/FastAPI的完整流程保留在仓库里，供想研究全栈架构的人运行和检查。

跨语言服务拆分 在真实系统里很常见，但它带来一个隐形成本：契约一致性。当请求要穿过三层（浏览器 → Java → Python）时，任何一层字段名拼错、类型不一致或缺少默认值，都会导致静默失败。文中提到的"请求和响应契约"指的就是这件事——三方必须对同一套 JSON 字段（比如 title、description、predicted_label、similar_issues）达成一致。实践中通常用 OpenAPI/Swagger 或共享的接口文档来固化契约，并写集成测试覆盖端到端路径。

为什么要多加一层 Java 可能让读者疑惑。从功能上看，FastAPI 足以直接服务 React 前端。作者加 Spring Boot 的动机是练习跨语言服务连接、理解 API 边界，这是一种学习型架构选择，而不是性能或部署上的必需。这也解释了为什么公开 Demo 反而退回到 Streamlit 单进程方案——它的目标是让用户一键体验，而不是展示分布式架构。两种方案共用同一个保存好的模型和索引，保证预测结果一致。

实际试一条报告

输入这样的标题：

read_csv crashes when the file has an empty header

Demo会建议Bug标签，并返回五条相关pandas issue。这些链接报告是调查的起点，不是自动的重复判定。你还可以试试文档和功能增强的例子，观察预测标签如何随措辞和上下文变化。

经验与下一步

这个项目最有价值的体会是：构建一个ML功能远不止训练模型。需要收集和清洗数据、防止简单的标签泄漏、在留出样本上评估、保证推理与训练一致、设计API，还要在界面里说清输出的局限。

仍有改进空间。当前数据集合有限，也没有构建已确认重复/非重复Issue对的基准测试。下一步可以创建这样的评估集，衡量相关Issue排序是否真的有助于找到真实重复。此外还可以扩展和刷新Issue索引，并按Bug、Docs、Enhancement分别跟踪分类性能随时间的变化。