Spring AI接入第三方大模型API服务：BaseURL与密钥配置实操

作者：nTokenX｜发布日期：2026-10-13｜更新日期：2026-10-13

Spring AI接入第三方大模型API服务，本质是让 OpenAI 模型适配器把请求发送到兼容网关。开发者通常只需处理依赖、BaseURL、API Key 和模型名四项配置，但要特别检查 URL 路径、属性版本和模型标识是否匹配。

Spring AI如何连接第三方大模型API？

Spring AI通过统一的 ChatModel 与 ChatClient 抽象调用模型。如果第三方服务提供 OpenAI 兼容协议，应用一般无需为 GPT、Claude、Gemini 或 Grok 分别编写客户端，只需更换网关地址、密钥与模型名。

第三方服务通常分为两类：

1. 正规API聚合或网关：企业绑定自己的模型厂商 Key，由平台统一完成转发、监控与计费。
2. 第三方模型中转服务：服务商采购或代理模型额度，再通过统一接口提供调用能力。

第二类服务在授权方式、可用性和数据安全方面差异较大。企业选型时应检查数据留存、密钥管理、故障处理与账单核对机制，可参考多模型API聚合平台的合规与选型方法。

接入前需要准备哪些参数？

最小接入参数只有三个：兼容接口的BaseURL、API Key和准确的模型ID。其中模型展示名称不一定等于请求参数，必须使用服务商接口文档或模型列表返回的标识。

nTokenX采用统一大模型API方式，用户申请一个 API Key，即可调用 GPT、Claude、Gemini、Grok 等多个模型。切换模型时，业务代码可以保持不变，主要调整模型标识。

如何添加Spring AI依赖？

使用Spring Boot自动配置时，只需引入OpenAI模型Starter，并通过Spring AI BOM统一管理版本。不要直接复制早期教程中的旧依赖名称，否则可能在依赖解析阶段失败。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

Spring AI官方OpenAI Chat文档列出的模型 Starter 为 spring-ai-starter-model-openai；自动配置还会提供可注入的 ChatClient.Builder。(docs.spring.io)

BaseURL与API Key如何配置？

推荐把密钥放入环境变量，并在YAML中只保留变量引用。通用配置适合聊天、嵌入等能力共用同一网关；如果只有聊天模型走第三方接口，可使用聊天级配置覆盖通用地址。

spring:
  ai:
    model:
      chat: openai
    openai:
      base-url: ${LLM_BASE_URL}
      api-key: ${LLM_API_KEY}
      timeout: 60s
      max-retries: 3
      chat:
        model: ${LLM_MODEL}
        temperature: 0.2

export LLM_BASE_URL="https://gateway.example.com"
export LLM_API_KEY="替换为真实密钥"
export LLM_MODEL="替换为网关模型ID"

官方配置中，spring.ai.openai.chat.base-url 和 spring.ai.openai.chat.api-key 的优先级高于对应的通用属性，适合将聊天与嵌入模型路由到不同服务。(docs.spring.io)

不要把 Key 写入 Git 仓库、镜像文件或前端代码。生产环境应使用配置中心、Kubernetes Secret 或云密钥管理服务，并按应用、环境和租户拆分凭证。

BaseURL是否必须包含“/v1”？

BaseURL没有适用于所有网关的固定写法。正确结果取决于客户端最终请求路径与网关路由的组合，因此不能机械套用“必须带 /v1”或“必须删除 /v1”的结论。

本文采用“路径拼接三例法”做静态审计。对三组常见组合演算后，2 组形成目标路径，1 组出现重复版本段：

这项演算的价值在于：BaseURL应根据最终请求地址反推，而不是只看配置字段名称。若接口返回 404，应先查看应用日志或网关访问日志，确认实际请求路径，再调整版本段和前缀。

如何编写最小可用的调用接口？

依赖与YAML生效后，可直接注入自动配置的ChatClient.Builder。先用非流式、短提示词验证鉴权和路由，再接入流式输出、工具调用或业务上下文。

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AiController {

    private final ChatClient chatClient;

    public AiController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/ai/chat")
    public String chat(
            @RequestParam(defaultValue = "用一句话介绍Spring AI") String question) {

        return chatClient.prompt()
                .user(question)
                .call()
                .content();
    }
}

启动应用后请求：

curl "http://localhost:8080/ai/chat?question=返回字符串OK"

建议把验收结果量化为 4/4通过：

1. Maven依赖成功解析；
2. 应用启动且 ChatClient.Builder 注入成功；
3. 非流式请求返回非空文本；
4. 网关账单或调用日志出现对应模型记录。

只有启动成功不能证明接入完成，因为它仅说明配置被加载，不代表密钥、路由和模型权限都正确。

常见错误如何快速定位？

排错应按照“依赖—配置—路由—模型—限流”的顺序进行。先确认请求是否真正到达网关，再判断是客户端参数错误还是服务端容量问题。

针对限流场景，可结合大模型API错误码429自动重试策略设计退避与抖动；生产系统还应通过大模型API多云容灾与自动降级方案避免单一接口故障扩大。

生产环境还要检查什么？

生产接入不能停留在“能返回文本”，还要验证密钥隔离、超时、重试、日志脱敏和模型切换。统一网关降低了SDK适配成本，但不会自动解决治理问题。

上线前至少完成以下检查：

• 为开发、测试、生产环境使用不同 Key；
• 日志不记录 Authorization 请求头和完整提示词；
• 为请求设置连接超时、读取超时和最大重试次数；
• 记录模型名、耗时、状态码和请求追踪ID；
• 对 429、5xx 和超时分别制定重试规则；
• 为核心业务配置备用模型或备用网关；
• 用固定测试集比较切换模型前后的格式与语义结果。

如果需要用一个密钥统一调用多个模型，可注册 nTokenX，再将获得的 BaseURL、API Key 与模型标识填入上述环境变量。

常见问题

Spring AI只能调用OpenAI模型吗？

不是。Spring AI提供多种模型适配器；对于提供 OpenAI 兼容协议的第三方网关，也可以通过 OpenAI 模型 Starter 转发到其他模型，但具体能力取决于网关的协议转换范围。

为什么配置正确仍然提示模型不存在？

最常见原因是填写了控制台展示名，而不是接口实际接收的模型ID。还应检查该 Key 是否拥有目标模型权限，以及模型名是否包含渠道或版本后缀。

可以把API Key直接写进application.yml吗？

本地临时验证可以，但不建议提交到代码仓库。测试和生产环境应通过环境变量、配置中心或密钥管理系统注入，并定期轮换。

聊天接口成功是否代表嵌入接口也能使用？

不代表。聊天与嵌入可能使用不同模型、路径甚至不同服务商。需要分别执行最小请求，并在必要时使用聊天级或嵌入级 BaseURL 覆盖通用配置。

更换第三方网关需要修改Java代码吗？

如果新网关保持 OpenAI 兼容请求结构，通常只需修改 BaseURL、API Key 和模型名。若其工具调用、流式响应或多模态字段不兼容，仍需调整请求参数或模型适配层。