Anthropic Chat

Anthropic Claude 是一系列基础 AI 模型,可用于各种应用。 对于开发者和企业,您可以利用 API 访问并直接在 Anthropic 的 AI 基础设施之上进行构建。 Spring AI 支持 Anthropic 消息 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=<您的 Anthropic API 密钥>

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

# 在 application.yml 中
spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
# 在您的环境或 .env 文件中
export ANTHROPIC_API_KEY=<您的 Anthropic API 密钥>

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

// 从安全来源或环境变量中检索 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 Chat 客户端提供了 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 秒

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

不应触发重试(例如,抛出 NonTransientAiException)的 HTTP 状态代码列表。

spring.ai.retry.on-http-codes

应触发重试(例如,抛出 TransientAiException)的 HTTP 状态代码列表。

目前重试策略不适用于流式 API。

连接属性

前缀 spring.ai.anthropic 用作属性前缀,允许您连接到 Anthropic。

属性 描述 默认值

spring.ai.anthropic.base-url

要连接的 URL

[role="bare"][role="bare"][role="bare"]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,则输出令牌限制从 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-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-20250805

claude-opus-4-20250514

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

(已弃用 - 已替换为 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 提供了模型配置,例如要使用的模型、温度、最大令牌计数等。

在启动时,可以使用 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 实例。

思维

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

支持的模型 思维功能受以下 Claude 模型支持:

  • Claude 4 模型 (claude-opus-4-20250514claude-sonnet-4-20250514)

  • Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)

模型能力:

  • Claude 3.7 Sonnet:返回完整的思维输出。行为一致,但不支持摘要或交错思维。

  • Claude 4 模型:支持摘要思维、交错思维和增强的工具集成。

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

思维配置

要在任何受支持的 Claude 模型上启用思维,请在您的请求中包含以下配置:

必需配置

  1. 添加 thinking 对象

    • "type": "enabled"

    • budget_tokens:推理的令牌限制(建议从 1024 开始)

  2. 令牌预算规则

    • budget_tokens 通常必须小于 max_tokens

    • Claude 可能会使用比分配的更少的令牌

    • 更大的预算会增加推理深度,但可能会影响延迟

    • 当使用交错思维的工具使用时(仅限 Claude 4),此限制会放宽,但 Spring AI 尚不支持。

关键注意事项

  • Claude 3.7 在响应中返回完整的思维内容

  • Claude 4 返回模型内部推理的*摘要*版本,以减少延迟并保护敏感内容

  • 思维令牌是可计费的,作为输出令牌的一部分(即使并非所有都可见于响应中)

  • *交错思维*仅在 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 模型:原生交错思维和工具使用,在工具交互过程中提供更深入的推理

使用思维的好处

思维功能提供了以下几个好处:

  1. 透明性:查看模型的推理过程以及它如何得出结论

  2. 调试:识别模型可能出现逻辑错误的地方

  3. 教育:将逐步推理作为教学工具

  4. 复杂问题解决:在数学、逻辑和推理任务上获得更好的结果

请注意,启用思维需要更高的令牌预算,因为思维过程本身会消耗您分配的令牌。

工具/函数调用

您可以使用 AnthropicChatModel 注册自定义 Java 工具,并让 Anthropic Claude 模型智能地选择输出一个 JSON 对象,其中包含调用一个或多个已注册函数的参数。 这是一种将 LLM 功能与外部工具和 API 连接起来的强大技术。 阅读有关 工具调用 的更多信息。

多模态

多模态是指模型同时理解和处理来自各种来源信息的能力,包括文本、PDF、图像、数据格式。

图像

目前,Anthropic Claude 3 支持 imagesbase64 源类型,以及 image/jpegimage/pngimage/gifimage/webp 媒体类型。 有关更多信息,请查阅 视觉指南。 Anthropic Claude 3.5 Sonnet 还支持 application/pdf 文件的 pdf 源类型。

Spring AI 的 Message 接口通过引入媒体类型支持多模态 AI 模型。 此类型包含消息中媒体附件的数据和信息,使用 Spring 的 org.springframework.util.MimeTypejava.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

以及文本消息“解释一下你在这张图片上看到了什么?”,并生成类似以下内容的响应:

图像显示了一个装有几片水果的铁丝水果篮的特写。
...

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=您的_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 类的示例,它使用聊天模型进行文本生成。

@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<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "讲个笑话") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

手动配置

AnthropicChatModel 实现了 ChatModelStreamingChatModel,并使用 低级 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 消息 API 的轻量级 Java 客户端。

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

anthropic claude3 class diagram
anthropic claude3 events model

这是一个如何以编程方式使用 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 示例