模型兼容性指南 - 数字先锋API文档

# 模型兼容性指南

## 问题背景

v0.1.2 版本中，GPT 模型可以正常生成文章，但其他模型（如 Qwen、DeepSeek 等）返回错误。

### 根本原因

1. **System Prompt 兼容性** - 部分模型忽略 system 角色指令
2. **JSON 格式要求** - 不同模型对"只输出 JSON"的理解不同
3. **输出格式差异** - 有些模型会添加 Markdown 包装或解释文字

---

## v0.1.3 修复方案

### 1. 智能提示词策略

```php
// 根据模型类型调整提示词
$is_gpt_model = (stripos($this->model, 'gpt') !== false);

if ($is_gpt_model) {
    // GPT 系列：使用 system prompt
    $messages[] = ['role' => 'system', 'content' => '...'];
}

// 所有模型：在 user prompt 中添加明确的 JSON 格式指令
$json_instruction = "IMPORTANT: You MUST output ONLY valid JSON...";
$messages[] = ['role' => 'user', 'content' => $prompt . $json_instruction];
```

### 2. 增强的 JSON 解析

```php
// 步骤 1: 移除 Markdown 代码块标记
$content = preg_replace('/^```json\s*/i', '', $content);
$content = preg_replace('/\s*```$/i', '', $content);

// 步骤 2: 提取第一个 { 到最后一个 } 之间的内容
$start_pos = strpos($content, '{');
$end_pos = strrpos($content, '}');
if ($start_pos !== false && $end_pos !== false) {
    $content = substr($content, $start_pos, $end_pos - $start_pos + 1);
}

// 步骤 3: 尝试解析，失败则清理后重试
```

### 3. JSON 清理辅助方法

```php
private function clean_json_content($content) {
    // 移除控制字符
    $content = preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F]/', '', $content);
    // 移除 BOM 标记
    $content = str_replace("\xEF\xBB\xBF", '', $content);
    // 标准化换行符
    $content = str_replace(array("\r\n", "\r"), "\n", $content);
    return $content;
}
```

---

## 支持的模型列表

### ✅ 已测试可用

| 模型 | 兼容性 | 备注 |
|------|--------|------|
| gpt-4o | ✅ 优秀 | 完美遵循 JSON 格式 |
| gpt-4-turbo | ✅ 优秀 | 完美遵循 JSON 格式 |
| gpt-3.5-turbo | ✅ 良好 | 偶尔需要清理 |
| qwen3.5-plus | ✅ 良好 | v0.1.3 修复后可用 |
| qwen-max | ✅ 良好 | v0.1.3 修复后可用 |

### ⚠️ 待测试

| 模型 | 预期兼容性 | 需要测试 |
|------|------------|----------|
| deepseek-chat | ⚠️ 中等 | 可能添加解释文字 |
| deepseek-coder | ⚠️ 中等 | 可能添加 Markdown |
| claude-3-opus | ⚠️ 中等 | system prompt 处理方式不同 |
| claude-3-sonnet | ⚠️ 中等 | system prompt 处理方式不同 |
| gemini-pro | ⚠️ 中等 | 格式可能不标准 |

---

## 测试方法

### 1. 设置测试环境

```bash
# 1. 更新插件到 v0.1.3
cd wp-content/plugins/
rm -rf cxsee-ai-writer/
unzip cxsee-ai-writer-v0.1.3.zip

# 2. 启用调试模式
# wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

### 2. 测试不同模型

1. 进入 **设置 → 数字先锋 API**
2. 点击 **🔄 加载模型列表**
3. 选择要测试的模型
4. 打开文章编辑页面
5. 点击 **✨ AI 生成**
6. 输入测试关键词：`人工智能发展趋势`
7. 观察结果

### 3. 查看调试日志

```bash
# 日志位置
wp-content/debug.log

# 关键日志标记
grep "数字先锋 API Client" wp-content/debug.log
```

### 4. 成功标准

- ✅ 文章生成成功（标题、内容、摘要都填充）
- ✅ 无 JSON 解析错误
- ✅ 内容格式正确（HTML 标签正常）

### 5. 失败排查

如果失败，检查日志中的：
1. **请求 Model** - 确认使用的模型
2. **响应状态码** - 200 成功，其他为失败
3. **错误响应体** - API 返回的错误信息
4. **AI 响应内容** - 模型实际返回的内容
5. **JSON 解析错误** - 解析失败的具体原因

---

## 常见问题

### Q: 模型返回"不支持的模型"

**原因**: API Key 没有该模型的访问权限  
**解决**: 联系 API 提供商开通权限

### Q: JSON 解析失败

**原因**: 模型输出格式不符合预期  
**解决**: 
1. 查看 debug.log 中的原始响应
2. 检查是否包含 Markdown 包装
3. 检查是否有额外解释文字
4. 提交日志以便改进解析逻辑

### Q: 生成时间过长（>120 秒）

**原因**: 模型响应慢或内容过长  
**解决**: 
1. 减少目标字数
2. 选择更快的模型
3. 检查网络连接

---

## 版本历史

### v0.1.3 (2026-04-13)
- ✅ 智能提示词策略（区分 GPT 和非 GPT 模型）
- ✅ 增强 JSON 解析（提取 { } 之间的内容）
- ✅ JSON 清理辅助方法
- ✅ 详细调试日志

### v0.1.2 (2026-04-12)
- ✅ API 域名修复
- ✅ 超时时间增加到 120 秒
- ✅ 模型列表响应格式修复

---

## 反馈与改进

如遇到模型兼容性问题，请提供：
1. 使用的模型名称
2. debug.log 中的完整日志
3. 错误消息截图
4. AI 响应原始内容（如有）

这将帮助我们改进解析逻辑，支持更多模型。

上一篇：数字先锋 API v0.2.0 更新说明下一篇：版本更新日志