Java 后端如何调用大模型 API？从零到一接入 AI 接口

Java 后端如何调用大模型 API？从零到一接入 AI 接口

本文将带你从零开始，使用 Java 后端调用大模型 API，实现一个完整的 AI 对话功能。无论你使用的是 OpenAI、通义千问、文心一言还是 DeepSeek，原理都是相通的。

一、前言

随着 AI 大模型的普及，越来越多的应用需要接入大模型能力。作为 Java 后端开发者，如何优雅地调用大模型 API 成为一项必备技能。本文将以 通义千问（Qwen） 为例，带你完成从零到一的接入过程。

本文你将学到：

• 大模型 API 调用的基本原理
• 使用 HttpClient 发送 HTTP 请求
• 封装通用的 AI 调用工具类
• 处理 API 响应与异常
• 实现一个简单的对话接口

---

二、大模型 API 调用原理

大多数大模型 API 都采用 HTTP RESTful 接口，核心流程如下：

┌─────────────┐     HTTP POST      ┌─────────────┐
│  Java 后端  │ ──────────────────>│  大模型 API │
│             │     JSON 请求      │             │
│             │<────────────────── │             │
│             │     JSON 响应      │             │
└─────────────┘                    └─────────────┘

请求格式（以通义千问为例）：

{
  "model": "qwen-plus",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "你好，请介绍一下自己"}
  ]
}

响应格式：

{
  "output": {
    "text": "你好！我是通义千问..."
  },
  "usage": {
    "input_tokens": 20,
    "output_tokens": 100
  }
}

---

三、准备工作

3.1 获取 API Key

以通义千问为例：

1. 访问 阿里云百炼平台
2. 开通服务并创建 API Key
3. 记录下你的 API Key

3.2 添加 Maven 依赖

使用 JDK 11+ 内置的 HttpClient，无需额外依赖。如果你使用的是 JDK 8，可以添加：

<!-- JSON 处理 -->
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.43</version>
</dependency>

<!-- 如使用 JDK 8，可添加 OkHttp -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

---

四、核心代码实现

4.1 定义请求/响应实体类

package com.example.ai.model;

import java.util.List;

/**
 * AI 对话请求
 */
public class ChatRequest {
    private String model;
    private List<Message> messages;

    public ChatRequest(String model, List<Message> messages) {
        this.model = model;
        this.messages = messages;
    }

    // getter、setter 省略

    public static class Message {
        private String role;
        private String content;

        public Message(String role, String content) {
            this.role = role;
            this.content = content;
        }

        // getter、setter 省略
    }
}

/**
 * AI 对话响应
 */
public class ChatResponse {
    private Output output;
    private Usage usage;

    // getter、setter 省略

    public static class Output {
        private String text;
        private String finish_reason;
        // getter、setter 省略
    }

    public static class Usage {
        private Integer input_tokens;
        private Integer output_tokens;
        // getter、setter 省略
    }
}

4.2 封装 AI 客户端工具类

package com.example.ai.client;

import com.alibaba.fastjson2.JSON;
import com.example.ai.model.ChatRequest;
import com.example.ai.model.ChatResponse;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;

/**
 * 大模型 API 客户端
 */
public class AiClient {

    private final String apiKey;
    private final String baseUrl;
    private final HttpClient httpClient;

    // 通义千问 API 地址
    private static final String QWEN_API_URL = "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation";

    public AiClient(String apiKey) {
        this(apiKey, QWEN_API_URL);
    }

    public AiClient(String apiKey, String baseUrl) {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
        this.httpClient = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(30))
                .build();
    }

    /**
     * 发送单轮对话
     *
     * @param model   模型名称，如 qwen-plus
     * @param content 用户消息内容
     * @return AI 回复内容
     */
    public String chat(String model, String content) {
        List<ChatRequest.Message> messages = new ArrayList<>();
        messages.add(new ChatRequest.Message("user", content));
        return chat(model, messages);
    }

    /**
     * 发送多轮对话
     *
     * @param model    模型名称
     * @param messages 消息列表
     * @return AI 回复内容
     */
    public String chat(String model, List<ChatRequest.Message> messages) {
        ChatRequest request = new ChatRequest(model, messages);
        String requestBody = JSON.toJSONString(request);

        HttpRequest httpRequest = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .timeout(Duration.ofSeconds(60))
                .build();

        try {
            HttpResponse<String> response = httpClient.send(
                    httpRequest,
                    HttpResponse.BodyHandlers.ofString()
            );

            if (response.statusCode() == 200) {
                ChatResponse chatResponse = JSON.parseObject(response.body(), ChatResponse.class);
                return chatResponse.getOutput().getText();
            } else {
                throw new RuntimeException("AI API 调用失败: " + response.statusCode() + " - " + response.body());
            }
        } catch (Exception e) {
            throw new RuntimeException("AI API 调用异常", e);
        }
    }
}

4.3 创建 Spring Boot 接口

package com.example.ai.controller;

import com.example.ai.client.AiClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;

/**
 * AI 对话接口
 */
@RestController
@RequestMapping("/api/ai")
public class AiController {

    private final AiClient aiClient;

    public AiController(@Value("${ai.api-key}") String apiKey) {
        this.aiClient = new AiClient(apiKey);
    }

    /**
     * 简单对话接口
     *
     * @param content 用户输入内容
     * @return AI 回复
     */
    @GetMapping("/chat")
    public String chat(@RequestParam String content) {
        return aiClient.chat("qwen-plus", content);
    }

    /**
     * 对话接口（POST 方式）
     *
     * @param request 对话请求
     * @return AI 回复
     */
    @PostMapping("/chat")
    public ChatResult chat(@RequestBody ChatRequest request) {
        String answer = aiClient.chat(request.getModel(), request.getContent());
        return new ChatResult(answer);
    }

    public static class ChatRequest {
        private String model = "qwen-plus";
        private String content;
        // getter、setter 省略
    }

    public static class ChatResult {
        private String answer;

        public ChatResult(String answer) {
            this.answer = answer;
        }
        // getter、setter 省略
    }
}

4.4 配置文件

# application.yml
ai:
  api-key: your-api-key-here

# 建议使用环境变量
# ai:
#   api-key: ${AI_API_KEY}

---

五、测试验证

5.1 单元测试

package com.example.ai.client;

import org.junit.jupiter.api.Test;

class AiClientTest {

    @Test
    void testChat() {
        String apiKey = System.getenv("AI_API_KEY");
        AiClient client = new AiClient(apiKey);

        String response = client.chat("qwen-plus", "请用一句话介绍 Java");
        System.out.println(response);

        assertNotNull(response);
        assertTrue(response.length() > 0);
    }
}

5.2 接口测试

# GET 请求
curl "http://localhost:8080/api/ai/chat?content=你好"

# POST 请求
curl -X POST http://localhost:8080/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-plus", "content": "介绍一下 Spring Boot"}'

---

六、常见问题与解决方案

6.1 API Key 泄露风险

问题：API Key 硬编码在代码中存在安全隐患。

解决方案：

// 使用环境变量
@Value("${AI_API_KEY}")
private String apiKey;

// 或使用配置中心（Nacos、Apollo）

6.2 请求超时

问题：AI 接口响应较慢，容易超时。

解决方案：

// 设置合理的超时时间
HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(30))
    .build();

HttpRequest.newBuilder()
    .timeout(Duration.ofSeconds(120))  // AI 响应可能较慢
    .build();

6.3 Token 超限

问题：输入内容过长，超过模型 Token 限制。

解决方案：

// 添加 Token 计算与截断逻辑
public String truncateContent(String content, int maxTokens) {
    // 简单估算：中文约 1.5 字符/token，英文约 4 字符/token
    int estimatedTokens = (int) (content.length() / 1.5);
    if (estimatedTokens > maxTokens) {
        int maxChars = (int) (maxTokens * 1.5);
        return content.substring(0, maxChars);
    }
    return content;
}

---

七、总结

本文从零开始，带你完成了 Java 后端调用大模型 API 的完整流程：

步骤	内容
1	了解大模型 API 的请求/响应格式
2	定义 Java 实体类映射 JSON
3	使用 HttpClient 发送请求
4	封装通用的 AiClient 工具类
5	创建 Spring Boot 接口对外服务

核心代码已提供，你可以直接复制使用。