Spring Boot WebClient 集成大模型 API：OpenAI、文心一言、通义千问

3. 读取 API 密钥（推荐使用环境变量）

在 application.yml 中配置密钥（切勿硬编码）：

api:
  openai:
    key: ${OPENAI_API_KEY} # 从环境变量读取
  wenxin:
    api-key: ${WENXIN_API_KEY}
    secret-key: ${WENXIN_SECRET_KEY}
  tongyi:
    key: ${TONGYI_API_KEY}

在服务类中注入：

@Service
public class ApiConfig {
    @Value("${api.openai.key}")
    private String openaiApiKey;
    @Value("${api.wenxin.api-key}")
    private String wenxinApiKey;
    @Value("${api.wenxin.secret-key}")
    private String wenxinSecretKey;
    @Value("${api.tongyi.key}")
    private String tongyiApiKey;
}

三、WebClient 基础配置

创建一个 WebClientConfig 类，封装通用配置：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.netty.http.client.HttpClient;

@Configuration
public class WebClientConfig {
    // 可选：配置超时、重试、连接池
    @Bean
    public WebClient webClient() {
        HttpClient httpClient = HttpClient.create()
                .responseTimeout(java.time.Duration.ofSeconds(30)); // 请求超时 30 秒
        return WebClient.builder()
                .clientConnector(new ReactorClientHttpConnector(httpClient))
                .build();
    }
}

提示：生产环境中应配置重试策略（如 Retry）、日志跟踪等。

四、调用 OpenAI API

1. OpenAI API 简介

• 端点：https://api.openai.com/v1/chat/completions
• 必需头：Authorization: Bearer <API_KEY>
• 请求体：JSON 格式，包含 model、messages 等字段。
• 官方文档：OpenAI API Reference

2. DTO 定义

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.util.List;

// 请求体
@Data
@NoArgsConstructor
@AllArgsConstructor
class OpenAiRequest {
    private String model; // 模型名，如 "gpt-3.5-turbo"
    private List<Message> messages;
}

@Data
@NoArgsConstructor
@AllArgsConstructor
class Message {
    private String role; // "user", "assistant", "system"
    private String content;
}

// 响应体（简化版，仅展示关键字段）
@Data
class OpenAiResponse {
    private List<Choice> choices;
    @Data
    static class Choice {
        private Message message;
    }
}

3. 服务实现

import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Service
public class OpenAiService {
    private final WebClient webClient;
    private final String apiKey;

    public OpenAiService(WebClient.Builder webClientBuilder, @Value("${api.openai.key}") String apiKey) {
        this.webClient = webClientBuilder
                .baseUrl("https://api.openai.com/v1")
                .defaultHeader("Authorization", "Bearer " + apiKey)
                .build();
        this.apiKey = apiKey;
    }

    public Mono<String> chat(String prompt) {
        // 构造请求体
        OpenAiRequest request = new OpenAiRequest(
                "gpt-3.5-turbo",
                List.of(new Message("user", prompt))
        );
        // 发送请求
        return webClient.post()
                .uri("/chat/completions")
                .contentType(MediaType.APPLICATION_JSON)
                .bodyValue(request)
                .retrieve()
                .bodyToMono(OpenAiResponse.class)
                .map(response -> response.getChoices().get(0).getMessage().getContent());
    }
}

4. Controller 使用

import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Mono;

@RestController
@RequestMapping("/ai")
public class AiController {
    private final OpenAiService openAiService;

    public AiController(OpenAiService openAiService) {
        this.openAiService = openAiService;
    }

    @GetMapping("/ask")
    public Mono<String> askOpenAi(@RequestParam String question) {
        return openAiService.chat(question);
    }
}

测试：发送 GET 请求 http://localhost:8080/ai/ask?question=你好，将返回 GPT 的回答。

五、调用文心一言 API

1. 文心一言 API 简介

• 获取访问令牌（Access Token）：
  • 首先需调用 OAuth 2.0 获取 access_token。
  • 端点：https://aip.baidubce.com/oauth/2.0/token
  • 参数：grant_type=client_credentials&client_id=<API_KEY>&client_secret=<SECRET_KEY>
• 聊天接口：
  • 端点：https://aip.baidubce.com/rpc/2.0/ai/custom/v1/wenxinworkshop/chat/completions?access_token=<TOKEN>
  • 请求体格式类似 OpenAI，但字段名不同。

注意：文心一言需在百度智能云控制台创建应用并获取密钥。

2. DTO 定义

// 访问令牌响应
@Data
class WenxinTokenResponse {
    private String access_token;
    private String expires_in;
}

// 文心一言请求体
@Data
@NoArgsConstructor
@AllArgsConstructor
class WenxinRequest {
    private String model = "eb-instant"; // 模型名（如 eb-instant、ernie-3.5-4k-0205）
    private List<Message> messages;
}

// 文心一言响应体
@Data
class WenxinResponse {
    private List<Choice> result;
    @Data
    static class Choice {
        private String content;
    }
}

3. 服务实现

import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Service
public class WenxinService {
    private final WebClient webClient;
    private final String apiKey;
    private final String secretKey;

    public WenxinService(WebClient.Builder webClientBuilder, @Value("${api.wenxin.api-key}") String apiKey, @Value("${api.wenxin.secret-key}") String secretKey) {
        this.webClient = webClientBuilder.build();
        this.apiKey = apiKey;
        this.secretKey = secretKey;
    }

    // Step 1: 获取 Access Token
    private Mono<String> getAccessToken() {
        return webClient.post()
                .uri("https://aip.baidubce.com/oauth/2.0/token")
                .queryParam("grant_type", "client_credentials")
                .queryParam("client_id", apiKey)
                .queryParam("client_secret", secretKey)
                .retrieve()
                .bodyToMono(WenxinTokenResponse.class)
                .map(WenxinTokenResponse::getAccess_token);
    }

    // Step 2: 调用聊天接口
    public Mono<String> chat(String prompt) {
        return getAccessToken().flatMap(accessToken -> {
            WenxinRequest request = new WenxinRequest(List.of(new Message("user", prompt)));
            return webClient.post()
                    .uri("https://aip.baidubce.com/rpc/2.0/ai/custom/v1/wenxinworkshop/chat/completions")
                    .queryParam("access_token", accessToken)
                    .contentType(MediaType.APPLICATION_JSON)
                    .bodyValue(request)
                    .retrieve()
                    .bodyToMono(WenxinResponse.class)
                    .map(resp -> resp.getResult().get(0).getContent());
        });
    }
}

4. Controller 使用

@RestController
@RequestMapping("/ai")
public class AiController {
    private final WenxinService wenxinService;

    public AiController(WenxinService wenxinService) {
        this.wenxinService = wenxinService;
    }

    @GetMapping("/wenxin")
    public Mono<String> askWenxin(@RequestParam String question) {
        return wenxinService.chat(question);
    }
}

六、调用通义千问 API

1. 通义千问 API 简介

• 端点：https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
• 必需头：Authorization: Bearer <API_KEY>
• 模型：dall-e-xl（图像）或 qwen-plus（文本）
• 官方文档：通义千问 API 文档

注意：通义千问由阿里云提供，需在阿里云控制台获取 API 密钥。

2. DTO 定义

import java.util.ArrayList;

// 请求体
@Data
@NoArgsConstructor
@AllArgsConstructor
class TongyiRequest {
    private String model = "qwen-long"; // 模型名
    private List<Message> input = new ArrayList<>();
    private Parameters parameters = new Parameters();

    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    static class Parameters {
        private float temperature = 0.7f; // 随机性
        private int max_tokens = 800; // 最多生成 token 数
    }
}

// 响应体
@Data
class TongyiResponse {
    private Output output;

    @Data
    static class Output {
        private List<Text> text;

        @Data
        static class Text {
            private String content;
        }
    }
}

3. 服务实现

import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Service
public class TongyiService {
    private final WebClient webClient;
    private final String apiKey;

    public TongyiService(WebClient.Builder webClientBuilder, @Value("${api.tongyi.key}") String apiKey) {
        this.webClient = webClientBuilder
                .baseUrl("https://dashscope.aliyuncs.com")
                .defaultHeader("Authorization", "Bearer " + apiKey)
                .defaultHeader("Content-Type", MediaType.APPLICATION_JSON)
                .build();
        this.apiKey = apiKey;
    }

    public Mono<String> chat(String prompt) {
        TongyiRequest request = new TongyiRequest();
        request.getInput().add(new Message("user", prompt));
        return webClient.post()
                .uri("/api/v1/services/aigc/text-generation/generation")
                .bodyValue(request)
                .retrieve()
                .bodyToMono(TongyiResponse.class)
                .map(resp -> resp.getOutput().getText().get(0).getContent());
    }
}

4. Controller 使用

@RestController
@RequestMapping("/ai")
public class AiController {
    private final TongyiService tongyiService;

    public AiController(TongyiService tongyiService) {
        this.tongyiService = tongyiService;
    }

    @GetMapping("/tongyi")
    public Mono<String> askTongyi(@RequestParam String question) {
        return tongyiService.chat(question);
    }
}

七、错误处理与最佳实践

1. 优雅处理 HTTP 错误

使用 onStatus() 捕获 4xx/5xx 错误：

public Mono<String> chat(String prompt) {
    return webClient.post()
            .uri("/chat/completions")
            .bodyValue(request)
            .retrieve()
            .onStatus(httpStatus -> httpStatus.value() >= 400, clientResponse -> {
                // 读取错误信息
                return clientResponse.bodyToMono(String.class)
                        .flatMap(errorBody -> Mono.error(new RuntimeException(
                                "API 调用失败：" + httpStatus.getReasonPhrase() + ", " + errorBody
                        )));
            })
            .bodyToMono(OpenAiResponse.class)
            .map(...);
}

2. 重要最佳实践

3. 流式输出示例（OpenAI）

public Flux<String> streamChat(String prompt) {
    OpenAiRequest request = new OpenAiRequest("gpt-3.5-turbo", List.of(new Message("user", prompt)));
    request.setStream(true); // 开启流式
    return webClient.post()
            .uri("/chat/completions")
            .bodyValue(request)
            .accept(MediaType.TEXT_EVENT_STREAM) // SSE 格式
            .exchangeToFlux(clientResponse -> clientResponse.bodyToFlux(String.class))
            .filter(chunk -> !chunk.trim().isEmpty())
            .map(chunk -> chunk.split("data: ")[1])
            .filter(data -> !data.equals("[\u200b]")) // 过滤心跳
            .map(data -> { /* 解析 JSON 得到内容 */ });
}

八、完整项目结构

src
├── main
│   ├── java
│   │   └── com.example.demo
│   │       ├── DemoApplication.java
│   │       ├── config
│   │       │   └── WebClientConfig.java
│   │       ├── controller
│   │       │   └── AiController.java
│   │       ├── dto
│   │       │   ├── OpenAiRequest.java
│   │       │   ├── WenxinRequest.java
│   │       │   └── TongyiRequest.java
│   │       ├── service
│   │       │   ├── OpenAiService.java
│   │       │   ├── WenxinService.java
│   │       │   └── TongyiService.java
│   │       └── ApiConfig.java
│   └── resources
│       └── application.yml

九、总结

通过本文，你掌握了：

1. 如何配置 Spring Boot 的 WebClient 作为高性能 HTTP 客户端。
2. 三大主流大模型 API 的调用流程：
   • OpenAI：直接传递 Bearer Token。
   • 文心一言：先获取 access_token，再带参调用。
   • 通义千问：使用 Bearer 方式传递 API 密钥。
3. 响应式编程实践：使用 Mono/Flux 处理异步调用，避免线程阻塞。
4. 生产级考量：错误处理、密钥管理、超时重试、流式输出等。

下一步建议：

• 集成 Spring AI（官方支持的 AI 框架），简化大模型调用。
• 尝试 流式输出，提升用户体验（如实时显示模型思考过程）。
• 使用 缓存 存储重复请求的结果，降低 API 调用成本。

现在，你可以将大模型能力集成到自己的 Spring Boot 应用中！

重要提醒： 大模型 API 通常需要付费（按 token 计费），请理性使用，并遵守各平台的使用政策。实际项目中请仔细阅读官方文档获取最新接口规范。