18_Spring AI 干货笔记之 Google VertexAI API

阿里云教程2个月前发布
13 0 0

一、Google VertexAI API

VertexAI API 通过最少的机器学习专业知识和工作量，提供高质量的定制机器学习模型。

Spring AI 通过以下客户端与 VertexAI API 集成：

VertexAI Gemini 对话模型

二、VertexAI Gemini 对话模型

Vertex AI Gemini API 允许开发者使用 Gemini 模型构建生成式 AI 应用程序。Vertex AI Gemini API 支持多模态提示作为输入，并输出文本或代码。多模态模型是能够处理来自多种模态信息的模型，包括图像、视频和文本。例如，您可以向模型发送一盘饼干的照片，并让它给出这些饼干的配方。

Gemini 是由 Google DeepMind 开发的生成式 AI 模型系列，专为多模态用例设计。Gemini API 让您能够访问 Gemini 2.0 Flash 和 Gemini 2.0 Flash-Lite。有关 Vertex AI Gemini API 模型的规格，请参阅 模型信息。

Gemini API 参考

三、先决条件

安装适用于您操作系统的 gcloud CLI。

运行以下命令进行身份验证。将 PROJECT_ID 替换为您的 Google Cloud 项目 ID，将 ACCOUNT 替换为您的 Google Cloud 用户名。


gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>

四、自动配置

Spring AI 的自动配置和 starter 模块的工件名称发生了重大变化。更多信息请参考升级说明。

Spring AI 为 VertexAI Gemini 聊天客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

Maven


<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-vertex-ai-gemini</artifactId>
</dependency>

Gradle


dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-vertex-ai-gemini'
}

请参阅 “依赖管理” 部分，将 Spring AI BOM 添加到您的构建文件中。

4.1 聊天属性

聊天自动配置的启用和禁用现在通过前缀为 spring.ai.model.chat 的顶级属性进行配置。

要启用：spring.ai.model.chat=vertexai（默认已启用）。

要禁用：spring.ai.model.chat=none（或任何不匹配 vertexai 的值）。

此项更改是为了支持配置多个模型。

前缀 spring.ai.vertex.ai.gemini 用作属性前缀，允许您连接到 VertexAI。
18_Spring AI 干货笔记之 Google VertexAI API
前缀 spring.ai.vertex.ai.gemini.chat 是用于配置 VertexAI Gemini 聊天模型实现的属性前缀。
18_Spring AI 干货笔记之 Google VertexAI API

所有以 spring.ai.vertex.ai.gemini.chat.options 为前缀的属性都可以在运行时通过向 Prompt 调用添加请求特定的“运行时选项”来覆盖。

五、运行时选项

VertexAiGeminiChatOptions.java 提供了模型配置，例如温度、topK 等。

在启动时，可以通过 VertexAiGeminiChatModel(api, options) 构造函数或 spring.ai.vertex.ai.chat.options.* 属性来配置默认选项。

在运行时，您可以通过向 Prompt 调用添加新的、特定于请求的选项来覆盖默认选项。例如，为特定请求覆盖默认温度：


ChatResponse response = chatModel.call(
    new Prompt(
        "生成 5 个著名海盗的名字。",
        VertexAiGeminiChatOptions.builder()
            .temperature(0.4)
        .build()
    ));

除了模型特定的 VertexAiGeminiChatOptions，您还可以使用可移植的 ChatOptions 实例，该实例通过 ChatOptions#builder() 创建。

六、工具调用

Vertex AI Gemini 模型支持工具调用（在 Google Gemini 上下文中，称为函数调用）功能，允许模型在对话过程中使用工具。以下是如何定义和使用基于 @Tool 的工具的示例：


public class WeatherService {

    @Tool(description = "获取指定地点的天气")
    public String weatherByLocation(@ToolParam(description= "城市或州名") String location) {
        ...
    }
}

String response = ChatClient.create(this.chatModel)
        .prompt("波士顿的天气怎么样？")
        .tools(new WeatherService())
        .call()
        .content();

您也可以使用 java.util.function bean 作为工具：


@Bean
@Description("获取指定地点的天气。以 36°F 或 36°C 格式返回温度。")
public Function<Request, Response> weatherFunction() {
    return new MockWeatherService();
}

String response = ChatClient.create(this.chatModel)
        .prompt("波士顿的天气怎么样？")
        .toolNames("weatherFunction")
        .inputType(Request.class)
        .call()
        .content();

更多信息请参阅 工具文档。

七、多模态

多模态性是指模型能够同时理解和处理来自各种（输入）源的信息，包括文本、PDF、图像、音频和其他数据格式。

7.1 图像、音频、视频

Google 的 Gemini AI 模型通过理解和集成文本、代码、音频、图像和视频来支持此功能。更多详情，请参阅博客文章《Introducing Gemini》。

Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 AI 模型。此类型包含消息中媒体附件的数据和信息，使用 Spring 的 org.springframework.util.MimeType 和用于原始媒体数据的 java.lang.Object。

以下是从 VertexAiGeminiChatModelIT#multiModalityTest() 中提取的简单代码示例，演示了用户文本与图像的结合。


byte[] data = new ClassPathResource("/vertex-test.png").getContentAsByteArray();

var userMessage = new UserMessage("解释一下你在这张图片中看到了什么？",
        List.of(new Media(MimeTypeUtils.IMAGE_PNG, this.data)));

ChatResponse response = chatModel.call(new Prompt(List.of(this.userMessage)));

7.2 PDF 格式

最新的 Vertex Gemini 支持 PDF 输入类型。使用 application/pdf 媒体类型将 PDF 文件附加到消息：


var pdfData = new ClassPathResource("/spring-ai-reference-overview.pdf");

var userMessage = new UserMessage(
        "你是一位非常专业的文档摘要专家。请总结给定的文档。",
        List.of(new Media(new MimeType("application", "pdf"), pdfData)));

var response = this.chatModel.call(new Prompt(List.of(userMessage)));

八、安全设置和安全评分

Vertex AI Gemini API 提供了安全过滤功能，帮助您控制提示和响应中的有害内容。更多详情，请参阅 Vertex AI 安全过滤器文档。

8.1 配置安全设置

您可以配置安全设置来控制不同危害类别的内容被阻止的阈值。可用的危害类别有：

HARM_CATEGORY_HATE_SPEECH – 仇恨言论内容

HARM_CATEGORY_DANGEROUS_CONTENT – 危险内容

HARM_CATEGORY_HARASSMENT – 骚扰内容

HARM_CATEGORY_SEXUALLY_EXPLICIT – 色情内容

HARM_CATEGORY_CIVIC_INTEGRITY – 公民诚信内容

可用的阈值级别有：

BLOCK_LOW_AND_ABOVE – 当低、中或高概率存在不安全内容时阻止

BLOCK_MEDIUM_AND_ABOVE – 当中或高概率存在不安全内容时阻止

BLOCK_ONLY_HIGH – 仅当高概率存在不安全内容时阻止

BLOCK_NONE – 从不阻止（谨慎使用）


List<VertexAiGeminiSafetySetting> safetySettings = List.of(
    VertexAiGeminiSafetySetting.builder()
        .withCategory(VertexAiGeminiSafetySetting.HarmCategory.HARM_CATEGORY_HARASSMENT)
        .withThreshold(VertexAiGeminiSafetySetting.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE)
        .build(),
    VertexAiGeminiSafetySetting.builder()
        .withCategory(VertexAiGeminiSafetySetting.HarmCategory.HARM_CATEGORY_HATE_SPEECH)
        .withThreshold(VertexAiGeminiSafetySetting.HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE)
        .build());

ChatResponse response = chatModel.call(new Prompt("您的提示在这里",
    VertexAiGeminiChatOptions.builder()
        .safetySettings(safetySettings)
        .build()));

8.2 访问响应中的安全评分

配置安全设置后，Gemini API 会为每个响应候选返回安全评分。这些评分表明每个类别中有害内容的概率和严重性。

安全评分可在 AssistantMessage 元数据中的 “safetyRatings” 键下找到：


ChatResponse response = chatModel.call(new Prompt(prompt,
    VertexAiGeminiChatOptions.builder()
        .safetySettings(safetySettings)
        .build()));

// 从响应中访问安全评分
List<VertexAiGeminiSafetyRating> safetyRatings =
    (List<VertexAiGeminiSafetyRating>) response.getResult()
        .getOutput()
        .getMetadata()
        .get("safetyRatings");

for (VertexAiGeminiSafetyRating rating : safetyRatings) {
    System.out.println("类别：" + rating.category());
    System.out.println("概率：" + rating.probability());
    System.out.println("严重性：" + rating.severity());
    System.out.println("是否被阻止：" + rating.blocked());
}

VertexAiGeminiSafetyRating 记录包含：

category – 危害类别（例如，HARM_CATEGORY_HARASSMENT）

probability – 概率级别（NEGLIGIBLE、LOW、MEDIUM、HIGH）

blocked – 内容是否因该评分而被阻止

probabilityScore – 原始概率分数（0.0 到 1.0）

severity – 严重性级别（HARM_SEVERITY_NEGLIGIBLE、HARM_SEVERITY_LOW、HARM_SEVERITY_MEDIUM、HARM_SEVERITY_HIGH）

severityScore – 原始严重性分数（0.0 到 1.0）

九、示例控制器

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-vertex-ai-gemini 添加到您的 pom（或 gradle）依赖项中。

在 src/main/resources 目录下添加一个 application.properties 文件，以启用和配置 VertexAi 聊天模型：


spring.ai.vertex.ai.gemini.project-id=项目_ID
spring.ai.vertex.ai.gemini.location=区域
spring.ai.vertex.ai.gemini.chat.options.model=gemini-2.0-flash
spring.ai.vertex.ai.gemini.chat.options.temperature=0.5

请将 project-id 替换为您的 Google Cloud 项目 ID，location 是 Google Cloud 区域，例如 us-central1、europe-west1 等。

每个模型都有自己支持的区域列表，您可以在模型页面上找到支持的区域列表。

例如，model=gemini-2.5-flash 当前仅在 us-central1 区域可用，您必须设置 location=us-central1，遵循模型页面 Gemini 2.5 Flash – 支持区域的说明。

这将创建一个 VertexAiGeminiChatModel 实现，您可以将其注入到您的类中。以下是一个简单的 @Controller 类示例，该类使用聊天模型进行文本生成。


@RestController
public class ChatController {

    private final VertexAiGeminiChatModel chatModel;

    @Autowired
    public ChatController(VertexAiGeminiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

十、手动配置

VertexAiGeminiChatModel 实现了 ChatModel，并使用 VertexAI 连接到 Vertex AI Gemini 服务。

将 spring-ai-vertex-ai-gemini 依赖项添加到项目的 Maven pom.xml 文件中：


<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-gemini</artifactId>
</dependency>

或者添加到您的 Gradle build.gradle 构建文件中。


dependencies {
    implementation 'org.springframework.ai:spring-ai-vertex-ai-gemini'
}

请参阅 “依赖管理” 部分，将 Spring AI BOM 添加到您的构建文件中。

接下来，创建一个 VertexAiGeminiChatModel 并将其用于文本生成：


VertexAI vertexApi =  new VertexAI(projectId, location);

var chatModel = new VertexAiGeminiChatModel(this.vertexApi,
    VertexAiGeminiChatOptions.builder()
        .model(ChatModel.GEMINI_2_0_FLASH)
        .temperature(0.4)
    .build());

ChatResponse response = this.chatModel.call(
    new Prompt("生成 5 个著名海盗的名字。"));

VertexAiGeminiChatOptions 为聊天请求提供配置信息。VertexAiGeminiChatOptions.Builder 是一个流畅的选项构建器。

十一、低级 Java 客户端

下面的类图说明了 Vertex AI Gemini 原生 Java API：

18_Spring AI 干货笔记之 Google VertexAI API

© 版权声明
文章版权归作者所有，未经允许请勿转载。

相关文章

暂无评论

none
暂无评论...
添加小工具
点此为“正文侧边栏”添加小工具