Anthropic 3
本站(springdoc.cn)中的内容来源于 spring.io ,原始版权归属于 spring.io。由 springdoc.cn 进行翻译,整理。可供个人学习、研究,未经许可,不得进行任何转载、商用或与之相关的行为。 商标声明:Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。 |
Anthropic Claude 是一系列基础 AI 模型,可应用于多种场景。开发者和企业可通过 API 直接接入,基于 Anthropic 的 AI 基础设施 进行构建。
Spring AI 支持 Anthropic Messaging API,可实现同步及流式文本生成功能。
Anthropic 的 Claude 模型也可通过 Amazon Bedrock Converse 服务调用。Spring AI 同时提供了专用于 Amazon Bedrock Converse 的 Anthropic 客户端实现。 |
先决条件
需要在 Anthropic 平台创建 API 密钥。
在 Anthropic API 仪表盘 创建账户,并在 Get API Keys 页面生成API密钥。
Spring AI 项目定义了一个名为 spring.ai.anthropic.api-key
的配置属性,你应将其设置为从 anthropic.com
获取的 API Key
值。
在 application.properties
文件中设置该配置属性:
spring.ai.anthropic.api-key=<your-anthropic-api-key>
为增强处理敏感信息(如 API 密钥)时的安全性,你可以使用 Spring 表达式语言(SpEL)引用自定义环境变量:
# In application.yml
spring:
ai:
anthropic:
api-key: ${ANTHROPIC_API_KEY}
# In your environment or .env file
export ANTHROPIC_API_KEY=<your-anthropic-api-key>
你还可以在应用程序代码中以编程方式设置此配置:
// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("ANTHROPIC_API_KEY");
自动配置
Spring AI 自动配置和 starter 模块的构件名称发生了重大变更。更多信息请参阅 升级说明。 |
Spring AI 为 Anthropic Chat Client 提供了 Spring Boot 自动配置。要启用该功能,请将以下依赖添加到项目的 Maven pom.xml
或 Gradle build.gradle
文件中:
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-anthropic</artifactId>
</dependency>
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-anthropic'
}
参考 依赖管理 章节将 Spring AI BOM 添加到你的构建文件。 |
聊天熟悉
重试属性
前缀 spring.ai.retry
用于配置 Anthropic 聊天模型的重试机制属性。
属性 | 说明 | 默认 |
---|---|---|
spring.ai.retry.max-attempts |
最大重试次数 |
10 |
spring.ai.retry.backoff.initial-interval |
指数退避策略的初始休眠时长 |
2 sec. |
spring.ai.retry.backoff.multiplier |
退避间隔乘数 |
5 |
spring.ai.retry.backoff.max-interval |
最大退避时长 |
3 min. |
spring.ai.retry.on-client-errors |
若为 |
false |
spring.ai.retry.exclude-on-http-codes |
不应触发重试的 HTTP 状态码列表(例如用于抛出 |
空 |
spring.ai.retry.on-http-codes |
应触发重试的 HTTP 状态码列表(例如用于抛出 |
空 |
当前重试策略不适用于流式 API |
连接属性
前缀 spring.ai.anthropic
用于配置连接至 Anthropic 的属性参数。
属性 | 说明 | 默认值 |
---|---|---|
spring.ai.anthropic.base-url |
要连接到的 URL |
|
spring.ai.anthropic.completions-path |
要附加到基础URL的路径 |
|
spring.ai.anthropic.version |
Anthropic API 版本号 |
2023-06-01 |
spring.ai.anthropic.api-key |
API Key |
- |
spring.ai.anthropic.beta-version |
启用新功能/实验功能。如果设置为 |
|
配置属性
聊天自动配置的启用/禁用现在通过顶级属性
此项变更是为了支持多模型配置。 |
前缀 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 聊天模型。支持以下模型: |
|
spring.ai.anthropic.chat.options.temperature |
用于控制生成内容表观创造力的采样温度值。数值越高输出越随机,数值越低结果越集中且确定。不建议在同一个补全请求中同时修改 |
0.8 |
spring.ai.anthropic.chat.options.max-tokens |
聊天补全中生成的最大 Token 数量。输入 Token 和生成 Token 的总长度受模型上下文长度限制 |
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 |
使用核采样(nucleus sampling)。在核采样中,我们会按概率降序计算每个后续 Token 所有选项的累积分布,当达到 top_p 指定的特定概率阈值时截断。你应该只调整 temperature 或 top_p 中的一个参数,而非同时修改两者。该参数仅推荐高级使用场景,通常只需使用 temperature 即可。 |
- |
spring.ai.anthropic.chat.options.top-k |
仅从每个后续 Token 的前 K 个选项中采样。用于消除 “长尾” 低概率响应(此处可了解更多技术细节)。该参数仅推荐高级使用场景,通常只需使用 temperature 即可。 |
- |
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 |
(已弃用 - 由 |
函数名称列表,用于在单次提示请求中启用函数调用功能。这些名称对应的函数必须已注册在 functionCallbacks 函数回调注册表中。 |
- |
(已弃用 - 由 |
注册到 ChatModel 的工具函数回调。 |
- |
(已弃用 - 由否定的 |
若为 true,Spring AI 不会内部处理函数调用,而是将其代理给客户端。此时客户端需负责处理函数调用、分派至对应函数并返回结果。若为 |
false |
spring.ai.anthropic.chat.options.http-headers |
可选的 HTTP 请求头,将添加到聊天补全请求中。 |
- |
所有以 spring.ai.anthropic.chat.options 为前缀的属性,都可通过在 Prompt 调用中添加特定请求的 运行时选项 进行覆盖。
|
运行时选项
AnthropicChatOptions.java 提供模型配置参数,包括使用的模型名称、温度值、最大 Token 数量等。
在启动时,默认选项可通过 AnthropicChatModel(api, options)
构造函数或 spring.ai.anthropic.chat.options.*
属性进行配置。
在运行时,你可以通过向 Prompt
调用添加新的、特定于请求的选项来覆盖默认配置。例如,要针对特定请求覆盖默认模型和温度参数:
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
AnthropicChatOptions.builder()
.model("claude-3-7-sonnet-latest")
.temperature(0.4)
.build()
));
除了模型专用的 AnthropicChatOptions 外,你还可以使用通过 ChatOptionsBuilder#builder() 创建的通用 ChatOptions 实例 |
工具/函数调用
你可以向 AnthropicChatModel
注册自定义 Java 工具,使 Anthropic Claude 模型能智能选择输出包含参数的 JSON 对象来调用一个或多个已注册函数。该技术能有效将大语言模型能力与外部工具及 API 连接,详见 工具调用文档。
多模态
多模态指模型能同时理解并处理来自文本、PDF、图像、数据格式等多种来源信息的能力。
图像
当前 Anthropic Claude 3 支持 base64
编码的图像源类型,媒体类型涵盖 image/jpeg
、image/png
、image/gif
和 image/webp
(详见 视觉指南)。Anthropic Claude 3.5 Sonnet 还支持 application/pdf
文件的 pdf
源类型。
Spring AI 的 Message
接口通过引入 Media
类型支持多模态 AI 模型。该类型包含有关消息中媒体附件的数据和信息,使用了 Spring 的 org.springframework.util.MimeType
和一个 java.lang.Object
来表示原始媒体数据。
以下是摘自 AnthropicChatModelIT.java 的一个简单代码示例,演示了如何将用户文本与图像进行组合:
var imageData = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage("Explain what do you see on this picture?",
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
图像作为输入:

连同文本消息 “Explain what do you see on this picture?”,并生成类似如下的响应:
The image shows a close-up view of a wire fruit basket containing several pieces of fruit. ...
Sonnet 3.5 开始提供 PDF(测试版)。使用 application/pdf
媒体类型将 PDF 文件附加到消息中:
var pdfData = new ClassPathResource("/spring-ai-reference-overview.pdf");
var userMessage = new UserMessage(
"You are a very professional document summarization specialist. Please summarize the given document.",
List.of(new Media(new MimeType("application", "pdf"), pdfData)));
var response = this.chatModel.call(new Prompt(List.of(userMessage)));
示例 Controller
创建 一个新的 Spring Boot 项目,并将 spring-ai-starter-model-anthropic
添加到你的 pom(或 gradle)依赖项中。
在 src/main/resources
目录下添加一个 application.properties
文件,以启用并配置 Anthropic 聊天模型:
spring.ai.anthropic.api-key=YOUR_API_KEY
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
类示例。
@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 = "Tell me a joke") String message) {
return Map.of("generation", this.chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
手动配置
AnthropicChatModel 实现了 ChatModel
和 StreamingChatModel
,并使用 低级的 AnthropicApi 客户端 连接到 Anthropic 服务。
将 spring-ai-anthropic
依赖项添加到你项目的 Maven pom.xml
文件中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-anthropic</artifactId>
</dependency>
或添加到你的 Gradle build.gradle
构建文件中:
dependencies {
implementation 'org.springframework.ai:spring-ai-anthropic'
}
请参阅 依赖管理 部分,将 Spring AI BOM 添加到你的构建文件中。 |
接下来,创建一个 AnthropicChatModel
并将其用于文本生成:
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("Generate the names of 5 famous pirates."));
// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
new Prompt("Generate the names of 5 famous pirates."));
AnthropicChatOptions
为聊天请求提供配置信息。AnthropicChatOptions.Builder
是一个 Fluent 式选项构建器。
低级的 AnthropicApi 客户端
AnthropicApi 为 Anthropic Message API 提供了一个轻量级的 Java 客户端。
以下类图说明了 AnthropicApi
的聊天接口和构建模块:


以下是一个以编程方式使用该 API 的简单代码片段:
AnthropicApi anthropicApi =
new AnthropicApi(System.getenv("ANTHROPIC_API_KEY"));
AnthropicMessage chatCompletionMessage = new AnthropicMessage(
List.of(new ContentBlock("Tell me a Joke?")), Role.USER);
// Sync request
ResponseEntity<ChatCompletionResponse> response = this.anthropicApi
.chatCompletionEntity(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_3_OPUS.getValue(),
List.of(this.chatCompletionMessage), null, 100, 0.8, false));
// Streaming request
Flux<StreamResponse> response = this.anthropicApi
.chatCompletionStream(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_3_OPUS.getValue(),
List.of(this.chatCompletionMessage), null, 100, 0.8, true));
请参考 AnthropicApi.java 的 JavaDoc 以获取更多信息。
低级 API 示例
AnthropicApiIT.java 测试提供了一些如何使用该轻量级库的通用示例。