Groq 聊天

Groq 是一个基于 LPU™、极快的 AI 推理引擎，支持多种 AI 模型，支持 Tool/Function Calling（工具/函数调用），并暴露一个 OpenAI API 兼容的端点。

Spring AI 通过复用现有的 OpenAI 客户端来与 Groq 集成。为此你需要获取一个 Groq Api Key，把 base-url 设为 https://api.groq.com/openai/v1，并从所提供的 Groq 模型中选择一个。

NOTE

Groq API 与 OpenAI API 并非完全兼容。

请留意以下兼容性限制。此外，当前 Groq 不支持多模态消息。

查看 GroqWithOpenAiChatModelIT.java 测试以获取在 Spring AI 中使用 Groq 的示例。

前置条件

创建一个 API 密钥：前往此处创建一个 API 密钥。 Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，你应把它设为从 groq.com 获取的 API Key 的值。
设置 Groq URL：你必须把 spring.ai.openai.base-url 属性设为 +https://api.groq.com/openai/v1+。
选择一个 Groq 模型：使用 spring.ai.openai.chat.model=<model name> 属性从可用的 Groq 模型中选择。

你可以在 application.properties 文件中设置这些配置属性：

properties

spring.ai.openai.api-key=<your-groq-api-key>
spring.ai.openai.base-url=https://api.groq.com/openai/v1
spring.ai.openai.chat.model=llama3-70b-8192

为在 handling 诸如 API 密钥这类敏感信息时获得更强的安全性，你可以使用 Spring 表达式语言（SpEL）引用自定义环境变量：

yaml

# In application.yml
spring:
  ai:
    openai:
      api-key: ${GROQ_API_KEY}
      base-url: ${GROQ_BASE_URL}
      chat:
        model: ${GROQ_MODEL}

bash

# In your environment or .env file
export GROQ_API_KEY=<your-groq-api-key>
export GROQ_BASE_URL=https://api.groq.com/openai/v1
export GROQ_MODEL=llama3-70b-8192

你也可以在应用代码中以编程方式设置这些配置：

java

// Retrieve configuration from secure sources or environment variables
String apiKey = System.getenv("GROQ_API_KEY");
String baseUrl = System.getenv("GROQ_BASE_URL");
String model = System.getenv("GROQ_MODEL");

添加仓库与 BOM

Spring AI 的制品发布在 Maven Central 和 Spring Snapshot 仓库中。参见制品仓库一节，把这些仓库添加到你的构建系统。

为便于依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保整个项目中使用一致版本的 Spring AI。参见依赖管理一节，把 Spring AI BOM 添加到你的构建系统。

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。更多信息请参阅升级说明。

Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 或 Gradle build.gradle 构建文件：

xml

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

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

聊天属性

重试属性

前缀 spring.ai.retry 用作配置 OpenAI 聊天模型重试机制的属性前缀。

属性	描述	默认值
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）。	empty
spring.ai.retry.on-http-codes	应触发重试的 HTTP 状态码列表（例如抛出 TransientAiException）。	empty

连接属性

前缀 spring.ai.openai 用作连接 OpenAI 的属性前缀。

属性	描述	默认值
spring.ai.openai.base-url	要连接到的 URL。必须设为 `+https://api.groq.com/openai/v1+`	-
spring.ai.openai.api-key	Groq API 密钥	-

配置属性

NOTE

聊天自动配置的启用与禁用，现通过以 spring.ai.model.chat 为前缀的顶层属性来配置。

要启用，spring.ai.model.chat=openai（默认启用）

要禁用，spring.ai.model.chat=none（或任何不匹配 openai 的值）

做出此变更是为了支持配置多个模型。

前缀 spring.ai.openai.chat 是为 OpenAI 配置聊天模型实现的属性前缀。

属性	描述	默认值
spring.ai.openai.chat.enabled (Removed and no longer valid)	启用 OpenAI 聊天模型。	true
spring.ai.model.chat	启用 OpenAI 聊天模型。	openai
spring.ai.openai.chat.base-url	可选，覆盖 spring.ai.openai.base-url 以提供一个聊天专用 url。必须设为 `+https://api.groq.com/openai/v1+`	-
spring.ai.openai.chat.api-key	可选，覆盖 spring.ai.openai.api-key 以提供一个聊天专用 api-key	-
spring.ai.openai.chat.model	可用的模型名称为 `llama3-8b-8192`、`llama3-70b-8192`、`mixtral-8x7b-32768`、`gemma2-9b-it`。	-
spring.ai.openai.chat.temperature	用于控制的采样温度，影响生成补全的表观创造性。较高的值使输出更随机，较低的值使结果更聚焦、更确定。不建议在同一补全请求中同时修改 temperature 与 top_p，因为这两个设置的相互作用难以预测。	0.8
spring.ai.openai.chat.frequency-penalty	-2.0 到 2.0 之间的数。正值依据新令牌在迄今文本中的既有频率对其加以惩罚，降低模型逐字重复同一行的可能性。	0.0f
spring.ai.openai.chat.max-tokens	在聊天补全中要生成的最大令牌数。输入令牌与生成令牌的总长度受模型上下文窗口长度限制。	-
spring.ai.openai.chat.n	为每个输入消息生成的聊天补全候选数。注意，你会依据所有候选生成的令牌总数被计费。保持 n 为 1 以最小化成本。	1
spring.ai.openai.chat.presence-penalty	-2.0 到 2.0 之间的数。正值依据新令牌是否已在迄今文本中出现对其加以惩罚，提升模型谈论新话题的可能性。	-
spring.ai.openai.chat.response-format	指定模型必须输出格式的對象。设为 `{ "type": "json_object" }` 会启用 JSON 模式，保证模型生成的消息是合法 JSON。	-
spring.ai.openai.chat.seed	此特性处于 Beta。若指定，我们的系统会尽力做确定性采样，使带相同 seed 与参数的重复请求返回相同结果。	-
spring.ai.openai.chat.stop	最多 4 个序列，API 到此处会停止生成更多令牌。	-
spring.ai.openai.chat.top-p	temperature 采样的替代方案，即核采样，模型会考虑具有 top_p 概率质量的那些令牌的结果。所以 0.1 意味着只考虑构成前 10% 概率质量的令牌。我们通常建议调整此项或 temperature，但不要同时调整两者。	-
spring.ai.openai.chat.tools	模型可调用工具列表。目前作为工具只支持函数。用它提供一个模型可为其生成 JSON 输入的函数列表。	-
spring.ai.openai.chat.tool-choice	控制模型调用哪个（若有）函数。none 表示模型不会调用函数而生成一条消息。auto 表示模型可在生成消息或调用函数之间选择。通过 {"type: "function", "function": {"name": "my_function"}} 指定某个特定函数会强制模型调用该函数。无函数存在时 none 为默认；有函数存在时 auto 为默认。	-
spring.ai.openai.chat.user	表示你最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用。	-
spring.ai.openai.chat.stream-usage	（仅流式）设置后会为整个请求附加一个带令牌用量统计的额外块。该块的 `choices` 字段为空数组，其余所有块也会包含一个 usage 字段但值为 null。	false
spring.ai.openai.chat.tool-callbacks	注册到 ChatModel 的工具回调。	-

TIP

所有以 spring.ai.openai.chat 为前缀的属性，都可通过在 Prompt 调用中添加一个请求专用的 chat-options 在运行时被覆盖。

运行时选项

OpenAiChatOptions.java 提供模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可通过 OpenAiChatModel(api, options) 构造器或 spring.ai.openai.chat.* 属性配置默认选项。

在运行时，你可以通过向 Prompt 调用添加新的、请求特定的选项来覆盖默认选项。例如，要为某个特定请求覆盖默认的模型和温度：

java

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OpenAiChatOptions.builder()
            .model("mixtral-8x7b-32768")
            .temperature(0.4)
        .build()
    ));

TIP

除模型特定的 OpenAiChatOptions 外，你还可以使用一个可移植的 ChatOptions 实例，通过 ChatOptions#builder() 创建。

工具调用

当所选模型支持时，Groq 支持工具调用。Spring AI 处理工具执行循环。

TIP

查看受支持的模型。

对于大多数应用，请搭配自动注册的 ToolCallingAdvisor 使用 ChatClient —— 参见工具调用。若需要由你自己驱动该循环的底层控制，参见 ChatModel 工具调用。

多模态

NOTE

当前 Groq API 不支持媒体内容。

示例控制器

创建一个新的 Spring Boot 项目，并把 spring-ai-starter-model-openai 添加到你的 pom（或 gradle）依赖。

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

application.properties

spring.ai.openai.api-key=<GROQ_API_KEY>
spring.ai.openai.base-url=https://api.groq.com/openai/v1
spring.ai.openai.chat.model=llama3-70b-8192
spring.ai.openai.chat.temperature=0.7

TIP

用你的 OpenAI 凭据替换 api-key。

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

java

@RestController
public class ChatController {

    private final OpenAiChatModel chatModel;

    @Autowired
    public ChatController(OpenAiChatModel 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);
    }
}

手动配置

OpenAiChatModel 实现了 ChatModel 和 StreamingChatModel，并使用底层 api 连接到 OpenAI 服务。

把 spring-ai-openai 依赖添加到你的项目的 Maven pom.xml 文件：

xml

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
</dependency>

或添加到你的 Gradle build.gradle 构建文件。

groovy

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

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

接下来，创建一个 OpenAiChatModel 并将其用于文本生成：

java

var chatModel = OpenAiChatModel.builder()
    .options(OpenAiChatOptions.builder()
        .baseUrl("https://api.groq.com/openai/v1")
        .apiKey(System.getenv("GROQ_API_KEY"))
        .model("llama3-70b-8192")
        .temperature(0.4)
        .maxTokens(200)
        .build())
    .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."));

OpenAiChatOptions 为聊天请求提供配置信息。 OpenAiChatOptions.Builder 是一个流式选项构建器。

Chat Client API

顾问（Advisor）API

结构化输出

模型

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

工具调用

Model Context Protocol (MCP)

MCP 服务端 Boot Starter

MCP 注解

检索增强生成

向量数据库

Groq 聊天

前置条件

添加仓库与 BOM

自动配置

聊天属性

重试属性

连接属性

配置属性

运行时选项

工具调用

多模态

示例控制器

手动配置

友情链接