Anthropic 3 聊天

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 Key 值。

你可以在 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

  • 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,对于 4xx 客户端错误代码抛出 NonTransientAiException,不尝试重试

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 密钥

-

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-3-7-sonnet-latestclaude-3-5-sonnet-latestclaude-3-opus-20240229claude-3-sonnet-20240229claude-3-haiku-20240307

claude-3-7-sonnet-latest

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 头。

-

提示:所有以 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 实例,该实例使用 ChatOptionsBuilder#builder() 创建。

工具/函数调用

你可以向 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 接口通过引入 Media 类型支持多模态 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 图像作为输入:

多模态测试图像

以及文本消息"解释你在这张图片上看到了什么?",并生成类似这样的响应:

图片显示了一个装有几块水果的金属丝水果篮的特写视图。
...

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 = "给我讲个笑话") 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 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("生成 5 个著名海盗的名字。"));

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

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

低级 AnthropicApi 客户端

AnthropicApi 提供了 Anthropic 消息 API 的轻量级 Java 客户端。

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

AnthropicApi 聊天 API 图
AnthropicApi 事件模型

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