OpenAI API 错误：不支持的请求参数 messages

问题描述

在使用 OpenAI 的 gpt-3.5-turbo 模型时，许多开发者会遇到以下错误：

InvalidRequestError: Unrecognized request argument supplied: messages

这个问题通常出现在类似下面的代码中：

response = openai.Completion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": prompt}],  # 错误的原因
    temperature=0,
    max_tokens=20
)

核心问题原因

这个错误的根本原因是 混淆了对话模型（Chat models）和补全模型（Completion models）的 API 调用方式：

1. 对话模型（如 gpt-3.5-turbo）需要使用 聊天补全端点（/v1/chat/completions）
2. 补全模型（如 davinci-002）需要使用 补全端点（/v1/completions）

当开发者尝试在 Completion.create() 方法中使用 messages 参数时，API 会因为参数不匹配而报错。

常见二次错误

如果直接将 messages 替换为 prompt 参数，会收到另一个错误：

InvalidRequestError: [{'role': 'user', 'content': '...'}] is valid under each of... - 'prompt'

这是因为数据格式不兼容 - Chat 模型需要角色消息数组，而旧版 API 需要的是纯文本提示字符串。

解决方案

关键步骤：选择正确的 API 端点

API 端点与模型对应关系

不同模型需要使用不同的 API 端点：

端点	支持的模型
/v1/chat/completions	gpt-4, gpt-4-turbo, gpt-3.5-turbo 等
/v1/completions (旧版)	gpt-3.5-turbo-instruct, babbage-002 等
/v1/assistants	助手 API 相关模型

Python SDK 的不同版本实现方式

重要版本差异

OpenAI Python SDK 在 v1.0.0+ 有重大变化，请根据你使用的版本来选择：

Python SDK < v1.0.0（旧版）

import openai
openai.api_key = "YOUR_API_KEY"

# 使用 ChatCompletion 而不是 Completion
response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "你是有用的助手"},
        {"role": "user", "content": "你好!"}
    ]
)

response_content = response['choices'][0]['message']['content']

Python SDK >= v1.0.0（新版）

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY")

# 新版使用 client.chat.completions.create
for prompt in prompts:
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": prompt}  # 直接传入每个提示
        ],
        temperature=0,
        max_tokens=20
    )
    print(response.choices[0].message.content)

处理多个提示的完整示例

from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def get_chat_responses(prompts: list, model="gpt-3.5-turbo"):
    responses = []
    for prompt in prompts:
        response = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            temperature=0,
            max_tokens=20
        )
        responses.append(response.choices[0].message.content.strip())
    return responses

# 使用示例
prompts = ['你的功能是什么?', '冰淇淋店最好的名字是什么?', '去年英超冠军是谁?']
results = get_chat_responses(prompts)

Node.js 中的正确使用方式

const OpenAI = require("openai");

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function getResponses(prompts) {
  const responses = [];
  for (const prompt of prompts) {
    const completion = await openai.chat.completions.create({
      model: "gpt-3.5-turbo",
      messages: [
        { role: "user", content: prompt }
      ],
      temperature: 0,
      max_tokens: 20
    });
    responses.push(completion.choices[0].message.content.trim());
  }
  return responses;
}

常见错误排查

1. 404 模型不支持错误

端点不匹配错误

如果使用旧版 /v1/completions 端点访问对话模型，会得到：

openai.NotFoundError: 404 Error - Did you mean to use v1/chat/completions?

解决方法：确保使用适合模型的 API 端点

2. SDK 版本升级问题

如果你最近升级过 OpenAI 包，检查当前安装版本：

pip show openai

旧版代码在新 SDK 上运行时需要修改为：

# 旧版：openai.ChatCompletion.create
# 新版：client.chat.completions.create

3. 参数位置错误

注意 messages 必须是非空数组，而不是单个对象：

# 错误 ❌
messages={"role": "user", "content": "Hello"}

# 正确 ✅
messages=[{"role": "user", "content": "Hello"}]

进阶注意事项

1. 历史消息上下文：
   对于连续对话，需维护完整的消息历史：

   messages = [
       {"role": "system", "content": "你是有帮助的助手"},
       {"role": "user", "content": "你好!"},
       {"role": "assistant", "content": "你好！有什么可以帮您？"},
       {"role": "user", "content": "告诉我一个笑话"}
   ]

2. 模型限制：
   gpt-3.5-turbo 的输入限制为 4096 tokens，最新版本如 gpt-4-turbo 支持 128K tokens

3. API 速率限制：
   当处理批量提示时，实现适当的请求间隔：

   import time
   
   for prompt in prompts:
       response = client.chat.completions.create(...)
       time.sleep(0.2)  # 基本速率限制控制

正确实现后的 API 调用将返回结构化响应：

{
  "id": "chatcmpl-123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "你好！我能帮你做什么？"
    },
    "finish_reason": "stop"
  }]
}

理解对话模型和补全模型的区别，正确使用对应方法即可解决 Unrecognized request argument supplied: messages 错误。