2.8 KiB

Raw Permalink Blame History Unescape Escape

前端模型联调指南 (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):

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 支持)。

// 处理逻辑示例
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`)

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

请求示例:

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. 注意事项

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

2.8 KiB Raw Permalink Blame History Unescape Escape