# learning 模块说明

## 模块作用

负责模式向量化（Sentence Transformers）、用户偏好向量的构建与融合（LLM 意图 + 反馈）、模式打分（含可选偏好加权与对比学习模型），以及 Triplet 数据集构建与 PreferenceEncoder 训练。

## 文件与类/函数

| 文件 | 类/函数 | 说明 |
|------|----------|------|
| embedder.py | PatternEmbedder | 模式文本 → 嵌入向量 |
| learner.py | PreferenceLearner | 用户向量融合、模式打分 |
| dataset.py | PreferenceDataset | 从反馈构建 (anchor, pos, neg) Triplet |
| trainer.py | PreferenceTrainer, CosineTripletLoss | 对比学习训练与损失 |

---

## 接口说明

### 1. PatternEmbedder（embedder.py）

#### `__init__(model_name: str = "sentence-transformers/all-MiniLM-L6-v2")`

- **传入参数**：`model_name`，Sentence Transformer 模型名。
- **传出参数**：无。

#### `encode_pattern(pattern: List[str]) -> np.ndarray`

- **传入参数**：`pattern`，特征名列表（如 `["Park", "Restaurant"]`），内部会转为字符串再编码。
- **传出参数**：一维嵌入向量。

#### `encode_patterns(patterns: List[List[str]]) -> np.ndarray`

- **传入参数**：模式列表，每项为特征名列表。
- **传出参数**：二维数组，每行一个模式向量。

#### `get_sentence_embedding_dimension() -> int`

- **传入参数**：无。
- **传出参数**：嵌入维度。

---

### 2. PreferenceLearner（learner.py）

#### `__init__(decay_lambda: float = 0.05, use_preference_weighted: bool = False)`

- **传入参数**：`decay_lambda` 意图权重衰减系数；`use_preference_weighted` 是否对分数做特征级偏好加权。
- **传出参数**：无。

#### `build_user_vectors() -> Tuple[Optional[np.ndarray], Optional[np.ndarray]]`

- **传入参数**：无（从 memory 读反馈）。
- **传出参数**：`(positive_vector, negative_vector)`，无反馈时为 `(None, None)`。

#### `compute_feedback_vector(user_id: str) -> Optional[np.ndarray]`

- **传入参数**：`user_id`。
- **传出参数**：u_feedback = mean(positive) - mean(negative)，无反馈为 `None`。

#### `get_user_vector(user_id: str, t: int = 0) -> Optional[np.ndarray]`

- **传入参数**：`user_id`；`t` 为交互轮次（用于衰减）。
- **传出参数**：融合向量 u_t = α_t * u_llm + (1-α_t) * u_feedback，无数据为 `None`。

#### `score_patterns(patterns, user_id=None, interaction_round=0) -> Optional[List[float]]`

- **传入参数**：`patterns` 模式列表；`user_id`、`interaction_round` 用于融合向量与可选偏好加权。
- **传出参数**：与 patterns 等长的分数列表，无法计算为 `None`。

#### `score_all_patterns(patterns, user_id=None, interaction_round=0) -> Optional[List[float]]`

- **传入参数**：同上。
- **传出参数**：同上（对 score_patterns 的封装）。

#### `fuse_vector(llm_vec, fb_vec, alpha: float) -> np.ndarray`

- **传入参数**：`llm_vec`、`fb_vec` 向量；`alpha` 融合权重。
- **传出参数**：α * llm_vec + (1-α) * fb_vec。

#### `update_user_vector_iterative(user_id: str, alpha: float = 0.6) -> Optional[np.ndarray]`

- **传入参数**：`user_id`；`alpha` 固定融合权重（Stage4）。
- **传出参数**：更新后的融合向量，无数据为 `None`。

---

### 3. PreferenceDataset（dataset.py）

#### `__init__(memory_store: MemoryStore, embedder: PatternEmbedder, user_id: str = "user_001")`

- **传入参数**：记忆存储、嵌入器、用户 ID。
- **传出参数**：无。

#### `build_user_vector() -> np.ndarray`

- **传入参数**：无。
- **传出参数**：当前用户向量（正负反馈均值差）。

#### `get_triplets() -> List[Tuple[np.ndarray, np.ndarray, np.ndarray]]`

- **传入参数**：无。
- **传出参数**：[(anchor, positive, negative), ...] 向量三元组列表。

#### `__len__()` / `__getitem__(idx)` 

- 标准 PyTorch Dataset 接口，返回三元组数量及第 idx 个 (anchor, positive, negative)。

---

### 4. PreferenceTrainer（trainer.py）

#### `__init__(input_dim, hidden_dim, margin=0.3, learning_rate=0.001, use_cosine_loss=True, ...)`

- **传入参数**：输入/隐藏维度、margin、学习率、是否使用余弦 Triplet 损失等。
- **传出参数**：无。

#### `train(epochs=10, batch_size=32, ...) -> Dict`

- **传入参数**：训练轮数、批大小等。
- **传出参数**：含 `loss_history` 等的字典。

#### `save_model(path: str)` / `load_model(path: str)`

- **传入参数**：模型保存/加载路径。
- **传出参数**：无。