argon-theme/.kiro/steering/xiaomi-mimo-api-fix.md

小米 Mimo API 修复说明

修复时间

2026-01-26

问题描述

小米 Mimo 模型 API 请求失败，无法正常调用 MiMo-V2-Flash 模型。

修复内容

1. 优化 argon_call_xiaomi_api 函数

修改位置: functions.php 第 8047-8140 行

主要改进:

• ✅ 添加 stream 参数，明确设置为 false（非流式响应）
• ✅ 添加 Accept 请求头，明确接受 JSON 格式
• ✅ 使用 JSON_UNESCAPED_UNICODE 标志编码请求体，确保中文字符正确传输
• ✅ 明确设置 sslverify 为 true，确保 SSL 验证

修改前:

$data = [
	'model' => $model,
	'messages' => [
		['role' => 'system', 'content' => $prompt],
		['role' => 'user', 'content' => $content]
	],
	'temperature' => 0.7,
	'max_tokens' => 500
];

$response = wp_remote_post($endpoint, [
	'headers' => [
		'Content-Type' => 'application/json',
		'Authorization' => 'Bearer ' . $api_key
	],
	'body' => json_encode($data),
	'timeout' => 30
]);

修改后:

$data = [
	'model' => $model,
	'messages' => [
		['role' => 'system', 'content' => $prompt],
		['role' => 'user', 'content' => $content]
	],
	'temperature' => 0.7,
	'max_tokens' => 500,
	'stream' => false
];

$response = wp_remote_post($endpoint, [
	'headers' => [
		'Content-Type' => 'application/json',
		'Authorization' => 'Bearer ' . $api_key,
		'Accept' => 'application/json'
	],
	'body' => json_encode($data, JSON_UNESCAPED_UNICODE),
	'timeout' => 30,
	'sslverify' => true
]);

2. 增强 argon_get_xiaomi_models 函数

修改位置: functions.php 第 9009-9055 行

主要改进:

• ✅ 添加 Accept 请求头
• ✅ 明确设置 sslverify 为 true
• ✅ 添加详细的错误日志记录
• ✅ 记录 HTTP 状态码和响应内容，便于调试
• ✅ 改进错误处理逻辑

新增错误日志:

• API 调用失败时记录错误信息
• HTTP 状态码非 200 时记录状态码和响应内容
• 响应格式异常时记录原始响应

可能的问题原因

根据修复内容，原始代码可能存在以下问题：

1. 缺少 stream 参数: 某些 API 实现要求明确指定是否使用流式响应
2. 缺少 Accept 头: API 可能需要明确的 Accept 头来返回正确格式
3. 中文编码问题: 未使用 JSON_UNESCAPED_UNICODE 可能导致中文字符编码错误
4. 缺少错误日志: 之前无法诊断具体的失败原因

测试方法

方法 1: 使用测试脚本

1. 打开 test-xiaomi-mimo-api.php 文件
2. 将 YOUR_API_KEY_HERE 替换为你的实际 API 密钥
3. 在浏览器中访问: https://your-domain.com/wp-content/themes/argon/test-xiaomi-mimo-api.php
4. 查看测试结果，包括：
   • 基本 API 请求测试
   • 简化请求格式测试
   • 获取模型列表测试
   • cURL 命令示例

方法 2: 在 WordPress 后台测试

1. 进入 WordPress 后台 → Argon 主题设置
2. 找到 "AI 功能" → "API 管理"
3. 添加或编辑小米 Mimo API 配置
4. 点击"测试"按钮
5. 查看测试结果

方法 3: 查看错误日志

如果仍然失败，检查 WordPress 错误日志：

# 查看 PHP 错误日志
tail -f /path/to/php-error.log

# 或者 WordPress debug.log
tail -f /path/to/wp-content/debug.log

错误日志会包含：

• API 调用失败的具体错误信息
• HTTP 状态码
• API 响应内容

小米 Mimo API 规范

端点

• Chat Completions: https://api.mimo.xiaomi.com/v1/chat/completions
• Models: https://api.mimo.xiaomi.com/v1/models

认证

使用 Bearer Token 认证：

Authorization: Bearer YOUR_API_KEY

请求格式

{
  "model": "MiMo-V2-Flash",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "stream": false
}

响应格式

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "MiMo-V2-Flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是小米的 AI 助手..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

支持的模型

根据官方文档，小米 Mimo 目前支持的模型：

• MiMo-V2-Flash (推荐)
  • 309B 总参数，15B 活跃参数
  • 256K 上下文窗口
  • 擅长推理、编码和 Agent 场景
  • 在 SWE-bench 上排名第一

常见问题

Q1: API 密钥在哪里获取？

A: 访问 小米 Mimo 平台 注册并获取 API 密钥。

Q2: API 是否免费？

A: 根据官方信息，MiMo-V2-Flash 目前处于公测阶段，可能提供免费额度。具体请查看官方文档。

Q3: 为什么返回 401 错误？

A: 检查以下几点：

• API 密钥是否正确
• API 密钥是否已激活
• 是否正确设置了 Authorization 头

Q4: 为什么返回 429 错误？

A: 请求频率超过限制，需要：

• 降低请求频率
• 检查是否有配额限制
• 联系小米客服增加配额

Q5: 为什么返回 500 错误？

A: 服务器端错误，可能原因：

• API 服务暂时不可用
• 请求参数格式错误
• 模型名称错误

参考资料

• LiteLLM - Xiaomi MiMo
• Puter.js - Free Xiaomi MiMo API
• OpenRouter - MiMo-V2-Flash
• Hugging Face - MiMo-V2-Flash

后续优化建议

1. 添加重试机制: 对于临时性失败，自动重试 2-3 次
2. 缓存模型列表: 减少对 models 端点的请求
3. 支持流式响应: 对于长文本生成，支持流式输出
4. 添加速率限制: 避免触发 API 限流
5. 监控 API 使用: 记录 API 调用次数和成本

相关文件

• functions.php - 核心函数（包含 API 调用逻辑）
• test-xiaomi-mimo-api.php - 测试脚本
• settings.php - 设置页面（AI 功能配置）

Git 提交

提交信息将包含：

fix: 修复小米 Mimo API 请求失败的问题

- 添加 stream 参数明确设置为非流式响应
- 添加 Accept 请求头确保返回 JSON 格式
- 使用 JSON_UNESCAPED_UNICODE 编码确保中文正确传输
- 添加详细的错误日志记录便于调试
- 改进 SSL 验证设置