benitodev/Olist_NLP

# Olist DS — NLP（差评检测）与推荐系统（冷/热启动） 基于 **Olist 巴西电子商务数据集** (Kaggle) 构建的端到端数据科学 / ML 项目，包含两个主要模块： 1. **NLP + 分类**：从葡萄牙语文本中检测负面评论（*差评*）以及主题建模 (NMF)。 2. **推荐系统**：针对 **冷启动**（新用户）和 **热启动**（回访用户）的基线与模型。 该项目还包含可复现的 **数据工程** 方法 (ETL)，以及面向生产的 **Postgres + Docker** 技术栈和用于模型服务的 **FastAPI**。 ## 解决的问题 - 从评论中 **自动检测糟糕的客户体验**（以便优先处理支持/QA）。 - 根据用户情境（新用户 vs 回访用户）及可用历史数据的数量，使用不同策略 **推荐产品**。 ## 数据集 **来源**：Olist Brazilian E-Commerce Public Dataset (Kaggle) https://www.kaggle.com/datasets/olistbr/brazilian-ecommerce 使用的表（来自公共数据集）： - Orders, Customers, Products, Sellers, Geolocation - Reviews（葡萄牙语文本） ## 模块 1 — NLP：差评检测 ### 目标 使用的定义： - `bad_review = 1` 如果 `review_score <= 2` - `bad_review = 0` 如果 `review_score > 2` ### 流程（高层） - 文本清洗与归一化： - 小写化 - 变音符归一化 - 葡萄牙语停用词（保留如 `não` 等否定词） - 向量化： - **TF-IDF 词 n-grams** - 可选的 **字符 n-grams**（有助于处理噪声/拼写错误） - 评估的模型（强健、可复现的基线）： - Logistic Regression - Linear SVM / 校准变体 ### 划分与评估 - **基于时间的划分**（以避免泄露）。 - 指标： - ROC-AUC, PR-AUC - 针对少数类（差评）的 F1 / Precision / Recall - 根据业务目标进行阈值分析（*threshold tuning*） ### 结果（基线） 示例（TF-IDF + Logistic Regression）： - **ROC-AUC ≈ 0.95** - **PR-AUC ≈ 0.82** - **F1 (bad)** ≈ 0.83 - **Recall (bad)** ≈ 0.91 - 混淆矩阵（示例）：`[[5665, 640], [183, 1641]]` ## 模块 2 — 推荐系统（冷启动 vs 热启动） 该数据集在用户-物品层面非常 **稀疏**。 使用这里采用的时间划分，大多数用户在 TRAIN 中 **只有 1 次购买**，这限制了纯协同方法的使用。 ### 为什么要区分场景 - **冷启动（新用户）**：无历史记录 → 使用热度/上下文基线。 - **热启动（回访用户）**：有一些历史记录 → 尝试 CF / item-item / 混合方法。 ### 场景 A — 冷启动（新用户） #### 基线 1：全局热度 推荐全局最受欢迎的 Top-K 物品。 示例 **HitRate@K**（冷启动）： - K=10 → ~0.0119 - K=50 → ~0.0385 - K=80 → ~0.0600 #### 基线 2：类别热度（上下文相关） 模拟“类别页面”：给定类别上下文，推荐该类别内的 Top-K 物品。 示例 **HitRate@K**（冷启动，类别热度）： - K=10 → ~0.1110 - K=20 → ~0.1676 - K=50 → ~0.2464 在冷启动中，**类别热度** 通常优于全局热度，因为它利用了上下文。 ### 场景 B — 热启动（回访用户） #### 热启动评估 - **留一法 / 基于时间** 的划分：在过去的记录上训练，并在用户的“最近”一次购买上进行评估。 #### 协同过滤 (ALS) — 侧重热启动 - 从 TRAIN 构建 user-item 矩阵 (CSR)。 - 训练 ALS（例如，`implicit` 库或等效实现）。 重要观察： - 稀疏性严重（拥有 ≥2 次购买的用户很少）。TRAIN 中的示例： - `>=2` 次交互：~6% - `>=3`：~0.9% - 由于用户历史记录太少，ALS 往往覆盖率/召回率较低。 示例（ALS 产品级 HitRate@K）： - K=10 → 0.0 - K=15 → ~0.0238 - K=30 → ~0.0476 实践结论：对于此数据集，**纯 CF** 本身是不够的；建议使用 **带有回退机制的混合方法**。 ### Item-to-Item（共现） + Postgres 中的“真实邻居” 基于订单中的共现（购物篮分析）构建 item-item 图： - 仅考虑包含 **2+ 个物品** 的订单。 - 基于计数的余弦式评分：`cooc / sqrt(freq_a * freq_b)` - 仅在数据库中存储“真实邻居”（top-K）以实现高效服务。 示例（来自训练）： - 包含 2+ 个物品的订单：~2560 - 共现对：~3135 - 典型超参数：`TOPK=30`, `MIN_COOC=2`（更高的精度，更低的覆盖率） 推荐的服务逻辑： 1. 如果查询物品有邻居 → 推荐 item-item 邻居。 2. 否则 → 回退到 **类别热度**。 3. 如果类别缺失 → 回退到 **全局热度**。 ### NLP 相似度（文本 KNN）— “问题相似度” 额外内容：TF-IDF + 余弦相似度以检索相似评论（可用于）： - 聚类反复出现的问题（客户支持） - 调试产品/物流问题 - 探索性主题/索赔分析 ## 建议的仓库结构 ``` OLIST_DS/ │ ├── data/ │ ├── raw/ # Original Kaggle CSVs │ ├── processed/ # Clean datasets / features │ └── README.md │ ├── notebooks/ │ ├── 1_eda_python.ipynb │ ├── 2_build_dataset.ipynb │ ├── 3_eda_text_quality.ipynb │ ├── 4_baseline_text_vs_nontext.ipynb │ ├── 5_recommender_baseline.ipynb │ ├── 6_warm_evaluation_split.ipynb │ ├── 7_issue_similarity_Knn.ipynb │ ├── 8_colaborative_filtering.ipynb │ └── 9_item_item_recs_cooccurrence_store_real_neighbors.ipynb │ ├── src/ │ ├── etl/ # Load to Postgres / cleaning │ ├── nlp/ # training/eval NLP │ ├── recsys/ # baselines + ALS + item-item │ └── utils/ │ ├── docker-compose.yml # Postgres (and optional API) ├── .env.example # env vars (do not commit real .env) └── README.md ``` ## 安装与运行（可复现） ### 1) 克隆 ``` git clone https://github.com//.git cd ``` ### 2) 数据集 下载 Kaggle 数据集并将 CSV 文件放入： ``` data/raw/ ``` ### 3) 环境 (Conda) ``` conda create -n olist_ds python=3.11 -y conda activate olist_ds # 如果你有 requirements.txt pip install -r requirements.txt ``` ### 4) （可选）使用 Docker 启动 Postgres ``` docker compose up -d ``` 在 `.env` 中配置环境变量（示例）： - `POSTGRES_HOST` - `POSTGRES_PORT` - `POSTGRES_DB` - `POSTGRES_USER` - `POSTGRES_PASSWORD` ### 5) ETL 至 Postgres（如适用） ``` python -m src.etl.load_data ``` ### 6) 运行 notebooks ``` jupyter lab ``` 打开 `notebooks/` 并按顺序运行（EDA → 数据集 → NLP 基线 → 推荐系统）。 ## 指标（如何解读） ### 分类 - **ROC-AUC / PR-AUC**：排序质量，对不平衡数据具有鲁棒性。 - **F1 / Recall / Precision**：取决于所选阈值。 ### 推荐 - **HitRate@K**：如果至少有 1 个推荐物品在用户的真实集合中，则等于 1；否则为 0。 - 一个简单、清晰的基线和冷启动指标。 ## 关键设计决策 - **基于时间的划分**以避免泄露（NLP 和 RecSys）。 - 由于数据集稀疏性而进行 **冷启动 vs 热启动** 分离。 - 使用 **回退机制**（item-item → 类别 → 全局）的稳健服务。 ## 路线图 / 未来改进 - **FastAPI** 服务用于： - `POST /predict_bad_review` - `GET /recommend?user_id=...`（热启动） - `GET /recommend?item_id=...`（item-item） - 实验跟踪 (MLflow) + 数据集版本控制。 - Transformer 模型（BERTimbau / multilingual）vs TF-IDF 基线。 - 混合推荐系统（ALS + item-item + 内容）和/或基于会话的方法。 - 其他指标：MAP@K / NDCG@K（热启动），覆盖率/多样性。

标签：Apex, AV绕过, Docker, ETL, FastAPI, JavaCC, Kaggle数据集, NMF, PostgreSQL, Python, TF-IDF, Web服务, 主题建模, 冷启动, 安全防御评估, 客户体验管理, 差评检测, 巴西电商, 情感分析, 推荐系统, 支持向量机, 数据科学, 文本分类, 无后门, 机器学习, 测试用例, 特征工程, 电子商务, 请求拦截, 资源验证, 逆向工具, 逻辑回归