# Co-location MVP 项目说明

## 项目概述

这是一个基于 LlamaFactory 和本地 LLM 的交互式空间共现模式挖掘系统 MVP 版本。系统能够：
1. 理解用户的自然语言查询（支持模糊意图理解）
2. 自动提取挖掘参数
3. 执行 co-location 模式挖掘
4. 基于用户反馈进行个性化排序优化（Stage3）
5. 使用 LLM 进行意图理解和偏好初始化（Stage0）
6. 支持多轮迭代交互式偏好精炼（Stage4）
7. 提供 Web 界面进行交互式查询和训练
8. 生成结果解释

## 项目结构

所有业务代码集中在 **`src/`** 目录下，便于阅读与维护；根目录保留入口脚本与配置。

```
colocation_mvp/
├── src/                    # 业务代码（全部放此处）
│   ├── llm/                # LLM 模块
│   │   ├── __init__.py
│   │   ├── client.py       # 模型加载和推理（集成 LlamaFactory）
│   │   ├── prompt.py       # 参数提取和解释生成提示词
│   │   ├── intent_encoder.py   # Stage0: 意图理解编码器
│   │   ├── intent_mapper.py    # Stage0: 意图到向量映射器
│   │   └── intent_prompt.py   # Stage0: 意图理解提示词模板
│   ├── preference/         # 偏好解析模块
│   │   ├── __init__.py
│   │   ├── parser.py       # 从 LLM 输出解析结构化参数
│   │   └── scorer.py       # 偏好打分器（Stage3）
│   ├── core/               # 核心挖掘模块
│   │   ├── __init__.py
│   │   └── miner.py        # Co-location 挖掘算法实现
│   ├── controller/         # 控制器模块
│   │   ├── __init__.py
│   │   ├── manager.py      # 流水线协调器（集成 Stage0 + Stage3 + Stage4）
│   │   └── iteration_manager.py  # Stage4: 迭代交互管理器
│   ├── memory/             # 记忆存储模块（Stage3 + Stage0）
│   │   ├── __init__.py
│   │   ├── store.py        # 用户反馈、偏好向量和意图向量存储
│   │   └── ...             # user_memory.json 等在 memory/ 下自动创建
│   ├── learning/           # 学习模块（Stage3）
│   │   ├── __init__.py
│   │   ├── embedder.py     # 模式向量化（Sentence Transformers）
│   │   ├── learner.py      # 用户偏好学习器（支持 Stage0 融合）
│   │   ├── dataset.py     # Triplet 数据集（对比学习）
│   │   └── trainer.py     # 对比学习训练器
│   ├── embedding/          # 编码器模块（Stage3）
│   │   ├── __init__.py
│   │   └── encoder.py      # PatternEncoder + PreferenceEncoder
│   ├── web/                # Web 模块（后端 + 前端 + 静态资源）
│   │   ├── __init__.py
│   │   ├── app.py          # FastAPI 应用入口
│   │   ├── router.py       # API 路由定义
│   │   ├── schemas.py      # Pydantic 数据模型
│   │   ├── services.py     # 业务逻辑层
│   │   ├── frontend/       # 前端页面
│   │   │   └── index.html  # 主页面
│   │   └── static/         # 静态资源（css, js）
│   │       ├── css/style.css
│   │       └── js/main.js
│   ├── experiment/         # 实验评估模块
│   │   ├── __init__.py
│   │   ├── simulator.py   # 用户模拟器
│   │   ├── metrics.py    # 评估指标
│   │   ├── evaluator.py  # 评估循环
│   │   ├── runner.py     # 实验运行器
│   │   └── plotter.py    # 绘图工具
│   ├── download/           # 数据下载/转换工具
│   ├── check_training_status.py
│   ├── convert_csv_to_json.py
│   └── test_stage3.py
│
├── data/                   # 数据目录
├── config/                 # 配置目录
├── models/                 # 模型目录（Stage3，自动创建）
├── logs/                   # 日志目录（自动创建）
├── document/               # 文档目录
├── main.py                 # 主程序入口（支持 CLI 和 Web 模式）
├── run_experiment.py       # 实验入口（从根目录运行，自动设置 src 路径）
├── run_plotter.py          # 绘图入口（从根目录运行）
├── requirements.txt
├── README.md
└── WEB_README.md
```

## 核心模块说明

### 1. LLM 模块 (`llm/`)

**client.py**: 
- 优先使用 LlamaFactory 加载模型（支持 LoRA 适配器）
- 如果 LlamaFactory 不可用，回退到直接使用 transformers
- 支持 GPU/CPU 推理
- 支持 JSON 提取和清理（处理多轮对话输出）

**prompt.py**:
- 定义参数提取提示词
- 定义解释生成提示词
- 系统提示词

**intent_encoder.py** (Stage0):
- 使用 LLM 解析用户模糊查询为结构化意图
- 验证意图中的 POI 类型是否在数据集中存在
- 过滤无效的意图模式

**intent_mapper.py** (Stage0):
- 将结构化意图转换为用户偏好向量
- 使用 Sentence Transformers 编码意图模式
- 生成初始用户向量 `u_llm`

**intent_prompt.py** (Stage0):
- 定义意图理解的提示词模板
- 动态包含数据集中的可用 POI 类型
- 引导 LLM 生成符合数据集的意图模式

### 2. 偏好解析模块 (`preference/`)

**parser.py**:
- 从 LLM 输出中提取 JSON 格式参数
- 如果 JSON 解析失败，使用正则表达式提取
- 参数验证和默认值填充
- 支持：min_participation, max_pattern_size, priority

### 3. 核心挖掘模块 (`core/`)

**miner.py**:
- 实现基于参与指数（Participation Index）的 co-location 挖掘算法
- 支持 2 阶到 k 阶模式挖掘
- 支持参与率阈值过滤
- 支持按置信度/参与率/大小排序

### 4. 控制器模块 (`controller/`)

**manager.py**:
- 协调整个流水线
- 调用 LLM 提取参数
- 调用挖掘算法
- 生成解释
- 提供 CLI 交互界面
- **Stage0**: 检测模糊查询，使用 LLM 进行意图理解
- **Stage0**: 初始化用户偏好向量（解决冷启动问题）
- **Stage3**: 集成用户偏好学习和排序优化
- **Stage3**: 支持手动触发模型训练
- **Stage0 + Stage3**: 动态融合意图向量和反馈向量（`u_t = α_t * u_llm + (1-α_t) * u_feedback`）
- **Stage4**: 支持多轮迭代交互模式（通过 `iteration_rounds` 参数）
- **Web**: 支持通过 API 进行查询、反馈和训练

**iteration_manager.py** (Stage4):
- 管理多轮迭代交互流程
- 维护迭代状态（IterationState）
- 执行单轮迭代（挖掘、排序、反馈收集、向量更新）
- 实现迭代偏好精炼算法
- 支持 LLM 意图初始化和反馈向量融合

### 5. 记忆存储模块 (`memory/`) - Stage3 + Stage0

**store.py**:
- 管理用户反馈历史（`history.json`）
- 管理用户偏好向量（`user_memory.json`）
- 管理意图理解数据（`intent_memory.json`，Stage0）
- 提供 `add_positive()` 和 `add_negative()` 方法
- 提供 `get_user_profile()` 方法
- 提供 `save_intent()` 和 `load_intent()` 方法（Stage0）
- 提供 `get_round_history()` 方法（Stage4，支持按轮查询历史）
- 自动处理 numpy 数组到 JSON 的序列化/反序列化

### 6. 学习模块 (`learning/`) - Stage3

**embedder.py**:
- 使用 Sentence Transformers 将模式编码为向量
- 支持模式列表的向量化

**learner.py**:
- 构建用户偏好向量（正反馈向量 - 负反馈向量）
- **Stage0 融合**: 动态融合意图向量和反馈向量
  - `u_t = α_t * u_llm + (1-α_t) * u_feedback`
  - `α_t = e^(-λt)`，其中 `t` 是交互轮数，`λ` 是衰减参数
- **Stage4 融合**: 支持固定权重融合（`u_t = α * u_llm + (1-α) * u_feedback`）
- 计算模式与用户偏好的相似度
- 支持基线方法（平均向量）和对比学习模型
- 提供 `fuse_vector()` 和 `update_user_vector_iterative()` 方法（Stage4）

**dataset.py**:
- 生成 Triplet 数据集（anchor, positive, negative）
- 用于对比学习训练

**trainer.py**:
- 实现 Triplet Loss 和 Cosine Triplet Loss
- 训练 PreferenceEncoder 模型
- 支持模型保存和加载

### 7. 编码器模块 (`embedding/`) - Stage3

**encoder.py**:
- `PatternEncoder`: 基础编码器（冻结的 Sentence Transformers）
- `PreferenceEncoder`: 可学习的偏好投影器（PyTorch nn.Module）

### 8. Web 服务模块 (`web/`) - Web UI

**app.py**:
- FastAPI 应用初始化
- 静态文件服务
- 启动事件处理

**router.py**:
- 定义 REST API 端点：
  - `POST /api/query`: 执行查询（支持 `iteration_rounds` 参数，Stage4）
  - `POST /api/feedback`: 提交用户反馈
  - `POST /api/train`: 触发模型训练
  - `GET /api/train/history`: 获取训练历史
  - `POST /api/iteration/start`: 启动迭代会话（Stage4）
  - `POST /api/iteration/next`: 继续下一轮迭代（Stage4）
  - `POST /api/iteration/finalize`: 完成迭代并获取最终结果（Stage4）
  - `POST /api/recompute`: 使用自定义参数重新计算模式

**schemas.py**:
- 使用 Pydantic 定义请求/响应模型
- 数据验证和序列化
- **API 响应模型更新**：
  * `IterationStartResponse`: 包含 `intent_used` 和 `intent_data` 字段（Stage0）
  * `IterationNextResponse`: 包含 `intent_used` 和 `intent_data` 字段（Stage0）
  * `IterationFinalizeResponse`: 包含 `intent_used`、`intent_data` 和 `params` 字段（Stage0）
  * 确保意图理解数据能够正确传递到前端

**services.py**:
- 业务逻辑层，连接 Web API 和 PipelineManager
- 处理数据清理（numpy 数组转列表）
- 管理训练历史

### 9. 前端模块 (`src/web/frontend/` + `src/web/static/`)

**frontend/index.html**:
- Web UI 主页面结构
- 查询输入、结果显示、反馈按钮
- 迭代轮数输入（Stage4）
- 迭代历史显示区域（Stage4）
- 训练历史可视化（Chart.js）

**web/static/js/main.js**:
- 前端交互逻辑
- API 调用
- 结果展示和可视化
- **意图理解显示**：
  * 显示用户偏好模式（Preferred Patterns），使用带编号的徽章样式
  * 显示目标业务类型、重要因素、风险因素
  * 自动过滤空值，只显示有实际内容的条目
  * 所有标签使用英文显示
- **界面优化**：
  * 移除所有 emoji 图标
  * 规则挖掘结果不在前端显示（后端仍会计算，但不展示）
  * 优化迭代历史显示，移除规则数量统计

**web/static/css/style.css**:
- Web UI 样式定义
- **意图理解样式**：
  * 意图框使用浅橙色背景（#fff3e0）
  * 偏好模式列表使用带编号的徽章样式（橙色背景）
  * 列表项使用浅黄色背景，左侧橙色边框
  * 向量信息使用灰色背景显示

## 工作流程

### 完整工作流程（包含 Stage0、Stage3 和 Stage4）

#### 单轮模式（默认，Stage0 + Stage3）

```
用户输入（自然语言，可能模糊）
    ↓
[Stage0] 检测是否为模糊查询
    ├─ 是 → LLM 意图理解（intent_encoder.py）
    │       ↓
    │   生成结构化意图（business, pattern_preference, risk等）
    │       ↓
    │   映射为初始用户向量 u_llm（intent_mapper.py）
    │       ↓
    │   保存到 intent_memory.json
    │
    └─ 否 → 直接提取参数
    ↓
LLM 提取挖掘参数（client.py + prompt.py）
    ↓
解析结构化参数（parser.py）
    ↓
执行模式挖掘（miner.py）
    ↓
[Stage3] 用户偏好排序优化
    ├─ 融合向量计算：u_t = α_t * u_llm + (1-α_t) * u_feedback
    │   (α_t = e^(-λt)，t 为交互轮数)
    ├─ 计算模式相似度（learner.py）
    └─ 重排序结果
    ↓
生成解释（client.py + prompt.py）
    ↓
输出结果（manager.py / Web API）
    ↓
收集用户反馈（store.py）
    ├─ 正反馈 → 添加到 user_memory.json
    └─ 负反馈 → 添加到 user_memory.json
    ↓
[手动触发训练] ← 用户输入 'train' 或使用 --train 参数或 Web UI
    ↓
训练 PreferenceEncoder（trainer.py，可选）
    ├─ 生成 Triplet 数据集
    ├─ 使用 Triplet Loss 或 Cosine Triplet Loss
    └─ 保存模型到 models/preference_encoder.pth
    ↓
下次查询使用训练后的模型进行更准确的排序优化
```

#### 多轮迭代模式（Stage4）

```
用户输入（自然语言查询）+ 迭代轮数 K
    ↓
[Stage4] 初始化迭代状态
    ├─ 初始化用户向量 u0（从 LLM 意图理解，Stage0）
    └─ 创建 IterationState（current_round=0, max_rounds=K）
    ↓
For t = 1 to K:
    ├─ [轮次 t] 执行模式挖掘（miner.py）
    ├─ [轮次 t] 使用当前用户向量 ut 对模式排序（learner.py）
    ├─ [轮次 t] 显示排序后的模式给用户
    ├─ [轮次 t] 收集用户反馈 Ft（positive/negative patterns）
    ├─ [轮次 t] 更新用户向量：
    │   └─ ut = α * u_llm + (1-α) * u_feedback
    │       (α 为固定融合权重，Stage4 使用 fusion_alpha)
    └─ [轮次 t] 保存轮次历史
    ↓
[最终] 生成最终排序结果
    ├─ 使用最终用户向量 uK 对模式排序
    └─ 返回最优模式集合 P*
    ↓
输出最终结果（包含迭代历史）
```

**Stage4 与 Stage3 的区别**：
- Stage3：单轮查询 → 反馈 → 训练 → 下次查询优化
- Stage4：多轮迭代 → 每轮反馈 → 每轮更新向量 → 渐进式精炼偏好

### Stage0 意图理解流程

```
模糊用户查询（如："我想开一家早餐店"）
    ↓
LLM 意图理解（intent_encoder.py）
    ├─ 解析目标业务类型
    ├─ 提取重要空间因素
    ├─ 生成偏好模式（如：[["Park", "Restaurant"], ["Shopping Mall", "Restaurant"]]）
    └─ 识别风险因素
    ↓
验证模式有效性（确保 POI 类型在数据集中存在）
    ↓
映射为初始用户向量 u_llm（intent_mapper.py）
    ├─ 使用 Sentence Transformers 编码偏好模式
    └─ 生成向量表示
    ↓
保存到 intent_memory.json
    ↓
在后续查询中使用（与反馈向量动态融合）
```

### Stage3 闭环学习流程

```
1. 用户查询 → 模式挖掘 → 显示结果
2. 用户提供反馈（喜欢/不喜欢）
3. 反馈保存到 user_memory.json
4. 手动触发训练（train 命令、--train 参数或 Web UI）
5. 训练 PreferenceEncoder（对比学习）
   ├─ 生成 Triplet 数据集（anchor, positive, negative）
   ├─ 使用 Triplet Loss 或 Cosine Triplet Loss
   └─ 训练 PreferenceEncoder 模型
6. 模型保存到 models/preference_encoder.pth
7. 下次查询使用训练后的模型进行排序优化
8. 随着交互增加，意图向量权重逐渐衰减，反馈向量权重逐渐增加
```

### Web UI 工作流程

```
1. 启动 Web 服务：python main.py --web
2. 浏览器访问：http://localhost:8000
3. 在 Web 界面输入查询
   - 支持模糊意图查询（如："我想开个花店"）
   - 可选：指定迭代轮数（Stage4）
4. 查看意图理解结果（Stage0）
   - 显示目标业务类型
   - 显示偏好模式列表（带编号徽章）
   - 显示重要因素和风险因素（自动过滤空值）
   - 显示初始用户向量信息
5. 查看挖掘结果和相似度分数
6. 点击 👍/👎 提供反馈
7. 点击"训练模型"按钮触发训练
8. 查看训练历史曲线（Loss 变化）
9. 训练后，下次查询自动使用优化后的排序
```

## 配置说明

### config/config.yaml

关键配置项：

```yaml
model:
  model_name_or_path: "/path/to/model"  # 必须配置
  adapter_name_or_path: null              # 可选，LoRA 适配器路径
  template: "qwen"                       # 模型模板
  finetuning_type: "lora"                # 如果使用适配器，设置为 "lora" 或 "none"
  trust_remote_code: true

inference:
  device: "cuda"                         # "cuda" 或 "cpu"
  temperature: 0.7
  max_new_tokens: 512
  top_p: 0.9
  do_sample: true
  use_fp16: true

mining:
  default_min_participation: 0.6
  default_max_pattern_size: 5
  default_priority: "confidence"

data:
  data_path: "./data/beijing_haidian.json"  # 数据文件路径

logging:
  level: "INFO"
  log_file: "./logs/mvp.log"

# Stage0: Intent-Aware Preference Initialization Configuration
# Stage0 使用 LLM 理解用户意图，生成初始偏好向量，解决冷启动问题
stage0:
  enabled: true                    # 是否启用意图理解模块
  decay_lambda: 0.05               # 意图向量权重衰减参数 (α_t = e^(-λt)，值越小衰减越慢)
  min_confidence: 0.6              # 意图理解的最小置信度阈值

# Stage3: User Preference Learning Configuration
# Stage3 基于用户反馈进行对比学习，实现个性化推荐
stage3:
  enabled: true                    # Enable Stage3 preference learning
  use_contrastive: true            # Use contrastive learning (requires PyTorch)
  retrain_interval: 20             # Retrain after N feedback sessions (for record)
  margin: 0.3                      # Margin for triplet loss
  learning_rate: 0.001             # Learning rate for training
  hidden_dim: 256                  # Hidden dimension for PreferenceEncoder
  epochs: 10                       # Training epochs per retrain
  batch_size: 32                   # Batch size for training
  alpha: 0.7                       # Weight for preference score (vs confidence)
  use_cosine_loss: true            # Use cosine-based triplet loss
  model_save_path: "./models/preference_encoder.pth"
  user_id: "user_001"              # Default user identifier

# Stage4: Iterative Interaction Engine Configuration
# Stage4 多轮交互式偏好进化机制，从单轮查询系统升级为多轮协同决策系统
stage4:
  enabled: false                   # Enable Stage4 iterative interaction
  default_rounds: 3                # Default number of iteration rounds
  max_rounds: 5                    # Maximum number of iteration rounds
  fusion_alpha: 0.6                # Weight for LLM intent vs feedback fusion (α)
                                   # u_t = α * u_llm + (1-α) * u_feedback
```

## 使用方法

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

主要依赖包括：
- `llamafactory`（可选，用于模型加载）
- `transformers`（模型推理）
- `sentence-transformers`（模式向量化）
- `torch`（对比学习，可选）
- `fastapi`、`uvicorn`（Web 服务）
- `pydantic`（数据验证）
- `numpy`、`pandas`（数据处理）

### 2. 配置模型路径

编辑 `config/config.yaml`，设置你的模型路径和其他参数。

### 3. 运行系统

#### 3.1 命令行模式（CLI）

**交互模式**：
```bash
python main.py
```

**非交互模式（单次查询）**：
```bash
python main.py --query "我更关注高置信度的三阶模式"
```

**多轮迭代模式**（Stage4）：
```bash
# 使用默认迭代轮数（从配置文件读取）
python main.py --query "推荐早餐店" --iter 3

# 指定迭代轮数
python main.py --query "推荐早餐店" --iter 5
```

**手动训练模式**（Stage3）：
```bash
python main.py --train
```

**交互模式中的训练命令**：
```bash
python main.py
# 在交互提示符下输入: train
```

#### 3.2 Web 界面模式

**启动 Web 服务**：
```bash
python main.py --web
```

**自定义端口和主机**：
```bash
python main.py --web --host 127.0.0.1 --port 8080
```

**直接使用 uvicorn**：
```bash
uvicorn web.app:app --host 0.0.0.0 --port 8000 --reload
```

**访问 Web 界面**：
- 浏览器打开：`http://localhost:8000`
- 支持的功能：
  - 输入自然语言查询（支持模糊意图查询）
  - 指定迭代轮数（Stage4，可选）
  - 查看意图理解结果（Stage0）：
    * 目标业务类型（Target Business Type）
    * 偏好模式列表（Preferred Patterns），带编号徽章显示
    * 重要因素（Important Factors），自动过滤空值
    * 风险因素（Risk Factors），自动过滤空值
    * 初始用户向量信息（Initial User Vector）
  - 查看挖掘结果和相似度分数
  - 查看迭代历史（Stage4，显示每轮的统计信息：模式数、向量范数）
  - 点击 👍/👎 提供反馈
  - 点击"训练模型"按钮触发训练
  - 查看训练历史曲线（Loss 变化）

## 示例查询

### 精确参数查询（传统模式）

- "我更关注高置信度的三阶模式"
- "找出参与率大于0.7的模式"
- "搜索大小不超过4的模式"
- "优先考虑参与率高的模式"

### 模糊意图查询（Stage0 模式）

- "我想开一家早餐店"
- "在哪里开咖啡店比较好"
- "适合开餐厅的位置"
- "我想找一个适合开健身房的地方"
- "开便利店的最佳位置"

这些模糊查询会被 Stage0 模块解析为结构化意图，包括：
- 目标业务类型（如：早餐店、咖啡店、餐厅）
- 偏好模式（如：[["Park", "Restaurant"], ["Shopping Mall", "Restaurant"]]）
- 重要空间因素（如：靠近公园、高流量区域）
- 风险因素（如：避免竞争激烈区域）

## 数据格式

数据文件应为 JSON 格式：

```json
[
  {"id": 1, "type": "A", "x": 24, "y": 14},
  {"id": 2, "type": "B", "x": 13, "y": 3}
]
```

字段说明：
- `id`: 实例ID（同一类型内唯一）
- `type`: 特征类型（字符串，如 "A", "B", "C"）
- `x`, `y`: 空间坐标（浮点数）

## 技术特点

1. **模块化设计**：各模块独立，易于扩展
2. **容错机制**：LlamaFactory 不可用时自动回退
3. **灵活配置**：通过 YAML 文件配置所有参数
4. **日志记录**：完整的日志系统，便于调试
5. **类型注解**：代码包含类型提示，提高可维护性

## 与 LlamaFactory 的集成

本项目充分利用了 LlamaFactory 的能力：

1. **模型加载**：使用 LlamaFactory 的 `ChatModel` 类
2. **LoRA 支持**：支持加载微调的 LoRA 适配器
3. **模板系统**：使用 LlamaFactory 的模板系统（如 qwen）
4. **推理引擎**：使用 HuggingFace 推理引擎

如果 LlamaFactory 不可用，系统会自动回退到直接使用 transformers。

## Stage0 功能说明

### 什么是 Stage0？

Stage0 是一个基于 LLM 的意图理解和偏好初始化系统，用于解决冷启动问题：

1. **意图理解**：使用 LLM 解析用户的模糊业务目标（如"我想开一家早餐店"）
2. **结构化意图**：将模糊查询转换为结构化意图（业务类型、偏好模式、风险因素）
3. **向量初始化**：将结构化意图映射为初始用户偏好向量 `u_llm`
4. **动态融合**：与用户反馈向量 `u_feedback` 动态融合
   - `u_t = α_t * u_llm + (1-α_t) * u_feedback`
   - `α_t = e^(-λt)`，随着交互轮数 `t` 增加，意图向量权重逐渐衰减

### Stage0 使用方法

1. **启用 Stage0**：在 `config/config.yaml` 中设置 `stage0.enabled: true`
2. **配置衰减参数**：设置 `stage0.decay_lambda`（默认 0.05，值越小衰减越慢）
3. **模糊查询**：输入模糊的业务目标查询（如"我想开一家早餐店"）
4. **查看意图理解结果**：
   - **CLI 模式**：在控制台查看意图理解结果
   - **Web 模式**：在"Intent Understanding (Stage0)"区域查看：
     * 目标业务类型（Target Business Type）
     * 偏好模式列表（Preferred Patterns），使用带编号的橙色徽章显示
     * 重要因素（Important Factors），自动过滤空值
     * 风险因素（Risk Factors），自动过滤空值
     * 初始用户向量信息（Initial User Vector），显示维度和范数
5. **自动融合**：意图向量会与后续的反馈向量自动融合，实现平滑过渡

### Stage0 前端显示特性

- **偏好模式展示**：使用带编号的徽章样式，清晰展示每个偏好模式（如：`1 Park, Restaurant`）
- **空值过滤**：自动过滤 importance 和 risk 中的空值，只显示有实际内容的条目
- **英文显示**：所有标签和文本使用英文，保持界面一致性
- **样式优化**：使用浅橙色背景突出显示意图理解区域，提高可读性

详细说明请参考：`document/Stage0_Intent_Aware_Upgrade.md`

## Stage3 功能说明

### 什么是 Stage3？

Stage3 是一个基于用户反馈的个性化排序优化系统，通过以下方式实现：

1. **用户反馈收集**：系统记录用户对每个模式的"喜欢"或"不喜欢"反馈
2. **偏好向量学习**：从反馈中构建用户偏好向量（正反馈向量 - 负反馈向量）
3. **模式重排序**：根据模式与用户偏好的相似度重新排序结果
4. **对比学习**（可选）：使用 Triplet Loss 训练 PreferenceEncoder，学习更准确的偏好表示
5. **与 Stage0 融合**：动态融合意图向量和反馈向量，实现从冷启动到个性化学习的平滑过渡

### Stage3 使用方法

1. **启用 Stage3**：在 `config/config.yaml` 中设置 `stage3.enabled: true`
2. **启用对比学习**：设置 `stage3.use_contrastive: true`（需要 PyTorch）
3. **收集反馈**：
   - CLI 模式：在交互模式中，对查询结果提供反馈
   - Web 模式：点击 👍/👎 按钮提供反馈
4. **手动训练**：
   - 命令行：`python main.py --train`
   - 交互模式：输入 `train` 命令
   - Web 界面：点击"训练模型"按钮
5. **查看效果**：训练后，下次查询结果会根据您的偏好自动排序
6. **查看训练历史**：Web 界面会显示训练 Loss 曲线

详细说明请参考：`document/Stage3排序优化说明.md`

## Stage4 功能说明

### 什么是 Stage4？

Stage4 是一个多轮交互式偏好精炼系统，将系统从"单轮查询系统"升级为"多轮协同决策系统"：

1. **多轮迭代**：支持设置迭代轮数 K（默认 3 轮，最大 5 轮）
2. **渐进式精炼**：每轮根据用户反馈更新偏好向量，逐步逼近真实需求
3. **批量反馈**：每轮可以收集多个模式的反馈（positive/negative）
4. **动态更新**：每轮更新用户向量，下一轮使用更新后的向量进行排序
5. **最终推荐**：经过 K 轮迭代后，输出最优模式集合

### Stage4 核心算法

```
Algorithm: Iterative Preference Refinement

Input: Q (query), K (rounds)
Output: P* (best patterns)

Initialize u0 (from LLM intent)
for t=1..K:
  Generate Ct (candidate patterns)
  Rank Ct by ut
  Collect Ft (feedback)
  Update ut = α * u_llm + (1-α) * u_feedback

Return best patterns
```

### Stage4 使用方法

1. **启用 Stage4**：在 `config/config.yaml` 中设置 `stage4.enabled: true`
2. **配置参数**：
   - `default_rounds`: 默认迭代轮数（3）
   - `max_rounds`: 最大迭代轮数（5）
   - `fusion_alpha`: LLM 意图与反馈的融合权重（0.6）
3. **CLI 使用**：
   ```bash
   # 使用默认轮数
   python main.py --query "推荐早餐店" --iter 3
   
   # 指定轮数
   python main.py --query "推荐早餐店" --iter 5
   ```
4. **Web UI 使用**：
   - 在查询框中输入查询
   - 在"迭代轮数"输入框中输入轮数（1-10）
   - 点击"搜索"按钮
   - 查看迭代历史（每轮的统计信息）
5. **查看结果**：系统会显示每轮的挖掘结果和最终推荐

### Stage4 与 Stage3 的区别

| 特性 | Stage3 | Stage4 |
|------|--------|--------|
| 交互模式 | 单轮查询 | 多轮迭代 |
| 反馈收集 | 单次反馈 | 每轮批量反馈 |
| 向量更新 | 训练后更新 | 每轮实时更新 |
| 适用场景 | 快速查询 | 深度精炼偏好 |
| 融合方式 | 动态衰减（α_t = e^(-λt)） | 固定权重（α = fusion_alpha） |

详细说明请参考：`document/Stage4_Iterative_Interaction_Upgrade.md`

## Web UI 功能说明

### Web UI 特性

1. **查询界面**：输入自然语言查询，实时查看挖掘结果
2. **迭代模式**（Stage4）：
   - 迭代轮数输入框（可选）
   - 迭代历史显示（每轮的统计信息）
   - 显示总轮数和每轮的模式数、规则数、向量范数
3. **结果展示**：
   - 模式列表（带相似度分数）
   - LLM 生成的解释
   - 意图理解结果（Stage0）：
     * 目标业务类型（Target Business Type）
     * 偏好模式列表（Preferred Patterns），带编号徽章显示
     * 重要因素（Important Factors），自动过滤空值
     * 风险因素（Risk Factors），自动过滤空值
     * 初始用户向量信息（Initial User Vector）
   - 迭代历史（Stage4）：显示每轮的统计信息（模式数、向量范数）
4. **反馈功能**：点击 👍/👎 按钮提供反馈
5. **训练功能**：点击"训练模型"按钮触发训练
6. **训练历史可视化**：使用 Chart.js 显示 Loss 曲线
7. **参数显示**：显示当前使用的挖掘参数
8. **界面优化**：
   - 所有界面文本使用英文显示
   - 移除所有 emoji 图标，保持界面简洁
   - 自动过滤空值，只显示有实际内容的条目

详细说明请参考：`WEB_README.md`

## 最新更新

### 前端界面优化（2024年更新）

1. ✅ **意图理解结果展示**：
   - 在前端完整显示用户偏好模式（Preferred Patterns）
   - 使用带编号的徽章样式，清晰展示每个偏好模式
   - 显示目标业务类型、重要因素、风险因素和初始用户向量信息

2. ✅ **API 响应模型完善**：
   - 更新 `IterationStartResponse`、`IterationNextResponse` 和 `IterationFinalizeResponse`
   - 添加 `intent_used` 和 `intent_data` 字段，确保意图理解数据正确传递到前端

3. ✅ **界面显示优化**：
   - 移除所有 emoji 图标，保持界面简洁专业
   - 所有标签和文本使用英文显示
   - 规则挖掘结果不在前端显示（后端仍会计算，但不展示给用户）
   - 自动过滤空值，只显示有实际内容的条目（如 importance 和 risk 中的空值）

4. ✅ **样式优化**：
   - 优化意图理解框的样式，使用浅橙色背景突出显示
   - 偏好模式列表使用带编号的徽章，提高可读性
   - 优化迭代历史显示，移除规则数量统计

## 扩展方向

1. ✅ **Web UI**：已完成，使用 FastAPI + HTML/CSS/JavaScript 创建 Web 界面
2. ✅ **Stage4 迭代交互**：已完成，支持多轮迭代式偏好精炼
3. ✅ **意图理解前端展示**：已完成，完整显示用户偏好模式和意图理解结果
4. ✅ **界面优化**：已完成，移除 emoji，使用英文显示，过滤空值
5. **可视化**：添加模式可视化功能（地图展示、空间分布）
6. **RAG 集成**：集成检索增强生成，提升解释质量
7. **多智能体**：支持多智能体协作挖掘
8. **自动训练选项**：可考虑添加配置选项，允许用户选择自动或手动训练模式
9. **多用户支持**：扩展为多用户系统，支持不同用户的个性化推荐
10. **实时推荐**：支持实时流式推荐和更新
11. **模式解释增强**：使用更详细的 LLM 解释，包括空间因素分析
12. **Stage4 批量反馈 UI**：在 Web UI 中支持批量选择模式进行反馈

## 故障排除

### 模型加载失败
- 检查模型路径是否正确
- 检查是否有足够的 GPU 内存
- 查看日志文件了解详细错误

### 数据格式错误
- 确保 JSON 格式正确
- 确保每个实例包含必需字段

### 依赖问题
- 确保已安装所有 requirements.txt 中的包
- 如果使用 LlamaFactory，确保路径正确

## 数据存储

### 日志文件

**系统日志** (`logs/mvp.log`)：
- 模型加载信息
- 参数提取过程
- 挖掘过程
- Stage0 意图理解过程
- Stage3 训练过程
- 错误信息

**训练历史** (`logs/training_history.json`)：
- 训练时间
- 反馈数量
- 训练轮数
- Loss 曲线数据

### 用户数据文件

**用户偏好向量** (`memory/user_memory.json`)：
- 用户 ID
- 正反馈向量列表
- 负反馈向量列表
- 查询历史

**意图理解数据** (`memory/intent_memory.json`)：
- 用户 ID
- 初始意图向量 `u_llm`
- 结构化意图数据（business, pattern_preference, risk 等）
- 意图理解时间戳

**查询历史** (`memory/history.json`)：
- 所有查询记录
- 提取的参数
- 挖掘结果摘要

**迭代历史**（Stage4，存储在 `user_memory.json` 中）：
- 每轮的统计信息（模式数、规则数、向量范数）
- 轮次时间戳
- 用户向量更新历史

## 许可证

基于 LlamaFactory 项目构建，遵循相应的开源许可证。