LangChain与MiniMax-M2.7结构化输出兼容性问题解析

1. MiniMax-M2.7 与 LangChain ToolStrategy 兼容性问题深度解析

最近在使用 LangChain 构建天气查询 Agent 时，遇到了一个令人困惑的技术问题：当我们将模型从 Claude 切换到 MiniMax-M2.7 后，原本正常工作的结构化输出功能突然失效。这个问题看似简单，实则涉及 LangChain 框架设计、不同大模型的行为差异以及提示工程等多个技术层面的深入理解。本文将详细记录整个问题的排查过程、解决方案以及从中获得的经验教训。

提示：这个问题特别容易发生在使用非主流大模型（如 MiniMax、智谱等）与 LangChain 高级功能（如 ToolStrategy）结合的场景中。如果你也遇到了类似问题，本文提供的解决方案可以直接套用。

2. 技术背景与问题现象

2.1 技术栈配置

我们先来看下这个天气查询 Agent 的技术栈配置：

2.2 预期工作流程

这个天气查询 Agent 的设计逻辑非常简单：

1. 用户询问天气情况（如"What is the weather outside?"）
2. Agent 首先调用位置获取工具确定用户位置
3. 然后调用天气查询工具获取该位置的天气数据
4. 最后以结构化格式返回结果，包含两个字段：
   • punny_response: 带有双关语的趣味回复
   • weather_conditions: 实际的天气状况数据

2.3 问题具体表现

当使用 Claude 模型时，一切工作正常。但切换到 MiniMax-M2.7 后，出现了以下异常现象：

python复制response = agent.invoke({"messages": [{"role": "user", "content": "What is the weather outside?"}]})
print(response['structured_response'])  # 期望输出 ResponseFormat 对象

抛出错误：

code复制KeyError: 'structured_response'

调试发现响应中确实缺少了应有的 structured_response 字段：

python复制print(f"Response keys: {response.keys()}")
# 输出：dict_keys(['messages'])

完整的响应内容显示模型虽然正确调用了业务工具，但最后却用普通文本而非结构化格式返回了结果：

json复制{
  "messages": [
    {"role": "user", "content": "What is the weather outside?"},
    {"role": "assistant", "content": "I'd be happy to check the weather..."},
    {"role": "tool", "content": "Florida", "name": "get_user_location"},
    {"role": "assistant", "content": "...checking weather for Florida..."},
    {"role": "tool", "content": "hot and humid, 85°F", "name": "get_weather_for_location"},
    {"role": "assistant", "content": "🌴 Florida is having a 'sun-derful' day!..."}
  ]
}

3. 问题排查过程

3.1 初步验证：代码是否正确

首先，我们仔细比对了代码与 LangChain 官方文档的示例：

python复制# 官方示例
agent = create_agent(
    model=model,
    system_prompt=SYSTEM_PROMPT,
    tools=[get_user_location, get_weather_for_location],
    context_schema=Context,
    response_format=ToolStrategy(ResponseFormat),
)

# 我们的实现
agent = create_agent(
    model=llm,
    tools=[get_weather_for_location, get_user_location],
    system_prompt=WEATHER_FORECASTER,
    context_schema=WeatherContext,
    response_format=ToolStrategy(ResponseFormat),
)

确认代码完全一致，排除了基础实现错误。

3.2 检查模型配置

检查模型初始化代码：

python复制from app.agent import create_llm

llm = create_llm(
    model="MiniMax-M2.7",
    model_provider="anthropic"
)

print(f'LLM type: {type(llm)}')
# 输出: <class 'langchain_anthropic.chat_models.ChatAnthropic'>

模型创建成功且类型正确，配置没有问题。

3.3 验证 ToolStrategy 行为

深入检查 ToolStrategy 的工作状态：

python复制from langchain.agents.structured_output import ToolStrategy

strategy = ToolStrategy(ResponseFormat)
print(f'schema: {strategy.schema}')
print(f'schema_specs: {strategy.schema_specs}')

输出显示 ToolStrategy 正确地将我们的 ResponseFormat 转换为了工具定义：

code复制schema: <class '__main__.ResponseFormat'>
schema_specs: [_SchemaSpec(
  schema=<class '__main__.ResponseFormat'>,
  name='ResponseFormat',
  description='ResponseFormat(punny_response: str, weather_conditions: str | None = None)',
  json_schema={
    'properties': {
      'punny_response': {'type': 'string'},
      'weather_conditions': {'type': 'string', 'nullable': True}
    },
    'required': ['punny_response']
  }
)]

3.4 关键发现：模型看到的工具列表

通过调试发现，模型实际接收到的工具列表如下：

json复制[
  {
    "name": "get_user_location",
    "description": "Retrieve user's location",
    "input_schema": {"type": "object", ...}
  },
  {
    "name": "get_weather_for_location",
    "description": "Get weather for a city",
    "input_schema": {"type": "object", ...}
  },
  {
    "name": "ResponseFormat",
    "description": "ResponseFormat(punny_response: str, ...)",
    "input_schema": {
      "properties": {
        "punny_response": {"type": "string"},
        "weather_conditions": {"type": "string"}
      },
      "required": ["punny_response"]
    }
  }
]

4. 根因分析与解决方案

4.1 问题本质：模型理解差异

经过深入分析，我们发现问题的核心在于不同模型对 ToolStrategy 的理解差异：

4.2 原始 Prompt 的不足

原始 prompt 存在几个关键缺陷：

python复制PROMPT = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:
- get_weather_for_location: use this to get the weather
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location..."""

主要问题点：

1. 明确说只有"two tools"，但实际提供了三个工具
2. 完全没有提及 ResponseFormat 工具的用途
3. 没有指示模型必须使用 ResponseFormat 返回最终结果

4.3 优化后的 Prompt

我们重构了 prompt，明确指示模型的行为：

python复制PROMPT = """You are an expert weather forecaster, who speaks in puns.

You have access to these tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location
- ResponseFormat: use this to return your final response in structured format

When a user asks you for the weather:
1. First, determine their location (use get_user_location if they mean their current location)
2. Then, get the weather using get_weather_for_location
3. Finally, use the ResponseFormat tool to return your answer with:
   - punny_response: A weather forecast with puns
   - weather_conditions: The actual weather conditions (optional)

IMPORTANT: Always use the ResponseFormat tool to provide your final answer. 
Do not just respond with regular text - you MUST call the ResponseFormat tool."""

关键改进：

1. 明确列出所有三个工具
2. 详细说明 ResponseFormat 的用途和字段含义
3. 分步骤指导模型的操作流程
4. 强调必须使用 ResponseFormat 的强制要求

4.4 验证结果

应用新 prompt 后，成功获得了结构化输出：

python复制print(f"Response keys: {response.keys()}")
# 输出：dict_keys(['messages', 'structured_response'])

print(f"structured_response: {response['structured_response']}")
# 输出：
# ResponseFormat(
#   punny_response="🌴 Weather in Florida...",
#   weather_conditions="hot and humid, 85°F..."
# )

完整输出示例：

code复制=== Structured Response ===
Punny Response: 🌴 Weather in Florida: It's a scorching 85°F with humidity so high...
Weather: hot and humid, 85°F - watch out for hurricanes!

5. 经验总结与通用方案

5.1 核心经验

1. ToolStrategy 的兼容性：不是所有模型都原生支持 ToolStrategy 的隐式约定，特别是未经过专门训练的模型
2. Prompt 的重要性：对于行为复杂的模型，prompt 需要像"操作手册"一样明确具体
3. 官方示例的局限性：官方文档通常以主流模型（如 Claude、GPT）为例，使用其他模型时需要额外适配

5.2 通用解决方案模板

针对类似问题，可以使用以下 prompt 模板：

python复制PROMPT_TEMPLATE = """
You are [角色描述].

You have access to these tools:

- tool_1: [用途说明]
- tool_2: [用途说明]
- ResponseFormat: use this to return your final response in structured format

When a user asks you to [任务描述]:
1. First, [步骤1说明]
2. Then, [步骤2说明]
3. Finally, use the ResponseFormat tool to return your answer

IMPORTANT: Always use the ResponseFormat tool to provide your final answer.
Do not just respond with regular text - you MUST call the ResponseFormat tool.
"""

5.3 替代方案

如果 prompt 优化后问题仍然存在，可以考虑：

1. 使用模型原生 SDK：如 langchain-minimax 等专门适配的库
2. 手动解析输出：放弃 ToolStrategy，直接从消息中提取结构化数据
3. 模型切换：换回 Claude/GPT 等完全兼容的模型

6. 完整实现代码

6.1 主程序 (main.py)

python复制"""Weather Forecaster Agent 主程序"""

import os
from dataclasses import dataclass
from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy
from app.agent import create_llm
from app.tools import get_weather_for_location, get_user_location, WeatherContext
from prompts import WEATHER_FORECASTER

load_dotenv()

@dataclass
class ResponseFormat:
    """响应数据结构定义"""
    punny_response: str
    weather_conditions: str | None = None

def main():
    """运行天气查询 Agent"""
    # 配置初始化
    model = os.getenv("MODEL", "MiniMax-M2.7")
    model_provider = os.getenv("MODEL_PROVIDER", "anthropic")
    llm = create_llm(model=model, model_provider=model_provider)

    # 创建 Agent
    agent = create_agent(
        model=llm,
        tools=[get_weather_for_location, get_user_location],
        system_prompt=WEATHER_FORECASTER,
        context_schema=WeatherContext,
        response_format=ToolStrategy(ResponseFormat),
    )

    # 执行查询
    response = agent.invoke(
        {"messages": [{"role": "user", "content": "What is the weather outside?"}]}
    )

    # 输出结果
    print("\n=== Structured Response ===")
    print(f"Punny Response: {response['structured_response'].punny_response}")
    if response['structured_response'].weather_conditions:
        print(f"Weather: {response['structured_response'].weather_conditions}")

if __name__ == "__main__":
    main()

6.2 提示词模板 (prompts/weather.py)

python复制"""Weather Forecaster 提示词定义"""

PROMPT = """You are an expert weather forecaster, who speaks in puns.

You have access to these tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location
- ResponseFormat: use this to return your final response in structured format

When a user asks you for the weather:
1. First, determine their location (use get_user_location if needed)
2. Then, get the weather using get_weather_for_location
3. Finally, use the ResponseFormat tool to return your answer with:
   - punny_response: A weather forecast with puns
   - weather_conditions: The actual weather conditions (optional)

IMPORTANT: Always use the ResponseFormat tool to provide your final answer. 
Do not just respond with regular text - you MUST call the ResponseFormat tool."""

7. 扩展思考与最佳实践

7.1 模型兼容性检查清单

在使用新模型与 LangChain 高级功能时，建议检查以下事项：

1. 工具调用能力：模型是否支持函数/工具调用
2. 结构化输出：是否理解特殊工具（如 ResponseFormat）的用途
3. Prompt 适配性：是否需要更明确的指令才能正确工作
4. SDK 支持：是否有官方或社区维护的专门集成

7.2 调试技巧

当遇到类似问题时，可以采用以下调试方法：

1. 打印完整工具列表：确认模型接收到的工具定义是否符合预期
2. 检查模型输出：查看模型的中间响应，了解其决策过程
3. 简化测试：用最小化示例复现问题，排除其他干扰因素
4. 对比测试：使用不同模型进行对比，快速定位问题边界

7.3 性能优化建议

1. 缓存工具定义：避免每次调用都重新生成工具 schema
2. 批量处理：对多个查询使用相同的 Agent 实例
3. 超时控制：为工具调用设置合理的超时时间
4. 错误处理：完善异常捕获和重试机制