

## 前言

最近在使用 Roo Code、Cursor 等 AI 编程工具时，尝试接入腾讯混元大模型。混元提供了 OpenAI 兼容的 API 接口，理论上可以直接替换 OpenAI 模型使用。但在实际使用中，频繁遇到 `400 Bad Request` 错误，提示 `messages 以 user（tool）提问结束`。

经过深入排查，发现这是混元大模型与 OpenAI API 规范之间的差异导致的。本文将详细介绍问题的根源以及如何通过 LiteLLM 代理优雅地解决这个问题。

## 问题分析

### 错误现象

在 Roo Code 中调用混元模型时，控制台频繁出现以下错误：

```
OpenAIException - messages 以 user（tool）提问结束, tool 可以连续出现多次
```

### 根本原因

通过抓包分析请求，发现问题出在消息格式上。混元大模型对 `messages` 数组有以下特殊要求：

1. **消息必须以 `user` 或 `tool` 角色结尾**：混元不允许对话以 `assistant` 角色结束
2. **工具调用序列要求**：当 `tool` 消息后紧跟 `user` 消息时，中间需要有一个 `assistant` 消息作为过渡
3. **不支持的参数**：`parallel_tool_calls`、`reasoning_effort` 等 OpenAI 特有参数会导致请求失败
4. **工具定义差异**：混元不支持 `function.strict` 等字段

而 Roo Code 等 AI 编程工具生成的请求，通常会以 `assistant` 角色结尾（因为模型刚回复完），这就触发了混元的校验错误。

## 解决方案

### 技术选型

考虑到需要在请求发送到混元之前进行拦截和修改，我选择使用 **LiteLLM** 作为代理层。LiteLLM 是一个优秀的 LLM 代理工具，支持：

- 统一的 API 接口，兼容 100+ 种 LLM
- 自定义回调（CustomLogger），可以在请求前后进行修改
- 自动参数过滤和转换

### 核心实现

创建一个 `HunyuanMessageFixer` 类，继承自 `CustomLogger`，在 `async_pre_call_hook` 中拦截并修正请求：

```python
import copy
import litellm
from litellm.integrations.custom_logger import CustomLogger

class HunyuanMessageFixer(CustomLogger):
    """
    LiteLLM 自定义回调：在请求发送到混元之前修正消息格式
    """
    
    def _fix_messages(self, messages: list) -> list:
        """修正消息列表，使其兼容混元大模型"""
        if not messages:
            return messages
        
        messages = copy.deepcopy(messages)
        fixed_messages = []
        
        for i, msg in enumerate(messages):
            role = msg.get("role")
            
            # 确保 assistant 消息有 content
            if role == "assistant":
                if not msg.get("content") or not msg.get("content").strip():
                    if msg.get("tool_calls"):
                        tool_names = [tc["function"].get("name", "unknown") 
                                    for tc in msg.get("tool_calls", []) 
                                    if isinstance(tc, dict) and "function" in tc]
                        msg["content"] = f"我将调用工具：{', '.join(tool_names)}"
                    else:
                        msg["content"] = "..."
            
            fixed_messages.append(msg)
            
            # 在 tool → user 之间插入过渡 assistant 消息
            if role == "tool" and i + 1 < len(messages):
                next_msg = messages[i + 1]
                if next_msg.get("role") == "user":
                    transition_msg = {
                        "role": "assistant",
                        "content": "工具返回了结果。"
                    }
                    fixed_messages.append(transition_msg)
        
        # 确保消息以 user 或 tool 结尾
        if fixed_messages:
            last_role = fixed_messages[-1].get("role")
            if last_role == "assistant":
                fixed_messages.append({"role": "user", "content": "请继续。"})
        
        return fixed_messages
    
    async def async_pre_call_hook(self, user_api_key_dict, cache, data: dict, call_type: str):
        """在 LLM 调用之前修改请求数据"""
        if call_type in ("completion", "acompletion"):
            # 修正消息
            if "messages" in data:
                data["messages"] = self._fix_messages(data["messages"])
            
            # 移除不支持的参数
            for param in ["parallel_tool_calls", "reasoning_effort"]:
                data.pop(param, None)
            
            # 清理 tools 中的 strict 字段
            if "tools" in data:
                for tool in data.get("tools", []):
                    if isinstance(tool, dict) and "function" in tool:
                        tool["function"].pop("strict", None)
        
        return data
```

### 配置文件

创建 `config.yaml` 配置 LiteLLM：

```yaml
model_list:
  - model_name: hunyuan-fixed
    litellm_params:
      model: openai/hunyuan-2.0-instruct-20251111
      api_key: your-api-key-here
      api_base: https://api.hunyuan.cloud.tencent.com/v1

litellm_settings:
  modify_params: true
  drop_params: true
```

### 启动代理

```python
if __name__ == "__main__":
    import uvicorn
    import asyncio
    from litellm.proxy.proxy_server import app, initialize
    
    # 注册回调
    hunyuan_fixer = HunyuanMessageFixer()
    litellm.drop_params = True
    litellm.callbacks = [hunyuan_fixer]
    
    async def start_server():
        await initialize(config="config.yaml")
        config = uvicorn.Config(app, host="0.0.0.0", port=4000, log_level="info")
        server = uvicorn.Server(config)
        await server.serve()
    
    asyncio.run(start_server())
```

## 部署指南

### 1. 环境准备

```bash
# 创建项目目录
mkdir hunyuan-proxy && cd hunyuan-proxy

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install litellm uvicorn
```

### 2. 配置文件

将上述 `proxy_handler.py` 和 `config.yaml` 放入项目目录，并修改 `config.yaml` 中的 API Key。

### 3. 运行服务

```bash
python proxy_handler.py
```

服务将在 `http://localhost:4000` 启动。

### 4. 配置为系统服务（可选）

使用 Supervisor 管理服务，实现开机自启动：

```bash
# macOS 安装 supervisor
brew install supervisor
brew services start supervisor
```

创建配置文件 `/opt/homebrew/etc/supervisor.d/litellm-proxy.ini`：

```ini
[program:litellm-proxy]
command=/path/to/.venv/bin/python /path/to/proxy_handler.py
directory=/path/to/hunyuan-proxy
autostart=true
autorestart=true
stdout_logfile=/path/to/logs/litellm-proxy.log
```

## 在 AI 工具中使用

以 Roo Code 为例，配置 API：

| 配置项 | 值 |
|--------|-----|
| Base URL | `http://localhost:4000/v1` |
| Model | `hunyuan-fixed` |
| API Key | 任意值 |

配置完成后，Roo Code 的请求会先经过代理，自动修正消息格式后再转发到混元 API。

## 效果验证

部署代理后，之前频繁出现的 `400 Bad Request` 错误完全消失，混元大模型可以正常处理 Roo Code 发送的各种请求，包括：

- 普通对话
- 工具调用（读取文件、执行命令等）
- 多轮工具调用

## 总结

本文介绍了一种通过 LiteLLM 代理解决混元大模型与 AI 编程工具兼容性问题的方法。核心思路是：

1. 使用 LiteLLM 的 `CustomLogger` 机制拦截请求
2. 在请求发送到混元之前，自动修正消息格式
3. 移除混元不支持的参数和字段

这种方案的优势是**对客户端透明**，无需修改 Roo Code 等工具的代码，只需配置代理地址即可。

完整代码已开源：[https://github.com/floatin/hunyuan_proxy](https://github.com/floatin/hunyuan_proxy)

---

> 作者：怀民
> 
> 如有问题欢迎在评论区交流讨论。

最近在使用 Roo Code、Cursor 等 AI 编程工具时，尝试接入腾讯混元大模型。混元提供了 OpenAI 兼容的 API 接口，理论上可以直接替换 OpenAI 模型使用。但在实际使用中，频繁遇到 400 Bad Request 错误，提示 messages 以 user（tool）提问结束。

使用 LiteLLM 解决腾讯混元大模型与 AI 编程工具的兼容性问题

本文介绍如何通过 LiteLLM 代理解决腾讯混元大模型与 Roo Code 等 AI 编程工具的兼容性问题，自动修正消息格式，实现无缝接入混元模型。附完整代码和部署指南。

数据库

解决腾讯混元大模型与AI编程工具兼容性问题：通过LiteLLM代理自动修正消息格式，消除400错误，实现无缝对接OpenAI兼容API。详细方案包含代码实现与部署指南，助力开发者高效使用混元模型。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

使用 LiteLLM 解决腾讯混元大模型与 AI 编程工具的兼容性问题-腾讯云开发者社区-腾讯云

使用 LiteLLM 解决腾讯混元大模型与 AI 编程工具的兼容性问题

使用 LiteLLM 解决腾讯混元大模型与 AI 编程工具的兼容性问题

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐