迁移指南

从 OpenAI 或 Anthropic Claude 迁移到 Gemini 时，重点不是简单替换模型名，而是调整接口路径、鉴权方式、消息结构、系统指令、函数调用和结构化输出配置。

从 OpenAI 迁移到 Gemini

OpenAI	Gemini
/v1/responses 或 /v1/chat/completions	/v1beta/models/{model}:generateContent
Authorization: Bearer	key 查询参数或服务端密钥配置
instructions / messages[].role = system	systemInstruction
input / messages	contents
content	parts
max_tokens / max_output_tokens	generationConfig.maxOutputTokens
tools / function	tools.functionDeclarations
JSON schema 输出	responseMimeType + responseJsonSchema

从 Claude 迁移到 Gemini

Anthropic Claude	Gemini
/v1/messages	/v1beta/models/{model}:generateContent
x-api-key	key 查询参数或服务端密钥配置
顶层 system	systemInstruction
messages	contents
content 内容块	parts 内容块
tool_use / tool_result	functionCall / functionResponse
max_tokens	generationConfig.maxOutputTokens

Messages 与 contents 差异

Gemini 使用 contents 表示对话历史，每条内容由 parts 组成。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Introduce Gemini" }
      ]
    }
  ]
}

systemInstruction 差异

Gemini 的系统级指令放在 systemInstruction 中。

{
  "systemInstruction": {
    "parts": [
      { "text": "You are a customer support assistant" }
    ]
  },
  "contents": [
    {
      "parts": [
        { "text": "Draft a reply for me" }
      ]
    }
  ]
}

generationConfig 差异

输出长度、随机性、停止序列和结构化格式通常放入 generationConfig。

{
  "generationConfig": {
    "temperature": 0.2,
    "maxOutputTokens": 1024,
    "responseMimeType": "application/json"
  }
}

函数调用差异

Gemini 使用 functionDeclarations 定义函数，模型返回 functionCall，服务端执行后回填 functionResponse。

迁移时需要检查：

• 函数定义字段名
• 参数 schema 类型写法
• 函数调用结果如何回填
• 多函数并发或顺序调用逻辑
• 写操作权限和确认流程

流式输出差异

Gemini 使用 streamGenerateContent 做流式输出。前端如果已经适配其他供应商的流式事件，迁移时建议在服务端统一封装为自己的增量格式。

迁移检查清单

• 请求地址是否改为 https://xikapi.com/v1beta/models/{model}:generateContent
• 模型名是否存在于 Xikapi 后台
• API Key 是否按 Gemini 兼容方式传入
• 系统提示词是否改为 systemInstruction
• 消息内容是否改为 contents[].parts
• 是否显式设置 generationConfig.maxOutputTokens
• 图像输入是否改为 inlineData
• 函数调用是否适配 functionCall 和 functionResponse
• 结构化输出是否使用 responseMimeType 或 responseJsonSchema