4.2 Spring AI Anthropic Claude

吴祖贤
45 阅读13分钟

Spring AI Anthropic Claude

概述

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仪表板上创建账户，并在获取API密钥页面上生成API密钥。

Spring AI项目定义了一个名为spring.ai.anthropic.api-key的配置属性，您应该将其设置为从anthropic.com获得的API密钥的值。

您可以在application.properties文件中设置此配置属性：

spring.ai.anthropic.api-key=<your-anthropic-api-key>

为了在处理API密钥等敏感信息时增强安全性，您可以使用Spring表达式语言（SpEL）来引用自定义环境变量：

# 在application.yml中
spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}

# 在您的环境或.env文件中
export ANTHROPIC_API_KEY=<your-anthropic-api-key>

您也可以在应用程序代码中以编程方式获取此配置：

// 从安全来源或环境变量检索API密钥
String apiKey = System.getenv("ANTHROPIC_API_KEY");

添加仓库和BOM

Spring AI工件发布在Maven Central和Spring Snapshot仓库中。请参考工件仓库部分将这些仓库添加到您的构建系统。

为了帮助依赖管理，Spring AI提供了BOM（物料清单）以确保在整个项目中使用一致的Spring AI版本。请参考依赖管理部分将Spring AI BOM添加到您的构建系统。

自动配置

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

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

Maven

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

Gradle

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 秒
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要连接的URLapi.anthropic.com
spring.ai.anthropic.completions-path要附加到基础URL的路径/v1/chat/completions
spring.ai.anthropic.versionAnthropic API版本2023-06-01
spring.ai.anthropic.api-keyAPI密钥-
spring.ai.anthropic.beta-version启用新/实验性功能。如果设置为max-tokens-3-5-sonnet-2024-07-15，输出token限制从4096增加到8192个token（仅适用于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-opus-4-0, claude-sonnet-4-0, 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, claude-sonnet-4-20250514, claude-opus-4-1-20250805claude-opus-4-20250514
spring.ai.anthropic.chat.options.temperature要使用的采样温度，控制生成完成内容的明显创造性。较高的值将使输出更加随机，而较低的值将使结果更加聚焦和确定性。不建议对同一个完成请求修改temperature和top_p，因为这两个设置的相互作用难以预测。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使用核心采样。在核心采样中，我们计算所有选项的累积分布，按概率递减顺序排列每个后续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
(已弃用 - 被toolNames替换) spring.ai.anthropic.chat.options.functions要在单个提示请求中启用函数调用的函数列表，通过其名称标识。具有这些名称的函数必须存在于functionCallbacks注册表中。-
(已弃用 - 被toolCallbacks替换) spring.ai.anthropic.chat.options.functionCallbacks要注册到ChatModel的工具函数回调。-
(已弃用 - 被取反的internal-tool-execution-enabled替换) spring.ai.anthropic.chat.options.proxy-tool-calls如果为true，Spring AI将不会内部处理函数调用，而是将它们代理给客户端。然后客户端负责处理函数调用，将它们分派给适当的函数，并返回结果。如果为false（默认值），Spring AI将内部处理函数调用。仅适用于具有函数调用支持的聊天模型false
spring.ai.anthropic.chat.options.http-headers要添加到聊天完成请求的可选HTTP头。-

有关模型别名及其描述的最新列表，请参阅官方Anthropic模型别名文档。

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

运行时选项

AnthropicChatOptions.java提供模型配置，如要使用的模型、温度、最大token数等。

在启动时，可以使用AnthropicChatModel(api, options)构造函数或spring.ai.anthropic.chat.options.*属性配置默认选项。

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

ChatResponse response = chatModel.call(
    new Prompt(
        "生成5个著名海盗的名字。",
        AnthropicChatOptions.builder()
            .model("claude-3-7-sonnet-latest")
            .temperature(0.4)
        .build()
    ));

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

思考功能（Thinking）

Anthropic Claude模型支持"思考"功能，允许模型在提供最终答案之前显示其推理过程。此功能启用更透明和详细的问题解决，特别是对于需要逐步推理的复杂问题。

支持的模型

思考功能由以下Claude模型支持：

  • Claude 4模型（claude-opus-4-20250514, claude-sonnet-4-20250514）
  • Claude 3.7 Sonnet（claude-3-7-sonnet-20250219）

模型能力：

  • Claude 3.7 Sonnet: 返回完整的思考输出。行为一致但不支持总结或交错思考。
  • Claude 4模型: 支持总结思考、交错思考和增强的工具集成。

API请求结构在所有支持的模型中相同，但输出行为有所不同。

思考配置

要在任何支持的Claude模型上启用思考，请在您的请求中包含以下配置：

必需配置

添加thinking对象：

"type": "enabled"

budget_tokens: 推理的token限制（建议从1024开始）

Token预算规则：

  • budget_tokens必须通常小于max_tokens
  • Claude可能使用比分配更少的token
  • 更大的预算增加推理深度但可能影响延迟

当使用带有交错思考的工具使用时（仅Claude 4），此约束被放宽，但在Spring AI中尚不支持。

关键考虑因素

  • Claude 3.7在响应中返回完整的思考内容
  • Claude 4返回模型内部推理的总结版本以减少延迟并保护敏感内容
  • 思考token作为输出token的一部分计费（即使并非所有都在响应中可见）
  • 交错思考仅在Claude 4模型上可用，并需要beta头interleaved-thinking-2025-05-14

工具集成和交错思考

Claude 4模型支持带有工具使用的交错思考，允许模型在工具调用之间进行推理。

当前的Spring AI实现分别支持基本思考和工具使用，但尚不支持带有工具使用的交错思考（思考在多个工具调用中继续）。

有关带有工具使用的交错思考的详细信息，请参阅Anthropic文档。

非流式示例

以下是使用ChatClient API在非流式请求中启用思考的方法：

ChatClient chatClient = ChatClient.create(chatModel);

// 对于Claude 3.7 Sonnet - 需要明确的思考配置
ChatResponse response = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-3-7-sonnet-latest")
        .temperature(1.0)  // 启用思考时温度应设置为1
        .maxTokens(8192)
        .thinking(AnthropicApi.ThinkingType.ENABLED, 2048)  // 必须 ≥1024 && < max_tokens
        .build())
    .user("是否存在无限多个素数使得 n mod 4 == 3？")
    .call()
    .chatResponse();

// 对于Claude 4模型 - 默认启用思考
ChatResponse response4 = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-opus-4-0")
        .maxTokens(8192)
        // 不需要明确的思考配置
        .build())
    .user("是否存在无限多个素数使得 n mod 4 == 3？")
    .call()
    .chatResponse();

// 处理可能包含思考内容的响应
for (Generation generation : response.getResults()) {
    AssistantMessage message = generation.getOutput();
    if (message.getText() != null) {
        // 常规文本响应
        System.out.println("文本响应: " + message.getText());
    }
    else if (message.getMetadata().containsKey("signature")) {
        // 思考内容
        System.out.println("思考: " + message.getMetadata().get("thinking"));
        System.out.println("签名: " + message.getMetadata().get("signature"));
    }
}

流式示例

您也可以将思考与流式响应一起使用：

ChatClient chatClient = ChatClient.create(chatModel);

// 对于Claude 3.7 Sonnet - 明确的思考配置
Flux<ChatResponse> responseFlux = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-3-7-sonnet-latest")
        .temperature(1.0)
        .maxTokens(8192)
        .thinking(AnthropicApi.ThinkingType.ENABLED, 2048)
        .build())
    .user("是否存在无限多个素数使得 n mod 4 == 3？")
    .stream();

// 对于Claude 4模型 - 默认启用思考
Flux<ChatResponse> responseFlux4 = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-opus-4-0")
        .maxTokens(8192)
        // 不需要明确的思考配置
        .build())
    .user("是否存在无限多个素数使得 n mod 4 == 3？")
    .stream();

// 对于流式传输，您可能只想收集文本响应
String textContent = responseFlux.collectList()
    .block()
    .stream()
    .map(ChatResponse::getResults)
    .flatMap(List::stream)
    .map(Generation::getOutput)
    .map(AssistantMessage::getText)
    .filter(text -> text != null && !text.isBlank())
    .collect(Collectors.joining());

工具使用集成

Claude 4模型集成了思考和工具使用能力：

  • Claude 3.7 Sonnet: 支持思考和工具使用，但它们分开操作并需要更明确的配置
  • Claude 4模型: 本质上交错思考和工具使用，在工具交互期间提供更深入的推理

使用思考的好处

思考功能提供了几个好处：

  • 透明度: 查看模型的推理过程以及它如何得出结论
  • 调试: 识别模型可能在何处犯逻辑错误
  • 教育: 使用逐步推理作为教学工具
  • 复杂问题解决: 在数学、逻辑和推理任务上获得更好的结果

请注意，启用思考需要更高的token预算，因为思考过程本身会消耗您分配中的token。

工具/函数调用

您可以使用AnthropicChatModel注册自定义Java工具，并让Anthropic Claude模型智能地选择输出包含调用一个或多个注册函数的参数的JSON对象。这是将LLM能力与外部工具和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("解释您在这张图片中看到了什么？",
        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图像作为输入：

Multimodal Test Image

以及文本消息"解释您在这张图片中看到了什么？"，并生成类似以下的响应：

图像显示了一个金属丝水果篮的特写视图，其中包含几块水果。
...

PDF

从Sonnet 3.5开始提供PDF支持（测试版）。使用application/pdf媒体类型将PDF文件附加到消息：

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

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

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

示例控制器

创建一个新的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 anthropicChatOptions = AnthropicChatOptions.builder()
            .model("claude-3-7-sonnet-20250219")
            .temperature(0.4)
            .maxTokens(200)
        .build()
var chatModel = AnthropicChatModel.builder().anthropicApi(anthropicApi)
                .defaultOptions(anthropicChatOptions).build();

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

// 或使用流式响应
Flux<ChatResponse> response = this.chatModel.stream(
    new Prompt("生成5个著名海盗的名字。"));

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

低级AnthropicApi客户端

AnthropicApi提供了用于Anthropic Message API的轻量级Java客户端。

以下类图说明了AnthropicApi聊天接口和构建块：

AnthropicApi Class Diagram

这是一个简单的代码片段，展示如何以编程方式使用api：

AnthropicApi anthropicApi =
    new AnthropicApi(System.getenv("ANTHROPIC_API_KEY"));

AnthropicMessage chatCompletionMessage = new AnthropicMessage(
        List.of(new ContentBlock("给我讲个笑话？")), Role.USER);

// 同步请求
ResponseEntity<ChatCompletionResponse> response = this.anthropicApi
    .chatCompletionEntity(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_3_OPUS.getValue(),
            List.of(this.chatCompletionMessage), null, 100, 0.8, false));

// 流式请求
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测试提供了一些如何使用轻量级库的一般示例。

avatar
文章
阅读
粉丝