协议自动转换 Google Gemini示例

协议自动转换 java-openai 的统一大模型调用能力

在真实的工程环境中，对接大模型的最大挑战从来不只是“调用 API”，而是跨平台协议差异带来的长期维护成本：

OpenAI、Google Gemini、Anthropic Claude 的请求结构完全不同
system prompt、messages、roles、token usage 命名不一致
流式返回（Streaming）实现方式各异
多模态（图片）字段与编码方式差异巨大
平台升级频繁，业务代码被迫跟着修改

java-openai 的核心价值之一，就是通过协议自动转换（Automatic Protocol Translation），彻底将业务代码与底层模型协议解耦。

业务侧只需要面对一套统一抽象：

UniChatRequest 作为唯一输入
UniChatResponse 作为唯一输出
UniChatClient 作为统一入口

底层根据平台与模型，自动完成协议翻译与结果归一。

一、设计目标

java-openai 在设计之初就明确了几个原则：

业务只表达意图，不关心协议
协议差异集中在适配层，不扩散到业务
同一业务逻辑可无缝切换模型平台
请求、流式、图片、多模态统一抽象
原始请求与响应可追溯，便于调试与审计

二、统一抽象层：业务只面向 UniChatRequest

无论目标平台是 OpenAI、Google Gemini、Claude，还是 OpenRouter、Groq 等聚合平台，业务侧始终只构造同一种请求对象。

最小使用模型

PlatformInput platformInput =new PlatformInput(ModelPlatformName.GOOGLE, GoogleModels.GEMINI_2_5_FLASH);
UniChatRequest request = new UniChatRequest(platformInput);
request.setSystemPrompt("...");
request.setMessages(List.of(
    UniChatMessage.buildUser("Input: 什么是线性齐次递推\nSummary:")
));

UniChatResponse response = UniChatClient.generate(request);
String content = response.getMessage().getContent();

在这段代码中：

没有 Gemini 的 system_instruction
没有 contents / parts
没有任何平台私有字段

业务代码只表达“我要用哪个模型 + 我要说什么”。

三、协议自动转换的本质

协议自动转换包含两个方向：

1. 请求翻译（UniChatRequest → 平台原生协议）

以 Google Gemini 为例。

业务侧表达

setSystemPrompt(...)
setMessages(List<UniChatMessage>)

自动转换后（Gemini 原生请求）

{
  "system_instruction": {
    "parts": [
      { "text": "..." }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Input: 什么是线性齐次递推\nSummary:" }
      ]
    }
  ]
}

映射关系本质上是：

统一抽象	Gemini
systemPrompt	system_instruction.parts[].text
UniChatMessage(role=user)	contents[].role = user
message.content	parts[].text

业务不需要了解这些规则，它们全部封装在平台适配层中。

2. 响应归一（平台原生响应 → UniChatResponse）

完整格式

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "线性齐次递推"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 206,
    "candidatesTokenCount": 5,
    "totalTokenCount": 448,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 206
      }
    ],
    "thoughtsTokenCount": 237
  },
  "modelVersion": "gemini-2.5-flash",
  "responseId": "s3F3aZrbCs-i_uMPloabcA"
}

Gemini 返回内容位于：

candidates[0].content.parts[0].text

但业务统一通过：

response.getMessage().getContent();

同时：

token 使用情况 → UniChatResponse.usage
实际模型版本 → UniChatResponse.model
原始 JSON → UniChatResponse.rawData（用于调试）

四、自动转换覆盖的能力范围

1. System Prompt 统一

不同平台对 system prompt 的支持方式不同：

OpenAI：system role
Gemini：system_instruction
Claude：system

业务侧统一使用：

request.setSystemPrompt(...)
request.setUseSystemPrompt(true);
request.setCacheSystemPrompt(true);

是否缓存、是否发送，由统一逻辑控制。

2. 消息结构统一

业务侧统一使用：

List<UniChatMessage>

底层自动映射为：

OpenAI messages
Gemini contents / parts
Claude content blocks

3. 流式输出统一

业务侧：

UniChatClient.stream(request, listener);

在回调中统一使用：

chatResponse.getDelta().getContent();

底层自动处理：

OpenAI delta
Gemini streaming parts
Claude stream blocks

业务完全不关心差异。

4. 图片与多模态统一

图片统一抽象为：

ChatImageFile

并作为 UniChatMessage.files 的一部分参与对话。

底层自动转换为：

Gemini inline_data
OpenAI image_url / base64
Claude vision blocks

业务侧只需选择支持视觉能力的模型。

5. Usage 与引用信息统一

不同平台返回的 token 统计字段不同：

Gemini：usageMetadata
OpenAI：usage
Claude：字段分散

最终统一归并到：

UniChatResponse.usage

可用于成本统计、限额控制与审计。

五、平台无关的业务架构实践

1. 平台切换只改 PlatformInput

new PlatformInput(ModelPlatformName.GOOGLE, ...)
new PlatformInput(ModelPlatformName.OPENAI, ...)
new PlatformInput(ModelPlatformName.CLAUDE, ...)

业务逻辑完全不变。

这使得以下场景非常容易实现：

多模型 A/B 测试
成本驱动路由
平台不可用时自动降级
按 domain / tenant 路由不同模型

2. 统一入口做重试、告警、治理

推荐将所有调用集中到类似 UniPredictService 的统一入口：

自动重试
捕获 GenerateException
上报原始 request / response
统一告警与监控

由于协议已自动转换，异常中拿到的 JSON 就是平台真实收到的请求，定位问题非常直接。

package com.litongjava.manim.proxy;

import com.litongjava.chat.UniChatClient;
import com.litongjava.chat.UniChatRequest;
import com.litongjava.chat.UniChatResponse;
import com.litongjava.exception.GenerateException;
import com.litongjava.manim.utils.LarkBotUtils;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class UniPredictService {

  public UniChatResponse generate(UniChatRequest uniChatRequest) {
    for (int i = 0; i < 10; i++) {
      try {
        return UniChatClient.generate(uniChatRequest);
      } catch (GenerateException e) {
        log.error(e.getMessage(), e);
        String requestJson = e.getRequestBody();
        String responseBody = e.getResponseBody();
        String name = "tio-boot";
        String warningName = "LlmOcrService Failed to request ExchangeToken:" + uniChatRequest.getTaskName();
        LarkBotUtils.sendExcpetion(name, warningName, requestJson, e.getStatusCode(), responseBody, e);
      }
    }
    return null;
  }
}

六、调试与可观测性

在协议自动转换体系中，调试能力尤为重要。

1. 请求级别调试

GenerateException.getRequestBody() → 已转换完成的原始平台请求 JSON

2. 响应级别调试

UniChatResponse.rawData → 平台原始返回内容

这让“平台不兼容”“字段不被识别”“协议升级导致失败”等问题，都可以在一次请求中定位清楚。

七、自动转换的边界说明

需要明确几点边界条件：

统一字段 ≠ 所有模型都支持（例如图片、搜索、思考能力）
是否生效取决于目标平台与模型能力
domain / groupId / taskId / taskName不会发送给模型，仅用于业务标识与治理

八、完整的代码

  @Test
  public void testChinese() {
    EnvUtils.load();
    MvPromptService mvPromptService = Aop.get(MvPromptService.class);
    MvSummaryQuestionService mvSummaryQuestionService = Aop.get(MvSummaryQuestionService.class);
    PlatformInput platformInput = new PlatformInput(ModelPlatformName.GOOGLE, GoogleModels.GEMINI_2_5_FLASH);
    String systemPrompt = mvPromptService.summary_question_prompt();
    String question = "什么是线性齐次递推";
    String languageRegion = "Chinese (China)";
    String summary = mvSummaryQuestionService.summary(platformInput, systemPrompt, question, languageRegion);
    System.out.println(summary);
  }

import java.util.ArrayList;
import java.util.List;

import com.litongjava.chat.PlatformInput;
import com.litongjava.chat.UniChatMessage;
import com.litongjava.chat.UniChatRequest;
import com.litongjava.chat.UniChatResponse;
import com.litongjava.consts.ModelPlatformName;
import com.litongjava.exchangetoken.ExchangetokenModels;
import com.litongjava.jfinal.aop.Aop;
import com.litongjava.manim.proxy.UniPredictService;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class MvSummaryQuestionService {

  private MvPromptService mvPromptService = Aop.get(MvPromptService.class);

  public String summary(PlatformInput platformInput, String systemPrompt, String question, String languageRegion) {
    // 2. 调用大模型进行推理
    String prompt = "Input: " + question + ". \nSummary:";
    UniChatMessage user = UniChatMessage.buildUser(prompt);
    List<UniChatMessage> messages = new ArrayList<>();
    messages.add(user);
    messages.add(UniChatMessage.buildUser("The generated content must use the " + languageRegion));

    UniChatRequest uniChatRequest = new UniChatRequest(platformInput);
    uniChatRequest.setSystemPrompt(systemPrompt);
    uniChatRequest.setCacheSystemPrompt(true);
    uniChatRequest.setMessages(messages);

    //uniChatRequest.setApiPrefixUrl("http://127.0.0.1:8080/google/v1beta/models");

    String content = null;
    UniChatResponse uniChatResponse = Aop.get(UniPredictService.class).generate(uniChatRequest);

    content = uniChatResponse.getMessage().getContent();

    // 3. 判断结果并返回
    if ("not_needed".equals(content)) {
      return question;
    }
    return content;
  }
}

九、总结

java-openai 的协议自动转换能力，本质上是：

用一套稳定的业务抽象
吸收所有不稳定的模型协议变化

它带来的直接收益包括：

业务代码平台无关
prompt 与消息结构可复用
流式、多模态统一处理
调试、监控、告警高度一致
模型升级与切换成本极低

在多模型时代，这种设计不是“锦上添花”，而是长期可维护系统的基础设施能力。