allWords = SensitiveWordHelper.findAll(text);
// 替换敏感词
String replaced = SensitiveWordHelper.replace(text);
```
#### 3. 自定义配置
可以使用SensitiveWordBs类来自定义各种配置选项,例如:
```java theme={"system"}
SensitiveWordBs wordBs = SensitiveWordBs.newInstance()
// 使用默认的敏感词词库（黑名单）
.wordDeny(WordDenys.defaults())
// 使用默认的白名单词库，白名单中的词不会被视为敏感词，即使它们在黑名单中
.wordAllow(WordAllows.defaults())
// 忽略大小写，例如："FuCk" 和 "fuck" 将被同等对待
.ignoreCase(true)
// 忽略全角和半角字符的区别，例如："ｆｕｃｋ" 和 "fuck" 将被同等对待
.ignoreWidth(true)
// 启用连续数字检测， 可用于检测电话号码、QQ号等
.enableNumCheck(true)
// 启用邮箱地址检测，可用于过滤包含邮箱地址的文本
.enableEmailCheck(true)
// 初始化敏感词过滤器， 这一步必须在所有配置完成后调用
.init();
// 使用配置好的过滤器检查文本是否包含敏感词
boolean contains = wordBs.contains(text);
```
总的来说,sensitive-word提供了一个功能丰富、性能优秀且易于使用的敏感词过滤解决方案,适用于各种需要文本审核的场景。
**为Java开发者提供全栈式AI工程化解决方案**，强类型/高可维护性架构，内置30+主流大模型支持。
* **🔍 知识引擎体系**：RAG 知识引擎全自动化多模态解决方案
* **📝 AI-OCR 中枢**：复杂非标场景高精度识别
* **⚙️ 业务智能融合**：函数编排 + Chat2SQL，无缝对接现有业务系统
* **🛡️ N维风控体系**：敏感词/IP/Token/User 规则控制引擎
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# RAG 进阶分享
Source: https://javaai.pig4cloud.com/docs/20-rag
# [基于上下文的检索：增强 AI 模型知识检索能力](https://www.anthropic.com/news/contextual-retrieval)
![1728399617]()
# 上下文检索:显著提高RAG性能的方法
对于AI模型在特定上下文中使用,通常需要访问背景知识。例如,客户支持聊天机器人需要了解特定业务的相关知识,而法律分析师机器人则需要了解大量过往案例。
开发者通常使用检索增强生成(RAG)来增强AI模型的知识。RAG是一种从知识库中检索相关信息并将其附加到用户提示中的方法,显著增强了模型的响应。问题在于传统的RAG解决方案在编码信息时会丢失上下文,这通常会导致系统无法从知识库中检索到相关信息。
在本文中,我们概述了一种显著提高RAG检索步骤性能的方法。该方法称为"上下文检索",并使用两种子技术:上下文向量(Contextual Embeddings)和上下文BM25。这种方法可以将检索失败率降低49%,如果再结合重排序技术,甚至可以降低67%。这些表示显著的性能提升,直接提高了下游任务的性能。
你可以轻松地使用Claude部署自己的上下文检索解决方案,只需参考我们的食谱。
## 使用更长的提示的注意事项
有时候最简单的方法是最好的。如果你的知识库小于200,000个标记(大约500页的材料),你可以将整个知识库包含在提供给模型的提示中,而不需要RAG或类似的方法。
几周前,我们为Claude发布了提示缓存,使这种方法显著更快和更节省成本。开发者现在可以在API调用之间缓存经常使用的提示,将延迟减少超过2倍,并将成本降低多达90%(你可以通过阅读我们的提示缓存食谱来了解它是如何工作的)。
然而,随着你的知识库的增长,你需要一个更可扩展的解决方案。这就是上下文检索的用武之地。
## RAG:扩展到更大的知识库
对于那些不适合上下文窗口的知识库,RAG是典型的解决方案。RAG通过以下步骤预处理知识库:
1. 将知识库(文档的"语料库")分解为较小的文本块,通常不超过几百个标记;
2. 使用向量模型将这些块转换为向量向量,这些向量编码意义;
3. 将这些向量存储在允许通过语义相似性搜索的向量数据库中。
在运行时,当用户向模型输入查询时,使用向量数据库根据语义相似性找到最相关的块。然后,将最相关的块添加到发送给生成模型的提示中。
虽然向量模型在捕捉语义关系方面表现出色,但它们可能会错过关键的精确匹配。幸运的是,有一种古老的技术可以在这方面提供帮助。BM25(最佳匹配25)是一种使用词汇匹配的排名函数,用于找到精确的单词或短语匹配。它特别适用于包含唯一标识符或技术术语的查询。
BM25 通过利用 TF-IDF(词频-逆文档频率)概念来工作。TF-IDF 衡量一个词在一个集合中的文档中的重要性。BM25 通过考虑文档长度并应用饱和函数来细化这一点,该函数有助于防止常见词在结果中占据主导地位。
BM25 可以在语义向量失败的地方成功:假设用户在一个技术支持数据库中查询"错误代码 TS-999"。一个向量模型可能会找到关于错误代码的一般内容,但可能会错过确切的"TS-999"匹配。BM25 寻找这个特定的文本字符串来识别相关的文档。
RAG 解决方案可以通过使用以下步骤结合向量和 BM25 技术来更准确地检索最相关的块:
1. 将知识库(文档的"语料库")分解为较小的文本块,通常不超过几百个标记;
2. 为这些块创建 TF-IDF 编码和语义向量;
3. 使用 BM25 根据确切匹配找到顶部块;
4. 使用向量根据语义相似性找到顶部块;
5. 使用 rank fusion 技术结合和去重 (3) 和 (4) 的结果;
6. 将顶部块添加到提示中以生成响应。
通过结合 BM25 和向量模型,传统的 RAG 系统可以提供更全面和准确的结果,平衡精确的词匹配与更广泛的语义理解。
![1728481113]()
这种方法允许你有效地扩展到巨大的知识库,远远超过单个提示所能容纳的范围。但这些传统的 RAG 系统有一个显著的限制:它们经常破坏上下文。
## 传统RAG中的上下文困境
在传统的 RAG 中,文档通常被拆分为较小的块以进行高效检索。虽然这种方法对许多应用效果很好,但当单个块缺乏足够的上下文时,可能会导致问题。
例如,想象一下,你的知识库中包含了一个财务信息集合(例如,美国 SEC 文件),并且你收到了以下问题:"ACME 公司在 2023 年第二季度的收入增长是多少?"
一个相关的块可能包含以下文本:"公司收入比上一季度增长了 3%。" 然而,这个块本身没有指明它指的是哪家公司或相关时间范围,这使得很难检索到正确的信息或有效地使用信息。
## 引入上下文检索
上下文检索通过在每个块之前添加特定于块的解释性上下文,在向量("上下文向量")和创建 BM25 索引("上下文 BM25")之前解决了这个问题。
让我们回到我们的 SEC 文件集合示例。以下是一个块可能被转换的方式:
```
original_chunk = "公司收入比上一季度增长了 3%。"
contextualized_chunk = "该段落摘自ACME公司2023年第二季度的SEC文件；上一季度的收入为3.14亿美元。该公司的收入比上一季度增长了3%。"
```
值得注意的是,其他方法已经提出使用上下文来提高检索性能。其他建议包括:在块中添加通用文档摘要(我们尝试过并发现效果有限),假设文档向量,以及基于摘要的索引(我们评估过并发现性能较低)。这些方法与本文提出的方法不同。
## 实现上下文检索
当然,手动注释知识库中的数千甚至数百万个块将是一项极其繁重的工作。为了实现上下文检索,我们求助于Claude。我们已经编写了一个提示,指示模型提供简洁的、块特定的上下文,使用整个文档的上下文解释块。我们使用以下Claude 3 Haiku提示为每个块生成上下文:
```
{{WHOLE_DOCUMENT}}
Here is the chunk we want to situate within the whole document
{{CHUNK_CONTENT}}
Please give a short succinct context to situate this chunk within the overall document for the purposes of improving search retrieval of the chunk. Answer only with the succinct context and nothing else.
```
生成的上下文文本,通常为50-100个标记,在向量之前和创建BM25索引之前附加到块。
以下是预处理流程的实际应用:
![1728481126]()
## 使用提示缓存减少上下文检索的成本
上下文检索在Claude中以低成本实现,得益于上述的特殊提示缓存功能。使用提示缓存,你不需要为每个块传递参考文档。你只需将文档加载到缓存中一次,然后引用之前缓存的内容。假设每个块有800个标记,8k标记的文档,50个标记的上下文指令,每个块有100个标记的上下文,生成上下文块的一次性成本为每百万文档标记1.02美元。
## 方法论
我们尝试了各种知识领域(代码库、小说、ArXiv论文、科学论文)、向量模型、检索策略和评估指标。我们在附录II中包含了一些我们用于每个领域的示例问题和答案。
下图显示了所有知识领域中所有向量配置的平均性能,使用最佳向量配置(Gemini Text 004)检索前20个块。我们使用1减去召回@20作为评估指标,该指标测量在20个块中未检索到的相关文档的百分比。你可以在附录中查看完整的结果——上下文化在所有评估的向量源组合中都提高了性能。
## 性能提升
我们的实验表明:
* 上下文向量将前20个块的检索失败率降低了35% (5.7% → 3.7%).
* 结合上下文向量和上下文BM25将前20个块的检索失败率降低了49% (5.7% → 2.9%).
![1728481137]()
## 实现考虑
在实现上下文检索时,有几点需要考虑:
* Chunk boundaries: 考虑如何将文档拆分为块。块大小、块边界和块重叠的选择会影响检索性能。
* Embedding model: 上下文检索在所有测试的向量模型中都提高了性能,但某些模型可能比其他模型表现更好。我们发现 Gemini 和 Voyage 向量特别有效。
* Custom contextualizer prompts: 虽然我们提供的通用提示效果很好,但你可以使用针对特定领域或用例的提示来实现更好的结果(例如,包括一个可能只在知识库中的其他文档中定义的关键术语词汇表)。
* Number of chunks: 将更多块添加到上下文窗口中会增加包含相关信息的机会。然而,更多的信息可能会分散模型的注意力,因此有一个限制。我们尝试了5、10和20个块,发现使用20个块是这些选项中性能最好的(见附录中的比较),但值得在特定用例上进行实验。
* Always run evals: 响应生成可以通过传递上下文块并区分上下文和块来改进。
## 进一步提高性能的重排序
在最后一步中,我们可以将上下文检索与另一种技术结合使用,以获得更多的性能提升。在传统的RAG中,AI系统搜索其知识库以找到可能相关的信息块。使用大型知识库时,此初始检索通常会返回大量块——有时多达数百个,具有不同的相关性和重要性。
重排序是一种常用的过滤技术,可以确保只将最相关的块传递给模型。重排序提供更好的响应并减少成本和延迟,因为模型处理的信息更少。关键步骤如下:
1. 执行初始检索以获取可能相关的顶部块(我们使用前150个);
2. 将前N个块和用户的查询传递给重排序模型;
3. 使用重排序模型,根据其与提示的相关性和重要性为每个块打分,然后选择前K个块(我们使用前20个);
4. 将前K个块传递给模型作为上下文,以生成最终结果。
![1728481149]()
### 性能提升
市场上有几种重排序模型。我们使用 Cohere 重排序器进行了测试。Voyage 也提供了一个重排序器,但我们没有时间测试它。我们的实验表明,在各种领域中,添加重排序步骤可以进一步优化检索。
具体来说,我们发现重排序的上下文向量和上下文 BM25 将前 20 个块的检索失败率降低了 67%(5.7% → 1.9%)。
![1728481154]()
### 成本和延迟考虑
重排序的一个重要考虑因素是对延迟和成本的影响，特别是在重排序大量块时。由于重排序在运行时添加了额外的步骤，即使重排序器并行对所有块进行评分，它也不可避免地会增加一些延迟。在重排序更多块以获得更好性能与重排序更少块以降低延迟和成本之间存在固有的权衡。我们建议在您的特定用例上尝试不同的设置，以找到合适的平衡点。
## 结论
我们进行了大量测试，比较了上述所有技术的不同组合（向量模型、使用 BM25、使用上下文检索、使用重排序器以及检索的前 K 个结果总数），涵盖了各种不同的数据集类型。以下是我们的发现总结：
1. 向量+BM25 比单独使用向量更好；
2. 在我们测试的向量中，Voyage 和 Gemini 的效果最好；
3. 将前 20 个块传递给模型比仅传递前 10 个或前 5 个更有效；
4. 为块添加上下文大大提高了检索准确性；
5. 使用重排序比不使用重排序更好；
6. **所有这些优势都可以叠加**：为了最大化性能提升，我们可以结合上下文向量（来自 Voyage 或 Gemini）、上下文 BM25、重排序步骤，并将 20 个块添加到提示中。
我们鼓励所有使用知识库的开发者使用**我们的指南**来尝试这些方法，以解锁新的性能水平。
## 附录 I
以下是各数据集、向量提供商、是否使用 BM25 补充向量、是否使用上下文检索以及是否使用重排序的前 20 个检索结果的细分。
有关前 10 个和前 5 个检索结果的细分以及每个数据集的示例问题和答案，请参见**附录 II**。
![1728481176]()
*各数据集和向量提供商的 1 减去召回率 @ 20 的结果。*
**为Java开发者提供全栈式AI工程化解决方案**，强类型/高可维护性架构，内置30+主流大模型支持。
* **🔍 知识引擎体系**：RAG 知识引擎全自动化多模态解决方案
* **📝 AI-OCR 中枢**：复杂非标场景高精度识别
* **⚙️ 业务智能融合**：函数编排 + Chat2SQL，无缝对接现有业务系统
* **🛡️ N维风控体系**：敏感词/IP/Token/User 规则控制引擎
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 增强器 API
Source: https://javaai.pig4cloud.com/spring-ai/api/advisors
Spring AI 增强器 API 提供了一种灵活而强大的方式来拦截、修改和增强 Spring 应用程序中的 AI 驱动交互。
通过利用增强器 API，开发者可以创建更复杂、可重用和可维护的 AI 组件。
主要优势包括封装重复出现的生成式 AI 模式、转换发送到大型语言模型（LLM） 的数据，以及提供跨各种模型和用例的可移植性。
您可以使用 [ChatClient API](/spring4ai/api/chatclient#advisor-configuration-in-chatclient) 配置现有增强器，如下例所示：
```java theme={"system"}
var chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(), // chat-memory 增强器
QuestionAnswerAdvisor.builder((vectorStore).builder() // RAG 增强器
)
.build();
var conversationId = "678";
String response = this.chatClient.prompt()
// 在运行时设置增强器参数
.advisors(advisor -> advisor.param(ChatMemory.CONVERSATION_ID, conversationId))
.user(userText)
.call()
.content();
```
建议在构建时使用 builder 的 `defaultAdvisors()` 方法注册增强器。
增强器也参与可观察性堆栈，因此您可以查看与其执行相关的指标和跟踪。
* [了解问题回答增强器](/spring4ai/api/retrieval-augmented-generation#questionansweradvisor)
* [了解聊天内存增强器](/spring4ai/api/chat-memory#memory-in-chat-client)
## 核心组件
API 包含用于非流式场景的 `CallAroundAdvisor` 和 `CallAroundAdvisorChain`，以及用于流式场景的 `StreamAroundAdvisor` 和 `StreamAroundAdvisorChain`。
它还包括 `AdvisedRequest` 用于表示未密封的 Prompt 请求，`AdvisedResponse` 用于 Chat Completion 响应。两者都包含一个 `advise-context` 用于在增强器链中共享状态。
![]()
`nextAroundCall()` 和 `nextAroundStream()` 是关键增强器方法，通常执行诸如检查未密封的 Prompt 数据、自定义和增强 Prompt 数据、调用增强器链中的下一个实体、可选地阻止请求、检查聊天完成响应以及抛出异常以指示处理错误等操作。
此外，`getOrder()` 方法确定增强器在链中的顺序，而 `getName()` 提供唯一的增强器名称。
由 Spring AI 框架创建的增强器链允许按 `getOrder()` 值排序的多个增强器顺序调用。
较低的值首先执行。
最后一个增强器（自动添加）将请求发送到 LLM。
以下流程图说明了增强器链与聊天模型之间的交互：
![]()
Spring AI 框架从用户的 `Prompt` 创建一个 `AdvisedRequest`，同时创建一个空的 `AdvisorContext` 对象。
链中的每个增强器处理请求，可能会修改它。或者，它可以选择通过不调用下一个实体来阻止请求。在后一种情况下，增强器负责填写响应。
框架提供的最后一个增强器将请求发送到 `Chat Model`。
聊天模型的响应然后通过增强器链传回并转换为 `AdvisedResponse`。后者包括共享的 `AdvisorContext` 实例。
每个增强器可以处理或修改响应。
通过提取 `ChatCompletion` 将最终的 `AdvisedResponse` 返回给客户端。
### 增强器顺序
增强器在链中的执行顺序由 `getOrder()` 方法决定。需要理解的关键点：
* 具有较低顺序值的增强器首先执行。
* 增强器链作为堆栈运行：
* 链中的第一个增强器首先处理请求。
* 它也是最后一个处理响应的。
* 要控制执行顺序：
* 将顺序设置为接近 `Ordered.HIGHEST_PRECEDENCE` 以确保增强器在链中首先执行（首先处理请求，最后处理响应）。
* 将顺序设置为接近 `Ordered.LOWEST_PRECEDENCE` 以确保增强器在链中最后执行（最后处理请求，首先处理响应）。
* 较高的值被解释为较低的优先级。
* 如果多个增强器具有相同的顺序值，它们的执行顺序不能保证。
执行顺序和顺序值之间的表面矛盾是由于增强器链的堆栈性质：
* 具有最高优先级（最低顺序值）的增强器被添加到堆栈顶部。
* 当堆栈展开时，它将首先处理请求。
* 当堆栈重绕时，它将最后处理响应。
作为提醒，以下是 Spring `Ordered` 接口的语义：
```java theme={"system"}
public interface Ordered {
/**
* 最高优先级值的常量。
* @see java.lang.Integer#MIN_VALUE
*/
int HIGHEST_PRECEDENCE = Integer.MIN_VALUE;
/**
* 最低优先级值的常量。
* @see java.lang.Integer#MAX_VALUE
*/
int LOWEST_PRECEDENCE = Integer.MAX_VALUE;
/**
* 获取此对象的顺序值。
* 较高的值被解释为较低的优先级。因此，
* 具有最低值的对象具有最高优先级（有点类似于 Servlet {@code load-on-startup} 值）。
*
相同的顺序值将导致受影响对象的任意排序位置。
* @return 顺序值
* @see #HIGHEST_PRECEDENCE
* @see #LOWEST_PRECEDENCE
*/
int getOrder();
}
```
对于需要在输入和输出端都是链中第一个的用例：
1. 为每一端使用单独的增强器。
2. 使用不同的顺序值配置它们。
3. 使用增强器上下文在它们之间共享状态。
## API 概述
主要增强器接口位于包 `org.springframework.ai.chat.client.advisor.api` 中。以下是创建自己的增强器时会遇到的关键接口：
```java theme={"system"}
public interface Advisor extends Ordered {
String getName();
}
```
同步和响应式增强器的两个子接口是：
```java theme={"system"}
public interface CallAroundAdvisor extends Advisor {
/**
* 环绕通知，包装 ChatModel#call(Prompt) 方法。
* @param advisedRequest 建议的请求
* @param chain 增强器链
* @return 响应
*/
AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain);
}
```
和
```java theme={"system"}
public interface StreamAroundAdvisor extends Advisor {
/**
* 环绕通知，包装建议请求的调用。
* @param advisedRequest 建议的请求
* @param chain 要执行的增强器链
* @return 建议请求的结果
*/
Flux aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain);
}
```
要继续建议链，在您的建议实现中使用 `CallAroundAdvisorChain` 和 `StreamAroundAdvisorChain`：
接口是：
```java theme={"system"}
public interface CallAroundAdvisorChain {
AdvisedResponse nextAroundCall(AdvisedRequest advisedRequest);
}
```
和
```java theme={"system"}
public interface StreamAroundAdvisorChain {
Flux nextAroundStream(AdvisedRequest advisedRequest);
}
```
## 实现增强器
要创建增强器，实现 `CallAroundAdvisor` 或 `StreamAroundAdvisor`（或两者）。要实现的关键方法是用于非流式的 `nextAroundCall()` 或用于流式增强器的 `nextAroundStream()`。
### 示例
我们将提供一些实践示例来说明如何实现用于观察和增强用例的增强器。
#### 日志增强器
我们可以实现一个简单的日志增强器，在调用链中的下一个增强器之前记录 `AdvisedRequest`，之后记录 `AdvisedResponse`。
注意，增强器只观察请求和响应，不修改它们。
此实现同时支持非流式和流式场景。
```java theme={"system"}
public class SimpleLoggerAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {
private static final Logger logger = LoggerFactory.getLogger(SimpleLoggerAdvisor.class);
@Override
public String getName() { // (1)
return this.getClass().getSimpleName();
}
@Override
public int getOrder() { // (2)
return 0;
}
@Override
public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) {
logger.debug("BEFORE: {}", advisedRequest);
AdvisedResponse advisedResponse = chain.nextAroundCall(advisedRequest);
logger.debug("AFTER: {}", advisedResponse);
return advisedResponse;
}
@Override
public Flux aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) {
logger.debug("BEFORE: {}", advisedRequest);
Flux advisedResponses = chain.nextAroundStream(advisedRequest);
return new MessageAggregator().aggregateAdvisedResponse(advisedResponses,
advisedResponse -> logger.debug("AFTER: {}", advisedResponse)); // (3)
}
}
```
1. 为增强器提供唯一名称。
2. 您可以通过设置顺序值来控制执行顺序。较低的值首先执行。
3. `MessageAggregator` 是一个实用类，将 Flux 响应聚合为单个 AdvisedResponse。这对于记录或观察整个响应而不是流中的单个项目的其他处理很有用。注意，您不能在 `MessageAggregator` 中修改响应，因为它是只读操作。
#### 重读 (Re2) 增强器
"[Re-Reading Improves Reasoning in Large Language Models](https://arxiv.org/pdf/2309.06275)" 文章介绍了一种称为重读 (Re2) 的技术，可以提高大型语言模型的推理能力。
Re2 技术要求像这样增强输入提示：
```
{Input_Query}
Read the question again: {Input_Query}
```
实现一个将 Re2 技术应用于用户输入查询的增强器可以这样做：
```java theme={"system"}
public class ReReadingAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {
private AdvisedRequest before(AdvisedRequest advisedRequest) { // (1)
Map advisedUserParams = new HashMap<>(advisedRequest.userParams());
advisedUserParams.put("re2_input_query", advisedRequest.userText());
return AdvisedRequest.from(advisedRequest)
.userText("""
{re2_input_query}
Read the question again: {re2_input_query}
""")
.userParams(advisedUserParams)
.build();
}
@Override
public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) { // (2)
return chain.nextAroundCall(this.before(advisedRequest));
}
@Override
public Flux aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) { // (3)
return chain.nextAroundStream(this.before(advisedRequest));
}
@Override
public int getOrder() { // (4)
return 0;
}
@Override
public String getName() { // (5)
return this.getClass().getSimpleName();
}
}
```
1. `before` 方法通过应用重读技术增强用户的输入查询。
2. `aroundCall` 方法拦截非流式请求并应用重读技术。
3. `aroundStream` 方法拦截流式请求并应用重读技术。
4. 您可以通过设置顺序值来控制执行顺序。较低的值首先执行。
5. 为增强器提供唯一名称。
### Spring AI 内置增强器
Spring AI 框架提供了几个内置增强器来增强您的 AI 交互。以下是可用增强器的概述：
这些增强器在聊天内存存储中管理对话历史：
检索内存并将其作为消息集合添加到提示中。这种方法保持了对话历史的结构。注意，并非所有 AI 模型都支持这种方法。
检索内存并将其合并到提示的系统文本中。
从 VectorStore 检索内存并将其添加到提示的系统文本中。此增强器对于从大型数据集中高效搜索和检索相关信息很有用。
此增强器使用向量存储来提供问答功能，实现 RAG（检索增强生成）模式。
一个简单的增强器，旨在防止模型生成有害或不适当的内容。
### 流式与非流式
![]()
* 非流式增强器处理完整的请求和响应。
* 流式增强器将请求和响应作为连续流处理，使用响应式编程概念（例如，用于响应的 Flux）。
实现带有阻塞和非阻塞代码的流式增强器的示例：
```java theme={"system"}
@Override
public Flux aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) {
return Mono.just(advisedRequest)
.publishOn(Schedulers.boundedElastic())
.map(request -> {
// 这可以由阻塞和非阻塞线程执行。
// 增强器在下一个部分之前
})
.flatMapMany(request -> chain.nextAroundStream(request))
.map(response -> {
// 增强器在下一个部分之后
});
}
```
### 最佳实践
保持增强器专注于特定任务以获得更好的模块化。
必要时使用 `adviseContext` 在增强器之间共享状态。
实现增强器的流式和非流式版本以获得最大灵活性。
仔细考虑增强器在链中的顺序以确保正确的数据流。
## 向后兼容性
`AdvisedRequest` 类已移动到新包。
## API 重大变更
Spring AI 增强器链从版本 1.0 M2 到 1.0 M3 经历了重大变化。以下是主要修改：
### 增强器接口
* 单独的 `RequestAdvisor` 和 `ResponseAdvisor` 接口
* `RequestAdvisor` 在 `ChatModel.call` 和 `ChatModel.stream` 方法之前调用
* `ResponseAdvisor` 在这些方法之后调用
* 使用 `StreamResponseMode` 作为 `ResponseAdvisor` 的一部分
* 替换为 `CallAroundAdvisor` 和 `StreamAroundAdvisor`
* 已移除 `StreamResponseMode`
### 上下文映射处理
* 上下文映射是一个单独的方法参数
* 映射是可变的并沿链传递
* 上下文映射现在是 `AdvisedRequest` 和 `AdvisedResponse` 记录的一部分
* 映射是不可变的
* 要更新上下文，使用 `updateContext` 方法，它创建一个具有更新内容的新不可变映射
在 1.0 M3 中更新上下文的示例：
```java theme={"system"}
@Override
public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) {
this.advisedRequest = advisedRequest.updateContext(context -> {
context.put("aroundCallBefore" + getName(), "AROUND_CALL_BEFORE " + getName()); // 添加多个键值对
context.put("lastBefore", getName()); // 添加单个键值对
return context;
});
// 方法实现继续...
}
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 音频模型
Source: https://javaai.pig4cloud.com/spring-ai/api/audio
Spring AI 支持的音频模型概述
# 音频模型
Spring AI 通过不同的提供商提供各种音频处理功能支持。音频功能主要分为两个主要类别：
## 转录
使用各种 AI 模型将语音转换为文本：
* [Azure OpenAI 转录](/api/audio/transcriptions/azure-openai-transcriptions)
* [OpenAI 转录](/api/audio/transcriptions/openai-transcriptions)
## 语音合成
将文本转换为语音：
* [OpenAI 语音](/api/audio/speech/openai-speech)
每个提供商都为其各自的音频处理功能实现了特定的接口，使您能够在保持一致的 API 的同时使用不同的 AI 模型。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 语音合成
Source: https://javaai.pig4cloud.com/spring-ai/api/audio/speech
Spring AI 文本转语音功能概述
# 语音合成
Spring AI 支持通过各种 AI 模型将文本转换为语音。以下是当前支持的实现：
## 支持的提供商
* [OpenAI Speech](/spring4ai/api/audio/speech/openai-speech)
每个提供商都实现了特定的语音合成接口，允许您使用不同的 AI 模型将文本转换为语音，同时保持一致的 API。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OpenAI 语音
Source: https://javaai.pig4cloud.com/spring-ai/api/audio/speech/openai-speech
使用 OpenAI 的 TTS 模型进行文本转语音
# OpenAI 语音
Spring AI 集成了 OpenAI 的文本转语音 (TTS) 模型，以实现语音合成功能。
## 配置
将以下依赖项添加到您的项目中：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-spring-boot-starter
```
## 属性
```properties theme={"system"}
spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.speech.model=tts-1
```
## 用法
```java theme={"system"}
@Autowired
private SpeechClient speechClient;
// 生成语音
SpeechResponse response = speechClient.call(
new SpeechPrompt("你好，这是一个文本转语音系统的测试。")
);
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 音频转录
Source: https://javaai.pig4cloud.com/spring-ai/api/audio/transcriptions
Spring AI 音频转录功能概述
# 音频转录
Spring AI 支持通过各种 AI 模型将语音转换为文本。以下是当前支持的实现：
## 支持的提供商
* [Azure OpenAI Transcriptions](/spring4ai/api/audio/transcriptions/azure-openai-transcriptions)
* [OpenAI Transcriptions](/spring4ai/api/audio/transcriptions/openai-transcriptions)
每个提供商都实现了特定的音频转录接口，允许您使用不同的 AI 模型将语音转换为文本，同时保持一致的 API。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Azure OpenAI 转录
Source: https://javaai.pig4cloud.com/spring-ai/api/audio/transcriptions/azure-openai-transcriptions
使用 Azure OpenAI 的 Whisper 模型进行语音转文本
# Azure OpenAI 转录
Spring AI 集成了 Azure OpenAI 的 Whisper 模型，以实现语音转文本功能。
## 配置
将以下依赖项添加到您的项目中：
```xml theme={"system"}
org.springframework.ai
spring-ai-azure-openai-spring-boot-starter
```
## 属性
```properties theme={"system"}
spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.openai.audio.model=whisper-1
```
## 用法
```java theme={"system"}
@Autowired
private TranscriptionClient transcriptionClient;
// 转录音频
TranscriptionResponse response = transcriptionClient.call(
new TranscriptionPrompt(audioFile)
);
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OpenAI 转录
Source: https://javaai.pig4cloud.com/spring-ai/api/audio/transcriptions/openai-transcriptions
使用 OpenAI 的 Whisper 模型进行语音转文本
# OpenAI 转录
Spring AI 集成了 OpenAI 的 Whisper 模型，以实现语音转文本功能。
## 配置
将以下依赖项添加到您的项目中：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-spring-boot-starter
```
## 属性
```properties theme={"system"}
spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.audio.model=whisper-1
```
## 用法
```java theme={"system"}
@Autowired
private TranscriptionClient transcriptionClient;
// 转录音频
TranscriptionResponse response = transcriptionClient.call(
new TranscriptionPrompt(audioFile)
);
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 聊天记忆
Source: https://javaai.pig4cloud.com/spring-ai/api/chat-memory
Spring AI 中的聊天记忆提供了维护 AI 聊天应用程序的对话上下文和历史的机制。
## 概述
聊天记忆使 AI 应用程序能够：
* 维护对话历史
* 提供上下文感知的响应
* 实现不同的记忆策略
* 管理对话状态
## 记忆类型
用于开发和测试的简单内存存储
用于生产环境的数据库支持存储
用于可扩展应用程序的分布式存储
用于特定需求的自定义存储实现
## 实现
### 基本配置
```java theme={"system"}
@Configuration
public class ChatMemoryConfig {
@Bean
public ChatMemory chatMemory() {
return new InMemoryChatMemory();
}
}
```
### 使用聊天记忆
```java theme={"system"}
@Service
public class ChatService {
private final ChatClient chatClient;
private final ChatMemory chatMemory;
public ChatService(ChatClient chatClient, ChatMemory chatMemory) {
this.chatClient = chatClient;
this.chatMemory = chatMemory;
}
public String chat(String message, String sessionId) {
// 将消息添加到记忆中
chatMemory.addMessage(sessionId, message);
// 获取对话历史
List history = chatMemory.getMessages(sessionId);
// 使用上下文生成响应
String response = chatClient.generate(history);
// 将响应存储在记忆中
chatMemory.addMessage(sessionId, response);
return response;
}
}
```
## 记忆策略
### 1. 固定窗口记忆
```java theme={"system"}
@Bean
public ChatMemory fixedWindowMemory() {
return new FixedWindowChatMemory(10); // 保留最后10条消息
}
```
### 2. 基于令牌的记忆
```java theme={"system"}
@Bean
public ChatMemory tokenBasedMemory() {
return new TokenBasedChatMemory(1000); // 在令牌限制内保留消息
}
```
### 3. 摘要记忆
```java theme={"system"}
@Bean
public ChatMemory summaryMemory() {
return new SummaryChatMemory(summarizer);
}
```
## 配置属性
```properties theme={"system"}
spring.ai.chat.memory.type=in-memory
spring.ai.chat.memory.max-messages=100
spring.ai.chat.memory.max-tokens=1000
spring.ai.chat.memory.ttl=3600
```
## 最佳实践
在实现聊天记忆时，请考虑以下最佳实践：
* **记忆大小**：根据您的用例选择适当的记忆大小
* **持久化**：在生产环境中使用持久化存储
* **清理**：为旧对话实现适当的清理机制
* **安全性**：确保适当的数据保护和隐私措施
* **可扩展性**：考虑为高规模应用程序使用分布式记忆
## 高级功能
### 自定义记忆实现
```java theme={"system"}
@Component
public class CustomChatMemory implements ChatMemory {
@Override
public void addMessage(String sessionId, String message) {
// 自定义实现
}
@Override
public List getMessages(String sessionId) {
// 自定义实现
return messages;
}
}
```
### 记忆监控
监控记忆使用情况和性能：
```properties theme={"system"}
management.endpoints.web.exposure.include=chat-memory
management.endpoint.chat-memory.enabled=true
```
## 故障排除
常见问题和解决方案：
1. **内存泄漏**
* 实现适当的清理
* 设置适当的 TTL
* 监控内存使用情况
2. **性能问题**
* 使用适当的记忆类型
* 实现缓存
* 优化存储
3. **可扩展性**
* 使用分布式记忆
* 实现适当的分区
* 考虑缓存策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Anthropic Claude 3 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/anthropic-chat
[Anthropic Claude](https://www.anthropic.com/) 是一系列基础 AI 模型，可用于各种应用程序。
对于开发人员和企业，你可以利用 API 访问权限并直接在 [Anthropic 的 AI 基础设施](https://www.anthropic.com/api)之上进行构建。
Spring AI 支持 Anthropic [消息传递 API](https://docs.anthropic.com/claude/reference/messages_post) 进行同步和流式文本生成。
Anthropic 的 Claude 模型也可通过 Amazon Bedrock Converse 获得。
Spring AI 还提供专用的 [Amazon Bedrock Converse Anthropic](/spring4ai/api/chat/bedrock-converse) 客户端实现。
## 前提条件
你需要在 Anthropic 门户上创建一个 API 密钥。
在 [Anthropic API 仪表板](https://console.anthropic.com/dashboard)创建一个帐户，并在[获取 API 密钥](https://console.anthropic.com/settings/keys)页面生成 API 密钥。
Spring AI 项目定义了一个名为 `spring.ai.anthropic.api-key` 的配置属性，你应该将其设置为从 anthropic.com 获取的 `API 密钥` 的值。
你可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.anthropic.api-key=<你的-anthropic-api-密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
spring:
ai:
anthropic:
api-key: ${ANTHROPIC_API_KEY}
```
```bash theme={"system"}
export ANTHROPIC_API_KEY=<你的-anthropic-api-密钥>
```
你也可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("ANTHROPIC_API_KEY");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Anthropic 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-anthropic
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-anthropic'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 Anthropic 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :----------------------------------------- | :------------------------------------------------------------- | :---- |
| `spring.ai.retry.max-attempts` | 最大重试次数。 | 10 |
| `spring.ai.retry.backoff.initial-interval` | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| `spring.ai.retry.backoff.multiplier` | 退避间隔乘数。 | 5 |
| `spring.ai.retry.backoff.max-interval` | 最大退避持续时间。 | 3 分钟 |
| `spring.ai.retry.on-client-errors` | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| `spring.ai.retry.exclude-on-http-codes` | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| `spring.ai.retry.on-http-codes` | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
目前，重试策略不适用于流式 API。
#### 连接属性
前缀 `spring.ai.anthropic` 用作属性前缀，允许你连接到 Anthropic。
| 属性 | 描述 | 默认值 |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------- |
| `spring.ai.anthropic.base-url` | 要连接的 URL | `https://api.anthropic.com` |
| `spring.ai.anthropic.completions-path` | 要附加到基本 URL 的路径。 | `/v1/chat/completions` |
| `spring.ai.anthropic.version` | Anthropic API 版本 | `2023-06-01` |
| `spring.ai.anthropic.api-key` | API 密钥 | - |
| `spring.ai.anthropic.beta-version` | 启用新的/实验性功能。如果设置为 `max-tokens-3-5-sonnet-2024-07-15` \n输出令牌限制从 `4096` 增加到 `8192` 个令牌（仅适用于 claude-3-5-sonnet）。 | `tools-2024-04-04` |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=anthropic` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 anthropic 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.anthropic.chat` 是属性前缀，允许你配置 Anthropic 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------- |
| `spring.ai.anthropic.chat.enabled` (已移除) | 启用 Anthropic 聊天模型。 | true |
| `spring.ai.model.chat` | 启用 Anthropic 聊天模型。 | anthropic |
| `spring.ai.anthropic.chat.options.model` | 这是要使用的 Anthropic 聊天模型。支持：`claude-3-7-sonnet-latest`、`claude-3-5-sonnet-latest`、`claude-3-opus-20240229`、`claude-3-sonnet-20240229`、`claude-3-haiku-20240307` | `claude-3-7-sonnet-latest` |
| `spring.ai.anthropic.chat.options.temperature` | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改温度和 top\_p，因为这两个设置的相互作用很难预测。 | 0.8 |
| `spring.ai.anthropic.chat.options.max-tokens` | 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | 500 |
| `spring.ai.anthropic.chat.options.stop-sequence` | 模型将停止生成的自定义文本序列。我们的模型通常会在自然完成其回合时停止，这将导致响应 stop\_reason 为"end\_turn"。如果你希望模型在遇到自定义文本字符串时停止生成，则可以使用 stop\_sequences 参数。如果模型遇到自定义序列之一，则响应 stop\_reason 值将为"stop\_sequence"，响应 stop\_sequence 值将包含匹配的停止序列。 | - |
| `spring.ai.anthropic.chat.options.top-p` | 使用核采样。在核采样中，我们计算后续每个标记的所有选项的累积分布（按概率降序排列），并在达到 top\_p 指定的特定概率时将其截断。你应该更改温度或 top\_p，但不能同时更改两者。建议仅用于高级用例。通常只需要使用温度。 | - |
| `spring.ai.anthropic.chat.options.top-k` | 仅从后续每个标记的前 K 个选项中采样。用于删除"长尾"低概率响应。在此处了解更多技术细节。建议仅用于高级用例。通常只需要使用温度。 | - |
| `spring.ai.anthropic.chat.options.toolNames` | 在单个提示请求中启用工具调用的工具列表（按其名称标识）。具有这些名称的工具必须存在于 toolCallbacks 注册表中。 | - |
| `spring.ai.anthropic.chat.options.toolCallbacks` | 要注册到 ChatModel 的工具回调。 | - |
| `spring.ai.anthropic.chat.options.internal-tool-execution-enabled` | 如果为 false，Spring AI 将不会在内部处理工具调用，而是将它们代理到客户端。然后由客户端负责处理工具调用，将它们分派到适当的函数，并返回结果。如果为 true（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | true |
| (**已弃用**) `spring.ai.anthropic.chat.options.functions` | 在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
| (**已弃用**) `spring.ai.anthropic.chat.options.functionCallbacks` | 要注册到 ChatModel 的工具函数回调。 | - |
| (**已弃用**) `spring.ai.anthropic.chat.options.proxy-tool-calls` | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
| `spring.ai.anthropic.chat.options.http-headers` | 要添加到聊天补全请求的可选 HTTP 标头。 | - |
所有以 `spring.ai.anthropic.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[运行时选项](#runtime-options)来覆盖。
## 运行时选项
[AnthropicChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java) 提供模型配置，例如要使用的模型、温度、最大令牌数等。
在启动时，可以使用 `AnthropicChatModel(api, options)` 构造函数或 `spring.ai.anthropic.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
AnthropicChatOptions.builder()
.model("claude-3-7-sonnet-latest")
.temperature(0.4)
.build()
));
```
除了特定于模型的 [AnthropicChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 工具/函数调用
你可以使用 `AnthropicChatModel` 注册自定义 Java 工具，并让 Anthropic Claude 模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关[工具调用](/spring4ai/api/tools)的更多信息。
## 多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、pdf、图像、数据格式。
### 图像
目前，Anthropic Claude 3 支持 `base64` 源类型的 `图像`，以及 `image/jpeg`、`image/png`、`image/gif` 和 `image/webp` 媒体类型。
有关更多信息，请查看[视觉指南](https://docs.anthropic.com/claude/docs/vision)。
Anthropic Claude 3.5 Sonnet 还支持 `application/pdf` 文件的 `pdf` 源类型。
Spring AI 的 `Message` 接口通过引入 Media 类型来支持多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和信息，使用 Spring 的 `org.springframework.util.MimeType` 和 `java.lang.Object` 来获取原始媒体数据。
以下是从 [AnthropicChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/AnthropicChatModelIT.java) 中提取的简单代码示例，演示了用户文本与图像的组合。
```java theme={"system"}
var imageData = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage("解释一下你在这张图片上看到了什么？",
List.of(new Media(MimeTypeUtils.IMAGE_PNG, this.imageData)));
ChatResponse response = chatModel.call(new Prompt(List.of(this.userMessage)));
logger.info(response.getResult().getOutput().getContent());
```
它将 `multimodal.test.png` 图像作为输入：
![]()
以及文本消息"解释一下你在这张图片上看到了什么？"，并生成如下响应：
```
图片显示了一个装满水果的金属丝水果篮的特写视图。
...
```
### PDF
从 Sonnet 3.5 开始，提供了 [PDF 支持（测试版）](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support)。
使用 `application/pdf` 媒体类型将 PDF 文件附加到消息：
```java theme={"system"}
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)));
```
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-anthropic` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 Anthropic 聊天模型：
```properties theme={"system"}
spring.ai.anthropic.api-key=你的API密钥
spring.ai.anthropic.chat.options.model=claude-3-5-sonnet-latest
spring.ai.anthropic.chat.options.temperature=0.7
spring.ai.anthropic.chat.options.max-tokens=450
```
将 `api-key` 替换为你的 Anthropic 凭据。
这将创建一个 `AnthropicChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成。
```java theme={"system"}
@RestController
public class ChatController {
private final AnthropicChatModel chatModel;
@Autowired
public ChatController(AnthropicChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
[AnthropicChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用[低级 AnthropicApi 客户端](#low-level-anthropicapi-client)连接到 Anthropic 服务。
将 `spring-ai-anthropic` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-anthropic
```
或添加到你的 Gradle `build.gradle` 构建文件中。
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-anthropic'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
接下来，创建一个 `AnthropicChatModel` 并将其用于文本生成：
```java theme={"system"}
var anthropicApi = new AnthropicApi(System.getenv("ANTHROPIC_API_KEY"));
var chatModel = new AnthropicChatModel(this.anthropicApi,
AnthropicChatOptions.builder()
.model("claude-3-opus-20240229")
.temperature(0.4)
.maxTokens(200)
.build());
ChatResponse response = this.chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux response = this.chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
`AnthropicChatOptions` 为聊天请求提供配置信息。
`AnthropicChatOptions.Builder` 是流畅的选项构建器。
## 低级 AnthropicApi 客户端
[AnthropicApi](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/AnthropicApi.java) 提供了轻量级的 Java 客户端，用于 [Anthropic 消息 API](https://docs.anthropic.com/claude/reference/messages_post)。
以下类图说明了 `AnthropicApi` 聊天接口和构建块：
![]()
![]()
以下是一个简单的代码片段，展示了如何以编程方式使用 API：
```java theme={"system"}
AnthropicApi anthropicApi =
new AnthropicApi(System.getenv("ANTHROPIC_API_KEY"));
AnthropicMessage chatCompletionMessage = new AnthropicMessage(
List.of(new ContentBlock("给我讲个笑话？")), Role.USER);
// 同步请求
ResponseEntity response = this.anthropicApi
.chatCompletionEntity(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_3_OPUS.getValue(),
List.of(this.chatCompletionMessage), null, 100, 0.8, false));
// 流式请求
Flux response = this.anthropicApi
.chatCompletionStream(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_3_OPUS.getValue(),
List.of(this.chatCompletionMessage), null, 100, 0.8, true));
```
有关更多信息，请参阅 [AnthropicApi.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/api/AnthropicApi.java) 的 JavaDoc。
### 低级 API 示例
* [AnthropicApiIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/chat/api/AnthropicApiIT.java) 测试提供了一些有关如何使用轻量级库的常规示例。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Azure OpenAI 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/azure-openai-chat
Azure 的 OpenAI 产品由 ChatGPT 提供支持，超越了传统的 OpenAI 功能，提供具有增强功能的 AI 驱动文本生成。Azure 提供额外的 AI 安全和负责任的 AI 功能，如其最近的更新[此处](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/announcing-new-ai-safety-amp-responsible-ai-features-in-azure/ba-p/3983686)所述。
Azure 为 Java 开发人员提供了通过将其与一系列 Azure 服务（包括 Azure 上的向量存储等 AI 相关资源）集成来充分利用 AI 潜力的机会。
## 前提条件
Azure OpenAI 客户端提供三种连接选项：使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。
### Azure API 密钥和终结点
要使用 API 密钥访问模型，请从 [Azure 门户](https://portal.azure.com)上的 Azure OpenAI 服务部分获取你的 Azure OpenAI `endpoint` 和 `api-key`。
Spring AI 定义了两个配置属性：
1. `spring.ai.azure.openai.api-key`：将其设置为从 Azure 获取的 `API 密钥` 的值。
2. `spring.ai.azure.openai.endpoint`：将其设置为在 Azure 中配置模型时获取的终结点 URL。
你可以在 `application.properties` 或 `application.yml` 文件中设置这些配置属性：
```properties theme={"system"}
spring.ai.azure.openai.api-key=<你的-azure-api-密钥>
spring.ai.azure.openai.endpoint=<你的-azure-终结点-url>
```
```yaml theme={"system"}
spring:
ai:
azure:
openai:
api-key: ${AZURE_OPENAI_API_KEY}
endpoint: ${AZURE_OPENAI_ENDPOINT}
```
```bash theme={"system"}
export AZURE_OPENAI_API_KEY=<你的-azure-openai-api-密钥>
export AZURE_OPENAI_ENDPOINT=<你的-azure-openai-终结点-url>
```
### OpenAI 密钥
要向 OpenAI 服务（而非 Azure）进行身份验证，请提供 OpenAI API 密钥。这会自动将终结点设置为 [https://api.openai.com/v1。](https://api.openai.com/v1。)
使用此方法时，请将 `spring.ai.azure.openai.chat.options.deployment-name` 属性设置为要使用的 [OpenAI 模型](https://platform.openai.com/docs/models)的名称。
在你的应用程序配置中：
```properties theme={"system"}
spring.ai.azure.openai.openai-api-key=<你的-azure-openai-密钥>
spring.ai.azure.openai.chat.options.deployment-name=
```
```yaml theme={"system"}
spring:
ai:
azure:
openai:
openai-api-key: ${AZURE_OPENAI_API_KEY}
chat:
options:
deployment-name: ${AZURE_OPENAI_MODEL_NAME}
```
```bash theme={"system"}
export AZURE_OPENAI_API_KEY=<你的-openai-密钥>
export AZURE_OPENAI_MODEL_NAME=
```
### Microsoft Entra ID
要使用 Microsoft Entra ID（以前称为 Azure Active Directory）进行无密钥身份验证，请\_仅\_设置 `spring.ai.azure.openai.endpoint` 配置属性，而\_不\_设置上面提到的 api-key 属性。
仅找到终结点属性后，你的应用程序将评估几个不同的凭据检索选项，并使用令牌凭据创建 `OpenAIClient` 实例。
不再需要创建 `TokenCredential` bean；它会自动为你配置。
### 部署名称
要使用 Azure AI 应用程序，你需要通过 [Azure AI 门户](https://oai.azure.com/portal)创建一个 Azure AI 部署。
在 Azure 中，每个客户端都必须指定一个 `Deployment Name` 才能连接到 Azure OpenAI 服务。
需要注意的是，`Deployment Name` 与你选择部署的模型不同。
例如，名为"MyAiDeployment"的部署可以配置为使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。
要开始使用，请按照以下步骤使用默认设置创建部署：
部署名称：`gpt-4o`
模型名称：`gpt-4o`
此 Azure 配置与 Spring Boot Azure AI Starter 及其自动配置功能的默认配置一致。
如果你使用不同的部署名称，请确保相应地更新配置属性：
```properties theme={"system"}
spring.ai.azure.openai.chat.options.deployment-name=<我的部署名称>
```
Azure OpenAI 和 OpenAI 的不同部署结构导致 Azure OpenAI 客户端库中有一个名为 `deploymentOrModelName` 的属性。
这是因为在 OpenAI 中没有 `Deployment Name`，只有 `Model Name`。
属性 `spring.ai.azure.openai.chat.options.model` 已重命名为 `spring.ai.azure.openai.chat.options.deployment-name`。
如果你决定通过设置 `spring.ai.azure.openai.openai-api-key=<你的 OpenAI 密钥>` 属性来连接到 `OpenAI` 而不是 `Azure OpenAI`，
那么 `spring.ai.azure.openai.chat.options.deployment-name` 将被视为 [OpenAI 模型](https://platform.openai.com/docs/models)名称。
#### 访问 OpenAI 模型
你可以将客户端配置为直接使用 `OpenAI`，而不是 `Azure OpenAI` 部署的模型。
为此，你需要设置 `spring.ai.azure.openai.openai-api-key=<你的 OpenAI 密钥>` 而不是 `spring.ai.azure.openai.api-key=<你的 Azure OpenAi 密钥>`。
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Azure OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-azure-openai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
Azure OpenAI 聊天客户端是使用 Azure SDK 提供的 [OpenAIClientBuilder](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/openai/azure-ai-openai/src/main/java/com/azure/ai/openai/OpenAIClientBuilder.java) 创建的。Spring AI 允许通过提供 [AzureOpenAIClientBuilderCustomizer](https://github.com/spring-projects/spring-ai/blob/main/auto-configurations/models/spring-ai-autoconfigure-model-azure-openai/src/main/java/org/springframework/ai/model/azure/openai/autoconfigure/AzureOpenAIClientBuilderCustomizer.java) bean 来自定义构建器。
例如，可以使用自定义程序来更改默认响应超时：
```java theme={"system"}
@Configuration
public class AzureOpenAiConfig {
@Bean
public AzureOpenAIClientBuilderCustomizer responseTimeoutCustomizer() {
return openAiClientBuilder -> {
HttpClientOptions clientOptions = new HttpClientOptions()
.setResponseTimeout(Duration.ofMinutes(5));
openAiClientBuilder.httpClient(HttpClient.createDefault(clientOptions));
};
}
}
```
### 聊天属性
前缀 `spring.ai.azure.openai` 是用于配置与 Azure OpenAI 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-- |
| `spring.ai.azure.openai.api-key` | Azure AI OpenAI `密钥和终结点` 部分（在 `资源管理` 下）中的密钥 | - |
| `spring.ai.azure.openai.endpoint` | Azure AI OpenAI `密钥和终结点` 部分（在 `资源管理` 下）中的终结点 | - |
| `spring.ai.azure.openai.openai-api-key` | （非 Azure）OpenAI API 密钥。用于向 OpenAI 服务（而非 Azure OpenAI）进行身份验证。这会自动将终结点设置为 [https://api.openai.com/v1。使用](https://api.openai.com/v1。使用) `api-key` 或 `openai-api-key` 属性。使用此配置时，`spring.ai.azure.openai.chat.options.deployment-name` 将被视为 [OpenAi 模型](https://platform.openai.com/docs/models)名称。 | - |
| `spring.ai.azure.openai.custom-headers` | 要包含在 API 请求中的自定义标头映射。映射中的每个条目代表一个标头，其中键是标头名称，值是标头值。 | 空映射 |
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=azure-openai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 azure-openai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.azure.openai.chat` 是配置 Azure OpenAI 的 `ChatModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- |
| `spring.ai.azure.openai.chat.enabled` (已移除且不再有效) | 启用 Azure OpenAI 聊天模型。 | true |
| `spring.ai.model.chat` | 启用 Azure OpenAI 聊天模型。 | azure-openai |
| `spring.ai.azure.openai.chat.options.deployment-name` | 在 Azure 中使用时，这指的是模型的"部署名称"，你可以在 [https://oai.azure.com/portal](https://oai.azure.com/portal) 中找到它。需要注意的是，在 Azure OpenAI 部署中，"部署名称"与模型本身不同。围绕这些术语的混淆源于使 Azure OpenAI 客户端库与原始 OpenAI 终结点兼容的意图。Azure OpenAI 和 Sam Altman 的 OpenAI 提供的部署结构有显著差异。部署模型名称作为此补全请求的一部分提供。 | gpt-4o |
| `spring.ai.azure.openai.chat.options.maxTokens` | 要生成的最大标记数。 | - |
| `spring.ai.azure.openai.chat.options.temperature` | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改温度和 top\_p，因为这两个设置的相互作用很难预测。 | 0.7 |
| `spring.ai.azure.openai.chat.options.topP` | 温度采样的替代方法，称为核采样。此值使模型考虑具有所提供概率质量的标记的结果。 | - |
| `spring.ai.azure.openai.chat.options.logitBias` | GPT 令牌 ID 和偏差分数之间的映射，影响特定令牌出现在补全响应中的概率。令牌 ID 通过外部令牌化工具计算，而偏差分数在 -100 到 100 的范围内，最小值和最大值分别对应于完全禁止或独占选择令牌。给定偏差分数的具体行为因模型而异。 | - |
| `spring.ai.azure.openai.chat.options.user` | 操作的调用方或最终用户的标识符。这可用于跟踪或速率限制目的。 | - |
| `spring.ai.azure.openai.chat.options.stream-usage` | （仅限流式传输）设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 `choices` 字段是一个空数组，所有其他块也将包含一个 usage 字段，但其值为 null。 | false |
| `spring.ai.azure.openai.chat.options.n` | 应为聊天补全响应生成的聊天补全选项的数量。 | - |
| `spring.ai.azure.openai.chat.options.stop` | 将结束补全生成的文本序列集合。 | - |
| `spring.ai.azure.openai.chat.options.presencePenalty` | 一个影响生成令牌出现概率的值，基于它们在生成文本中已有的存在。正值会使令牌在已存在时不太可能出现，并增加模型输出新主题的可能性。 | - |
| `spring.ai.azure.openai.chat.options.responseFormat` | 指定模型必须输出的格式的对象。使用 `AzureOpenAiResponseFormat.JSON` 启用 JSON 模式，可确保模型生成的消息是有效的 JSON。使用 AzureOpenAiResponseFormat.TEXT 启用 TEXT 模式。 | - |
| `spring.ai.azure.openai.chat.options.frequencyPenalty` | 一个影响生成令牌出现概率的值，基于它们在生成文本中的累积频率。正值会使令牌随着频率的增加而不太可能出现，并降低模型逐字重复相同语句的可能性。 | - |
| `spring.ai.azure.openai.chat.options.proxy-tool-calls` | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
所有以 `spring.ai.azure.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[运行时选项](#runtime-options)来覆盖。
## 运行时选项
[AzureOpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `AzureOpenAiChatModel(api, options)` 构造函数或 `spring.ai.azure.openai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
AzureOpenAiChatOptions.builder()
.deploymentName("gpt-4o")
.temperature(0.4)
.build()
));
```
除了特定于模型的 [AzureOpenAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 函数调用
你可以使用 AzureOpenAiChatModel 注册自定义 Java 函数，并让模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关[工具调用](/spring4ai/api/tools)的更多信息。
## 多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。
目前，Azure OpenAI `gpt-4o` 模型提供多模态支持。
Azure OpenAI 可以将 base64 编码的图像或图像 URL 列表与消息合并。
Spring AI 的 [Message](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/messages/Message.java) 接口通过引入 [Media](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/model/Media.java) 类型来促进多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和详细信息，利用 Spring 的 `org.springframework.util.MimeType` 和 `java.lang.Object` 来获取原始媒体数据。
以下是从 [OpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/c9a3e66f90187ce7eae7eb78c462ec622685de6c/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/OpenAiChatModelIT.java#L293) 中摘录的代码示例，说明了使用 `GPT_4_O` 模型将用户文本与图像融合。
```java theme={"system"}
URL url = new URL("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png");
String response = ChatClient.create(chatModel).prompt()
.options(AzureOpenAiChatOptions.builder().deploymentName("gpt-4o").build())
.user(u -> u.text("解释一下你在这张图片上看到了什么？").media(MimeTypeUtils.IMAGE_PNG, this.url))
.call()
.content();
```
你也可以传递多个图像。
它将 `multimodal.test.png` 图像作为输入：
![]()
以及文本消息"解释一下你在这张图片上看到了什么？"，并生成如下响应：
```
这是一张水果盘的图片，设计简单。碗由金属制成，带有弯曲的金属丝边缘，
形成开放式结构，可以从各个角度看到水果。碗里，两根香蕉放在一个看起来像是红苹果的水果上面。
香蕉有点过熟，表皮上有褐色的斑点。碗的顶部有一个金属环，可能是用来提携的。
碗放在一个平坦的表面上，背景颜色中性，可以清楚地看到里面的水果。
```
你也可以传入类路径资源而不是 URL，如下例所示：
```java theme={"system"}
Resource resource = new ClassPathResource("multimodality/multimodal.test.png");
String response = ChatClient.create(chatModel).prompt()
.options(AzureOpenAiChatOptions.builder()
.deploymentName("gpt-4o").build())
.user(u -> u.text("解释一下你在这张图片上看到了什么？")
.media(MimeTypeUtils.IMAGE_PNG, this.resource))
.call()
.content();
```
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-azure-openai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OpenAi 聊天模型：
```properties theme={"system"}
spring.ai.azure.openai.api-key=你的API密钥
spring.ai.azure.openai.endpoint=你的终结点
spring.ai.azure.openai.chat.options.deployment-name=gpt-4o
spring.ai.azure.openai.chat.options.temperature=0.7
```
将 `api-key` 和 `endpoint` 替换为你的 Azure OpenAI 凭据。
这将创建一个 `AzureOpenAiChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成：
```java theme={"system"}
@RestController
public class ChatController {
private final AzureOpenAiChatModel chatModel;
@Autowired
public ChatController(AzureOpenAiChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
[AzureOpenAiChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用 [Azure OpenAI Java 客户端](https://learn.microsoft.com/en-us/java/api/overview/azure/ai-openai-readme?view=azure-java-preview)。
要启用它，请将 `spring-ai-azure-openai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-azure-openai
```
或添加到你的 Gradle `build.gradle` 构建文件中：
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-azure-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
`spring-ai-azure-openai` 依赖项还提供对 `AzureOpenAiChatModel` 的访问。有关 `AzureOpenAiChatModel` 的更多信息，请参阅 [Azure OpenAI 聊天](/spring4ai/api/chat/azure-openai-chat)部分。
接下来，创建一个 `AzureOpenAiChatModel` 实例并将其用于生成文本响应：
```java theme={"system"}
var openAIClientBuilder = new OpenAIClientBuilder()
.credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"));
var openAIChatOptions = AzureOpenAiChatOptions.builder()
.deploymentName("gpt-4o")
.temperature(0.4)
.maxTokens(200)
.build();
var chatModel = AzureOpenAiChatModel.builder()
.openAIClientBuilder(openAIClientBuilder)
.defaultOptions(openAIChatOptions)
.build();
ChatResponse response = chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux streamingResponses = chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
`gpt-4o` 实际上是 Azure AI 门户中显示的`部署名称`。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Bedrock Converse API
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/bedrock-converse
[Amazon Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html) 为对话式 AI 模型提供统一接口，具有增强功能，包括函数/工具调用、多模态输入和流式响应。
Bedrock Converse API 具有以下高级功能：
支持对话期间的函数定义和工具使用
能够在对话中处理文本和图像输入
模型响应的实时流式传输
支持系统级指令和上下文设置
Bedrock Converse API 在多个模型提供商之间提供统一接口，同时处理特定于 AWS 的身份验证和基础设施问题。
目前，Converse API [支持的模型](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html)包括：
`Amazon Titan`、`Amazon Nova`、`AI21 Labs`、`Anthropic Claude`、`Cohere Command`、`Meta Llama`、`Mistral AI`。
根据 Bedrock 的建议，Spring AI 正在过渡到使用 Amazon Bedrock 的 Converse API 来实现 Spring AI 中的所有聊天对话。
虽然现有的 [InvokeModel API](/spring4ai/api/bedrock-chat) 支持对话应用程序，但我们强烈建议为所有聊天对话模型采用 Converse API。
Converse API 不支持嵌入操作，因此这些操作将保留在当前 API 中，并且现有 `InvokeModel API` 中的嵌入模型功能将得到维护。
## 前提条件
有关设置 API 访问权限，请参阅[Amazon Bedrock 入门](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html)。
如果你还没有 AWS 账户和配置好的 AWS CLI，此视频指南可以帮助你进行配置：[不到 4 分钟完成 AWS CLI 和 SDK 设置！](https://youtu.be/gswVHTrRX8I?si=buaY7aeI0l3-bBVb)。你应该能够获取你的访问密钥和安全密钥。
转到 [Amazon Bedrock](https://us-east-1.console.aws.amazon.com/bedrock/home) 并从左侧的[模型访问](https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/modelaccess)菜单中，配置对要使用的模型的访问权限。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
将 `spring-ai-starter-model-bedrock-converse` 依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-bedrock-converse
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-bedrock-converse'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
前缀 `spring.ai.bedrock.aws` 是用于配置与 AWS Bedrock 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------ | :---------------- | :-------- |
| `spring.ai.bedrock.aws.region` | 要使用的 AWS 区域。 | us-east-1 |
| `spring.ai.bedrock.aws.timeout` | 要使用的 AWS 超时。 | 5m |
| `spring.ai.bedrock.aws.access-key` | AWS 访问密钥。 | - |
| `spring.ai.bedrock.aws.secret-key` | AWS 秘密密钥。 | - |
| `spring.ai.bedrock.aws.session-token` | 用于临时凭证的 AWS 会话令牌。 | - |
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=bedrock-converse` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 bedrock-converse 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.bedrock.converse.chat` 是配置 Converse API 聊天模型实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `spring.ai.bedrock.converse.chat.enabled` (已移除) | 启用 Bedrock Converse 聊天模型。 | true |
| `spring.ai.model.chat` | 启用 Bedrock Converse 聊天模型。 | bedrock-converse |
| `spring.ai.bedrock.converse.chat.options.model` | 要使用的模型 ID。你可以使用[支持的模型和模型功能](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html) | 无。从 AWS Bedrock 控制台选择你的 [modelId](https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/models)。 |
| `spring.ai.bedrock.converse.chat.options.temperature` | 控制输出的随机性。值范围为 \[0.0,1.0] | 0.8 |
| `spring.ai.bedrock.converse.chat.options.top-p` | 采样时要考虑的最大累积概率标记。 | AWS Bedrock 默认值 |
| `spring.ai.bedrock.converse.chat.options.top-k` | 用于生成下一个标记的标记选项数。 | AWS Bedrock 默认值 |
| `spring.ai.bedrock.converse.chat.options.max-tokens` | 生成响应中的最大标记数。 | 500 |
## 运行时选项
使用可移植的 `ChatOptions` 或 `ToolCallingChatOptions` 可移植构建器来创建模型配置，例如温度、最大令牌数、topP 等。
在启动时，可以使用 `BedrockConverseProxyChatModel(api, options)` 构造函数或 `spring.ai.bedrock.converse.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项：
```java theme={"system"}
var options = ToolCallingChatOptions.builder()
.model("anthropic.claude-3-5-sonnet-20240620-v1:0")
.temperature(0.6)
.maxTokens(300)
.toolCallbacks(List.of(FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
.description("获取某个位置的天气。以 36°F 或 36°C 格式返回温度。如果需要，请使用多轮对话。")
.inputType(WeatherService.Request.class)
.build()))
.build();
String response = ChatClient.create(this.chatModel)
.prompt("阿姆斯特丹现在天气怎么样？")
.options(options)
.call()
.content();
```
## 工具调用
Bedrock Converse API 支持工具调用功能，允许模型在对话期间使用工具。
以下是如何定义和使用基于 @Tool 的工具的示例：
```java theme={"system"}
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 作为工具：
```java theme={"system"}
@Bean
@Description("获取某个位置的天气。以 36°F 或 36°C 格式返回温度。")
public Function weatherFunction() {
return new MockWeatherService();
}
String response = ChatClient.create(this.chatModel)
.prompt("波士顿的天气怎么样？")
.tools("weatherFunction")
.inputType(Request.class)
.call()
.content();
```
在[工具](/spring4ai/api/tools)文档中查找更多信息。
## 多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、视频、pdf、doc、html、md 和更多数据格式。
Bedrock Converse API 支持多模态输入，包括文本和图像输入，并且可以根据组合输入生成文本响应。
你需要一个支持多模态输入的模型，例如 Anthropic Claude 或 Amazon Nova 模型。
### 图像
对于支持视觉多模态的[模型](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html)（例如 Amazon Nova、Anthropic Claude、Llama 3.2），Bedrock Converse API Amazon 允许你在有效负载中包含多个图像。这些模型可以分析传递的图像并回答问题、对图像进行分类，以及根据提供的说明对图像进行总结。
目前，Bedrock Converse 支持 `image/jpeg`、`image/png`、`image/gif` 和 `image/webp` mime 类型的 `base64` 编码图像。
Spring AI 的 `Message` 接口通过引入 `Media` 类型来支持多模态 AI 模型。
它包含有关消息中媒体附件的数据和信息，使用 Spring 的 `org.springframework.util.MimeType` 和 `java.lang.Object` 来获取原始媒体数据。
以下是一个简单的代码示例，演示了用户文本与图像的组合。
```java theme={"system"}
String response = ChatClient.create(chatModel)
.prompt()
.user(u -> u.text("解释一下你在这张图片上看到了什么？")
.media(Media.Format.IMAGE_PNG, new ClassPathResource("/test.png")))
.call()
.content();
logger.info(response);
```
它将 `test.png` 图像作为输入：
![]()
以及文本消息“解释一下你在这张图片上看到了什么？”，并生成如下响应：
```
图片显示了一个装满水果的金属丝水果篮的特写视图。
...
```
### 视频
[Amazon Nova 模型](https://docs.aws.amazon.com/nova/latest/userguide/modalities-video.html)允许你在有效负载中包含单个视频，该视频可以以 base64 格式或通过 Amazon S3 URI 提供。
目前，Bedrock Nova 支持 `video/x-matros`、`video/quicktime`、`video/mp4`、`video/video/webm`、`video/x-flv`、`video/mpeg`、`video/x-ms-wmv` 和 `image/3gpp` mime 类型的图像。
Spring AI 的 `Message` 接口通过引入 `Media` 类型来支持多模态 AI 模型。
它包含有关消息中媒体附件的数据和信息，使用 Spring 的 `org.springframework.util.MimeType` 和 `java.lang.Object` 来获取原始媒体数据。
以下是一个简单的代码示例，演示了用户文本与视频的组合。
```java theme={"system"}
String response = ChatClient.create(chatModel)
.prompt()
.user(u -> u.text("解释一下你在这段视频中看到了什么？")
.media(Media.Format.VIDEO_MP4, new ClassPathResource("/test.video.mp4")))
.call()
.content();
logger.info(response);
```
它将 `test.video.mp4` 图像作为输入：
![]()
以及文本消息“解释一下你在这段视频中看到了什么？”，并生成如下响应：
```
视频显示一群小鸡，也称为雏鸡，挤在一块表面上
...
```
### 文档
对于某些模型，Bedrock 允许你通过 Converse API 文档支持在有效负载中包含文档，这些文档可以以字节形式提供。
文档支持有两种不同的变体，如下所述：
（txt、csv、html、md 等），重点是文本理解。这些用例包括基于文档的文本元素进行回答。
（pdf、docx、xlsx），重点是基于视觉的理解来回答问题。这些用例包括基于图表、图形等回答问题。
目前，Anthropic [PDF 支持（测试版）](https://docs.anthropic.com/en/docs/build-with-claude/pdf-support)和 Amazon Bedrock Nova 模型支持文档多模态。
以下是一个简单的代码示例，演示了用户文本与媒体文档的组合。
```java theme={"system"}
String response = ChatClient.create(chatModel)
.prompt()
.user(u -> u.text(
"你是一位非常专业的文档摘要专家。请总结给定的文档。")
.media(Media.Format.DOC_PDF, new ClassPathResource("/spring-ai-reference-overview.pdf")))
.call()
.content();
logger.info(response);
```
它将 `spring-ai-reference-overview.pdf` 文档作为输入：
![]()
以及文本消息“你是一位非常专业的文档摘要专家。请总结给定的文档。”，并生成如下响应：
```
**简介：**
- Spring AI 旨在简化具有人工智能 (AI) 功能的应用程序的开发，旨在避免不必要的复杂性。
...
```
## 示例控制器
创建一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-bedrock-converse` 添加到你的依赖项中。
在 `src/main/resources` 下添加一个 `application.properties` 文件：
```properties theme={"system"}
spring.ai.bedrock.aws.region=eu-central-1
spring.ai.bedrock.aws.timeout=10m
spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID}
spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY}
# 仅临时凭证需要会话令牌
spring.ai.bedrock.aws.session-token=${AWS_SESSION_TOKEN}
spring.ai.bedrock.converse.chat.options.temperature=0.8
spring.ai.bedrock.converse.chat.options.top-k=15
```
以下是使用聊天模型的示例控制器：
```java theme={"system"}
@RestController
public class ChatController {
private final ChatClient chatClient;
@Autowired
public ChatController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
return Map.of("generation", this.chatClient.prompt(message).call().content());
}
@GetMapping("/ai/generateStream")
public Flux generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
return this.chatClient.prompt(message).stream().content();
}
}
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
```
# 聊天模型比较
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/comparison
下表比较了 Spring AI 支持的各种聊天模型，详细说明了它们的功能：
* [多模态](/spring4ai/api/multimodality)：模型可以处理的输入类型（例如，文本、图像、音频、视频）。
* [工具/函数调用](/spring4ai/api/tools)：模型是否支持函数调用或工具使用。
* 流式传输：模型是否提供流式响应。
* 重试：支持重试机制。
* [可观察性](/spring4ai/observability)：用于监控和调试的功能。
* [内置 JSON](/spring4ai/api/structured-output-converter#built-in-json-mode)：对 JSON 输出的原生支持。
* 本地部署：模型是否可以在本地运行。
* OpenAI API 兼容性：模型是否与 OpenAI 的 API 兼容。
| 提供商 | 多模态 | 工具/函数 | 流式传输 | 重试 | 可观察性 | 内置 JSON | 本地 | OpenAI API 兼容性 |
| :----------------------------------------------------------------- | :------------------------------------ | :-------------------- | :-------------------- | :-------------------- | :-------------------- | :-------------------- | :-------------------- | :-------------------- |
| [Anthropic Claude](/spring4ai/api/chat/anthropic-chat) | 文本、pdf、图像 | | | | | | | |
| [Azure OpenAI](/spring4ai/api/chat/azure-openai-chat) | 文本、图像 | | | | | | | |
| [DeepSeek (OpenAI-proxy)](/spring4ai/api/chat/deepseek-chat) | 文本 | | | | | | | |
| [Google VertexAI Gemini](/spring4ai/api/chat/vertexai-gemini-chat) | 文本、pdf、图像、音频、视频 | | | | | | | |
| [Groq (OpenAI-proxy)](/spring4ai/api/chat/groq-chat) | 文本、图像 | | | | | | | |
| [HuggingFace](/spring4ai/api/chat/huggingface) | 文本 | | | | | | | |
| [Mistral AI](/spring4ai/api/chat/mistralai-chat) | 文本、图像 | | | | | | | |
| [MiniMax](/spring4ai/api/chat/minimax-chat) | 文本 | | | | | | | |
| [Moonshot AI](/spring4ai/api/chat/moonshot-chat) | 文本 | | | | | | | |
| [NVIDIA (OpenAI-proxy)](/spring4ai/api/chat/nvidia-chat) | 文本、图像 | | | | | | | |
| [OCI GenAI/Cohere](/spring4ai/api/chat/oci-genai/cohere-chat) | 文本 | | | | | | | |
| [Ollama](/spring4ai/api/chat/ollama-chat) | 文本、图像 | | | | | | | |
| [OpenAI](/spring4ai/api/chat/openai-chat) | 输入：文本、图像、音频
输出：文本、音频 | | | | | | | |
| [Perplexity (OpenAI-proxy)](/spring4ai/api/chat/perplexity-chat) | 文本 | | | | | | | |
| [QianFan](/spring4ai/api/chat/qianfan-chat) | 文本 | | | | | | | |
| [ZhiPu AI](/spring4ai/api/chat/zhipuai-chat) | 文本 | | | | | | | |
| [Amazon Bedrock Converse](/spring4ai/api/chat/bedrock-converse) | 文本、图像、视频、文档 (pdf, html, md, docx ...) | | | | | | | |
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# DeepSeek 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/deepseek-chat
[DeepSeek](https://platform.deepseek.com/) 提供各种 AI 语言模型，你可以使用它们来创建多语言会话助手。Spring AI 与 DeepSeek 的模型集成，为构建 AI 驱动的应用程序提供无缝体验。
![]()
## 前提条件
要在 Spring AI 中开始使用 DeepSeek，你需要：
1. 在 [DeepSeek 注册页面](https://platform.deepseek.com/sign_up)创建一个帐户
2. 在 [API 密钥页面](https://platform.deepseek.com/api_keys)生成一个 API 密钥
3. 在你的 Spring AI 项目中配置 API 密钥
你可以在 `application.properties` 文件中设置 API 密钥配置：
```properties theme={"system"}
spring.ai.deepseek.api-key=<你的-deepseek-api-密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
spring:
ai:
deepseek:
api-key: ${DEEPSEEK_API_KEY}
```
```bash theme={"system"}
export DEEPSEEK_API_KEY=<你的-deepseek-api-密钥>
```
你也可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("DEEPSEEK_API_KEY");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Spring Milestone 和 Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 为 DeepSeek 聊天模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-deepseek
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-deepseek'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 DeepSeek 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.deepseek` 用作属性前缀，允许你连接到 DeepSeek。
| 属性 | 描述 | 默认值 |
| :-------------------------- | :------- | :--------------------------------------------------- |
| spring.ai.deepseek.base-url | 要连接的 URL | [https://api.deepseek.com](https://api.deepseek.com) |
| spring.ai.deepseek.api-key | API 密钥 | - |
#### 配置属性
前缀 `spring.ai.deepseek.chat` 是属性前缀，允许你配置 DeepSeek 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :----------------------------------------------- | :------------------------------------------------ | :----------------------------------------------------- |
| spring.ai.deepseek.chat.enabled | 启用 DeepSeek 聊天模型。 | true |
| spring.ai.deepseek.chat.base-url | 可选地覆盖 spring.ai.deepseek.base-url 以提供特定于聊天的 URL | [https://api.deepseek.com/](https://api.deepseek.com/) |
| spring.ai.deepseek.chat.api-key | 可选地覆盖 spring.ai.deepseek.api-key 以提供特定于聊天的 API 密钥 | - |
| spring.ai.deepseek.chat.completions-path | 聊天补全端点的路径 | /chat/completions |
| spring.ai.deepseek.chat.beta-prefix-path | Beta 功能端点的前缀路径 | /beta/chat/completions |
| spring.ai.deepseek.chat.options.model | 要使用的模型的 ID。你可以使用 deepseek-coder 或 deepseek-chat。 | deepseek-chat |
| spring.ai.deepseek.chat.options.frequencyPenalty | -2.0 到 2.0 之间的数字。正值会根据新标记在文本中已有的频率对其进行惩罚。 | 0.0f |
| spring.ai.deepseek.chat.options.maxTokens | 在聊天补全中生成的最大标记数。 | - |
| spring.ai.deepseek.chat.options.presencePenalty | -2.0 到 2.0 之间的数字。正值会根据新标记是否已出现在文本中对其进行惩罚。 | 0.0f |
| spring.ai.deepseek.chat.options.stop | API 将停止生成更多标记的最多 4 个序列。 | - |
| spring.ai.deepseek.chat.options.temperature | 采样温度在 0 到 2 之间。较高的值（如 0.8）会使输出更随机。 | 1.0F |
| spring.ai.deepseek.chat.options.topP | 核采样的温度替代方案。值在 0 到 1 之间。 | 1.0F |
| spring.ai.deepseek.chat.options.logprobs | 是否返回输出标记的对数概率。 | - |
| spring.ai.deepseek.chat.options.topLogprobs | 与对数概率一起返回的最可能标记的数量 (0-20)。 | - |
你可以为 `ChatModel` 实现覆盖通用的 `spring.ai.deepseek.base-url` 和 `spring.ai.deepseek.api-key`。
如果设置了 `spring.ai.deepseek.chat.base-url` 和 `spring.ai.deepseek.chat.api-key` 属性，则它们优先于通用属性。
如果你想为不同的模型和不同的模型端点使用不同的 DeepSeek 帐户，这将非常有用。
所有以 `spring.ai.deepseek.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的运行时选项来覆盖。
## 运行时选项
[DeepSeekChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-deepseek/src/main/java/org/springframework/ai/deepseek/DeepSeekChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `DeepSeekChatModel(api, options)` 构造函数或 `spring.ai.deepseek.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
````java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。请提供 JSON 响应，不要包含任何代码块标记，例如 ```json```。",
DeepSeekChatOptions.builder()
.withModel(DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue())
.withTemperature(0.8f)
.build()
));
````
除了特定于模型的 [DeepSeekChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-deepseek/src/main/java/org/springframework/ai/deepseek/DeepSeekChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-core/src/main/java/org/springframework/ai/chat/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-core/src/main/java/org/springframework/ai/chat/ChatOptions.java) 实例。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-deepseek` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 DeepSeek 聊天模型：
```properties theme={"system"}
spring.ai.deepseek.api-key=你的API密钥
spring.ai.deepseek.chat.options.model=deepseek-chat
spring.ai.deepseek.chat.options.temperature=0.8
```
将 `api-key` 替换为你的 DeepSeek 凭据。
这将创建一个 `DeepSeekChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成：
```java theme={"system"}
@RestController
public class ChatController {
private final DeepSeekChatModel chatModel;
@Autowired
public ChatController(DeepSeekChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
return Map.of("generation", chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
var prompt = new Prompt(new UserMessage(message));
return chatModel.stream(prompt);
}
}
```
## 聊天前缀补全
聊天前缀补全遵循聊天补全 API，用户提供助手的消息前缀，模型补全消息的其余部分。
使用前缀补全时，用户必须确保消息列表中的最后一条消息是 DeepSeekAssistantMessage。
以下是聊天前缀补全的完整 Java 代码示例。在此示例中，我们将助手的消息前缀设置为 "`python\n" 以强制模型输出 Python 代码，并将 stop 参数设置为 ['`'] 以防止模型进行额外解释：
````java theme={"system"}
@RestController
public class CodeGenerateController {
private final DeepSeekChatModel chatModel;
@Autowired
public ChatController(DeepSeekChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generatePythonCode")
public String generate(@RequestParam(value = "message", defaultValue = "请编写快速排序代码") String message) {
UserMessage userMessage = new UserMessage(message);
Message assistantMessage = DeepSeekAssistantMessage.prefixAssistantMessage("```python\\n");
Prompt prompt = new Prompt(List.of(userMessage, assistantMessage),
ChatOptions.builder().stopSequences(List.of("```")).build());
ChatResponse response = chatModel.call(prompt);
return response.getResult().getOutput().getText();
}
}
````
## 推理模型 (deepseek-reasoner)
`deepseek-reasoner` 是 DeepSeek 开发的推理模型。在给出最终答案之前，模型首先生成一个思维链 (CoT) 以提高其响应的准确性。
我们的 API 允许用户访问 `deepseek-reasoner` 生成的 CoT 内容，从而能够查看、显示和提炼它。
你可以使用 `DeepSeekAssistantMessage` 获取 `deepseek-reasoner` 生成的 CoT 内容：
```java theme={"system"}
public void deepSeekReasonerExample() {
DeepSeekChatOptions promptOptions = DeepSeekChatOptions.builder()
.model(DeepSeekApi.ChatModel.DEEPSEEK_REASONER.getValue())
.build();
Prompt prompt = new Prompt("9.11 和 9.8，哪个更大？", promptOptions);
ChatResponse response = chatModel.call(prompt);
// 获取 deepseek-reasoner 生成的 CoT 内容
DeepSeekAssistantMessage deepSeekAssistantMessage =
(DeepSeekAssistantMessage) response.getResult().getOutput();
String reasoningContent = deepSeekAssistantMessage.getReasoningContent();
}
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Docker Model Runner 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/dmr-chat
[Docker Model Runner](https://docs.docker.com/desktop/features/model-runner/) 是一个 AI 推理引擎，提供来自[各种提供商](https://hub.docker.com/u/ai)的各种模型。
Spring AI 通过复用现有的 [OpenAI](/spring4ai/api/chat/openai-chat) 支持的 `ChatClient` 与 Docker Model Runner 集成。为此，请将基本 URL 设置为 `http://localhost:12434/engines` 并选择提供的 [LLM 模型](https://hub.docker.com/u/ai)之一。
请查看 [DockerModelRunnerWithOpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/DockerModelRunnerWithOpenAiChatModelIT.java) 测试，获取如何将 Docker Model Runner 与 Spring AI 结合使用的示例。
## 前提条件
* 下载 Docker Desktop for Mac 4.40.0。
选择以下选项之一来启用 Model Runner：
### 选项 1：直接连接
* 启用 Model Runner：`docker desktop enable model-runner --tcp 12434`
* 将 base-url 设置为 `http://localhost:12434/engines`
### 选项 2：使用 Testcontainers
* 启用 Model Runner：`docker desktop enable model-runner`
* 使用 Testcontainers 并按如下方式设置 base-url：
```java theme={"system"}
@Container
private static final SocatContainer socat = new SocatContainer()
.withTarget(80, "model-runner.docker.internal");
@Bean
public OpenAiApi chatCompletionApi() {
var baseUrl = "http://%s:%d/engines".formatted(socat.getHost(), socat.getMappedPort(80));
return OpenAiApi.builder().baseUrl(baseUrl).apiKey("test").build();
}
```
你可以通过阅读 [使用 Docker 在本地运行 LLM](https://www.docker.com/blog/run-llms-locally/) 博文来了解有关 Docker Model Runner 的更多信息。
## 自动配置
自 1.0.0.M7 版本以来，Spring AI 启动器模块的工件 ID 已重命名。依赖项名称现在应遵循模型、向量存储和 MCP 启动器的更新命名模式。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-openai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 OpenAI 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.openai` 用作属性前缀，允许你连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| :------------------------ | :------------------------------------------- | :-- |
| spring.ai.openai.base-url | 要连接的 URL。必须设置为 `https://hub.docker.com/u/ai` | - |
| spring.ai.openai.api-key | 任何字符串 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=openai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 openai 不匹配的值)
此更改允许在你的应用程序中配置多个模型。
前缀 `spring.ai.openai.chat` 是属性前缀，允许你配置 OpenAI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------- | :------------------------------------------------------------------------------------- | :----- |
| spring.ai.model.chat | 启用 OpenAI 聊天模型。 | openai |
| spring.ai.openai.chat.base-url | 可选地覆盖 `spring.ai.openai.base-url` 以提供特定于聊天的 url。必须设置为 `http://localhost:12434/engines` | - |
| spring.ai.openai.chat.api-key | 可选地覆盖 spring.ai.openai.api-key 以提供特定于聊天的 api-key | - |
| spring.ai.openai.chat.options.model | 要使用的 [LLM 模型](https://hub.docker.com/u/ai) | - |
| spring.ai.openai.chat.options.temperature | 控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。 | 0.8 |
| spring.ai.openai.chat.options.frequencyPenalty | -2.0 到 2.0 之间的数字。正值会根据新标记在文本中已有的频率对其进行惩罚。 | 0.0f |
| spring.ai.openai.chat.options.maxTokens | 在聊天补全中生成的最大标记数。 | - |
| spring.ai.openai.chat.options.n | 为每个输入消息生成多少个聊天补全选项。 | 1 |
| spring.ai.openai.chat.options.presencePenalty | -2.0 到 2.0 之间的数字。正值会根据新标记是否已出现在文本中对其进行惩罚。 | - |
| spring.ai.openai.chat.options.responseFormat | 指定模型必须输出的格式的对象。设置为 `{ "type": "json_object" }` 可启用 JSON 模式。 | - |
| spring.ai.openai.chat.options.seed | 此功能处于测试阶段。如果指定，我们的系统将尽最大努力进行确定性采样。 | - |
| spring.ai.openai.chat.options.stop | API 将停止生成更多标记的最多 4 个序列。 | - |
| spring.ai.openai.chat.options.topP | 温度采样的替代方法，称为核采样。 | - |
| spring.ai.openai.chat.options.tools | 模型可能调用的工具列表。目前，仅支持函数作为工具。 | - |
| spring.ai.openai.chat.options.toolChoice | 控制模型调用哪个（如果有）函数。 | - |
| spring.ai.openai.chat.options.user | 代表你的最终用户的唯一标识符。 | - |
| spring.ai.openai.chat.options.functions | 按名称标识的函数列表，用于启用函数调用。 | - |
| spring.ai.openai.chat.options.stream-usage | （仅限流式传输）设置为添加一个包含标记使用情况统计信息的附加块。 | false |
| spring.ai.openai.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。 | false |
所有以 `spring.ai.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的运行时选项来覆盖。
## 运行时选项
[OpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `OpenAiChatModel(api, options)` 构造函数或 `spring.ai.openai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OpenAiChatOptions.builder()
.model("ai/gemma3:4B-F16")
.build()
));
```
除了特定于模型的 [OpenAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java)之外，你还可以使用通过 [ChatOptions#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 函数调用
当选择支持它的模型时，Docker Model Runner 支持工具/函数调用。
你可以使用 ChatModel 注册自定义 Java 函数，并让提供的模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
### 工具示例
以下是如何将 Docker Model Runner 函数调用与 Spring AI 结合使用的简单示例：
```properties theme={"system"}
spring.ai.openai.api-key=test
spring.ai.openai.base-url=http://localhost:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3:4B-F16
```
```java theme={"system"}
@SpringBootApplication
public class DockerModelRunnerLlmApplication {
public static void main(String[] args) {
SpringApplication.run(DockerModelRunnerLlmApplication.class, args);
}
@Bean
CommandLineRunner runner(ChatClient.Builder chatClientBuilder) {
return args -> {
var chatClient = chatClientBuilder.build();
var response = chatClient.prompt()
.user("阿姆斯特丹和巴黎的天气怎么样？")
.functions("weatherFunction") // 按 bean 名称引用。
.call()
.content();
System.out.println(response);
};
}
@Bean
@Description("获取某个位置的天气")
public Function weatherFunction() {
return new MockWeatherService();
}
public static class MockWeatherService implements Function {
public record WeatherRequest(String location, String unit) {}
public record WeatherResponse(double temp, String unit) {}
@Override
public WeatherResponse apply(WeatherRequest request) {
double temperature = request.location().contains("Amsterdam") ? 20 : 25;
return new WeatherResponse(temperature, request.unit);
}
}
}
```
在此示例中，当模型需要天气信息时，它将自动调用 `weatherFunction` bean，该 bean 可以获取实时天气数据。
预期的响应是："阿姆斯特丹目前的天气是 20 摄氏度，巴黎目前的天气是 25 摄氏度。"
阅读有关 OpenAI [函数调用](/spring4ai/api/chat/functions/openai-chat-functions)的更多信息。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-openai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OpenAi 聊天模型：
```properties theme={"system"}
spring.ai.openai.api-key=test
spring.ai.openai.base-url=http://localhost:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3:4B-F16
# Docker Model Runner 不支持嵌入，因此我们需要禁用它们。
spring.ai.openai.embedding.enabled=false
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Groq 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/groq-chat
[Groq](https://groq.com/) 是一个速度极快的，基于 LPU™ 的 AI 推理引擎，支持多种 [AI 模型](https://console.groq.com/docs/models)，
支持 `工具/函数调用` 并提供一个与 `OpenAI API` 兼容的端点。
Spring AI 通过复用现有的 [OpenAI](/spring4ai/api/chat/openai-chat) 客户端来集成 [Groq](https://groq.com/)。
为此，你需要获取一个 [Groq Api 密钥](https://console.groq.com/keys)，将 base-url 设置为 [https://api.groq.com/openai](https://api.groq.com/openai) 并选择一个
提供的 [Groq 模型](https://console.groq.com/docs/models)。
![]()
Groq API 与 OpenAI API 不完全兼容。
请注意以下[兼容性限制](https://console.groq.com/docs/openai)。
此外，目前 Groq 不支持多模态消息。
请查看 [GroqWithOpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/GroqWithOpenAiChatModelIT.java) 测试
获取将 Groq 与 Spring AI 结合使用的示例。
## 前提条件
* **创建 API 密钥**：
访问[此处](https://console.groq.com/keys)创建 API 密钥。
Spring AI 项目定义了一个名为 `spring.ai.openai.api-key` 的配置属性，你应该将其设置为从 groq.com 获取的 `API 密钥` 的值。
* **设置 Groq URL**：
你必须将 `spring.ai.openai.base-url` 属性设置为 `https://api.groq.com/openai`。
* **选择 Groq 模型**：
使用 `spring.ai.openai.chat.model=<模型名称>` 属性从可用的 [Groq 模型](https://console.groq.com/docs/models)中进行选择。
你可以在 `application.properties` 文件中设置这些配置属性：
```properties theme={"system"}
spring.ai.openai.api-key=<你的-groq-api-密钥>
spring.ai.openai.base-url=https://api.groq.com/openai
spring.ai.openai.chat.model=llama3-70b-8192
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
openai:
api-key: ${GROQ_API_KEY}
base-url: ${GROQ_BASE_URL}
chat:
model: ${GROQ_MODEL}
```
```bash theme={"system"}
# 在你的环境或 .env 文件中
export GROQ_API_KEY=<你的-groq-api-密钥>
export GROQ_BASE_URL=https://api.groq.com/openai
export GROQ_MODEL=llama3-70b-8192
```
你也可以在应用程序代码中以编程方式设置这些配置：
```java theme={"system"}
// 从安全来源或环境变量中检索配置
String apiKey = System.getenv("GROQ_API_KEY");
String baseUrl = System.getenv("GROQ_BASE_URL");
String model = System.getenv("GROQ_MODEL");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-openai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 OpenAI 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.openai` 用作属性前缀，允许你连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| :------------------------ | :------------------------------------------- | :-- |
| spring.ai.openai.base-url | 要连接的 URL。必须设置为 `https://api.groq.com/openai` | - |
| spring.ai.openai.api-key | Groq API 密钥 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=openai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 openai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.openai.chat` 是属性前缀，允许你配置 OpenAI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
| spring.ai.openai.chat.enabled (已移除且不再有效) | 启用 OpenAI 聊天模型。 | true |
| spring.ai.openai.chat | 启用 OpenAI 聊天模型。 | openai |
| spring.ai.openai.chat.base-url | 可选地覆盖 spring.ai.openai.base-url 以提供特定于聊天的 url。必须设置为 `https://api.groq.com/openai` | - |
| spring.ai.openai.chat.api-key | 可选地覆盖 spring.ai.openai.api-key 以提供特定于聊天的 api-key | - |
| spring.ai.openai.chat.options.model | [可用模型](https://console.groq.com/docs/models)名称为 `llama3-8b-8192`、`llama3-70b-8192`、`mixtral-8x7b-32768`、`gemma2-9b-it`。 | - |
| spring.ai.openai.chat.options.temperature | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改温度和 top\_p，因为这两个设置的相互作用很难预测。 | 0.8 |
| spring.ai.openai.chat.options.frequencyPenalty | -2.0 到 2.0 之间的数字。正值会根据新标记在文本中已有的频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。 | 0.0f |
| spring.ai.openai.chat.options.maxTokens | 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | - |
| spring.ai.openai.chat.options.n | 为每个输入消息生成多少个聊天补全选项。请注意，你将根据所有选项中生成的标记数付费。将 n 保持为 1 以最大程度地降低成本。 | 1 |
| spring.ai.openai.chat.options.presencePenalty | -2.0 到 2.0 之间的数字。正值会根据新标记是否已出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。 | - |
| spring.ai.openai.chat.options.responseFormat | 指定模型必须输出的格式的对象。设置为 `{ "type": "json_object" }` 可启用 JSON 模式，该模式可确保模型生成的消息是有效的 JSON。 | - |
| spring.ai.openai.chat.options.seed | 此功能处于测试阶段。如果指定，我们的系统将尽最大努力进行确定性采样，以便具有相同种子和参数的重复请求应返回相同的结果。 | - |
| spring.ai.openai.chat.options.stop | API 将停止生成更多标记的最多 4 个序列。 | - |
| spring.ai.openai.chat.options.topP | 温度采样的替代方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记的结果。因此 0.1 表示仅考虑构成前 10% 概率质量的标记。我们通常建议更改此项或温度，但不能同时更改两者。 | - |
| spring.ai.openai.chat.options.tools | 模型可能调用的工具列表。目前，仅支持函数作为工具。使用此选项可提供模型可能为其生成 JSON 输入的函数列表。 | - |
| spring.ai.openai.chat.options.toolChoice | 控制模型调用哪个（如果有）函数。none 表示模型不会调用函数，而是生成一条消息。auto 表示模型可以在生成消息或调用函数之间进行选择。通过 `{"type: "function", "function": {"name": "my_function"}}` 指定特定函数会强制模型调用该函数。当不存在函数时，none 是默认值。如果存在函数，则 auto 是默认值。 | - |
| spring.ai.openai.chat.options.user | 代表你的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。 | - |
| spring.ai.openai.chat.options.functions | 在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
| spring.ai.openai.chat.options.stream-usage | （仅限流式传输）设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 `choices` 字段是一个空数组，所有其他块也将包含一个 usage 字段，但其值为 null。 | false |
| spring.ai.openai.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
所有以 `spring.ai.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的运行时选项来覆盖。
## 运行时选项
[OpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `OpenAiChatModel(api, options)` 构造函数或 `spring.ai.openai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OpenAiChatOptions.builder()
.model("mixtral-8x7b-32768")
.temperature(0.4)
.build()
));
```
除了特定于模型的 [OpenAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java)之外，你还可以使用通过 [ChatOptions#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 函数调用
当选择支持工具/函数的模型之一时，Groq API 端点支持[工具/函数调用](https://console.groq.com/docs/tool-use)。
检查工具[支持的模型](https://console.groq.com/docs/tool-use)。
![]()
你可以使用 ChatModel 注册自定义 Java 函数，并让提供的 Groq 模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
### 工具示例
以下是如何将 Groq 函数调用与 Spring AI 结合使用的简单示例：
```java theme={"system"}
@SpringBootApplication
public class GroqApplication {
public static void main(String[] args) {
SpringApplication.run(GroqApplication.class, args);
}
@Bean
CommandLineRunner runner(ChatClient.Builder chatClientBuilder) {
return args -> {
var chatClient = chatClientBuilder.build();
var response = chatClient.prompt()
.user("阿姆斯特丹和巴黎的天气怎么样？")
.functions("weatherFunction") // 按 bean 名称引用。
.call()
.content();
System.out.println(response);
};
}
@Bean
@Description("获取某个位置的天气")
public Function weatherFunction() {
return new MockWeatherService();
}
public static class MockWeatherService implements Function {
public record WeatherRequest(String location, String unit) {}
public record WeatherResponse(double temp, String unit) {}
@Override
public WeatherResponse apply(WeatherRequest request) {
double temperature = request.location().contains("Amsterdam") ? 20 : 25;
return new WeatherResponse(temperature, request.unit);
}
}
}
```
在此示例中，当模型需要天气信息时，它将自动调用 `weatherFunction` bean，该 bean 可以获取实时天气数据。
预期的响应如下所示："阿姆斯特丹目前的天气是 20 摄氏度，巴黎目前的天气是 25 摄氏度。"
阅读有关 OpenAI [函数调用](/spring4ai/api/chat/functions/openai-chat-functions)的更多信息。
## 多模态
目前 Groq API 不支持媒体内容。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-openai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OpenAi 聊天模型：
```properties theme={"system"}
spring.ai.openai.api-key=
spring.ai.openai.base-url=https://api.groq.com/openai
spring.ai.openai.chat.options.model=llama3-70b-8192
spring.ai.openai.chat.options.temperature=0.7
```
将 `api-key` 替换为你的 OpenAI 凭据。
这将创建一个 `OpenAiChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成。
```java theme={"system"}
@RestController
public class ChatController {
private final OpenAiChatModel chatModel;
@Autowired
public ChatController(OpenAiChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
[OpenAiChatModel.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用低级 API 连接到 OpenAI 服务。
将 `spring-ai-openai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai
```
或添加到你的 Gradle `build.gradle` 构建文件中。
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
接下来，创建一个 `OpenAiChatModel` 并将其用于文本生成：
```java theme={"system"}
var openAiApi = new OpenAiApi("https://api.groq.com/openai", System.getenv("GROQ_API_KEY"));
var openAiChatOptions = OpenAiChatOptions.builder()
.model("llama3-70b-8192")
.temperature(0.4)
.maxTokens(200)
.build();
var chatModel = new OpenAiChatModel(this.openAiApi, this.openAiChatOptions);
ChatResponse response = this.chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux response = this.chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
## 2. Accordion Groups（折叠组）
适用场景：分组管理多个折叠面板，组织复杂文档内容。
示例用法：
查看 [Accordion](mdc:content/components/accordions) 文档以获取所有支持的属性。
查看 [Accordion](mdc:content/components/accordions) 文档以获取所有支持的属性。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MiniMax 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/minimax-chat
Spring AI 支持 MiniMax 提供的各种 AI 语言模型。你可以与 MiniMax 语言模型进行交互，并基于 MiniMax 模型创建多语言会话助手。
## 前提条件
你需要使用 MiniMax 创建一个 API 才能访问 MiniMax 语言模型。
在 [MiniMax 注册页面](https://www.minimaxi.com/login)创建一个帐户，并在[API 密钥页面](https://www.minimaxi.com/user-center/basic-information/interface-key)生成令牌。
Spring AI 项目定义了一个名为 `spring.ai.minimax.api-key` 的配置属性，你应该将其设置为从 API 密钥页面获取的 `API 密钥` 的值。
你可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.minimax.api-key=<你的minimax-api密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
minimax:
api-key: ${MINIMAX_API_KEY}
```
```bash theme={"system"}
# 在你的环境或 .env 文件中
export MINIMAX_API_KEY=<你的minimax-api密钥>
```
你也可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("MINIMAX_API_KEY");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 MiniMax 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-minimax
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-minimax'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 MiniMax 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.minimax` 用作属性前缀，允许你连接到 MiniMax。
| 属性 | 描述 | 默认值 |
| :------------------------- | :------- | :--------------------------------------------------- |
| spring.ai.minimax.base-url | 要连接的 URL | [https://api.minimax.chat](https://api.minimax.chat) |
| spring.ai.minimax.api-key | API 密钥 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=minimax` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 minimax 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.minimax.chat` 是属性前缀，允许你配置 MiniMax 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
| spring.ai.minimax.chat.enabled (已移除且不再有效) | 启用 MiniMax 聊天模型。 | true |
| spring.ai.model.chat | 启用 MiniMax 聊天模型。 | minimax |
| spring.ai.minimax.chat.base-url | 可选地覆盖 spring.ai.minimax.base-url 以提供特定于聊天的 url | [https://api.minimax.chat](https://api.minimax.chat) |
| spring.ai.minimax.chat.api-key | 可选地覆盖 spring.ai.minimax.api-key 以提供特定于聊天的 api-key | - |
| spring.ai.minimax.chat.options.model | 这是要使用的 MiniMax 聊天模型 | `abab6.5g-chat` (`abab5.5-chat`、`abab5.5s-chat`、`abab6.5-chat`、`abab6.5g-chat`、`abab6.5t-chat` 和 `abab6.5s-chat` 指向最新的模型版本) |
| spring.ai.minimax.chat.options.maxTokens | 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | - |
| spring.ai.minimax.chat.options.temperature | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改温度和 top\_p，因为这两个设置的相互作用很难预测。 | 0.7 |
| spring.ai.minimax.chat.options.topP | 温度采样的替代方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记的结果。因此 0.1 表示仅考虑构成前 10% 概率质量的标记。我们通常建议更改此项或温度，但不能同时更改两者。 | 1.0 |
| spring.ai.minimax.chat.options.n | 为每个输入消息生成多少个聊天补全选项。请注意，你将根据所有选项中生成的标记数付费。默认值为 1，不能大于 5。具体来说，当温度非常小且接近 0 时，我们只能返回 1 个结果。如果此时已设置 n 且 >1，服务将返回非法输入参数 (invalid\_request\_error) | 1 |
| spring.ai.minimax.chat.options.presencePenalty | -2.0 到 2.0 之间的数字。正值会根据新标记是否已出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。 | 0.0f |
| spring.ai.minimax.chat.options.frequencyPenalty | -2.0 到 2.0 之间的数字。正值会根据新标记在文本中已有的频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。 | 0.0f |
| spring.ai.minimax.chat.options.stop | 模型将停止生成由 stop 指定的字符，目前仅支持 \["stop\_word1"] 格式的单个停止词 | - |
你可以为 `ChatModel` 实现覆盖通用的 `spring.ai.minimax.base-url` 和 `spring.ai.minimax.api-key`。
如果设置了 `spring.ai.minimax.chat.base-url` 和 `spring.ai.minimax.chat.api-key` 属性，则它们优先于通用属性。
如果你想为不同的模型和不同的模型端点使用不同的 MiniMax 帐户，这将非常有用。
所有以 `spring.ai.minimax.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
## 运行时选项
[MiniMaxChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/main/java/org/springframework/ai/minimax/MiniMaxChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `MiniMaxChatModel(api, options)` 构造函数或 `spring.ai.minimax.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
MiniMaxChatOptions.builder()
.model(MiniMaxApi.ChatModel.ABAB_6_5_S_Chat.getValue())
.temperature(0.5)
.build()
));
```
除了特定于模型的 [MiniMaxChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/main/java/org/springframework/ai/minimax/MiniMaxChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/ChatOptions.java) 实例。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-minimax` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 MiniMax 聊天模型：
```properties theme={"system"}
spring.ai.minimax.api-key=你的API密钥
spring.ai.minimax.chat.options.model=abab6.5g-chat
spring.ai.minimax.chat.options.temperature=0.7
```
将 `api-key` 替换为你的 MiniMax 凭据。
这将创建一个 `MiniMaxChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成。
```java theme={"system"}
@RestController
public class ChatController {
private final MiniMaxChatModel chatModel;
@Autowired
public ChatController(MiniMaxChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
var prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
[MiniMaxChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/main/java/org/springframework/ai/minimax/MiniMaxChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用[低级 API](#low-level-api)连接到 MiniMax 服务。
将 `spring-ai-minimax` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-minimax
```
或添加到你的 Gradle `build.gradle` 构建文件中：
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-minimax'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
接下来，创建一个 `MiniMaxChatModel` 并将其用于文本生成：
```java theme={"system"}
var miniMaxApi = new MiniMaxApi(System.getenv("MINIMAX_API_KEY"));
var chatModel = new MiniMaxChatModel(this.miniMaxApi, MiniMaxChatOptions.builder()
.model(MiniMaxApi.ChatModel.ABAB_6_5_S_Chat.getValue())
.temperature(0.4)
.maxTokens(200)
.build());
ChatResponse response = this.chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux streamResponse = this.chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
`MiniMaxChatOptions` 为聊天请求提供配置信息。
`MiniMaxChatOptions.Builder` 是流畅的选项构建器。
### 低级 MiniMaxApi 客户端
[MiniMaxApi](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/main/java/org/springframework/ai/minimax/api/MiniMaxApi.java) 提供了轻量级的 Java 客户端，用于 [MiniMax API](https://www.minimaxi.com/document/guides/chat-model/V2)。
以下是一个简单的代码片段，展示了如何以编程方式使用 API：
```java theme={"system"}
MiniMaxApi miniMaxApi =
new MiniMaxApi(System.getenv("MINIMAX_API_KEY"));
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("你好世界", Role.USER);
// 同步请求
ResponseEntity response = this.miniMaxApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), MiniMaxApi.ChatModel.ABAB_6_5_S_Chat.getValue(), 0.7f, false));
// 流式请求
Flux streamResponse = this.miniMaxApi.chatCompletionStream(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), MiniMaxApi.ChatModel.ABAB_6_5_S_Chat.getValue(), 0.7f, true));
```
有关更多信息，请参阅 [MiniMaxApi.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/main/java/org/springframework/ai/minimax/api/MiniMaxApi.java) 的 JavaDoc。
### WebSearch 聊天
MiniMax 模型支持 Web 搜索功能。Web 搜索功能允许你搜索 Web 上的信息并在聊天响应中返回结果。
有关 Web 搜索的更多信息，请参阅 [MiniMax ChatCompletion](https://platform.minimaxi.com/document/ChatCompletion%20v2)。
以下是如何使用 Web 搜索的简单代码片段：
```java theme={"system"}
UserMessage userMessage = new UserMessage(
"美国在 2024 年奥运会上总共获得了多少枚金牌？");
List messages = new ArrayList<>(List.of(this.userMessage));
List functionTool = List.of(MiniMaxApi.FunctionTool.webSearchFunctionTool());
MiniMaxChatOptions options = MiniMaxChatOptions.builder()
.model(MiniMaxApi.ChatModel.ABAB_6_5_S_Chat.value)
.tools(this.functionTool)
.build();
// 同步请求
ChatResponse response = chatModel.call(new Prompt(this.messages, this.options));
// 流式请求
Flux streamResponse = chatModel.stream(new Prompt(this.messages, this.options));
```
#### MiniMaxApi 示例
* [MiniMaxApiIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiIT.java) 测试提供了一些有关如何使用轻量级库的常规示例。
* [MiniMaxApiToolFunctionCallIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiToolFunctionCallIT.java) 测试演示了如何使用低级 API 调用工具函数。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Mistral AI 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/mistralai-chat
Spring AI 支持 Mistral AI 提供的各种 AI 语言模型。你可以与 Mistral AI 语言模型进行交互，并基于 Mistral 模型创建多语言会话助手。
Mistral AI 也提供与 OpenAI API 兼容的端点。
请查看 [OpenAI API 兼容性](/spring4ai/api/chat/openai-chat#openai-api-compatibility)部分，了解如何使用 [Spring AI OpenAI](/spring4ai/api/chat/openai-chat) 集成与 Mistral 端点通信。
## 前提条件
你需要使用 Mistral AI 创建一个 API 才能访问 Mistral AI 语言模型。
在 [Mistral AI 注册页面](https://auth.mistral.ai/ui/registration)创建一个帐户，并在[API 密钥页面](https://console.mistral.ai/api-keys/)生成令牌。
Spring AI 项目定义了一个名为 `spring.ai.mistralai.api-key` 的配置属性，你应该将其设置为从 console.mistral.ai 获取的 `API 密钥` 的值。
你可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.mistralai.api-key=<你的-mistralai-api-密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
mistralai:
api-key: ${MISTRALAI_API_KEY}
```
```bash theme={"system"}
# 在你的环境或 .env 文件中
export MISTRALAI_API_KEY=<你的-mistralai-api-密钥>
```
你也可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("MISTRALAI_API_KEY");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Mistral AI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-mistral-ai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-mistral-ai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 Mistral AI 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.mistralai` 用作属性前缀，允许你连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| :--------------------------- | :------- | :----------------------------------------------- |
| spring.ai.mistralai.base-url | 要连接的 URL | [https://api.mistral.ai](https://api.mistral.ai) |
| spring.ai.mistralai.api-key | API 密钥 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=mistral` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 mistral 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.mistralai.chat` 是属性前缀，允许你配置 Mistral AI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------- |
| spring.ai.mistralai.chat.enabled (已移除且不再有效) | 启用 Mistral AI 聊天模型。 | true |
| spring.ai.model.chat | 启用 Mistral AI 聊天模型。 | mistral |
| spring.ai.mistralai.chat.base-url | 可选地覆盖 `spring.ai.mistralai.base-url` 属性以提供特定于聊天的 URL。 | - |
| spring.ai.mistralai.chat.api-key | 可选地覆盖 `spring.ai.mistralai.api-key` 以提供特定于聊天的 API 密钥。 | - |
| spring.ai.mistralai.chat.options.model | 这是要使用的 Mistral AI 聊天模型 | `open-mistral-7b`、`open-mixtral-8x7b`、`open-mixtral-8x22b`、`mistral-small-latest`、`mistral-large-latest` |
| spring.ai.mistralai.chat.options.temperature | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改 `temperature` 和 `top_p`，因为这两个设置的相互作用很难预测。 | 0.8 |
| spring.ai.mistralai.chat.options.maxTokens | 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | - |
| spring.ai.mistralai.chat.options.safePrompt | 指示是否在所有对话之前注入安全提示。 | false |
| spring.ai.mistralai.chat.options.randomSeed | 此功能处于测试阶段。如果指定，我们的系统将尽最大努力进行确定性采样，以便具有相同种子和参数的重复请求应返回相同的结果。 | - |
| spring.ai.mistralai.chat.options.stop | 如果检测到此标记，则停止生成。或者，如果在提供数组时检测到这些标记之一。 | - |
| spring.ai.mistralai.chat.options.topP | 温度采样的替代方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记的结果。因此 0.1 表示仅考虑构成前 10% 概率质量的标记。我们通常建议更改此项或 `temperature`，但不能同时更改两者。 | - |
| spring.ai.mistralai.chat.options.responseFormat | 指定模型必须输出的格式的对象。设置为 `{ "type": "json_object" }` 可启用 JSON 模式，该模式可确保模型生成的消息是有效的 JSON。 | - |
| spring.ai.mistralai.chat.options.tools | 模型可能调用的工具列表。目前，仅支持函数作为工具。使用此选项可提供模型可能为其生成 JSON 输入的函数列表。 | - |
| spring.ai.mistralai.chat.options.toolChoice | 控制模型调用哪个（如果有）函数。`none` 表示模型不会调用函数，而是生成一条消息。`auto` 表示模型可以在生成消息或调用函数之间进行选择。通过 `{"type: "function", "function": {"name": "my_function"}}` 指定特定函数会强制模型调用该函数。当不存在函数时，`none` 是默认值。如果存在函数，则 `auto` 是默认值。 | - |
| spring.ai.mistralai.chat.options.functions | 在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
| spring.ai.mistralai.chat.options.functionCallbacks | 要注册到 ChatModel 的 Mistral AI 工具函数回调。 | - |
| spring.ai.mistralai.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
你可以为 `ChatModel` 和 `EmbeddingModel` 实现覆盖通用的 `spring.ai.mistralai.base-url` 和 `spring.ai.mistralai.api-key`。
如果设置了 `spring.ai.mistralai.chat.base-url` 和 `spring.ai.mistralai.chat.api-key` 属性，则它们优先于通用属性。
如果你想为不同的模型和不同的模型端点使用不同的 Mistral AI 帐户，这将非常有用。
所有以 `spring.ai.mistralai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
## 运行时选项
[MistralAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/MistralAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `MistralAiChatModel(api, options)` 构造函数或 `spring.ai.mistralai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
MistralAiChatOptions.builder()
.model(MistralAiApi.ChatModel.LARGE.getValue())
.temperature(0.5)
.build()
));
```
除了特定于模型的 [MistralAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/MistralAiChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 函数调用
你可以使用 `MistralAiChatModel` 注册自定义 Java 函数，并让 Mistral AI 模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关[工具调用](/spring4ai/api/tools)的更多信息。
## 多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。
Mistral AI 支持文本和视觉模态。
### 视觉
Mistral AI 模型提供视觉多模态支持，包括 `pixtral-large-latest`。
有关更多信息，请参阅[视觉](https://docs.mistral.ai/capabilities/vision/)指南。
Mistral AI [用户消息 API](https://docs.mistral.ai/api/#tag/chat/operation/chat_completion_v1_chat_completions_post) 可以将 base64 编码的图像或图像 URL 列表与消息合并。
Spring AI 的 [Message](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/messages/Message.java) 接口通过引入 [Media](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/model/Media.java) 类型来促进多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和详细信息，利用 Spring 的 `org.springframework.util.MimeType` 和 `org.springframework.core.io.Resource` 来获取原始媒体数据。
以下是从 `MistralAiChatModelIT.java` 中摘录的代码示例，说明了用户文本与图像的融合：
```java theme={"system"}
var imageResource = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage("解释一下你在这张图片上看到了什么？",
new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));
ChatResponse response = chatModel.call(new Prompt(this.userMessage,
ChatOptions.builder().model(MistralAiApi.ChatModel.PIXTRAL_LARGE.getValue()).build()));
```
或等效的图像 URL：
```java theme={"system"}
var userMessage = new UserMessage("解释一下你在这张图片上看到了什么？",
new Media(MimeTypeUtils.IMAGE_PNG,
URI.create("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png")));
ChatResponse response = chatModel.call(new Prompt(this.userMessage,
ChatOptions.builder().model(MistralAiApi.ChatModel.PIXTRAL_LARGE.getValue()).build()));
```
你也可以传递多个图像。
该示例显示了一个模型，它将 `multimodal.test.png` 图像作为输入：
![多模态测试图像]()
以及文本消息"解释一下你在这张图片上看到了什么？"，并生成如下响应：
```
这是一张水果盘的图片，设计简单。碗由金属制成，带有弯曲的金属丝边缘，
形成开放式结构，可以从各个角度看到水果。碗里，两根香蕉放在一个看起来像是红苹果的水果上面。
香蕉有点过熟，表皮上有褐色的斑点。碗的顶部有一个金属环，可能是用来提携的。
碗放在一个平坦的表面上，背景颜色中性，可以清楚地看到里面的水果。
```
## OpenAI API 兼容性
Mistral 与 OpenAI API 兼容，你可以使用 [Spring AI OpenAI](/spring4ai/api/chat/openai-chat) 客户端与 Mistral 通信。
为此，你需要将 OpenAI 基本 URL 配置为 Mistral AI 平台：`spring.ai.openai.chat.base-url=https://api.mistral.ai`，选择一个 Mistral 模型：`spring.ai.openai.chat.options.model=mistral-small-latest` 并设置 Mistral AI API 密钥：`spring.ai.openai.chat.api-key=<你的 MISTRAL API 密钥>`。
请查看 [MistralWithOpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/MistralWithOpenAiChatModelIT.java) 测试，获取通过 Spring AI OpenAI 使用 Mistral 的示例。
## 示例控制器（自动配置）
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-mistral-ai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 Mistral AI 聊天模型：
```properties theme={"system"}
spring.ai.mistralai.api-key=你的API密钥
spring.ai.mistralai.chat.options.model=mistral-small
spring.ai.mistralai.chat.options.temperature=0.7
```
将 `api-key` 替换为你的 Mistral AI 凭据。
这将创建一个 `MistralAiChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@RestController` 类的示例，该类使用聊天模型进行文本生成：
```java theme={"system"}
@RestController
public class ChatController {
private final MistralAiChatModel chatModel;
@Autowired
public ChatController(MistralAiChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
var prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
[MistralAiChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/MistralAiChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用[低级 API](#low-level-api)连接到 Mistral AI 服务。
将 `spring-ai-mistral-ai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-mistral-ai
```
或添加到你的 Gradle `build.gradle` 构建文件中：
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-mistral-ai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
接下来，创建一个 `MistralAiChatModel` 并将其用于文本生成：
```java theme={"system"}
var mistralAiApi = new MistralAiApi(System.getenv("MISTRAL_AI_API_KEY"));
var chatModel = new MistralAiChatModel(this.mistralAiApi, MistralAiChatOptions.builder()
.model(MistralAiApi.ChatModel.LARGE.getValue())
.temperature(0.4)
.maxTokens(200)
.build());
ChatResponse response = this.chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux response = this.chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
`MistralAiChatOptions` 为聊天请求提供配置信息。
`MistralAiChatOptions.Builder` 是一个流畅的选项构建器。
### 低级 MistralAiApi 客户端
[MistralAiApi](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/api/MistralAiApi.java) 提供了轻量级的 Java 客户端，用于 [Mistral AI API](https://docs.mistral.ai/api/)。
以下是一个简单的代码片段，展示了如何以编程方式使用 API：
```java theme={"system"}
MistralAiApi mistralAiApi = new MistralAiApi(System.getenv("MISTRAL_AI_API_KEY"));
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("你好世界", Role.USER);
// 同步请求
ResponseEntity response = this.mistralAiApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), MistralAiApi.ChatModel.LARGE.getValue(), 0.8, false));
// 流式请求
Flux streamResponse = this.mistralAiApi.chatCompletionStream(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), MistralAiApi.ChatModel.LARGE.getValue(), 0.8, true));
```
有关更多信息，请参阅 [MistralAiApi.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/api/MistralAiApi.java) 的 JavaDoc。
#### MistralAiApi 示例
* [MistralAiApiIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/test/java/org/springframework/ai/mistralai/api/MistralAiApiIT.java) 测试提供了一些有关如何使用轻量级库的常规示例。
* [PaymentStatusFunctionCallingIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/test/java/org/springframework/ai/mistralai/api/tool/PaymentStatusFunctionCallingIT.java) 测试演示了如何使用低级 API 调用工具函数。
基于 [Mistral AI 函数调用](https://docs.mistral.ai/guides/function-calling/)教程。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Moonshot AI 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/moonshot-chat
# Moonshot AI 聊天
此功能已移至 Spring AI 社区代码库。
请访问 GitHub 代码库以获取最新版本。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# NVIDIA 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/nvidia-chat
[NVIDIA LLM API](https://docs.api.nvidia.com/nim/reference/llm-apis) 是一个代理 AI 推理引擎，提供来自[各种提供商](https://docs.api.nvidia.com/nim/reference/llm-apis#models)的各种模型。
Spring AI 通过复用现有的 [OpenAI](/spring4ai/api/chat/openai-chat) 客户端与 NVIDIA LLM API 集成。
为此，你需要将 base-url 设置为 `https://integrate.api.nvidia.com`，选择提供的 [LLM 模型](https://docs.api.nvidia.com/nim/reference/llm-apis#model)之一并获取其 `api-key`。
![NVIDIA LLM API 集成]()
NVIDIA LLM API 要求显式设置 `max-tokens` 参数，否则将引发服务器错误。
请查看 [NvidiaWithOpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/NvidiaWithOpenAiChatModelIT.java) 测试，获取将 NVIDIA LLM API 与 Spring AI 结合使用的示例。
## 前提条件
* 创建具有足够积分的 [NVIDIA](https://build.nvidia.com/explore/discover) 帐户。
* 选择要使用的 LLM 模型。例如，下面屏幕截图中的 `meta/llama-3.1-70b-instruct`。
* 从所选模型的页面中，你可以获取访问此模型的 `api-key`。
![NVIDIA 注册]()
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-openai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 OpenAI 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.openai` 用作属性前缀，允许你连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| :------------------------ | :------------------------------------------------ | :-- |
| spring.ai.openai.base-url | 要连接的 URL。必须设置为 `https://integrate.api.nvidia.com` | - |
| spring.ai.openai.api-key | NVIDIA API 密钥 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=openai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 openai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.openai.chat` 是属性前缀，允许你配置 OpenAI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| spring.ai.openai.chat.enabled (已移除且不再有效) | 启用 OpenAI 聊天模型。 | true |
| spring.ai.model.chat | 启用 OpenAI 聊天模型。 | openai |
| spring.ai.openai.chat.base-url | 可选地覆盖 spring.ai.openai.base-url 以提供特定于聊天的 url。必须设置为 `https://integrate.api.nvidia.com` | - |
| spring.ai.openai.chat.api-key | 可选地覆盖 spring.ai.openai.api-key 以提供特定于聊天的 api-key | - |
| spring.ai.openai.chat.options.model | 要使用的 [NVIDIA LLM 模型](https://docs.api.nvidia.com/nim/reference/llm-apis#models) | - |
| spring.ai.openai.chat.options.temperature | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改温度和 top\_p，因为这两个设置的相互作用很难预测。 | 0.8 |
| spring.ai.openai.chat.options.frequencyPenalty | -2.0 到 2.0 之间的数字。正值会根据新标记在文本中已有的频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。 | 0.0f |
| spring.ai.openai.chat.options.maxTokens | 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | 注意：NVIDIA LLM API 要求显式设置 `max-tokens` 参数，否则将引发服务器错误。 |
| spring.ai.openai.chat.options.n | 为每个输入消息生成多少个聊天补全选项。请注意，你将根据所有选项中生成的标记数付费。将 n 保持为 1 以最大程度地降低成本。 | 1 |
| spring.ai.openai.chat.options.presencePenalty | -2.0 到 2.0 之间的数字。正值会根据新标记是否已出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。 | - |
| spring.ai.openai.chat.options.responseFormat | 指定模型必须输出的格式的对象。设置为 `{ "type": "json_object" }` 可启用 JSON 模式，该模式可确保模型生成的消息是有效的 JSON。 | - |
| spring.ai.openai.chat.options.seed | 此功能处于测试阶段。如果指定，我们的系统将尽最大努力进行确定性采样，以便具有相同种子和参数的重复请求应返回相同的结果。 | - |
| spring.ai.openai.chat.options.stop | API 将停止生成更多标记的最多 4 个序列。 | - |
| spring.ai.openai.chat.options.topP | 温度采样的替代方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记的结果。因此 0.1 表示仅考虑构成前 10% 概率质量的标记。我们通常建议更改此项或温度，但不能同时更改两者。 | - |
| spring.ai.openai.chat.options.tools | 模型可能调用的工具列表。目前，仅支持函数作为工具。使用此选项可提供模型可能为其生成 JSON 输入的函数列表。 | - |
| spring.ai.openai.chat.options.toolChoice | 控制模型调用哪个（如果有）函数。none 表示模型不会调用函数，而是生成一条消息。auto 表示模型可以在生成消息或调用函数之间进行选择。通过 `{"type: "function", "function": {"name": "my_function"}}` 指定特定函数会强制模型调用该函数。当不存在函数时，none 是默认值。如果存在函数，则 auto 是默认值。 | - |
| spring.ai.openai.chat.options.user | 代表你的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。 | - |
| spring.ai.openai.chat.options.functions | 在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
| spring.ai.openai.chat.options.stream-usage | （仅限流式传输）设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 `choices` 字段是一个空数组，所有其他块也将包含一个 usage 字段，但其值为 null。 | false |
| spring.ai.openai.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
所有以 `spring.ai.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
## 运行时选项
[OpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `OpenAiChatModel(api, options)` 构造函数或 `spring.ai.openai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OpenAiChatOptions.builder()
.model("mixtral-8x7b-32768")
.temperature(0.4)
.build()
));
```
除了特定于模型的 [OpenAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java)之外，你还可以使用通过 [ChatOptions#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 函数调用
当选择支持它的模型时，NVIDIA LLM API 支持工具/函数调用。
![NVIDIA 函数调用]()
你可以使用 ChatModel 注册自定义 Java 函数，并让提供的模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
### 工具示例
以下是如何将 NVIDIA LLM API 函数调用与 Spring AI 结合使用的简单示例：
```properties theme={"system"}
spring.ai.openai.api-key=${NVIDIA_API_KEY}
spring.ai.openai.base-url=https://integrate.api.nvidia.com
spring.ai.openai.chat.options.model=meta/llama-3.1-70b-instruct
spring.ai.openai.chat.options.max-tokens=2048
```
```java theme={"system"}
@SpringBootApplication
public class NvidiaLlmApplication {
public static void main(String[] args) {
SpringApplication.run(NvidiaLlmApplication.class, args);
}
@Bean
CommandLineRunner runner(ChatClient.Builder chatClientBuilder) {
return args -> {
var chatClient = chatClientBuilder.build();
var response = chatClient.prompt()
.user("阿姆斯特丹和巴黎的天气怎么样？")
.functions("weatherFunction") // 按 bean 名称引用。
.call()
.content();
System.out.println(response);
};
}
@Bean
@Description("获取某个位置的天气")
public Function weatherFunction() {
return new MockWeatherService();
}
public static class MockWeatherService implements Function {
public record WeatherRequest(String location, String unit) {}
public record WeatherResponse(double temp, String unit) {}
@Override
public WeatherResponse apply(WeatherRequest request) {
double temperature = request.location().contains("Amsterdam") ? 20 : 25;
return new WeatherResponse(temperature, request.unit);
}
}
}
```
在此示例中，当模型需要天气信息时，它将自动调用 `weatherFunction` bean，该 bean 可以获取实时天气数据。
预期的响应如下所示："阿姆斯特丹目前的天气是 20 摄氏度，巴黎目前的天气是 25 摄氏度。"
阅读有关 OpenAI [函数调用](/spring4ai/api/chat/functions/openai-chat-functions)的更多信息。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-openai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OpenAi 聊天模型：
```properties theme={"system"}
spring.ai.openai.api-key=${NVIDIA_API_KEY}
spring.ai.openai.base-url=https://integrate.api.nvidia.com
spring.ai.openai.chat.options.model=meta/llama-3.1-70b-instruct
# NVIDIA LLM API 不支持嵌入，因此我们需要禁用它。
spring.ai.openai.embedding.enabled=false
# NVIDIA LLM API 要求显式设置此参数，否则将引发服务器内部错误。
spring.ai.openai.chat.options.max-tokens=2048
```
将 `api-key` 替换为你的 NVIDIA 凭据。
NVIDIA LLM API 要求显式设置 `max-token` 参数，否则将引发服务器错误。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成：
```java theme={"system"}
@RestController
public class ChatController {
private final OpenAiChatModel chatModel;
@Autowired
public ChatController(OpenAiChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OCI GenAI Cohere 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/oci-genai/cohere-chat
[OCI GenAI 服务](https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/) 提供按需模型或专用 AI 集群的生成式 AI 聊天功能。
[OCI 聊天模型页面](https://docs.oracle.com/en-us/iaas/Content/generative-ai/chat-models.htm)和 [OCI 生成式 AI 试验场](https://docs.oracle.com/en-us/iaas/Content/generative-ai/use-playground-embed.htm)提供了有关在 OCI 上使用和托管聊天模型的详细信息。
## 前提条件
你需要一个有效的 [Oracle Cloud Infrastructure (OCI)](https://signup.oraclecloud.com/) 帐户才能使用 OCI GenAI Cohere 聊天客户端。该客户端提供四种不同的连接方式，包括使用用户和私钥的简单身份验证、工作负载身份、实例主体或 OCI 配置文件身份验证。
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OCI GenAI Cohere 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-oci-genai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-oci-genai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 连接属性
前缀 `spring.ai.oci.genai` 是用于配置与 OCI GenAI 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------- | :------------------------------------------------------------------------------------- | :---------------- |
| spring.ai.oci.genai.authenticationType | 向 OCI 进行身份验证时使用的身份验证类型。可以是 `file`、`instance-principal`、`workload-identity` 或 `simple`。 | file |
| spring.ai.oci.genai.region | OCI 服务区域。 | us-chicago-1 |
| spring.ai.oci.genai.tenantId | OCI 租户 OCID，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.userId | OCI 用户 OCID，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.fingerprint | 私钥指纹，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.privateKey | 私钥内容，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.passPhrase | 可选的私钥密码，在使用 `simple` 身份验证和受密码保护的私钥时使用。 | - |
| spring.ai.oci.genai.file | OCI 配置文件路径。在使用 `file` 身份验证时使用。 | 用户主目录/.oci/config |
| spring.ai.oci.genai.profile | OCI 配置文件名称。在使用 `file` 身份验证时使用。 | DEFAULT |
| spring.ai.oci.genai.endpoint | 可选的 OCI GenAI 端点。 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=oci-genai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 oci-genai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.oci.genai.chat.cohere` 是配置 OCI GenAI Cohere Chat 的 `ChatModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------------- | :---------------------------------------- | :-------- |
| spring.ai.model.chat | 启用 OCI GenAI Cohere 聊天模型。 | oci-genai |
| spring.ai.oci.genai.chat.cohere.enabled (不再有效) | 启用 OCI GenAI Cohere 聊天模型。 | true |
| spring.ai.oci.genai.chat.cohere.options.model | 模型 OCID 或端点 | - |
| spring.ai.oci.genai.chat.cohere.options.compartment | 模型区间 OCID。 | - |
| spring.ai.oci.genai.chat.cohere.options.servingMode | 要使用的模型服务模式。可以是 `on-demand` 或 `dedicated`。 | on-demand |
| spring.ai.oci.genai.chat.cohere.options.preambleOverride | 覆盖聊天模型的提示前导 | - |
| spring.ai.oci.genai.chat.cohere.options.temperature | 推理温度 | - |
| spring.ai.oci.genai.chat.cohere.options.topP | Top P 参数 | - |
| spring.ai.oci.genai.chat.cohere.options.topK | Top K 参数 | - |
| spring.ai.oci.genai.chat.cohere.options.frequencyPenalty | 较高的值会减少重复的标记，输出会更随机。 | - |
| spring.ai.oci.genai.chat.cohere.options.presencePenalty | 较高的值鼓励生成包含尚未使用过的标记的输出。 | - |
| spring.ai.oci.genai.chat.cohere.options.stop | 将结束补全生成的文本序列列表。 | - |
| spring.ai.oci.genai.chat.cohere.options.documents | 聊天上下文中使用的文档列表。 | - |
所有以 `spring.ai.oci.genai.chat.cohere.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
## 运行时选项
[OCICohereChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-oci-genai/src/main/java/org/springframework/ai/oci/cohere/OCICohereChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `OCICohereChatModel(api, options)` 构造函数或 `spring.ai.oci.genai.chat.cohere.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OCICohereChatOptions.builder()
.model("我的模型ocid")
.compartment("我的区间ocid")
.temperature(0.5)
.build()
));
```
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-oci-genai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OCI GenAI Cohere 聊天模型：
```properties theme={"system"}
spring.ai.oci.genai.authenticationType=file
spring.ai.oci.genai.file=/path/to/oci/config/file
spring.ai.oci.genai.cohere.chat.options.compartment=我的区间ocid
spring.ai.oci.genai.cohere.chat.options.servingMode=on-demand
spring.ai.oci.genai.cohere.chat.options.model=我的聊天模型ocid
```
将 `file`、`compartment` 和 `model` 替换为你的 OCI 帐户中的值。
这将创建一个 `OCICohereChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成。
```java theme={"system"}
@RestController
public class ChatController {
private final OCICohereChatModel chatModel;
@Autowired
public ChatController(OCICohereChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
return Map.of("generation", chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
var prompt = new Prompt(new UserMessage(message));
return chatModel.stream(prompt);
}
}
```
## 手动配置
[OCICohereChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-oci-genai/src/main/java/org/springframework/ai/oci/cohere/OCICohereChatModel.java) 实现了 `ChatModel` 并使用 OCI Java SDK 连接到 OCI GenAI 服务。
将 `spring-ai-oci-genai` 依赖项添加到项目的构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-oci-genai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-oci-genai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
接下来，创建一个 `OCICohereChatModel` 并将其用于文本生成：
```java theme={"system"}
var CONFIG_FILE = Paths.get(System.getProperty("user.home"), ".oci", "config").toString();
var COMPARTMENT_ID = System.getenv("OCI_COMPARTMENT_ID");
var MODEL_ID = System.getenv("OCI_CHAT_MODEL_ID");
ConfigFileAuthenticationDetailsProvider authProvider = new ConfigFileAuthenticationDetailsProvider(
CONFIG_FILE,
"DEFAULT"
);
var genAi = GenerativeAiInferenceClient.builder()
.region(Region.valueOf("us-chicago-1"))
.build(authProvider);
var chatModel = new OCICohereChatModel(genAi, OCICohereChatOptions.builder()
.model(MODEL_ID)
.compartment(COMPARTMENT_ID)
.servingMode("on-demand")
.build());
ChatResponse response = chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
```
`OCICohereChatOptions` 为聊天请求提供配置信息。
`OCICohereChatOptions.Builder` 是流畅的选项构建器。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Ollama 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/ollama-chat
使用 [Ollama](https://ollama.ai/)，你可以在本地运行各种大型语言模型 (LLM) 并从中生成文本。
Spring AI 支持 Ollama 聊天补全功能，并提供 `OllamaChatModel` API。
Ollama 也提供 OpenAI API 兼容端点。
请查看 [OpenAI API 兼容性](/spring4ai/api/chat/openai-chat#openai-api-compatibility) 部分，了解如何使用 [Spring AI OpenAI](/spring4ai/api/chat/openai-chat) 集成与 Ollama 服务器通信。
## 前提条件
你首先需要访问 Ollama 实例。有几种选择，包括以下几种：
* 在你的本地计算机上[下载并安装 Ollama](https://ollama.com/download)。
* 通过 [Testcontainers](/spring4ai/api/testcontainers) 配置并[运行 Ollama](/spring4ai/api/testcontainers)。
* 通过 [Kubernetes 服务绑定](/spring4ai/api/cloud-bindings)绑定到 Ollama 实例。
你可以从 [Ollama 模型库](https://ollama.com/library)中拉取要在应用程序中使用的模型：
```bash theme={"system"}
ollama pull <模型名称>
```
你还可以拉取数千个免费的 [GGUF Hugging Face 模型](https://huggingface.co/models?library=gguf\&sort=trending)中的任何一个：
```bash theme={"system"}
ollama pull hf.co/<用户名>/<模型仓库>
```
或者，你可以启用自动下载任何所需模型的选项：[自动拉取模型](#auto-pulling-models)。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Ollama 聊天集成提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-ollama
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 基本属性
前缀 `spring.ai.ollama` 是用于配置与 Ollama 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------ | :----------------------- | :----------------------- |
| spring.ai.ollama.base-url | Ollama API 服务器运行的基本 URL。 | `http://localhost:11434` |
以下是用于初始化 Ollama 集成和[自动拉取模型](#auto-pulling-models)的属性。
| 属性 | 描述 | 默认值 |
| :------------------------------------------- | :-------------------------- | :------ |
| spring.ai.ollama.init.pull-model-strategy | 是否在启动时拉取模型以及如何拉取。 | `never` |
| spring.ai.ollama.init.timeout | 等待模型拉取的时间。 | `5m` |
| spring.ai.ollama.init.max-retries | 模型拉取操作的最大重试次数。 | `0` |
| spring.ai.ollama.init.chat.include | 在初始化任务中包含此类型的模型。 | `true` |
| spring.ai.ollama.init.chat.additional-models | 除了通过默认属性配置的模型之外，还要初始化的其他模型。 | `[]` |
### 聊天属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=ollama` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 ollama 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.ollama.chat.options` 是配置 Ollama 聊天模型的属性前缀。
它包括 Ollama 请求（高级）参数，例如 `model`、`keep-alive` 和 `format`，以及 Ollama 模型 `options` 属性。
以下是 Ollama 聊天模型的高级请求参数：
| 属性 | 描述 | 默认值 |
| :---------------------------------------- | :--------------------------------------------------------------------------------- | :------ |
| spring.ai.ollama.chat.enabled (已移除且不再有效) | 启用 Ollama 聊天模型。 | true |
| spring.ai.model.chat | 启用 Ollama 聊天模型。 | ollama |
| spring.ai.ollama.chat.options.model | 要使用的[支持的模型](https://github.com/ollama/ollama?tab=readme-ov-file#model-library)的名称。 | mistral |
| spring.ai.ollama.chat.options.format | 返回响应的格式。目前，唯一接受的值是 `json` | - |
| spring.ai.ollama.chat.options.keep\_alive | 控制请求后模型在内存中保留多长时间 | 5m |
其余 `options` 属性基于 [Ollama 有效参数和值](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values) 和 [Ollama 类型](https://github.com/ollama/ollama/blob/main/api/types.go)。默认值基于 [Ollama 类型默认值](https://github.com/ollama/ollama/blob/b538dc3858014f94b099730a592751a5454cab0a/api/types.go#L364)。
| 属性 | 描述 | 默认值 |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---- |
| spring.ai.ollama.chat.options.numa | 是否使用 NUMA。 | false |
| spring.ai.ollama.chat.options.num-ctx | 设置用于生成下一个标记的上下文窗口的大小。 | 2048 |
| spring.ai.ollama.chat.options.num-batch | 提示处理最大批处理大小。 | 512 |
| spring.ai.ollama.chat.options.num-gpu | 要发送到 GPU 的层数。在 macOS 上，默认为 1 以启用 metal 支持，0 以禁用。此处的 1 表示应动态设置 NumGPU | -1 |
| spring.ai.ollama.chat.options.main-gpu | 使用多个 GPU 时，此选项控制哪个 GPU 用于小型张量，对于这些张量，跨所有 GPU 拆分计算的开销不值得。相关 GPU 将使用稍多的 VRAM 来存储用于临时结果的暂存缓冲区。 | 0 |
| spring.ai.ollama.chat.options.low-vram | - | false |
| spring.ai.ollama.chat.options.f16-kv | - | true |
| spring.ai.ollama.chat.options.logits-all | 返回所有标记的 logits，而不仅仅是最后一个。要使补全返回 logprobs，此项必须为 true。 | - |
| spring.ai.ollama.chat.options.vocab-only | 仅加载词汇表，而不加载权重。 | - |
| spring.ai.ollama.chat.options.use-mmap | 默认情况下，模型会映射到内存中，这允许系统根据需要仅加载模型的必要部分。但是，如果模型大于你的总 RAM 量，或者你的系统可用内存不足，则使用 mmap 可能会增加页面换出的风险，从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢，但如果你不使用 mlock，则可能会减少页面换出。请注意，如果模型大于总 RAM 量，则关闭 mmap 将阻止模型完全加载。 | null |
| spring.ai.ollama.chat.options.use-mlock | 将模型锁定在内存中，防止在内存映射时将其换出。这可以提高性能，但会牺牲内存映射的一些优势，因为它需要更多 RAM 才能运行，并且随着模型加载到 RAM 中，可能会减慢加载时间。 | false |
| spring.ai.ollama.chat.options.num-thread | 设置计算期间要使用的线程数。默认情况下，Ollama 会检测此值以获得最佳性能。建议将此值设置为系统具有的物理 CPU 内核数（而不是逻辑内核数）。0 = 让运行时决定 | 0 |
| spring.ai.ollama.chat.options.num-keep | - | 4 |
| spring.ai.ollama.chat.options.seed | 设置用于生成的随机数种子。将其设置为特定数字将使模型为相同的提示生成相同的文本。 | -1 |
| spring.ai.ollama.chat.options.num-predict | 生成文本时要预测的最大标记数。（-1 = 无限生成，-2 = 填充上下文） | -1 |
| spring.ai.ollama.chat.options.top-k | 降低生成无意义内容的概率。较高的值（例如 100）将提供更多样化的答案，而较低的值（例如 10）将更保守。 | 40 |
| spring.ai.ollama.chat.options.top-p | 与 top-k 一起使用。较高的值（例如 0.95）将导致更多样化的文本，而较低的值（例如 0.5）将生成更集中和保守的文本。 | 0.9 |
| spring.ai.ollama.chat.options.min-p | top\_p 的替代方案，旨在确保质量和多样性的平衡。参数 p 表示要考虑的标记的最小概率，相对于最可能标记的概率。例如，当 p=0.05 且最可能标记的概率为 0.9 时，值小于 0.045 的 logits 将被过滤掉。 | 0.0 |
| spring.ai.ollama.chat.options.tfs-z | 无尾采样用于减少输出中不太可能的标记的影响。较高的值（例如 2.0）将更多地减少影响，而值 1.0 将禁用此设置。 | 1.0 |
| spring.ai.ollama.chat.options.typical-p | - | 1.0 |
| spring.ai.ollama.chat.options.repeat-last-n | 设置模型向后查看多远以防止重复。（默认值：64，0 = 禁用，-1 = num\_ctx） | 64 |
| spring.ai.ollama.chat.options.temperature | 模型的温度。增加温度会使模型回答更具创造性。 | 0.8 |
| spring.ai.ollama.chat.options.repeat-penalty | 设置对重复的惩罚强度。较高的值（例如 1.5）将更强烈地惩罚重复，而较低的值（例如 0.9）将更宽松。 | 1.1 |
| spring.ai.ollama.chat.options.presence-penalty | - | 0.0 |
| spring.ai.ollama.chat.options.frequency-penalty | - | 0.0 |
| spring.ai.ollama.chat.options.mirostat | 启用 Mirostat 采样以控制困惑度。（默认值：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0） | 0 |
| spring.ai.ollama.chat.options.mirostat-tau | 控制输出的连贯性和多样性之间的平衡。较低的值将导致更集中和连贯的文本。 | 5.0 |
| spring.ai.ollama.chat.options.mirostat-eta | 影响算法对生成文本反馈的响应速度。较低的学习率将导致较慢的调整，而较高的学习率将使算法更具响应性。 | 0.1 |
| spring.ai.ollama.chat.options.penalize-newline | - | true |
| spring.ai.ollama.chat.options.stop | 设置要使用的停止序列。遇到此模式时，LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的 stop 参数来设置多个停止模式。 | - |
| spring.ai.ollama.chat.options.functions | 在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
| spring.ai.ollama.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
所有以 `spring.ai.ollama.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
## 运行时选项
[OllamaOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaOptions.java) 类提供模型配置，例如要使用的模型、温度等。
在启动时，可以使用 `OllamaChatModel(api, options)` 构造函数或 `spring.ai.ollama.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OllamaOptions.builder()
.model(OllamaModel.LLAMA3_1)
.temperature(0.4)
.build()
));
```
除了特定于模型的 [OllamaOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 自动拉取模型
当 Ollama 实例中没有可用模型时，Spring AI Ollama 可以自动拉取模型。
此功能对于开发和测试以及将应用程序部署到新环境特别有用。
你还可以按名称拉取数千个免费的 [GGUF Hugging Face 模型](https://huggingface.co/models?library=gguf\&sort=trending)中的任何一个。
有三种拉取模型的策略：
* `always` (在 `PullModelStrategy.ALWAYS` 中定义)：始终拉取模型，即使它已经可用。用于确保你使用的是最新版本的模型。
* `when_missing` (在 `PullModelStrategy.WHEN_MISSING` 中定义)：仅当模型尚不可用时才拉取模型。这可能会导致使用较旧版本的模型。
* `never` (在 `PullModelStrategy.NEVER` 中定义)：从不自动拉取模型。
由于下载模型时可能会出现延迟，因此不建议在生产环境中使用自动拉取。相反，请考虑提前评估和预下载必要的模型。
所有通过配置属性和默认选项定义的模型都可以在启动时自动拉取。
你可以使用配置属性配置拉取策略、超时和最大重试次数：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
timeout: 60s
max-retries: 1
```
在 Ollama 中所有指定的模型都可用之前，应用程序不会完成其初始化。根据模型大小和互联网连接速度，这可能会显著减慢应用程序的启动时间。
你可以在启动时初始化其他模型，这对于在运行时动态使用的模型很有用：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
chat:
additional-models:
- llama3.2
- qwen2.5
```
如果你只想将拉取策略应用于特定类型的模型，则可以从初始化任务中排除聊天模型：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
chat:
include: false
```
此配置将拉取策略应用于除聊天模型之外的所有模型。
## 函数调用
你可以使用 `OllamaChatModel` 注册自定义 Java 函数，并让 Ollama 模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关[工具调用](/spring4ai/api/tools)的更多信息。
你需要 Ollama 0.2.8 或更高版本才能使用函数调用功能，需要 Ollama 0.4.6 或更高版本才能在流模式下使用它们。
## 多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。
Ollama 中一些支持多模态的模型是 [LLaVA](https://ollama.com/library/llava) 和 [BakLLaVA](https://ollama.com/library/bakllava)（请参阅[完整列表](https://ollama.com/search?c=vision)）。
有关更多详细信息，请参阅 [LLaVA：大型语言和视觉助手](https://llava-vl.github.io/)。
Ollama [消息 API](https://github.com/ollama/ollama/blob/main/docs/api.md#parameters-1) 提供了一个"图像"参数，用于将 base64 编码的图像列表与消息合并。
Spring AI 的 [Message](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/messages/Message.java) 接口通过引入 [Media](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/model/Media.java) 类型来促进多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和详细信息，利用 Spring 的 `org.springframework.util.MimeType` 和 `org.springframework.core.io.Resource` 来获取原始媒体数据。
以下是从 [OllamaChatModelMultimodalIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/test/java/org/springframework/ai/ollama/OllamaChatModelMultimodalIT.java) 中摘录的一个简单代码示例，说明了用户文本与图像的融合。
```java theme={"system"}
var imageResource = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage("解释一下你在这张图片上看到了什么？",
new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));
ChatResponse response = chatModel.call(new Prompt(this.userMessage,
OllamaOptions.builder().model(OllamaModel.LLAVA)).build());
```
该示例显示了一个模型，它将 `multimodal.test.png` 图像作为输入：
![多模态测试图像]()
以及文本消息"解释一下你在这张图片上看到了什么？"，并生成如下响应：
```
图片显示了一个装满成熟香蕉和红苹果的小金属篮子。篮子放在一个表面上，
看起来像一张桌子或台面，因为背景中隐约可见似乎是厨柜或抽屉的东西。
篮子后面还有一个金色的环，这可能表明这张照片是在一个有金属装饰品或固定装置的区域拍摄的。
整体环境表明这是一个家庭环境，水果正在展示，可能是为了方便或美观。
```
## 结构化输出
Ollama 提供自定义[结构化输出](https://ollama.com/blog/structured-outputs) API，可确保你的模型生成的响应严格符合你提供的 `JSON Schema`。
除了现有的与 Spring AI 模型无关的[结构化输出转换器](/spring4ai/api/structured-output-converter)之外，这些 API 还提供了增强的控制和精度。
### 配置
Spring AI 允许你使用 `OllamaOptions` 构建器以编程方式配置响应格式。
#### 使用聊天选项构建器
你可以使用 `OllamaOptions` 构建器以编程方式设置响应格式，如下所示：
```java theme={"system"}
String jsonSchema = """
{
"type": "object",
"properties": {
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"explanation": { "type": "string" },
"output": { "type": "string" }
},
"required": ["explanation", "output"],
"additionalProperties": false
}
},
"final_answer": { "type": "string" }
},
"required": ["steps", "final_answer"],
"additionalProperties": false
}
""";
Prompt prompt = new Prompt("如何求解 8x + 7 = -23",
OllamaOptions.builder()
.model(OllamaModel.LLAMA3_2.getName())
.format(new ObjectMapper().readValue(jsonSchema, Map.class))
.build());
ChatResponse response = this.ollamaChatModel.call(this.prompt);
```
#### 与 BeanOutputConverter 实用程序集成
你可以利用现有的 [BeanOutputConverter](/spring4ai/api/structured-output-converter#_bean_output_converter) 实用程序从你的域对象自动生成 JSON Schema，然后将结构化响应转换为特定于域的实例：
```java theme={"system"}
record MathReasoning(
@JsonProperty(required = true, value = "steps") Steps steps,
@JsonProperty(required = true, value = "final_answer") String finalAnswer) {
record Steps(
@JsonProperty(required = true, value = "items") Items[] items) {
record Items(
@JsonProperty(required = true, value = "explanation") String explanation,
@JsonProperty(required = true, value = "output") String output) {
}
}
}
var outputConverter = new BeanOutputConverter<>(MathReasoning.class);
Prompt prompt = new Prompt("如何求解 8x + 7 = -23",
OllamaOptions.builder()
.model(OllamaModel.LLAMA3_2.getName())
.format(outputConverter.getJsonSchemaMap())
.build());
ChatResponse response = this.ollamaChatModel.call(this.prompt);
String content = this.response.getResult().getOutput().getText();
MathReasoning mathReasoning = this.outputConverter.convert(this.content);
```
确保使用 `@JsonProperty(required = true,...)` 注释来生成准确标记字段为 `required` 的模式。
尽管这对于 JSON Schema 是可选的，但建议这样做以使结构化响应正常工作。
## OpenAI API 兼容性
Ollama 与 OpenAI API 兼容，你可以使用 [Spring AI OpenAI](/spring4ai/api/chat/openai-chat) 客户端与 Ollama 通信并使用工具。
为此，你需要将 OpenAI 基本 URL 配置为你的 Ollama 实例：`spring.ai.openai.chat.base-url=http://localhost:11434` 并选择提供的 Ollama 模型之一：`spring.ai.openai.chat.options.model=mistral`。
![Ollama OpenAI API 兼容性]()
请查看 [OllamaWithOpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/OllamaWithOpenAiChatModelIT.java) 测试，获取通过 Spring AI OpenAI 使用 Ollama 的示例。
## HuggingFace 模型
Ollama 可以开箱即用地访问所有 [GGUF Hugging Face](https://huggingface.co/models?library=gguf\&sort=trending) 聊天模型。
你可以按名称拉取这些模型中的任何一个：`ollama pull hf.co/<用户名>/<模型仓库>` 或配置自动拉取策略：[自动拉取模型](#auto-pulling-models)：
```properties theme={"system"}
spring.ai.ollama.chat.options.model=hf.co/bartowski/gemma-2-2b-it-GGUF
spring.ai.ollama.init.pull-model-strategy=always
```
* `spring.ai.ollama.chat.options.model`：指定要使用的 [Hugging Face GGUF 模型](https://huggingface.co/models?library=gguf\&sort=trending)。
* `spring.ai.ollama.init.pull-model-strategy=always`：（可选）在启动时启用自动模型拉取。
对于生产环境，你应该预先下载模型以避免延迟：`ollama pull hf.co/bartowski/gemma-2-2b-it-GGUF`。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-ollama` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.yaml` 文件，以启用和配置 Ollama 聊天模型：
```yaml theme={"system"}
spring:
ai:
ollama:
base-url: http://localhost:11434
chat:
options:
model: mistral
temperature: 0.7
```
将 `base-url` 替换为你的 Ollama 服务器 URL。
这将创建一个 `OllamaChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@RestController` 类的示例，该类使用聊天模型进行文本生成：
```java theme={"system"}
@RestController
public class ChatController {
private final OllamaChatModel chatModel;
@Autowired
public ChatController(OllamaChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
如果你不想使用 Spring Boot 自动配置，可以在应用程序中手动配置 `OllamaChatModel`。
[OllamaChatModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/OllamaChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用[低级 API](#low-level-api)连接到 Ollama 服务。
要使用它，请将 `spring-ai-ollama` 依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-ollama
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-ollama'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
`spring-ai-ollama` 依赖项还提供对 `OllamaEmbeddingModel` 的访问。
有关 `OllamaEmbeddingModel` 的更多信息，请参阅 [Ollama 嵌入模型](/spring4ai/api/embeddings/ollama-embeddings) 部分。
接下来，创建一个 `OllamaChatModel` 实例并将其用于发送文本生成请求：
```java theme={"system"}
var ollamaApi = OllamaApi.builder().build();
var chatModel = OllamaChatModel.builder()
.ollamaApi(ollamaApi)
.defaultOptions(
OllamaOptions.builder()
.model(OllamaModel.MISTRAL)
.temperature(0.9)
.build())
.build();
ChatResponse response = this.chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux response = this.chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
`OllamaOptions` 为所有聊天请求提供配置信息。
## 低级 OllamaApi 客户端
[OllamaApi](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaApi.java) 提供了轻量级的 Java 客户端，用于 [Ollama 聊天补全 API](https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion)。
以下类图说明了 `OllamaApi` 聊天接口和构建块：
![OllamaApi 聊天补全 API 图]()
`OllamaApi` 是一个低级 API，不建议直接使用。请改用 `OllamaChatModel`。
以下是一个简单的代码片段，展示了如何以编程方式使用 API：
```java theme={"system"}
OllamaApi ollamaApi = new OllamaApi("你的主机:你的端口");
// 同步请求
var request = ChatRequest.builder("orca-mini")
.stream(false) // 非流式
.messages(List.of(
Message.builder(Role.SYSTEM)
.content("你是一名地理老师。你正在和一名学生交谈。")
.build(),
Message.builder(Role.USER)
.content("保加利亚的首都是哪里，面积有多大？ "
+ "国歌是什么？")
.build()))
.options(OllamaOptions.builder().temperature(0.9).build())
.build();
ChatResponse response = this.ollamaApi.chat(this.request);
// 流式请求
var request2 = ChatRequest.builder("orca-mini")
.stream(true) // 流式
.messages(List.of(Message.builder(Role.USER)
.content("保加利亚的首都是哪里，面积有多大？ " + "国歌是什么？")
.build()))
.options(OllamaOptions.builder().temperature(0.9).build().toMap())
.build();
Flux streamingResponse = this.ollamaApi.streamingChat(this.request2);
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OpenAI 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/openai-chat
Spring AI 支持 OpenAI 提供的各种 AI 语言模型。OpenAI 是 ChatGPT 背后的公司，凭借其创建的行业领先的文本生成模型和嵌入，在激发人们对 AI 驱动的文本生成的兴趣方面发挥了重要作用。
## 前提条件
你需要使用 OpenAI 创建一个 API 才能访问 ChatGPT 模型。
在 [OpenAI 注册页面](https://platform.openai.com/signup) 创建一个帐户，并在 [API 密钥页面](https://platform.openai.com/account/api-keys) 生成令牌。
Spring AI 项目定义了一个名为 `spring.ai.openai.api-key` 的配置属性，你应该将其设置为从 openai.com 获取的 `API 密钥` 的值。
你可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.openai.api-key=<你的-openai-api-密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
```
```bash theme={"system"}
# 在你的环境或 .env 文件中
export OPENAI_API_KEY=<你的-openai-api-密钥>
```
你也可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("OPENAI_API_KEY");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-openai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
## 配置属性
:::note
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，spring.ai.model.chat=openai (默认启用)
要禁用，spring.ai.model.chat=none (或任何与 openai 不匹配的值)
此更改是为了允许配置多个模型。
:::
### 连接属性
前缀 `spring.ai.openai` 用作属性前缀，允许你连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| -------------------------------- | ---------------------- | ------------------------------------------------ |
| spring.ai.openai.base-url | 要连接的 URL | [https://api.openai.com](https://api.openai.com) |
| spring.ai.openai.api-key | API 密钥 | - |
| spring.ai.openai.organization-id | 可选地，你可以指定用于 API 请求的组织。 | - |
| spring.ai.openai.project-id | 可选地，你可以指定用于 API 请求的项目。 | - |
:::tip
对于属于多个组织的用户（或通过其旧版用户 API 密钥访问其项目的用户），你可以选择指定用于 API 请求的组织和项目。
来自这些 API 请求的使用量将计为指定组织和项目的使用量。
:::
### 聊天属性
前缀 `spring.ai.openai.chat` 是属性前缀，允许你配置 OpenAI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| spring.ai.model.chat | 启用 OpenAI 聊天模型。 | openai |
| spring.ai.openai.chat.base-url | 可选地覆盖 `spring.ai.openai.base-url` 属性以提供特定于聊天的 URL。 | - |
| spring.ai.openai.chat.completions-path | 要附加到基本 URL 的路径。 | `/v1/chat/completions` |
| spring.ai.openai.chat.api-key | 可选地覆盖 `spring.ai.openai.api-key` 以提供特定于聊天的 API 密钥。 | - |
| spring.ai.openai.chat.organization-id | 可选地，你可以指定用于 API 请求的组织。 | - |
| spring.ai.openai.chat.project-id | 可选地，你可以指定用于 API 请求的项目。 | - |
| spring.ai.openai.chat.options.model | 要使用的 OpenAI 聊天模型的名称。你可以在诸如 `gpt-4o`、`gpt-4o-mini`、`gpt-4-turbo`、`gpt-3.5-turbo` 等模型之间进行选择。有关更多信息，请参阅[模型](https://platform.openai.com/docs/models)页面。 | `gpt-4o-mini` |
| spring.ai.openai.chat.options.temperature | 用于控制生成补全的明显创造性的采样温度。较高的值会使输出更随机，而较低的值会使结果更集中和确定。不建议为同一补全请求修改 `temperature` 和 `top_p`，因为这两个设置的相互作用很难预测。 | 0.8 |
| spring.ai.openai.chat.options.frequencyPenalty | -2.0 到 2.0 之间的数字。正值会根据新标记在文本中已有的频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。 | 0.0f |
| spring.ai.openai.chat.options.logitBias | 修改指定标记在补全中出现的可能性。 | - |
| spring.ai.openai.chat.options.maxTokens | (已弃用，建议使用 `maxCompletionTokens`) 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | - |
| spring.ai.openai.chat.options.maxCompletionTokens | 可为补全生成的标记数的上限，包括可见输出标记和推理标记。 | - |
| spring.ai.openai.chat.options.n | 为每个输入消息生成多少个聊天补全选项。请注意，你将根据所有选项中生成的标记数付费。将 `n` 保持为 1 以最大程度地降低成本。 | 1 |
| spring.ai.openai.chat.options.store | 是否存储此聊天补全请求的输出以用于我们的模型 | false |
| spring.ai.openai.chat.options.metadata | 用于在聊天补全仪表板中筛选补全的开发人员定义的标签和值 | 空映射 |
| spring.ai.openai.chat.options.output-modalities | 你希望模型为此请求生成的输出类型。大多数模型都能够生成文本，这是默认设置。`gpt-4o-audio-preview` 模型也可用于生成音频。要请求此模型同时生成文本和音频响应，你可以使用：`text`、`audio`。不支持流式传输。 | - |
| spring.ai.openai.chat.options.output-audio | 音频生成的音频参数。当使用 `output-modalities` 请求音频输出时是必需的：`audio`。需要 `gpt-4o-audio-preview` 模型，并且不支持流式补全。 | - |
| spring.ai.openai.chat.options.presencePenalty | -2.0 到 2.0 之间的数字。正值会根据新标记是否已出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。 | - |
| spring.ai.openai.chat.options.responseFormat.type | 与 `GPT-4o`、`GPT-4o mini`、`GPT-4 Turbo` 以及所有比 `gpt-3.5-turbo-1106` 新的 `GPT-3.5 Turbo` 模型兼容。`JSON_OBJECT` 类型启用 JSON 模式，可确保模型生成的消息是有效的 JSON。`JSON_SCHEMA` 类型启用[结构化输出](https://platform.openai.com/docs/guides/structured-outputs)，可确保模型与你提供的 JSON 模式匹配。`JSON_SCHEMA` 类型还需要设置 `responseFormat.schema` 属性。 | - |
| spring.ai.openai.chat.options.responseFormat.name | 响应格式模式名称。仅适用于 `responseFormat.type=JSON_SCHEMA` | custom\_schema |
| spring.ai.openai.chat.options.responseFormat.schema | 响应格式 JSON 模式。仅适用于 `responseFormat.type=JSON_SCHEMA` | - |
| spring.ai.openai.chat.options.responseFormat.strict | 响应格式 JSON 模式遵循严格性。仅适用于 `responseFormat.type=JSON_SCHEMA` | - |
| spring.ai.openai.chat.options.seed | 此功能处于测试阶段。如果指定，我们的系统将尽最大努力进行确定性采样，以便具有相同种子和参数的重复请求应返回相同的结果。 | - |
| spring.ai.openai.chat.options.stop | API 将停止生成更多标记的最多 4 个序列。 | - |
| spring.ai.openai.chat.options.topP | 温度采样的替代方法，称为核采样，其中模型考虑具有 `top_p` 概率质量的标记的结果。因此 0.1 表示仅考虑构成前 10% 概率质量的标记。我们通常建议更改此项或 `temperature`，但不能同时更改两者。 | - |
| spring.ai.openai.chat.options.tools | 模型可能调用的工具列表。目前，仅支持函数作为工具。使用此选项可提供模型可能为其生成 JSON 输入的函数列表。 | - |
| spring.ai.openai.chat.options.toolChoice | 控制模型调用哪个（如果有）函数。`none` 表示模型不会调用函数，而是生成一条消息。`auto` 表示模型可以在生成消息或调用函数之间进行选择。通过 `{"type: "function", "function": {"name": "my_function"}}` 指定特定函数会强制模型调用该函数。当不存在函数时，`none` 是默认值。如果存在函数，则 `auto` 是默认值。 | - |
| spring.ai.openai.chat.options.user | 代表你的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。 | - |
| spring.ai.openai.chat.options.functions | 在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 `functionCallbacks` 注册表中。 | - |
| spring.ai.openai.chat.options.stream-usage | （仅限流式传输）设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 `choices` 字段是一个空数组，所有其他块也将包含一个 usage 字段，但其值为 null。 | false |
| spring.ai.openai.chat.options.parallel-tool-calls | 在工具使用期间是否启用[并行函数调用](https://platform.openai.com/docs/guides/function-calling/parallel-function-calling)。 | true |
| spring.ai.openai.chat.options.http-headers | 要添加到聊天补全请求的可选 HTTP 标头。要覆盖 `api-key`，你需要使用 `Authorization` 标头键，并且必须在键值前加上 `Bearer` 前缀。 | - |
| spring.ai.openai.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
:::note
你可以为 `ChatModel` 和 `EmbeddingModel` 实现覆盖通用的 `spring.ai.openai.base-url` 和 `spring.ai.openai.api-key`。
如果设置了 `spring.ai.openai.chat.base-url` 和 `spring.ai.openai.chat.api-key` 属性，则它们优先于通用属性。
如果你想为不同的模型和不同的模型端点使用不同的 OpenAI 帐户，这将非常有用。
:::
:::tip
所有以 `spring.ai.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
:::
## 运行时选项
[OpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java) 类提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `OpenAiChatModel(api, options)` 构造函数或 `spring.ai.openai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OpenAiChatOptions.builder()
.model("gpt-4o")
.temperature(0.4)
.build()
));
```
## 低级 OpenAiApi 客户端
[OpenAiApi](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/api/OpenAiApi.java) 提供了轻量级的 Java 客户端，用于 [OpenAI 聊天 API](https://platform.openai.com/docs/api-reference/chat)。
以下类图说明了 `OpenAiApi` 聊天接口和构建块：
![OpenAiApi 聊天 API 图]()
以下是一个简单的代码片段，展示了如何以编程方式使用 API：
```java theme={"system"}
OpenAiApi openAiApi = OpenAiApi.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("你好世界", Role.USER);
// 同步请求
ResponseEntity response = this.openAiApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), "gpt-3.5-turbo", 0.8, false));
// 流式请求
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Perplexity 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/perplexity-chat
[Perplexity AI](https://perplexity.ai/) 提供独特的 AI 服务，将其语言模型与实时搜索功能相结合。它提供多种模型并支持流式响应以实现对话式 AI。
Spring AI 通过复用现有的 [OpenAI](/spring4ai/api/chat/openai-chat) 客户端与 Perplexity AI 集成。要开始使用，你需要获取一个 [Perplexity API 密钥](https://docs.perplexity.ai/guides/getting-started)，配置基本 URL，并选择一个支持的[模型](https://docs.perplexity.ai/guides/model-cards)。
![]()
Perplexity API 与 OpenAI API 不完全兼容。
Perplexity 将实时 Web 搜索结果与其语言模型响应相结合。
与 OpenAI 不同，Perplexity 不公开 `toolCalls` - `function call` 机制。
此外，目前 Perplexity 不支持多模态消息。
请查看 [PerplexityWithOpenAiChatModelIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/PerplexityWithOpenAiChatModelIT.java) 测试，获取将 Perplexity 与 Spring AI 结合使用的示例。
## 前提条件
* **创建 API 密钥**：
访问[此处](https://docs.perplexity.ai/guides/getting-started)创建 API 密钥。
在你的 Spring AI 项目中使用 `spring.ai.openai.api-key` 属性进行配置。
* **设置 Perplexity 基本 URL**：
将 `spring.ai.openai.base-url` 属性设置为 `https://api.perplexity.ai`。
* **选择 Perplexity 模型**：
使用 `spring.ai.openai.chat.model=<模型名称>` 属性指定模型。
有关可用选项，请参阅[支持的模型](https://docs.perplexity.ai/guides/model-cards)。
* **设置聊天补全路径**：
将 `spring.ai.openai.chat.completions-path` 设置为 `/chat/completions`。
有关更多详细信息，请参阅[聊天补全 API](https://docs.perplexity.ai/api-reference/chat-completions)。
你可以在 `application.properties` 文件中设置这些配置属性：
```properties theme={"system"}
spring.ai.openai.api-key=<你的-perplexity-api-密钥>
spring.ai.openai.base-url=https://api.perplexity.ai
spring.ai.openai.chat.model=llama-3.1-sonar-small-128k-online
spring.ai.openai.chat.completions-path=/chat/completions
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
spring:
ai:
openai:
api-key: ${PERPLEXITY_API_KEY}
base-url: ${PERPLEXITY_BASE_URL}
chat:
model: ${PERPLEXITY_MODEL}
completions-path: ${PERPLEXITY_COMPLETIONS_PATH}
```
```bash theme={"system"}
export PERPLEXITY_API_KEY=<你的-perplexity-api-密钥>
export PERPLEXITY_BASE_URL=https://api.perplexity.ai
export PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-online
export PERPLEXITY_COMPLETIONS_PATH=/chat/completions
```
你也可以在应用程序代码中以编程方式设置这些配置：
```java theme={"system"}
// 从安全来源或环境变量中检索配置
String apiKey = System.getenv("PERPLEXITY_API_KEY");
String baseUrl = System.getenv("PERPLEXITY_BASE_URL");
String model = System.getenv("PERPLEXITY_MODEL");
String completionsPath = System.getenv("PERPLEXITY_COMPLETIONS_PATH");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-openai
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置 OpenAI 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.openai` 用作属性前缀，允许你连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| :---------------------------- | :----------------------------------------- | :-- |
| spring.ai.openai.base-url | 要连接的 URL。必须设置为 `https://api.perplexity.ai` | - |
| spring.ai.openai.chat.api-key | 你的 Perplexity API 密钥 | - |
#### 配置属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=openai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 openai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.openai.chat` 是属性前缀，允许你配置 OpenAI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------- |
| spring.ai.model.chat | 启用 OpenAI 聊天模型。 | openai |
| spring.ai.openai.chat.model | 支持的 [Perplexity 模型](https://docs.perplexity.ai/guides/model-cards)之一。例如：`llama-3.1-sonar-small-128k-online`。 | - |
| spring.ai.openai.chat.base-url | 可选地覆盖 spring.ai.openai.base-url 以提供特定于聊天的 url。必须设置为 `https://api.perplexity.ai` | - |
| spring.ai.openai.chat.completions-path | 必须设置为 `/chat/completions` | `/v1/chat/completions` |
| spring.ai.openai.chat.options.temperature | 响应中的随机性量，值介于 0（含）和 2（不含）之间。较高的值更随机，较低的值更具确定性。必需范围：`0 < x < 2`。 | 0.2 |
| spring.ai.openai.chat.options.frequencyPenalty | 大于 0 的乘法惩罚。大于 1.0 的值会根据新标记在文本中已有的频率对其进行惩罚，从而降低模型逐字重复同一行的可能性。值为 1.0 表示没有惩罚。与 presence\_penalty 不兼容。必需范围：`x > 0`。 | 1 |
| spring.ai.openai.chat.options.maxTokens | API 返回的最大补全标记数。max\_tokens 中请求的标记总数加上消息中发送的提示标记数不得超过所请求模型的上下文窗口标记限制。如果未指定，则模型将生成标记，直到达到其停止标记或其上下文窗口的末尾。 | - |
| spring.ai.openai.chat.options.presencePenalty | -2.0 到 2.0 之间的值。正值会根据新标记是否已出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。与 `frequency_penalty` 不兼容。必需范围：`-2 < x < 2` | 0 |
| spring.ai.openai.chat.options.topP | 核采样阈值，值介于 0 和 1（含）之间。对于每个后续标记，模型都会考虑具有 top\_p 概率质量的标记的结果。我们建议更改 top\_k 或 top\_p，但不能同时更改两者。必需范围：`0 < x < 1` | 0.9 |
| spring.ai.openai.chat.options.stream-usage | （仅限流式传输）设置为添加一个包含整个请求的标记使用情况统计信息的附加块。此块的 `choices` 字段是一个空数组，所有其他块也将包含一个 usage 字段，但其值为 null。 | false |
所有以 `spring.ai.openai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[运行时选项](#runtime-options)来覆盖。
## 运行时选项
[OpenAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `OpenAiChatModel(api, options)` 构造函数或 `spring.ai.openai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
OpenAiChatOptions.builder()
.model("llama-3.1-sonar-large-128k-online")
.temperature(0.4)
.build()
));
```
除了特定于模型的 [OpenAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java)之外，你还可以使用通过 [ChatOptions#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 函数调用
Perplexity 不支持显式函数调用。相反，它将搜索结果直接集成到响应中。
## 多模态
目前，Perplexity API 不支持媒体内容。
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-openai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 OpenAi 聊天模型：
```properties theme={"system"}
spring.ai.openai.api-key=
spring.ai.openai.base-url=https://api.perplexity.ai
spring.ai.openai.chat.completions-path=/chat/completions
spring.ai.openai.chat.options.model=llama-3.1-sonar-small-128k-online
spring.ai.openai.chat.options.temperature=0.7
# Perplexity API 不支持嵌入，因此我们需要禁用它。
spring.ai.openai.embedding.enabled=false
```
将 `api-key` 替换为你的 Perplexity Api 密钥。
这将创建一个 `OpenAiChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成：
```java theme={"system"}
@RestController
public class ChatController {
private final OpenAiChatModel chatModel;
@Autowired
public ChatController(OpenAiChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 支持的模型
Perplexity 支持多种针对搜索增强型对话 AI 优化的模型。有关详细信息，请参阅[支持的模型](https://docs.perplexity.ai/guides/model-cards)。
## 参考
* [文档主页](https://docs.perplexity.ai/home)
* [API 参考](https://docs.perplexity.ai/api-reference/chat-completions)
* [入门指南](https://docs.perplexity.ai/guides/getting-started)
* [速率限制](https://docs.perplexity.ai/guides/rate-limits)
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 千帆聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/qianfan-chat
此功能已移至 Spring AI 社区代码库。
请访问 [https://github.com/spring-ai-community/qianfan](https://github.com/spring-ai-community/qianfan) 获取最新版本。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# VertexAI Gemini 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/vertexai-gemini-chat
[Vertex AI Gemini API](https://cloud.google.com/vertex-ai/docs/generative-ai/multimodal/overview) 允许开发人员使用 Gemini 模型构建生成式 AI 应用程序。
Vertex AI Gemini API 支持多模态提示作为输入和输出文本或代码。
多模态模型是一种能够处理来自多种模态（包括图像、视频和文本）信息的模型。例如，你可以向模型发送一张饼干盘子的照片，并要求它提供这些饼干的食谱。
![]()
Gemini 是由 Google DeepMind 开发的一系列生成式 AI 模型，专为多模态用例而设计。Gemini API 允许你访问 [Gemini 2.0 Flash](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-0-flash) 和 [Gemini 2.0 Flash-Lite](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-0-flash-lite)。
有关 Vertex AI Gemini API 模型的规范，请参阅[模型信息](https://cloud.google.com/vertex-ai/generative-ai/docs/models#gemini-models)。
有关详细的 API 参考，请参阅 [Gemini API 参考](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference)。
## 前提条件
* 根据你的操作系统安装 [gcloud](https://cloud.google.com/sdk/docs/install) CLI。
* 通过运行以下命令进行身份验证。
将 `PROJECT_ID` 替换为你的 Google Cloud 项目 ID，将 `ACCOUNT` 替换为你的 Google Cloud 用户名。
```bash theme={"system"}
gcloud config set project &&\
gcloud auth application-default login
```
## 自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 VertexAI Gemini 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-vertex-ai-gemini
```
```gradle theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-vertex-ai-gemini'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
### 聊天属性
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，`spring.ai.model.chat=vertexai` (默认启用)
要禁用，`spring.ai.model.chat=none` (或任何与 vertexai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.vertex.ai.gemini` 用作属性前缀，允许你连接到 VertexAI。
| 属性 | 描述 | 默认值 |
| :----------------------------------------- | :----------------------------------------------------------------------------- | :------- |
| spring.ai.model.chat | 启用聊天模型客户端 | vertexai |
| spring.ai.vertex.ai.gemini.project-id | Google Cloud Platform 项目 ID | - |
| spring.ai.vertex.ai.gemini.location | 区域 | - |
| spring.ai.vertex.ai.gemini.credentials-uri | Vertex AI Gemini 凭据的 URI。提供时，它用于创建 `GoogleCredentials` 实例以对 `VertexAI` 进行身份验证。 | - |
| spring.ai.vertex.ai.gemini.api-endpoint | Vertex AI Gemini API 端点。 | - |
| spring.ai.vertex.ai.gemini.scopes | - | - |
| spring.ai.vertex.ai.gemini.transport | API 传输。GRPC 或 REST。 | GRPC |
前缀 `spring.ai.vertex.ai.gemini.chat` 是属性前缀，允许你配置 VertexAI Gemini Chat 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| :---------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| spring.ai.vertex.ai.gemini.chat.options.model | 支持的 [Vertex AI Gemini 聊天模型](https://cloud.google.com/vertex-ai/generative-ai/docs/models#gemini-models) 包括 `gemini-2.0-flash`、`gemini-2.0-flash-lite` 以及新的 `gemini-2.5-pro-preview-03-25`、`gemini-2.5-flash-preview-04-17` 模型。 | gemini-2.0-flash |
| spring.ai.vertex.ai.gemini.chat.options.response-mime-type | 生成的候选文本的输出响应 mimetype。 | `text/plain`：（默认）文本输出或 `application/json`：JSON 响应。 |
| spring.ai.vertex.ai.gemini.chat.options.google-search-retrieval | 使用 Google 搜索 Grounding 功能 | `true` 或 `false`，默认为 `false`。 |
| spring.ai.vertex.ai.gemini.chat.options.temperature | 控制输出的随机性。值范围为 \[0.0,1.0]（含）。接近 1.0 的值将产生更多样化的响应，而接近 0.0 的值通常会导致生成式模型产生不那么令人惊讶的响应。 | 0.7 |
| spring.ai.vertex.ai.gemini.chat.options.top-k | 采样时要考虑的最大标记数。生成式模型使用组合的 Top-k 和核采样。Top-k 采样考虑 topK 个最可能标记的集合。 | - |
| spring.ai.vertex.ai.gemini.chat.options.top-p | 采样时要考虑的最大累积概率标记。生成式模型使用组合的 Top-k 和核采样。核采样考虑概率总和至少为 topP 的最小标记集。 | - |
| spring.ai.vertex.ai.gemini.chat.options.candidate-count | 要返回的生成响应消息的数量。此值必须介于 \[1, 8]（含）之间。默认为 1。 | 1 |
| spring.ai.vertex.ai.gemini.chat.options.max-output-tokens | 要生成的最大标记数。 | - |
| spring.ai.vertex.ai.gemini.chat.options.tool-names | 在单个提示请求中启用函数调用的工具列表（按其名称标识）。具有这些名称的工具必须存在于 ToolCallback 注册表中。 | - |
| spring.ai.vertex.ai.gemini.chat.options.functions | （已由 `tool-names` 弃用）在单个提示请求中启用函数调用的函数列表（按其名称标识）。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
| spring.ai.vertex.ai.gemini.chat.options.internal-tool-execution-enabled | 如果为 true，则应执行工具，否则模型中的响应将返回给用户。默认为 null，但如果为 null，则会考虑 `ToolCallingChatOptions.DEFAULT_TOOL_EXECUTION_ENABLED`（即 true） | - |
| spring.ai.vertex.ai.gemini.chat.options.proxy-tool-calls | （已由 `internal-tool-execution-enabled` 弃用）如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。 | false |
| spring.ai.vertex.ai.gemini.chat.options.safety-settings | 用于控制安全过滤器的安全设置列表，由 [Vertex AI 安全过滤器](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/configure-safety-filters)定义。每个安全设置都可以有一个方法、阈值和类别。 | - |
所有以 `spring.ai.vertex.ai.gemini.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的运行时选项来覆盖。
## 运行时选项
[VertexAiGeminiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatOptions.java) 提供模型配置，例如温度、topK 等。
在启动时，可以使用 `VertexAiGeminiChatModel(api, options)` 构造函数或 `spring.ai.vertex.ai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
VertexAiGeminiChatOptions.builder()
.temperature(0.4)
.build()
));
```
除了特定于模型的 `VertexAiGeminiChatOptions`之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/prompt/DefaultChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/prompt/ChatOptions.java) 实例。
## 工具调用
Vertex AI Gemini 模型支持工具调用（在 Google Gemini 上下文中，称为 `function calling`）功能，允许模型在对话期间使用工具。
以下是如何定义和使用基于 `@Tool` 的工具的示例：
```java theme={"system"}
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 作为工具：
```java theme={"system"}
@Bean
@Description("获取某个位置的天气。以 36°F 或 36°C 格式返回温度。")
public Function weatherFunction() {
return new MockWeatherService();
}
String response = ChatClient.create(this.chatModel)
.prompt("波士顿的天气怎么样？")
.tools("weatherFunction")
.inputType(Request.class)
.call()
.content();
```
在[工具](/spring4ai/api/tools)文档中查找更多信息。
## 多模态
多模态是指模型同时理解和处理来自各种（输入）来源（包括 `文本`、`pdf`、`图像`、`音频` 和其他数据格式）信息的能力。
### 图像、音频、视频
Google 的 Gemini AI 模型通过理解和集成文本、代码、音频、图像和视频来支持此功能。
有关更多详细信息，请参阅博文 [Introducing Gemini](https://blog.google/technology/ai/google-gemini-ai/#introducing-gemini)。
Spring AI 的 `Message` 接口通过引入 Media 类型来支持多模态 AI 模型。
此类型包含有关消息中媒体附件的数据和信息，使用 Spring 的 `org.springframework.util.MimeType` 和 `java.lang.Object` 来获取原始媒体数据。
以下是从 [VertexAiGeminiChatModelIT#multiModalityTest()](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-vertex-ai-gemini/src/test/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModelIT.java) 中提取的简单代码示例，演示了用户文本与图像的组合：
```java theme={"system"}
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)));
```
### PDF
最新的 Vertex Gemini 支持 PDF 输入类型。
使用 `application/pdf` 媒体类型将 PDF 文件附加到消息：
```java theme={"system"}
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)));
```
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-vertex-ai-gemini` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 VertexAi 聊天模型：
```properties theme={"system"}
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` 等...
每个模型都有其自己的一组支持区域，你可以在模型页面中找到支持区域的列表。
例如，模型=`gemini-2.5-flash` 目前仅在 `us-central1` 区域可用，你必须将 location 设置为 `us-central1`，
遵循模型页面 [Gemini 2.5 Flash - 支持的区域](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash)。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 智谱 AI 聊天
Source: https://javaai.pig4cloud.com/spring-ai/api/chat/zhipuai-chat
Spring AI 支持智谱 AI 提供的各种 AI 语言模型。你可以与智谱 AI 语言模型进行交互，并基于智谱 AI 模型创建多语言会话助手。
## 前提条件
你需要使用智谱 AI 创建一个 API 才能访问智谱 AI 语言模型。
在[智谱 AI 注册页面](https://open.bigmodel.cn/login)创建一个帐户，并在[API 密钥页面](https://open.bigmodel.cn/usercenter/apikeys)生成令牌。
Spring AI 项目定义了一个名为 `spring.ai.zhipuai.api-key` 的配置属性，你应该将其设置为从 API 密钥页面获取的 `API 密钥` 的值。
你可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.zhipuai.api-key=<你的智谱AI API密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，你可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
zhipuai:
api-key: ${ZHIPUAI_API_KEY}
```
```bash theme={"system"}
# 在你的环境或 .env 文件中
export ZHIPUAI_API_KEY=<你的智谱AI API密钥>
```
你也可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("ZHIPUAI_API_KEY");
```
### 添加仓库和 BOM
Spring AI 的构件发布在 Maven Central 和 Spring Snapshot 仓库中。
请参阅[构件仓库](/getting-started#artifact-repositories)部分，将这些仓库添加到你的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (bill of materials)，以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建系统中。
## 自动配置
:::note
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
:::
Spring AI 为智谱 AI 聊天客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-zhipuai
```
或添加到你的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-zhipuai'
}
```
:::tip
请参阅[依赖管理](/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
:::
### 聊天属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，允许你配置智谱 AI 聊天模型的重试机制。
| 属性 | 描述 | 默认值 |
| ---------------------------------------- | -------------------------------------------------------------- | ----- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）。 | 空 |
#### 连接属性
前缀 `spring.ai.zhiPu` 用作属性前缀，允许你连接到智谱 AI。
| 属性 | 描述 | 默认值 |
| -------------------------- | -------- | ---------------------------------------------------------------------- |
| spring.ai.zhipuai.base-url | 要连接的 URL | [https://open.bigmodel.cn/api/paas](https://open.bigmodel.cn/api/paas) |
| spring.ai.zhipuai.api-key | API 密钥 | - |
#### 配置属性
:::note
聊天自动配置的启用和禁用现在通过前缀为 `spring.ai.model.chat` 的顶级属性进行配置。
要启用，spring.ai.model.chat=zhipuai (默认启用)
要禁用，spring.ai.model.chat=none (或任何与 zhipuai 不匹配的值)
此更改是为了允许配置多个模型。
:::
前缀 `spring.ai.zhipuai.chat` 是属性前缀，允许你配置智谱 AI 的聊天模型实现。
| 属性 | 描述 | 默认值 |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| spring.ai.zhipuai.chat.enabled (已移除且不再有效) | 启用智谱 AI 聊天模型。 | true |
| spring.ai.model.chat | 启用智谱 AI 聊天模型。 | zhipuai |
| spring.ai.zhipuai.chat.base-url | 可选地覆盖 spring.ai.zhipuai.base-url 以提供特定于聊天的 url | [https://open.bigmodel.cn/api/paas](https://open.bigmodel.cn/api/paas) |
| spring.ai.zhipuai.chat.api-key | 可选地覆盖 spring.ai.zhipuai.api-key 以提供特定于聊天的 api-key | - |
| spring.ai.zhipuai.chat.options.model | 这是要使用的智谱 AI 聊天模型 | `GLM-3-Turbo` (`GLM-3-Turbo`、`GLM-4`、`GLM-4-Air`、`GLM-4-AirX`、`GLM-4-Flash` 和 `GLM-4V` 指向最新的模型版本) |
| spring.ai.zhipuai.chat.options.maxTokens | 在聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。 | - |
| spring.ai.zhipuai.chat.options.temperature | 使用的采样温度，介于 0 和 1 之间。较高的值（如 0.8）会使输出更随机，而较低的值（如 0.2）会使其更集中和确定。我们通常建议更改此项或 top\_p，但不能同时更改两者。 | 0.7 |
| spring.ai.zhipuai.chat.options.topP | 温度采样的替代方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记的结果。因此 0.1 表示仅考虑构成前 10% 概率质量的标记。我们通常建议更改此项或温度，但不能同时更改两者。 | 1.0 |
| spring.ai.zhipuai.chat.options.stop | 模型将停止生成由 stop 指定的字符，目前仅支持 \["stop\_word1"] 格式的单个停止词 | - |
| spring.ai.zhipuai.chat.options.user | 代表你的最终用户的唯一标识符，可以帮助智谱 AI 监控和检测滥用行为。 | - |
| spring.ai.zhipuai.chat.options.requestId | 该参数由客户端传递，并且必须确保唯一性。它用于区分每个请求的唯一标识符。如果客户端未提供，平台将默认生成它。 | - |
| spring.ai.zhipuai.chat.options.doSample | 当 do\_sample 设置为 true 时，启用采样策略。如果 do\_sample 为 false，则采样策略参数 temperature 和 top\_p 将不会生效。 | true |
| spring.ai.zhipuai.chat.options.proxy-tool-calls | 如果为 true，Spring AI 将不会在内部处理函数调用，而是将它们代理到客户端。然后由客户端负责处理函数调用，将它们分派到适当的函数，并返回结果。如果为 false（默认值），Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
:::note
你可以为 `ChatModel` 实现覆盖通用的 `spring.ai.zhipuai.base-url` 和 `spring.ai.zhipuai.api-key`。
如果设置了 `spring.ai.zhipuai.chat.base-url` 和 `spring.ai.zhipuai.chat.api-key` 属性，则它们优先于通用属性。
如果你想为不同的模型和不同的模型端点使用不同的智谱 AI 帐户，这将非常有用。
:::
:::tip
所有以 `spring.ai.zhipuai.chat.options` 为前缀的属性都可以在运行时通过向 `Prompt` 调用添加特定于请求的[聊天选项](#runtime-options)来覆盖。
:::
## 运行时选项
[ZhiPuAiChatOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/ZhiPuAiChatOptions.java) 提供模型配置，例如要使用的模型、温度、频率惩罚等。
在启动时，可以使用 `ZhiPuAiChatModel(api, options)` 构造函数或 `spring.ai.zhipuai.chat.options.*` 属性配置默认选项。
在运行时，你可以通过向 `Prompt` 调用添加新的、特定于请求的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
```java theme={"system"}
ChatResponse response = chatModel.call(
new Prompt(
"生成 5 个著名海盗的名字。",
ZhiPuAiChatOptions.builder()
.model(ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue())
.temperature(0.5)
.build()
));
```
:::tip
除了特定于模型的 [ZhiPuAiChatOptions](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/ZhiPuAiChatOptions.java)之外，你还可以使用通过 [ChatOptionsBuilder#builder()](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/ChatOptionsBuilder.java) 创建的可移植 [ChatOptions](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/ChatOptions.java) 实例。
:::
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-zhipuai` 添加到你的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置智谱 AI 聊天模型：
```properties theme={"system"}
spring.ai.zhipuai.api-key=你的API密钥
spring.ai.zhipuai.chat.options.model=glm-4-air
spring.ai.zhipuai.chat.options.temperature=0.7
```
:::tip
将 `api-key` 替换为你的智谱 AI 凭据。
:::
这将创建一个 `ZhiPuAiChatModel` 实现，你可以将其注入到你的类中。
以下是一个简单的 `@Controller` 类的示例，该类使用聊天模型进行文本生成。
```java theme={"system"}
@RestController
public class ChatController {
private final ZhiPuAiChatModel chatModel;
@Autowired
public ChatController(ZhiPuAiChatModel 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 generateStream(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
var prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
```
## 手动配置
[ZhiPuAiChatModel.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/ZhiPuAiChatModel.java) 实现了 `ChatModel` 和 `StreamingChatModel`，并使用[低级 API](#low-level-api)连接到智谱 AI 服务。
将 `spring-ai-zhipuai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-zhipuai
```
或添加到你的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-zhipuai'
}
```
:::tip
请参阅[依赖管理](/getting-started#dependency-management)部分，将 Spring AI BOM 添加到你的构建文件中。
:::
接下来，创建一个 `ZhiPuAiChatModel` 并将其用于文本生成：
```java theme={"system"}
var zhiPuAiApi = new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));
var chatModel = new ZhiPuAiChatModel(this.zhiPuAiApi, ZhiPuAiChatOptions.builder()
.model(ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue())
.temperature(0.4)
.maxTokens(200)
.build());
ChatResponse response = this.chatModel.call(
new Prompt("生成 5 个著名海盗的名字。"));
// 或使用流式响应
Flux streamResponse = this.chatModel.stream(
new Prompt("生成 5 个著名海盗的名字。"));
```
`ZhiPuAiChatOptions` 为聊天请求提供配置信息。
`ZhiPuAiChatOptions.Builder` 是流畅的选项构建器。
### 低级智谱 AI API 客户端
[ZhiPuAiApi.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/api/ZhiPuAiApi.java) 提供了轻量级的 Java 客户端，用于[智谱 AI API](https://open.bigmodel.cn/dev/api)。
以下是一个简单的代码片段，展示了如何以编程方式使用 API：
```java theme={"system"}
ZhiPuAiApi zhiPuAiApi =
new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("你好世界", Role.USER);
// 同步请求
ResponseEntity response = this.zhiPuAiApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue(), 0.7, false));
// 流式请求
Flux streamResponse = this.zhiPuAiApi.chatCompletionStream(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_3_Turbo.getValue(), 0.7, true));
```
有关更多信息，请参阅 [ZhiPuAiApi.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/api/ZhiPuAiApi.java) 的 JavaDoc。
#### 智谱 AI API 示例
* [ZhiPuAiApiIT.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/test/java/org/springframework/ai/zhipuai/api/ZhiPuAiApiIT.java) 测试提供了一些有关如何使用轻量级库的常规示例。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 聊天客户端 API
Source: https://javaai.pig4cloud.com/spring-ai/api/chatclient
`ChatClient` 提供了一个流畅的 API 用于与 AI 模型进行通信。
它同时支持同步和流式编程模型。
请参阅本文档底部的[实现说明](#implementation-notes)，了解 `ChatClient` 中命令式和响应式编程模型结合使用的相关信息。
流畅的 API 提供了构建 [Prompt](/spring4ai/api/prompt) 各个组成部分的方法，这些部分作为输入传递给 AI 模型。
`Prompt` 包含指导 AI 模型输出和行为的指令文本。从 API 的角度来看，提示由消息集合组成。
AI 模型处理两种主要类型的消息：用户消息（来自用户的直接输入）和系统消息（由系统生成以指导对话）。
这些消息通常包含占位符，这些占位符在运行时根据用户输入进行替换，以根据用户输入自定义 AI 模型的响应。
还有一些可以指定的提示选项，例如要使用的 AI 模型的名称和控制生成输出随机性或创造性的温度设置。
## 创建 ChatClient
`ChatClient` 使用 `ChatClient.Builder` 对象创建。
您可以为任何 [ChatModel](/spring4ai/api/chatmodel) Spring Boot 自动配置获取自动配置的 `ChatClient.Builder` 实例，或以编程方式创建一个。
### 使用自动配置的 ChatClient.Builder
在最简单的用例中，Spring AI 提供 Spring Boot 自动配置，为您创建一个原型 `ChatClient.Builder` bean，您可以将其注入到您的类中。
以下是一个简单的示例，展示如何获取简单用户请求的 `String` 响应：
```java theme={"system"}
@RestController
class MyController {
private final ChatClient chatClient;
public MyController(ChatClient.Builder chatClientBuilder) {
this.chatClient = chatClientBuilder.build();
}
@GetMapping("/ai")
String generation(String userInput) {
return this.chatClient.prompt()
.user(userInput)
.call()
.content();
}
}
```
在这个简单的示例中，用户输入设置了用户消息的内容。
`call()` 方法向 AI 模型发送请求，`content()` 方法将 AI 模型的响应作为 `String` 返回。
### 使用多个聊天模型
在单个应用程序中使用多个聊天模型有几种场景：
* 为不同类型的任务使用不同的模型（例如，使用强大的模型进行复杂推理，使用更快、更便宜的模型进行简单任务）
* 当一个模型服务不可用时实现回退机制
* 对不同的模型或配置进行 A/B 测试
* 根据用户偏好提供模型选择
* 组合专业模型（一个用于代码生成，另一个用于创意内容等）
默认情况下，Spring AI 自动配置单个 `ChatClient.Builder` bean。但是，您可能需要在应用程序中使用多个聊天模型。以下是处理这种情况的方法：
在所有情况下，您都需要通过设置属性 `spring.ai.chat.client.enabled=false` 来禁用 `ChatClient.Builder` 自动配置。
这允许您手动创建多个 `ChatClient` 实例。
#### 使用单个模型类型的多个 ChatClient
本节介绍一个常见用例，您需要创建多个使用相同底层模型类型但具有不同配置的 ChatClient 实例。
```java theme={"system"}
// 以编程方式创建 ChatClient 实例
ChatModel myChatModel = ... // 已由 Spring Boot 自动配置
ChatClient chatClient = ChatClient.create(myChatModel);
// 或使用构建器以获得更多控制
ChatClient.Builder builder = ChatClient.builder(myChatModel);
ChatClient customChatClient = builder
.defaultSystemPrompt("你是一个乐于助人的助手。")
.build();
```
#### 不同模型类型的 ChatClient
当使用多个 AI 模型时，您可以为每个模型定义单独的 `ChatClient` bean：
```java theme={"system"}
import org.springframework.ai.chat.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class ChatClientConfig {
@Bean
public ChatClient openAiChatClient(OpenAiChatModel chatModel) {
return ChatClient.create(chatModel);
}
@Bean
public ChatClient anthropicChatClient(AnthropicChatModel chatModel) {
return ChatClient.create(chatModel);
}
}
```
然后，您可以使用 `@Qualifier` 注解将这些 bean 注入到应用程序组件中：
```java theme={"system"}
@Configuration
public class ChatClientExample {
@Bean
CommandLineRunner cli(
@Qualifier("openAiChatClient") ChatClient openAiChatClient,
@Qualifier("anthropicChatClient") ChatClient anthropicChatClient) {
return args -> {
var scanner = new Scanner(System.in);
ChatClient chat;
// 模型选择
System.out.println("\n选择您的 AI 模型：");
System.out.println("1. OpenAI");
System.out.println("2. Anthropic");
System.out.print("输入您的选择（1 或 2）：");
String choice = scanner.nextLine().trim();
if (choice.equals("1")) {
chat = openAiChatClient;
System.out.println("使用 OpenAI 模型");
} else {
chat = anthropicChatClient;
System.out.println("使用 Anthropic 模型");
}
// 使用选定的聊天客户端
System.out.print("\n输入您的问题：");
String input = scanner.nextLine();
String response = chat.prompt(input).call().content();
System.out.println("助手：" + response);
scanner.close();
};
}
}
```
#### 多个 OpenAI 兼容的 API 端点
`OpenAiApi` 和 `OpenAiChatModel` 类提供了 `mutate()` 方法，允许您创建具有不同属性的现有实例的变体。这在需要处理多个 OpenAI 兼容 API 时特别有用。
```java theme={"system"}
@Service
public class MultiModelService {
private static final Logger logger = LoggerFactory.getLogger(MultiModelService.class);
@Autowired
private OpenAiChatModel baseChatModel;
@Autowired
private OpenAiApi baseOpenAiApi;
public void multiClientFlow() {
try {
// 为 Groq (Llama3) 派生新的 OpenAiApi
OpenAiApi groqApi = baseOpenAiApi.mutate()
.baseUrl("https://api.groq.com/openai")
.apiKey(System.getenv("GROQ_API_KEY"))
.build();
// 为 OpenAI GPT-4 派生新的 OpenAiApi
OpenAiApi gpt4Api = baseOpenAiApi.mutate()
.baseUrl("https://api.openai.com")
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
// 为 Groq 派生新的 OpenAiChatModel
OpenAiChatModel groqModel = baseChatModel.mutate()
.openAiApi(groqApi)
.defaultOptions(OpenAiChatOptions.builder().model("llama3-70b-8192").temperature(0.5).build())
.build();
// 为 GPT-4 派生新的 OpenAiChatModel
OpenAiChatModel gpt4Model = baseChatModel.mutate()
.openAiApi(gpt4Api)
.defaultOptions(OpenAiChatOptions.builder().model("gpt-4").temperature(0.7).build())
.build();
// 两个模型的简单提示
String prompt = "法国的首都是什么？";
String groqResponse = ChatClient.builder(groqModel).build().prompt(prompt).call().content();
String gpt4Response = ChatClient.builder(gpt4Model).build().prompt(prompt).call().content();
logger.info("Groq (Llama3) 响应：{}", groqResponse);
logger.info("OpenAI GPT-4 响应：{}", gpt4Response);
}
catch (Exception e) {
logger.error("多客户端流程中的错误", e);
}
}
}
```
## ChatClient 流畅 API
`ChatClient` 流畅 API 允许您使用重载的 `prompt` 方法以三种不同的方式创建提示：
这个无参数方法让您开始使用流畅 API，允许您构建用户、系统和其他提示部分。
这个方法接受 `Prompt` 参数，让您传入使用 Prompt 的非流畅 API 创建的 `Prompt` 实例。
这是一个类似于前一个重载的便捷方法。它接受用户的文本内容。
## ChatClient 响应
`ChatClient` API 提供了几种使用流畅 API 格式化 AI 模型响应的方法。
### 返回 ChatResponse
AI 模型的响应是一个由 [ChatResponse](/spring4ai/api/chatmodel#chatresponse) 类型定义的丰富结构。
它包括有关如何生成响应的元数据，还可以包含多个响应，称为 [Generation](/spring4ai/api/chatmodel#generation)s，每个都有自己的元数据。
元数据包括用于创建响应的令牌数量（每个令牌大约是一个单词的 3/4）。
这些信息很重要，因为托管 AI 模型根据每个请求使用的令牌数量收费。
下面通过调用 `call()` 方法后的 `chatResponse()` 方法展示了返回包含元数据的 `ChatResponse` 对象的示例：
```java theme={"system"}
ChatResponse chatResponse = chatClient.prompt()
.user("给我讲个笑话")
.call()
.chatResponse();
```
### 返回实体
您通常希望返回一个从返回的 `String` 映射的实体类。
`entity()` 方法提供了这个功能。
例如，给定 Java 记录：
```java theme={"system"}
record ActorFilms(String actor, List movies) {}
```
您可以使用 `entity()` 方法轻松地将 AI 模型的输出映射到这个记录，如下所示：
```java theme={"system"}
ActorFilms actorFilms = chatClient.prompt()
.user("生成一个随机演员的电影作品。")
.call()
.entity(ActorFilms.class);
```
还有一个重载的 `entity` 方法，签名为 `entity(ParameterizedTypeReference type)`，允许您指定泛型列表等类型：
```java theme={"system"}
List actorFilms = chatClient.prompt()
.user("生成汤姆·汉克斯和比尔·默瑞的 5 部电影作品。")
.call()
.entity(new ParameterizedTypeReference>() {});
```
### 流式响应
`stream()` 方法让您获得异步响应，如下所示：
```java theme={"system"}
Flux output = chatClient.prompt()
.user("给我讲个笑话")
.stream()
.content();
```
您还可以使用方法 `Flux chatResponse()` 流式传输 `ChatResponse`。
在未来，我们将提供一个便捷方法，让您使用响应式 `stream()` 方法返回 Java 实体。
同时，您应该使用 [结构化输出转换器](/spring4ai/api/structured-output-converter#structuredoutputconverter) 显式转换聚合响应，如下所示。
这也演示了流畅 API 中参数的使用，这将在文档的后面部分详细讨论。
```java theme={"system"}
var converter = new BeanOutputConverter<>(new ParameterizedTypeReference>() {});
Flux flux = this.chatClient.prompt()
.user(u -> u.text("""
生成一个随机演员的电影作品。
{format}
""")
.param("format", this.converter.getFormat()))
.stream()
.content();
String content = this.flux.collectList().block().stream().collect(Collectors.joining());
List actorFilms = this.converter.convert(this.content);
```
## 提示模板
`ChatClient` 流畅 API 允许您提供带有变量的用户和系统文本作为模板，这些变量在运行时被替换。
```java theme={"system"}
String answer = ChatClient.create(chatModel).prompt()
.user(u -> u
.text("告诉我 5 部由 {composer} 作曲的电影原声带")
.param("composer", "John Williams"))
.call()
.content();
```
在内部，ChatClient 使用 `PromptTemplate` 类来处理用户和系统文本，并使用给定的 `TemplateRenderer` 实现替换变量。
默认情况下，Spring AI 使用 `StTemplateRenderer` 实现，它基于 Terence Parr 开发的开源 [StringTemplate](https://www.stringtemplate.org/) 引擎。
Spring AI 还为不需要模板处理的情况提供了 `NoOpTemplateRenderer`。
直接在 `ChatClient` 上配置的 `TemplateRenderer`（通过 `.templateRenderer()`）仅适用于直接在 `ChatClient` 构建器链中定义的提示内容（例如，通过 `.user()`、`.system()`）。
它不会影响 [Advisors](/spring4ai/api/retrieval-augmented-generation#_questionansweradvisor) 内部使用的模板，如 `QuestionAnswerAdvisor`，它们有自己的模板自定义机制（参见[自定义 Advisor 模板](/spring4ai/api/retrieval-augmented-generation#_custom_template)）。
如果您想使用不同的模板引擎，您可以直接向 ChatClient 提供 `TemplateRenderer` 接口的自定义实现。您也可以继续使用默认的 `StTemplateRenderer`，但使用自定义配置。
例如，默认情况下，模板变量由 `{}` 语法标识。如果您计划在提示中包含 JSON，您可能想使用不同的语法以避免与 JSON 语法冲突。例如，您可以使用 `<` 和 `>` 分隔符。
```java theme={"system"}
String answer = ChatClient.create(chatModel).prompt()
.user(u -> u
.text("告诉我 5 部由 作曲的电影原声带")
.param("composer", "John Williams"))
.templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
.call()
.content();
```
## call() 返回值
在 `ChatClient` 上指定 `call()` 方法后，响应类型有几种不同的选项：
返回响应的 String 内容
返回包含多个生成以及有关响应的元数据的 `ChatResponse` 对象，例如用于创建响应的令牌数量
返回一个 `ChatClientResponse` 对象，其中包含 `ChatResponse` 对象和 ChatClient 执行上下文，让您可以访问在执行 advisors 期间使用的其他数据（例如，在 RAG 流程中检索的相关文档）
使用以下方法之一返回 Java 类型：
- `entity(ParameterizedTypeReference type)`：用于返回实体类型的 `Collection`
- `entity(Class type)`：用于返回特定的实体类型
- `entity(StructuredOutputConverter structuredOutputConverter)`：用于指定 `StructuredOutputConverter` 的实例，将 `String` 转换为实体类型
您也可以调用 `stream()` 方法而不是 `call()`。
## stream() 返回值
在 `ChatClient` 上指定 `stream()` 方法后，响应类型有几种选项：
返回 AI 模型生成的字符串的 `Flux`
返回 `Flux` 对象，其中包含有关响应的其他元数据
返回 `Flux` 对象，其中包含 `ChatResponse` 对象和 ChatClient 执行上下文，让您可以访问在执行 advisors 期间使用的其他数据（例如，在 RAG 流程中检索的相关文档）
## 使用默认值
在 `@Configuration` 类中创建带有默认系统文本的 `ChatClient` 可以简化运行时代码。
通过设置默认值，您只需要在调用 `ChatClient` 时指定用户文本，无需在运行时代码路径中为每个请求设置系统文本。
### 默认系统文本
在以下示例中，我们将配置系统文本始终以海盗的声音回复。
为了避免在运行时代码中重复系统文本，我们将在 `@Configuration` 类中创建一个 `ChatClient` 实例。
```java theme={"system"}
@Configuration
class Config {
@Bean
ChatClient chatClient(ChatClient.Builder builder) {
return builder.defaultSystem("你是一个友好的聊天机器人，用海盗的声音回答问题")
.build();
}
}
```
以及一个调用它的 `@RestController`：
```java theme={"system"}
@RestController
class AIController {
private final ChatClient chatClient;
AIController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai/simple")
public Map completion(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
return Map.of("completion", this.chatClient.prompt().user(message).call().content());
}
}
```
当通过 curl 调用应用程序端点时，结果是：
```bash theme={"system"}
❯ curl localhost:8080/ai/simple
{"completion":"为什么海盗去喜剧俱乐部？为了听一些 arrr-rated 笑话！啊，伙计！"}
```
### 带参数的默认系统文本
在以下示例中，我们将在系统文本中使用占位符，以便在运行时而不是设计时指定完成的声音。
```java theme={"system"}
@Configuration
class Config {
@Bean
ChatClient chatClient(ChatClient.Builder builder) {
return builder.defaultSystem("你是一个友好的聊天机器人，用 {voice} 的声音回答问题")
.build();
}
}
```
```java theme={"system"}
@RestController
class AIController {
private final ChatClient chatClient;
AIController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai")
Map completion(@RequestParam(value = "message", defaultValue = "给我讲个笑话") String message, String voice) {
return Map.of("completion",
this.chatClient.prompt()
.system(sp -> sp.param("voice", voice))
.user(message)
.call()
.content());
}
}
```
当通过 httpie 调用应用程序端点时，结果是：
```bash theme={"system"}
http localhost:8080/ai voice=='Robert DeNiro'
{
"completion": "你在跟我说话吗？好吧，给你讲个笑话：为什么自行车不能自己站起来？因为它太累了！经典，对吧？"
}
```
### 其他默认值
在 `ChatClient.Builder` 级别，您可以指定默认提示配置。
传入 `ChatOptions` 类中定义的便携选项或特定于模型的选项，如 `OpenAiChatOptions` 中的选项。有关特定于模型的 `ChatOptions` 实现的更多信息，请参阅 JavaDocs。
`name` 用于在用户文本中引用函数。`description` 解释函数的用途，帮助 AI 模型选择正确的函数以获得准确的响应。`function` 参数是模型在需要时将执行的 Java 函数实例。
应用程序上下文中定义的 `java.util.Function` 的 bean 名称。
这些方法让您定义用户文本：
- `defaultUser(String text)`
- `defaultUser(Resource text)`
- `defaultUser(Consumer userSpecConsumer)`：`Consumer` 允许您使用 lambda 来指定用户文本和任何默认参数。
Advisors 允许修改用于创建 `Prompt` 的数据。`QuestionAnswerAdvisor` 实现通过附加与用户文本相关的上下文信息来启用 `Retrieval Augmented Generation` 模式。
此方法允许您定义一个 `Consumer` 来使用 `AdvisorSpec` 配置多个 advisors。Advisors 可以修改用于创建最终 `Prompt` 的数据。`Consumer` 让您指定一个 lambda 来添加 advisors，如 `QuestionAnswerAdvisor`，它通过附加与用户文本相关的相关上下文信息来支持 `Retrieval Augmented Generation`。
您可以使用不带 `default` 前缀的相应方法在运行时覆盖这些默认值。
覆盖默认选项
覆盖默认函数
覆盖默认函数
覆盖默认用户
覆盖默认 advisors
使用 consumer 覆盖默认 advisors
## Advisors
[Advisors API](/spring4ai/api/advisors) 提供了一种灵活而强大的方式来拦截、修改和增强 Spring 应用程序中的 AI 驱动交互。
在调用带有用户文本的 AI 模型时，一个常见的模式是附加或增强带有上下文数据的提示。
这种上下文数据可以是不同类型。常见类型包括：
这是 AI 模型尚未训练过的数据。即使模型见过类似的数据，附加的上下文数据在生成响应时也会优先考虑。
聊天模型的 API 是无状态的。如果您告诉 AI 模型您的名字，它不会在后续交互中记住它。必须随每个请求发送对话历史，以确保在生成响应时考虑先前的交互。
### ChatClient 中的 Advisor 配置
ChatClient 流畅 API 提供了 `AdvisorSpec` 接口用于配置 advisors。这个接口提供了添加参数、一次设置多个参数以及向链中添加一个或多个 advisors 的方法。
```java theme={"system"}
interface AdvisorSpec {
AdvisorSpec param(String k, Object v);
AdvisorSpec params(Map p);
AdvisorSpec advisors(Advisor... advisors);
AdvisorSpec advisors(List advisors);
}
```
advisors 添加到链中的顺序至关重要，因为它决定了它们的执行顺序。每个 advisor 都以某种方式修改提示或上下文，一个 advisor 所做的更改会传递给链中的下一个。
```java theme={"system"}
ChatClient.builder(chatModel)
.build()
.prompt()
.advisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
QuestionAnswerAdvisor.builder(vectorStore).build()
)
.user(userText)
.call()
.content();
```
在此配置中，`MessageChatMemoryAdvisor` 将首先执行，将对话历史添加到提示中。然后，`QuestionAnswerAdvisor` 将基于用户的问题和添加的对话历史执行其搜索，可能会提供更相关的结果。
[了解 Question Answer Advisor](/spring4ai/api/retrieval-augmented-generation#_questionansweradvisor)
### 检索增强生成
请参阅[检索增强生成](/spring4ai/api/retrieval-augmented-generation)指南。
### 日志记录
`SimpleLoggerAdvisor` 是一个记录 `ChatClient` 的 `request` 和 `response` 数据的 advisor。
这对于调试和监控您的 AI 交互很有用。
Spring AI 支持 LLM 和向量存储交互的可观察性。有关更多信息，请参阅[可观察性](/spring4ai/observability)指南。
要启用日志记录，在创建 ChatClient 时将 `SimpleLoggerAdvisor` 添加到 advisor 链中。
建议将其添加到链的末尾：
```java theme={"system"}
ChatResponse response = ChatClient.create(chatModel).prompt()
.advisors(new SimpleLoggerAdvisor())
.user("给我讲个笑话？")
.call()
.chatResponse();
```
要查看日志，将 advisor 包的日志级别设置为 `DEBUG`：
```
logging.level.org.springframework.ai.chat.client.advisor=DEBUG
```
将此添加到您的 `application.properties` 或 `application.yaml` 文件中。
您可以通过使用以下构造函数自定义从 `AdvisedRequest` 和 `ChatResponse` 记录的哪些数据：
```java theme={"system"}
SimpleLoggerAdvisor(
Function requestToString,
Function responseToString
)
```
使用示例：
```java theme={"system"}
SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
request -> "自定义请求：" + request.userText,
response -> "自定义响应：" + response.getResult()
);
```
这允许您根据特定需求定制记录的信息。
在生产环境中记录敏感信息时要小心。
## 聊天内存
`ChatMemory` 接口表示聊天对话内存的存储。它提供了向对话添加消息、从对话中检索消息以及清除对话历史的方法。
目前有一个内置实现：`MessageWindowChatMemory`。
`MessageWindowChatMemory` 是一个聊天内存实现，它维护一个最多指定最大大小（默认：20 条消息）的消息窗口。当消息数量超过此限制时，较旧的消息会被逐出，但系统消息会被保留。如果添加了新的系统消息，所有先前的系统消息都会从内存中删除。这确保了对话始终可以使用最新的上下文，同时保持内存使用有界。
`MessageWindowChatMemory` 由 `ChatMemoryRepository` 抽象支持，它提供了聊天对话内存的存储实现。有几种实现可用，包括 `InMemoryChatMemoryRepository`、`JdbcChatMemoryRepository`、`CassandraChatMemoryRepository` 和 `Neo4jChatMemoryRepository`。
有关更多详细信息和用法示例，请参阅[聊天内存](/spring4ai/api/chat-memory)文档。
## 实现说明
`ChatClient` 中命令式和响应式编程模型的结合使用是 API 的一个独特方面。
通常，应用程序要么是响应式的，要么是命令式的，但不是两者都是。
在自定义 Model 实现的 HTTP 客户端交互时，必须同时配置 RestClient 和 WebClient。
由于 Spring Boot 3.4 中的一个错误，必须设置 "spring.http.client.factory=jdk" 属性。否则，它默认设置为 "reactor"，这会破坏某些 AI 工作流，如 ImageModel。
* 流式处理仅通过响应式堆栈支持。命令式应用程序必须包含响应式堆栈（例如 spring-boot-starter-webflux）。
* 非流式处理仅通过 Servlet 堆栈支持。响应式应用程序必须包含 Servlet 堆栈（例如 spring-boot-starter-web），并期望某些调用是阻塞的。
工具调用是命令式的，导致阻塞工作流。这也导致部分/中断的 Micrometer 观察（例如，ChatClient spans 和工具调用 spans 没有连接，第一个因此保持不完整）。
内置的 advisors 对标准调用执行阻塞操作，对流式调用执行非阻塞操作。用于 advisor 流式调用的 Reactor Scheduler 可以通过每个 Advisor 类上的 Builder 进行配置。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 聊天模型 API
Source: https://javaai.pig4cloud.com/spring-ai/api/chatmodel
聊天模型 API 为开发者提供了将 AI 驱动的聊天完成功能集成到其应用程序中的能力。它利用预训练的语言模型，如 GPT（生成式预训练转换器），以自然语言生成类似人类的响应。
API 通常通过向 AI 模型发送提示或部分对话来工作，然后 AI 模型根据其训练数据和对自然语言模式的理解生成完成或对话的延续。完成的响应随后返回给应用程序，应用程序可以将其呈现给用户或用于进一步处理。
`Spring AI 聊天模型 API` 旨在为与各种 [AI 模型](/spring4ai/overview/concepts#models) 交互提供一个简单且可移植的接口，允许开发者在不同模型之间切换，只需最少的代码更改。
这种设计符合 Spring 的模块化和可互换性理念。
此外，借助 `Prompt` 等配套类进行输入封装和 `ChatResponse` 进行输出处理，聊天模型 API 统一了与 AI 模型的通信。
它管理请求准备和响应解析的复杂性，提供直接和简化的 API 交互。
您可以在 [可用实现](#available-implementations) 部分找到更多关于可用实现的信息，以及在 [聊天模型比较](/spring4ai/api/chat/comparison) 部分找到详细的比较。
## API 概述
本节提供了 Spring AI 聊天模型 API 接口和相关类的指南。
### ChatModel
以下是 [ChatModel](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat//model/ChatModel.java) 接口定义：
```java theme={"system"}
public interface ChatModel extends Model {
default String call(String message) {...}
@Override
ChatResponse call(Prompt prompt);
}
```
带有 `String` 参数的 `call()` 方法简化了初始使用，避免了更复杂的 `Prompt` 和 `ChatResponse` 类的复杂性。
在实际应用程序中，更常见的是使用接受 `Prompt` 实例并返回 `ChatResponse` 的 `call()` 方法。
### StreamingChatModel
以下是 [StreamingChatModel](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/model/StreamingChatModel.java) 接口定义：
```java theme={"system"}
public interface StreamingChatModel extends StreamingModel {
default Flux stream(String message) {...}
@Override
Flux stream(Prompt prompt);
}
```
`stream()` 方法接受 `String` 或 `Prompt` 参数，类似于 `ChatModel`，但它使用响应式 Flux API 流式传输响应。
### Prompt
[Prompt](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/Prompt.java) 是一个 `ModelRequest`，它封装了 [Message](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/messages/Message.java) 对象列表和可选的模型请求选项。
以下列表显示了 `Prompt` 类的截断版本，不包括构造函数和其他实用方法：
```java theme={"system"}
public class Prompt implements ModelRequest> {
private final List messages;
private ChatOptions modelOptions;
@Override
public ChatOptions getOptions() {...}
@Override
public List getInstructions() {...}
// 构造函数和实用方法省略
}
```
#### Message
`Message` 接口封装了 `Prompt` 文本内容、元数据属性集合和称为 `MessageType` 的分类。
接口定义如下：
```java theme={"system"}
public interface Content {
String getText();
Map getMetadata();
}
public interface Message extends Content {
MessageType getMessageType();
}
```
多模态消息类型还实现了 `MediaContent` 接口，提供 `Media` 内容对象列表。
```java theme={"system"}
public interface MediaContent extends Content {
Collection getMedia();
}
```
`Message` 接口有各种实现，对应于 AI 模型可以处理的消息类别：
![]()
聊天完成端点根据对话角色区分消息类别，这些角色由 `MessageType` 有效映射。
例如，OpenAI 识别不同对话角色的消息类别，如 `system`、`user`、`function` 或 `assistant`。
虽然 `MessageType` 这个术语可能暗示特定的消息格式，但在这种情况下，它实际上指定了消息在对话中扮演的角色。
对于不使用特定角色的 AI 模型，`UserMessage` 实现作为标准类别，通常代表用户生成的查询或指令。
要了解 `Prompt` 和 `Message` 之间的实际应用和关系，特别是在这些角色或消息类别的上下文中，请参阅 [提示](/spring4ai/api/prompt) 部分中的详细说明。
#### 聊天选项
表示可以传递给 AI 模型的选项。`ChatOptions` 类是 `ModelOptions` 的子类，用于定义可以传递给 AI 模型的几个可移植选项。
`ChatOptions` 类定义如下：
```java theme={"system"}
public interface ChatOptions extends ModelOptions {
String getModel();
Float getFrequencyPenalty();
Integer getMaxTokens();
Float getPresencePenalty();
List getStopSequences();
Float getTemperature();
Integer getTopK();
Float getTopP();
ChatOptions copy();
}
```
此外，每个模型特定的 ChatModel/StreamingChatModel 实现都可以有自己的选项，可以传递给 AI 模型。例如，OpenAI 聊天完成模型有自己的选项，如 `logitBias`、`seed` 和 `user`。
这是一个强大的功能，允许开发者在启动应用程序时使用模型特定的选项，然后使用 `Prompt` 请求在运行时覆盖它们。
Spring AI 提供了一个复杂的系统来配置和使用聊天模型。
它允许在启动时设置默认配置，同时还提供了在每次请求的基础上覆盖这些设置的灵活性。
这种方法使开发者能够轻松地使用不同的 AI 模型并根据需要调整参数，所有这些都在 Spring AI 框架提供的一致接口内。
以下流程图说明了 Spring AI 如何处理聊天模型的配置和执行，结合了启动和运行时选项：
![]()
ChatModel/StreamingChatModel 使用"启动"聊天选项进行初始化。这些选项在 ChatModel 初始化期间设置，旨在提供默认配置。
对于每个请求，Prompt 可以包含运行时聊天选项：这些可以覆盖启动选项。
"合并选项"步骤结合了启动和运行时选项。如果提供了运行时选项，它们将优先于启动选项。
"转换输入"步骤将输入指令转换为本地的、模型特定的格式。
"转换输出"步骤将模型的响应转换为标准化的 `ChatResponse` 格式。
启动和运行时选项的分离允许全局配置和请求特定的调整。
### ChatResponse
`ChatResponse` 类的结构如下：
```java theme={"system"}
public class ChatResponse implements ModelResponse {
private final ChatResponseMetadata chatResponseMetadata;
private final List generations;
@Override
public ChatResponseMetadata getMetadata() {...}
@Override
public List getResults() {...}
// 其他方法省略
}
```
[ChatResponse](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/model/ChatResponse.java) 类保存 AI 模型的输出，每个 `Generation` 实例包含来自单个提示的潜在多个输出之一。
`ChatResponse` 类还携带有关 AI 模型响应的 `ChatResponseMetadata` 元数据。
### Generation
最后，[Generation](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/model/Generation.java) 类从 `ModelResult` 扩展而来，表示模型输出（助手消息）和相关元数据：
```java theme={"system"}
public class Generation implements ModelResult {
private final AssistantMessage assistantMessage;
private ChatGenerationMetadata chatGenerationMetadata;
@Override
public AssistantMessage getOutput() {...}
@Override
public ChatGenerationMetadata getMetadata() {...}
// 其他方法省略
}
```
## 可用实现
此图说明了统一的接口 `ChatModel` 和 `StreamingChatModel` 用于与来自不同提供商的各种 AI 聊天模型交互，允许轻松集成和在不同 AI 服务之间切换，同时为客户端应用程序维护一致的 API。
![]()
支持流式传输、多模态和函数调用。
支持流式传输和函数调用。
支持流式传输、多模态和函数调用。
不支持流式传输。
支持流式传输、多模态和函数调用。
各种具有不同功能的模型。
支持流式传输和函数调用。
支持流式传输和函数调用。
在 [聊天模型比较](/spring4ai/api/chat/comparison) 部分找到可用聊天模型的详细比较。
## 聊天模型 API
Spring AI 聊天模型 API 构建在 Spring AI `通用模型 API` 之上，提供聊天特定的抽象和实现。
这允许轻松集成和在不同 AI 服务之间切换，同时为客户端应用程序维护一致的 API。
以下类图说明了 Spring AI 聊天模型 API 的主要类和接口。
![]()
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# AI Docker Compose
Source: https://javaai.pig4cloud.com/spring-ai/api/docker-compose
Spring AI 开发的 Docker Compose 服务
# 开发时服务
Spring AI 为本地开发和测试提供 Docker Compose 配置。
## 概述
本节描述了可用于 Spring AI 开发的 Docker Compose 服务，包括：
* 向量数据库
* AI 模型服务器
* 测试工具
## 可用服务
### 向量数据库
* 带 pgvector 的 PostgreSQL
* Milvus
* Qdrant
* Weaviate
* Chroma
### AI 模型服务器
* Ollama
* LocalAI
* Hugging Face 推理服务器
### 测试工具
* Testcontainers 配置
* 模拟 AI 服务
## 使用方法
要使用这些服务，您可以运行：
```bash theme={"system"}
docker-compose up -d
```
这将启动本地开发所需的所有必要服务。
## 配置
每个服务都可以通过环境变量或 Docker Compose 覆盖进行配置。
## 实现
### 基本 Docker Compose 设置
```yaml theme={"system"}
version: '3.8'
services:
# 向量存储
pgvector:
image: pgvector/pgvector:latest
environment:
POSTGRES_DB: vectordb
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- "5432:5432"
# AI 模型服务器
ollama:
image: ollama/ollama:latest
ports:
- "11434:11434"
volumes:
- ollama_data:/root/.ollama
# 监控
prometheus:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
volumes:
ollama_data:
```
### 服务配置
```yaml theme={"system"}
# 向量存储配置
spring.ai.vectorstore.pgvector.url=jdbc:postgresql://localhost:5432/vectordb
spring.ai.vectorstore.pgvector.username=postgres
spring.ai.vectorstore.pgvector.password=postgres
# AI 模型配置
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.model=llama2
```
## 服务类别
### 1. 向量存储
```yaml theme={"system"}
# 带 pgvector 的 PostgreSQL
pgvector:
image: pgvector/pgvector:latest
environment:
POSTGRES_DB: vectordb
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- "5432:5432"
# Milvus
milvus:
image: milvusdb/milvus:latest
ports:
- "19530:19530"
- "9091:9091"
```
### 2. AI 模型服务器
```yaml theme={"system"}
# Ollama
ollama:
image: ollama/ollama:latest
ports:
- "11434:11434"
volumes:
- ollama_data:/root/.ollama
# LocalAI
localai:
image: localai/localai:latest
ports:
- "8080:8080"
volumes:
- ./models:/models
```
### 3. 监控服务
```yaml theme={"system"}
# Prometheus
prometheus:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
# Grafana
grafana:
image: grafana/grafana:latest
ports:
- "3000:3000"
volumes:
- grafana_data:/var/lib/grafana
```
## 配置属性
```properties theme={"system"}
spring.ai.development.services.enabled=true
spring.ai.development.services.auto-start=true
spring.ai.development.services.port-range=8000-9000
```
## 最佳实践
使用开发时服务时，请考虑以下最佳实践：
* **资源管理**：监控资源使用情况
* **数据持久化**：使用卷进行数据持久化
* **安全性**：保护开发环境
* **网络**：配置适当的网络隔离
* **文档**：记录服务配置
## 高级功能
### 自定义服务配置
```yaml theme={"system"}
# 自定义服务配置
services:
custom-service:
build:
context: ./custom-service
dockerfile: Dockerfile
environment:
CUSTOM_VAR: value
ports:
- "8080:8080"
```
### 服务健康检查
```yaml theme={"system"}
services:
pgvector:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
```
## 故障排除
常见问题和解决方案：
1. **服务启动问题**
* 检查端口冲突
* 验证资源可用性
* 查看服务日志
2. **连接问题**
* 检查网络配置
* 验证服务健康状态
* 测试连接性
3. **资源问题**
* 监控资源使用情况
* 调整资源限制
* 清理未使用的资源
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 嵌入模型 API
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings
嵌入是文本、图像或视频的数值表示，用于捕获输入之间的关系。
嵌入通过将文本、图像和视频转换为浮点数数组（称为向量）来工作。
这些向量旨在捕获文本、图像和视频的含义。
嵌入数组的长度称为向量的维度。
通过计算两段文本的向量表示之间的数值距离，应用程序可以确定用于生成嵌入向量的对象之间的相似性。
`EmbeddingModel` 接口设计用于在 AI 和机器学习中直接集成嵌入模型。
它的主要功能是将文本转换为数值向量，通常称为嵌入。
这些嵌入对于语义分析和文本分类等各种任务至关重要。
EmbeddingModel 接口的设计围绕两个主要目标：
* *可移植性*：此接口确保在各种嵌入模型之间轻松适应。
它允许开发者在不同的嵌入技术或模型之间切换，只需最少的代码更改。
这种设计符合 Spring 的模块化和可互换性理念。
* *简单性*：EmbeddingModel 简化了将文本转换为嵌入的过程。
通过提供像 `embed(String text)` 和 `embed(Document document)` 这样的直接方法，它消除了处理原始文本数据和嵌入算法的复杂性。这种设计选择使开发者，特别是 AI 新手，能够在其应用程序中使用嵌入，而无需深入了解底层机制。
## API 概述
嵌入模型 API 构建在通用 [Spring AI 模型 API](https://github.com/spring-projects/spring-ai/tree/main/spring-ai-model/src/main/java/org/springframework/ai/model) 之上，这是 Spring AI 库的一部分。
因此，EmbeddingModel 接口扩展了 `Model` 接口，该接口提供了与 AI 模型交互的标准方法集。`EmbeddingRequest` 和 `EmbeddingResponse` 类从 `ModelRequest` 和 `ModelResponse` 扩展而来，分别用于封装嵌入模型的输入和输出。
嵌入 API 又被更高级别的组件用来实现特定嵌入模型的嵌入模型，如 OpenAI、Titan、Azure OpenAI、Ollie 等。
以下图说明了嵌入 API 及其与 Spring AI 模型 API 和嵌入模型的关系：
![嵌入 API]()
### EmbeddingModel
本节提供了 `EmbeddingModel` 接口和相关类的指南。
```java theme={"system"}
public interface EmbeddingModel extends Model {
@Override
EmbeddingResponse call(EmbeddingRequest request);
/**
* 将给定文档的内容嵌入到向量中。
* @param document 要嵌入的文档。
* @return 嵌入的向量。
*/
float[] embed(Document document);
/**
* 将给定文本嵌入到向量中。
* @param text 要嵌入的文本。
* @return 嵌入的向量。
*/
default float[] embed(String text) {
Assert.notNull(text, "Text must not be null");
return this.embed(List.of(text)).iterator().next();
}
/**
* 将一批文本嵌入到向量中。
* @param texts 要嵌入的文本列表。
* @return 嵌入向量列表的列表。
*/
default List embed(List texts) {
Assert.notNull(texts, "Texts must not be null");
return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY))
.getResults()
.stream()
.map(Embedding::getOutput)
.toList();
}
/**
* 将一批文本嵌入到向量中并返回 {@link EmbeddingResponse}。
* @param texts 要嵌入的文本列表。
* @return 嵌入响应。
*/
default EmbeddingResponse embedForResponse(List texts) {
Assert.notNull(texts, "Texts must not be null");
return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY));
}
/**
* @return 嵌入向量的维度数。它是生成特定的。
*/
default int dimensions() {
return embed("Test String").size();
}
}
```
嵌入方法提供了各种将文本转换为嵌入的选项，适应单个字符串、结构化 `Document` 对象或文本批次。
提供了多个嵌入文本的快捷方法，包括 `embed(String text)` 方法，它接受单个字符串并返回相应的嵌入向量。
所有快捷方法都是围绕 `call` 方法实现的，这是调用嵌入模型的主要方法。
通常嵌入返回浮点数列表，以数值向量格式表示嵌入。
`embedForResponse` 方法提供了更全面的输出，可能包括有关嵌入的附加信息。
dimensions 方法是开发者快速确定嵌入向量大小的便捷工具，这对于理解嵌入空间和后续处理步骤很重要。
### EmbeddingRequest
`EmbeddingRequest` 是一个 `ModelRequest`，它接受文本对象列表和可选的嵌入请求选项。
以下列表显示了 EmbeddingRequest 类的截断版本，不包括构造函数和其他实用方法：
```java theme={"system"}
public class EmbeddingRequest implements ModelRequest> {
private final List inputs;
private final EmbeddingOptions options;
// 其他方法省略
}
```
### EmbeddingResponse
`EmbeddingResponse` 类的结构如下：
```java theme={"system"}
public class EmbeddingResponse implements ModelResponse {
private List embeddings;
private EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
// 其他方法省略
}
```
`EmbeddingResponse` 类保存 AI 模型的输出，每个 `Embedding` 实例包含来自单个文本输入的结果向量数据。
`EmbeddingResponse` 类还携带有关 AI 模型响应的 `EmbeddingResponseMetadata` 元数据。
### Embedding
`Embedding` 表示单个嵌入向量。
```java theme={"system"}
public class Embedding implements ModelResult {
private float[] embedding;
private Integer index;
private EmbeddingResultMetadata metadata;
// 其他方法省略
}
```
## 可用实现
内部各种 `EmbeddingModel` 实现使用不同的低级库和 API 来执行嵌入任务。以下是 `EmbeddingModel` 实现的一些可用实现：
* [Spring AI OpenAI 嵌入](/spring4ai/api/embeddings/openai-embeddings)
* [Spring AI Azure OpenAI 嵌入](/spring4ai/api/embeddings/azure-openai-embeddings)
* [Spring AI Ollama 嵌入](/spring4ai/api/embeddings/ollama-embeddings)
* [Spring AI Transformers (ONNX) 嵌入](/spring4ai/api/embeddings/onnx)
* [Spring AI PostgresML 嵌入](/spring4ai/api/embeddings/postgresml-embeddings)
* [Spring AI Bedrock Cohere 嵌入](/spring4ai/api/embeddings/bedrock-cohere-embedding)
* [Spring AI Bedrock Titan 嵌入](/spring4ai/api/embeddings/bedrock-titan-embedding)
* [Spring AI VertexAI 嵌入](/spring4ai/api/embeddings/vertexai-embeddings-text)
* [Spring AI Mistral AI 嵌入](/spring4ai/api/embeddings/mistralai-embeddings)
* [Spring AI Oracle Cloud Infrastructure GenAI 嵌入](/spring4ai/api/embeddings/oci-genai-embeddings)
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Azure OpenAI 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/azure-openai-embeddings
Azure OpenAI 扩展了 OpenAI 的功能，为各种任务提供安全的文本生成和 Embeddings 计算模型：
* 相似性嵌入擅长捕捉两个或多个文本片段之间的语义相似性。
* 文本搜索嵌入有助于衡量长文档是否与短查询相关。
* 代码搜索嵌入可用于嵌入代码片段和嵌入自然语言搜索查询。
Azure OpenAI 嵌入依赖于`余弦相似度`来计算文档和查询之间的相似度。
## 先决条件
Azure OpenAI 客户端提供三种连接选项：使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。
### Azure API 密钥和终结点
从 [Azure 门户](https://portal.azure.com)上的 Azure OpenAI 服务部分获取您的 Azure OpenAI `endpoint` 和 `api-key`。
Spring AI 定义了两个配置属性：
1. `spring.ai.azure.openai.api-key`：将其设置为从 Azure 获取的 `API Key` 的值。
2. `spring.ai.azure.openai.endpoint`：将其设置为在 Azure 中预配模型时获取的终结点 URL。
您可以在 `application.properties` 或 `application.yml` 文件中设置这些配置属性：
```properties theme={"system"}
spring.ai.azure.openai.api-key=<您的 Azure API 密钥>
spring.ai.azure.openai.endpoint=<您的 Azure 终结点 URL>
```
如果您希望对 API 密钥等敏感信息使用环境变量，可以在配置中使用 Spring 表达式语言 (SpEL)：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
azure:
openai:
api-key: ${AZURE_OPENAI_API_KEY}
endpoint: ${AZURE_OPENAI_ENDPOINT}
```
```bash theme={"system"}
# 在您的环境或 .env 文件中
export AZURE_OPENAI_API_KEY=<您的 Azure OpenAI API 密钥>
export AZURE_OPENAI_ENDPOINT=<您的 Azure 终结点 URL>
```
### OpenAI 密钥
要使用 OpenAI 服务（而非 Azure）进行身份验证，请提供 OpenAI API 密钥。
## 自动配置
> **注意**：Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
> 有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Azure OpenAI Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-azure-openai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai'
}
```
> **提示**：请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
前缀 `spring.ai.azure.openai` 是用于配置与 Azure OpenAI 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-- |
| spring.ai.azure.openai.api-key | Azure AI OpenAI `资源管理`下`密钥和终结点`部分的密钥。 | - |
| spring.ai.azure.openai.endpoint | Azure AI OpenAI `资源管理`下`密钥和终结点`部分的终结点。 | - |
| spring.ai.azure.openai.openai-api-key | (非 Azure) OpenAI API 密钥。用于向 OpenAI 服务（而非 Azure OpenAI）进行身份验证。这会自动将终结点设置为 [https://api.openai.com/v1。使用](https://api.openai.com/v1。使用) `api-key` 或 `openai-api-key` 属性。使用此配置时，`spring.ai.azure.openai.embedding.options.deployment-name` 将被视为 [OpenAI 模型](https://platform.openai.com/docs/models)名称。 | - |
> **注意**：嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
>
> 要启用，请设置 spring.ai.model.embedding=azure-openai (默认情况下启用)
>
> 要禁用，请设置 spring.ai.model.embedding=none (或任何与 azure-openai 不匹配的值)
>
> 此更改是为了允许配置多个模型。
前缀 `spring.ai.azure.openai.embedding` 是配置 Azure OpenAI 的 `EmbeddingModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------------- | :----------------------------- | :--------------------- |
| spring.ai.azure.openai.embedding.enabled (已删除且不再有效) | 启用 Azure OpenAI 嵌入模型。 | true |
| spring.ai.model.embedding | 启用 Azure OpenAI 嵌入模型。 | azure-openai |
| spring.ai.azure.openai.embedding.metadata-mode | 文档内容提取模式。 | EMBED |
| spring.ai.azure.openai.embedding.options.deployment-name | 这是 Azure AI 门户中显示的"部署名称"的值。 | text-embedding-ada-002 |
| spring.ai.azure.openai.embedding.options.user | 操作的调用方或最终用户的标识符。这可用于跟踪或速率限制目的。 | - |
> **提示**：所有以 `spring.ai.azure.openai.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
`AzureOpenAiEmbeddingOptions` 提供嵌入请求的配置信息。
`AzureOpenAiEmbeddingOptions` 提供了一个构建器来创建选项。
在启动时，使用 `AzureOpenAiEmbeddingModel` 构造函数设置用于所有嵌入请求的默认选项。
在运行时，您可以通过将 `AzureOpenAiEmbeddingOptions` 实例传递给 `EmbeddingRequest` 请求来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
AzureOpenAiEmbeddingOptions.builder()
.model("Different-Embedding-Model-Deployment-Name")
.build()));
```
## 示例代码
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```properties theme={"system"}
spring.ai.azure.openai.api-key=您的 API 密钥
spring.ai.azure.openai.endpoint=您的终结点
spring.ai.azure.openai.embedding.options.model=text-embedding-ada-002
```
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
如果您不想使用 Spring Boot 自动配置，可以在应用程序中手动配置 `AzureOpenAiEmbeddingModel`。
为此，请将 `spring-ai-azure-openai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-azure-openai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-azure-openai'
}
```
> **提示**：请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
> **注意**：`spring-ai-azure-openai` 依赖项还提供对 `AzureOpenAiEmbeddingModel` 的访问。有关 `AzureOpenAiChatModel` 的更多信息，请参阅 [Azure OpenAI Embeddings](/spring4ai/api/embeddings/azure-openai-embeddings) 部分。
接下来，创建一个 `AzureOpenAiEmbeddingModel` 实例，并用它来计算两个输入文本之间的相似度：
```java theme={"system"}
var openAIClient = OpenAIClientBuilder()
.credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
.buildClient();
var embeddingModel = new AzureOpenAiEmbeddingModel(this.openAIClient)
.withDefaultOptions(AzureOpenAiEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.user("user-6")
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
```
> **注意**：`text-embedding-ada-002` 实际上是 Azure AI 门户中显示的`部署名称`。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Mistral AI 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/mistralai-embeddings
Spring AI 支持 Mistral AI 的文本嵌入模型。
嵌入是文本的向量表示，通过其在高维向量空间中的位置捕获段落的语义含义。Mistral AI Embeddings API 提供最先进的文本嵌入技术，可用于许多 NLP 任务。
## 先决条件
您需要使用 MistralAI 创建一个 API 才能访问 MistralAI 嵌入模型。
在 [MistralAI 注册页面](https://auth.mistral.ai/ui/registration)创建一个帐户，并在[API 密钥页面](https://console.mistral.ai/api-keys/)生成令牌。
Spring AI 项目定义了一个名为 `spring.ai.mistralai.api-key` 的配置属性，您应该将其设置为从 console.mistral.ai 获取的 `API Key` 的值。
您可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.mistralai.api-key=<您的 MistralAI API 密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，您可以使用 Spring 表达式语言 (SpEL) 引用环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
mistralai:
api-key: ${MISTRALAI_API_KEY}
```
```bash theme={"system"}
# 在您的环境或 .env 文件中
export MISTRALAI_API_KEY=<您的 MistralAI API 密钥>
```
您还可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("MISTRALAI_API_KEY");
```
### 添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (物料清单) 以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建系统中。
## 自动配置
Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 MistralAI Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-mistral-ai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-mistral-ai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，可让您配置 Mistral AI Embedding 模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :-------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试。 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表 (例如，抛出 NonTransientAiException)。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表 (例如，抛出 TransientAiException)。 | 空 |
#### 连接属性
前缀 `spring.ai.mistralai` 用作属性前缀，可让您连接到 MistralAI。
| 属性 | 描述 | 默认值 |
| :--------------------------- | :-------- | :----------------------------------------------- |
| spring.ai.mistralai.base-url | 要连接的 URL。 | [https://api.mistral.ai](https://api.mistral.ai) |
| spring.ai.mistralai.api-key | API 密钥。 | - |
#### 配置属性
嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=mistral (默认情况下启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与 mistral 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.mistralai.embedding` 是配置 MistralAI 的 `EmbeddingModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------------- | :-------------------------------------------------- | :------------ |
| spring.ai.mistralai.embedding.enabled (已删除且不再有效) | 启用 OpenAI 嵌入模型。 | true |
| spring.ai.model.embedding | 启用 OpenAI 嵌入模型。 | true |
| spring.ai.mistralai.embedding.base-url | 可选，覆盖 spring.ai.mistralai.base-url 以提供特定于嵌入的 URL。 | - |
| spring.ai.mistralai.embedding.api-key | 可选，覆盖 spring.ai.mistralai.api-key 以提供特定于嵌入的 API 密钥。 | - |
| spring.ai.mistralai.embedding.metadata-mode | 文档内容提取模式。 | EMBED |
| spring.ai.mistralai.embedding.options.model | 要使用的模型。 | mistral-embed |
| spring.ai.mistralai.embedding.options.encodingFormat | 返回嵌入的格式。可以是 float 或 base64。 | - |
您可以为 `ChatModel` 和 `EmbeddingModel` 实现覆盖通用的 `spring.ai.mistralai.base-url` 和 `spring.ai.mistralai.api-key`。
如果设置了 `spring.ai.mistralai.embedding.base-url` 和 `spring.ai.mistralai.embedding.api-key` 属性，则它们优先于通用属性。
同样，如果设置了 `spring.ai.mistralai.chat.base-url` 和 `spring.ai.mistralai.chat.api-key` 属性，则它们优先于通用属性。
如果您想为不同的模型和不同的模型端点使用不同的 MistralAI 帐户，这将非常有用。
所有以 `spring.ai.mistralai.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
[MistralAiEmbeddingOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/MistralAiEmbeddingOptions.java) 提供了 MistralAI 配置，例如要使用的模型等。
默认选项也可以使用 `spring.ai.mistralai.embedding.options` 属性进行配置。
在启动时，使用 `MistralAiEmbeddingModel` 构造函数设置用于所有嵌入请求的默认选项。
在运行时，您可以通过在 `EmbeddingRequest` 中使用 `MistralAiEmbeddingOptions` 实例来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
MistralAiEmbeddingOptions.builder()
.withModel("Different-Embedding-Model-Deployment-Name")
.build()));
```
## 示例控制器
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```properties theme={"system"}
spring.ai.mistralai.api-key=您的 API 密钥
spring.ai.mistralai.embedding.options.model=mistral-embed
```
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
var embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
如果您不使用 Spring Boot，则可以手动配置 OpenAI Embedding 模型。
为此，请将 `spring-ai-mistral-ai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-mistral-ai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-mistral-ai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
`spring-ai-mistral-ai` 依赖项还提供对 `MistralAiChatModel` 的访问。
有关 `MistralAiChatModel` 的更多信息，请参阅 [MistralAI 聊天客户端](/spring4ai/api/chat/mistralai-chat)部分。
接下来，创建一个 `MistralAiEmbeddingModel` 实例，并用它来计算两个输入文本之间的相似度：
```java theme={"system"}
var mistralAiApi = new MistralAiApi(System.getenv("MISTRAL_AI_API_KEY"));
var embeddingModel = new MistralAiEmbeddingModel(this.mistralAiApi,
MistralAiEmbeddingOptions.builder()
.withModel("mistral-embed")
.withEncodingFormat("float")
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
```
`MistralAiEmbeddingOptions` 为嵌入请求提供配置信息。
该选项类提供了一个 `builder()` 以便轻松创建选项。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OCI GenAI 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/oci-genai-embeddings
[OCI GenAI 服务](https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/) 提供文本嵌入功能，支持按需模型或专用 AI 集群。
[OCI Embedding 模型页面](https://docs.oracle.com/en-us/iaas/Content/generative-ai/embed-models.htm) 和 [OCI 文本嵌入页面](https://docs.oracle.com/en-us/iaas/Content/generative-ai/use-playground-embed.htm) 提供了有关在 OCI 上使用和托管嵌入模型的详细信息。
## 先决条件
### 添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (物料清单) 以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建系统中。
## 自动配置
Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OCI GenAI Embedding 客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-oci-genai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-oci-genai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
前缀 `spring.ai.oci.genai` 是用于配置与 OCI GenAI 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------- | :------------------------------------------------------------------------------------ | :---------------- |
| spring.ai.oci.genai.authenticationType | 用于向 OCI 进行身份验证的身份验证类型。可以是 `file`、`instance-principal`、`workload-identity` 或 `simple`。 | file |
| spring.ai.oci.genai.region | OCI 服务区域。 | us-chicago-1 |
| spring.ai.oci.genai.tenantId | OCI 租户 OCID，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.userId | OCI 用户 OCID，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.fingerprint | 私钥指纹，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.privateKey | 私钥内容，在使用 `simple` 身份验证时使用。 | - |
| spring.ai.oci.genai.passPhrase | 可选的私钥密码短语，在使用 `simple` 身份验证和受密码短语保护的私钥时使用。 | - |
| spring.ai.oci.genai.file | OCI 配置文件路径。在使用 `file` 身份验证时使用。 | 用户主目录/.oci/config |
| spring.ai.oci.genai.profile | OCI 配置文件名称。在使用 `file` 身份验证时使用。 | DEFAULT |
| spring.ai.oci.genai.endpoint | 可选的 OCI GenAI 端点。 | - |
嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=oci-genai (默认情况下启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与 oci-genai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.oci.genai.embedding` 是配置 OCI GenAI 的 `EmbeddingModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :----------------------------------------------- | :---------------------------------------- | :-------- |
| spring.ai.oci.genai.embedding.enabled (已删除且不再有效) | 启用 OCI GenAI 嵌入模型。 | true |
| spring.ai.model.embedding | 启用 OCI GenAI 嵌入模型。 | oci-genai |
| spring.ai.oci.genai.embedding.compartment | 模型隔间 OCID。 | - |
| spring.ai.oci.genai.embedding.servingMode | 要使用的模型服务模式。可以是 `on-demand` 或 `dedicated`。 | on-demand |
| spring.ai.oci.genai.embedding.truncate | 如果文本超出嵌入上下文，如何截断文本。可以是 `START` 或 `END`。 | END |
| spring.ai.oci.genai.embedding.model | 用于嵌入的模型或模型端点。 | - |
所有以 `spring.ai.oci.genai.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
`OCIEmbeddingOptions` 提供嵌入请求的配置信息。
`OCIEmbeddingOptions` 提供了一个构建器来创建选项。
在启动时，使用 `OCIEmbeddingOptions` 构造函数设置用于所有嵌入请求的默认选项。
在运行时，您可以通过将 `OCIEmbeddingOptions` 实例传递给 `EmbeddingRequest` 请求来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OCIEmbeddingOptions.builder()
.model("my-other-embedding-model")
.build()
));
```
## 示例代码
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```properties theme={"system"}
spring.ai.oci.genai.embedding.model=<你的模型>
spring.ai.oci.genai.embedding.compartment=<你的模型隔间>
```
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
如果您不想使用 Spring Boot 自动配置，可以在应用程序中手动配置 `OCIEmbeddingModel`。
为此，请将 `spring-oci-genai-openai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-oci-genai-openai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-oci-genai-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
接下来，创建一个 `OCIEmbeddingModel` 实例，并用它来计算两个输入文本之间的相似度：
```java theme={"system"}
final String EMBEDDING_MODEL = "cohere.embed-english-light-v2.0";
final String CONFIG_FILE = Paths.get(System.getProperty("user.home"), ".oci", "config").toString();
final String PROFILE = "DEFAULT";
final String REGION = "us-chicago-1";
final String COMPARTMENT_ID = System.getenv("OCI_COMPARTMENT_ID");
var authProvider = new ConfigFileAuthenticationDetailsProvider(
this.CONFIG_FILE, this.PROFILE);
var aiClient = GenerativeAiInferenceClient.builder()
.region(Region.valueOf(this.REGION))
.build(this.authProvider);
var options = OCIEmbeddingOptions.builder()
.model(this.EMBEDDING_MODEL)
.compartment(this.COMPARTMENT_ID)
.servingMode("on-demand")
.build();
var embeddingModel = new OCIEmbeddingModel(this.aiClient, this.options);
List embedding = this.embeddingModel.embed(new Document("How many provinces are in Canada?"));
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Ollama 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/ollama-embeddings
通过 [Ollama](https://ollama.ai/)，您可以在本地运行各种[AI 模型](https://ollama.com/search?c=embedding)并从中生成嵌入。
嵌入是一个浮点数向量（列表）。
两个向量之间的距离衡量它们的相关性。
小距离表示高相关性，大距离表示低相关性。
`OllamaEmbeddingModel` 实现利用了 Ollama [Embeddings API](https://github.com/ollama/ollama/blob/main/docs/api.md#generate-embeddings) 端点。
## 先决条件
您首先需要访问 Ollama 实例。有几种选择，包括：
* 在本地计算机上[下载并安装 Ollama](https://ollama.com/download)。
* 通过 [Testcontainers](/spring4ai/api/testcontainers) 配置并运行 Ollama。
* 通过 [Kubernetes 服务绑定](/spring4ai/api/cloud-bindings)绑定到 Ollama 实例。
您可以从 [Ollama 模型库](https://ollama.com/search?c=embedding)中拉取要在应用程序中使用的模型：
```bash theme={"system"}
ollama pull <模型名称>
```
您还可以拉取数千个免费的 [GGUF Hugging Face 模型](https://huggingface.co/models?library=gguf\&sort=trending)中的任何一个：
```bash theme={"system"}
ollama pull hf.co/<用户名>/<模型存储库>
```
或者，您可以启用自动下载任何所需模型的选项：[自动拉取模型](#auto-pulling-models)。
## 自动配置
Spring AI 自动配置、启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Ollama Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到您的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-ollama
```
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分将 Spring AI BOM 添加到您的构建文件中。
### 基本属性
前缀 `spring.ai.ollama` 是用于配置与 Ollama 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------ | :----------------------- | :----------------------------------------------- |
| spring.ai.ollama.base-url | Ollama API 服务器运行的基本 URL。 | [http://localhost:11434](http://localhost:11434) |
以下是初始化 Ollama 集成和[自动拉取模型](#auto-pulling-models)的属性。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------ | :----------------------- | :---- |
| spring.ai.ollama.init.pull-model-strategy | 是否在启动时拉取模型以及如何拉取。 | never |
| spring.ai.ollama.init.timeout | 等待模型拉取的时间。 | 5m |
| spring.ai.ollama.init.max-retries | 模型拉取操作的最大重试次数。 | 0 |
| spring.ai.ollama.init.embedding.include | 在初始化任务中包含此类型的模型。 | true |
| spring.ai.ollama.init.embedding.additional-models | 除通过默认属性配置的模型外，要初始化的其他模型。 | \[] |
### Embedding 属性
Embedding 自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=ollama (默认启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与 ollama 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.ollama.embedding.options` 是配置 Ollama 嵌入模型的属性前缀。
它包括 Ollama 请求（高级）参数，例如 `model`、`keep-alive` 和 `truncate`，以及 Ollama 模型 `options` 属性。
以下是 Ollama 嵌入模型的高级请求参数：
| 属性 | 描述 | 默认值 |
| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| spring.ai.ollama.embedding.enabled (已移除且不再有效) | 启用 Ollama 嵌入模型自动配置。 | true |
| spring.ai.model.embedding | 启用 Ollama 嵌入模型自动配置。 | ollama |
| spring.ai.ollama.embedding.options.model | 要使用的[支持的模型](https://github.com/ollama/ollama?tab=readme-ov-file#model-library)的名称。您可以使用专用的[嵌入模型](https://ollama.com/search?c=embedding)类型 | mistral |
| spring.ai.ollama.embedding.options.keep\_alive | 控制模型在请求后将保持加载到内存中的时间。 | 5m |
| spring.ai.ollama.embedding.options.truncate | 截断每个输入的末尾以适应上下文长度。如果为 false 且超出上下文长度，则返回错误。 | true |
其余 `options` 属性基于 [Ollama 有效参数和值](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values) 和 [Ollama 类型](https://github.com/ollama/ollama/blob/main/api/types.go)。默认值基于：[Ollama 类型默认值](https://github.com/ollama/ollama/blob/b538dc3858014f94b099730a592751a5454cab0a/api/types.go#L364)。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---- |
| spring.ai.ollama.embedding.options.numa | 是否使用 NUMA。 | false |
| spring.ai.ollama.embedding.options.num-ctx | 设置用于生成下一个令牌的上下文窗口的大小。 | 2048 |
| spring.ai.ollama.embedding.options.num-batch | 提示处理最大批处理大小。 | 512 |
| spring.ai.ollama.embedding.options.num-gpu | 发送到 GPU 的层数。在 macOS 上，默认为 1 以启用 metal 支持，0 禁用。此处的 1 表示应动态设置 NumGPU。 | -1 |
| spring.ai.ollama.embedding.options.main-gpu | 使用多个 GPU 时，此选项控制哪个 GPU 用于小张量，对于这些张量，跨所有 GPU 拆分计算的开销不值得。所讨论的 GPU 将使用稍多的 VRAM 来存储临时结果的暂存缓冲区。 | 0 |
| spring.ai.ollama.embedding.options.low-vram | - | false |
| spring.ai.ollama.embedding.options.f16-kv | - | true |
| spring.ai.ollama.embedding.options.logits-all | 返回所有令牌的 logits，而不仅仅是最后一个。要启用补全以返回 logprobs，此值必须为 true。 | - |
| spring.ai.ollama.embedding.options.vocab-only | 仅加载词汇表，不加载权重。 | - |
| spring.ai.ollama.embedding.options.use-mmap | 默认情况下，模型映射到内存中，这允许系统仅根据需要加载模型的必要部分。但是，如果模型大于您的总 RAM 量，或者如果您的系统可用内存不足，则使用 mmap 可能会增加页面换出的风险，从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢，但如果您不使用 mlock，则可能会减少页面换出。请注意，如果模型大于总 RAM 量，则关闭 mmap 将阻止模型完全加载。 | null |
| spring.ai.ollama.embedding.options.use-mlock | 将模型锁定在内存中，防止在内存映射时将其换出。这可以提高性能，但会牺牲内存映射的一些优势，因为它需要更多 RAM 才能运行，并且随着模型加载到 RAM 中，加载时间可能会变慢。 | false |
| spring.ai.ollama.embedding.options.num-thread | 设置计算期间要使用的线程数。默认情况下，Ollama 将检测此值以获得最佳性能。建议将此值设置为系统具有的物理 CPU 内核数（而不是逻辑内核数）。0 = 让运行时决定。 | 0 |
| spring.ai.ollama.embedding.options.num-keep | - | 4 |
| spring.ai.ollama.embedding.options.seed | 设置用于生成的随机数种子。将此值设置为特定数字将使模型为同一提示生成相同的文本。 | -1 |
| spring.ai.ollama.embedding.options.num-predict | 生成文本时要预测的最大令牌数。（-1 = 无限生成，-2 = 填充上下文） | -1 |
| spring.ai.ollama.embedding.options.top-k | 降低生成无意义内容的概率。较高的值（例如 100）将提供更多样化的答案，而较低的值（例如 10）将更加保守。 | 40 |
| spring.ai.ollama.embedding.options.top-p | 与 top-k 一起工作。较高的值（例如 0.95）将导致更多样化的文本，而较低的值（例如 0.5）将生成更集中和保守的文本。 | 0.9 |
| spring.ai.ollama.embedding.options.min-p | top\_p 的替代方案，旨在确保质量和多样性的平衡。参数 p 表示要考虑的令牌的最小概率，相对于最可能令牌的概率。例如，当 p=0.05 且最可能令牌的概率为 0.9 时，值小于 0.045 的 logits 将被过滤掉。 | 0.0 |
| spring.ai.ollama.embedding.options.tfs-z | 无尾采样用于减少输出中不太可能的令牌的影响。较高的值（例如 2.0）将更多地减少影响，而值 1.0 将禁用此设置。 | 1.0 |
| spring.ai.ollama.embedding.options.typical-p | - | 1.0 |
| spring.ai.ollama.embedding.options.repeat-last-n | 设置模型向后看多远以防止重复。（默认值：64，0 = 禁用，-1 = num\_ctx） | 64 |
| spring.ai.ollama.embedding.options.temperature | 模型的温度。增加温度会使模型回答更具创造性。 | 0.8 |
| spring.ai.ollama.embedding.options.repeat-penalty | 设置惩罚重复的强度。较高的值（例如 1.5）将更强烈地惩罚重复，而较低的值（例如 0.9）将更宽松。 | 1.1 |
| spring.ai.ollama.embedding.options.presence-penalty | - | 0.0 |
| spring.ai.ollama.embedding.options.frequency-penalty | - | 0.0 |
| spring.ai.ollama.embedding.options.mirostat | 启用 Mirostat 采样以控制困惑度。（默认值：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0） | 0 |
| spring.ai.ollama.embedding.options.mirostat-tau | 控制输出的连贯性和多样性之间的平衡。较低的值将导致更集中和连贯的文本。 | 5.0 |
| spring.ai.ollama.embedding.options.mirostat-eta | 影响算法响应生成文本反馈的速度。较低的学习率将导致较慢的调整，而较高的学习率将使算法更具响应性。 | 0.1 |
| spring.ai.ollama.embedding.options.penalize-newline | - | true |
| spring.ai.ollama.embedding.options.stop | 设置要使用的停止序列。遇到此模式时，LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的停止参数来设置多个停止模式。 | - |
| spring.ai.ollama.embedding.options.functions | 函数列表，由其名称标识，用于在单个提示请求中启用函数调用。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
所有以 `spring.ai.ollama.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
[OllamaOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaOptions.java) 提供了 Ollama 配置，例如要使用的模型、低级 GPU 和 CPU 调整等。
默认选项也可以使用 `spring.ai.ollama.embedding.options` 属性进行配置。
在启动时，使用 `OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions)` 配置用于所有嵌入请求的默认选项。
在运行时，您可以通过在 `EmbeddingRequest` 中使用 `OllamaOptions` 实例来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OllamaOptions.builder()
.model("Different-Embedding-Model-Deployment-Name"))
.truncates(false)
.build());
```
## 自动拉取模型
当 Ollama 实例中没有可用模型时，Spring AI Ollama 可以自动拉取模型。
此功能对于开发和测试以及将应用程序部署到新环境特别有用。
您还可以按名称拉取数千个免费的 [GGUF Hugging Face 模型](https://huggingface.co/models?library=gguf\&sort=trending)中的任何一个。
有三种拉取模型的策略：
* `always` (在 `PullModelStrategy.ALWAYS` 中定义): 始终拉取模型，即使它已经可用。有助于确保您使用的是最新版本的模型。
* `when_missing` (在 `PullModelStrategy.WHEN_MISSING` 中定义): 仅当模型尚不可用时才拉取模型。这可能会导致使用较旧版本的模型。
* `never` (在 `PullModelStrategy.NEVER` 中定义): 从不自动拉取模型。
由于下载模型时可能会出现延迟，因此不建议在生产环境中使用自动拉取。相反，请考虑提前评估和预下载必要的模型。
通过配置属性和默认选项定义的所有模型都可以在启动时自动拉取。
您可以使用配置属性配置拉取策略、超时和最大重试次数：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
timeout: 60s
max-retries: 1
```
在 Ollama 中所有指定的模型都可用之前，应用程序不会完成其初始化。根据模型大小和互联网连接速度，这可能会显著减慢应用程序的启动时间。
您可以在启动时初始化其他模型，这对于在运行时动态使用的模型很有用：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
additional-models:
- mxbai-embed-large
- nomic-embed-text
```
如果只想将拉取策略应用于特定类型的模型，则可以从初始化任务中排除嵌入模型：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
include: false
```
此配置将拉取策略应用于除嵌入模型之外的所有模型。
## HuggingFace 模型
Ollama 可以开箱即用地访问所有 [GGUF Hugging Face](https://huggingface.co/models?library=gguf\&sort=trending) 嵌入模型。
您可以按名称拉取这些模型中的任何一个：`ollama pull hf.co/<用户名>/<模型存储库>` 或配置自动拉取策略：[自动拉取模型](#auto-pulling-models)：
```
spring.ai.ollama.embedding.options.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=always
```
* `spring.ai.ollama.embedding.options.model`: 指定要使用的 [Hugging Face GGUF 模型](https://huggingface.co/models?library=gguf\&sort=trending)。
* `spring.ai.ollama.init.pull-model-strategy=always`: (可选) 启用启动时自动拉取模型。
对于生产环境，您应该预先下载模型以避免延迟：`ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1`。
## 示例控制器
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
如果您不使用 Spring Boot，则可以手动配置 `OllamaEmbeddingModel`。
为此，请将 spring-ai-ollama 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-ollama
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-ollama'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分将 Spring AI BOM 添加到您的构建文件中。
`spring-ai-ollama` 依赖项还提供对 `OllamaChatModel` 的访问。
有关 `OllamaChatModel` 的更多信息，请参阅 [Ollama 聊天客户端](/spring4ai/api/chat/ollama-chat)部分。
接下来，创建一个 `OllamaEmbeddingModel` 实例，并使用它通过专用的 `chroma/all-minilm-l6-v2-f32` 嵌入模型计算两个输入文本的嵌入：
```java theme={"system"}
var ollamaApi = OllamaApi.builder().build();
var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
OllamaOptions.builder()
.model(OllamaModel.MISTRAL.id())
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OllamaOptions.builder()
.model("chroma/all-minilm-l6-v2-f32"))
.truncate(false)
.build());
```
`OllamaOptions` 为所有嵌入请求提供配置信息。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# ONNX 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/onnx-embeddings
`TransformersEmbeddingModel` 是一个 `EmbeddingModel` 实现，它使用选定的[句子转换器](https://www.sbert.net/)在本地计算[句子嵌入](https://www.sbert.net/examples/applications/computing-embeddings/README.html#sentence-embeddings-with-transformers)。
您可以使用任何[HuggingFace Embedding模型](https://huggingface.co/spaces/mteb/leaderboard)。
它使用[预训练的](https://www.sbert.net/docs/pretrained_models.html)转换器模型，序列化为[开放神经网络交换 (ONNX)](https://onnx.ai/) 格式。
[Deep Java Library](https://djl.ai/) 和 Microsoft [ONNX Java Runtime](https://onnxruntime.ai/docs/get-started/with-java.html) 库用于运行 ONNX 模型并在 Java 中计算嵌入。
## 先决条件
要在 Java 中运行，我们需要将*分词器和转换器模型序列化*为 `ONNX` 格式。
使用 optimum-cli 序列化 - 实现此目的的一种快速方法是使用 [optimum-cli](https://huggingface.co/docs/optimum/exporters/onnx/usage_guides/export_a_model#exporting-a-model-to-onnx-using-the-cli) 命令行工具。
以下代码片段准备一个 python 虚拟环境，安装所需的包，并使用 `optimum-cli` 序列化（例如导出）指定的模型：
```bash theme={"system"}
python3 -m venv venv
source ./venv/bin/activate
(venv) pip install --upgrade pip
(venv) pip install optimum onnx onnxruntime sentence-transformers
(venv) optimum-cli export onnx --model sentence-transformers/all-MiniLM-L6-v2 onnx-output-folder
```
该代码片段将 [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) 转换器导出到 `onnx-output-folder` 文件夹。后者包含嵌入模型使用的 `tokenizer.json` 和 `model.onnx` 文件。
您可以使用任何 huggingface 转换器标识符或提供直接文件路径来代替 all-MiniLM-L6-v2。
## 自动配置
Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 ONNX Transformer Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-transformers
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-transformers'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分将 Spring AI BOM 添加到您的构建文件中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分将这些存储库添加到您的构建系统中。
要配置它，请使用 `spring.ai.embedding.transformer.*` 属性。
例如，将此添加到您的 *application.properties* 文件中，以使用 [intfloat/e5-small-v2](https://huggingface.co/intfloat/e5-small-v2) 文本嵌入模型配置客户端：
```properties theme={"system"}
spring.ai.embedding.transformer.onnx.modelUri=https://huggingface.co/intfloat/e5-small-v2/resolve/main/model.onnx
spring.ai.embedding.transformer.tokenizer.uri=https://huggingface.co/intfloat/e5-small-v2/raw/main/tokenizer.json
```
支持的属性的完整列表如下：
### Embedding 属性
Embedding 自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=transformers (默认启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与 transformers 不匹配的值)
此更改是为了允许配置多个模型。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
| spring.ai.embedding.transformer.enabled (已移除且不再有效) | 启用 Transformer Embedding 模型。 | true |
| spring.ai.model.embedding | 启用 Transformer Embedding 模型。 | transformers |
| spring.ai.embedding.transformer.tokenizer.uri | ONNX 引擎创建的预训练 HuggingFaceTokenizer 的 URI (例如 tokenizer.json)。 | onnx/all-MiniLM-L6-v2/tokenizer.json |
| spring.ai.embedding.transformer.tokenizer.options | HuggingFaceTokenizer 选项，例如 '`addSpecialTokens`', '`modelMaxLength`', '`truncation`', '`padding`', '`maxLength`', '`stride`', '`padToMultipleOf`'。留空以回退到默认值。 | 空 |
| spring.ai.embedding.transformer.cache.enabled | 启用远程资源缓存。 | true |
| spring.ai.embedding.transformer.cache.directory | 缓存远程资源（例如 ONNX 模型）的目录路径。 | `${java.io.tmpdir}`/spring-ai-onnx-model |
| spring.ai.embedding.transformer.onnx.modelUri | 现有的预训练 ONNX 模型。 | onnx/all-MiniLM-L6-v2/model.onnx |
| spring.ai.embedding.transformer.onnx.modelOutputName | ONNX 模型的输出节点名称，我们将用于嵌入计算。 | last\_hidden\_state |
| spring.ai.embedding.transformer.onnx.gpuDeviceId | 要执行的 GPU 设备 ID。仅当 >= 0 时适用。否则忽略。(需要额外的 onnxruntime\_gpu 依赖项) | -1 |
| spring.ai.embedding.transformer.metadataMode | 指定将使用文档内容和元数据的哪些部分来计算嵌入。 | NONE |
### 错误和特殊情况
如果您看到类似 `Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..` 的错误，您还需要在 `application.properties` 中启用分词器填充，如下所示：
```properties theme={"system"}
spring.ai.embedding.transformer.tokenizer.options.padding=true
```
如果您收到类似 `The generative output names don't contain expected: last_hidden_state. Consider one of the available model outputs: token_embeddings, ....` 的错误，您需要根据您的模型将模型输出名称设置为正确的值。
请考虑错误消息中列出的名称。
例如：
```properties theme={"system"}
spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings
```
如果您收到类似 `ai.onnxruntime.OrtException: Error code - ORT_FAIL - message: Deserialize tensor onnx::MatMul_10319 failed.GetFileLength for ./model.onnx_data failed:Invalid fd was supplied: -1` 的错误，
这意味着您的模型大于 2GB，并且已序列化为两个文件：`model.onnx` 和 `model.onnx_data`。
`model.onnx_data` 称为[外部数据](https://onnx.ai/onnx/repo-docs/ExternalData.html#external-data)，并且应位于 `model.onnx` 的同一目录下。
目前唯一的解决方法是将大的 `model.onnx_data` 复制到运行 Boot 应用程序的文件夹中。
如果您收到类似 `ai.onnxruntime.OrtException: Error code - ORT_EP_FAIL - message: Failed to find CUDA shared provider` 的错误，
这意味着您正在使用 GPU 参数 `spring.ai.embedding.transformer.onnx.gpuDeviceId`，但缺少 onnxruntime\_gpu 依赖项。
```xml theme={"system"}
com.microsoft.onnxruntime
onnxruntime_gpu
```
请根据 CUDA 版本选择合适的 onnxruntime\_gpu 版本 ([ONNX Java Runtime](https://onnxruntime.ai/docs/get-started/with-java.html))。
## 手动配置
如果您不使用 Spring Boot，则可以手动配置 Onnx Transformers Embedding 模型。
为此，请将 `spring-ai-transformers` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-transformers
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分将 Spring AI BOM 添加到您的构建文件中。
然后创建一个新的 `TransformersEmbeddingModel` 实例，并使用 `setTokenizerResource(tokenizerJsonUri)` 和 `setModelResource(modelOnnxUri)` 方法设置导出的 `tokenizer.json` 和 `model.onnx` 文件的 URI。(支持 `classpath:`、`file:` 或 `https:` URI 方案)。
如果未显式设置模型，`TransformersEmbeddingModel` 默认为 [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)：
| 维度 | 平均性能 | 速度 | 大小 |
| :-- | :---- | :---------- | :--- |
| 384 | 58.80 | 14200 个句子/秒 | 80MB |
以下代码片段演示了如何手动使用 `TransformersEmbeddingModel`：
```java theme={"system"}
TransformersEmbeddingModel embeddingModel = new TransformersEmbeddingModel();
// (可选) 默认为 classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json
embeddingModel.setTokenizerResource("classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json");
// (可选) 默认为 classpath:/onnx/all-MiniLM-L6-v2/model.onnx
embeddingModel.setModelResource("classpath:/onnx/all-MiniLM-L6-v2/model.onnx");
// (可选) 默认为 ${java.io.tmpdir}/spring-ai-onnx-model
// 默认情况下仅缓存 http/https 资源。
embeddingModel.setResourceCacheDirectory("/tmp/onnx-zoo");
// (可选) 如果看到类似以下错误，请设置分词器填充：
// "ai.onnxruntime.OrtException: Supplied array is ragged, ..."
embeddingModel.setTokenizerOptions(Map.of("padding", "true"));
embeddingModel.afterPropertiesSet();
List> embeddings = this.embeddingModel.embed(List.of("Hello world", "World is big"));
```
如果手动创建 `TransformersEmbeddingModel` 实例，则必须在设置属性之后和使用客户端之前调用 `afterPropertiesSet()` 方法。
第一次 `embed()` 调用会下载大的 ONNX 模型并将其缓存在本地文件系统中。
因此，第一次调用可能比平时花费更长的时间。
使用 `#setResourceCacheDirectory()` 方法设置存储 ONNX 模型的本地文件夹。
默认缓存文件夹为 `${java.io.tmpdir}/spring-ai-onnx-model`。
将 TransformersEmbeddingModel 创建为 `Bean` 更方便（且推荐）。
这样您就不必手动调用 `afterPropertiesSet()`：
```java theme={"system"}
@Bean
public EmbeddingModel embeddingModel() {
return new TransformersEmbeddingModel();
}
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OpenAI 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/openai-embeddings
Spring AI 支持 OpenAI 的文本嵌入模型。
OpenAI 的文本嵌入模型衡量文本字符串的相关性。
嵌入是一个浮点数向量（列表）。两个向量之间的距离衡量它们的相关性。小距离表示高相关性，大距离表示低相关性。
## 先决条件
您需要使用 OpenAI 创建一个 API 才能访问 OpenAI 嵌入模型。
在 [OpenAI 注册页面](https://platform.openai.com/signup)创建一个帐户，并在[API 密钥页面](https://platform.openai.com/account/api-keys)生成令牌。
Spring AI 项目定义了一个名为 `spring.ai.openai.api-key` 的配置属性，您应该将其设置为从 openai.com 获取的 `API Key` 的值。
您可以在 `application.properties` 文件中设置此配置属性：
```properties theme={"system"}
spring.ai.openai.api-key=<您的 OpenAI API 密钥>
```
为了在处理 API 密钥等敏感信息时增强安全性，您可以使用 Spring 表达式语言 (SpEL) 引用环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
```
```bash theme={"system"}
# 在您的环境或 .env 文件中
export OPENAI_API_KEY=<您的 OpenAI API 密钥>
```
您还可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索 API 密钥
String apiKey = System.getenv("OPENAI_API_KEY");
```
### 添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (物料清单) 以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建系统中。
## 自动配置
Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 OpenAI Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-openai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
#### 重试属性
前缀 `spring.ai.retry` 用作属性前缀，可让您配置 OpenAI Embedding 模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :-------------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不尝试对 `4xx` 客户端错误代码进行重试。 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表 (例如，抛出 NonTransientAiException)。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态代码列表 (例如，抛出 TransientAiException)。 | 空 |
#### 连接属性
前缀 `spring.ai.openai` 用作属性前缀，可让您连接到 OpenAI。
| 属性 | 描述 | 默认值 |
| :------------------------------- | :-------------------- | :----------------------------------------------- |
| spring.ai.openai.base-url | 要连接的 URL。 | [https://api.openai.com](https://api.openai.com) |
| spring.ai.openai.api-key | API 密钥。 | - |
| spring.ai.openai.organization-id | 可选，您可以指定用于 API 请求的组织。 | - |
| spring.ai.openai.project-id | 可选，您可以指定用于 API 请求的项目。 | - |
对于属于多个组织的用户 (或通过其旧版用户 API 密钥访问其项目的用户)，您可以选择指定用于 API 请求的组织和项目。
来自这些 API 请求的使用量将计为指定组织和项目的使用量。
#### 配置属性
嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=openai (默认情况下启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与 openai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.openai.embedding` 是配置 OpenAI 的 `EmbeddingModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------ | :------------------------------------------------- | :-------------------------------------------------------------------------- |
| spring.ai.openai.embedding.enabled (必需且不再有效) | 启用 OpenAI 嵌入模型。 | true |
| spring.ai.model.embedding | 启用 OpenAI 嵌入模型。 | openai |
| spring.ai.openai.embedding.base-url | 可选，覆盖 spring.ai.openai.base-url 以提供特定于嵌入的 URL。 | - |
| spring.ai.openai.embedding.embeddings-path | 要附加到 base-url 的路径。 | `/v1/embeddings` |
| spring.ai.openai.embedding.api-key | 可选，覆盖 spring.ai.openai.api-key 以提供特定于嵌入的 API 密钥。 | - |
| spring.ai.openai.embedding.organization-id | 可选，您可以指定用于 API 请求的组织。 | - |
| spring.ai.openai.embedding.project-id | 可选，您可以指定用于 API 请求的项目。 | - |
| spring.ai.openai.embedding.metadata-mode | 文档内容提取模式。 | EMBED |
| spring.ai.openai.embedding.options.model | 要使用的模型。 | text-embedding-ada-002 (其他选项：text-embedding-3-large、text-embedding-3-small) |
| spring.ai.openai.embedding.options.encodingFormat | 返回嵌入的格式。可以是 float 或 base64。 | - |
| spring.ai.openai.embedding.options.user | 代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。 | - |
| spring.ai.openai.embedding.options.dimensions | 生成的输出嵌入应具有的维度数。仅在 `text-embedding-3` 及更高版本的模型中受支持。 | - |
您可以为 `ChatModel` 和 `EmbeddingModel` 实现覆盖通用的 `spring.ai.openai.base-url` 和 `spring.ai.openai.api-key`。
如果设置了 `spring.ai.openai.embedding.base-url` 和 `spring.ai.openai.embedding.api-key` 属性，则它们优先于通用属性。
同样，如果设置了 `spring.ai.openai.chat.base-url` 和 `spring.ai.openai.chat.api-key` 属性，则它们优先于通用属性。
如果您想为不同的模型和不同的模型端点使用不同的 OpenAI 帐户，这将非常有用。
所有以 `spring.ai.openai.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
[OpenAiEmbeddingOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiEmbeddingOptions.java) 提供了 OpenAI 配置，例如要使用的模型等。
默认选项也可以使用 `spring.ai.openai.embedding.options` 属性进行配置。
在启动时，使用 `OpenAiEmbeddingModel` 构造函数设置用于所有嵌入请求的默认选项。
在运行时，您可以通过在 `EmbeddingRequest` 中使用 `OpenAiEmbeddingOptions` 实例来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OpenAiEmbeddingOptions.builder()
.model("Different-Embedding-Model-Deployment-Name")
.build()));
```
## 示例控制器
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```properties theme={"system"}
spring.ai.openai.api-key=您的 API 密钥
spring.ai.openai.embedding.options.model=text-embedding-ada-002
```
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
如果您不使用 Spring Boot，则可以手动配置 OpenAI Embedding 模型。
为此，请将 `spring-ai-openai` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
`spring-ai-openai` 依赖项还提供对 `OpenAiChatModel` 的访问。
有关 `OpenAiChatModel` 的更多信息，请参阅 [OpenAI 聊天客户端](/spring4ai/api/chat/openai-chat)部分。
接下来，创建一个 `OpenAiEmbeddingModel` 实例，并用它来计算两个输入文本之间的相似度：
```java theme={"system"}
var openAiApi = OpenAiApi.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var embeddingModel = new OpenAiEmbeddingModel(
this.openAiApi,
MetadataMode.EMBED,
OpenAiEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.user("user-6")
.build(),
RetryUtils.DEFAULT_RETRY_TEMPLATE);
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
```
`OpenAiEmbeddingOptions` 为嵌入请求提供配置信息。
api 和选项类提供了一个 `builder()` 以便轻松创建选项。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# PostgresML 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/postgresml-embeddings
Spring AI 支持 PostgresML 文本嵌入模型。
嵌入是文本的数字表示。
它们用于将单词和句子表示为向量，即数字数组。
嵌入可用于通过使用距离度量比较数字向量的相似性来查找相似的文本片段，或者它们可以用作其他机器学习模型的输入特征，因为大多数算法不能直接使用文本。
许多预训练的 LLM 可用于在 PostgresML 中从文本生成嵌入。
您可以在 Hugging Face 上浏览所有可用的[模型](https://huggingface.co/models?library=sentence-transformers)以找到最佳解决方案。
## 添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (物料清单) 以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建系统中。
## 自动配置
Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 PostgresML Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-postgresml-embedding
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-postgresml-embedding'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=postgresml (默认情况下启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与 postgresml 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.postgresml.embedding` 是为 PostgresML 嵌入配置 `EmbeddingModel` 实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :-------------------------------------------------- | :----------------------------------------------------- | :---------------------- |
| spring.ai.postgresml.embedding.enabled (已删除且不再有效) | 启用 PostgresML 嵌入模型。 | true |
| spring.ai.model.embedding | 启用 PostgresML 嵌入模型。 | postgresml |
| spring.ai.postgresml.embedding.create-extension | 执行 SQL 'CREATE EXTENSION IF NOT EXISTS pgml' 以启用扩展。 | false |
| spring.ai.postgresml.embedding.options.transformer | 用于嵌入的 Hugging Face 转换器模型。 | distilbert-base-uncased |
| spring.ai.postgresml.embedding.options.kwargs | 其他特定于转换器的选项。 | 空映射 |
| spring.ai.postgresml.embedding.options.vectorType | 用于嵌入的 PostgresML 向量类型。支持两种选项：`PG_ARRAY` 和 `PG_VECTOR`。 | PG\_ARRAY |
| spring.ai.postgresml.embedding.options.metadataMode | 文档元数据聚合模式。 | EMBED |
所有以 `spring.ai.postgresml.embedding.options` 为前缀的属性都可以在运行时通过向 `EmbeddingRequest` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
使用 [PostgresMlEmbeddingOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/postgresml/PostgresMlEmbeddingOptions.java) 通过选项（例如要使用的模型等）配置 `PostgresMlEmbeddingModel`。
启动时，您可以将 `PostgresMlEmbeddingOptions` 传递给 `PostgresMlEmbeddingModel` 构造函数，以配置用于所有嵌入请求的默认选项。
在运行时，您可以通过在 `EmbeddingRequest` 中使用 `PostgresMlEmbeddingOptions` 来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
PostgresMlEmbeddingOptions.builder()
.transformer("intfloat/e5-small")
.vectorType(VectorType.PG_ARRAY)
.kwargs(Map.of("device", "gpu"))
.build()));
```
## 示例控制器
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```properties theme={"system"}
spring.ai.postgresml.embedding.options.transformer=distilbert-base-uncased
spring.ai.postgresml.embedding.options.vectorType=PG_ARRAY
spring.ai.postgresml.embedding.options.metadataMode=EMBED
spring.ai.postgresml.embedding.options.kwargs.device=cpu
```
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
您可以不使用 Spring Boot 自动配置，而是手动创建 `PostgresMlEmbeddingModel`。
为此，请将 `spring-ai-postgresml` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-postgresml
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-postgresml'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
接下来，创建一个 `PostgresMlEmbeddingModel` 实例，并用它来计算两个输入文本之间的相似度：
```java theme={"system"}
var jdbcTemplate = new JdbcTemplate(dataSource); // 您的 postgresml 数据源
PostgresMlEmbeddingModel embeddingModel = new PostgresMlEmbeddingModel(this.jdbcTemplate,
PostgresMlEmbeddingOptions.builder()
.transformer("distilbert-base-uncased") // huggingface 转换器模型名称。
.vectorType(VectorType.PG_VECTOR) //PostgreSQL 中的向量类型。
.kwargs(Map.of("device", "cpu")) // 可选参数。
.metadataMode(MetadataMode.EMBED) // 文档元数据模式。
.build());
embeddingModel.afterPropertiesSet(); // 初始化 jdbc 模板和数据库。
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
```
手动创建时，必须在设置属性之后和使用客户端之前调用 `afterPropertiesSet()`。
将 PostgresMlEmbeddingModel 创建为 `@Bean` 更方便（且推荐）。
这样您就不必手动调用 `afterPropertiesSet()`：
```java theme={"system"}
@Bean
public EmbeddingModel embeddingModel(JdbcTemplate jdbcTemplate) {
return new PostgresMlEmbeddingModel(jdbcTemplate,
PostgresMlEmbeddingOptions.builder()
....
.build());
}
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Google 多模态 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/vertexai-embeddings-multimodal
实验性功能。仅用于实验目的。尚不兼容 `VectorStores`。
Vertex AI 支持两种类型的嵌入模型：文本和多模态。
本文档介绍如何使用 Vertex AI [多模态嵌入 API](https://cloud.google.com/vertex-ai/generative-ai/docs/embeddings/get-multimodal-embeddings) 创建多模态嵌入。
多模态嵌入模型会根据您提供的输入（可以包括图像、文本和视频数据的组合）生成 1408 维向量。
然后，嵌入向量可用于后续任务，例如图像分类或视频内容审核。
图像嵌入向量和文本嵌入向量位于同一语义空间中，具有相同的维度。
因此，这些向量可以互换使用于诸如通过文本搜索图像或通过图像搜索视频之类的用例。
VertexAI 多模态 API 强制执行[以下限制](https://cloud.google.com/vertex-ai/generative-ai/docs/embeddings/get-multimodal-embeddings#api-limits)。
对于纯文本嵌入用例，我们建议改用 [Vertex AI 文本嵌入模型](/spring4ai/api/embeddings/vertexai-embeddings-text)。
## 先决条件
* 安装适用于您操作系统的 [gcloud](https://cloud.google.com/sdk/docs/install) CLI。
* 通过运行以下命令进行身份验证。
将 `PROJECT_ID` 替换为您的 Google Cloud 项目 ID，并将 `ACCOUNT` 替换为您的 Google Cloud 用户名。
```bash theme={"system"}
gcloud config set project && \
gcloud auth application-default login
```
### 添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (物料清单) 以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建系统中。
## 自动配置
Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 VertexAI Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-vertex-ai-embedding
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-vertex-ai-embedding'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
前缀 `spring.ai.vertex.ai.embedding` 用作属性前缀，可让您连接到 VertexAI Embedding API。
| 属性 | 描述 | 默认值 |
| :---------------------------------------- | :-------------------------- | :-- |
| spring.ai.vertex.ai.embedding.project-id | Google Cloud Platform 项目 ID | - |
| spring.ai.vertex.ai.embedding.location | 区域 | - |
| spring.ai.vertex.ai.embedding.apiEndpoint | Vertex AI Embedding API 端点。 | - |
嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding.multimodal=vertexai (默认情况下启用)
要禁用，请设置 spring.ai.model.embedding.multimodal=none (或任何与 vertexai 不匹配的值)
此更改是为了允许配置多个模型。
前缀 `spring.ai.vertex.ai.embedding.multimodal` 是配置 VertexAI 多模态嵌入的嵌入模型实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :---------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |
| spring.ai.vertex.ai.embedding.multimodal.enabled (已删除且不再有效) | 启用 Vertex AI Embedding API 模型。 | true |
| spring.ai.model.embedding.multimodal=vertexai | 启用 Vertex AI Embedding API 模型。 | vertexai |
| spring.ai.vertex.ai.embedding.multimodal.options.model | 您可以使用以下模型获取多模态嵌入： | multimodalembedding\@001 |
| spring.ai.vertex.ai.embedding.multimodal.options.dimensions | 指定较低维度的嵌入。默认情况下，嵌入请求为数据类型返回一个 1408 浮点向量。您还可以为文本和图像数据指定较低维度的嵌入（128、256 或 512 浮点向量）。 | 1408 |
| spring.ai.vertex.ai.embedding.multimodal.options.video-start-offset-sec | 视频片段的开始偏移量（以秒为单位）。如果未指定，则计算为 max(0, endOffsetSec - 120)。 | - |
| spring.ai.vertex.ai.embedding.multimodal.options.video-end-offset-sec | 视频片段的结束偏移量（以秒为单位）。如果未指定，则计算为 min(video length, startOffSec + 120)。如果同时指定了 startOffSec 和 endOffSec，则将 endOffsetSec 调整为 min(startOffsetSec+120, endOffsetSec)。 | - |
| spring.ai.vertex.ai.embedding.multimodal.options.video-interval-sec | 将生成嵌入的视频间隔。interval\_sec 的最小值为 4。如果间隔小于 4，则返回 InvalidArgumentError。间隔的最大值没有限制。但是，如果间隔大于 min(video length, 120s)，则会影响生成的嵌入的质量。默认值：16。 | - |
## 手动配置
[VertexAiMultimodalEmbeddingModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/VertexAiMultimodalEmbeddingModel.java) 实现了 `DocumentEmbeddingModel`。
将 `spring-ai-vertex-ai-embedding` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-vertex-ai-embedding
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-vertex-ai-embedding'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
接下来，创建一个 `VertexAiMultimodalEmbeddingModel` 并将其用于嵌入生成：
```java theme={"system"}
VertexAiEmbeddingConnectionDetails connectionDetails =
VertexAiEmbeddingConnectionDetails.builder()
.projectId(System.getenv())
.location(System.getenv())
.build();
VertexAiMultimodalEmbeddingOptions options = VertexAiMultimodalEmbeddingOptions.builder()
.model(VertexAiMultimodalEmbeddingOptions.DEFAULT_MODEL_NAME)
.build();
var embeddingModel = new VertexAiMultimodalEmbeddingModel(this.connectionDetails, this.options);
Media imageMedial = new Media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/test.image.png"));
Media videoMedial = new Media(new MimeType("video", "mp4"), new ClassPathResource("/test.video.mp4"));
var document = new Document("Explain what do you see on this video?", List.of(this.imageMedial, this.videoMedial), Map.of());
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
DocumentEmbeddingRequest embeddingRequest = new DocumentEmbeddingRequest(List.of(this.document),
EmbeddingOptions.EMPTY);
EmbeddingResponse embeddingResponse = multiModelEmbeddingModel.call(this.embeddingRequest);
assertThat(embeddingResponse.getResults()).hasSize(3);
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Google 文本 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/vertexai-embeddings-text
Vertex AI 支持两种类型的嵌入模型：文本和多模态。
本文档介绍如何使用 Vertex AI [文本嵌入 API](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api) 创建文本嵌入。
Vertex AI 文本嵌入 API 使用密集向量表示。
与稀疏向量（倾向于将单词直接映射到数字）不同，密集向量旨在更好地表示一段文本的含义。
在生成式 AI 中使用密集向量嵌入的好处在于，您可以更好地搜索与查询含义一致的段落，即使这些段落使用的语言不同，而不是搜索直接的单词或语法匹配。
## 先决条件
* 安装适用于您操作系统的 [gcloud](https://cloud.google.com/sdk/docs/install) CLI。
* 通过运行以下命令进行身份验证。
将 `PROJECT_ID` 替换为您的 Google Cloud 项目 ID，并将 `ACCOUNT` 替换为您的 Google Cloud 用户名。
```bash theme={"system"}
gcloud config set project && \
gcloud auth application-default login
```
### 添加存储库和 BOM
Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。
请参阅[工件存储库](/spring4ai/getting-started#artifact-repositories)部分，将这些存储库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI 提供了一个 BOM (物料清单) 以确保在整个项目中使用一致版本的 Spring AI。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建系统中。
## 自动配置
> **注意**：Spring AI 自动配置和启动器模块的工件名称已发生重大更改。
> 有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 VertexAI Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-vertex-ai-embedding
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-vertex-ai-embedding'
}
```
> **提示**：请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
### Embedding 属性
前缀 `spring.ai.vertex.ai.embedding` 用作属性前缀，可让您连接到 VertexAI Embedding API。
| 属性 | 描述 | 默认值 |
| :---------------------------------------- | :-------------------------- | :-- |
| spring.ai.vertex.ai.embedding.project-id | Google Cloud Platform 项目 ID | - |
| spring.ai.vertex.ai.embedding.location | 区域 | - |
| spring.ai.vertex.ai.embedding.apiEndpoint | Vertex AI Embedding API 端点。 | - |
> **注意**：嵌入自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
>
> 要启用，请设置 spring.ai.model.embedding.text=vertexai (默认情况下启用)
>
> 要禁用，请设置 spring.ai.model.embedding.text=none (或任何与 vertexai 不匹配的值)
>
> 此更改是为了允许配置多个模型。
前缀 `spring.ai.vertex.ai.embedding.text` 是配置 VertexAI 文本嵌入的嵌入模型实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
| spring.ai.vertex.ai.embedding.text.enabled (已删除且不再有效) | 启用 Vertex AI Embedding API 模型。 | true |
| spring.ai.model.embedding.text | 启用 Vertex AI Embedding API 模型。 | vertexai |
| spring.ai.vertex.ai.embedding.text.options.model | 这是要使用的 [Vertex 文本嵌入模型](https://cloud.google.com/vertex-ai/generative-ai/docs/embeddings/get-text-embeddings#supported-models)。 | text-embedding-004 |
| spring.ai.vertex.ai.embedding.text.options.task-type | 预期的下游应用程序，以帮助模型生成更高质量的嵌入。可用的[任务类型](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#request_body)。 | `RETRIEVAL_DOCUMENT` |
| spring.ai.vertex.ai.embedding.text.options.title | 可选标题，仅在 task\_type=RETRIEVAL\_DOCUMENT 时有效。 | - |
| spring.ai.vertex.ai.embedding.text.options.dimensions | 生成的输出嵌入应具有的维度数。模型版本 004 及更高版本支持。您可以使用此参数来减小嵌入大小，例如，用于存储优化。 | - |
| spring.ai.vertex.ai.embedding.text.options.auto-truncate | 设置为 true 时，将截断输入文本。设置为 false 时，如果输入文本长于模型支持的最大长度，则返回错误。 | true |
## 示例控制器
[创建](https://start.spring.io/)一个新的 Spring Boot 项目，并将 `spring-ai-starter-model-vertex-ai-embedding` 添加到您的 pom (或 gradle) 依赖项中。
在 `src/main/resources` 目录下添加一个 `application.properties` 文件，以启用和配置 VertexAi 聊天模型：
```properties theme={"system"}
spring.ai.vertex.ai.embedding.project-id=<您的项目 ID>
spring.ai.vertex.ai.embedding.location=<您的项目位置>
spring.ai.vertex.ai.embedding.text.options.model=text-embedding-004
```
这将创建一个 `VertexAiTextEmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用嵌入模型进行嵌入生成。
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
[VertexAiTextEmbeddingModel](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/VertexAiTextEmbeddingModel.java) 实现了 `EmbeddingModel`。
将 `spring-ai-vertex-ai-embedding` 依赖项添加到项目的 Maven `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-vertex-ai-embedding
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-vertex-ai-embedding'
}
```
> **提示**：请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将 Spring AI BOM 添加到您的构建文件中。
接下来，创建一个 `VertexAiTextEmbeddingModel` 并将其用于文本生成：
```java theme={"system"}
VertexAiEmbeddingConnectionDetails connectionDetails =
VertexAiEmbeddingConnectionDetails.builder()
.projectId(System.getenv())
.location(System.getenv())
.build();
VertexAiTextEmbeddingOptions options = VertexAiTextEmbeddingOptions.builder()
.model(VertexAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
.build();
var embeddingModel = new VertexAiTextEmbeddingModel(this.connectionDetails, this.options);
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
```
### 从 Google 服务帐户加载凭据
要从服务帐户 json 文件以编程方式加载 GoogleCredentials，可以使用以下方法：
```java theme={"system"}
GoogleCredentials credentials = GoogleCredentials.fromStream()
.createScoped("https://www.googleapis.com/auth/cloud-platform");
credentials.refreshIfExpired();
VertexAiEmbeddingConnectionDetails connectionDetails =
VertexAiEmbeddingConnectionDetails.builder()
.projectId(System.getenv())
.location(System.getenv())
.apiEndpoint(endpoint)
.predictionServiceSettings(
PredictionServiceSettings.newBuilder()
.setEndpoint(endpoint)
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build());
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 智谱AI 向量模型
Source: https://javaai.pig4cloud.com/spring-ai/api/embeddings/zhipuai-embeddings
Spring AI 支持智谱AI的文本嵌入模型。
智谱AI的文本嵌入模型衡量文本字符串的相关性。
嵌入是一个浮点数向量（列表）。两个向量之间的距离衡量它们的相关性。小距离表示高相关性，大距离表示低相关性。
## 先决条件
您需要使用智谱AI创建一个API才能访问智谱AI语言模型。
在[智谱AI注册页面](https://open.bigmodel.cn/login)创建一个帐户，并在[API密钥页面](https://open.bigmodel.cn/usercenter/apikeys)生成令牌。
Spring AI项目定义了一个名为`spring.ai.zhipu.api-key`的配置属性，您应该将其设置为从API密钥页面获取的`API Key`的值。
您可以在`application.properties`文件中设置此配置属性：
```properties theme={"system"}
spring.ai.zhipu.api-key=<您的智谱AI API密钥>
```
为了在处理API密钥等敏感信息时增强安全性，您可以使用Spring表达式语言（SpEL）引用环境变量：
```yaml theme={"system"}
# 在 application.yml 中
spring:
ai:
zhipu:
api-key: ${ZHIPU_API_KEY}
```
```bash theme={"system"}
# 在您的环境或 .env 文件中
export ZHIPU_API_KEY=<您的智谱AI API密钥>
```
您还可以在应用程序代码中以编程方式设置此配置：
```java theme={"system"}
// 从安全来源或环境变量中检索API密钥
String apiKey = System.getenv("ZHIPU_API_KEY");
```
### 添加仓库和BOM
Spring AI的构件发布在Maven Central和Spring Snapshot仓库中。
请参阅[构件仓库](/spring4ai/getting-started#artifact-repositories)部分，将这些仓库添加到您的构建系统中。
为了帮助进行依赖管理，Spring AI提供了一个BOM（物料清单），以确保在整个项目中都使用一致的Spring AI版本。请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将Spring AI BOM添加到您的构建系统中。
## 自动配置
Spring AI自动配置、启动器模块的构件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI为智谱AI Embedding模型提供Spring Boot自动配置。
要启用它，请将以下依赖项添加到项目的Maven `pom.xml`文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-zhipuai
```
或添加到您的Gradle `build.gradle`构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-zhipuai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将Spring AI BOM添加到您的构建文件中。
### Embedding属性
#### 重试属性
前缀`spring.ai.retry`用作属性前缀，可让您配置智谱AI Embedding模型的重试机制。
| 属性 | 描述 | 默认值 |
| :--------------------------------------- | :---------------------------------------------------------- | :---- |
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠持续时间。 | 2 秒 |
| spring.ai.retry.backoff.multiplier | 退避间隔乘数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 分钟 |
| spring.ai.retry.on-client-errors | 如果为false，则抛出NonTransientAiException，并且不尝试对`4xx`客户端错误代码进行重试。 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的HTTP状态代码列表（例如，抛出NonTransientAiException）。 | 空 |
| spring.ai.retry.on-http-codes | 应触发重试的HTTP状态代码列表（例如，抛出TransientAiException）。 | 空 |
#### 连接属性
前缀`spring.ai.zhipuai`用作属性前缀，可让您连接到智谱AI。
| 属性 | 描述 | 默认值 |
| :------------------------- | :------- | :--------------------------------------------------------------------- |
| spring.ai.zhipuai.base-url | 要连接的URL。 | [https://open.bigmodel.cn/api/paas](https://open.bigmodel.cn/api/paas) |
| spring.ai.zhipuai.api-key | API密钥。 | - |
#### 配置属性
Embedding自动配置的启用和禁用现在通过前缀为`spring.ai.model.embedding`的顶级属性进行配置。
要启用，请设置 spring.ai.model.embedding=zhipuai (默认启用)
要禁用，请设置 spring.ai.model.embedding=none (或任何与zhipuai不匹配的值)
此更改是为了允许配置多个模型。
前缀`spring.ai.zhipuai.embedding`是配置智谱AI的`EmbeddingModel`实现的属性前缀。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------- | :--------------------------------------------------- | :---------- |
| spring.ai.zhipuai.embedding.enabled (已移除且不再有效) | 启用智谱AI Embedding模型。 | true |
| spring.ai.model.embedding | 启用智谱AI Embedding模型。 | zhipuai |
| spring.ai.zhipuai.embedding.base-url | 可选，覆盖spring.ai.zhipuai.base-url以提供特定于Embedding的URL。 | - |
| spring.ai.zhipuai.embedding.api-key | 可选，覆盖spring.ai.zhipuai.api-key以提供特定于Embedding的API密钥。 | - |
| spring.ai.zhipuai.embedding.options.model | 要使用的模型。 | embedding-2 |
| spring.ai.zhipuai.embedding.options.dimensions | 维度数量，当模型为embedding-3时，默认值为2048。 | - |
您可以为`ChatModel`和`EmbeddingModel`实现覆盖通用的`spring.ai.zhipuai.base-url`和`spring.ai.zhipuai.api-key`。
如果设置了`spring.ai.zhipuai.embedding.base-url`和`spring.ai.zhipuai.embedding.api-key`属性，则它们优先于通用属性。
同样，如果设置了`spring.ai.zhipuai.chat.base-url`和`spring.ai.zhipuai.chat.api-key`属性，则它们优先于通用属性。
如果您想为不同的模型和不同的模型端点使用不同的智谱AI帐户，这将非常有用。
所有以`spring.ai.zhipuai.embedding.options`为前缀的属性都可以在运行时通过向`EmbeddingRequest`调用添加特定于请求的[Embedding选项](#embedding-options)来覆盖。
## 运行时选项
[ZhiPuAiEmbeddingOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/ZhiPuAiEmbeddingOptions.java)提供了智谱AI的配置，例如要使用的模型等。
默认选项也可以使用`spring.ai.zhipuai.embedding.options`属性进行配置。
在启动时，使用`ZhiPuAiEmbeddingModel`构造函数设置用于所有Embedding请求的默认选项。
在运行时，您可以通过在`EmbeddingRequest`中使用`ZhiPuAiEmbeddingOptions`实例来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
ZhiPuAiEmbeddingOptions.builder()
.model("Different-Embedding-Model-Deployment-Name")
.build()));
```
## 示例控制器
这将创建一个`EmbeddingModel`实现，您可以将其注入到您的类中。
这是一个简单的`@Controller`类的示例，它使用`EmbeddingModel`实现。
```properties theme={"system"}
spring.ai.zhipuai.api-key=您的API密钥
spring.ai.zhipuai.embedding.options.model=embedding-2
```
```java theme={"system"}
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
```
## 手动配置
如果您不使用Spring Boot，则可以手动配置智谱AI Embedding模型。
为此，请将`spring-ai-zhipuai`依赖项添加到项目的Maven `pom.xml`文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-zhipuai
```
或添加到您的Gradle `build.gradle`构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-zhipuai'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分，将Spring AI BOM添加到您的构建文件中。
`spring-ai-zhipuai`依赖项还提供对`ZhiPuAiChatModel`的访问。
有关`ZhiPuAiChatModel`的更多信息，请参阅[智谱AI聊天客户端](/spring4ai/api/chat/zhipuai-chat)部分。
接下来，创建一个`ZhiPuAiEmbeddingModel`实例，并使用它来计算两个输入文本之间的相似度：
```java theme={"system"}
var zhiPuAiApi = new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));
var embeddingModel = new ZhiPuAiEmbeddingModel(api, MetadataMode.EMBED,
ZhiPuAiEmbeddingOptions.builder()
.model("embedding-3")
.dimensions(1536)
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
```
`ZhiPuAiEmbeddingOptions`为Embedding请求提供配置信息。
该选项类提供了一个`builder()`，以便轻松创建选项。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# ETL 清洗
Source: https://javaai.pig4cloud.com/spring-ai/api/etl-pipeline
ETL（提取、转换、加载）管道是构建有效的 RAG（检索增强生成）系统的关键组件。
## 概述
Spring AI 中的 ETL 管道通过以下方式帮助准备和处理数据以供 RAG 系统使用：
* 从各种来源提取数据
* 将其转换为合适的格式
* 将其加载到向量存储中以实现高效检索
## 主要特性
从各种来源提取数据，包括文档、数据库和 API
将原始数据转换为向量嵌入和元数据
将处理后的数据加载到向量存储中以实现高效检索
管理和监控整个 ETL 流程
## 实现
### 基本管道结构
```java theme={"system"}
@Configuration
public class ETLPipelineConfig {
@Bean
public ETLPipeline etlPipeline(
DocumentLoader documentLoader,
EmbeddingModel embeddingModel,
VectorStore vectorStore) {
return ETLPipeline.builder()
.documentLoader(documentLoader)
.embeddingModel(embeddingModel)
.vectorStore(vectorStore)
.build();
}
}
```
### 管道组件
1. **文档加载器**
* PDF 文档
* 文本文件
* 网页
* 数据库记录
2. **转换器**
* 文本分块
* 嵌入生成
* 元数据提取
3. **向量存储**
* 与各种向量数据库集成
* 高效存储和检索
* 索引管理
## 最佳实践
在实现 ETL 管道时，请考虑以下最佳实践：
* **分块策略**：根据您的用例选择适当的分块大小
* **元数据**：包含相关元数据以提供更好的上下文
* **错误处理**：实现强大的错误处理和重试机制
* **监控**：设置管道性能和数据质量监控
* **版本控制**：维护数据和模型的版本控制
## 配置属性
```properties theme={"system"}
spring.ai.etl.pipeline.enabled=true
spring.ai.etl.pipeline.chunk-size=1000
spring.ai.etl.pipeline.chunk-overlap=200
spring.ai.etl.pipeline.batch-size=100
```
## 高级特性
### 自定义转换器
您可以为特定的数据处理需求实现自定义转换器：
```java theme={"system"}
@Component
public class CustomTransformer implements DocumentTransformer {
@Override
public Document transform(Document document) {
// 自定义转换逻辑
return transformedDocument;
}
}
```
### 管道监控
使用 Spring Boot Actuator 监控您的 ETL 管道：
```properties theme={"system"}
management.endpoints.web.exposure.include=etl-pipeline
management.endpoint.etl-pipeline.enabled=true
```
## 故障排除
常见问题及其解决方案：
1. **内存问题**
* 调整批处理大小
* 实现流式处理
* 使用适当的分块大小
2. **性能瓶颈**
* 优化嵌入生成
* 使用并行处理
* 实现缓存
3. **数据质量**
* 实现验证步骤
* 添加数据清理转换器
* 监控嵌入质量
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Azure OpenAI 图像模型
Source: https://javaai.pig4cloud.com/spring-ai/api/image/azure-openai-image
# Azure OpenAI 图像模型
Spring AI 项目集成了 Azure OpenAI 的图像生成模型。
## 添加依赖
将 `spring-ai-azure-openai-spring-boot-starter` 依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-azure-openai-spring-boot-starter
```
## 配置 Azure OpenAI 凭证
请确保在您的 `application.properties` 文件中设置了以下属性：
* `spring.ai.azure.openai.api-key`: 您的 Azure OpenAI API 密钥。
* `spring.ai.azure.openai.endpoint`: 您的 Azure OpenAI 端点。
```properties theme={"system"}
spring.ai.azure.openai.api-key=YOUR_AZURE_OPENAI_API_KEY
spring.ai.azure.openai.endpoint=YOUR_AZURE_OPENAI_ENDPOINT
```
您还需要通过设置 `spring.ai.azure.openai.image.enabled=true` 属性来启用 Azure OpenAI 图像客户端。
此外，请浏览 [Azure OpenAI图像选项 (AzureOpenAiImageOptions)](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiImageOptions.java) 了解可用的调用选项。常用选项也可以通过 `spring.ai.azure.openai.image.options.*` 属性进行配置。
## 调用 ImageClient
`ImageClient` 接口提供了一种与图像生成模型交互的便携方式。
```java theme={"system"}
ImageResponse imageResponse = imageClient.call(
new ImagePrompt("A light cream cat on a purple background") // 示例提示内容通常保留英文
);
```
***
`ImageClient` 会自动配置和注入。
```java theme={"system"}
@RestController
public class ImageController {
private final ImageClient imageClient;
@Autowired
public ImageController(ImageClient imageClient) {
this.imageClient = imageClient;
}
@GetMapping("/image")
public String image(@RequestParam String prompt) {
ImageResponse response = imageClient.call(new ImagePrompt(prompt));
// 处理响应
return response.getResult().getOutput().getUrl();
}
}
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
```
# OpenAI 图像模型
Source: https://javaai.pig4cloud.com/spring-ai/api/image/openai-image
# OpenAI 图像模型
Spring AI 项目集成了 OpenAI 的图像生成模型。
## 添加依赖
将 `spring-ai-openai-spring-boot-starter` 依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-spring-boot-starter
```
## 配置 OpenAI 凭证
请确保在您的 `application.properties` 文件中设置了 `spring.ai.openai.api-key` 属性：
```properties theme={"system"}
spring.ai.openai.api-key=YOUR_API_KEY
```
您还需要通过设置 `spring.ai.openai.image.enabled=true` 属性来启用 OpenAI 图像客户端。
此外，请浏览 [OpenAI图像选项 (OpenAiImageOptions)](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiImageOptions.java) 了解可用的调用选项。常用选项也可以通过 `spring.ai.openai.image.options.*` 属性进行配置。
## 调用 ImageClient
`ImageClient` 接口提供了一种与图像生成模型交互的便携方式。
```java theme={"system"}
ImageResponse imageResponse = imageClient.call(
new ImagePrompt("A light cream cat on a purple background") // 示例提示内容通常保留英文
);
```
***
`ImageClient` 会自动配置和注入。
```java theme={"system"}
@RestController
public class ImageController {
private final ImageClient imageClient;
@Autowired
public ImageController(ImageClient imageClient) {
this.imageClient = imageClient;
}
@GetMapping("/image")
public String image(@RequestParam String prompt) {
ImageResponse response = imageClient.call(new ImagePrompt(prompt));
// 处理响应
return response.getResult().getOutput().getUrl();
}
}
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
```
# 千帆图像模型
Source: https://javaai.pig4cloud.com/spring-ai/api/image/qianfan-image
# 千帆图像模型
Spring AI 项目集成了百度智能云千帆的图像生成模型。
## 添加依赖
将 `spring-ai-qianfan-spring-boot-starter` 依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-qianfan-spring-boot-starter
```
## 配置千帆凭证
请确保在您的 `application.properties` 文件中设置了 `spring.ai.qianfan.api-key` 和 `spring.ai.qianfan.secret-key` 属性：
```properties theme={"system"}
spring.ai.qianfan.api-key=YOUR_API_KEY
spring.ai.qianfan.secret-key=YOUR_SECRET_KEY
```
您还需要通过设置 `spring.ai.qianfan.image.enabled=true` 属性来启用千帆图像客户端。
此外，请浏览 [千帆图像选项 (QianfanImageOptions)](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-qianfan/src/main/java/org/springframework/ai/qianfan/api/QianfanImageApi.java)
了解可用的调用选项。常用选项也可以通过 `spring.ai.qianfan.image.options.*` 属性进行配置。
## 调用 ImageClient
`ImageClient` 接口提供了一种与图像生成模型交互的便携方式。
```java theme={"system"}
ImageResponse imageResponse = imageClient.call(
new ImagePrompt("A light cream cat on a purple background") // 示例提示内容通常保留英文
);
```
***
`ImageClient` 会自动配置和注入。
```java theme={"system"}
@RestController
public class ImageController {
private final ImageClient imageClient;
@Autowired
public ImageController(ImageClient imageClient) {
this.imageClient = imageClient;
}
@GetMapping("/image")
public String image(@RequestParam String prompt) {
ImageResponse response = imageClient.call(new ImagePrompt(prompt));
// 处理响应
return response.getResult().getOutput().getUrl();
}
}
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
```
# StabilityAI 图像模型
Source: https://javaai.pig4cloud.com/spring-ai/api/image/stabilityai-image
# StabilityAI 图像模型
Spring AI 项目集成了 StabilityAI 的图像生成模型。
## 添加依赖
将 `spring-ai-stabilityai-spring-boot-starter` 依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-stabilityai-spring-boot-starter
```
## 配置 StabilityAI 凭证
请确保在您的 `application.properties` 文件中设置了 `spring.ai.stabilityai.api-key` 属性：
```properties theme={"system"}
spring.ai.stabilityai.api-key=YOUR_API_KEY
```
您还需要通过设置 `spring.ai.stabilityai.image.enabled=true` 属性来启用 StabilityAI 图像客户端。
此外，请浏览 [StabilityAI图像选项 (StabilityAiImageOptions)](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-stabilityai/src/main/java/org/springframework/ai/stabilityai/api/StabilityAiImageOptions.java) 了解可用的调用选项。常用选项也可以通过 `spring.ai.stabilityai.image.options.*` 属性进行配置。
## 调用 ImageClient
`ImageClient` 接口提供了一种与图像生成模型交互的便携方式。
```java theme={"system"}
ImageResponse imageResponse = imageClient.call(
new ImagePrompt("A light cream cat on a purple background") // 示例提示内容通常保留英文
);
```
***
`ImageClient` 会自动配置和注入。
```java theme={"system"}
@RestController
public class ImageController {
private final ImageClient imageClient;
@Autowired
public ImageController(ImageClient imageClient) {
this.imageClient = imageClient;
}
@GetMapping("/image")
public String image(@RequestParam String prompt) {
ImageResponse response = imageClient.call(new ImagePrompt(prompt));
// 处理响应
return response.getResult().getOutput().getUrl();
}
}
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
```
# 智谱AI图像模型
Source: https://javaai.pig4cloud.com/spring-ai/api/image/zhipuai-image
# 智谱AI图像模型
Spring AI 项目集成了智谱AI的图像生成模型。
## 添加依赖
将 `spring-ai-zhipuai-spring-boot-starter` 依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-zhipuai-spring-boot-starter
```
## 配置智谱AI凭证
请确保在您的 `application.properties` 文件中设置了 `spring.ai.zhipuai.api-key` 属性：
```properties theme={"system"}
spring.ai.zhipuai.api-key=YOUR_API_KEY
```
您还需要通过设置 `spring.ai.zhipuai.image.enabled=true` 属性来启用智谱AI图像客户端。
此外，请浏览 [智谱AI图像选项 (ZhipuAiImageOptions)](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/ZhipuAiImageOptions.java) 了解可用的调用选项。常用选项也可以通过 `spring.ai.zhipuai.image.options.*` 属性进行配置。
## 调用 ImageClient
`ImageClient` 接口提供了一种与图像生成模型交互的便携方式。
```java theme={"system"}
ImageResponse imageResponse = imageClient.call(
new ImagePrompt("A light cream cat on a purple background") // 示例提示内容通常保留英文
);
```
***
`ImageClient` 会自动配置和注入。
```java theme={"system"}
@RestController
public class ImageController {
private final ImageClient imageClient;
@Autowired
public ImageController(ImageClient imageClient) {
this.imageClient = imageClient;
}
@GetMapping("/image")
public String image(@RequestParam String prompt) {
ImageResponse response = imageClient.call(new ImagePrompt(prompt));
// 处理响应
return response.getResult().getOutput().getUrl();
}
}
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
```
# 图像模型
Source: https://javaai.pig4cloud.com/spring-ai/api/imageclient
Spring AI 中支持的图像生成模型概述
# 图像模型
Spring AI 通过不同的提供商提供对各种图像生成模型的支持。以下是当前支持的实现：
## 支持的提供商
* [Azure OpenAI](/api/image/azure-openai-image)
* [OpenAI](/api/image/openai-image)
* [Stability AI](/api/image/stabilityai-image)
* [智谱AI](/api/image/zhipuai-image)
* [千帆](/api/image/qianfan-image)
每个提供商都实现了 `ImageClient` 接口，允许您使用不同的 AI 模型生成图像，同时保持一致的 API。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MCP 客户端启动器文档
Source: https://javaai.pig4cloud.com/spring-ai/api/mcp/mcp-client-boot-starter-docs
# MCP 客户端启动器文档
Spring AI MCP 客户端启动器 (`spring-ai-mcp-client-boot-starter`) 促进了与符合模型上下文协议 (MCP) 的服务器的集成。
## 概述
MCP 客户端启动器提供：
* 用于与 MCP 服务器交互的自动配置客户端。
* 用于发送 MCP 请求和处理响应的简化抽象。
* 与 Spring Boot 应用程序的无缝集成。
## 入门
要开始使用 MCP 客户端启动器，请将以下依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-mcp-client-boot-starter
```
## 配置
MCP 客户端启动器可以通过 `application.properties` 或 `application.yml` 文件进行配置。以下是一些常见的配置选项：
### 客户端属性
* `spring.ai.mcp.client.base-url`: MCP 服务器的基础 URL。
* `spring.ai.mcp.client.timeout`: 请求超时时间 (以毫秒为单位，默认为 10000)。
* `spring.ai.mcp.client.username` / `spring.ai.mcp.client.password`: 用于基本身份验证的凭证 (如果需要)。
示例 `application.properties`：
```properties theme={"system"}
spring.ai.mcp.client.base-url=http://localhost:8080/mcp
spring.ai.mcp.client.username=user
spring.ai.mcp.client.password=secret
```
### ChatModel 和 EmbeddingModel 配置
当使用 MCP 客户端时，您通常会在您的应用程序中定义 `ChatModel` 或 `EmbeddingModel` bean，这些 bean 将通过 MCP 与远程模型进行通信。
通过设置以下属性，将 Spring AI 模型配置为使用 MCP 客户端：
* 对于聊天模型：`spring.ai.mcp.chat.enabled=true`
* 对于嵌入模型：`spring.ai.mcp.embedding.enabled=true`
您还可以使用 `spring.ai.mcp.chat.options.*` 和 `spring.ai.mcp.embedding.options.*` 配置特定于模型的选项，例如模型名称。
示例 `application.properties` 以通过 MCP 使用远程聊天模型：
```properties theme={"system"}
spring.ai.mcp.client.base-url=http://mcp-server.example.com/mcp
spring.ai.mcp.chat.enabled=true
spring.ai.mcp.chat.options.model=remote-gpt-model # 在 MCP 服务器上配置的模型名称
# spring.ai.mcp.chat.options.temperature=0.7 # 其他模型选项
```
## 用法
配置完成后，您可以像使用任何其他 Spring AI 模型一样，将 `ChatModel` 或 `EmbeddingModel` 注入到您的服务中。MCP 客户端启动器确保这些模型通过 MCP 协议与配置的远程服务器进行通信。
### 使用 `ChatModel`
```java theme={"system"}
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class MyChatService {
private final ChatClient chatClient; // ChatClient 将使用配置的 MCP ChatModel
@Autowired
public MyChatService(ChatClient chatClient) {
this.chatClient = chatClient;
}
public String getChatResponse(String message) {
Prompt prompt = new Prompt(message);
ChatResponse response = chatClient.call(prompt);
return response.getResult().getOutput().getContent();
}
}
```
### 使用 `EmbeddingModel`
```java theme={"system"}
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class MyEmbeddingService {
private final EmbeddingClient embeddingClient; // EmbeddingClient 将使用配置的 MCP EmbeddingModel
@Autowired
public MyEmbeddingService(EmbeddingClient embeddingClient) {
this.embeddingClient = embeddingClient;
}
public List getEmbeddings(String text) {
return embeddingClient.embed(text);
}
}
```
## 请求和响应
客户端将自动将您的 `ChatModel` 或 `EmbeddingModel` 调用转换为 MCP 请求，并将 MCP 响应转换回标准的 Spring AI 对象 (`ChatResponse`, `EmbeddingResponse`)。
## 安全性
如果 MCP 服务器需要身份验证，请确保在客户端配置中提供必要的凭证 (例如，用户名/密码进行基本身份验证，或配置 OAuth2/JWT 的 `RestTemplate` 自定义器)。
启动器支持通过 `spring.ai.mcp.client.username` 和 `spring.ai.mcp.client.password` 属性进行基本身份验证。
对于更高级的身份验证方案，您可能需要提供一个自定义的 `RestTemplateBuilderConfigurer` bean 来自定义用于 MCP 通信的 `RestTemplate`。
```java theme={"system"}
@Bean
public RestTemplateBuilderConfigurer mcpRestTemplateBuilderConfigurer() {
return builder -> builder.additionalInterceptors(
// 添加您的自定义身份验证拦截器，例如用于 OAuth2 或 API 密钥头的拦截器
(request, body, execution) -> {
request.getHeaders().add("X-Custom-Auth-Header", "YourToken");
return execution.execute(request, body);
}
);
}
```
## 故障排除
* **连接错误**：验证 MCP 服务器的 `base-url` 是否正确，以及服务器是否可访问。
* **身份验证失败**：检查您的凭证或身份验证机制是否正确配置。
* **模型未找到**：确保您在客户端选项中指定的模型名称与 MCP 服务器上可用的模型匹配。
有关更多详细信息和高级配置，请参阅 Spring AI MCP [参考文档](https://docs.spring.io/spring-ai/reference/api/mcp.html) 和 [GitHub 仓库](https://github.com/spring-projects/spring-ai/tree/main/spring-ai-spring-boot-starters/spring-ai-mcp-client-spring-boot-starter)。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MCP 助手
Source: https://javaai.pig4cloud.com/spring-ai/api/mcp/mcp-helpers
# MCP 助手
Spring AI 提供了几个助手类来简化与模型上下文协议 (MCP) 的交互。
## `McpUtils`
`McpUtils` 类提供了一组实用方法，用于创建符合 MCP 规范的消息。
### 创建用户消息
你可以使用 `McpUtils.user()` 方法创建一个用户角色的消息：
```java theme={"system"}
import org.springframework.ai.model.content. யூserMessage;
import org.springframework.ai.mcp.McpUtils;
// ...
UserMessage userMessage = McpUtils.user("Tell me a joke about a cat."); // 示例提示内容通常保留英文
```
### 创建助手消息
你可以使用 `McpUtils.assistant()` 方法创建一个助手角色的消息：
```java theme={"system"}
import org.springframework.ai.model.content.AssistantMessage;
import org.springframework.ai.mcp.McpUtils;
// ...
AssistantMessage assistantMessage = McpUtils.assistant("Why was the cat sitting on the computer? To keep an eye on the mouse!"); // 示例提示内容通常保留英文
```
### 创建带工具调用的助手消息
你可以使用 `McpUtils.assistant()` 方法创建一个包含工具调用的助手消息：
```java theme={"system"}
import org.springframework.ai.model.content.AssistantMessage;
import org.springframework.ai.mcp.McpUtils;
import org.springframework.ai.model. யூserMessage;
import java.util.List;
// ...
AssistantMessage.ToolCall toolCall = new AssistantMessage.ToolCall("toolCallId", "weatherTool", "{\"location\": \"San Francisco\"}"); // 示例参数保留英文
AssistantMessage assistantMessageWithToolCall = McpUtils.assistant(List.of(toolCall));
```
### 创建带工具调用响应的工具消息
你可以使用 `McpUtils.tool()` 方法创建一个包含工具调用响应的工具消息：
```java theme={"system"}
import org.springframework.ai.model.content.ToolResponseMessage;
import org.springframework.ai.mcp.McpUtils;
import java.util.UUID;
// ...
String toolCallId = UUID.randomUUID().toString();
ToolResponseMessage toolResponseMessage = McpUtils.tool("The weather in San Francisco is sunny.", toolCallId, "weatherTool"); // 示例响应及参数保留英文
```
## `McpReason`
`McpReason` 类表示工具调用的原因。它帮助将工具调用请求与相应的工具调用响应关联起来。
### 创建 `McpReason`
你可以为工具调用请求创建一个 `McpReason`：
```java theme={"system"}
import org.springframework.ai.mcp.McpReason;
import org.springframework.ai.model.content.AssistantMessage;
// ...
AssistantMessage.ToolCall toolCall = new AssistantMessage.ToolCall("toolCallId", "calculatorTool", "{\"expression\": \"2 + 2\"}"); // 示例参数保留英文
McpReason reason = new McpReason(List.of(toolCall), null);
```
或者，你可以为工具调用响应创建一个 `McpReason`：
```java theme={"system"}
import org.springframework.ai.mcp.McpReason;
import org.springframework.ai.model.content.ToolResponseMessage;
import java.util.List;
// ...
ToolResponseMessage toolResponseMessage = new ToolResponseMessage("4", "toolCallId", "calculatorTool"); // 示例响应及参数保留英文
McpReason reason = new McpReason(null, List.of(toolResponseMessage));
```
## `McpRole`
`McpRole` 枚举定义了 MCP 消息中允许的角色：`USER`, `ASSISTANT`, 和 `TOOL`。
```java theme={"system"}
import org.springframework.ai.mcp.McpRole;
// ...
McpRole userRole = McpRole.USER;
McpRole assistantRole = McpRole.ASSISTANT;
McpRole toolRole = McpRole.TOOL;
```
## `McpMessage`
`McpMessage` 是 MCP 消息的基类。它包含消息的通用属性，如 `id`, `role`, `reason`, 和 `sequenceId`。
` யூserMessage`, `AssistantMessage`, 和 `ToolResponseMessage` 都扩展了 `McpMessage`。
### 消息内容
消息内容可以以多种格式提供，包括纯文本、模板化文本和多部分内容。
#### 纯文本内容
```java theme={"system"}
import org.springframework.ai.model.content. யூserMessage;
import org.springframework.ai.mcp.McpUtils;
// ...
UserMessage userMessage = McpUtils.user("What is the capital of France?"); // 示例提示内容通常保留英文
```
#### 模板化内容
你可以使用 `MessageBuilder` 来创建模板化内容：
```java theme={"system"}
import org.springframework.ai.mcp.McpMessage;
import org.springframework.ai.mcp.McpRole;
import org.springframework.ai.model. யூserMessage;
import org.springframework.ai.model.MessageBuilder;
import java.util.Map;
// ...
String template = "Tell me a joke about {animal}."; // 示例模板通常保留英文
Map model = Map.of("animal", "dog");
McpMessage templatedMessage = MessageBuilder.with रोल(McpRole.USER)
.withTemplate(template)
.withModel(model)
.build();
```
#### 多部分内容
多部分内容允许你在单个消息中组合不同类型的内容（例如，文本和图像）。
```java theme={"system"}
import org.springframework.ai.model.content.MultiPart யூserMessage;
import org.springframework.ai.model.content. யூserMessage;
import org.springframework.ai.model.Media;
import org.springframework.util.MimeTypeUtils;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.List;
// ...
MultiPartUserMessage multiPartUserMessage;
try {
multiPartUserMessage = new MultiPartUserMessage(
"What is in this image?", // 示例提示内容通常保留英文
List.of(new Media(MimeTypeUtils.IMAGE_PNG, new URI("https://example.com/image.png")))
);
} catch (URISyntaxException e) {
throw new RuntimeException(e);
}
```
## 总结
这些助手类旨在简化在 Spring AI 应用程序中构建和使用 MCP 消息的过程。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MCP 概述
Source: https://javaai.pig4cloud.com/spring-ai/api/mcp/mcp-overview
# 模型上下文协议 (MCP) 概述
模型上下文协议 (MCP) 为 AI 模型交互定义了一个标准化的消息传递格式。它促进了不同 AI 模型和平台之间的互操作性。
## 主要特性
* **标准化消息格式**：MCP 为请求、响应和错误消息定义了一个通用的结构。
* **模型无关**：该协议设计为可与各种类型的 AI 模型（例如，聊天模型、嵌入模型、图像模型）配合使用。
* **可扩展性**：MCP 允许添加自定义元数据和扩展，以支持特定用例。
* **互操作性**：通过遵守 MCP，不同的 AI 系统可以无缝通信。
## MCP 消息结构
一个典型的 MCP 消息包含以下组件：
* **标头 (Headers)**：包含元数据，如消息 ID、时间戳和模型信息。
* **正文 (Body)**：携带实际的有效载荷，如用户输入或模型输出。
* **上下文 (Context)**：提供有关对话历史或先前交互的附加信息。
## 用例
MCP 可以用于各种场景，包括：
* 在微服务架构中集成多个 AI 模型。
* 构建可与不同 AI 提供商互操作的应用程序。
* 标准化 AI 模型交互的日志记录和监控。
## Spring AI 中的 MCP 支持
Spring AI 为 MCP 提供了强大的支持，包括：
* [MCP 客户端启动器](./mcp-client-boot-starter-docs)：用于轻松与符合 MCP 的服务器集成。
* [MCP 服务器启动器](./mcp-server-boot-starter-docs)：用于构建符合 MCP 的服务器应用程序。
* [MCP 助手](./mcp-helpers)：用于创建和处理 MCP 消息的实用程序。
通过利用 Spring AI 的 MCP 功能，开发人员可以构建灵活且可互操作的 AI 驱动的应用程序。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MCP 服务器启动器文档
Source: https://javaai.pig4cloud.com/spring-ai/api/mcp/mcp-server-boot-starter-docs
# MCP 服务器启动器文档
Spring AI MCP 服务器启动器 (`spring-ai-mcp-server-boot-starter`) 简化了符合模型上下文协议 (MCP) 的服务器应用程序的创建。
## 概述
MCP 服务器启动器提供了：
* 自动配置 MCP 端点。
* 用于处理 MCP 请求的组件。
* 与 Spring Boot 应用程序的无缝集成。
## 入门
要开始使用 MCP 服务器启动器，请将以下依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-mcp-server-boot-starter
```
## 配置
MCP 服务器启动器可以通过 `application.properties` 或 `application.yml` 文件进行配置。以下是一些常见的配置选项：
### 服务器属性
* `spring.ai.mcp.server.enabled`: 启用或禁用 MCP 服务器 (默认为 `true`)。
* `spring.ai.mcp.server.path`: MCP API 端点的基础路径 (默认为 `/mcp`)。
* `spring.ai.mcp.server.port`: MCP 服务器监听的端口 (默认为应用程序的服务器端口)。
示例 `application.properties`：
```properties theme={"system"}
spring.ai.mcp.server.path=/api/mcp
```
### 模型配置
您需要配置您的 Spring AI 模型 (例如，ChatModel、EmbeddingModel)。MCP 服务器将使用这些已配置的模型来处理传入的请求。
确保您已按照各个模型文档中的说明配置了所需的模型 bean。
例如，要配置 OpenAI 聊天模型：
```properties theme={"system"}
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.chat.options.model=gpt-4o
```
## 用法
一旦配置完成，MCP 服务器启动器将自动暴露处理 MCP 请求所需的端点。
### MCP 端点
默认情况下，MCP 服务器在 `/mcp/v1/chat/completions` (对于聊天模型) 和 `/mcp/v1/embeddings` (对于嵌入模型) 上暴露端点。这些路径可以通过 `spring.ai.mcp.server.path` 属性进行自定义。
### 处理程序
启动器提供了 `McpChatHandler` 和 `McpEmbeddingHandler` 来处理相应的 MCP 请求。这些处理程序使用已配置的 Spring AI 模型与底层 AI 提供程序进行交互。
您可以自定义这些处理程序的行为，或者通过提供您自己的 `McpChatHandler` 或 `McpEmbeddingHandler` bean 来提供您自己的实现。
#### 自定义 `McpChatHandler`
```java theme={"system"}
@Bean
public McpChatHandler customMcpChatHandler(ChatModel chatModel) {
// 自定义逻辑
return new McpChatHandler(chatModel, new McpChatOptions(), null);
}
```
其中 `McpChatOptions` 可以包含特定于聊天的选项，如默认提示模板或后处理器。
### 请求和响应格式
服务器期望请求并以 MCP 指定的格式发送响应。有关详细信息，请参阅 MCP 规范。
## 示例：创建一个简单的 MCP 服务器
1. **添加依赖项**：如上所述，将 `spring-ai-mcp-server-boot-starter` 和模型特定的启动器 (例如，`spring-ai-openai-spring-boot-starter`) 添加到您的 `pom.xml` 中。
2. **配置属性**：在 `application.properties` 中配置您的 AI 模型凭证和可选的 MCP 服务器属性。
```properties theme={"system"}
# OpenAI 配置
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.chat.options.model=gpt-4o
# MCP 服务器配置 (可选)
# spring.ai.mcp.server.path=/custom-mcp-path
```
3. **运行应用程序**：启动您的 Spring Boot 应用程序。
MCP 服务器现在应该正在运行并准备好在配置的路径上处理 MCP 请求。
## 安全性
保护您的 MCP 端点非常重要。考虑使用 Spring Security 或其他身份验证/授权机制来保护您的 API。
以下是使用 Spring Security 进行基本身份验证的简单示例：
1. 添加 Spring Security 依赖项：
```xml theme={"system"}
org.springframework.boot
spring-boot-starter-security
```
2. 配置安全规则：
```java theme={"system"}
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(authorizeRequests ->
authorizeRequests
.requestMatchers("/mcp/**").authenticated() // 保护 MCP 端点
.anyRequest().permitAll()
)
.httpBasic(withDefaults());
return http.build();
}
@Bean
public InMemoryUserDetailsManager userDetailsService() {
UserDetails user = User.withDefaultPasswordEncoder()
.username("user")
.password("password")
.roles("USER")
.build();
return new InMemoryUserDetailsManager(user);
}
}
```
上述安全配置仅为示例。对于生产环境，请实施更强大的安全措施。
## 故障排除
* **404 未找到**：验证 MCP 端点路径是否正确配置，并且您的应用程序是否正在运行。
* **身份验证错误**：确保您的 AI 模型凭证正确无误且具有必要的权限。
* **依赖项冲突**：检查您的 `pom.xml` 是否存在可能导致问题的冲突依赖项。
有关更多详细信息和高级配置，请参阅 Spring AI MCP [参考文档](https://docs.spring.io/spring-ai/reference/api/mcp.html) 和 [GitHub 仓库](https://github.com/spring-projects/spring-ai/tree/main/spring-ai-spring-boot-starters/spring-ai-mcp-server-spring-boot-starter)。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 内容审核模型
Source: https://javaai.pig4cloud.com/spring-ai/api/moderation
本节介绍 Spring AI 中可用的内容审核模型。
## OpenAI 内容审核
OpenAI 的内容审核模型，用于检测潜在有害内容
## Mistral AI 内容审核
Mistral AI 的内容审核功能
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Mistral AI 内容审核
Source: https://javaai.pig4cloud.com/spring-ai/api/moderation/mistral-ai-moderation
Spring AI 中的 Mistral AI 内容审核功能使用 Mistral AI 的审核模型提供内容审核能力。
## 概述
Mistral AI 内容审核能够：
* 高级内容过滤
* 多语言支持
* 自定义审核规则
* 实时内容分析
## 功能
深度内容分析
支持多种语言
可自定义审核规则
实时内容审核
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-mistral-moderation
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Mistral AI 内容审核配置
spring.ai.mistral.moderation.enabled=true
spring.ai.mistral.moderation.api-key=${MISTRAL_API_KEY}
spring.ai.mistral.moderation.model=mistral-moderation
```
### 用法
```java theme={"system"}
@Service
public class MistralModerationService {
private final MistralModerationClient moderationClient;
public MistralModerationService(MistralModerationClient moderationClient) {
this.moderationClient = moderationClient;
}
public ModerationResult moderateContent(String content) {
return moderationClient.moderate(content);
}
}
```
## 审核功能
### 1. 基本审核
```java theme={"system"}
@Configuration
public class MistralModerationConfig {
@Bean
public ModerationClient mistralModerationClient(MistralModerationProperties properties) {
return new MistralModerationClient(properties);
}
}
```
### 2. 特定语言审核
```java theme={"system"}
@Configuration
public class LanguageModerationConfig {
@Bean
public ModerationClient languageModerationClient(MistralModerationProperties properties) {
return ModerationClient.builder()
.properties(properties)
.languages(Arrays.asList("en", "fr", "es"))
.build();
}
}
```
### 3. 自定义审核规则
```java theme={"system"}
@Configuration
public class CustomModerationConfig {
@Bean
public ModerationClient customModerationClient(MistralModerationProperties properties) {
return ModerationClient.builder()
.properties(properties)
.rules(customRules())
.build();
}
private List customRules() {
return Arrays.asList(
new ModerationRule("hate", 0.7),
new ModerationRule("harassment", 0.6),
new ModerationRule("violence", 0.8)
);
}
}
```
## 高级功能
### 自定义审核逻辑
```java theme={"system"}
@Component
public class CustomModerationLogic implements ModerationLogic {
@Override
public ModerationResult process(String content) {
// 自定义审核逻辑
return result;
}
@Override
public boolean isAllowed(ModerationResult result) {
// 自定义允许逻辑
return allowed;
}
}
```
### 审核监控
```properties theme={"system"}
management.endpoints.web.exposure.include=mistral-moderation
management.endpoint.mistral-moderation.enabled=true
```
## 最佳实践
使用 Mistral AI 内容审核时，请考虑以下最佳实践：
* **API 安全**：保护您的 API 密钥
* **错误处理**：实现稳健的错误处理
* **速率限制**：监控 API 使用情况
* **语言支持**：配置适当的语言
* **规则管理**：维护清晰的审核规则
## 故障排除
常见问题和解决方案：
1. **API 问题**
* 验证 API 密钥
* 检查 API 限制
* 查看错误消息
2. **语言问题**
* 验证语言支持
* 检查语言检测
* 查看语言设置
3. **性能问题**
* 优化请求频率
* 实现缓存
* 使用批处理
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OpenAI 内容审核
Source: https://javaai.pig4cloud.com/spring-ai/api/moderation/openai-moderation
Spring AI 中的 OpenAI 内容审核功能使用 OpenAI 的审核模型提供内容审核能力。
## 概述
OpenAI 内容审核能够：
* 内容安全检查
* 有害内容检测
* 策略合规性验证
* 自动化内容过滤
## 功能
检测有害或不当内容
验证内容是否符合策略
检查多个内容类别
实时内容审核
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-moderation
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# OpenAI 内容审核配置
spring.ai.openai.moderation.enabled=true
spring.ai.openai.moderation.api-key=${OPENAI_API_KEY}
spring.ai.openai.moderation.model=text-moderation-latest
```
### 用法
```java theme={"system"}
@Service
public class ContentModerationService {
private final OpenAIModerationClient moderationClient;
public ContentModerationService(OpenAIModerationClient moderationClient) {
this.moderationClient = moderationClient;
}
public ModerationResult moderateContent(String content) {
return moderationClient.moderate(content);
}
}
```
## 审核类别
### 1. 基本审核
```java theme={"system"}
@Configuration
public class ModerationConfig {
@Bean
public ModerationClient moderationClient(OpenAIModerationProperties properties) {
return new OpenAIModerationClient(properties);
}
}
```
### 2. 自定义类别
```java theme={"system"}
@Configuration
public class CustomModerationConfig {
@Bean
public ModerationClient customModerationClient(OpenAIModerationProperties properties) {
return ModerationClient.builder()
.properties(properties)
.categories(Arrays.asList("hate", "harassment", "self-harm"))
.build();
}
}
```
### 3. 基于阈值的审核
```java theme={"system"}
@Configuration
public class ThresholdModerationConfig {
@Bean
public ModerationClient thresholdModerationClient(OpenAIModerationProperties properties) {
return ModerationClient.builder()
.properties(properties)
.threshold(0.7)
.build();
}
}
```
## 高级功能
### 自定义审核规则
```java theme={"system"}
@Component
public class CustomModerationRules implements ModerationRules {
@Override
public boolean isAllowed(ModerationResult result) {
return result.getHateScore() < 0.5 &&
result.getHarassmentScore() < 0.5 &&
result.getSelfHarmScore() < 0.5;
}
}
```
### 审核监控
```properties theme={"system"}
management.endpoints.web.exposure.include=openai-moderation
management.endpoint.openai-moderation.enabled=true
```
## 最佳实践
使用 OpenAI 内容审核时，请考虑以下最佳实践：
* **API 密钥安全**：保护您的 API 密钥
* **错误处理**：实现适当的错误处理
* **速率限制**：监控 API 使用情况
* **内容过滤**：定义清晰的内容策略
* **监控**：跟踪审核结果
## 故障排除
常见问题和解决方案：
1. **API 问题**
* 检查 API 密钥
* 验证 API 限制
* 查看错误响应
2. **性能问题**
* 优化请求频率
* 实现缓存
* 使用批处理
3. **内容问题**
* 查看审核阈值
* 更新内容策略
* 监控误报
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 多模态 API
Source: https://javaai.pig4cloud.com/spring-ai/api/multimodality
> "所有与自然相关的事物都应该结合起来教授" - John Amos Comenius, "Orbis Sensualium Pictus", 1658
人类同时通过多种数据输入模式处理知识。
我们学习的方式、我们的经历都是多模态的。
我们不仅仅有视觉、音频和文本。
与这些原则相反，机器学习往往专注于处理单一模态的专门模型。
例如，我们开发了用于文本到语音或语音到文本等任务的音频模型，以及用于对象检测和分类等任务的计算机视觉模型。
然而，新一代的多模态大型语言模型开始出现。
例如，OpenAI 的 GPT-4o、Google 的 Vertex AI Gemini 1.5、Anthropic 的 Claude3，以及开源产品 Llama3.2、LLaVA 和 BakLLaVA 都能够接受多种输入，包括文本图像、音频和视频，并通过整合这些输入生成文本响应。
多模态大型语言模型（LLM）功能使模型能够处理文本并结合其他模态（如图像、音频或视频）生成文本。
## Spring AI 多模态
多模态指的是模型同时理解和处理来自各种来源的信息的能力，包括文本、图像、音频和其他数据格式。
Spring AI Message API 提供了支持多模态 LLM 所需的所有抽象。
![]()
UserMessage 的 `content` 字段主要用于文本输入，而可选的 `media` 字段允许添加一个或多个不同模态的额外内容，如图像、音频和视频。
`MimeType` 指定模态类型。
根据使用的 LLM，`Media` 数据字段可以是作为 `Resource` 对象的原始媒体内容，也可以是内容的 `URI`。
media 字段目前仅适用于用户输入消息（例如，`UserMessage`）。它对系统消息没有意义。包含 LLM 响应的 `AssistantMessage` 仅提供文本内容。要生成非文本媒体输出，您应该使用专门的单模态模型之一。
例如，我们可以将以下图片（`multimodal.test.png`）作为输入，并要求 LLM 解释它看到的内容。
![]()
对于大多数多模态 LLM，Spring AI 代码如下所示：
```java theme={"system"}
var imageResource = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage(
"解释你在这张图片中看到了什么？", // content
new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource)); // media
ChatResponse response = chatModel.call(new Prompt(this.userMessage));
```
或使用流畅的 [ChatClient](/spring4ai/api/chatclient) API：
```java theme={"system"}
String response = ChatClient.create(chatModel).prompt()
.user(u -> u.text("解释你在这张图片上看到了什么？")
.media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/multimodal.test.png")))
.call()
.content();
```
并产生如下响应：
> 这是一张设计简单的水果碗图片。碗由金属制成，边缘是弯曲的金属丝，形成一个开放式结构，可以从各个角度看到水果。碗里有两个黄色的香蕉放在一个红色的苹果上面。香蕉略微过熟，可以从果皮上的棕色斑点看出。碗的顶部有一个金属环，可能是用来提携的把手。碗放在一个平面上，背景是中性色，可以清楚地看到碗里的水果。
## 支持的多模态模型
Spring AI 为以下聊天模型提供多模态支持：
支持图像输入进行分析和推理
亚马逊的多模态对话 AI 服务
支持 GPT-4o 和其他多模态模型
具有图像理解能力的 Mistral Pixtral 模型
支持开源多模态模型，如 LLaVA、BakLLaVA 和 Llama3.2
具有视觉能力的 GPT-4 和 GPT-4o 模型
具有多模态能力的 Google Gemini 模型（gemini-1.5-pro-001、gemini-1.5-flash-001）
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 提示词
Source: https://javaai.pig4cloud.com/spring-ai/api/prompt
提示是引导 AI 模型生成特定输出的输入。
提示的设计和措辞会显著影响模型的响应。
在 Spring AI 中与 AI 模型交互的最低层级，处理提示有点类似于在 Spring MVC 中管理"视图"。
这涉及创建带有动态内容占位符的大段文本。
这些占位符随后会根据用户请求或应用程序中的其他代码进行替换。
另一个类比是包含某些表达式占位符的 SQL 语句。
随着 Spring AI 的发展，它将引入更高级别的与 AI 模型交互的抽象。
本节描述的基础类在其角色和功能上可以类比为 JDBC。
例如，`ChatModel` 类类似于 JDK 中的核心 JDBC 库。
`ChatClient` 类类似于 `JdbcClient`，它构建在 `ChatModel` 之上，并通过 `Advisor` 提供更高级的构造，能够考虑与模型的历史交互、用额外的上下文文档增强提示，并引入代理行为。
提示的结构在 AI 领域内随着时间的推移而演变。
最初，提示只是简单的字符串。
随着时间的推移，它们发展为包含特定输入占位符，如"USER:"，AI 模型能够识别。
OpenAI 通过在处理前将多条消息字符串分类为不同角色，为提示引入了更多结构。
## API 概述
### Prompt
通常会使用 `ChatModel` 的 `call()` 方法，该方法接受一个 `Prompt` 实例并返回一个 `ChatResponse`。
`Prompt` 类作为有序 `Message` 对象序列和请求 `ChatOptions` 的容器。
每个 `Message` 在提示中都具有独特的角色，内容和意图各不相同。
这些角色可以包含多种元素，从用户提问到 AI 生成的响应，再到相关的背景信息。
这种安排使与 AI 模型的交互变得复杂且详细，因为提示由多个消息构建，每个消息在对话中扮演特定角色。
下面是 Prompt 类的简化版本，省略了构造函数和工具方法：
```java theme={"system"}
public class Prompt implements ModelRequest> {
private final List messages;
private ChatOptions chatOptions;
}
```
### Message
`Message` 接口封装了提示的文本内容、元数据属性集合和称为 `MessageType` 的分类。
接口定义如下：
```java theme={"system"}
public interface Content {
String getContent();
Map getMetadata();
}
public interface Message extends Content {
MessageType getMessageType();
}
```
多模态消息类型还实现了 `MediaContent` 接口，提供 `Media` 内容对象列表。
```java theme={"system"}
public interface MediaContent extends Content {
Collection getMedia();
}
```
`Message` 接口有多种实现，对应于 AI 模型可以处理的不同类别的消息。
模型根据对话角色区分消息类别。
![]()
这些角色由 `MessageType` 有效映射，如下所述。
#### 角色
每条消息都被分配了一个特定角色。
这些角色对消息进行分类，为 AI 模型澄清每个提示片段的上下文和目的。
这种结构化方法增强了与 AI 的交流的细致性和有效性，因为提示的每一部分在交互中都扮演着独特且明确定义的角色。
指导 AI 的行为和响应风格，设置参数或规则，规定 AI 如何解释和回复输入。类似于在开始对话前为 AI 提供指令。
代表用户的输入——他们对 AI 的问题、命令或陈述。这个角色是基础，因为它构成了 AI 响应的依据。
AI 对用户输入的响应。不仅仅是答案或反应，对于维持对话的流畅性至关重要。
通过跟踪 AI 先前的响应（其"助手角色"消息），系统确保交互的连贯性和上下文相关性。
助手消息还可能包含函数工具调用请求信息。
这就像 AI 的一个特殊功能，在需要时用于执行特定功能，如计算、获取数据或其他超出对话的任务。
工具/函数角色专注于响应工具调用助手消息时返回额外信息。
角色在 Spring AI 中以枚举方式表示，如下所示：
```java theme={"system"}
public enum MessageType {
USER("user"),
ASSISTANT("assistant"),
SYSTEM("system"),
TOOL("tool");
...
}
```
### PromptTemplate
Spring AI 中提示模板的关键组件是 `PromptTemplate` 类，旨在便于创建结构化提示，然后将其发送给 AI 模型进行处理。
```java theme={"system"}
public class PromptTemplate implements PromptTemplateActions, PromptTemplateMessageActions {
// 其他方法后续讨论
}
```
该类使用 `TemplateRenderer` API 渲染模板。默认情况下，Spring AI 使用基于 Terence Parr 开发的开源 [StringTemplate](https://www.stringtemplate.org/) 引擎的 `StTemplateRenderer` 实现。模板变量由 `{}` 语法标识，但您也可以配置分隔符以使用其他语法。
```java theme={"system"}
public interface TemplateRenderer extends BiFunction, String> {
@Override
String apply(String template, Map variables);
}
```
Spring AI 使用 `TemplateRenderer` 接口处理变量到模板字符串的实际替换。
默认实现使用 StringTemplate。
如果需要自定义逻辑，您可以提供自己的 `TemplateRenderer` 实现。
对于不需要模板渲染的场景（例如模板字符串已完整），可以使用提供的 `NoOpTemplateRenderer`。
```java theme={"system"}
PromptTemplate promptTemplate = PromptTemplate.builder()
.renderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
.template("""
告诉我 5 部由 作曲的电影名称。
""")
.build();
String prompt = promptTemplate.render(Map.of("composer", "John Williams"));
```
该类实现的接口支持提示创建的不同方面：
* `PromptTemplateStringActions` 专注于创建和渲染提示字符串，代表最基本的提示生成形式。
* `PromptTemplateMessageActions` 针对通过生成和操作 `Message` 对象进行提示创建。
* `PromptTemplateActions` 旨在返回 `Prompt` 对象，可传递给 `ChatModel` 以生成响应。
虽然这些接口在许多项目中可能不会被广泛使用，但它们展示了提示创建的不同方法。
实现的接口如下：
```java theme={"system"}
public interface PromptTemplateStringActions {
String render();
String render(Map model);
}
```
* `String render()`：将提示模板渲染为最终字符串格式，无需外部输入，适用于无占位符或动态内容的模板。
* `String render(Map model)`：增强渲染功能以包含动态内容。它使用 `Map`，其中 map 的键是提示模板中的占位符名称，值是要插入的动态内容。
```java theme={"system"}
public interface PromptTemplateMessageActions {
Message createMessage();
Message createMessage(List mediaList);
Message createMessage(Map model);
}
```
* `Message createMessage()`：创建不带附加数据的 `Message` 对象，用于静态或预定义的消息内容。
* `Message createMessage(List mediaList)`：创建带有静态文本和媒体内容的 `Message` 对象。
* `Message createMessage(Map model)`：扩展消息创建以集成动态内容，接受 `Map`，每个条目代表消息模板中的占位符及其对应的动态值。
```java theme={"system"}
public interface PromptTemplateActions extends PromptTemplateStringActions {
Prompt create();
Prompt create(ChatOptions modelOptions);
Prompt create(Map model);
Prompt create(Map model, ChatOptions modelOptions);
}
```
* `Prompt create()`：生成不带外部数据输入的 `Prompt` 对象，适用于静态或预定义的提示。
* `Prompt create(ChatOptions modelOptions)`：生成不带外部数据输入且带有特定聊天请求选项的 `Prompt` 对象。
* `Prompt create(Map model)`：扩展提示创建能力以包含动态内容，接受 `Map`，每个 map 条目是提示模板中的占位符及其关联的动态值。
* `Prompt create(Map model, ChatOptions modelOptions)`：扩展提示创建能力以包含动态内容，接受 `Map`，每个 map 条目是提示模板中的占位符及其关联的动态值，并带有特定的聊天请求选项。
## 示例用法
以下是 [AI Workshop on PromptTemplates](https://github.com/Azure-Samples/spring-ai-azure-workshop/blob/main/2-README-prompt-templating.md) 中的一个简单示例。
```java theme={"system"}
PromptTemplate promptTemplate = new PromptTemplate("Tell me a {adjective} joke about {topic}");
Prompt prompt = promptTemplate.create(Map.of("adjective", adjective, "topic", topic));
return chatModel.call(prompt).getResult();
```
另一个示例来自 [AI Workshop on Roles](https://github.com/Azure-Samples/spring-ai-azure-workshop/blob/main/3-README-prompt-roles.md)：
```java theme={"system"}
String userText = """
告诉我三位黄金时代著名海盗以及他们为什么出名。
每位海盗至少写一句话。
""";
```
## 提示工程
在生成 AI 中，提示的创建是开发人员的重要任务。
提示的质量和结构会显著影响 AI 的输出效果。
在设计提示上投入时间和精力可以大大提高 AI 的结果。
分享和讨论提示是 AI 社区中的常见做法。
这种协作方法不仅创造了共享学习环境，还导致了高度有效提示的识别和使用。
该领域的研究通常涉及分析和比较不同的提示，以评估它们在各种情况下的有效性。
例如，一项重大研究证明，从"Take a deep breath and work on this problem step by step"开始，问题解决效率显著提高。
这强调了语言选择对生成 AI 系统性能的影响。
掌握提示的最佳使用，特别是在 AI 技术快速发展的情况下，是一个持续的挑战。
你应该认识到提示工程的重要性，并考虑使用社区和研究中的见解来改进提示创建策略。
### 创建有效提示
在开发提示时，重要的是整合几个关键组件，以确保清晰和有效性：
Offer clear and direct instructions to the AI, similar to how you would communicate with a person. This clarity is essential for helping the AI "understand" what is expected.
Include relevant background information or specific guidance for the AI's response when necessary. This "external context" frames the prompt and aids the AI in grasping the overall scenario.
This is the straightforward part - the user's direct request or question forming the core of the prompt.
This aspect can be tricky. It involves specifying the desired format for the AI's response, such as JSON. However, be aware that the AI might not always adhere strictly to this format. For instance, it might prepend a phrase like "here is your JSON" before the actual JSON data, or sometimes generate a JSON-like structure that is not accurate.
提供 AI 预期的提问和答案格式示例可以极大地帮助在创建提示时。
这种做法帮助 AI "理解"查询的结构和意图，导致更精确和相关的响应。
虽然此文档不会深入探讨这些技术，但它们为 AI 提示工程提供了起点。
以下是进一步调查的资源列表。
#### Simple Techniques
Reduces extensive text into concise summaries, capturing key points and main ideas while omitting less critical details.
Focuses on deriving specific answers from provided text, based on user-posed questions. It's about pinpointing and extracting relevant information in response to queries.
Systematically categorizes text into predefined categories or groups, analyzing the text and assigning it to the most fitting category based on its content.
Creates interactive dialogues where the AI can engage in back-and-forth communication with users, simulating a natural conversation flow.
Generates functional code snippets based on specific user requirements or descriptions, translating natural language instructions into executable code.
#### Advanced Techniques
Enables the model to make accurate predictions or responses with minimal to no prior examples of the specific problem type, understanding and acting on new tasks using learned generalizations.
Links multiple AI responses to create a coherent and contextually aware conversation. It helps the AI maintain the thread of the discussion, ensuring relevance and continuity.
In this method, the AI first analyzes (reasons about) the input, then determines the most appropriate course of action or response. It combines understanding with decision-making.
#### Microsoft Guidance
Microsoft offers a structured approach to developing and refining prompts. This framework guides users in creating effective prompts that elicit the desired responses from AI models, optimizing the interaction for clarity and efficiency.
## Tokens
Tokens 在 AI 模型处理文本中起着关键作用，它们充当中介，将我们理解的单词转换为 AI 模型可以处理的格式。
这种转换发生在两个阶段：单词在输入时转换为 tokens，然后这些 tokens 再转换回单词输出。
Tokenization，将文本分解为 tokens 的过程，是 AI 模型理解和处理语言的基础。
AI 模型使用这种 tokenized 格式来理解和响应提示。
为了更好地理解 tokens，可以将其视为单词的一部分。通常，一个 token 代表大约三个四分之一单词。例如，莎士比亚的完整作品，总计约 900,000 个单词，将翻译为约 120 万个 tokens。
实验使用 [OpenAI Tokenizer UI](https://platform.openai.com/tokenizer) 查看单词如何转换为 tokens。
Tokens 在 AI 处理中的实际含义超出了它们的技术角色，特别是在与计费和模型能力相关：
AI 模型服务通常根据 token 使用量计费。输入（提示）和输出（响应）都贡献到总 token 计数中，使较短的提示更经济。
Different AI 模型具有不同的 token 限制，定义它们的 "context window" ——它们一次可以处理的最大信息量。例如，GPT-3 限制为 4K tokens，而其他模型如 Claude 2 和 Meta Llama 2 限制为 100K tokens，一些研究模型可以处理高达 100 万个 tokens。
A model's token limit determines its context window。如果输入超过此限制，模型不会处理输入。为了处理，只需发送最小有效信息集。例如，在询问 "Hamlet" 时，没有必要包括莎士比亚其他作品的 tokens。
来自 AI 模型的响应的元数据包括使用的 token 数量，对于管理使用和成本至关重要。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 检索增强生成 (RAG)
Source: https://javaai.pig4cloud.com/spring-ai/api/retrieval-augmented-generation
检索增强生成 (RAG) 结合了基于检索和基于生成的方法的优势，以提供增强的 AI 响应。
## ETL 管道
用于为 RAG 系统准备数据的提取、转换、加载管道
RAG 系统结合了基于检索和基于生成的方法的优势，以提供更准确和上下文相关的响应。
## 关键组件
* **检索**：从知识库中查找相关信息
* **增强**：用检索到的信息增强上下文
* **生成**：基于增强的上下文创建响应
## 优势
* 提高响应的准确性和相关性
* 更好地处理特定领域的知识
* 减少生成内容中的幻觉
* 增强上下文感知能力
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 结构化输出转换器
Source: https://javaai.pig4cloud.com/spring-ai/api/structured-output-converter
截至 2024 年 2 月 5 日，旧的 `OutputParser`、`BeanOutputParser`、`ListOutputParser` 和 `MapOutputParser` 类已被弃用，取而代之的是新的 `StructuredOutputConverter`、`BeanOutputConverter`、`ListOutputConverter` 和 `MapOutputConverter` 实现。
后者是前者的直接替代品，提供相同的功能。更改的原因主要是命名，因为没有进行任何解析，同时也与 Spring `org.springframework.core.convert.converter` 包保持一致，带来了一些改进的功能。
LLM 生成结构化输出的能力对于依赖可靠解析输出值的下游应用程序很重要。
开发人员希望快速将 AI 模型的结果转换为可以传递给其他应用程序函数和方法的数据类型，如 JSON、XML 或 Java 类。
Spring AI `Structured Output Converters` 帮助将 LLM 输出转换为结构化格式。
如下图所示，这种方法围绕 LLM 文本完成端点运行：
![]()
使用通用完成 API 从大型语言模型 (LLM) 生成结构化输出需要仔细处理输入和输出。结构化输出转换器在 LLM 调用前后都起着关键作用，确保实现所需的输出结构。
在 LLM 调用之前，转换器将格式指令附加到提示中，为模型提供明确的指导，以生成所需的输出结构。这些指令作为蓝图，塑造模型的响应以符合指定的格式。
在 LLM 调用之后，转换器获取模型的输出文本并将其转换为结构化类型的实例。这个转换过程涉及解析原始文本输出并将其映射到相应的结构化数据表示，如 JSON、XML 或特定领域的数据结构。
`StructuredOutputConverter` 是尽最大努力将模型输出转换为结构化输出。
AI 模型不能保证按照请求返回结构化输出。
模型可能不理解提示或无法生成请求的结构化输出。
考虑实现验证机制以确保模型输出符合预期。
`StructuredOutputConverter` 不用于 LLM [工具调用](/spring4ai/api/tools)，因为此功能默认提供结构化输出。
## 结构化输出 API
`StructuredOutputConverter` 接口允许您获取结构化输出，例如将输出映射到 Java 类或从基于文本的 AI 模型输出中获取值数组。
接口定义如下：
```java theme={"system"}
public interface StructuredOutputConverter extends Converter, FormatProvider {
}
```
它结合了 Spring [Converter](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/convert/converter/Converter.html) 接口和 FormatProvider 接口
```java theme={"system"}
public interface FormatProvider {
String getFormat();
}
```
下图显示了使用结构化输出 API 时的数据流。
![]()
`FormatProvider` 为 AI 模型提供特定的格式指南，使其能够生成可以转换为指定目标类型 `T` 的文本输出。以下是此类格式指令的示例：
```
您的响应应该是 JSON 格式。
JSON 的数据结构应该匹配这个 Java 类：java.util.HashMap
不要包含任何解释，只提供符合此格式的 RFC8259 兼容 JSON 响应，不要有任何偏差。
```
格式指令通常使用 [PromptTemplate](/spring4ai/api/prompt#prompttemplate) 附加到用户输入的末尾，如下所示：
```java theme={"system"}
StructuredOutputConverter outputConverter = ...
String userInputTemplate = """
... 用户文本输入 ....
{format}
"""; // 带有 "format" 占位符的用户输入。
Prompt prompt = new Prompt(
new PromptTemplate(
this.userInputTemplate,
Map.of(..., "format", outputConverter.getFormat()) // 用转换器的格式替换 "format" 占位符。
).createMessage());
```
转换器负责将模型的输出文本转换为指定类型 `T` 的实例。
### 可用的转换器
目前，Spring AI 提供了 `AbstractConversionServiceOutputConverter`、`AbstractMessageOutputConverter`、`BeanOutputConverter`、`MapOutputConverter` 和 `ListOutputConverter` 实现：
![]()
提供预配置的 [GenericConversionService](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/convert/support/GenericConversionService.html) 用于将 LLM 输出转换为所需格式。不提供默认的 `FormatProvider` 实现。
提供预配置的 [MessageConverter](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/jms/support/converter/MessageConverter.html) 用于将 LLM 输出转换为所需格式。不提供默认的 `FormatProvider` 实现。
配置有指定的 Java 类（例如，Bean）或 [ParameterizedTypeReference](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/ParameterizedTypeReference.html)，此转换器使用 `FormatProvider` 实现，指导 AI 模型生成符合从指定 Java 类派生的 `DRAFT_2020_12`、`JSON Schema` 的 JSON 响应。随后，它使用 `ObjectMapper` 将 JSON 输出反序列化为目标类的 Java 对象实例。
扩展 `AbstractMessageOutputConverter` 的功能，提供 `FormatProvider` 实现，指导 AI 模型生成符合 RFC8259 的 JSON 响应。此外，它还包含一个转换器实现，使用提供的 `MessageConverter` 将 JSON 负载转换为 `java.util.Map` 实例。
扩展 `AbstractConversionServiceOutputConverter` 并包含一个 `FormatProvider` 实现，专为逗号分隔的列表输出而设计。转换器实现使用提供的 `ConversionService` 将模型文本输出转换为 `java.util.List`。
## 使用转换器
以下部分提供了如何使用可用转换器生成结构化输出的指南。
### Bean 输出转换器
以下示例显示如何使用 `BeanOutputConverter` 生成演员的电影作品。
表示演员电影作品的目标记录：
```java theme={"system"}
record ActorsFilms(String actor, List movies) {
}
```
以下是使用高级、流畅的 `ChatClient` API 应用 BeanOutputConverter 的方法：
```java theme={"system"}
ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
.user(u -> u.text("为 {actor} 生成 5 部电影的电影作品。")
.param("actor", "Tom Hanks"))
.call()
.entity(ActorsFilms.class);
```
或直接使用低级 `ChatModel` API：
```java theme={"system"}
BeanOutputConverter beanOutputConverter =
new BeanOutputConverter<>(ActorsFilms.class);
String format = this.beanOutputConverter.getFormat();
String actor = "Tom Hanks";
String template = """
为 {actor} 生成 5 部电影的电影作品。
{format}
""";
Generation generation = chatModel.call(
new PromptTemplate(this.template, Map.of("actor", this.actor, "format", this.format)).create()).getResult();
ActorsFilms actorsFilms = this.beanOutputConverter.convert(this.generation.getOutput().getText());
```
### 生成模式中的属性排序
`BeanOutputConverter` 通过 `@JsonPropertyOrder` 注解支持在生成的 JSON 模式中进行自定义属性排序。
此注解允许您指定属性在模式中出现的确切顺序，无论它们在类或记录中的声明顺序如何。
例如，要确保 `ActorsFilms` 记录中的属性特定排序：
```java theme={"system"}
@JsonPropertyOrder({"actor", "movies"})
record ActorsFilms(String actor, List movies) {}
```
此注解适用于记录和常规 Java 类。
#### 泛型 Bean 类型
使用 `ParameterizedTypeReference` 构造函数指定更复杂的目标类结构。
例如，要表示演员及其电影作品列表：
```java theme={"system"}
List actorsFilms = ChatClient.create(chatModel).prompt()
.user("为 Tom Hanks 和 Bill Murray 生成 5 部电影的电影作品。")
.call()
.entity(new ParameterizedTypeReference>() {});
```
或直接使用低级 `ChatModel` API：
```java theme={"system"}
BeanOutputConverter> outputConverter = new BeanOutputConverter<>(
new ParameterizedTypeReference>() { });
String format = this.outputConverter.getFormat();
String template = """
为 Tom Hanks 和 Bill Murray 生成 5 部电影的电影作品。
{format}
""";
Prompt prompt = new PromptTemplate(this.template, Map.of("format", this.format)).create();
Generation generation = chatModel.call(this.prompt).getResult();
List actorsFilms = this.outputConverter.convert(this.generation.getOutput().getText());
```
### Map 输出转换器
以下代码片段显示如何使用 `MapOutputConverter` 将模型输出转换为地图中的数字列表。
```java theme={"system"}
Map result = ChatClient.create(chatModel).prompt()
.user(u -> u.text("为我提供一个 {subject}")
.param("subject", "一个从 1 到 9 的数字数组，键名为 'numbers'"))
.call()
.entity(new ParameterizedTypeReference>() {});
```
或直接使用低级 `ChatModel` API：
```java theme={"system"}
MapOutputConverter mapOutputConverter = new MapOutputConverter();
String format = this.mapOutputConverter.getFormat();
String template = """
为我提供一个 {subject}
{format}
""";
Prompt prompt = new PromptTemplate(this.template,
Map.of("subject", "一个从 1 到 9 的数字数组，键名为 'numbers'", "format", this.format)).create();
Generation generation = chatModel.call(this.prompt).getResult();
Map result = this.mapOutputConverter.convert(this.generation.getOutput().getText());
```
### List 输出转换器
以下代码片段显示如何使用 `ListOutputConverter` 将模型输出转换为冰淇淋口味列表。
```java theme={"system"}
List flavors = ChatClient.create(chatModel).prompt()
.user(u -> u.text("列出五种 {subject}")
.param("subject", "冰淇淋口味"))
.call()
.entity(new ListOutputConverter(new DefaultConversionService()));
```
或直接使用低级 `ChatModel API`：
```java theme={"system"}
ListOutputConverter listOutputConverter = new ListOutputConverter(new DefaultConversionService());
String format = this.listOutputConverter.getFormat();
String template = """
列出五种 {subject}
{format}
""";
Prompt prompt = new PromptTemplate(this.template,
Map.of("subject", "冰淇淋口味", "format", this.format)).create();
Generation generation = this.chatModel.call(this.prompt).getResult();
List list = this.listOutputConverter.convert(this.generation.getOutput().getText());
```
## 支持的 AI 模型
以下 AI 模型已经过测试，支持 List、Map 和 Bean 结构化输出。
[查看测试](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/OpenAiChatModelIT.java)
[查看测试](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-anthropic/src/test/java/org/springframework/ai/anthropic/AnthropicChatModelIT.java)
[查看测试](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-azure-openai/src/test/java/org/springframework/ai/azure/openai/AzureOpenAiChatModelIT.java)
[查看测试](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-mistral-ai/src/test/java/org/springframework/ai/mistralai/MistralAiChatModelIT.java)
[查看测试](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/test/java/org/springframework/ai/ollama/OllamaChatModelIT.java)
[查看测试](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-vertex-ai-gemini/src/test/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModelIT.java)
## 内置 JSON 模式
一些 AI 模型提供专门的配置选项来生成结构化（通常是 JSON）输出。
[OpenAI 结构化输出](/spring4ai/api/chat/openai-chat#structured-outputs) 可以确保您的模型生成严格符合您提供的 JSON Schema 的响应。您可以选择 `JSON_OBJECT`，它保证模型生成的消息是有效的 JSON，或者选择 `JSON_SCHEMA` 并提供模式，保证模型将生成与您提供的模式匹配的响应（`spring.ai.openai.chat.options.responseFormat` 选项）。
[Azure OpenAI](/spring4ai/api/chat/azure-openai-chat) 提供 `spring.ai.azure.openai.chat.options.responseFormat` 选项，指定模型必须输出的格式。设置为 `{ "type": "json_object" }` 启用 JSON 模式，它保证模型生成的消息是有效的 JSON。
[Ollama](/spring4ai/api/chat/ollama-chat) 提供 `spring.ai.ollama.chat.options.format` 选项来指定返回响应的格式。目前，唯一接受的值是 `json`。
[Mistral AI](/spring4ai/api/chat/mistralai-chat) 提供 `spring.ai.mistralai.chat.options.responseFormat` 选项来指定返回响应的格式。设置为 `{ "type": "json_object" }` 启用 JSON 模式，它保证模型生成的消息是有效的 JSON。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 单元测试容器
Source: https://javaai.pig4cloud.com/spring-ai/api/testcontainers
在 Spring AI 中使用 Testcontainers
# Testcontainers
Spring AI 提供 Testcontainers 支持，用于测试您的 AI 应用程序。
## 概述
Testcontainers 允许您在 Docker 容器中针对真实服务运行测试，提供更真实的测试环境。
## 特性
* AI 模型的预配置容器
* 向量数据库容器
* 与 Spring Boot 测试的轻松集成
* 自动容器生命周期管理
## 开始使用
将以下依赖项添加到您的项目中：
```xml theme={"system"}
org.springframework.ai
spring-ai-testcontainers
test
```
## 使用方法
```java theme={"system"}
@SpringBootTest
class MyAITest {
@Container
static OllamaContainer ollama = new OllamaContainer();
@Test
void testWithOllama() {
// 在此处编写测试代码
}
}
```
## 可用容器
* OllamaContainer
* MilvusContainer
* QdrantContainer
* WeaviateContainer
* ChromaContainer
## 配置
可以通过属性或编程方式配置容器：
```java theme={"system"}
@Container
static OllamaContainer ollama = new OllamaContainer()
.withModel("llama2")
.withPort(11434);
```
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 模型评估
Source: https://javaai.pig4cloud.com/spring-ai/api/testing
Spring AI 中的模型评估提供了全面的工具和框架，用于测试和评估 AI 模型。
## 概述
模型评估使开发人员能够：
* 测试模型性能
* 比较不同模型
* 验证模型输出
* 测量模型指标
## 评估类型
测量模型速度和资源使用情况
评估模型准确性和精确度
确保模型在不同版本间的稳定性
测试模型与其他组件的集成
## 实现
### 基本测试设置
```java theme={"system"}
@SpringBootTest
public class ModelEvaluationTest {
@Autowired
private ChatClient chatClient;
@Test
public void testModelResponse() {
String prompt = "什么是 Spring AI？";
String response = chatClient.generate(prompt);
assertNotNull(response);
assertTrue(response.length() > 0);
}
}
```
### 性能测试
```java theme={"system"}
@Test
public void testModelPerformance() {
ModelEvaluator evaluator = new ModelEvaluator(chatClient);
PerformanceMetrics metrics = evaluator.evaluatePerformance(
"测试提示",
Duration.ofSeconds(5)
);
assertTrue(metrics.getAverageResponseTime() < 1000);
assertTrue(metrics.getSuccessRate() > 0.95);
}
```
### 准确性测试
```java theme={"system"}
@Test
public void testModelAccuracy() {
ModelEvaluator evaluator = new ModelEvaluator(chatClient);
AccuracyMetrics metrics = evaluator.evaluateAccuracy(
testDataset,
expectedOutputs
);
assertTrue(metrics.getAccuracy() > 0.9);
assertTrue(metrics.getPrecision() > 0.85);
assertTrue(metrics.getRecall() > 0.85);
}
```
## 测试类别
### 1. 单元测试
```java theme={"system"}
@Test
public void testModelConfiguration() {
ModelConfig config = new ModelConfig();
config.setTemperature(0.7);
config.setMaxTokens(100);
assertNotNull(config);
assertEquals(0.7, config.getTemperature());
assertEquals(100, config.getMaxTokens());
}
```
### 2. 集成测试
```java theme={"system"}
@Test
public void testModelIntegration() {
// 测试模型与其他组件的集成
ModelService service = new ModelService(chatClient, memory, tools);
String result = service.processRequest("测试请求");
assertNotNull(result);
}
```
### 3. 负载测试
```java theme={"system"}
@Test
public void testModelLoad() {
LoadTester loadTester = new LoadTester(chatClient);
LoadTestResults results = loadTester.runLoadTest(
concurrentUsers: 100,
duration: Duration.ofMinutes(5)
);
assertTrue(results.getAverageResponseTime() < 2000);
assertTrue(results.getErrorRate() < 0.01);
}
```
## 配置属性
```properties theme={"system"}
spring.ai.testing.enabled=true
spring.ai.testing.timeout=30000
spring.ai.testing.retry-count=3
spring.ai.testing.metrics-enabled=true
```
## 最佳实践
在实现模型评估时，请考虑以下最佳实践：
* **测试覆盖率**：确保全面的测试覆盖率
* **性能指标**：监控关键性能指标
* **错误处理**：测试错误场景和边缘情况
* **数据质量**：使用高质量的测试数据集
* **持续测试**：在 CI/CD 中实现持续测试
## 高级特性
### 自定义评估器
```java theme={"system"}
@Component
public class CustomModelEvaluator implements ModelEvaluator {
@Override
public EvaluationResults evaluate(Model model, TestDataset dataset) {
// 自定义评估逻辑
return results;
}
}
```
### 测试报告
生成详细的测试报告：
```properties theme={"system"}
spring.ai.testing.reporting.enabled=true
spring.ai.testing.reporting.format=html
spring.ai.testing.reporting.location=reports
```
## 故障排除
常见问题和解决方案：
1. **测试失败**
* 检查模型配置
* 验证测试数据
* 查看错误日志
2. **性能问题**
* 优化测试执行
* 使用适当的测试数据大小
* 实现适当的清理
3. **集成问题**
* 验证组件连接
* 检查配置
* 隔离测试
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# 工具调用
Source: https://javaai.pig4cloud.com/spring-ai/api/tools
Spring AI 中的工具调用使 AI 模型能够与外部工具和服务交互，从而增强其功能。
## 概述
工具调用允许 AI 模型：
* 执行外部函数
* 访问外部服务
* 执行复杂操作
* 与现有系统集成
## 工具类型
执行自定义函数和方法
与外部 API 和服务交互
执行数据库操作
实现自定义工具功能
## 实现
### 基本工具定义
```java theme={"system"}
@Tool
public class CalculatorTool {
@ToolMethod
public double add(double a, double b) {
return a + b;
}
@ToolMethod
public double subtract(double a, double b) {
return a - b;
}
}
```
### 工具注册
```java theme={"system"}
@Configuration
public class ToolConfig {
@Bean
public ToolRegistry toolRegistry() {
return new ToolRegistry()
.register(new CalculatorTool())
.register(new WeatherTool())
.register(new DatabaseTool());
}
}
```
### 在聊天中使用工具
```java theme={"system"}
@Service
public class ChatService {
private final ChatClient chatClient;
private final ToolRegistry toolRegistry;
public ChatService(ChatClient chatClient, ToolRegistry toolRegistry) {
this.chatClient = chatClient;
this.toolRegistry = toolRegistry;
}
public String chat(String message) {
return chatClient.generate(message, toolRegistry);
}
}
```
## 工具类别
### 1. 函数工具
```java theme={"system"}
@Tool
public class MathTool {
@ToolMethod
public double calculate(String expression) {
// 实现
}
}
```
### 2. API 工具
```java theme={"system"}
@Tool
public class WeatherTool {
@ToolMethod
public Weather getWeather(String location) {
// API 调用实现
}
}
```
### 3. 数据库工具
```java theme={"system"}
@Tool
public class DatabaseTool {
@ToolMethod
public List query(String sql) {
// 数据库查询实现
}
}
```
## 配置属性
```properties theme={"system"}
spring.ai.tools.enabled=true
spring.ai.tools.timeout=5000
spring.ai.tools.max-retries=3
spring.ai.tools.cache-enabled=true
```
## 最佳实践
实现工具调用时，请考虑以下最佳实践：
* **错误处理**：实现强大的错误处理
* **安全性**：验证输入并限制访问
* **性能**：优化工具执行
* **监控**：跟踪工具使用情况和性能
* **文档**：记录工具功能和用法
## 高级特性
### 自定义工具实现
```java theme={"system"}
@Component
public class CustomTool implements Tool {
@Override
public String getName() {
return "custom-tool";
}
@Override
public Object execute(Map parameters) {
// 自定义实现
return result;
}
}
```
### 工具监控
监控工具使用情况和性能：
```properties theme={"system"}
management.endpoints.web.exposure.include=tools
management.endpoint.tools.enabled=true
```
## 故障排除
常见问题和解决方案：
1. **工具执行错误**
* 实现适当的错误处理
* 添加重试机制
* 记录详细的错误信息
2. **性能问题**
* 优化工具实现
* 实现缓存
* 使用异步执行
3. **安全问题**
* 验证输入
* 实现访问控制
* 监控工具使用情况
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Apache Cassandra 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/apache-cassandra
Spring AI 中的 Apache Cassandra 向量数据库集成了 Apache Cassandra 的向量功能，提供向量存储和搜索能力。
## 概述
Apache Cassandra 向量数据库支持：
* 分布式向量存储
* 线性可扩展性
* 高可用性
* 容错性
## 特性
分布式向量存储
线性扩展
高可用性
容错性
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-cassandra-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Apache Cassandra 向量数据库配置
spring.ai.cassandra.vectordb.enabled=true
spring.ai.cassandra.vectordb.contact-points=localhost
spring.ai.cassandra.vectordb.port=9042
spring.ai.cassandra.vectordb.keyspace=vectordb
spring.ai.cassandra.vectordb.table=vectors
```
### 用法
```java theme={"system"}
@Service
public class CassandraVectorService {
private final CassandraVectorClient vectorClient;
public CassandraVectorService(CassandraVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector) {
vectorClient.store(id, vector);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class CassandraVectorStorageConfig {
@Bean
public VectorStorage cassandraVectorStorage(CassandraVectorProperties properties) {
return new CassandraVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class CassandraSimilaritySearchConfig {
@Bean
public SimilaritySearch cassandraSimilaritySearch(CassandraVectorProperties properties) {
return new CassandraSimilaritySearch(properties);
}
}
```
### 3. 批量操作
```java theme={"system"}
@Service
public class BatchVectorService {
private final CassandraVectorClient vectorClient;
public void batchStore(List documents) {
vectorClient.batchStore(documents);
}
public List> batchSearch(List queryVectors, int k) {
return vectorClient.batchSearch(queryVectors, k);
}
}
```
## 高级特性
### 自定义复制策略
```java theme={"system"}
@Configuration
public class ReplicationStrategyConfig {
@Bean
public ReplicationStrategy replicationStrategy() {
return SimpleStrategy.builder()
.replicationFactor(3)
.build();
}
}
```
### 一致性级别配置
```java theme={"system"}
@Configuration
public class ConsistencyLevelConfig {
@Bean
public ConsistencyLevel consistencyLevel() {
return ConsistencyLevel.LOCAL_QUORUM;
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=cassandra-vectordb
management.endpoint.cassandra-vectordb.enabled=true
```
## 最佳实践
使用 Apache Cassandra 向量数据库时，请考虑以下最佳实践：
* **数据建模**：设计高效的数据模型
* **复制**：配置适当的复制
* **一致性**：选择合适的一致性级别
* **压缩**：优化压缩策略
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证联系点
* 检查网络连接性
* 查看身份验证
2. **性能问题**
* 优化数据模型
* 调整一致性级别
* 查看压缩策略
3. **存储问题**
* 监控磁盘使用情况
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Azure AI 搜索向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/azure
Spring AI 中的 Azure AI 搜索 (以前称为 Azure Cognitive Search) 向量数据库集成了 Azure 的向量数据库服务，提供向量存储和搜索能力。
## 概述
Azure AI 搜索向量数据库支持：
* 向量存储和索引
* 相似性搜索
* 实时向量操作
* 可扩展向量管理
## 特性
高效的向量存储
快速相似性搜索
水平扩展
轻松集成 Spring
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-azure-ai-search-store
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Azure AI 搜索向量数据库配置
spring.ai.vectorstore.azure.aisearch.endpoint=YOUR_AZURE_AI_SEARCH_ENDPOINT # 例如 https://your-service-name.search.windows.net
spring.ai.vectorstore.azure.aisearch.api-key=YOUR_AZURE_AI_SEARCH_API_KEY
spring.ai.vectorstore.azure.aisearch.index-name=vector-store-index # 要使用的索引名称
# spring.ai.vectorstore.azure.aisearch.create-index-if-not-exists=true # 如果索引不存在则创建 (可选, 默认为 false)
# spring.ai.vectorstore.azure.aisearch.embedding-dimension=1536 # 嵌入维度 (如果 create-index-if-not-exists=true 则需要)
```
### 用法
```java theme={"system"}
@Service
public class VectorService {
private final AzureAiSearchVectorStore vectorStore;
public VectorService(AzureAiSearchVectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public void storeVector(String id, float[] vector, Map metadata) {
// 注意：Azure AI 搜索通常从嵌入客户端获取嵌入
// 此处仅为示例，实际使用时通常直接添加 Document 对象
Document document = new Document(id, "Content related to vector", metadata);
// 假设嵌入由 AzureAiSearchVectorStore 内部处理或您已配置 EmbeddingClient
vectorStore.add(List.of(document));
}
public List searchSimilar(String query, int k) {
return vectorStore.similaritySearch(SearchRequest.query(query).withTopK(k));
}
}
```
## 向量操作
### 1. 向量存储
`AzureAiSearchVectorStore` 直接与 `EmbeddingClient` 集成以在添加文档时生成嵌入。
```java theme={"system"}
@Configuration
public class VectorStorageConfig {
// AzureAiSearchVectorStore bean 通常由 Spring Boot 自动配置
// 如果需要，您可以自定义它
}
```
### 2. 相似性搜索
```java theme={"system"}
@Service
public class SimilaritySearchService {
private final AzureAiSearchVectorStore vectorStore;
public SimilaritySearchService(AzureAiSearchVectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public List findSimilar(String queryText, int topK) {
return vectorStore.similaritySearch(SearchRequest.query(queryText).withTopK(topK));
}
}
```
### 3. 批量操作
`AzureAiSearchVectorStore` 支持批量添加文档。
```java theme={"system"}
@Service
public class BatchVectorService {
private final AzureAiSearchVectorStore vectorStore;
public BatchVectorService(AzureAiSearchVectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public void batchStore(List documents) {
vectorStore.add(documents);
}
}
```
## 高级特性
### 自定义索引配置
如果 `spring.ai.vectorstore.azure.aisearch.create-index-if-not-exists` 设置为 `true`，则会自动创建索引。
嵌入维度 (`spring.ai.vectorstore.azure.aisearch.embedding-dimension`) 必须与您的 `EmbeddingClient` 生成的维度匹配。
有关更高级的索引自定义，请参阅 [Azure AI 搜索文档](https://docs.microsoft.com/azure/search/search-what-is-azure-search)。
### 监控
Azure AI 搜索提供强大的监控功能，可以通过 Azure 门户访问。
## 最佳实践
使用 Azure AI 搜索向量数据库时，请考虑以下最佳实践：
* **索引设计**：为您的数据和查询模式设计高效的索引。
* **API 密钥管理**：安全地管理您的 API 密钥。
* **批量处理**：尽可能使用批量操作以提高效率。
* **错误处理**：实施稳健的错误处理。
* **监控**：利用 Azure 门户中的监控功能。
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证端点和 API 密钥。
* 检查网络连接性。
* 查看防火墙设置。
2. **性能问题**
* 优化索引配置。
* 考虑扩展您的 Azure AI 搜索服务。
* 查看查询复杂性。
3. **存储问题**
* 监控存储使用情况。
* 实施清理策略。
* 查看 Azure AI 搜索服务的限制。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Azure Cosmos DB 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/azure-cosmos-db
# Azure Cosmos DB NoSQL 向量数据库
Spring AI 支持使用 [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/) 作为向量数据库，通过其向量嵌入和索引功能。
## 先决条件
1. **Azure 账户**：您需要一个拥有有效订阅的 Azure 账户。
2. **Azure Cosmos DB for NoSQL 资源**：在您的 Azure 账户中创建一个 Azure Cosmos DB for NoSQL 账户。
* 在创建过程中，请确保选择"NoSQL" API。
* 记下您的 Cosmos DB 端点和主密钥，因为在应用程序配置中将会用到它们。
3. **向量嵌入功能**：目前，Azure Cosmos DB for NoSQL 中的向量搜索功能处于预览阶段。您需要按照[这些说明](https://learn.microsoft.com/azure/cosmos-db/nosql/vector-search#register-for-the-preview-of-vector-search-in-azure-cosmos-db-for-nosql)注册预览版。
## 添加依赖
将 `spring-ai-azure-cosmos-db-store-spring-boot-starter` 依赖项添加到您的 `pom.xml` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-azure-cosmos-db-store-spring-boot-starter
```
您还需要一个 `EmbeddingClient` 实现来为您的文档生成向量嵌入。例如，您可以添加 `spring-ai-openai-spring-boot-starter` 以使用 OpenAI 的嵌入模型：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-spring-boot-starter
```
## 配置属性
在您的 `application.properties` 或 `application.yml` 文件中配置 Azure Cosmos DB 和嵌入客户端属性。
### Azure Cosmos DB 属性
```properties theme={"system"}
# Azure Cosmos DB 配置
spring.ai.vectorstore.cosmosdb.endpoint=YOUR_COSMOS_DB_ENDPOINT # 例如 https://your-account.documents.azure.com:443/
spring.ai.vectorstore.cosmosdb.key=YOUR_COSMOS_DB_PRIMARY_KEY
spring.ai.vectorstore.cosmosdb.database-name=your_database_name
spring.ai.vectorstore.cosmosdb.container-name=your_container_name # 将在其中存储向量的容器
spring.ai.vectorstore.cosmosdb.create-container-if-not-exists=true # 如果容器不存在则创建 (可选, 默认为 false)
# 向量索引策略 (在容器创建时应用)
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].path="/embedding" # JSON 文档中包含向量的路径
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].type="vector-ivf" # 索引类型，例如 vector-ivf, vector-hnsw
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].num-lists=1 # 对于 IVF (默认为 1)
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].dimensions=1536 # 嵌入向量的维度 (例如 OpenAI text-embedding-ada-002 为 1536)
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].distance-function="cosine" # 距离函数，例如 cosine, euclidean, dotproduct
```
如果 `create-container-if-not-exists` 设置为 `true`，则当容器尚不存在时，将使用提供的 `indexing-policy` 创建它。
如果容器已存在，则现有索引策略将保持不变，并且提供的 `indexing-policy` 配置将被忽略。
确保嵌入客户端输出的维度与索引策略中配置的 `dimensions` 匹配。
### 嵌入客户端属性 (例如 OpenAI)
```properties theme={"system"}
# OpenAI EmbeddingClient 配置
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002
```
## 使用 `VectorStore`
将 `VectorStore` bean 注入到您的组件中以与之交互：
```java theme={"system"}
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.document.Document;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class MyVectorStoreService {
private final VectorStore vectorStore;
@Autowired
public MyVectorStoreService(VectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public void addDocuments(List documents) {
vectorStore.add(documents);
}
public List findSimilarDocuments(String query, int k) {
return vectorStore.similaritySearch(query, k);
}
}
```
### 创建 `CosmosDBVectorStore` Bean (可选)
Spring Boot 会自动配置 `CosmosDBVectorStore` bean。但是，如果您需要自定义配置，可以定义自己的 bean：
```java theme={"system"}
import com.azure.cosmos.CosmosAsyncClient;
import com.azure.cosmos.CosmosClientBuilder;
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.vectorstore.azure.cosmosdb.CosmosDBVectorStore;
import org.springframework.ai.vectorstore.azure.cosmosdb.CosmosDBVectorStoreConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class MyCosmosDbConfig {
@Bean
public CosmosAsyncClient cosmosAsyncClient() {
// 从属性或直接创建 CosmosAsyncClient
return new CosmosClientBuilder()
.endpoint("YOUR_COSMOS_DB_ENDPOINT")
.key("YOUR_COSMOS_DB_PRIMARY_KEY")
.buildAsyncClient();
}
@Bean
public CosmosDBVectorStore cosmosDBVectorStore(CosmosAsyncClient cosmosAsyncClient, EmbeddingClient embeddingClient) {
CosmosDBVectorStoreConfig config = CosmosDBVectorStoreConfig.builder("your_database_name", "your_container_name")
// .createContainerIfNotExists(true) // 按需设置
// .indexingPolicy(...) // 按需设置索引策略
.build();
return new CosmosDBVectorStore(cosmosAsyncClient, embeddingClient, config);
}
}
```
## 向量索引
Azure Cosmos DB for NoSQL 支持多种类型的向量索引，例如 `vector-ivf` 和 `vector-hnsw`。索引的选择取决于您的特定用例和性能要求。
* **`vector-ivf` (Inverted File Index)**：适用于大型数据集，并在准确性和查询速度之间提供良好的平衡。它将向量空间划分为簇，并在查询时仅搜索最相关的簇。
* **`vector-hnsw` (Hierarchical Navigable Small World)**：一种基于图的索引，以其高查询召回率和低延迟而闻名，尤其适用于高维数据。
您可以在 `application.properties` 中的 `spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes` 下或在以编程方式配置 `CosmosDBVectorStoreConfig` 时配置索引类型、维度、距离函数和特定于类型的参数 (例如 `num-lists` for IVF)。
```json theme={"system"}
// 示例索引策略 JSON
{
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*"
}
],
"excludedPaths": [
{
"path": "/\"_etag\"/?"
}
],
"vectorIndexes": [
{
"path": "/embedding", // 确保这与您的文档结构匹配
"type": "vector-ivf",
"numLists": 1,
"dimensions": 1536,
"distanceFunction": "cosine"
}
]
}
```
有关向量索引的更多详细信息，请参阅 [Azure Cosmos DB for NoSQL 向量索引文档](https://learn.microsoft.com/azure/cosmos-db/nosql/vector-search#vector-indexing-policies)。
## 元数据过滤
Cosmos DB 向量存储支持使用 [SQL WHERE子句](https://learn.microsoft.com/azure/cosmos-db/nosql/query/where) 和 [相似性搜索过滤器表达式](./../index.mdx#metadata-filtering) 进行元数据过滤。这些过滤器应用于相似性搜索查询期间，以根据其元数据字段缩小结果范围。
过滤器表达式直接转换为 Cosmos DB SQL WHERE 子句。
例如，如果您有带有元数据字段 `genre` 和 `year` 的文档，则可以按如下方式进行过滤：
```java theme={"system"}
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;
// ...
FilterExpressionBuilder b = new FilterExpressionBuilder();
// WHERE genre = 'drama' AND year > 2020
Filter filter = new Filter(b.eq("genre", "drama").and(b.gt("year", 2020)).build());
SearchRequest request = SearchRequest.query("A tragic hero") // 示例查询通常保留英文
.withTopK(5)
.withSimilarityThreshold(0.75)
.withFilter(filter);
List results = vectorStore.similaritySearch(request);
```
这将转换为类似于以下的 Cosmos DB 查询：
```sql theme={"system"}
SELECT c.id, c.content, c.metadata, VectorDistance(c.embedding, @embeddingParam) AS similarity
FROM c
WHERE c.metadata.genre = 'drama' AND c.metadata.year > 2020
ORDER BY VectorDistance(c.embedding, @embeddingParam)
```
确保您的容器中存在用于过滤的元数据字段，并且它们已正确索引 (如果需要提高性能)。
并非所有 Spring AI 过滤器表达式操作符都直接映射到 Cosmos DB SQL 函数。支持基本比较 (`EQ`, `NE`, `GT`, `GTE`, `LT`, `LTE`)、逻辑运算符 (`AND`, `OR`, `NOT`) 和 `IN` / `NIN`。
## 删除数据
`CosmosDBVectorStore` 支持通过文档 ID 删除数据。
```java theme={"system"}
boolean deleted = vectorStore.delete(List.of("documentId1", "documentId2"));
```
## 总结
通过将 Spring AI 与 Azure Cosmos DB for NoSQL 集成，您可以利用 Azure 的可扩展且全球分布的数据库服务来满足您的向量存储需求，并结合 Spring AI 的简化抽象来构建强大的 AI 应用程序。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Chroma 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/chroma
Spring AI 中的 Chroma 向量数据库集成了 Chroma 的向量数据库功能，提供向量存储和搜索能力。
## 概述
Chroma 向量数据库支持：
* 本地和分布式向量存储
* 快速相似性搜索
* 元数据过滤
* 轻松集成
## 特性
高效的向量存储
快速相似性搜索
丰富的元数据支持
多种部署选项
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-chroma-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Chroma 向量数据库配置
spring.ai.chroma.vectordb.enabled=true
spring.ai.chroma.vectordb.host=localhost
spring.ai.chroma.vectordb.port=8000
spring.ai.chroma.vectordb.collection-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class ChromaVectorService {
private final ChromaVectorClient vectorClient;
public ChromaVectorService(ChromaVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class ChromaVectorStorageConfig {
@Bean
public VectorStorage chromaVectorStorage(ChromaVectorProperties properties) {
return new ChromaVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class ChromaSimilaritySearchConfig {
@Bean
public SimilaritySearch chromaSimilaritySearch(ChromaVectorProperties properties) {
return new ChromaSimilaritySearch(properties);
}
}
```
### 3. 元数据过滤
```java theme={"system"}
@Service
public class MetadataFilterService {
private final ChromaVectorClient vectorClient;
public List searchWithFilter(float[] queryVector, Map filter, int k) {
return vectorClient.searchWithFilter(queryVector, filter, k);
}
}
```
## 高级特性
### 自定义集合配置
```java theme={"system"}
@Configuration
public class CollectionConfig {
@Bean
public CollectionConfig collectionConfig() {
return CollectionConfig.builder()
.name("custom-collection")
.dimension(1536)
.metric(MetricType.COSINE)
.build();
}
}
```
### 持久化配置
```java theme={"system"}
@Configuration
public class PersistenceConfig {
@Bean
public PersistenceConfig persistenceConfig() {
return PersistenceConfig.builder()
.directory("/path/to/persist")
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=chroma-vectordb
management.endpoint.chroma-vectordb.enabled=true
```
## 最佳实践
使用 Chroma 向量数据库时，请考虑以下最佳实践：
* **集合管理**：有效组织集合
* **元数据使用**：利用元数据进行过滤
* **持久化**：配置适当的持久化
* **性能**：优化搜索参数
* **监控**：设置适当的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证主机和端口
* 检查网络连接性
* 查看服务器状态
2. **性能问题**
* 优化集合设置
* 使用适当的度量标准
* 实现缓存
3. **存储问题**
* 监控磁盘使用情况
* 配置持久化
* 执行清理
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Couchbase 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/couchbase
Spring AI 中的 Couchbase 向量数据库集成了 Couchbase 的向量功能，提供向量存储和搜索能力。
## 概述
Couchbase 向量数据库支持：
* 分布式向量存储
* 全文搜索集成
* 实时向量操作
* 多维扩展
## 特性
分布式向量存储
全文搜索
多维扩展
实时操作
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-couchbase-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Couchbase 向量数据库配置
spring.ai.couchbase.vectordb.enabled=true
spring.ai.couchbase.vectordb.connection-string=couchbase://localhost
spring.ai.couchbase.vectordb.bucket-name=vectordb
spring.ai.couchbase.vectordb.scope-name=vectors
spring.ai.couchbase.vectordb.collection-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class CouchbaseVectorService {
private final CouchbaseVectorClient vectorClient;
public CouchbaseVectorService(CouchbaseVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class CouchbaseVectorStorageConfig {
@Bean
public VectorStorage couchbaseVectorStorage(CouchbaseVectorProperties properties) {
return new CouchbaseVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class CouchbaseSimilaritySearchConfig {
@Bean
public SimilaritySearch couchbaseSimilaritySearch(CouchbaseVectorProperties properties) {
return new CouchbaseSimilaritySearch(properties);
}
}
```
### 3. 全文搜索集成
```java theme={"system"}
@Service
public class FullTextSearchService {
private final CouchbaseVectorClient vectorClient;
public List searchWithText(String text, float[] queryVector, int k) {
return vectorClient.searchWithText(text, queryVector, k);
}
}
```
## 高级特性
### 自定义索引配置
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector-index")
.dimension(1536)
.metric(MetricType.COSINE)
.build();
}
}
```
### Bucket 配置
```java theme={"system"}
@Configuration
public class BucketConfig {
@Bean
public BucketConfig bucketConfig() {
return BucketConfig.builder()
.name("vectordb")
.memoryQuota(1024)
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=couchbase-vectordb
management.endpoint.couchbase-vectordb.enabled=true
```
## 最佳实践
使用 Couchbase 向量数据库时，请考虑以下最佳实践：
* **集群设计**：设计高效的集群拓扑
* **索引管理**：优化索引配置
* **内存管理**：配置适当的内存配额
* **复制**：设置适当的复制
* **监控**：实施全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证连接字符串
* 检查集群状态
* 查看身份验证
2. **性能问题**
* 优化索引配置
* 调整内存配额
* 查看查询模式
3. **存储问题**
* 监控存储桶使用情况
* 配置清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Elasticsearch 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/elasticsearch
Spring AI 中的 Elasticsearch 向量数据库集成了 Elasticsearch 的向量功能，提供向量存储和搜索能力。
## 概述
Elasticsearch 向量数据库支持：
* 分布式向量存储
* 高级搜索功能
* 实时向量操作
* 全文搜索集成
## 特性
分布式向量存储
丰富的搜索功能
实时操作
全文搜索集成
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-elasticsearch-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Elasticsearch 向量数据库配置
spring.ai.elasticsearch.vectordb.enabled=true
spring.ai.elasticsearch.vectordb.host=localhost
spring.ai.elasticsearch.vectordb.port=9200
spring.ai.elasticsearch.vectordb.index-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class ElasticsearchVectorService {
private final ElasticsearchVectorClient vectorClient;
public ElasticsearchVectorService(ElasticsearchVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class ElasticsearchVectorStorageConfig {
@Bean
public VectorStorage elasticsearchVectorStorage(ElasticsearchVectorProperties properties) {
return new ElasticsearchVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class ElasticsearchSimilaritySearchConfig {
@Bean
public SimilaritySearch elasticsearchSimilaritySearch(ElasticsearchVectorProperties properties) {
return new ElasticsearchSimilaritySearch(properties);
}
}
```
### 3. 混合搜索
```java theme={"system"}
@Service
public class HybridSearchService {
private final ElasticsearchVectorClient vectorClient;
public List hybridSearch(String text, float[] queryVector, int k) {
return vectorClient.hybridSearch(text, queryVector, k);
}
}
```
## 高级特性
### 自定义索引配置
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector-index")
.dimension(1536)
.metric(MetricType.COSINE)
.build();
}
}
```
### 映射配置
```java theme={"system"}
@Configuration
public class MappingConfig {
@Bean
public MappingConfig mappingConfig() {
return MappingConfig.builder()
.vectorField("vector")
.metadataFields(Arrays.asList("title", "content"))
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=elasticsearch-vectordb
management.endpoint.elasticsearch-vectordb.enabled=true
```
## 最佳实践
使用 Elasticsearch 向量数据库时，请考虑以下最佳实践：
* **索引设计**：设计高效的索引结构
* **映射优化**：优化字段映射
* **分片管理**：配置适当的分片
* **查询优化**：优化搜索查询
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证主机和端口
* 检查集群健康状况
* 查看身份验证
2. **性能问题**
* 优化索引设置
* 调整分片配置
* 查看查询模式
3. **存储问题**
* 监控索引大小
* 配置清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# GemFire 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/gemfire
Spring AI 中的 GemFire 向量数据库集成了 VMware GemFire 的向量功能，提供向量存储和搜索能力。
## 概述
GemFire 向量数据库支持：
* 分布式向量存储
* 内存向量操作
* 实时向量搜索
* 高性能扩展
## 特性
内存向量存储
分布式架构
实时操作
高性能扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-gemfire-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# GemFire 向量数据库配置
spring.ai.gemfire.vectordb.enabled=true
spring.ai.gemfire.vectordb.locator-host=localhost
spring.ai.gemfire.vectordb.locator-port=10334
spring.ai.gemfire.vectordb.region-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class GemFireVectorService {
private final GemFireVectorClient vectorClient;
public GemFireVectorService(GemFireVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector) {
vectorClient.store(id, vector);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class GemFireVectorStorageConfig {
@Bean
public VectorStorage gemFireVectorStorage(GemFireVectorProperties properties) {
return new GemFireVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class GemFireSimilaritySearchConfig {
@Bean
public SimilaritySearch gemFireSimilaritySearch(GemFireVectorProperties properties) {
return new GemFireSimilaritySearch(properties);
}
}
```
### 3. Region 配置
```java theme={"system"}
@Configuration
public class RegionConfig {
@Bean
public RegionConfig regionConfig() {
return RegionConfig.builder()
.name("vectors")
.dataPolicy(DataPolicy.REPLICATE)
.build();
}
}
```
## 高级特性
### 自定义 Region 配置
```java theme={"system"}
@Configuration
public class CustomRegionConfig {
@Bean
public RegionConfig customRegionConfig() {
return RegionConfig.builder()
.name("custom-vectors")
.dataPolicy(DataPolicy.PARTITION)
.partitionAttributes(partitionAttributes())
.build();
}
private PartitionAttributes partitionAttributes() {
return PartitionAttributes.builder()
.redundantCopies(1)
.build();
}
}
```
### 持久化配置
```java theme={"system"}
@Configuration
public class PersistenceConfig {
@Bean
public PersistenceConfig persistenceConfig() {
return PersistenceConfig.builder()
.diskStoreName("vectorStore")
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=gemfire-vectordb
management.endpoint.gemfire-vectordb.enabled=true
```
## 最佳实践
使用 GemFire 向量数据库时，请考虑以下最佳实践：
* **Region 设计**：设计高效的 Region 结构
* **内存管理**：配置适当的内存设置
* **持久化**：设置适当的持久化
* **分区**：优化分区策略
* **监控**：实施全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证定位器设置
* 检查网络连接性
* 查看安全设置
2. **性能问题**
* 优化 Region 配置
* 调整内存设置
* 查看分区策略
3. **存储问题**
* 监控内存使用情况
* 配置持久化
* 查看清理策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# SAP HANA Cloud 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/hana
# SAP HANA Cloud 向量数据库
Spring AI 支持将 [SAP HANA Cloud](https://www.sap.com/products/technology-platform/hana.html) 作为向量数据库，利用其向量引擎进行相似性搜索。
## 添加依赖
要使用 SAP HANA Cloud 向量存储，您需要将 `spring-ai-sap-hana-store-spring-boot-starter` 依赖项添加到项目的 `pom.xml` 文件中。
该启动器包含了 `spring-ai-core` 和 SAP HANA JDBC 驱动程序。
```xml theme={"system"}
org.springframework.ai
spring-ai-sap-hana-store-spring-boot-starter
```
您还需要一个 `EmbeddingClient` 实现来为您的文档生成向量嵌入。例如，您可以添加 `spring-ai-openai-spring-boot-starter` 以使用 OpenAI 的嵌入模型：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-spring-boot-starter
```
## 配置属性
在您的 `application.properties` 或 `application.yml` 文件中配置 SAP HANA Cloud 和嵌入客户端属性。
### SAP HANA Cloud 属性
| 属性 | 描述 | 默认值 |
| :---------------------------------------------------- | :---------------------------------------------------------------------- | :----------------------------------- |
| `spring.ai.vectorstore.hana.host` | SAP HANA Cloud 实例的主机名或 IP 地址。 | |
| `spring.ai.vectorstore.hana.port` | SAP HANA Cloud 实例的端口。 | |
| `spring.ai.vectorstore.hana.username` | 用于连接到 SAP HANA Cloud 的用户名。 | |
| `spring.ai.vectorstore.hana.password` | 用于连接到 SAP HANA Cloud 的密码。 | |
| `spring.ai.vectorstore.hana.table-name` | 用于存储向量和元数据的表名。 | `SPRING_AI_VECTOR_STORE` |
| `spring.ai.vectorstore.hana.embedding-dimension` | 嵌入向量的维度。必须与 `EmbeddingClient` 生成的维度匹配。 | 1536 (OpenAI text-embedding-ada-002) |
| `spring.ai.vectorstore.hana.distance-type` | 用于相似性搜索的距离类型 (`L2DISTANCE`, `COSINE_SIMILARITY`, `EUCLIDEAN_DISTANCE`)。 | `L2DISTANCE` |
| `spring.ai.vectorstore.hana.schema-name` | SAP HANA Cloud 中的 schema 名称。 | (用户默认 schema) |
| `spring.ai.vectorstore.hana.ssl.enabled` | 是否为 JDBC 连接启用 SSL。 | `false` |
| `spring.ai.vectorstore.hana.ssl.trust-store-location` | SSL 信任库文件的路径 (如果 `ssl.enabled` 为 `true`)。 | |
| `spring.ai.vectorstore.hana.ssl.trust-store-password` | SSL 信任库的密码 (如果 `ssl.enabled` 为 `true`)。 | |
**示例 `application.properties`:**
```properties theme={"system"}
# SAP HANA Cloud 配置
spring.ai.vectorstore.hana.host=your-hana-host
spring.ai.vectorstore.hana.port=your-hana-port
spring.ai.vectorstore.hana.username=your-username
spring.ai.vectorstore.hana.password=your-password
spring.ai.vectorstore.hana.table-name=MY_VECTOR_TABLE
spring.ai.vectorstore.hana.embedding-dimension=1536
spring.ai.vectorstore.hana.distance-type=COSINE_SIMILARITY
# spring.ai.vectorstore.hana.schema-name=MY_SCHEMA # 可选
# spring.ai.vectorstore.hana.ssl.enabled=true # 如果需要 SSL
# spring.ai.vectorstore.hana.ssl.trust-store-location=path/to/truststore.jks
# spring.ai.vectorstore.hana.ssl.trust-store-password=truststore_password
# 嵌入客户端配置 (例如 OpenAI)
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002
```
确保 `spring.ai.vectorstore.hana.embedding-dimension` 与您正在使用的 `EmbeddingClient` 输出的嵌入维度相匹配。
如果表不存在，它将在第一次添加文档时自动创建。
## 使用 `VectorStore`
将 `VectorStore` bean 注入到您的组件中以与之交互：
```java theme={"system"}
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.document.Document;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class MyVectorStoreService {
private final VectorStore vectorStore; // 将自动配置 HanaVectorStore
@Autowired
public MyVectorStoreService(VectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public void addDocuments(List documents) {
vectorStore.add(documents);
}
public List findSimilarDocuments(String query, int k) {
return vectorStore.similaritySearch(query, k);
}
}
```
### 创建 `HanaVectorStore` Bean (可选)
Spring Boot 会自动配置 `HanaVectorStore` bean。但是，如果您需要自定义配置，可以定义自己的 bean：
```java theme={"system"}
import com.zaxxer.hikari.HikariDataSource;
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.vectorstore.HanaVectorStore;
import org.springframework.ai.vectorstore.HanaVectorStore.HanaVectorStoreConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;
import javax.sql.DataSource;
@Configuration
public class MyHanaConfig {
@Bean
public DataSource hanaDataSource() {
HikariDataSource dataSource = new HikariDataSource();
dataSource.setJdbcUrl("jdbc:sap://your-hana-host:your-hana-port");
dataSource.setUsername("your-username
dataSource.setPassword("your-password");
// dataSource.setSchema("MY_SCHEMA"); // 可选
// SSL 属性 (如果需要)
// dataSource.getDataSourceProperties().setProperty("encrypt", "true");
// dataSource.getDataSourceProperties().setProperty("trustStore", "path/to/truststore.jks");
// dataSource.getDataSourceProperties().setProperty("trustStorePassword", "truststore_password");
return dataSource;
}
@Bean
public JdbcTemplate jdbcTemplate(DataSource hanaDataSource) {
return new JdbcTemplate(hanaDataSource);
}
@Bean
public HanaVectorStore hanaVectorStore(JdbcTemplate jdbcTemplate, EmbeddingClient embeddingClient) {
HanaVectorStoreConfig config = HanaVectorStoreConfig.builder()
.tableName("MY_CUSTOM_TABLE")
.embeddingDimension(1536)
.distanceType(HanaVectorStoreConfig.DistanceType.COSINE_SIMILARITY)
// .schemaName("MY_SCHEMA") // 可选
.build();
return new HanaVectorStore(jdbcTemplate, embeddingClient, config);
}
}
```
## 元数据过滤
SAP HANA Cloud 向量存储支持使用 SQL `WHERE` 子句和 Spring AI 的 [相似性搜索过滤器表达式](./index.mdx#metadata-filtering) 进行元数据过滤。
过滤器表达式会转换为 SQL `WHERE` 子句中的条件。
**示例：**
```java theme={"system"}
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;
// ...
FilterExpressionBuilder b = new FilterExpressionBuilder();
// "metadata"->>'genre' = 'drama' AND "metadata"->>'year' > 2020
// 注意：在 SAP HANA 中，JSON 字段访问通常使用 JSON 函数或路径表达式。
// 此处的示例假定元数据存储为 JSON，并且数据库配置为支持此类查询。
// 精确的 SQL 语法可能因您的 HANA 版本和表结构而异。
Filter filter = new Filter(b.eq("genre", "drama").and(b.gt("year", 2020)).build());
SearchRequest request = SearchRequest.query("A dramatic film released after 2020") // 示例查询通常保留英文
.withTopK(5)
.withFilter(filter);
List results = vectorStore.similaritySearch(request);
```
元数据存储在表中的 `metadata` JSON 列中。
过滤器表达式中使用的键 (例如，`genre`, `year`) 应该是您在文档元数据中使用的键。
确保您的 SAP HANA Cloud 实例配置为允许对 JSON 列进行高效查询。根据需要，可能需要为元数据字段创建索引。
## 删除数据
`HanaVectorStore` 支持通过文档 ID 删除数据。
```java theme={"system"}
boolean deleted = vectorStore.delete(List.of("documentId1", "documentId2"));
```
## 总结
将 Spring AI 与 SAP HANA Cloud 集成，使您能够利用 HANA 的内存计算能力和企业级特性进行向量存储和相似性搜索，从而增强您的 AI 应用程序。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MariaDB 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/mariadb
Spring AI 中的 MariaDB 向量数据库集成了 MariaDB 的向量功能，提供向量存储和搜索能力。
## 概述
MariaDB 向量数据库支持：
* 关系型向量存储
* 基于 SQL 的向量操作
* 全文搜索集成
* 事务支持
## 特性
关系型向量存储
基于 SQL 的操作
事务支持
全文搜索集成
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-mariadb-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# MariaDB 向量数据库配置
spring.ai.mariadb.vectordb.enabled=true
spring.ai.mariadb.vectordb.url=jdbc:mariadb://localhost:3306/vectordb
spring.ai.mariadb.vectordb.username=root
spring.ai.mariadb.vectordb.password=password
spring.ai.mariadb.vectordb.table-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class MariaDBVectorService {
private final MariaDBVectorClient vectorClient;
public MariaDBVectorService(MariaDBVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class MariaDBVectorStorageConfig {
@Bean
public VectorStorage mariaDBVectorStorage(MariaDBVectorProperties properties) {
return new MariaDBVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class MariaDBSimilaritySearchConfig {
@Bean
public SimilaritySearch mariaDBSimilaritySearch(MariaDBVectorProperties properties) {
return new MariaDBSimilaritySearch(properties);
}
}
```
### 3. 事务管理
```java theme={"system"}
@Service
@Transactional
public class TransactionalVectorService {
private final MariaDBVectorClient vectorClient;
public void storeVectorWithTransaction(String id, float[] vector) {
vectorClient.store(id, vector);
}
}
```
## 高级特性
### 自定义表配置
```java theme={"system"}
@Configuration
public class TableConfig {
@Bean
public TableConfig tableConfig() {
return TableConfig.builder()
.name("vector_table")
.vectorColumn("vector")
.metadataColumns(Arrays.asList("title", "content"))
.build();
}
}
```
### 索引配置
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector_index")
.type(IndexType.VECTOR)
.dimension(1536)
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=mariadb-vectordb
management.endpoint.mariadb-vectordb.enabled=true
```
## 最佳实践
使用 MariaDB 向量数据库时，请考虑以下最佳实践：
* **表设计**：设计高效的表结构
* **索引管理**：优化索引配置
* **事务管理**：使用适当的事务级别
* **连接池**：配置连接池
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证数据库连接
* 检查凭据
* 查看网络设置
2. **性能问题**
* 优化表结构
* 配置索引
* 查看查询模式
3. **存储问题**
* 监控表大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Milvus 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/milvus
Spring AI 中的 Milvus 向量数据库集成了 Milvus 的向量功能，提供向量存储和搜索能力。
## 概述
Milvus 向量数据库支持：
* 分布式向量存储
* 高性能相似性搜索
* 实时向量操作
* 可扩展架构
## 特性
分布式架构
快速相似性搜索
水平扩展
实时操作
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-milvus-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Milvus 向量数据库配置
spring.ai.milvus.vectordb.enabled=true
spring.ai.milvus.vectordb.host=localhost
spring.ai.milvus.vectordb.port=19530
spring.ai.milvus.vectordb.collection-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class MilvusVectorService {
private final MilvusVectorClient vectorClient;
public MilvusVectorService(MilvusVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class MilvusVectorStorageConfig {
@Bean
public VectorStorage milvusVectorStorage(MilvusVectorProperties properties) {
return new MilvusVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class MilvusSimilaritySearchConfig {
@Bean
public SimilaritySearch milvusSimilaritySearch(MilvusVectorProperties properties) {
return new MilvusSimilaritySearch(properties);
}
}
```
### 3. 集合管理
```java theme={"system"}
@Service
public class CollectionService {
private final MilvusVectorClient vectorClient;
public void createCollection(String name, int dimension) {
vectorClient.createCollection(name, dimension);
}
public void dropCollection(String name) {
vectorClient.dropCollection(name);
}
}
```
## 高级特性
### 自定义集合配置
```java theme={"system"}
@Configuration
public class CollectionConfig {
@Bean
public CollectionConfig collectionConfig() {
return CollectionConfig.builder()
.name("custom-collection")
.dimension(1536)
.indexType(IndexType.IVF_FLAT)
.metricType(MetricType.COSINE)
.build();
}
}
```
### 分区管理
```java theme={"system"}
@Configuration
public class PartitionConfig {
@Bean
public PartitionConfig partitionConfig() {
return PartitionConfig.builder()
.name("custom-partition")
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=milvus-vectordb
management.endpoint.milvus-vectordb.enabled=true
```
## 最佳实践
使用 Milvus 向量数据库时，请考虑以下最佳实践：
* **集合设计**：设计高效的集合结构
* **索引选择**：选择合适的索引类型
* **分区策略**：实施有效的分区
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证主机和端口
* 检查网络连接性
* 查看身份验证
2. **性能问题**
* 优化索引配置
* 调整分区策略
* 查看资源分配
3. **存储问题**
* 监控集合大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# MongoDB 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/mongodb
Spring AI 中的 MongoDB 向量数据库集成了 MongoDB 的向量功能，提供向量存储和搜索能力。
## 概述
MongoDB 向量数据库支持：
* 基于文档的向量存储
* 灵活的模式设计
* 实时向量搜索
* 可扩展架构
## 特性
文档向量存储
灵活的模式设计
实时搜索
水平扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-mongodb-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# MongoDB 向量数据库配置
spring.ai.mongodb.vectordb.enabled=true
spring.ai.mongodb.vectordb.uri=mongodb://localhost:27017
spring.ai.mongodb.vectordb.database=vectordb
spring.ai.mongodb.vectordb.collection=vectors
```
### 用法
```java theme={"system"}
@Service
public class MongoDBVectorService {
private final MongoDBVectorClient vectorClient;
public MongoDBVectorService(MongoDBVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class MongoDBVectorStorageConfig {
@Bean
public VectorStorage mongoDBVectorStorage(MongoDBVectorProperties properties) {
return new MongoDBVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class MongoDBSimilaritySearchConfig {
@Bean
public SimilaritySearch mongoDBSimilaritySearch(MongoDBVectorProperties properties) {
return new MongoDBSimilaritySearch(properties);
}
}
```
### 3. 集合管理
```java theme={"system"}
@Service
public class CollectionService {
private final MongoDBVectorClient vectorClient;
public void createCollection(String name, int dimension) {
vectorClient.createCollection(name, dimension);
}
public void dropCollection(String name) {
vectorClient.dropCollection(name);
}
}
```
## 高级特性
### 自定义集合配置
```java theme={"system"}
@Configuration
public class CollectionConfig {
@Bean
public CollectionConfig collectionConfig() {
return CollectionConfig.builder()
.name("custom-vectors")
.dimension(1536)
.indexType(IndexType.HNSW)
.metricType(MetricType.COSINE)
.build();
}
}
```
### 索引管理
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector_index")
.type(IndexType.HNSW)
.dimension(1536)
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=mongodb-vectordb
management.endpoint.mongodb-vectordb.enabled=true
```
## 最佳实践
使用 MongoDB 向量数据库时，请考虑以下最佳实践：
* **集合设计**：设计高效的集合结构
* **索引管理**：优化索引配置
* **分片策略**：实施有效的分片
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证连接 URI
* 检查身份验证
* 查看网络设置
2. **性能问题**
* 优化索引配置
* 调整分片策略
* 查看查询模式
3. **存储问题**
* 监控集合大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Neo4j 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/neo4j
Spring AI 中的 Neo4j 向量数据库集成了 Neo4j 基于图的向量功能，提供向量存储和搜索能力。
## 概述
Neo4j 向量数据库支持：
* 基于图的向量存储
* 关系感知搜索
* 实时向量操作
* 图分析集成
## 特性
图向量存储
关系感知搜索
实时操作
图分析
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-neo4j-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Neo4j 向量数据库配置
spring.ai.neo4j.vectordb.enabled=true
spring.ai.neo4j.vectordb.uri=bolt://localhost:7687
spring.ai.neo4j.vectordb.username=neo4j
spring.ai.neo4j.vectordb.password=password
spring.ai.neo4j.vectordb.database=vectordb
```
### 用法
```java theme={"system"}
@Service
public class Neo4jVectorService {
private final Neo4jVectorClient vectorClient;
public Neo4jVectorService(Neo4jVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class Neo4jVectorStorageConfig {
@Bean
public VectorStorage neo4jVectorStorage(Neo4jVectorProperties properties) {
return new Neo4jVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class Neo4jSimilaritySearchConfig {
@Bean
public SimilaritySearch neo4jSimilaritySearch(Neo4jVectorProperties properties) {
return new Neo4jSimilaritySearch(properties);
}
}
```
### 3. 图操作
```java theme={"system"}
@Service
public class GraphService {
private final Neo4jVectorClient vectorClient;
public void createVectorNode(String id, float[] vector) {
vectorClient.createNode(id, vector);
}
public void createRelationship(String fromId, String toId, String type) {
vectorClient.createRelationship(fromId, toId, type);
}
}
```
## 高级特性
### 自定义节点配置
```java theme={"system"}
@Configuration
public class NodeConfig {
@Bean
public NodeConfig nodeConfig() {
return NodeConfig.builder()
.label("Vector")
.properties(Arrays.asList("id", "vector", "metadata"))
.build();
}
}
```
### 索引管理
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector_index")
.type(IndexType.VECTOR)
.dimension(1536)
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=neo4j-vectordb
management.endpoint.neo4j-vectordb.enabled=true
```
## 最佳实践
使用 Neo4j 向量数据库时，请考虑以下最佳实践：
* **图设计**：设计高效的图结构
* **索引管理**：优化索引配置
* **关系策略**：实施有效的关系
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证连接 URI
* 检查身份验证
* 查看网络设置
2. **性能问题**
* 优化图结构
* 调整索引配置
* 查看查询模式
3. **存储问题**
* 监控图大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# OpenSearch 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/opensearch
Spring AI 中的 OpenSearch 向量数据库集成了 OpenSearch 的向量功能，提供向量存储和搜索能力。
## 概述
OpenSearch 向量数据库支持：
* 分布式向量存储
* 全文搜索集成
* 实时向量操作
* 可扩展架构
## 特性
分布式架构
全文搜索
实时操作
水平扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-opensearch-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# OpenSearch 向量数据库配置
spring.ai.opensearch.vectordb.enabled=true
spring.ai.opensearch.vectordb.uri=http://localhost:9200
spring.ai.opensearch.vectordb.username=admin
spring.ai.opensearch.vectordb.password=admin
spring.ai.opensearch.vectordb.index-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class OpenSearchVectorService {
private final OpenSearchVectorClient vectorClient;
public OpenSearchVectorService(OpenSearchVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class OpenSearchVectorStorageConfig {
@Bean
public VectorStorage openSearchVectorStorage(OpenSearchVectorProperties properties) {
return new OpenSearchVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class OpenSearchSimilaritySearchConfig {
@Bean
public SimilaritySearch openSearchSimilaritySearch(OpenSearchVectorProperties properties) {
return new OpenSearchSimilaritySearch(properties);
}
}
```
### 3. 索引管理
```java theme={"system"}
@Service
public class IndexService {
private final OpenSearchVectorClient vectorClient;
public void createIndex(String name, int dimension) {
vectorClient.createIndex(name, dimension);
}
public void deleteIndex(String name) {
vectorClient.deleteIndex(name);
}
}
```
## 高级特性
### 自定义索引配置
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("custom-vectors")
.dimension(1536)
.indexType(IndexType.HNSW)
.metricType(MetricType.COSINE)
.build();
}
}
```
### 映射配置
```java theme={"system"}
@Configuration
public class MappingConfig {
@Bean
public MappingConfig mappingConfig() {
return MappingConfig.builder()
.vectorField("vector")
.metadataFields(Arrays.asList("title", "content"))
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=opensearch-vectordb
management.endpoint.opensearch-vectordb.enabled=true
```
## 最佳实践
使用 OpenSearch 向量数据库时，请考虑以下最佳实践：
* **索引设计**：设计高效的索引结构
* **映射策略**：优化字段映射
* **分片策略**：实施有效的分片
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证连接 URI
* 检查身份验证
* 查看网络设置
2. **性能问题**
* 优化索引配置
* 调整分片策略
* 查看查询模式
3. **存储问题**
* 监控索引大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Oracle 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/oracle
Spring AI 中的 Oracle 向量数据库集成了 Oracle 的向量功能，提供向量存储和搜索能力。
## 概述
Oracle 向量数据库支持：
* 关系型向量存储
* 基于 SQL 的向量操作
* 企业级安全
* 高性能扩展
## 特性
关系型向量存储
企业级特性
高级安全
高性能扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-oracle-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Oracle 向量数据库配置
spring.ai.oracle.vectordb.enabled=true
spring.ai.oracle.vectordb.url=jdbc:oracle:thin:@localhost:1521:XE
spring.ai.oracle.vectordb.username=system
spring.ai.oracle.vectordb.password=oracle
spring.ai.oracle.vectordb.table-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class OracleVectorService {
private final OracleVectorClient vectorClient;
public OracleVectorService(OracleVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class OracleVectorStorageConfig {
@Bean
public VectorStorage oracleVectorStorage(OracleVectorProperties properties) {
return new OracleVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class OracleSimilaritySearchConfig {
@Bean
public SimilaritySearch oracleSimilaritySearch(OracleVectorProperties properties) {
return new OracleSimilaritySearch(properties);
}
}
```
### 3. 表管理
```java theme={"system"}
@Service
public class TableService {
private final OracleVectorClient vectorClient;
public void createTable(String name, int dimension) {
vectorClient.createTable(name, dimension);
}
public void dropTable(String name) {
vectorClient.dropTable(name);
}
}
```
## 高级特性
### 自定义表配置
```java theme={"system"}
@Configuration
public class TableConfig {
@Bean
public TableConfig tableConfig() {
return TableConfig.builder()
.name("custom_vectors")
.vectorColumn("vector")
.metadataColumns(Arrays.asList("title", "content"))
.build();
}
}
```
### 索引管理
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector_idx")
.type(IndexType.VECTOR)
.dimension(1536)
.build();
}
}
```
### 安全配置
```java theme={"system"}
@Configuration
public class SecurityConfig {
@Bean
public SecurityConfig securityConfig() {
return SecurityConfig.builder()
.encryptionEnabled(true)
.auditEnabled(true)
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=oracle-vectordb
management.endpoint.oracle-vectordb.enabled=true
```
## 最佳实践
使用 Oracle 向量数据库时，请考虑以下最佳实践：
* **表设计**：设计高效的表结构
* **索引管理**：优化索引配置
* **安全**：实施适当的安全措施
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证连接 URL
* 检查凭据
* 查看网络设置
2. **性能问题**
* 优化表结构
* 配置索引
* 查看查询模式
3. **存储问题**
* 监控表大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# pgvector 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/pgvector
Spring AI 中的 pgvector 向量数据库集成了 PostgreSQL 的 pgvector 扩展，提供向量存储和搜索能力。
## 概述
pgvector 向量数据库支持：
* 基于 PostgreSQL 的向量存储
* 基于 SQL 的向量操作
* 全文搜索集成
* 事务支持
## 特性
PostgreSQL 集成
基于 SQL 的操作
事务支持
全文搜索
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-pgvector-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# pgvector 向量数据库配置
spring.ai.pgvector.vectordb.enabled=true
spring.ai.pgvector.vectordb.url=jdbc:postgresql://localhost:5432/vectordb
spring.ai.pgvector.vectordb.username=postgres
spring.ai.pgvector.vectordb.password=postgres
spring.ai.pgvector.vectordb.table-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class PgVectorService {
private final PgVectorClient vectorClient;
public PgVectorService(PgVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class PgVectorStorageConfig {
@Bean
public VectorStorage pgVectorStorage(PgVectorProperties properties) {
return new PgVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class PgVectorSimilaritySearchConfig {
@Bean
public SimilaritySearch pgVectorSimilaritySearch(PgVectorProperties properties) {
return new PgVectorSimilaritySearch(properties);
}
}
```
### 3. 表管理
```java theme={"system"}
@Service
public class TableService {
private final PgVectorClient vectorClient;
public void createTable(String name, int dimension) {
vectorClient.createTable(name, dimension);
}
public void dropTable(String name) {
vectorClient.dropTable(name);
}
}
```
## 高级特性
### 自定义表配置
```java theme={"system"}
@Configuration
public class TableConfig {
@Bean
public TableConfig tableConfig() {
return TableConfig.builder()
.name("custom_vectors")
.vectorColumn("vector")
.metadataColumns(Arrays.asList("title", "content"))
.build();
}
}
```
### 索引管理
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("vector_idx")
.type(IndexType.IVFFLAT)
.dimension(1536)
.build();
}
}
```
### 扩展管理
```java theme={"system"}
@Configuration
public class ExtensionConfig {
@Bean
public ExtensionConfig extensionConfig() {
return ExtensionConfig.builder()
.name("vector")
.version("0.5.1")
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=pgvector-vectordb
management.endpoint.pgvector-vectordb.enabled=true
```
## 最佳实践
使用 pgvector 向量数据库时，请考虑以下最佳实践：
* **表设计**：设计高效的表结构
* **索引管理**：优化索引配置
* **扩展版本**：保持 pgvector 更新
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证连接 URL
* 检查凭据
* 查看网络设置
2. **性能问题**
* 优化表结构
* 配置索引
* 查看查询模式
3. **存储问题**
* 监控表大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Pinecone 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/pinecone
Spring AI 中的 Pinecone 向量数据库集成了 Pinecone 基于云的向量功能，提供向量存储和搜索能力。
## 概述
Pinecone 向量数据库支持：
* 基于云的向量存储
* 实时相似性搜索
* 托管服务
* 可扩展架构
## 特性
基于云的存储
托管服务
实时搜索
自动扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-pinecone-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Pinecone 向量数据库配置
spring.ai.pinecone.vectordb.enabled=true
spring.ai.pinecone.vectordb.api-key=your-api-key
spring.ai.pinecone.vectordb.environment=us-west1-gcp
spring.ai.pinecone.vectordb.index-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class PineconeVectorService {
private final PineconeVectorClient vectorClient;
public PineconeVectorService(PineconeVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class PineconeVectorStorageConfig {
@Bean
public VectorStorage pineconeVectorStorage(PineconeVectorProperties properties) {
return new PineconeVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class PineconeSimilaritySearchConfig {
@Bean
public SimilaritySearch pineconeSimilaritySearch(PineconeVectorProperties properties) {
return new PineconeSimilaritySearch(properties);
}
}
```
### 3. 索引管理
```java theme={"system"}
@Service
public class IndexService {
private final PineconeVectorClient vectorClient;
public void createIndex(String name, int dimension) {
vectorClient.createIndex(name, dimension);
}
public void deleteIndex(String name) {
vectorClient.deleteIndex(name);
}
}
```
## 高级特性
### 自定义索引配置
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("custom-vectors")
.dimension(1536)
.metricType(MetricType.COSINE)
.podType(PodType.P1)
.build();
}
}
```
### 命名空间管理
```java theme={"system"}
@Configuration
public class NamespaceConfig {
@Bean
public NamespaceConfig namespaceConfig() {
return NamespaceConfig.builder()
.name("custom-namespace")
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=pinecone-vectordb
management.endpoint.pinecone-vectordb.enabled=true
```
## 最佳实践
使用 Pinecone 向量数据库时，请考虑以下最佳实践：
* **索引设计**：设计高效的索引结构
* **命名空间策略**：有效组织数据
* **API 密钥管理**：保护 API 密钥
* **资源管理**：选择合适的 Pod 类型
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证 API 密钥
* 检查环境
* 查看网络设置
2. **性能问题**
* 优化索引配置
* 调整 Pod 类型
* 查看查询模式
3. **存储问题**
* 监控索引大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Qdrant 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/qdrant
Spring AI 中的 Qdrant 向量数据库集成了 Qdrant 的向量功能，提供向量存储和搜索能力。
## 概述
Qdrant 向量数据库支持：
* 高性能向量存储
* 实时相似性搜索
* 筛选搜索
* 可扩展架构
## 特性
高性能存储
筛选搜索
实时操作
水平扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-qdrant-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Qdrant 向量数据库配置
spring.ai.qdrant.vectordb.enabled=true
spring.ai.qdrant.vectordb.host=localhost
spring.ai.qdrant.vectordb.port=6333
spring.ai.qdrant.vectordb.collection-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class QdrantVectorService {
private final QdrantVectorClient vectorClient;
public QdrantVectorService(QdrantVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class QdrantVectorStorageConfig {
@Bean
public VectorStorage qdrantVectorStorage(QdrantVectorProperties properties) {
return new QdrantVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class QdrantSimilaritySearchConfig {
@Bean
public SimilaritySearch qdrantSimilaritySearch(QdrantVectorProperties properties) {
return new QdrantSimilaritySearch(properties);
}
}
```
### 3. 集合管理
```java theme={"system"}
@Service
public class CollectionService {
private final QdrantVectorClient vectorClient;
public void createCollection(String name, int dimension) {
vectorClient.createCollection(name, dimension);
}
public void deleteCollection(String name) {
vectorClient.deleteCollection(name);
}
}
```
## 高级特性
### 自定义集合配置
```java theme={"system"}
@Configuration
public class CollectionConfig {
@Bean
public CollectionConfig collectionConfig() {
return CollectionConfig.builder()
.name("custom-vectors")
.dimension(1536)
.distanceType(DistanceType.COSINE)
.build();
}
}
```
### 筛选器配置
```java theme={"system"}
@Configuration
public class FilterConfig {
@Bean
public FilterConfig filterConfig() {
return FilterConfig.builder()
.must(Arrays.asList("category", "status"))
.should(Arrays.asList("tags"))
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=qdrant-vectordb
management.endpoint.qdrant-vectordb.enabled=true
```
## 最佳实践
使用 Qdrant 向量数据库时，请考虑以下最佳实践：
* **集合设计**：设计高效的集合结构
* **筛选策略**：优化筛选器配置
* **距离度量**：选择合适的距离度量
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证主机和端口
* 检查网络连接性
* 查看身份验证
2. **性能问题**
* 优化集合配置
* 调整筛选策略
* 查看查询模式
3. **存储问题**
* 监控集合大小
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Redis 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/redis
Spring AI 中的 Redis 向量数据库集成了 Redis 的向量功能，提供向量存储和搜索能力。
## 概述
Redis 向量数据库支持：
* 内存向量存储
* 实时相似性搜索
* 高性能操作
* 可扩展架构
## 特性
内存存储
实时搜索
高性能
水平扩展
## 实现
### 基本设置
```xml theme={"system"}
org.springframework.ai
spring-ai-redis-vectordb
${spring-ai.version}
```
### 配置
```properties theme={"system"}
# Redis 向量数据库配置
spring.ai.redis.vectordb.enabled=true
spring.ai.redis.vectordb.host=localhost
spring.ai.redis.vectordb.port=6379
spring.ai.redis.vectordb.index-name=vectors
```
### 用法
```java theme={"system"}
@Service
public class RedisVectorService {
private final RedisVectorClient vectorClient;
public RedisVectorService(RedisVectorClient vectorClient) {
this.vectorClient = vectorClient;
}
public void storeVector(String id, float[] vector, Map metadata) {
vectorClient.store(id, vector, metadata);
}
public List searchSimilar(float[] queryVector, int k) {
return vectorClient.search(queryVector, k);
}
}
```
## 向量操作
### 1. 向量存储
```java theme={"system"}
@Configuration
public class RedisVectorStorageConfig {
@Bean
public VectorStorage redisVectorStorage(RedisVectorProperties properties) {
return new RedisVectorStorage(properties);
}
}
```
### 2. 相似性搜索
```java theme={"system"}
@Configuration
public class RedisSimilaritySearchConfig {
@Bean
public SimilaritySearch redisSimilaritySearch(RedisVectorProperties properties) {
return new RedisSimilaritySearch(properties);
}
}
```
### 3. 索引管理
```java theme={"system"}
@Service
public class IndexService {
private final RedisVectorClient vectorClient;
public void createIndex(String name, int dimension) {
vectorClient.createIndex(name, dimension);
}
public void dropIndex(String name) {
vectorClient.dropIndex(name);
}
}
```
## 高级特性
### 自定义索引配置
```java theme={"system"}
@Configuration
public class IndexConfig {
@Bean
public IndexConfig indexConfig() {
return IndexConfig.builder()
.name("custom-vectors")
.dimension(1536)
.algorithm(Algorithm.HNSW)
.metricType(MetricType.COSINE)
.build();
}
}
```
### 集群配置
```java theme={"system"}
@Configuration
public class ClusterConfig {
@Bean
public ClusterConfig clusterConfig() {
return ClusterConfig.builder()
.nodes(Arrays.asList("redis-1:6379", "redis-2:6379"))
.build();
}
}
```
### 监控
```properties theme={"system"}
management.endpoints.web.exposure.include=redis-vectordb
management.endpoint.redis-vectordb.enabled=true
```
## 最佳实践
使用 Redis 向量数据库时，请考虑以下最佳实践：
* **内存管理**：配置适当的内存设置
* **索引设计**：设计高效的索引结构
* **集群策略**：实施有效的集群
* **资源管理**：配置资源分配
* **监控**：设置全面的监控
## 故障排除
常见问题及解决方案：
1. **连接问题**
* 验证主机和端口
* 检查网络连接性
* 查看身份验证
2. **性能问题**
* 优化内存设置
* 调整索引配置
* 查看查询模式
3. **存储问题**
* 监控内存使用情况
* 执行清理
* 查看保留策略
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
# Typesense 向量数据库
Source: https://javaai.pig4cloud.com/spring-ai/api/vectordbs/typesense
# Typesense 向量数据库
Spring AI 支持将 [Typesense](https://typesense.org/) 作为向量数据库。
## 添加依赖
要使用 Typesense 向量存储，您需要将 `spring-ai-typesense-store-spring-boot-starter` 依赖项添加到项目的 `pom.xml` 文件中。
该启动器包含了 `spring-ai-core` 和 Typesense Java 客户端库。
```xml theme={"system"}
org.springframework.ai
spring-ai-typesense-store-spring-boot-starter
```
您还需要一个 `EmbeddingClient` 实现来为您的文档生成向量嵌入。例如，您可以添加 `spring-ai-openai-spring-boot-starter` 以使用 OpenAI 的嵌入模型：
```xml theme={"system"}
org.springframework.ai
spring-ai-openai-spring-boot-starter
```
## 配置属性
在您的 `application.properties` 或 `application.yml` 文件中配置 Typesense 和嵌入客户端属性。
### Typesense 属性
| 属性 | 描述 | 默认值 |
| :---------------------------------------------------- | :------------------------------------------- | :----------------------------------- |
| `spring.ai.vectorstore.typesense.collection-name` | 用于存储文档的 Typesense 集合名称。 | `spring_ai_collection` |
| `spring.ai.vectorstore.typesense.embedding-dimension` | 嵌入向量的维度。必须与 `EmbeddingClient` 生成的维度匹配。 | 1536 (OpenAI text-embedding-ada-002) |
| `spring.ai.vectorstore.typesense.host` | Typesense 服务器的主机名或 IP 地址。 | `localhost` |
| `spring.ai.vectorstore.typesense.port` | Typesense 服务器的端口。 | `8108` |
| `spring.ai.vectorstore.typesense.protocol` | 用于连接到 Typesense 服务器的协议 (例如 `http` 或 `https`) | `http` |
| `spring.ai.vectorstore.typesense.api-key` | 用于向 Typesense 服务器进行身份验证的 API 密钥。 | |
**示例 `application.properties`:**
```properties theme={"system"}
# Typesense 配置
spring.ai.vectorstore.typesense.collection-name=my_documents
spring.ai.vectorstore.typesense.embedding-dimension=1536
spring.ai.vectorstore.typesense.host=localhost
spring.ai.vectorstore.typesense.port=8108
spring.ai.vectorstore.typesense.protocol=http
spring.ai.vectorstore.typesense.api-key=YOUR_TYPESENSE_API_KEY
# 嵌入客户端配置 (例如 OpenAI)
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002
```
确保 `spring.ai.vectorstore.typesense.embedding-dimension` 与您正在使用的 `EmbeddingClient` 输出的嵌入维度相匹配。
## 使用 `VectorStore`
将 `VectorStore` bean 注入到您的组件中以与之交互：
```java theme={"system"}
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.document.Document;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class MyVectorStoreService {
private final VectorStore vectorStore; // 将自动配置 TypesenseVectorStore
@Autowired
public MyVectorStoreService(VectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public void addDocuments(List documents) {
vectorStore.add(documents);
}
public List findSimilarDocuments(String query, int k) {
return vectorStore.similaritySearch(query, k);
}
}
```
### 创建 `TypesenseVectorStore` Bean (可选)
Spring Boot 会自动配置 `TypesenseVectorStore` bean。但是，如果您需要自定义配置，可以定义自己的 bean：
```java theme={"system"}
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.vectorstore.TypesenseVectorStore;
import org.springframework.ai.vectorstore.TypesenseVectorStore.TypesenseVectorStoreConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.typesense.api.Client;
import org.typesense.api.ConfigurationNode;
import java.util.List;
@Configuration
public class MyTypesenseConfig {
@Bean
public Client typesenseClient() {
// 从属性或直接创建 TypesenseClient
List nodes = List.of(
new ConfigurationNode("localhost", "8108", "http")
);
// 如果需要 API 密钥:
// org.typesense.api.Configuration configuration = new org.typesense.api.Configuration(nodes, java.time.Duration.ofSeconds(10), "YOUR_TYPESENSE_API_KEY");
org.typesense.api.Configuration configuration = new org.typesense.api.Configuration(nodes, java.time.Duration.ofSeconds(10), "YOUR_TYPESENSE_API_KEY");
return new Client(configuration);
}
@Bean
public TypesenseVectorStore typesenseVectorStore(Client typesenseClient, EmbeddingClient embeddingClient) {
TypesenseVectorStoreConfig config = TypesenseVectorStoreConfig.builder()
.withCollectionName("my_custom_collection")
.withEmbeddingDimension(1536)
.build();
return new TypesenseVectorStore(typesenseClient, embeddingClient, config);
}
}
```
## 元数据过滤
Typesense 向量存储支持使用 [Typesense 的 filter\_by 查询参数](https://typesense.org/docs/0.25.2/api/vector-search.html#filter-results) 和 Spring AI 的 [相似性搜索过滤器表达式](./index.mdx#metadata-filtering) 进行元数据过滤。
过滤器表达式会转换为 Typesense 的 `filter_by` 字符串格式。
**示例：**
```java theme={"system"}
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;
// ...
FilterExpressionBuilder b = new FilterExpressionBuilder();
// genre:='drama' && year:>2020
Filter filter = new Filter(b.eq("genre", "drama").and(b.gt("year", 2020)).build());
SearchRequest request = SearchRequest.query("A dramatic film released after 2020") // 示例查询通常保留英文
.withTopK(5)
.withFilter(filter);
List results = vectorStore.similaritySearch(request);
```