【20260502】Hermes 融合 MiniMax Token Plan MCP 实现图片理解

最近在折腾 Hermes 的图片理解能力，记录一下解决过程。

背景

Hermes 的 auxiliary.vision 配置可以指定图片理解的后端，但当主渠道（如 MiniMax 的 OpenAI 兼容端点）失败时，没有自动 fallback 机制。

而 MiniMax 的 MCP Server（minimax-coding-plan-mcp）提供了独立的 understand_image 工具，但 Hermes 默认不会用它做图片理解。

目标

当 Auxiliary Vision 失败时，自动启用 mcp_minimax_understand_image 作为 fallback。

实现思路

在 vision_tools.py 的 vision_analyze_tool 函数中，捕获 Auxiliary Vision 的异常后，尝试通过 MCP server 直接调用 understand_image 工具。

关键代码

核心逻辑：

1. 通过 tools.mcp_tool 的 _servers 获取已连接的 MCP 服务器


2. 找到 MiniMax 服务器，获取其 session


3. 使用 _run_on_mcp_loop 在 MCP 事件循环中执行 call_tool


4. 解析返回的 CallToolResult，提取图片分析文本

# 使用 _run_on_mcp_loop 执行异步 MCP 调用                                                                                                                                                                                                                    

from tools.mcp_tool import _run_on_mcp_loop                      

                                   

async def _mcp_call():

    async with server._rpc_lock:

        result = await server.session.call_tool(mcp_tool_name, arguments={                                                                                                                                                                                   

            "prompt": comprehensive_prompt or "描述这张图片的内容",

            "image_source": str(temp_image_path)                                                                                                                                                                                                             

        })                                                       

        return result              



result = _run_on_mcp_loop(_mcp_call(), timeout=60.0)                                                                                                                                                                                                         

 

踩坑记录                                                                                                                                                                                                                                                     

                                                                 

1. 直接 await 会死锁 - MCP session 运行在独立事件循环，直接 await 会卡住                                                                                                                                                                                     

2. _servers 可能为空 - 需要 gateway 正常运行后才能获取到

3. session.call_tool 返回 CallToolResult - 需要手动解析 .content 和 .isError                                                                                                                                                                                 

                                                                                                                                                                                                                                                             

验证结果                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                             

[Lark] 图片消息                                                  

    ↓                                                                                                                                                                                                                                                        

Auxiliary Vision 失败 (gpt-4o-mini 模型不支持)

    ↓                                                                                                                                                                                                                                                        

MCP Fallback 触发                                                

    ↓                              

mcp_minimax_understand_image 成功分析图片

                                                                                                                                                                                                                                                             

图片分析结果正常返回，描述了自动驾驶车辆和智能城市基础设施。                                                                                                                                                                                                 

                                                                                                                                                                                                                                                             

配置文件                                                                                                                                                                                                                                                     

                                                                 

auxiliary:                         

  vision:

    provider: openai

    base_url: https://api.minimaxi.com/v1

    api_key: sk-cp-xxx

                                                                                                                                                                                                                                                             

mcp_servers:

  MiniMax:                                                                                                                                                                                                                                                   

    command: uvx                                                 

    args:                          

    - minimax-coding-plan-mcp

    - -y

    env:

      MINIMAX_API_KEY: ${MINIMAX_TOKEN_PLAN_KEY}

      MINIMAX_API_HOST: https://api.minimaxi.com                                                                                                                                                                                                             

 

总结                                                                                                                                                                                                                                                         

                                                                 

Hermes 的 MCP 集成比较灵活，可以通过 _run_on_mcp_loop 在工具处理器中调用其他 MCP 工具。关键是理解 MCP 使用独立事件循环，不能直接 await。                                                                                                                     

 

---                                                                                                                                                                                                                                                          欢迎佬友们交流，给我一些新的想法💡方案