Light AI Spring Boot Starter

一个强大的、统一的 AI 调用框架 Spring Boot Starter，支持多种 AI 引擎和 Provider。

特性

• 🚀 开箱即用：添加依赖即可使用，无需复杂配置
• 🔌 多引擎支持：支持 Spring AI 和自定义 HTTP 引擎
• 🎯 统一接口：提供统一的 API，屏蔽底层差异
• 🔄 动态配置：支持从 JSON、数据库、配置中心动态加载 Provider
• ⚡ 流式响应：支持流式对话
• 🛠️ 中间件机制：支持重试、限流、日志等中间件
• 🔧 灵活扩展：易于扩展新的 AI Provider

快速开始

1. 添加依赖

<dependency>
    <groupId>cn.lightr</groupId>
    <artifactId>light-ai-spring-boot-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2. 创建配置文件

在你的项目 src/main/resources/ 目录下创建 ai-providers.json：

{
  "providers": [
    {
      "id": "openai",
      "type": "openai",
      "name": "OpenAI",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "your-api-key",
      "model": "gpt-4",
      "engineType": "spring-ai"
    }
  ]
}

3. 使用客户端

@RestController
@RequestMapping("/api/chat")
public class ChatController {
    
    @Autowired
    private LightAIClient aiClient;
    
    @PostMapping("/send")
    public Mono<String> chat(@RequestBody String message) {
        ChatRequest request = ChatRequest.builder()
                .providerId("openai")
                .messages(List.of(
                    ChatMessage.builder()
                        .role(MessageRole.USER)
                        .content(message)
                        .build()
                ))
                .build();
        
        return aiClient.chat(request)
                .map(ChatMessage::getContent);
    }
    
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> chatStream(@RequestParam String message) {
        ChatRequest request = ChatRequest.builder()
                .providerId("openai")
                .messages(List.of(
                    ChatMessage.builder()
                        .role(MessageRole.USER)
                        .content(message)
                        .build()
                ))
                .build();
        
        return aiClient.chatStream(request);
    }
}

配置说明

配置文件位置

• 默认位置：src/main/resources/ai-providers.json
• 自定义位置：通过 application.yml 配置

lightr:
  ai:
    enabled: true
    config:
      source: json
      file: classpath:config/my-providers.json
      auto-init: true

配置字段说明

字段	必填	说明
id	✅	Provider 唯一标识
type	✅	Provider 类型（openai, zhipu等）
baseUrl	✅	API 基础 URL
apiKey	✅	API 密钥
model	✅	默认模型
engineType	❌	引擎类型（spring-ai 或 custom）

详细配置说明请查看 配置指南

支持的 Provider

已支持

• ✅ OpenAI (GPT-4, GPT-3.5)
• ✅ 智谱 AI (GLM-4)
• ✅ Anthropic (Claude)
• ✅ 任何 OpenAI 兼容的 API

引擎类型

• spring-ai: 使用 Spring AI 框架（推荐）
• custom: 使用自定义 HTTP 引擎

示例项目结构

your-project/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/
│       │       └── ChatController.java
│       └── resources/
│           ├── application.yml
│           └── ai-providers.json  ← 在这里配置
├── pom.xml
└── ...

高级用法

使用对话上下文

// 创建对话
Conversation conversation = new Conversation("openai", "gpt-4");
conversation.setSystemPrompt("你是一个有帮助的AI助手");

// 发送消息
Mono<ChatMessage> response = aiClient.chatWithConversation(
    conversation, 
    "你好，介绍一下你自己"
);

运行时覆盖参数

ChatRequest request = ChatRequest.builder()
    .providerId("openai")
    .model("gpt-4-turbo")  // 覆盖默认模型
    .temperature(0.7)       // 设置温度
    .maxTokens(1000)        // 设置最大token数
    .messages(messages)
    .build();

检查 Provider 可用性

// 检查单个 Provider
boolean available = aiClient.isProviderAvailable("openai");

// 获取所有可用的 Provider
List<String> providers = aiClient.getAvailableProviders();

环境隔离

使用 Spring Profile 实现环境隔离：

# application-dev.yml
lightr:
  ai:
    config:
      file: classpath:ai-providers-dev.json

# application-prod.yml
lightr:
  ai:
    config:
      file: file:/etc/ai/providers-prod.json

安全建议

⚠️ 重要：不要将包含真实 API Key 的配置文件提交到版本控制系统！

方法一：使用环境变量

lightr:
  ai:
    providers:
      - id: openai
        api-key: ${OPENAI_API_KEY}

方法二：使用 .gitignore

ai-providers.json
**/ai-providers-*.json
!**/ai-providers-example.json

常见问题

Q: 启动时提示"配置文件不存在"？

A: 请在你的项目 src/main/resources/ 目录下创建 ai-providers.json 文件。

Q: 如何添加多个 Provider？

A: 在 providers 数组中添加多个配置即可：

{
  "providers": [
    { "id": "openai", ... },
    { "id": "zhipu", ... },
    { "id": "claude", ... }
  ]
}

Q: 如何动态切换 Provider？

A: 只需修改 ChatRequest 中的 providerId 参数：

// 使用 OpenAI
request.setProviderId("openai");

// 切换到智谱 AI
request.setProviderId("zhipu");

错误处理

常见错误：503 Service Overloaded

当看到以下错误时：

TransientAiException: 503 - The model is overloaded. Please try again later.

这是正常的业务异常，表示 OpenAI API 服务器暂时过载。建议实现以下处理方式：

方案一：添加重试机制

import reactor.util.retry.Retry;
import java.time.Duration;

@PostMapping("/send")
public Mono<String> chat(@RequestBody String message) {
    return aiClient.chat(request)
            .map(ChatMessage::getContent)
            .retryWhen(Retry.backoff(3, Duration.ofSeconds(2))
                .filter(throwable -> throwable instanceof TransientAiException));
}

方案二：全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(TransientAiException.class)
    public ResponseEntity<Map<String, Object>> handleTransientAiException(
            TransientAiException e) {
        return ResponseEntity
                .status(HttpStatus.SERVICE_UNAVAILABLE)
                .body(Map.of(
                    "success", false,
                    "error", "AI服务暂时不可用，请稍后重试",
                    "code", "SERVICE_OVERLOADED"
                ));
    }
}

方案三：优雅降级

public Mono<String> chatWithFallback(String message) {
    return aiClient.chat(createRequest("openai", message))
            .map(ChatMessage::getContent)
            .onErrorResume(e -> {
                // 尝试备用 Provider
                return aiClient.chat(createRequest("zhipu", message))
                        .map(ChatMessage::getContent);
            })
            .onErrorResume(e -> {
                // 返回默认响应
                return Mono.just("抱歉，服务暂时不可用");
            });
}

详细的错误处理指南请查看：错误处理指南

技术栈

• Spring Boot 3.x
• Spring AI 1.1.0
• Reactor (响应式编程)
• Jackson (JSON处理)
• Lombok