小米AI音箱集成本地LLM服务404错误排查指南

小米AI音箱集成本地LLM服务404错误排查指南

mi-gpt 🏠 将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手。 项目地址: https://gitcode.com/gh_mirrors/mi/mi-gpt

在使用小米AI音箱(MiGPT项目)对接本地LLM服务时，开发者可能会遇到"404 page not found"的错误提示。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象分析

当配置小米AI音箱连接本地LLM服务时，系统返回404错误，表明请求的资源不存在。典型错误日志显示AI客户端尝试访问API端点失败，核心报错信息为"NotFoundError: 404 404 page not found"。

根本原因

这种错误通常由以下两种情况导致：

1. API端点不兼容：本地LLM服务未实现与AI兼容的API接口格式。AI客户端期望的API路径结构为/v1/chat/completions，而许多本地LLM服务可能使用不同的API路径。

2. 基础URL配置问题：配置的AI_BASE_URL未正确生效，导致请求被发送到错误的地址。特别是在容器化部署时，网络配置可能导致URL解析异常。

详细解决方案

方案一：验证API兼容性

首先确认本地LLM服务是否实现了AI兼容的API。以Ollama为例，需要确保：

1. 服务端已启用AI兼容模式
2. API路径正确配置为/v1/chat/completions
3. 请求/响应格式符合AI规范

可以通过以下命令测试API是否可用：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'

方案二：调试配置参数

1. 启用MiGPT的调试模式，查看实际发出的请求URL
2. 检查环境变量AI_BASE_URL是否被正确加载
3. 验证网络连通性，确保音箱设备可以访问LLM服务主机
4. 检查端口映射，特别是当服务运行在Docker容器中时

方案三：适配层解决方案

如果本地LLM服务确实不兼容AI API，可以考虑以下方法：

1. 使用API适配层(如llama.cpp提供的AI兼容服务器)
2. 修改MiGPT代码，适配本地LLM的API格式
3. 使用反向代理重写API路径

预防措施

为避免类似问题再次发生，建议：

1. 在配置前先使用Postman或curl测试API可用性
2. 在MiGPT配置中使用完整的API路径，如http://host:port/v1
3. 保持MiGPT和LLM服务版本的兼容性
4. 记录详细的请求日志以便排查

通过以上方法，开发者应该能够解决小米AI音箱对接本地LLM服务时的404错误问题，实现稳定的语音交互功能。

mi-gpt 🏠 将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手。 项目地址: https://gitcode.com/gh_mirrors/mi/mi-gpt