从零开始学Java调用Gemma-3-12B-IT API实战教程-开发者社区

从零开始学Java调用Gemma-3-12B-IT API实战教程

你是不是对最近很火的大语言模型感兴趣，想在自己的Java项目里用起来，但又觉得那些复杂的配置和调用方式让人头大？别担心，今天咱们就来手把手搞定这件事。

Gemma-3-12B-IT是一个功能强大的开源大模型，能帮你做文本生成、对话、分析等各种智能任务。作为Java开发者，我们不需要去研究模型内部那些复杂的算法，只需要学会怎么通过API和它“对话”就行。这就像你点外卖，不需要知道厨房怎么做菜，只需要会下单和取餐。

这篇教程就是为你准备的。我会假设你有一些Java基础，知道怎么创建类和运行程序，但完全没接触过AI模型调用也没关系。咱们从最基础的HTTP请求开始，一步步搭建一个能稳定、高效调用Gemma模型的Java工具。学完之后，你就能轻松地让模型帮你写文案、分析情感，或者进行智能对话了。

1. 环境准备与项目搭建

工欲善其事，必先利其器。在开始写代码之前，咱们先把“厨房”收拾好。

首先，你需要一个可以访问Gemma模型API的环境。通常，你需要在一个提供了该模型服务的平台上获取一个API访问密钥（API Key）和一个基础的请求地址（Base URL）。这个步骤因平台而异，你需要根据所选服务商的文档来完成。拿到这两样东西后，记下来，后面会用到。

接下来，我们创建一个新的Java项目。你可以使用任何你熟悉的IDE，比如IntelliJ IDEA、Eclipse，或者直接用命令行和Maven。这里我推荐使用Maven来管理依赖，这样最省心。

在你的项目根目录下，找到或创建pom.xml文件，我们需要添加几个关键的依赖库：

<dependencies> <!-- 用于发送HTTP请求，我们选用OkHttp，它简单又好用 --> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> </dependency> <!-- 用于处理JSON数据，序列化和反序列化离不开它 --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.16.1</version> </dependency> <!-- 如果你喜欢用Gson，也可以用它来代替Jackson --> <!-- <dependency> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> <version>2.10.1</version> </dependency> --> <!-- 用于记录日志，方便调试和查看程序运行状态 --> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>2.0.9</version> </dependency> </dependencies>

添加完依赖，记得刷新一下你的Maven项目，让IDE把这些库下载到本地。好了，我们的“厨房”和“食材”都准备好了，接下来可以开始“炒菜”了。

2. 核心工具类：封装API调用

直接在每个地方都写一遍发送HTTP请求的代码会很啰嗦，也容易出错。最好的办法是把它封装成一个工具类，以后想调用模型，只需要跟这个工具类打交道就行。

我们来创建一个叫做GemmaApiClient的类。这个类就像是我们和Gemma模型之间的专属接线员。

2.1 构建请求基础

首先，这个接线员需要知道把电话打到哪里（Base URL），以及通话时的暗号是什么（API Key）。我们在构造方法里传入这些信息。

import okhttp3.*; import java.io.IOException; public class GemmaApiClient { private final OkHttpClient client; private final String baseUrl; private final String apiKey; // 接线员上岗，记住服务地址和暗号 public GemmaApiClient(String baseUrl, String apiKey) { this.client = new OkHttpClient(); this.baseUrl = baseUrl; this.apiKey = apiKey; } }

这里我们初始化了一个OkHttpClient对象，它是实际负责拨打电话的。为了安全，API Key通常不会直接放在URL里，而是放在HTTP请求的头部（Header）。

2.2 发送消息并获取回复

接下来，我们给这个接线员赋予核心能力：发送一个请求（一段对话内容）给模型，并拿回模型的回复。我们设计一个chatCompletion方法。

模型的API通常接收一个JSON格式的请求体，里面包含了我们的对话消息、模型名称以及其他参数。我们先来定义这个请求体的Java类，这样后面组装数据会非常方便。

import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; // 描述单条消息的类 class ChatMessage { private String role; // 角色：user（用户）, assistant（助手） private String content; // 消息内容 // 构造方法、Getter和Setter省略，实际编写时需要加上 // 可以使用IDE快捷键生成，或者使用Lombok库的 @Data 注解 } // 描述整个API请求的类 class ChatRequest { private String model; // 指定使用的模型，例如 "gemma-3-12b-it" private List<ChatMessage> messages; // 对话历史列表 private double temperature = 0.7; // 创造性参数，0-1，越高回答越随机 private int maxTokens = 512; // 生成回复的最大长度 // 同样，需要构造方法和Getter/Setter }

有了这些“数据模具”，我们就能在方法里轻松地构造请求了。现在来看chatCompletion方法的实现：

public String chatCompletion(ChatRequest request) throws IOException { // 1. 将Java对象转换成JSON字符串 ObjectMapper mapper = new ObjectMapper(); String requestBody = mapper.writeValueAsString(request); // 2. 构建HTTP请求 Request httpRequest = new Request.Builder() .url(baseUrl + "/v1/chat/completions") // 拼接完整的API地址 .post(RequestBody.create(requestBody, MediaType.get("application/json"))) .addHeader("Authorization", "Bearer " + apiKey) // 添加认证头 .addHeader("Content-Type", "application/json") .build(); // 3. 发送请求并获取响应 try (Response response = client.newCall(httpRequest).execute()) { if (!response.isSuccessful()) { // 如果请求失败（比如状态码不是200），抛出异常并带上错误信息 throw new IOException("Unexpected code " + response + ", body: " + response.body().string()); } // 4. 解析响应JSON，提取出模型生成的回复文本 String responseBody = response.body().string(); JsonNode rootNode = mapper.readTree(responseBody); // 通常回复文本在 choices[0].message.content 路径下 return rootNode.path("choices").get(0).path("message").path("content").asText(); } }

这个方法干了四件事：把请求数据打包成JSON、打电话、检查电话是否接通成功、最后从回复里拆出我们需要的文本内容。

3. 第一个实战项目：情感分析助手

工具类写好了，不拿来用用怎么知道好不好使？咱们来做一个既简单又实用的小项目：情感分析助手。你给它一段话，它告诉你这段话表达的情绪是积极的、消极的还是中性的。

3.1 设计对话提示词

让AI做情感分析，关键在于你怎么“问”它。我们需要设计一个清晰的“提示词”（Prompt），告诉模型它现在扮演什么角色，任务是什么，以及输出的格式。

我们可以在用户消息前面，先插入一条系统消息来设定规则：

// 创建请求对象 ChatRequest request = new ChatRequest(); request.setModel("gemma-3-12b-it"); // 构建对话消息列表 List<ChatMessage> messages = new ArrayList<>(); // 第一条是系统消息，定义助手的行为 ChatMessage systemMsg = new ChatMessage(); systemMsg.setRole("system"); systemMsg.setContent("你是一个情感分析助手。用户会给你一段文本，你需要分析其情感倾向。请只用以下三个词之一回答：积极、消极、中性。不要解释，不要额外输出。"); messages.add(systemMsg); // 第二条是用户消息，即需要分析的文本 ChatMessage userMsg = new ChatMessage(); userMsg.setRole("user"); userMsg.setContent("等了三年的电影今天终于上映了，特效和剧情都远超预期，太震撼了！"); messages.add(userMsg); request.setMessages(messages); request.setTemperature(0.1); // 情感分析需要确定性，创造性调低 request.setMaxTokens(10); // 输出很短，限制一下长度

3.2 调用并处理结果

现在，用我们之前写好的工具类来发送这个请求。

public class SentimentAnalyzer { public static void main(String[] args) { // 替换成你自己的Base URL和API Key String baseUrl = "https://your-gemma-api-endpoint.com"; String apiKey = "your-secret-api-key-here"; GemmaApiClient client = new GemmaApiClient(baseUrl, apiKey); // 构建上面定义好的请求 ChatRequest request = buildSentimentRequest("等了三年的电影今天终于上映了，特效和剧情都远超预期，太震撼了！"); try { String result = client.chatCompletion(request); System.out.println("情感分析结果: " + result); // 预期输出：积极 } catch (IOException e) { System.err.println("调用API时出错: " + e.getMessage()); e.printStackTrace(); } } // 将构建请求的逻辑封装成一个方法，方便复用 private static ChatRequest buildSentimentRequest(String textToAnalyze) { // ... 上面构建请求的代码 ... } }

运行这个程序，如果一切配置正确，你应该能看到控制台打印出“积极”两个字。你可以尝试换一些不同的句子，比如“今天工作搞砸了，心情糟透了”，看看模型会不会输出“消极”。

4. 第二个实战项目：智能文本生成器

情感分析是让模型做“选择题”，而文本生成则是让模型做“填空题”或“作文题”。我们再来试试让Gemma帮你进行创意写作，比如生成一篇简短的产品介绍。

4.1 实现流式文本生成

对于文本生成，尤其是生成长文本时，我们可能希望看到模型一个字一个字“思考”和“输出”的过程，而不是干等很久后一次性拿到全部结果。这种体验叫做“流式响应”。

很多AI API都支持流式传输（Server-Sent Events）。我们需要稍微修改一下工具类，让它能处理这种持续不断的数据流。

import okhttp3.sse.EventSource; import okhttp3.sse.EventSources; public void streamChatCompletion(ChatRequest request, EventSource.Listener listener) { ObjectMapper mapper = new ObjectMapper(); String requestBody; try { requestBody = mapper.writeValueAsString(request); } catch (Exception e) { throw new RuntimeException(e); } // 构建请求，注意这里通常需要添加一个 stream=true 的参数 // 具体方式可能因API而异，有时是在请求体里加字段，有时是加查询参数 request.setStream(true); // 假设我们在ChatRequest类里添加了stream字段 Request httpRequest = new Request.Builder() .url(baseUrl + "/v1/chat/completions") .post(RequestBody.create(requestBody, MediaType.get("application/json"))) .addHeader("Authorization", "Bearer " + apiKey) .addHeader("Accept", "text/event-stream") // 声明接受事件流 .build(); // 创建事件源并启动流式连接 EventSource eventSource = EventSources.createFactory(client).newEventSource(httpRequest, listener); // 监听器会回调 onEvent 方法，我们在那里处理每一块收到的数据 }

你需要实现一个EventSource.Listener，在它的onEvent方法中解析收到的数据块（通常是data: {...}格式的JSON），并实时提取出部分文本更新到你的UI或控制台。

4.2 生成产品介绍案例

即使不用流式，普通的文本生成也很有用。我们来让Gemma为一款“智能咖啡杯”写个介绍。

public class ProductDescGenerator { public static void main(String[] args) throws IOException { String baseUrl = "https://your-gemma-api-endpoint.com"; String apiKey = "your-secret-api-key-here"; GemmaApiClient client = new GemmaApiClient(baseUrl, apiKey); List<ChatMessage> messages = new ArrayList<>(); ChatMessage userMsg = new ChatMessage(); userMsg.setRole("user"); userMsg.setContent("请为‘智能恒温咖啡杯’撰写一段吸引人的电商产品介绍，突出其保温、温度显示和手机APP控制的特点。字数在150字左右。"); messages.add(userMsg); ChatRequest request = new ChatRequest(); request.setModel("gemma-3-12b-it"); request.setMessages(messages); request.setTemperature(0.8); // 创意写作，可以调高一点创造性 request.setMaxTokens(300); String productDesc = client.chatCompletion(request); System.out.println("生成的产品介绍：\n"); System.out.println(productDesc); } }

运行后，你可能会得到一段类似这样的文字：“告别冷咖啡！这款智能恒温咖啡杯，内置精准温控系统，能将您喜爱的饮品长时间保持在最佳口感温度。杯身LED屏实时显示温度，轻触即可切换模式。连接专属手机APP，可自定义保温曲线、设定提醒，让每一口都恰到好处。无论是办公室的忙碌时光，还是户外的悠闲片刻，它都是您品味生活的智能伴侣。”

5. 完善与进阶：异常处理与性能优化

我们的工具类已经能工作了，但一个好的“接线员”不仅要能通话，还要能处理各种意外情况，并且要高效。

5.1 健壮的异常处理

网络可能会超时，API密钥可能过期，返回的数据格式可能意外。我们需要增强代码的健壮性。

首先，可以为OkHttpClient设置合理的超时时间，避免程序无限期等待。

private final OkHttpClient client; public GemmaApiClient(String baseUrl, String apiKey) { this.client = new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) // 连接超时 .writeTimeout(30, TimeUnit.SECONDS) // 发送数据超时 .readTimeout(60, TimeUnit.SECONDS) // 读取响应超时 .build(); this.baseUrl = baseUrl; this.apiKey = apiKey; }

其次，在chatCompletion方法中，我们需要更细致地处理HTTP错误码和响应体解析异常。

public String chatCompletion(ChatRequest request) throws IOException, ApiException { // ... 构建请求的代码 ... try (Response response = client.newCall(httpRequest).execute()) { String responseBody = response.body().string(); int code = response.code(); if (code == 401) { throw new ApiException("认证失败，请检查API Key是否正确。", code); } else if (code == 429) { throw new ApiException("请求过于频繁，请稍后再试。", code); } else if (code == 503) { throw new ApiException("服务暂时不可用，可能是模型正在加载。", code); } else if (!response.isSuccessful()) { // 尝试解析错误信息 try { JsonNode errorNode = mapper.readTree(responseBody).path("error"); String errorMsg = errorNode.path("message").asText("未知错误"); throw new ApiException("API调用失败: " + errorMsg, code); } catch (Exception e) { throw new ApiException("API调用失败，状态码: " + code + ", 响应: " + responseBody, code); } } // ... 成功时解析正常响应的代码 ... } catch (SocketTimeoutException e) { throw new IOException("网络请求超时，请检查网络连接或调整超时设置。", e); } } // 自定义一个业务异常类 class ApiException extends Exception { private final int statusCode; public ApiException(String message, int statusCode) { super(message); this.statusCode = statusCode; } public int getStatusCode() { return statusCode; } }