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-latest、claude-3-5-sonnet-latest、claude-3-opus-20240229、claude-3-sonnet-20240229、claude-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 支持 images 的 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 图像作为输入:

多模态测试图像

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

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

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 实现了 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 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 示例