# llm 模块说明

## 模块作用

负责大语言模型（LLM）的加载、推理，以及 Stage0 意图理解相关能力：从用户自然语言中提取挖掘参数、生成解释文本、解析模糊查询为结构化意图并映射为初始用户偏好向量。

## 文件与类

| 文件 | 类/对象 | 说明 |
|------|--------|------|
| client.py | LLMClient | 模型加载与文本生成 |
| prompt.py | PromptTemplate | 参数提取、解释生成的提示词常量 |
| intent_encoder.py | IntentEncoder | Stage0：模糊查询 → 结构化意图 |
| intent_mapper.py | IntentMapper | Stage0：意图 JSON → 用户向量 u_llm |
| intent_prompt.py | IntentPrompt | Stage0：意图理解提示词构建 |

---

## 接口说明

### 1. LLMClient（client.py）

#### `__init__(config_path: str = "config/config.yaml")`

- **传入参数**：`config_path`，配置文件路径（YAML）。
- **传出参数**：无（构造实例，内部加载模型）。

#### `generate(prompt: str, system: Optional[str] = None) -> str`

- **传入参数**：
  - `prompt`：用户输入文本。
  - `system`：可选系统提示。
- **传出参数**：模型生成的文本字符串。

---

### 2. PromptTemplate（prompt.py）

类属性（常量）：`PREFERENCE_EXTRACTION_PROMPT`、`EXPLANATION_GENERATION_PROMPT`、`SYSTEM_PROMPT`，用于参数提取与解释生成的提示模板，无显式“接口”参数。

---

### 3. IntentEncoder（intent_encoder.py）

#### `__init__(llm_client: LLMClient, available_poi_types: Optional[list] = None)`

- **传入参数**：
  - `llm_client`：LLM 客户端实例。
  - `available_poi_types`：数据集中存在的 POI 类型列表，用于校验意图中的模式。
- **传出参数**：无。

#### `parse(query: str) -> Optional[Dict[str, Any]]`

- **传入参数**：`query`，用户自然语言查询。
- **传出参数**：解析得到的意图字典（如 `business`、`pattern_preference`、`importance`、`risk` 等），失败为 `None`。

---

### 4. IntentMapper（intent_mapper.py）

#### `__init__(embedder: PatternEmbedder)`

- **传入参数**：`embedder`，模式嵌入器（来自 learning.embedder）。
- **传出参数**：无。

#### `to_vector(intent_json: Dict[str, Any]) -> Optional[np.ndarray]`

- **传入参数**：`intent_json`，IntentEncoder 输出的意图字典。
- **传出参数**：初始用户偏好向量 `u_llm`（对 pattern_preference 嵌入后求平均），失败为 `None`。

---

### 5. IntentPrompt（intent_prompt.py）

#### `build_intent_prompt(query: str, available_poi_types: list) -> str`（静态方法）

- **传入参数**：
  - `query`：用户查询。
  - `available_poi_types`：数据集 POI 类型列表。
- **传出参数**：填充好的意图理解提示词字符串。