map-client-vue/STREAM_DEBUG_GUIDE.md

# 流式输出调试指南

## 如何确认流式是否启用

### 1. 检查控制台日志

发送消息后,你应该看到以下日志(按顺序):

```
✅ 流式已启用的标志:
🚀 [callModelStream] === 开始真正的流式请求 ===
🚀🚀🚀 [sendChatRequestStream] === 进入流式请求方法 ===
🌊🌊🌊 [makeChatRequestStream] === 开始读取流数据 ===
⚡⚡⚡ [makeChatRequestStream] 收到第一个数据块!耗时: XX ms
⚡ [callModelStream] 首字延迟: XX ms

❌ 流式未启用的标志:
⏱️ [callModel] 开始处理  ← 如果看到这个,说明用的是非流式
⏱️ [callModelStream] 模拟流式输出耗时  ← 旧的模拟流式
```

### 2. 观察用户体验

**流式已启用**:
- 发送消息后 1-2秒内开始看到文字
- 文字一个个或一小段一小段地出现
- 没有明显的"模拟打字"效果

**流式未启用**:
- 等待 8-10秒后才看到文字
- 文字以固定速度"打字"出现
- 看起来很假的打字效果

### 3. 检查网络面板

**Chrome DevTools → Network**:
- 查找请求到 `/chat/completions`
- 查看 Response 标签:
  - **流式**: 显示 `(pending)` 并逐渐增加内容
  - **非流式**: 一次性显示完整内容

## 可能的问题

### 问题1: 代码没有调用流式方法

**症状**: 控制台没有 `🚀🚀🚀` 日志

**原因**: `callModelStream` 可能还在调用 `callModel` 而不是 `sendChatRequestStream`

**检查**:
```typescript
// web/src/services/chatService.ts 第625行左右
// 应该是:
const result = await modelServiceManager.sendChatRequestStream(...)

// 不应该是:
const result = await this.callModel(...)
```

### 问题2: API不支持流式

**症状**: 有 `🚀🚀🚀` 日志,但没有 `🌊🌊🌊` 日志

**原因**: 
- 服务类型识别错误
- `stream: true` 没有生效

**检查**:
```typescript
// 查看控制台日志
🔍 [mapProviderType] volcengine → volcengine  // 应该正确映射

// 查看请求体
body = {
  model: "...",
  messages: [...],
  stream: true  // ← 必须是 true
}
```

### 问题3: 流式解析错误

**症状**: 有 `🌊🌊🌊` 日志,但没有 `⚡⚡⚡` 日志

**原因**: SSE (Server-Sent Events) 格式解析失败

**检查**: 在 `makeChatRequestStream` 中添加调试:
```typescript
for (const line of lines) {
  console.log('🔍 收到行:', line.slice(0, 100))  // 查看原始数据
  
  if (line.startsWith('data: ')) {
    try {
      const data = JSON.parse(line.slice(6))
      console.log('🔍 解析后:', data)  // 查看解析结果
    } catch (e) {
      console.error('❌ 解析失败:', e, line)
    }
  }
}
```

## 手动测试流式API

你可以手动测试API是否支持流式:

```bash
curl -N -X POST https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seed-1-6-flash-250828",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

**期望输出** (流式):
```
data: {"choices":[{"delta":{"content":"你"}}]}

data: {"choices":[{"delta":{"content":"好"}}]}

data: {"choices":[{"delta":{"content":"！"}}]}

data: [DONE]
```

**如果看到这样** (非流式):
```json
{
  "choices": [{
    "message": {"content": "你好！我是AI助手..."}
  }]
}
```

说明API不支持流式或配置错误。

## 快速修复步骤

### 步骤1: 确认流式方法被调用

1. 刷新页面
2. 打开控制台 (F12)
3. 发送消息 "测试"
4. 搜索 `🚀🚀🚀`

- ✅ **找到**: 进入步骤2
- ❌ **没找到**: 代码问题,检查 `chatService.ts`

### 步骤2: 确认开始读取流

1. 搜索 `🌊🌊🌊`

- ✅ **找到**: 进入步骤3  
- ❌ **没找到**: API配置问题,检查 `stream: true`

### 步骤3: 确认收到数据

1. 搜索 `⚡⚡⚡`

- ✅ **找到**: 流式成功!
- ❌ **没找到**: SSE解析问题,检查数据格式

### 步骤4: 检查首字延迟

流式成功后,查看性能:
```
⚡ [callModelStream] 首字延迟: 1500.00 ms  ← 应该 <2000ms
```

- ✅ **<2000ms**: 性能良好
- ⚠️ **2000-5000ms**: 网络慢但可接受
- ❌ **>5000ms**: 网络问题,考虑换API端点

## 性能对比

### 非流式 (当前可能的状态):
```
⏱️ [makeChatRequest] 网络请求耗时: 9,660 ms
⏱️ [callModelStream] 模拟流式输出耗时: 521 ms
总延迟: ~10,181 ms
首字延迟: 9,660 ms (等待完整响应)
```

### 真流式 (目标状态):
```
⏱️ [makeChatRequestStream] 首字节响应耗时: 1,200 ms
⚡ [callModelStream] 首字延迟: 1,200 ms
⏱️ [makeChatRequestStream] 流式总耗时: 3,500 ms
总延迟: ~3,500 ms
首字延迟: 1,200 ms (实时流式)
```

**改善**: 
- 首字延迟: 9,660ms → 1,200ms (提升 **8倍**) ⚡
- 总延迟: 10,181ms → 3,500ms (提升 **3倍**) 🚀

## 常见问题 FAQ

### Q: 为什么我看不到流式效果?

**A**: 检查以下几点:
1. 控制台是否有 `🚀🚀🚀` 日志?
2. API是否支持 `stream: true`?
3. 服务类型是否正确识别?

### Q: 流式请求报错怎么办?

**A**: 常见错误:
- `无法获取响应流`: API不支持流式
- `流式请求超时`: 网络问题或API响应慢
- `HTTP 400`: 请求参数错误,检查 `stream: true`

### Q: 首字延迟还是很高?

**A**: 可能原因:
- API服务器响应慢
- 网络延迟高
- 模型计算时间长

**解决**: 更换更快的模型或API端点

### Q: 如何回退到非流式?

**A**: 修改 `chatService.ts`:
```typescript
// 回退方案
const result = await this.callModel(conversation, model)
// 而不是
const result = await modelServiceManager.sendChatRequestStream(...)
```

---

**创建时间**: 2025年10月14日
**用途**: 调试流式输出功能