update at 2025-10-14 21:52:11

STREAM_DEBUG_GUIDE.md

@@ -0,0 +1,238 @@
+# 流式输出调试指南
+
+## 如何确认流式是否启用
+
+### 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日
+**用途**: 调试流式输出功能