# 前端模型联调指南 (V3 & R1)

本文档旨在指导前端开发人员如何通过 API 调用不同的 LLM 模型（DeepSeek-V3 和 DeepSeek-R1）。

---

## 1. 模型标识符说明

在调用 API 时，请使用以下字符串作为模型标识：

| 模型名称 | 标识符 (API 传参值) | 适用场景 |
| :--- | :--- | :--- |
| **DeepSeek-V3** | `deepseek-ai/DeepSeek-V3` | 普通对话、通用问答、响应速度快。 |
| **DeepSeek-R1** | `Pro/deepseek-ai/DeepSeek-R1` | 复杂逻辑推理、深度故障诊断、代码生成。 |

---

## 2. 接口调用方式

### 2.1 AI 聊天接口 (`/api/v1/ai/chat`)

前端需要在请求体的 `context` 对象中传入 `model` 字段。

#### 请求示例 (TypeScript/Fetch):
```typescript
const response = await fetch('/api/v1/ai/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`
  },
  body: JSON.stringify({
    sessionId: "current-chat-id",
    message: "如何解决 NameNode 处于安全模式？",
    stream: true, // 建议开启流式
    context: {
      model: "Pro/deepseek-ai/DeepSeek-R1", // 切换模型
      agent: "HadoopExpert"
    }
  })
});
```

#### 响应处理 (SSE 流式):
当 `stream: true` 时，响应格式为 SSE (Server-Sent Events)。每一行 `data` 是一个 JSON 字符串，包含 `content` (正文) 和 `reasoning` (思维链，仅 R1 支持)。

```javascript
// 处理逻辑示例
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = new TextDecoder().decode(value);
  const lines = chunk.split('\n');
  lines.forEach(line => {
    if (line.startsWith('data: ')) {
      const { content, reasoning } = JSON.parse(line.slice(6));
      if (reasoning) updateReasoningUI(reasoning); // 更新思考过程 UI
      if (content) updateContentUI(content);       // 更新正文 UI
    }
  });
}
```

---

## 3. 故障诊断与自动修复接口 (`/api/v1/ai/diagnose-repair`)

对于自动诊断任务，模型参数直接放在请求体根部。

#### 请求示例:
```bash
curl -X POST http://localhost:8000/api/v1/ai/diagnose-repair \
-H "Content-Type: application/json" \
-d '{
  "cluster": "cluster-uuid-123",
  "model": "Pro/deepseek-ai/DeepSeek-R1",
  "auto": true,
  "maxSteps": 3
}'
```

---

## 4. 注意事项

1.  **默认模型**: 如果前端不传递 `model` 参数，后端将使用 `.env` 文件中配置的 `LLM_MODEL` (目前默认为 V3)。
2.  **R1 推理过程**: DeepSeek-R1 会输出 `reasoning_content`。前端建议提供一个可折叠的“思考过程”组件，用来展示 `reasoning` 字段的内容，以增强用户体验。
3.  **错误处理**: 若传入无效的模型名称，后端可能会返回 `403` 或 `502` 错误，请前端做好兜底逻辑。