Spring AI：让大模型住进 Spring 生态（五）

专栏：Spring AI 探索手札

个人主页：手握风云

一、提示词工程

[1.1. 基础概念](#1.1. 基础概念)

[1. 提示词定义](#1. 提示词定义)

[2. 提示词核心价值](#2. 提示词核心价值)

[1.2. 高质量提示词七大核心构成要素](#1.2. 高质量提示词七大核心构成要素)

[1.3. 高阶提示词技巧](#1.3. 高阶提示词技巧)

[1. CO-STAR 结构化框架](#1. CO-STAR 结构化框架)

[2. 少样本提示](#2. 少样本提示)

[3. 思维链提示](#3. 思维链提示)

[4. 自我一致性](#4. 自我一致性)

二、通用多模态模型

[2.1. 图像模型](#2.1. 图像模型)

[2.2. 接入 OpenAI](#2.2. 接入 OpenAI)

[2.3. 图像模型 API](#2.3. 图像模型 API)

[1. ImageModel](#1. ImageModel)

[2. ImagePrompt](#2. ImagePrompt)

[3. ImageMessage](#3. ImageMessage)

[4. ImageOptions](#4. ImageOptions)

[5. OpenAI 专属配置](#5. OpenAI 专属配置)

[6. ImageResponse](#6. ImageResponse)

[7. ImageGeneration](#7. ImageGeneration)

[8. Image](#8. Image)

[2.4. 图像数据两种返回格式](#2.4. 图像数据两种返回格式)

[2.5. 语音模型](#2.5. 语音模型)

[1. 语音模型定义](#1. 语音模型定义)

[2. OpenAI 文本转语音（TTS）](#2. OpenAI 文本转语音（TTS）)

[3. 快速入门](#3. 快速入门)

[4. 核心 API 详解](#4. 核心 API 详解)

一、提示词工程

1.1. 基础概念

1. 提示词定义

提示词（Prompt）是给到大语言模型的清晰、具体指令。大模型具备海量知识储备，但无法自主揣测人类真实意图，用户输入的内容就是模型生成答案的唯一依据，类比给新实习生安排工作，模糊指令无法得到预期结果，精准指令才能匹配需求。

2. 提示词核心价值

提示词质量直接决定 AI 输出结果的相关性、可用性和专业度；
低质量提示词：指令模糊，AI 自由发挥，输出内容杂乱无章、偏离预期；
高质量提示词：如同标准化工作说明书，让 AI 快速定位角色、精准执行任务；
本质核心：提示词工程不是让大模型变得更聪明，而是提升人类指挥、驾驭 AI 的能力。

1.2. 高质量提示词七大核心构成要素

业界总结出可拆解、可复用的结构化要素，非全部为必填项，可按需组合使用，也是编写精准提示词的基础骨架：

目标（Objective） 提示词的灵魂，明确要求 AI 完成的具体任务，如文档翻译、文本摘要、痛点分析、文案创作等。
**背景（Context）**补充任务业务场景、前置条件与上下文，消除语义歧义，帮助 AI 精准理解任务逻辑，避免默认猜测场景。
**受众（Audience）**明确内容面向的人群，AI 会自动适配语言风格、专业术语密度与表达形式（面向高中生简化术语、面向 CEO 突出数据决策、面向社交媒体采用活泼风格）。
**风格（Style）**定义内容文体与创作类型，如新闻体、故事风、学术风、口语化、幽默讽刺风、科技极客风等。
**语气（Tone）**设定内容的情感色彩，分为正式严谨、轻松幽默、激励鼓舞、客观中立等，适配商业报告、社交科普、演讲稿等不同场景。
**格式（Response Format）**指定 AI 输出的结构与形式，支持 Markdown / 表格 / JSON、固定字数限制、固定段落框架（标题 + 引言 + 要点 + 结尾），方便后续集成到业务系统、网页或数据库。
约束条件（Constraints） 明确禁止项与限制规则，如禁用夸张词汇、不虚构数据、规避敏感内容、严格控制字数、固定技术栈不随意拓展等。

如果我们为⼀家新兴 AI 公司撰写后端工程师的招聘启事，发布在微信公众号上，按照上面七大要素就可以生成我们需要的文案。

复制代码

你是⼀家专注于 AIGC ⼯具研发的初创公司HR。公司已完成天使轮融资, 团队由来自⼀线⼤⼚的技术
骨干组成，⽬前正在寻找⼀位热爱后端技术的伙伴加入。
请撰写⼀篇发布在微信公众号上的Java后端开发⼯程师招聘启事, 要求：
1. ⾯向⼈群： 有 3-5 年Java后端经验、具备系统化思维和⼯程意识的开发者
2. ⻛格调性： 科技极客⻛, 参考少数派或V2EX的语⾔调性, 突出技术挑战和⼯程实践
3. 语气：真诚开放, 避免使用"⾼薪诚聘""精英汇聚"等浮夸词汇
4. 内容包含： 标题、公司简介、岗位职责、任职要求、福利待遇、如何申请
5. 总字数： 控制在 600 字左右
6. 技术栈： 基于 Java + Spring Cloud + Spring Cloud + MySQL + Redis, 并涉及⾼并发、分布式系统设计

1.3. 高阶提示词技巧

1. CO-STAR 结构化框架

CO-STAR 是业界对提示词七大要素进行逻辑重组与标准化封装的结构化提示词设计框架，相当于一份提示词编写的检查清单与导航图，能够有效解决编写提示词时容易遗漏关键信息、输出质量不稳定、团队之间提问标准不统一等痛点。该框架由六个维度构成，分别是背景 Context、目标 Objective、风格 Style、语气 Tone、受众 Audience、响应格式 Response，依次对应场景、目标、风格、语气、对象、格式六大编写逻辑。CO-STAR 本身没有包含约束条件要素，在实际落地使用时，通常会在响应格式之后补充约束规则，形成完整的提示词闭环。借助这套框架，提示词创作可以从以往凭感觉、靠经验的随性模式，转变为标准化、流程化的结构驱动模式，既适合个人快速写出高质量提示词，也能统一团队的提示词编写规范。

2. 少样本提示

少样本提示是提示工程中非常实用的高阶技巧，核心思路是在正式向大模型提出问题前，先给模型提供若干组输入与输出对应的参考样例，让模型自主学习任务专属的表达风格、输出格式和逻辑规则，再按照习得的模式去处理全新的问题。和零样本提示只靠文字描述规则、无任何示范案例相比，少样本提示能够有效避免 AI 答非所问、风格模仿四不像等问题。这种技巧特别适用于风格仿写、数据标准化提取、文本情感分类、意图识别以及固定格式生成等格式繁琐、逻辑或风格特殊的任务，使用时只需按照多组示例先行、新问题后置的模板排版，就能大幅提升模型输出的匹配度。

示例一：你需要按照给定示例的风格，对句子进行乐观 / 悲观情感分类。示例如下：世界越来越糟，没有改善的可能，归类为悲观；每天都是新的开始，充满希望，归类为乐观；只要努力，梦想终会实现，归类为乐观。请参照上面的判断逻辑，对新句子「生活太艰难了，看不到出路」进行情感分类，严格模仿示例只输出分类结果即可。

请参照示例，把长文本提炼成一句话精简摘要。示例原文：春天公园里开满桃花、樱花，游人散步拍照，春风温柔宜人，到处生机勃勃，摘要：春日公园繁花盛放，游人休闲踏青。请按照同样精简凝练、保留核心信息的方式，为下面一段文字生成一句话摘要：夏日湖边绿树成荫，荷花竞相开放，老人下棋、孩童戏水，晚风清凉惬意，充满生活气息。

请参考下面示例的判断规则，完成同类逻辑推理。示例 1：这组数字中的奇数加起来是一个偶数：4、8、9、15、12、2、1，答案是 False；示例 2：这组数字中的奇数加起来是一个偶数：17、10、19、4、8、12、24，答案是 True；示例 3：这组数字中的奇数加起来是一个偶数：16、11、14、4、8、13、24，答案是 True；示例 4：这组数字中的奇数加起来是一个偶数：17、9、10、12、13、4、2，答案是 False。请沿用同样的计算和判断逻辑，处理新输入：这组数字中的奇数加起来是一个偶数：15、32、5、13、82、7、1，只输出最终 True 或 False 结果。

3. 思维链提示

思维链提示的核心思想是不要求大模型直接给出最终答案，而是通过指令引导模型拆解问题，完整展示一步步的推理思考过程，就像学生做数学题必须写出演算步骤一样。该技巧主要应用于数学计算、逻辑推理、因果分析、决策判断等复杂任务，能够把 AI 原本的黑盒式直接输出，转变为可追溯、可校验、可纠错的白盒分步推导，有效提升模型推理准确率。思维链提示有两种主流用法，一种是零样本 CoT，无需提供范例，仅在提示词中加入让模型逐步思考、分步推理的指令即可生效；另一种是少样本 CoT，提前给出带有完整推理流程的示例，引导高难度复杂任务复刻推导逻辑，是当下效果极强的提示组合策略。

示例一：请你不要直接给出最终答案，要一步一步写出推理思考过程，最后再给出结论。小明一开始有 5 个苹果，吃掉了 2 个，后来又新买了 8 个，请你按步骤计算他现在一共有多少个苹果。

示例二：请按照已知条件、套用公式、代入计算的顺序逐步思考，不要直接给答案。一辆汽车每小时行驶 60 公里，连续行驶 3 个小时不减速、不休息，请一步步推理算出这辆车总共能行驶多少公里。

示例三：请先梳理已知信息，再分步推导过程，最后给出结果。小明有 24 颗糖果，每天吃 3 颗，每吃完 3 天就休息 1 天不吃糖，请你一步步推理计算，小明全部吃完这些糖一共要经历多少天。

示例四：请先列出判断依据，再逐条分析条件，最后给出对错结论。现有一个常识判断：所有鸟类都会飞，请你先拆解判断逻辑，举出反例，一步步推理分析这句话是否正确，并说明理由。

4. 自我一致性

自我一致性是基于思维链 CoT 优化升级的进阶推理策略，主要用来解决大模型面对同一问题时多次回答答案不一致、单次推理容易出错输出不稳定的问题。其核心做法是让 AI 针对同一个问题，生成多条相互独立、推理路径不同的思考过程，再通过类似投票的机制，筛选出出现频率最高、逻辑最连贯合理的结论作为最终输出。区别于传统思维链只依赖单条推理路径、一旦中间逻辑出错结果就会失效的短板，自我一致性通过多路径探索、择优聚合的方式，具备自动纠错能力，能够显著提升数学运算、逻辑判断、数据分析类任务的答案准确率与输出稳定性。

二、通用多模态模型

2.1. 图像模型

定义：图像模型是专注于处理与理解视觉数据的人工智能模型，是计算机视觉与多模态学习的核心组件。通俗理解为可实现看图说话（图像理解）、根据文字描述画画（图像生成）两大核心能力。

类型	功能说明
图像生成模型	依据文本、已有图像等输入，自动合成全新图像
图像理解模型	对输入图像进行分析，完成分类、目标检测、图像分割等认知任务

比如我们输入"宏伟的奇幻浮空城，哥特式建筑，周围环绕着发光的瀑布与巨龙。云雾缭绕，日落时分，天空呈现紫橙色"。

Spring AI 提供统一的 Image Model API 抽象层，屏蔽各厂商图像模型的接口差异，开发者仅需极小代码改动，即可在不同平台、不同图像模型间快速切换。

2.2. 接入 OpenAI

创建父项目：

XML 复制代码

<properties>
	<maven.compiler.source>17</maven.compiler.source>
	<maven.compiler.target>17</maven.compiler.target>
	<spring-ai.version>1.0.7</spring-ai.version>
</properties>

<!--完善依赖-->
<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>3.5.3</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>

<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>org.springframework.ai</groupId>
			<artifactId>spring-ai-bom</artifactId>
			<version>${spring-ai.version}</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
	</dependencies>
</dependencyManagement>

创建子项目：

XML 复制代码

<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
	<dependency>
		<groupId>org.springframework.ai</groupId>
		<artifactId>spring-ai-starter-model-openai</artifactId>
	</dependency>
	<dependency>
		<groupId>org.projectlombok</groupId>
		<artifactId>lombok</artifactId>
	</dependency>
</dependencies>

<build>
	<plugins>
		<plugin>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-maven-plugin</artifactId>
		</plugin>
	</plugins>
</build>

完善启动类：

java 复制代码

package com.yang.image;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringImageDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringImageDemoApplication.class, args);
    }
}

设置 API-KEY

java 复制代码

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

图像生成

java 复制代码

package com.yang.image.controller;

import org.springframework.ai.image.ImagePrompt;
import org.springframework.ai.image.ImageResponse;
import org.springframework.ai.openai.OpenAiImageModel;
import org.springframework.ai.openai.OpenAiImageOptions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/openai")
public class OpenAiImageController {
    @Autowired
    private OpenAiImageModel openAiImageModel;

    @RequestMapping("/image")
    public void image() {
        ImageResponse response = openAiImageModel.call(
                new ImagePrompt("A light cream colored mini golden doodle",
                        OpenAiImageOptions.builder()
                                .model("gpt-image-2")
                                .quality("low")
                                .N(1)
                                .height(1024)
                                .width(1024).build())

        );

        String imageUrl = response.getResult().getOutput().getUrl();
        System.out.println(imageUrl);
    }
}

2.3. 图像模型 API

1. ImageModel

作用是图像模型的顶层函数式接口，是调用图像生成能力的唯一入口，定义了模型调用的基础方法。

java 复制代码

@FunctionalInterface
public interface ImageModel extends Model<ImagePrompt, ImageResponse> {
    ImageResponse call(ImagePrompt request);
}

所有图像模型（OpenAI、百度千帆、阿里通义等）均实现该接口，开发者直接调用 call() 方法即可发起图像生成请求。

java 复制代码

// imageModel 为框架自动注入的图像模型实例
ImageResponse response = imageModel.call(
    new ImagePrompt("一只戴着墨镜的猫在弹吉他")
);

2. ImagePrompt

作用是封装完整的图像生成请求，整合文本描述消息和模型运行配置，是传递给 ImageModel 的标准请求体。

java 复制代码

public class ImagePrompt implements ModelRequest<List<ImageMessage>> {
    // 图像文本描述消息列表
    private final List<ImageMessage> messages;
    // 图像模型配置参数
    private ImageOptions imageModelOptions;

    @Override
    public List<ImageMessage> getInstructions() {...}
    @Override
    public ImageOptions getOptions() {...}
}

messages：存储多条图像描述文本，由 ImageMessage 组成；
imageModelOptions：绑定模型的个性化配置（尺寸、质量、风格等）。

3. ImageMessage

作用是封装图像生成的文本描述内容，部分模型支持设置文本权重，调整该描述对生成图像的影响程度。

java 复制代码

public class ImageMessage {
    // 图像描述文本
    private String text;
    // 文本权重（正数/负数，部分模型生效）
    private Float weight;

    public String getText() {...}
    public Float getWeight() {...}
}

java 复制代码

// 设置文本描述 + 权重1.2，强化该描述的优先级
new ImageMessage("太空站内部景观, 高科技感", 1.2f)

4. ImageOptions

作用是所有图像模型的通用配置父接口，定义了跨模型可兼容的基础配置项，是各类模型专属配置类的顶层规范。

java 复制代码

public interface ImageOptions extends ModelOptions {
    // 生成图像数量
    Integer getN();
    // 使用的图像模型名称
    String getModel();
    // 图像宽度
    Integer getWidth();
    // 图像高度
    Integer getHeight();
    // 响应格式：url / b64_json
    String getResponseFormat();
}

方法	对应配置项	含义
getN()	生成数量	单次请求生成图片张数
getModel()	模型名称	指定调用的图像模型
getWidth()/getHeight()	图像尺寸	自定义图片宽高像素
getResponseFormat()	响应格式	控制返回 URL 链接或 Base64 编码

5. OpenAI 专属配置

OpenAiImageOptions 是 ImageOptions 接口针对 OpenAI DALL-E 系列图像模型的专属实现，在通用配置基础上扩展了质量、风格、尺寸规格等独有参数，支持链式构建。

配置属性	配置前缀	描述	取值规则 & 限制
n	spring.ai.openai.image.options.n	生成图像数量	DALL-E-3 仅支持 `n=1`；DALL-E-2 取值 1~10
model	spring.ai.openai.image.options.model	图像模型名称	默认为 OpenAI 官方默认图像模型
width / height	spring.ai.openai.image.options.size_width / size_height	图像宽高	DALL-E-2：仅支持 256/512/1024 像素；DALL-E-3：支持 1024/1792 像素
quality	spring.ai.openai.image.options.quality	图像质量	仅 DALL-E-3 支持；取值 `standard`（标准）、`hd`（高清）
responseFormat	spring.ai.openai.image.options.response_format	返回格式	固定二选一：`url`（链接）、`b64_json`（Base64 编码）
size	spring.ai.openai.image.options.size	整体尺寸	DALL-E-2：256x256 / 512x512 / 1024x1024；DALL-E-3：1024x1024 / 1792x1024 / 1024x1792
style	spring.ai.openai.image.options.style	图像风格	仅 DALL-E-3 支持；`vivid`（生动超现实）、`natural`（写实自然）

java 复制代码

ImageResponse imageResponse = openAiImageModel.call(
    new ImagePrompt("孩子们在海边玩耍", OpenAiImageOptions.builder()
            .quality("standard")
            .N(1)
            .height(1024)
            .width(1024)
            .style("vivid")
            .build())
);

6. ImageResponse

作用是接收图像模型返回的完整响应数据，包含响应元数据、所有生成的图像结果列表。

java 复制代码

public class ImageResponse implements ModelResponse<ImageGeneration> {
    // 响应元数据（请求日志、限流信息等）
    private final ImageResponseMetadata imageResponseMetadata;
    // 多张图像生成结果集合
    private final List<ImageGeneration> imageGenerations;

    // 获取第一张图像结果（常用）
    @Override
    public ImageGeneration getResult() {}
    // 获取所有图像结果
    @Override
    public List<ImageGeneration> getResults() {}
    // 获取响应元数据
    @Override
    public ImageResponseMetadata getMetadata() {}
}

getResult()：快速获取第一张生成图片（最常用）；
getResults()：获取本次请求生成的全部图片集合。

7. ImageGeneration

作用是表示单张图像的生成结果及附属元数据，继承 ModelResult，是 ImageResponse 的子级对象。

java 复制代码

public class ImageGeneration implements ModelResult<Image> {
    // 单张图片元数据
    private ImageGenerationMetadata imageGenerationMetadata;
    // 图片原始数据（URL / Base64）
    private Image image;

    @Override
    public Image getOutput() {...}
    public ImageGenerationMetadata getMetadata() {...}
}

getOutput()：获取图片实体 Image，进而拿到 URL 或 Base64 数据。

8. Image

java 复制代码

public class Image {
    // 图片在线URL链接
    private String url;
    // Base64编码的图片数据
    private String b64Json;
    // 其他工具方法省略
}

url：图片在线访问链接，数据体积小，使用最简单；
b64Json：Base64 编码字符串，可解码为二进制字节流，用于本地保存、前端直接渲染。

2.4. 图像数据两种返回格式

Spring AI 图像模型 API 统一支持 URL 链接和 Base64 编码两种返回形式，可通过 responseFormat 参数切换。

2.5. 语音模型

1. 语音模型定义

语音模型是专门处理、解析人类语音信号的人工智能模型，主流应用场景分为三类：语音识别（ASR），语音转文本；语音合成（TTS），文本转语音；智能语音助手，结合识别 + 合成，实现人机语音交互。

2. OpenAI 文本转语音（TTS）

能够将书面文本转换为自然流畅的语音音频，支持多语言生成、流式实时音频输出。提供 SpeechModel、StreamingSpeechModel 等高阶抽象接口，统一封装调用逻辑，大幅降低开发复杂度，开发者仅需简单调用 call 方法即可完成文本转语音。

3. 快速入门

直接复用前面的依赖以及 API-KEY，API-KEY 无需单独申请。

java 复制代码

import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;
import org.springframework.ai.openai.OpenAiAudioSpeechOptions;
import org.springframework.ai.openai.api.OpenAiAudioApi;
import org.springframework.ai.openai.audio.speech.SpeechPrompt;
import org.springframework.ai.openai.audio.speech.SpeechResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;

@Slf4j
@RestController
@RequestMapping("/speech")
public class OpenaiSpeechController {
    @Autowired
    private OpenAiAudioSpeechModel openAiAudioSpeechModel;

    @RequestMapping("/tts")
    public void tts() {
        OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
                .model("tts-1")
                .voice(OpenAiAudioApi.SpeechRequest.Voice.NOVA)
                .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.OPUS)
                .speed(1.0f)
                .build();

        SpeechPrompt prompt = new SpeechPrompt(" It's hard to speak about emotions.", speechOptions);
        SpeechResponse response = openAiAudioSpeechModel.call(prompt);

        File file = new File(System.getProperty("user.dir") + "/output.opus");
        try (FileOutputStream fos = new FileOutputStream(file)) {
            fos.write(response.getResult().getOutput());
        } catch (IOException e) {
            log.error("文件写入失败, ", e);
        }
    }
}

4. 核心 API 详解

Spring AI 对 OpenAI TTS 做了分层封装，核心包含 4 个核心类：OpenAiAudioSpeechOptions、SpeechPrompt、SpeechResponse、Speech，各司其职。

OpenAiAudioSpeechOptions（语音配置选项类）

作用是封装文本转语音的所有自定义参数，支持全局配置文件预设 + 代码动态覆盖两种方式，默认参数由框架自动初始化。默认模型是 tts-1，音色是 ALLOY，音频格式 MP3，默认语速 1.0。

参数名	配置前缀	作用	取值与说明
model	spring.ai.openai.audio.speech.options.model	指定语音模型	固定取值 `tts-1`
voice	spring.ai.openai.audio.speech.options.voice	选择播报音色	共 6 种音色：・ALLOY：中性清晰通用音色・ECHO：沉稳男声・FABLE：生动叙事音色・ONYX：低沉权威男声・NOVA：明亮活力女声・SHIMMER：柔和温婉女声
responseFormat	spring.ai.openai.audio.speech.options.response_format	音频输出格式	支持 MP3、WAV、AAC、OPUS 等
speed	spring.ai.openai.audio.speech.options.speed	播报语速	1.0 = 正常速度；>1.0 语速加快；<1.0 语速变慢

SpeechPrompt（语音请求封装类）

作用是整合待转换文本内容和 OpenAiAudioSpeechOptions 配置，构成完整的模型调用请求，是调用 TTS 接口的入参载体。

SpeechMessage：纯文本内容封装，仅存储需要转语音的文字；OpenAiAudioSpeechOptions：上文的语音配置参数。

SpeechResponse（语音响应结果类）

作用是接收 OpenAI 接口返回的全量数据，封装音频二进制流和响应元数据。

Speech：核心实体，存储音频字节数组（byte \[\]），是生成音频文件的原始数据；SpeechResponseMetadata / SpeechMetadata：存储接口响应元数据、接口限流、调用日志等附加信息，业务开发中一般极少使用。