Messages Array跨LLM API适配全攻略

作者：浪迹天涯

为什么同一个Messages Array不能直接用在所有模型上？

在使用OpenAI Chat API时，你可能对这样的结构很熟悉：

[
  {"role": "system", "content": "你是一位友善的家庭顾问。"},
  {"role": "user", "content": "谁该洗碗？"}
]

在GPT-4o上，这个格式可以直接使用。但切换到Claude、LLaMA、Gemini、DeepSeek、Grok等模型时，往往会出现报错或输出异常。

原因在于，不同LLM API的消息格式各不相同，同一个Messages Array不能直接通用，需要根据目标API的要求进行适配。

不同LLM API的消息格式差异

模型/API	System字段位置	消息结构	历史记录处理方式	工具调用支持	特殊点	最大上下文长度	是否多模态	是否支持JSON模式
OpenAI	messages数组中	system/user/assistant	支持，由开发者拼接完整对话	支持（functions/tools）	最通用的接口格式，兼容性强	GPT-4-turbo：128k	是	支持（`response_format: json`）
Claude	单独的system字段	messages中仅user/assistant	支持，由开发者提供完整对话	不支持	system单独传	Claude Sonnet 4：200k	是	支持
Gemini	prompt中或系统设置	contents/queries数组	不自动保存，需开发者重构对话	部分支持（如function calling）	Google 风格API，结构差异大	Gemini 2.5 Pro：1M+	是	部分支持
DeepSeek	兼容OpenAI格式	messages数组，含system等角色	支持	不支持	支持JSON模式输出优化	DeepSeek-V3：66k	是	支持
Grok 4	兼容OpenAI格式	system /user/assistant	支持	支持（如网页搜索等功能）	输出更简洁偏实用风格	256K	是	部分支持

三种通用适配方法

方法一：自定义Python脚本

通过自定义脚本，将标准的Messages Array转换为不同API所需的格式：

优点：实现简单，可控性强，适合小型项目

缺点：需要自行维护适配逻辑

方法二：使用LangChain框架

LangChain是一个开源的大语言模型应用开发框架，支持多模型统一调用，简化了提示构建、上下文管理和工具集成等流程，适合多模型测试：

优点：支持多模型快速切换，减少格式转换工作量

缺点：依赖更多库，配置稍复杂

方法三：API Wrapper

API Wrapper是一种接口适配工具，可以将不同LLM API的输入输出转换为统一格式，例如：

- vLLM：可部署LLaMA等模型，支持OpenAI风格调用
- LM Studio：本地运行模型，兼容OpenAI格式
- llama.cpp + openai server：轻量本地方案

优点：一次适配，多处使用

缺点：需要部署与维护环境

实战案例：两步推理（CoT）

假设我们希望先分析“谁洗碗”，再提出方案。

第一步：分析情况

{
  "model": "grok-4",
  "messages": [
    {"role": "system", "content": "你是一位家庭顾问，请用JSON返回。"},
    {"role": "user", "content": "分析家庭的洗碗安排（时间表、喜好）。"}
  ]
}

输出

{
  "分析": {
    "时间表": "A晚归，B早回家",
    "喜好": "A不喜欢洗碗，B无所谓"
  }
}

第二步：基于上一步提出方案

{
  "model": "grok-4",
  "messages": [
    {"role": "system", "content": "你是一位家庭顾问，请用JSON返回。"},
    {"role": "assistant", "content": "{\"分析\": {\"时间表\": \"A晚归，B早回家\", \"喜好\": \"A不喜欢洗碗，B无所谓\"}}"},
    {"role": "user", "content": "基于分析提出公平的洗碗方案"}
  ]
}

输出

{
  "方案": "工作日B洗碗，周末轮流"
}

总结

本文介绍了不同LLM API在Messages Array格式上的差异，以及三种常见的适配方法。

初学者可优先使用Python脚本适配法，简单灵活。

项目规模扩大或需支持多模型时，可考虑LangChain或API Wrapper。

除了格式，还需注意历史记录、工具调用、JSON输出等功能差异。

Messages Array跨LLM API适配全攻略

为什么同一个Messages Array不能直接用在所有模型上？#

不同LLM API的消息格式差异#

三种通用适配方法#

方法一：自定义Python脚本#

方法二：使用LangChain框架#

方法三：API Wrapper#

实战案例：两步推理（CoT）#

总结#