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

添加仓库和 BOM

Spring AI 组件已发布在 Maven 中央仓库和 Spring Snapshot 仓库。参阅 工件仓库 章节将这些仓库添加到你的构建系统。

为简化依赖管理,Spring AI 提供了 BOM 来确保整个项目使用统一版本的Spring AI。参阅 依赖管理 章节将 Spring AI BOM 添加到你的构建系统。

自动配置

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,则抛出 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

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 Key

-

spring.ai.anthropic.beta-version

启用新功能/实验功能。如果设置为 max-tokens-3-5-sonnet-2024-07-15,输出令牌(Token)限制将从 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-5-sonnet-latestclaude-3-7-sonnet-latestclaude-3-opus-20240229claude-3-sonnet-20240229claude-3-haiku-20240307

claude-3-7-sonnet-latest

spring.ai.anthropic.chat.options.temperature

用于控制生成内容表观创造力的采样温度值。数值越高输出越随机,数值越低结果越集中且确定。不建议在同一个补全请求中同时修改 temperaturetop_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

使用核采样(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

(已弃用 - 由 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 请求头,将添加到聊天补全请求中。

-

所有以 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/jpegimage/pngimage/gifimage/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.
...

PDF

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 实现了 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 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 客户端

AnthropicApiAnthropic Message API 提供了一个轻量级的 Java 客户端。

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

AnthropicApi Chat API Diagram
AnthropicApi Event Model

以下是一个以编程方式使用该 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 测试提供了一些如何使用该轻量级库的通用示例。