# 🔍 Grok API 调试指南

## 数据格式说明

### WebClient 处理后的数据格式

Spring WebFlux 的 `WebClient.bodyToFlux(String.class)` 会自动处理 SSE 流，每个元素直接就是一个完整的 JSON 字符串：

```json
{
  "id": "8670de6a-75b3-97e2-fa5a-c2e3d7f1d0f2",
  "object": "chat.completion.chunk",
  "created": 1764858564,
  "model": "grok-4-1-fast-non-reasoning",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "你",
      "role": "assistant"
    },
    "finish_reason": null
  }],
  "system_fingerprint": "fp_174298dd8e"
}
```

### 字段说明

| 字段 | 说明 | 示例值 |
|------|------|--------|
| `id` | 请求唯一ID | `"8670de6a-75b3-97e2-fa5a-c2e3d7f1d0f2"` |
| `object` | 对象类型 | `"chat.completion.chunk"` |
| `created` | 创建时间戳 | `1764858564` |
| `model` | 使用的模型 | `"grok-4-1-fast-non-reasoning"` |
| `choices[0].index` | 选择索引 | `0` |
| `choices[0].delta.content` | 当前token内容 | `"你"` |
| `choices[0].delta.role` | 角色（首次出现） | `"assistant"` |
| `choices[0].finish_reason` | 结束原因 | `null`, `"stop"`, `"length"`, `"content_filter"` |
| `system_fingerprint` | 系统指纹 | `"fp_174298dd8e"` |

## finish_reason 说明

| 值 | 含义 | 处理建议 |
|----|------|----------|
| `null` | 流还在继续 | 继续接收token |
| `"stop"` | 正常结束 | ✅ 回复完整 |
| `"length"` | 达到最大token限制 | ⚠️ 回复可能被截断，建议增加 `max_tokens` |
| `"content_filter"` | 内容被过滤 | ⚠️ 回复包含敏感内容 |

## 解析流程

```
收到数据 → 跳过空行 → 检查 [DONE] → 去除 "data: " 前缀（如果有）
    ↓
解析 JSON → 验证 choices 字段 → 获取 choices[0]
    ↓
检查 delta 字段 → 提取 content → 回调 onToken(content)
    ↓
检查 finish_reason → 记录日志 → 完成
```

## 日志级别配置

在 `application.yml` 中配置：

```yaml
logging:
  level:
    com.xiaozhi.dialogue.llm.GrokStreamService: DEBUG  # 或 TRACE
```

### 各级别输出内容

#### TRACE（最详细）
```
TRACE - 收到原始SSE数据: {"id":"8670de6a...
TRACE - 提取到token: 你
TRACE - 提取到token: 好
```

#### DEBUG
```
DEBUG - 请求体: {"model":"grok-4-1-fast-non-reasoning",...}
DEBUG - 收到角色信息: assistant
DEBUG - JSON中缺少choices字段（如果有问题）
```

#### INFO
```
INFO  - 开始调用Grok API - Model: grok-4-1-fast-non-reasoning, UserMessage: 你好...
INFO  - 流结束原因: length
INFO  - Grok API流式调用完成
```

#### ERROR
```
ERROR - JSON解析失败 - 原始数据: xxx
ERROR - LLM调用失败: Connection refused
```

## 常见问题排查

### 问题1: 没有收到任何token

**可能原因**：
- API Key 错误
- 网络连接问题
- API URL 配置错误

**检查步骤**：
1. 查看日志是否有 `INFO - 开始调用Grok API`
2. 检查是否有错误日志
3. 验证 `application.yml` 中的配置：
   ```yaml
   xiaozhi:
     voice-stream:
       grok:
         api-key: ${GROK_API_KEY}
         api-url: https://api.x.ai/v1/chat/completions
   ```

### 问题2: token乱码或格式错误

**检查点**：
1. 启用 TRACE 日志查看原始数据
2. 确认 JSON 格式是否正确
3. 查看是否有 `ERROR - JSON解析失败` 日志

### 问题3: 回复被截断

**日志特征**：
```
INFO - 流结束原因: length
```

**解决方案**：
增加 `DEFAULT_MAX_TOKENS` 常量：
```java
private static final int DEFAULT_MAX_TOKENS = 4000; // 或更大
```

### 问题4: WebClient 连接超时

**错误日志**：
```
ERROR - LLM调用失败: Connection timeout
```

**解决方案**：
在 `initWebClient()` 中增加超时配置：
```java
this.webClient = WebClient.builder()
    .baseUrl(apiUrl)
    .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(10 * 1024 * 1024))
    .defaultHeader(HttpHeaders.ACCEPT, "text/event-stream")
    .build();
```

## 测试建议

### 1. 使用 curl 测试 API

```bash
curl -X POST https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4-1-fast-non-reasoning",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

预期输出：
```
data: {"id":"xxx","object":"chat.completion.chunk",...}
data: {"id":"xxx","object":"chat.completion.chunk",...}
data: [DONE]
```

### 2. 检查配置

```java
// 在 GrokStreamService 中添加测试方法
@PostConstruct
public void testConfig() {
    logger.info("Grok配置:");
    logger.info("  API URL: {}", voiceStreamConfig.getGrok().getApiUrl());
    logger.info("  Model: {}", voiceStreamConfig.getGrok().getModel());
    logger.info("  API Key配置: {}", voiceStreamConfig.getGrok().getApiKey() != null ? "已配置" : "未配置");
}
```

### 3. 单元测试

```java
@Test
public void testParseSSE() {
    String testJson = """
        {
          "id": "test",
          "choices": [{
            "delta": {
              "content": "测试"
            }
          }]
        }
        """;
    
    // 测试解析逻辑
}
```

## 性能监控

### 关键指标

1. **首 token 延迟**：从发送请求到收到第一个 token 的时间
2. **token 吞吐率**：每秒收到的 token 数量
3. **总响应时间**：从开始到收到 [DONE] 的时间

### 添加监控日志

```java
private long startTime;
private int tokenCount = 0;

public void streamChat(...) {
    startTime = System.currentTimeMillis();
    // ...
    .doOnNext(token -> {
        tokenCount++;
        if (tokenCount == 1) {
            long firstTokenLatency = System.currentTimeMillis() - startTime;
            logger.info("首token延迟: {}ms", firstTokenLatency);
        }
    })
    .doOnComplete(() -> {
        long totalTime = System.currentTimeMillis() - startTime;
        double tps = tokenCount / (totalTime / 1000.0);
        logger.info("总计: {}个token, 耗时: {}ms, 吞吐率: {:.2f} tokens/s", 
                    tokenCount, totalTime, tps);
    })
}
```

## 调试技巧

### 1. 保存原始响应

```java
// 在parseSSE中
logger.trace("原始响应: {}", line);
```

### 2. 使用断点调试

在以下位置设置断点：
- `parseSSE()` 方法入口
- `sink.next(content)` 之前
- `callback.onToken()` 调用处

### 3. 模拟测试

创建测试类：
```java
@Test
public void testGrokStreamService() {
    GrokStreamService service = new GrokStreamService();
    service.streamChat("你好", null, new TokenCallback() {
        @Override
        public void onToken(String token) {
            System.out.println("Token: " + token);
        }
        
        @Override
        public void onComplete() {
            System.out.println("完成");
        }
        
        @Override
        public void onError(String error) {
            System.err.println("错误: " + error);
        }
    });
    
    // 等待完成
    Thread.sleep(10000);
}
```

## 总结

正常工作流程：
1. ✅ 看到 `INFO - 开始调用Grok API`
2. ✅ 看到多个 `TRACE - 提取到token: xxx`
3. ✅ 看到 `INFO - 流结束原因: stop`（或 length）
4. ✅ 看到 `INFO - Grok API流式调用完成`

如果出现问题：
1. 检查日志级别是否足够详细
2. 查找 ERROR 级别的日志
3. 验证配置是否正确
4. 使用 curl 直接测试 API
5. 检查网络连接

---

**需要更多帮助？** 提供完整的错误日志和配置信息。