# CompKey_Work

**Repository Path**: deeperName/comp-key_-work

## Basic Information

- **Project Name**: CompKey_Work
- **Description**: 智能商务作业。竞争性关键词分词算法
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CompKey: 工业级电子产品品牌竞争性关键词分析系统

CompKey 是一个基于 **Elasticsearch + MySQL + Redis** 构建的高性能算法系统，旨在通过海量搜索日志，精准计算电子产品品牌间的竞争关系，并具备基于 AI 的质量治理与闭环优化能力。

---

## 🚀 核心亮点

### 1. 分层停用词治理 (Layered Stopwords Design)
系统采用了三层过滤架构，确保从原始语料到最终展示的全链路质量：
- **Global 层**：通用虚词与地名，在分词阶段拦截。
- **Business 层**：业务噪声（如“官网”、“说明书”），在 ES 聚合阶段下沉执行（Pushdown Filter）。
- **Final Blacklist 层**：结果黑名单，在 API 返回前进行末端拦截，确保绝对的输出安全。

### 2. 智能化举报与闭环治理 (Closed-Loop Governance)
建立了一套“发现问题 -> 自动修复”的自进化链路：
- **实时反馈**：支持前端批量举报不满意结果。
- **凌晨复盘**：自动执行 RCA (Root Cause Analysis) 溯源，通过 `Scan` 模式抓取导致错误结果的中介词。
- **AI 审判**：集成 DeepSeek 判官，对中介词和结果词进行质量判定。
- **自动沉淀**：判定结果自动入库并生效，系统具备随使用时间增长而不断净化的能力。

### 3. 高性能 Redis 缓存体系 (Advanced Caching)
针对搜索场景的读多写少特性，设计了三道 Redis 防线：
- **结果缓存 (Result Cache)**：通过参数指纹实现结果级秒开。
- **幂等索引 (Idempotency Map)**：避免频繁查询 MySQL，快速复用已有任务。
- **分布式锁 (Distributed Lock)**：防止缓存击穿与并发重复计算。

### 4. 极致并发与并行设计 (Parallel Processing)
- **多进程并行**：利用 `ProcessPoolExecutor` 分摊 CPU 密集型的竞争度打分计算，充分榨干多核服务器性能。
- **计算下沉与“编排执行分离”**：利用 ES Aggregations 与 Painless 脚本将统计逻辑下沉至数据库侧，减少 90% 以上的网络传输开销。系统采用 **Python 指挥 + ES 执行** 的两阶段模式：
    - **为何必须返回 Python？** 第一阶段（Aggs）产出的中介词分布数据是第二阶段（Painless）打分的动态输入。Python 作为“中心大脑”根据识别出的 **品牌（Brand）与品类（Category）** 动态调整权重公式，实现特征空间的精准剪枝。
    - **效率平衡**：返回 Python 的仅为极少量的统计摘要，沉重的原始文档扫描与打分循环依然留在 ES 侧，实现“数据不动，指令动”。

### 5. 严格幂等性保障 (Strict Idempotency)
- **参数指纹**：对所有请求参数进行标准化哈希，确保同一请求在同一时段内只会被执行一次。
- **任务复用**：新请求会自动挂载到正在执行的相同任务上，极大节省了系统资源。

---

## 🛠️ 技术架构

```mermaid
graph TD
    User((用户/前端)) -- "1. 提交搜索 (含品牌/品类)" --> API[FastAPI Gateway]
    API -- "2. 校验幂等与缓存" --> Redis[(Redis Cache)]
    Redis -- "缓存缺失" --> Scheduler[Task Orchestrator]
    Scheduler -- "3. 并行打分" --> Worker[ProcessPoolExecutor]
    Worker -- "4. 聚合下沉查询" --> ES[(Elasticsearch)]
    Worker -- "5. 结果持久化" --> MySQL[(MySQL)]
    
    Gov[治理中心] -- "凌晨复盘" --> MySQL
    Gov -- "RCA 溯源" --> ES
    Gov -- "AI 审判" --> DS[DeepSeek API]
    DS -- "沉淀规则" --> MySQL
    MySQL -- "启动预热" --> Memory[Python Local Cache]
```

---

## 📁 目录指南

- [backend/](file:///e:/智能商务作业/EComp/backend/): FastAPI 后端核心代码。
- [docs/](file:///e:/智能商务作业/EComp/docs/):
    - [ARCH_DESIGN.md](file:///e:/智能商务作业/EComp/docs/ARCH_DESIGN.md): **核心！详细架构设计与流程图。**
    - [frontend_integration_guide.md](file:///e:/智能商务作业/EComp/docs/frontend_integration_guide.md): 前端对接说明书。
- [redis/](file:///e:/智能商务作业/EComp/redis/): Redis 专项设计文档。
- [sql/](file:///e:/智能商务作业/EComp/sql/): 数据库初始化与表结构说明。

---

## 🏃 快速开始

1. **环境准备**：
   - 推荐使用 Conda 环境：`e:\conda_envs\hanlp2-gpu-clean`
   - 安装依赖：`pip install -r backend/requirements.txt`

2. **配置启动**：
   - 复制 `backend/.env.example` 为 `.env` 并配置 ES/MySQL/Redis/DeepSeek 信息。
   - 启动后端：`uvicorn app.main:app --host 0.0.0.0 --port 8000`

3. **启动定时任务**：
   - 系统会自动随 FastAPI 启动调度器，执行凌晨治理任务。

---

## 📖 核心文档索引
- **想了解怎么做品牌补完？** 见 [brand_model_completion_guide.md](file:///e:/智能商务作业/EComp/docs/brand_model_completion_guide.md)
- **想了解 Redis 详细 Key 设计？** 见 [redis/README.md](file:///e:/智能商务作业/EComp/redis/README.md)
- **想了解如何优化 ES 性能？** 见 [ARCH_DESIGN.md](file:///e:/智能商务作业/EComp/docs/ARCH_DESIGN.md) 第 4 节。