快速入门与核心概念（Getting Started & AI Concepts）
合集说明
本文合并了「快速入门」与「AI 概念」两部分内容：先教你快速搭建 Java AI 项目，再梳理 Java AI 涉及的核心概念（模型、Prompt、Embedding、Token、RAG、Tool Calling 等），为后续深入学习打好基础。
快速入门（Getting Started）
📌 原文地址：https://docs.spring.io/java-ai/reference/getting-started.html 📌 原文版本：Java AI Reference v2.0.1（Stable 稳定版）
本节为想要上手 Java AI 的开发者提供「起跑点」式的入门指引。
你可以根据自己的实际需要，按顺序完成下面各小节中的步骤。
版本兼容性
Java AI 2.0.x 支持 Spring Boot 4.0.x 和 4.1.x 版本。
白话解读
Java AI 是 Spring 官方推出的 AI 应用开发框架，它把 OpenAI、Anthropic、Azure OpenAI、Ollama 等各家大模型，以及 PGvector、Redis、Milvus 等各种向量数据库的接口统一封装起来，让你像写普通 Spring Boot（Spring 家族最流行的应用开发框架）应用一样开发 AI 功能。动手之前，请先确认你的 Spring Boot 版本在支持范围内。
使用 Spring Initializr 创建项目
直接前往 start.spring.io（Spring Initializr，Spring 官方的项目脚手架/初始化工具），在创建新应用时勾选你想使用的 AI Models（AI 模型）和 Vector Stores（向量数据库）相关依赖即可。
白话解读
Spring Initializr 会帮你生成一个依赖都配好的项目骨架：选好要用的模型（比如 OpenAI）和向量库（比如 PGvector），生成并下载项目，用 IDE 打开就能直接开写，省去手动加依赖的麻烦。
依赖仓库配置
正式发布版——使用 Maven Central
Java AI 的制品已发布到 Maven Central（Maven 中央仓库），无需额外配置仓库地址。你只需确保构建文件中启用了 Maven Central 即可。
Maven 配置：
<!-- Maven Central 在 Maven 构建中默认已包含。
通常无需显式配置，
此处仅为清晰展示而列出。 -->
<repositories>
<repository>
<id>central</id>
<url>https://repo.maven.apache.org/maven2</url> <!-- Maven 中央仓库地址 -->
</repository>
</repositories>Gradle 配置：
repositories {
mavenCentral() // 启用 Maven 中央仓库
}快照版——添加 Snapshot 仓库
如果想使用最新的开发版本（例如 2.0.0-SNAPSHOT，即仍在开发中的每日构建版本），你需要在构建文件中添加以下 Snapshot（快照）仓库。
在 Maven 或 Gradle 构建文件中加入以下仓库定义：
Maven 配置：
<repositories>
<!-- Spring 官方快照仓库 -->
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/snapshot</url>
<releases>
<enabled>false</enabled> <!-- 不从该仓库拉取正式发布版 -->
</releases>
</repository>
<!-- Central Portal 快照仓库 -->
<repository>
<name>Central Portal Snapshots</name>
<id>central-portal-snapshots</id>
<url>https://central.sonatype.com/repository/maven-snapshots/</url>
<releases>
<enabled>false</enabled> <!-- 不从该仓库拉取正式发布版 -->
</releases>
<snapshots>
<enabled>true</enabled> <!-- 启用快照版本拉取 -->
</snapshots>
</repository>
</repositories>Gradle 配置：
repositories {
mavenCentral()
maven { url 'https://repo.spring.io/milestone' } // Spring 里程碑版本仓库
maven { url 'https://repo.spring.io/snapshot' } // Spring 快照版本仓库
maven {
name = 'Central Portal Snapshots'
url = 'https://central.sonatype.com/repository/maven-snapshots/' // Central Portal 快照仓库
}
}注意：Maven 镜像配置可能挡住快照仓库
在 Maven 中配合 Java AI 快照版使用时，请留意你的 Maven 镜像配置。如果你在 settings.xml 中配置了如下镜像：
<mirror>
<id>my-mirror</id>
<mirrorOf>*</mirrorOf> <!-- 通配符 *：所有仓库请求都重定向到该镜像 -->
<url>https://my-company-repository.com/maven</url>
</mirror>其中通配符 * 会把所有仓库请求都重定向到你的镜像，导致无法访问 Spring 的快照仓库。解决办法是修改 mirrorOf 配置，把 Spring 相关仓库排除在外：
<mirror>
<id>my-mirror</id>
<!-- 排除 spring-snapshots 和 central-portal-snapshots 两个仓库，其余依赖仍走镜像 -->
<mirrorOf>*,!spring-snapshots,!central-portal-snapshots</mirrorOf>
<url>https://my-company-repository.com/maven</url>
</mirror>这样配置后，Maven 既能直接访问 Spring 快照仓库，其他依赖也依然使用你的公司镜像。
依赖管理
Java AI 的 BOM（Bill of Materials，依赖版本清单）声明了某个 Java AI 版本所推荐使用的全部依赖版本。这是一个「只管版本」的 BOM：它仅包含依赖版本管理信息，不含任何插件声明，也不直接引用 Spring 或 Spring Boot 本身。你可以使用 Spring Boot 的父 POM（parent POM，父级 pom 配置），或使用 Spring Boot 的 BOM（spring-boot-dependencies）来管理 Spring Boot 的版本。
将 Java AI BOM 添加到你的项目中：
Maven 配置：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.0</version> <!-- Spring AI BOM 版本 -->
<type>pom</type>
<scope>import</scope> <!-- 以 import 方式导入 BOM，统一接管版本管理 -->
</dependency>
</dependencies>
</dependencyManagement>Gradle 配置：
dependencies {
// 通过 platform 引入 Spring AI BOM，统一管理所有 Spring AI 模块的版本
implementation platform("org.springframework.ai:spring-ai-bom:2.0.0")
// 下面这行请替换成你实际想用的具体模块依赖（例如 spring-ai-openai）
// 或 starter 模块（Spring Boot Starter，开箱即用的启动器依赖，例如 spring-ai-starter-model-openai）
implementation 'org.springframework.ai:spring-ai-openai'
}白话解读
BOM 的作用说白了就是「统一管版本」：引入它之后，你在添加各个 Java AI 模块时不必再手动写版本号，框架会自动帮你对齐所有模块的版本，从根本上避免版本冲突。
Gradle 用户也可以借助 Gradle 原生的「基于 Maven BOM 声明依赖约束」能力来使用 Java AI BOM，具体做法是在 Gradle 构建脚本的 dependencies 部分使用 platform 依赖声明方法（即上例中的 platform(...) 写法）。
为具体功能组件添加依赖
文档后续各章节会分别说明：你需要往项目构建系统中添加哪些依赖，包括：
- Chat Models（聊天模型 / 对话模型）
- Embeddings Models（Embedding 模型，把文本转换成向量的模型）
- Image Generation Models（图像生成模型）
- Transcription Models（语音转录模型，把音频转成文字）
- Text-To-Speech（TTS）Models（文本转语音模型）
- Vector Databases（向量数据库，用于存储与检索向量）
白话解读
一句话总结：「用什么、加什么」。想调用哪类模型或哪个向量库，就翻到文档对应章节，照着里面的依赖坐标（groupId / artifactId）添加即可，不必一次性把所有依赖全加进来。
Java AI 示例项目
更多与 Java AI 相关的学习资源和示例代码，请参阅官方的 Java AI Samples（示例项目）页面。
AI 概念（AI Concepts）
📌 原文地址：https://docs.spring.io/java-ai/reference/concepts.html 📌 原文版本：Java AI Reference v2.0.1（Stable 稳定版）
本节介绍 Java AI 用到的核心概念。建议仔细阅读，理解 Java AI 实现背后的设计思想。
白话解读
这一页相当于 Java AI 的"入门词典 + 世界观"：一次性讲清 Model（模型）、Prompt（提示词）、Embedding（嵌入）、Token（词元）、RAG 这些高频名词，后面学 Chat Client API、Tool Calling、向量数据库等内容时才不会一头雾水。
模型（Models）
AI 模型是一类用来处理和生成信息的算法，很多方面都在模仿人类的认知功能。它们从海量数据中学习规律和洞见，进而能够做出预测、生成文字或图像等输出，在各行各业都能派上用场。
AI 模型种类繁多，各有各的用武之地。虽然 ChatGPT 凭借"文本进、文本出"的生成式 AI 能力惊艳了无数用户，但许多模型和厂商提供的输入、输出形式其实相当多样。甚至在 ChatGPT 火起来之前，Midjourney、Stable Diffusion 这类"文字生成图片"的模型就已经让人着迷了。
下面的表格按"输入 / 输出类型"对常见模型做了分类：
| 模型类型 | 输入 | 输出 | 典型示例 |
|---|---|---|---|
| Text to Text（文本转文本） | 语言 | 语言 | ChatGPT、GPT-4 等对话模型 |
| Text to Image（文本转图像） | 语言 | 图像 | Midjourney、Stable Diffusion |
| Image to Text（图像转文本） | 图像 | 语言 | 图像理解 / 视觉问答类模型 |
| Text to Speech（文本转语音） | 语言 | 音频 | OpenAI TTS、ElevenLabs 等 |
| Speech to Text（语音转文本） | 音频 | 语言 | OpenAI Transcription API 等 |
| Text Embedding（文本嵌入） | 语言 | 数字（向量） | 各家厂商的 Embedding 模型 |
Java AI 目前支持的模型，输入输出覆盖语言、图像、音频三类。上表最后一行"文本进、数字出"的做法，更常见的叫法是 text embedding（文本嵌入），它代表的是 AI 模型内部使用的数据结构。Java AI 对 Embedding 同样提供了支持，用于实现更高级的使用场景。
像 GPT 这类模型的独到之处在于"预训练"——也就是名字里的那个 "P"（Chat Generative Pre-trained Transformer，聊天生成式预训练变换器）。正是预训练这一特性，把 AI 变成了通用开发工具：开发者不需要深厚的机器学习功底、也不需要自己训练模型，就能直接上手。
Prompt（提示词）
Prompt（提示词）是基于语言的输入的基石，用来引导 AI 模型产生特定的输出。对用惯 ChatGPT 的人来说，Prompt 看起来就是对话框里敲进去、发给 API 的那段文字。但实际上远不止这么简单——在很多 AI 模型里，Prompt 的文本并不是一个简单的字符串。
ChatGPT 的 API 中，一个 Prompt 内部包含多条文本输入，每条文本都分配了一个"角色"（role）。比如 system（系统）角色，负责告诉模型该如何表现、为整个交互设定语境；还有 user（用户）角色，通常就是用户输入的内容。
写出好 Prompt 既是一门艺术，也是一门科学。ChatGPT 本来就是为"人与人对话"设计的，这跟用 SQL 去"问数据"完全是两种思路——你得像跟一个真人交流那样去和 AI 模型沟通。
这种交互方式重要到什么程度？甚至催生出一门独立学科——"Prompt Engineering（提示词工程）"，各种提升 Prompt 效果的技巧如雨后春笋般涌现。在 Prompt 上花的心思，会直接决定输出质量的天花板。
分享 Prompt 已经成为一种社区文化，学术界也在积极研究这个课题。举个能说明"写好 Prompt 有多反直觉"的例子（对比一下 SQL 就明白了）：近期有篇研究论文发现，最有效的开场白之一竟然是——"Take a deep breath and work on this step by step"（深呼吸，一步一步来）。由此可见"语言"本身有多重要。对 ChatGPT 3.5 这样的上一代技术，我们都还没完全摸透最佳用法，更别提还在不断迭代的新版本了。
白话解读
一句话总结：跟模型对话 ≠ 写 SQL 查询。把模型当成"聪明但需要明确交代的同事"，角色（system/user）、语气、步骤说得越清楚，它干得越好——连"深呼吸、一步步来"这种看似玄学的开场白都能显著提升效果。
Prompt 模板（Prompt Templates）
要写出高效的 Prompt，需要先搭好请求的上下文框架，再把其中一部分内容替换成与用户输入相关的具体值。
这个流程用的是传统的文本模板引擎来创建和管理 Prompt。Java AI 采用的开源方案是 StringTemplate 库。
举个例子，一个简单的 Prompt 模板：
Tell me a {adjective} joke about {content}.
// 告诉我一个关于 {content} 的 {adjective} 笑话。
// {adjective} 和 {content} 是占位符，运行时会被具体值替换在 Java AI 中，Prompt 模板的角色可以类比 Spring MVC 架构里的"View（视图）"。程序会传入一个模型对象（通常是 java.util.Map）来填充模板里的占位符；"渲染"出来的字符串，就是最终发给 AI 模型的 Prompt 内容。
发给模型的 Prompt，具体数据格式千差万别。它最初只是简单的字符串，后来演化为包含多条 message（消息）的结构，每条消息的字符串各自代表模型语境中的一个角色。
白话解读
类比 Web 开发：模板 + 数据 = 页面；这里就是：模板 + Map 数据 = 最终 Prompt。{adjective}、{content} 这类占位符会被 Map 里对应的值替换掉，跟 JSP / Thymeleaf 渲染页面的思路一脉相承。
Embeddings（嵌入）
Embedding（嵌入）是文本、图像或视频的数值化表示，能够捕捉输入内容之间的关系。
Embedding 的原理是：把文本、图像、视频转换成浮点数数组，这种数组叫向量（Vector）。这些向量的设计目标，就是承载原文的"含义"。Embedding 数组的长度，称为向量的维度（Dimension）。
通过计算两段文本对应的向量之间的数值距离，应用程序就能判断生成这些向量的对象有多相似。
作为探索 AI 的 Java 开发者，你不需要吃透这些向量背后的数学理论和具体实现，理解它们在 AI 系统里的角色和作用就足够了——尤其是当你只是想把 AI 功能集成进自己的应用时。
Embedding 在 Retrieval Augmented Generation（RAG，检索增强生成）这类实际应用模式里特别关键。它把数据表示成"语义空间"中的点：可以类比成欧氏几何里的二维平面，只是维度更高。就像平面上两个点可以按坐标算出远近，语义空间里点的"远近"反映的则是含义上的相似度——讲相似话题的句子会在多维空间里彼此靠近，就像图上相邻的点。这种"邻近关系"能帮上文本分类、语义搜索、甚至商品推荐等很多忙，因为 AI 可以依据概念在这片"语义地图"上的位置，来识别和归类相关内容。
你可以把这个语义空间理解为一个向量。
白话解读
白话版：Embedding 就是给每段内容发一个"数字指纹"。意思越接近，指纹越相似、距离越近。于是"找相似内容"这个语义问题，就变成了"找最近的点"这个数学问题。
Tokens（词元）
Token（词元）是 AI 模型运转的基本积木。输入时，模型把文字切分成 Token；输出时，再把 Token 还原成文字。
在英文里，1 个 Token 大约相当于 0.75 个单词。给个直观参照：莎士比亚全集约 90 万个单词，折合约 120 万个 Token。
更要紧的一点是：Token = Money（Token 就是钱）。使用托管型（云端）AI 模型时，费用按消耗的 Token 数计算，输入和输出都计入总账。
此外，模型还有 Token 上限，限制单次 API 调用能处理的文本量，这个阈值常被称为 Context Window（上下文窗口）。超出上限的文本，模型是不会处理的。
举例：ChatGPT3 的 Token 上限是 4K；GPT4 提供 8K、16K、32K 等多种规格；Anthropic 的 Claude 模型达到 100K；Meta 的最新研究甚至做出了 1M Token 上限的模型。
想让 GPT4 总结莎士比亚全集？你就得设计一套软件工程策略，把数据切块、分批塞进模型的上下文窗口。Java AI 项目就是帮你干这个活儿的。
白话解读
Token 是 AI 世界的"计价货币 + 行李限重"：账单按 Token 算，上下文窗口按 Token 限。开发时要有 Token 预算意识——数据塞不下就得切块分批处理。
结构化输出（Structured Output）
传统上，AI 模型的输出就是一个 java.lang.String 字符串——哪怕你在 Prompt 里要求它用 JSON 回答。它返回的可能确实是格式正确的 JSON 文本，但那不是 JSON 数据结构，只是一串字符串。而且，在 Prompt 里写上"请给我 JSON"，也做不到 100% 可靠。
这个麻烦催生出一个专门领域：精心设计 Prompt 让模型输出期望的格式，再把返回的纯字符串转换成应用程序能直接使用的数据结构。
Structured Output（结构化输出）的转换，依赖精心打磨的 Prompt，而且往往需要与模型多次交互，才能得到想要的格式。
白话解读
白话版：模型嘴上答应给你 JSON，实际递过来的是"写着 JSON 的纸条"（字符串）。Java AI 的 Structured Output 负责验明正身再入库：校验格式、转换成真正的 Java 对象。详见参考文档的 Structured Output（结构化输出） 章节。
把你的数据和 API 交给 AI 模型
怎么让 AI 模型掌握那些它没被训练过的信息？
冷知识
GPT 3.5 / 4.0 的训练数据只到 2021 年 9 月。因此，凡是需要这之后知识的问题，模型都会回答"不知道"。这个数据集约 650GB。
有三种技术可以把"你的数据"定制进 AI 模型：
- Fine Tuning（微调）：传统机器学习手法，通过调整模型内部权重来定制模型。但这活儿对机器学习专家来说都很难，对 GPT 这种体量的模型来说还极其耗资源。而且有些模型根本不开放微调。
- Prompt Stuffing（提示词填充，俗称"塞 Prompt"）：更实用的替代方案，把你的数据直接嵌入发给模型的 Prompt 里。考虑到模型的 Token 上限，需要一些技巧把相关数据放进上下文窗口。Java AI 库帮你实现基于这种技术的方案，它更正式的名字叫 Retrieval Augmented Generation（RAG，检索增强生成）。
- Tool Calling（工具调用）：允许注册"工具"（用户自定义的服务），把大语言模型连接到外部系统的 API。Java AI 大幅简化了支持 Tool Calling 需要写的代码。
白话解读
三招对比：Fine Tuning = "给模型做手术"（贵、难、还不一定让做）；Prompt Stuffing = "考前划重点"（把资料塞进考卷里）；Tool Calling = "开卷考试还能现场打电话查资料"（模型实时调外部 API）。
检索增强生成（RAG）
为了解决"怎么把相关数据装进 Prompt、让 AI 模型回答得更准"这个难题，业界提出了一种叫 Retrieval Augmented Generation（RAG，检索增强生成） 的技术。
这套做法采用类似批处理式的编程模型：作业先从你的文档里读取非结构化数据，进行转换，然后写入向量数据库。宏观来看，这就是一条 ETL（Extract, Transform, Load，抽取-转换-加载） 流水线。向量数据库承担的正是 RAG 技术中"检索"的那一环。
往向量数据库装数据时，最重要的转换之一是把原始文档切成小块。切分有两个关键步骤：
- 先把文档拆成若干部分，同时保住内容的语义边界。比如一份既有段落又有表格的文档，应避免从段落或表格中间"一刀切开"；对代码而言，避免从一个方法实现到一半的地方切开。
- 再把这些部分进一步切小，使每块的大小只占 AI 模型 Token 上限的一小部分。
RAG 的下一阶段是处理用户输入。当某个用户提问需要 AI 模型作答时，就把这个问题连同所有"相似"的文档块一起放进发给模型的 Prompt 里。这正是用向量数据库的原因——它极其擅长查找相似内容。
- ETL Pipeline 章节进一步介绍如何编排"从数据源抽取数据、存入结构化向量库"的流程，确保数据在传给 AI 模型时处于最适合检索的格式。
- ChatClient - RAG 章节讲解如何使用
QuestionAnswerAdvisor在你的应用中启用 RAG 能力。
白话解读
RAG 白话流程：① 离线阶段把你的文档切块、算成向量、存进向量库；② 用户提问时，拿问题去向量库"捞"最相关的几块；③ 把"问题 + 捞到的资料"一起塞进 Prompt，让模型照着资料回答。相当于给模型临时发了一份参考资料。
Tool Calling（工具调用）
大语言模型（LLM，Large Language Model）在训练完成后就"冻结"了，导致知识停留在训练截止那一刻，而且它们既访问不了、也改不了外部数据。
Tool Calling（工具调用） 机制正是为了解决这些短板。它允许你把自己的服务注册为"工具"，把大语言模型连接到外部系统的 API。这些系统既能为 LLM 提供实时数据，也能替它执行数据处理动作。
Java AI 大幅简化了支持工具调用所需的代码——工具调用的整个"对话过程"它全帮你包办。你只需把工具写成带 @Tool 注解的方法，并在 Prompt 选项中提供它，模型就能使用了。此外，你还可以在单个 Prompt 里定义并引用多个工具。
工具调用的完整流程：
- 当我们希望把某个工具提供给模型使用时，把它的定义放进 chat 请求中。每个工具定义包含：工具名称、描述、以及输入参数的 schema（参数结构定义）。
- 模型决定调用某个工具时，它会返回一个响应，其中带有工具名称和按既定 schema 组织好的输入参数。
- 应用程序负责根据工具名称找到对应工具，并用传来的输入参数执行它。
- 工具调用的结果由应用程序处理。
- 应用程序把工具调用结果发回给模型。
- 模型以工具调用结果作为额外上下文，生成最终响应。
更多关于如何在各家 AI 模型上使用该功能的细节，请参阅 Tool Calling（工具调用） 文档。
白话解读
白话版：Tool Calling 就是"模型提需求、你的代码跑腿、结果回填给模型"。模型自己不执行任何东西，它只会喊一嗓子："请帮我调 weather 工具，参数是 city=北京"，真正干活的是你的 Java 代码（@Tool 方法）。
评估 AI 响应（Evaluating AI Responses）
有效评估 AI 系统对用户请求的输出，对保证最终应用的准确性和实用性非常重要。目前已涌现出多种技术，可以借助"预训练模型本身"来完成评估。
评估过程要分析：生成的回答是否契合用户意图和提问语境。通常会用到一些量化指标来衡量 AI 回答的质量，例如相关性、连贯性、事实正确性。
一种做法是：把"用户的请求 + AI 模型的回答"一起交给模型，让它判断该回答是否与所给数据相符。
此外，把向量数据库中存储的信息当作辅助数据加以利用，可以增强评估效果，帮助判断回答的相关性。
Java AI 项目提供了 Evaluator API，目前提供若干评估模型回答的基础策略。详情请参阅 Evaluation Testing 文档。
白话解读
白话版：让 AI 给 AI 当"阅卷老师"（即 LLM-as-a-Judge 思路）。把"题目 + 答案"交给模型让它打分："这个回答靠谱吗？"Java AI 的 Evaluator API 把这套"阅卷"流程标准化了，具体用法见 Evaluation Testing 文档与 LLM-as-a-Judge Evaluation 指南。