Anthropic

Anthropic Chat

Anthropic Claude 是一系列可用于各种应用的基础 AI 模型。对于开发人员和企业，您可以利用 API 访问权限，直接在 Anthropic 的 AI 基础设施之上进行构建。

Spring AI 支持 Anthropic Claude API, 用于同步和流文本生成。

前提条件（Prerequisites）

您需要在 Anthropic 门户上创建一个 API 密钥。

在 Anthropic API 控制台中创建一个账户，并在 “获取 API 密钥” 页面上生成 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}

您也可以在 application 代码中以编程方式获取这个配置：

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("ANTHROPIC_API_KEY");

添加存储库和 BOM

Spring AI 构件发布在 Maven Central 和 Spring Snapshot 存储库中。请参阅 Artifact 存储库部分，将这些存储库添加到构建系统中。

为了帮助进行依赖管理，Spring AI 提供了一个 BOM (材料清单), 以确保在整个项目中使用一致的 Spring AI 版本。请参阅 “依赖管理” 部分，将 Spring AI BOM 添加到你的构建系统中。

自动配置（Auto-configuration）

Spring AI 为 Anthropic Chat 客户端提供 Spring Boot 自动配置功能。要使其能够将以下依赖关系添加到项目的 Maven pom.xml或 Gradle build.gradle build文件中，请执行以下操作：

• Maven

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

• Gradle

  dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-anthropic'
  }

聊天属性（Chat Properties）

Retry 属性（Retry Properties）

前缀 spring.ai.retry 用作属性前缀，允许您为 Anthropic Chat 模型配置 retry 机制。

连接属性（Connection Properties）

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

配置属性（Configuration Properties）

前缀 spring.ai.anthropic.chat 是为 Anthropic 配置 ChatModel 实现的属性前缀。

运行时选项（Runtime Options ）

Anthropicchatoptions.java 提供模型配置，例如要使用的 temperature、maxToken、topP 等。

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

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

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()
    ));

思考（Thinking）

Claude 模型支持 “Thinking” 功能，该功能允许模型在给出最终答案之前展示其推理过程。这个功能使问题解决更加透明和详细，特别是对于需要逐步推理的复杂问题。

支持的模型
以下 Claude 模型支持 “Thinking” 功能：

• Claude 4 models (clade-opus-4-20250514,clade-sonet-4-20250514)
• Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
  模型能力：
• Claude 3.7 Sonnet: 返回完整的思维输出。行为一致，但不支持总结性或交织性思维。
• Claude 4 models: 支持汇总思维、交织思维和增强的工具集成。
  API 请求结构在所有支持的模型中都是相同的，但输出行为各不相同。

思考配置（Thinking Configuration）

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

必要配置

• 1、添加思考对象：
  • “type”: “enabled”
  • budget_tokens: 推理的 token 限制 (建议从 1024 开始)
• 2、Token 预算规则：
  • budget_tokens 通常必须小于 max_tokens
  • Claude 可能使用比分配的 token 更少的 token
  • 更大的预算会增加推理深度，但可能会影响延迟
  • 当使用工具并进行交错思维时 (仅限 Claude 4), 这种约束会放松，但 Spring AI 尚未支持。

    关键考虑

• Claude 3.7 在响应中返回完整的思考内容
• Claude 4 返回模型内部推理的摘要版本，以减少延迟并保护敏感内容
• 思维令牌作为输出令牌的一部分可计费 (即使在响应中并非所有令牌都可见)
• Interleaved Thinking 仅在 Claude 4 模型上可用，需要 beta 标头 Interleaved-thinking-2025-05-14

  工具集成和交织思维

• Claude 4 模型支持交织思维和工具使用，允许模型在工具调用之间进行推理。

非流示例（Non-streaming Example）

以下是如何使用 ChatClient API 在非流请求中启用思考功能：

ChatClient chatClient = ChatClient.create(chatModel);

// For Claude 3.7 Sonnet - explicit thinking configuration required
ChatResponse response = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-3-7-sonnet-latest")
        .temperature(1.0)  // Temperature should be set to 1 when thinking is enabled
        .maxTokens(8192)
        .thinking(AnthropicApi.ThinkingType.ENABLED, 2048)  // Must be ≥1024 && < max_tokens
        .build())
    .user("Are there an infinite number of prime numbers such that n mod 4 == 3?")
    .call()
    .chatResponse();

// For Claude 4 models - thinking is enabled by default
ChatResponse response4 = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-opus-4-0")
        .maxTokens(8192)
        // No explicit thinking configuration needed
        .build())
    .user("Are there an infinite number of prime numbers such that n mod 4 == 3?")
    .call()
    .chatResponse();

// Process the response which may contain thinking content
for (Generation generation : response.getResults()) {
    AssistantMessage message = generation.getOutput();
    if (message.getText() != null) {
        // Regular text response
        System.out.println("Text response: " + message.getText());
    }
    else if (message.getMetadata().containsKey("signature")) {
        // Thinking content
        System.out.println("Thinking: " + message.getMetadata().get("thinking"));
        System.out.println("Signature: " + message.getMetadata().get("signature"));
    }
}

流式处理示例（Streaming Example）

您也可以将思考与流式响应结合使用：

ChatClient chatClient = ChatClient.create(chatModel);

// For Claude 3.7 Sonnet - explicit thinking configuration
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("Are there an infinite number of prime numbers such that n mod 4 == 3?")
    .stream();

// For Claude 4 models - thinking is enabled by default
Flux<ChatResponse> responseFlux4 = chatClient.prompt()
    .options(AnthropicChatOptions.builder()
        .model("claude-opus-4-0")
        .maxTokens(8192)
        // No explicit thinking configuration needed
        .build())
    .user("Are there an infinite number of prime numbers such that n mod 4 == 3?")
    .stream();

// For streaming, you might want to collect just the text responses
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());

工具使用集成（ Tool Use Integration）

Claude 4 模型整合了思考和工具使用能力：

• Claude 3.7 Sonnet: 支持思考和工具使用，但它们各自独立运作，需要更明确的配置
• Claude 4 models: 本质上将思维和工具使用交织在一起，在工具交互过程中提供更深入的推理

使用思维的好处（Benefits of Using Thinking）

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

• 透明度：查看模型的推理过程及其如何得出结论
• 调试：确定模型可能出现逻辑错误的位置
• 教育：使用分步推理作为教学工具
• 复杂问题解决：在数学、逻辑和推理任务中获得更好的结果

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

工具 / 功能调用（Tool/Function Calling）

您可以使用 AnthropicChatModel 注册自定义 Java 工具，并让 Anthropic Claude 模型智能地选择输出一个包含参数的 JSON 对象来调用一个或多个注册的函数。这是一种强大的技术，可以将 LLM 功能与外部工具和 API 连接起来。详细了解工具调用。

图片（Images）

目前，Anthropic Claude 3 支持，包括 image/jpeg, image/png, image/gif 和 image/webp mime 类型的 base64 编码图像。

Spring AI 的消息接口通过引入媒体类型来支持多模态 AI 模型。它使用 Spring 的 org.springframework.util.MimeType 和一个 java.lang.Object来包含消息中媒体附件的数据和信息，用于原始媒体数据。

下面是一个简单的代码示例，演示了用户文本与图像的组合。

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 图像作为输入：

伴随着 “解释一下你在这张照片上看到了什么？” 的文本信息，并产生类似以下内容的回复：

The image shows a close-up view of a wire fruit basket containing several pieces of fruit.
...

PDF

从 Sonnet 3.5 开始提供 PDF 支持 (beta)。使用 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)));

Sample Controller

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-anthropic 添加到 pom (或 gradle) 依赖项中。

在 src/main/resources 目录下添加 application.properties 文件，以启用和配置 Anthropic 聊天模型：

spring.ai.anthropic.api-key=${ANTHROPIC_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

这将创建一个 AnthropicChatModel 的实现，你可以将其注入到你的类中。下面是一个简单的 @Controller 类的示例，它使用聊天模型进行文本生成。

@RestController
public class ChatController {

    private final AzureOpenAiChatModel chatModel;

    @Autowired
    public ChatController(AzureOpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    /**
     * 文本生成
     * eg. http://localhost:8080/ai/generate?message=你好
     * @param message
     * @return
     */
    @GetMapping("/ai/generate")
    @Operation(summary = "文本生成")
    public Map<String, Object> generate(@RequestParam(value = "message", defaultValue = "你好！") String message) {
        try {
            String response = chatModel.call(message);
            return Map.of(
                "success", true,
                "generation", response,
                "message", "Generated successfully"
            );
        } catch (Exception e) {
            return Map.of(
                "success", false,
                "error", e.getMessage(),
                "message", "Generation failed"
            );
        }
    }

    @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 build 文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-anthropic'
}

接下来，创建一个 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("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 是一个流畅的选项构建器。

轻量级 AnthropicApi Client

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。