SillyTavern_replica/API_CONFIG_DEBUG.md

# API 配置调试指南

## 问题描述

后端日志显示 Model 和 API URL 为空：
```
[LLMClient] 🔧 创建 ChatOpenAI 实例
  - Model: 
  - API URL: 
  - Temperature: 1
  - Max Tokens: 30000
```

## 可能的原因

### 1. 前端未配置 API

**症状**：
- 前端控制台显示 `currentProfile` 为 `null` 或 `apis.mainLLM` 不存在
- 后端接收到的 `apiConfig` 为空对象或字段为空

**解决方案**：
1. 打开浏览器开发者工具（F12）
2. 切换到 Console 标签
3. 查看是否有以下警告：
   ```
   [ChatBoxStore] ⚠️ 未找到 API 配置，请先到 API 配置页面设置
   ```
4. 如果有，需要先到 API 配置页面设置

### 2. API 配置页面设置步骤

1. **打开左侧边栏** → 点击 **API 配置** 标签
2. **创建或选择配置文件**：
   - 如果没有配置文件，点击 "新建配置"
   - 输入配置名称（如 "Default"）
3. **填写 Main LLM 配置**：
   - API URL: `https://api.openai.com/v1`（或其他兼容 OpenAI 的 API）
   - API Key: 你的 API 密钥
   - Model: `gpt-4` 或 `gpt-3.5-turbo`
4. **测试连接**：
   - 点击 "测试连接" 按钮
   - 确保连接成功并获取到模型列表
5. **保存配置**：
   - 点击 "保存" 按钮
6. **设置为默认**（可选）：
   - 在配置列表中点击 "设为默认"

### 3. 数据结构检查

正确的 `currentProfile` 结构应该是：

```javascript
{
  id: "profile-xxx",
  name: "Default",
  apis: {
    mainLLM: {
      apiUrl: "https://api.openai.com/v1",
      apiKey: "sk-xxx...",
      model: "gpt-4"
    },
    // 其他 API 配置...
  }
}
```

## 调试步骤

### 前端调试

1. **打开浏览器控制台**（F12 → Console）

2. **发送消息前查看日志**：
   ```
   [ChatBoxStore] 🔍 API 配置状态检查:
     - currentProfile: {...}
     - apis: {...}
     - mainLLM: {...}
   ```

3. **发送消息时查看日志**：
   ```
   --------------------------------------------------------------------------------
   [WebSocket] 📤 发送消息:
     - Floor: 6
     - Role: 互动小说家
     - Chat: 赛博朋克-数据幽灵
     - Stream: true
     - Message Length: 45
     - API Config: {
         api_url: "https://api.openai.com/v1",
         api_key: "***",
         model: "gpt-4"
       }
     - Current Profile: {...}
   --------------------------------------------------------------------------------
   ```

4. **如果 API Config 为空**：
   - 检查 `Current Profile` 是否为 `null`
   - 检查 `apis.mainLLM` 是否存在
   - 确认是否已保存配置

### 后端调试

1. **查看接收到的请求**：
   ```
   --------------------------------------------------------------------------------
   [WebSocket] 📨 收到请求:
     - Floor: 6
     - Role: 互动小说家
     - Chat: 赛博朋克-数据幽灵
     - Stream: True
     - Message Length: 45
     - API URL: https://api.openai.com/v1
     - API Key: ***xxxx
     - Model: gpt-4
   --------------------------------------------------------------------------------
   ```

2. **如果显示 "⚠️ 未提供"**：
   - 说明前端没有发送 `apiConfig`
   - 检查前端代码是否正确组装数据
   - 检查 WebSocket 消息格式

3. **如果字段为空**：
   - 说明前端发送了空值
   - 回到前端调试步骤

## 常见问题

### Q1: 配置保存后仍然为空？

**A**: 可能是以下原因：
1. 配置没有正确保存到 localStorage
2. 页面刷新后没有重新加载配置
3. 多个配置文件混淆

**解决**：
```javascript
// 在控制台执行
const store = useApiConfigStore.getState();
console.log('Profiles:', store.profiles);
console.log('Current:', store.currentProfile);
```

### Q2: 有多个配置文件，如何切换？

**A**: 
1. 在 API 配置页面选择要使用的配置
2. 点击 "加载" 按钮
3. 确认 `currentProfile` 已更新

### Q3: 测试连接成功，但发送消息时仍为空？

**A**: 
- 可能是测试后没有保存配置
- 或者保存后没有重新加载
- 尝试刷新页面重新加载配置

### Q4: 如何快速验证配置是否正确？

**A**: 在浏览器控制台执行：
```javascript
const apiConfig = useApiConfigStore.getState().currentProfile?.apis?.mainLLM;
console.log('API URL:', apiConfig?.apiUrl);
console.log('API Key:', apiConfig?.apiKey ? '已设置' : '未设置');
console.log('Model:', apiConfig?.model);
```

应该输出：
```
API URL: https://api.openai.com/v1
API Key: 已设置
Model: gpt-4
```

## 临时解决方案

如果暂时无法配置 API，可以使用环境变量或默认值：

### 方法 1: 使用 .env 文件

在 `.env` 文件中添加：
```env
MAIN_LLM_API_KEY=sk-your-api-key
MAIN_LLM_MODEL=gpt-4
MAIN_LLM_BASE_URL=https://api.openai.com/v1
```

### 方法 2: 代码中添加默认值

修改 `ChatBoxSlice.jsx`：
```javascript
apiConfig: {
  api_url: apiConfigStore.currentProfile?.apis?.mainLLM?.apiUrl || 
           import.meta.env.VITE_DEFAULT_API_URL || 
           'https://api.openai.com/v1',
  api_key: apiConfigStore.currentProfile?.apis?.mainLLM?.apiKey || 
           import.meta.env.VITE_DEFAULT_API_KEY || 
           '',
  model: apiConfigStore.currentProfile?.apis?.mainLLM?.model || 
         import.meta.env.VITE_DEFAULT_MODEL || 
         'gpt-4'
}
```

## 验证修复

完成配置后，发送一条测试消息，应该看到：

**前端日志**：
```
[WebSocket] 📤 发送消息:
  - API Config: {
      api_url: "https://api.openai.com/v1",
      api_key: "***",
      model: "gpt-4"
    }
```

**后端日志**：
```
[WebSocket] 📨 收到请求:
  - API URL: https://api.openai.com/v1
  - API Key: ***xxxx
  - Model: gpt-4

[LLMClient] 🔧 创建 ChatOpenAI 实例
  - Model: gpt-4
  - API URL: https://api.openai.com/v1
  - Temperature: 1.0
  - Max Tokens: 30000

[LLMClient] 🚀 开始流式请求...
```

## 总结

1. ✅ 确保在 API 配置页面创建了配置文件
2. ✅ 填写完整的 Main LLM 配置（URL、Key、Model）
3. ✅ 测试连接成功后保存配置
4. ✅ 在前端控制台验证 `currentProfile.apis.mainLLM` 存在
5. ✅ 发送消息时检查前后端日志中的 API 配置信息

如果仍有问题，请提供：
- 前端控制台的完整日志
- 后端控制台的完整日志
- API 配置页面的截图