# easy-llm

**Repository Path**: wingahi/easy-llm

## Basic Information

- **Project Name**: easy-llm
- **Description**: No description available
- **Primary Language**: Java
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-08
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy LLM SDK

一个集成主流大语言模型的Java SDK，支持OpenAI、DeepSeek、通义千问、Gemini等多种模型，提供统一的API接口方便开发者使用。

## 项目结构

```
easy-llm/
├── easy-llm-common/             # 公共组件模块
├── easy-llm-deepseek/           # DeepSeek模型实现
├── easy-llm-gemini/             # Gemini模型实现
├── easy-llm-openai/             # OpenAI模型实现
├── easy-llm-tongyi/             # 通义千问模型实现
├── easy-llm-springboot-starter/ # Spring Boot Starter
└── easy-llm-parent/             # 父模块配置
```

## 技术栈

- Java 17
- Maven
- OkHttp / HttpClient (用于API调用)
- Jackson (JSON处理)

## 功能特性

1. **多模型支持**：集成OpenAI、DeepSeek、通义千问、Gemini等主流大语言模型
2. **统一API**：提供统一的API接口，开发者无需关心不同模型的API差异
3. **模块化设计**：每个模型独立成模块，便于扩展和维护
4. **配置灵活**：支持多种配置方式，方便集成到不同项目中
5. **Spring Boot集成**：提供Spring Boot Starter，快速集成到Spring Boot项目中
6. **流式输出**：支持模型响应的流式输出
7. **轻量级**：核心依赖精简，易于嵌入到现有项目

## 快速开始

### 1. 环境准备

- Java 17+
- Maven 3.6+

### 2. 引入依赖

#### 2.1 Spring Boot项目（推荐）

直接引入Spring Boot Starter：

```xml
<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-springboot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

#### 2.2 非Spring Boot项目

在项目的pom.xml文件中添加以下依赖：

```xml
<!-- 父模块 -->
<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-parent</artifactId>
    <version>1.0.0</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<!-- 引入公共模块 -->
<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-common</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- 引入所需的模型实现 -->
<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-deepseek</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-tongyi</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-gemini</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>com.wgh.easyllm</groupId>
    <artifactId>easy-llm-openai</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 3. 配置

#### 3.1 Spring Boot项目配置

在`application.properties`或`application.yml`中添加以下配置：

```properties
# 初始化方式：file(默认) 或 db
easy-llm.init-type=file

# DeepSeek客户端配置
easy-llm.clients.deepseek.model-type=deepseek
easy-llm.clients.deepseek.api-key=your-api-key
easy-llm.clients.deepseek.base-url=https://api.deepseek.com
easy-llm.clients.deepseek.model=deepseek-chat

# 通义千问客户端配置
easy-llm.clients.tongyi.model-type=tongyi
easy-llm.clients.tongyi.api-key=your-api-key
easy-llm.clients.tongyi.base-url=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
easy-llm.clients.tongyi.model=qwen-plus

# Gemini客户端配置
easy-llm.clients.gemini.model-type=gemini
easy-llm.clients.gemini.api-key=your-api-key
easy-llm.clients.gemini.base-url=https://generativelanguage.googleapis.com/v1
easy-llm.clients.gemini.model=gemini-pro

# OpenAI客户端配置
easy-llm.clients.openai.model-type=openai
easy-llm.clients.openai.api-key=your-api-key
easy-llm.clients.openai.base-url=https://api.openai.com/v1
easy-llm.clients.openai.model=gpt-3.5-turbo
```

### 4. 使用示例

#### 4.1 Spring Boot项目用法

```java
import com.wgh.easyllm.common.client.BaseLLMClient;
import com.wgh.easyllm.common.client.LLMClientFactory;
import com.wgh.easyllm.common.model.request.ChatMessage;
import com.wgh.easyllm.common.model.request.ChatRequest;
import com.wgh.easyllm.common.model.response.ChatResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class MyLLMService {
    
    public String chat(String clientName, String content) {
        // 获取客户端
        BaseLLMClient client = LLMClientFactory.getClient(clientName);
        
        // 构建聊天请求
        ChatRequest request = new ChatRequest();
        request.addMessage(new ChatMessage("user", content));
        
        // 发送请求
        ChatResponse response = client.chat(request);
        
        return response.getContent();
    }
}
```

#### 4.2 非Spring Boot项目用法

```java
// 导入必要的类
import com.wgh.easyllm.common.client.BaseLLMClient;
import com.wgh.easyllm.common.client.LLMClientFactory;
import com.wgh.easyllm.common.config.LLMConfig;
import com.wgh.easyllm.common.model.request.ChatMessage;
import com.wgh.easyllm.common.model.request.ChatRequest;
import com.wgh.easyllm.common.model.response.ChatResponse;

// 创建配置
LLMConfig config = new LLMConfig();
config.setModelType("deepseek");
config.setApiKey("your-api-key");
config.setBaseUrl("https://api.deepseek.com");
config.setModel("deepseek-chat");

// 创建客户端
BaseLLMClient client = LLMClientFactory.createClient(config);

// 构建聊天请求
ChatRequest request = new ChatRequest();
request.addMessage(new ChatMessage("user", "Hello, world!"));

// 发送请求
ChatResponse response = client.chat(request);

// 处理响应
System.out.println(response.getContent());
```

## 支持的模型类型

- `deepseek` - DeepSeek模型
- `tongyi` - 通义千问模型
- `gemini` - Gemini模型
- `openai` - OpenAI模型

## 核心API

### BaseLLMClient接口

```java
public interface BaseLLMClient {
    // 聊天对话
    ChatResponse chat(ChatRequest request);
    
    // 流式聊天对话
    void chatStream(ChatRequest request, StreamCallback callback);
    
    // 生成文本
    LLMResponse generateText(LLMRequest request);
    
    // 流式生成文本
    void generateTextStream(LLMRequest request, StreamCallback callback);
}
```

### 主要请求/响应类

- `ChatRequest` - 聊天请求
  - `messages`: 对话消息列表
  - `temperature`: 生成温度，控制输出的随机性
  - `maxTokens`: 最大生成令牌数
  
- `ChatResponse` - 聊天响应
  - `content`: 生成的回复内容
  - `tokensUsed`: 使用的令牌数
  
- `LLMRequest` - 文本生成请求
  - `prompt`: 输入的提示文本
  - `temperature`: 生成温度，控制输出的随机性
  - `maxTokens`: 最大生成令牌数
  
- `LLMResponse` - 文本生成响应
  - `text`: 生成的文本
  - `tokensUsed`: 使用的令牌数
  
- `StreamCallback` - 流式响应回调接口
  - `onStart()`: 流开始时调用
  - `onToken(String token)`: 收到新令牌时调用
  - `onComplete()`: 流结束时调用
  - `onError(Exception e)`: 发生错误时调用

## 构建项目

在项目根目录执行以下命令构建项目：

```bash
cd easy-llm-parent
mvn clean install
```

## 运行测试

```bash
# 运行特定模型的测试
mvn test -pl easy-llm-springboot-starter -Dtest=DeepseekClientTest
mvn test -pl easy-llm-springboot-starter -Dtest=TongyiClientTest
mvn test -pl easy-llm-springboot-starter -Dtest=GeminiClientTest
mvn test -pl easy-llm-springboot-starter -Dtest=OpenaiClientTest

# 运行特定测试方法
mvn test -pl easy-llm-springboot-starter -Dtest=DeepseekClientTest#testGetDefaultDeepseekClient

# 运行所有测试
mvn test
```

## 扩展自定义模型

要添加新的模型支持，可以按照以下步骤：

1. 创建一个新的模块，命名为 `easy-llm-{model-name}`
2. 在新模块中实现 `BaseLLMClient` 接口
3. 确保新模型的客户端类位于 `com.wgh.easyllm.{model-name}.client` 包下
4. 添加相应的请求/响应类
5. 客户端类名应为 `{ModelName}Client`，例如：`MyModelClient`

LLMClientFactory会自动根据模型类型加载对应的客户端实现。

## 许可证

MIT License