🚀 StackOverflow-Clustering：Oracle 数据库问题语义聚类与去重项目

🌟 项目概览 (Project Overview)

本项目旨在对 152,758 条关于 oracle-database 的 Stack Overflow 问答数据进行高精度语义聚类 (Semantic Clustering)，以实现主题级别的去重和知识聚合。

我们采用 SBERT 向量化技术结合 PCA 降维，并最终选定 MiniBatchKMeans ($K=1200$) 模型进行划分。项目的核心亮点在于建立了六类对照基线 (Baselines) 和九大评估指标 (Metrics) 体系，严格验证了聚类结果的真实语义结构和有效性。

核心成果

• 最终模型： MiniBatchKMeans ($K=1200$)

• 输入数据： PCA 降维至 256 维的 SBERT 语义向量。

• 去重效果： 通过定性分析，证明聚类能高效识别“本质相同但表达不同”的重复问题。

---

🛠️ 技术栈与依赖 (Tech Stack)

类别	库/工具	作用
向量化	sentence-transformers	使用 SBERT 模型生成高质量语义向量。
降维	scikit-learn (PCA), UMAP	高维数据降维及空间结构分析。
聚类	scikit-learn (MiniBatchKMeans, DBSCAN)	模型实现与参数调优。
数据处理	pandas, numpy	数据加载、清洗与矩阵运算。
可视化	matplotlib, plotly	生成 2D/3D 可视化图表。

📂 仓库结构说明 (Repository Structure)

本仓库按照项目的四个主要技术阶段进行组织。

StackOverflow-Clustering/
├── code/                         # 核心代码脚本
│   ├── 01_vectorization/         # 文本预处理与 SBERT 编码
│   ├── 02_dim_reduction/         # PCA/UMAP 降维与可视化
│   │   ├── run_dim_reduction.py    # 运行 PCA 降维，生成 pca_256.npy
│   │   └── run_comparison_viz.py   # 生成 UMAP/t-SNE 可视化图
│   ├── 03_clustering/            # 聚类模型实现
│   │   └── clustering_main.py      # 包含 DBSCAN 尝试和 K-Means 优化
│   └── 04_evaluation/            # 评估与定性分析模块
│       ├── baseline_generate.py    # 生成六类对照基线数据
|       ├── export_question_clusters.py # 生成对应 question id 的各 baseline 与 ours 的数据
|       ├── export_clusters.py # 找到小簇，并生成对应的 csv ，以便我们分析
│       ├── metrics_extended.py     # 计算九大聚类指标
│       └── question_cluster_inspect/topic_tree_generation.py# 簇内部子主题分解分析 (定性)
├── data/                         # 数据文件 (大型文件需通过链接下载)
│   ├── input/                      # 原始数据链接
│   └── final_outputs/              # 最终产出数据
├── docs/                         # 文档与报告
│   ├── 总结报告.md           # 完整的项目技术总结报告
├── results/                      # 实验结果输出文件
│   ├── visualization/            # 可视化图表
│   │   ├── visualization_result.png# 2D 聚类散点图
│   │   └── 3d_umap_256_dim.html    # 3D 交互式可视化文件
│   └── clustering_metrics/       # 模型对比图
│       └── k_distance_plot.png     # DBSCAN 失败证明图
└── README.md

💾 数据下载与准备 (Data Preparation)

由于原始数据和 SBERT 向量文件体积较大，它们未直接包含在 GitHub 仓库中。

1. 核心大文件下载 (Core Data Files)

请从以下链接下载核心数据文件，并将其放入 data/intermediate/ 文件夹中：

• 原始 SBERT 向量 (384D): [https://pan.baidu.com/s/1qOxf2zcBrfVJ9aOQue1PPQ?pwd=x8bw] oracle_full_content_embeddings.npy

2. 运行顺序 (Run Sequence)

按以下顺序运行代码：

1. 向量化 (01_vectorization): 运行相应的向量化脚本（如果要重新生成 embeddings.npy）。

2. 降维 (02_dim_reduction): 运行 run_dim_reduction.py 生成 pca_256.npy。

3. 聚类 (03_clustering): 运行 clustering_main.py 得到结果

4. 评估 (04_evaluation):

   • 运行 baseline_generate.py 生成对照基线。

   • 运行 metrics_extended.py 计算并输出评估报告 (cluster_metrics_extended_with_baselines.csv)。

   • 运行 topic_tree_generation.py 进行定性分析。