# java-openai-sdk

**Repository Path**: liu-qi-start/java-openai-sdk

## Basic Information

- **Project Name**: java-openai-sdk
- **Description**: 1、使用java开发语言，开发openai api接口调用支持
2、使用httpclient5发起openai api接口调用
3、使用Gson序列化与反序列化
4、支持文本生成(completions)、对话(/chat/completions)、向量化(embeddings)
5、支持tool call外部工具调用
6、支持检索增强生成
7、支持链式与AI对话
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-06-28
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# java-openai-sdk

#### 介绍
- 使用java开发语言，开发openai api接口调用支持
- 使用httpclient5发起openai api接口调用
- 使用Gson序列化与反序列化
- 支持文本生成(completions)、对话(/chat/completions)、向量化(embeddings)
- 支持流式响应，并提供了流式响应块数据合并。
- 支持tool call外部工具调用
- 支持检索增强生成
- 支持链式与AI对话
  - 内置对话记忆
  - 可配置外部工具，交互链会自主完成工具调用，并将结果提供给AI，由AI生成结果内容
  - 可配置向量检索器，通过用户输入文本进行向量化搜索内容，由AI基于检索内容生成结果

#### 软件架构
```
com.liuqi.openai.chain   对话交互链
├── impl: 对话交互链实现
│   └── RetrievalChatChain: 可检索的，通过用户输入查找内容
│   └── SimpleChatChain: 没有检索
├── result: 对话交互链中AI响应结果集
│   └── ChainResult: 对话交互链一轮对话的返回结果
│   └── Content: 正文内容
│   └── Function: 函数调用
│   └── Think: 思考内容
├── retriever: 检索器
│   └── EmbeddingStoreRetriever: 向量存储器检索
├── ChainStreamingHandler: 交互链中的流式响应回调处理器
├── OpenAiChain: 交互链
├── Retriever: 检索器
├── AbstractOpenAiChain: 交互链的基类
├── ChainExecutor: 交互链中的对话执行器，用户没发起一次对话，都创建一个新的执行器
├── OpenAiChainException: 异常处理

com.liuqi.openai.core   核心部分
├── client: 对接openai api的客户端
│   └── httpclient: 使用httpclient5实现http接口调用
│       └── HttpClientExecutor: openai 请求执行器，每次请求创建一个新的执行器
│       └── OpenAiHttpClient: openai httpclient  
│   └── Executor: 发起http openai请求的执行器
│   └── OpenAiClient: openai api 接口描述
│   └── StreamHandler: 流式响应的回调接口
│   └── AbstractOpenAiClient: 提供了构建openai客户端的构建基本参数
├── chat: 对话(/chat/completions) 请求参数与响应参数的描述
│   └── ChatCompletionRequest: 对话接口请求参数
│   └── ChatCompletionResponse: 对话接口响应参数
├── completion: 文本生成(completions) 请求参数与响应参数的描述
│   └── CompletionRequest: 文本生成接口请求参数
│   └── CompletionResponse: 文本生成接口响应参数
├── embedding: 向量化(embeddings) 请求参数与响应参数的描述
│   └── EmbeddingRequest: 向量化接口请求参数
│   └── EmbeddingResponse: 向量化接口响应参数
├── shared: api接口公共的 请求参数与响应参数的描述
│   └── StreamOptions: stream_options 请求参数
│   └── Usage: usage 响应参数(usage), 描述tokens计量
├── json: 流式响应数据块合并
│   └── GJson: Gson序列化，适用与opanai api入参和出参，需要满足驼峰与下划线的转换
│   └── RoleAdapter: 消息角色类型自定义适配器
├── merge: 流式响应数据块合并
│   └── MergeChunkChatCompletion: 对话(/chat/completions)接口 流式响应数据块合并
│   └── MergeChunkCompletion: 文本生成(completions)接口 流式响应数据块合并

com.liuqi.openai.data: openai所需要使用到的数据
├── document: 文档
│   └── parser: 文档解析
│   └── source: 文档数据源
│   └── splitter: 文档分割
├── message: openai 交互消息
│   └── ChatMessage: openai 交互消息父类
│   └── AiMessage: AI消息
│   └── SystemMessage: 系统消息
│   └── ToolResultMessage: 工具调用
│   └── UserMessage: 用户消息
│   └── ChatMessageType: 消息类型
├── tool: 定义外部工具调用
│   └── webhook: webhook工具
│       └── WebHook: webhook 请求信息描述
│       └── WebHookTool: 内置的webhook工具，实现http远程调用.
│   └── CustomTool: 自定义工具接口描述
│   └── ToolCallRequest: AI响应的工具调用描述

com.liuqi.openai.embedding: 向量相关数据
│   └── EmbeddingEntity: 向量数据存储实体类
│   └── EmbeddingStore: 向量数据存储器
│   └── ScoredResult: 向量数据检索查询结果，具有得分描述

com.liuqi.openai.keyword: 关键词，文本关键词提取、关键词检索内容
│   └── extractor: 提取器
│   └── retriever: 检索器

com.liuqi.openai.memory: 对话缓存/记忆
├── chat: 对话缓存/记忆
│   └── MessageWindowChatMemory: 最大窗口限制缓存器

com.liuqi.openai.model: 对openai client进行简化封装，简化openai api的调用。支持在model配置模型入参，后续调用opanai api，参数都会带上
├── handler: 流式响应回调
│   └── StreamingResponseHandler: 思考内容、内容、完成、错误 的回调
├── input: Prompt的格式化
│   └── Prompt: Prompt
│   └── PromptTemplate: Prompt模板，使用Mustache模板引擎解析
├── output: Ai 模型的统一格式输出
│   └── Response: Ai 模型的统一格式输出
│   └── TokenUsage: Token 使用
│   └── FinishReason: finish_reason 参数描述
├── StoppedStreamingResponseHandler: 流式响应回调处理器，可以通过此处理器进行主动停止响应
├── OpenAiChatModel: 对话模型
├── OpenAiCompletionModel: 文本生成模型
├── OpenAiEmbeddingModel: 向量化模型

com.liuqi.openai.util: 工具包
```

#### 测试用例
```
测试用例引用了logback作为日志输出，在resources目录下的logback.xml进行配置。
设置 <logger name="com.liuqi.openai" level="TRACE"/> trace级别，观察项目中的日志输出
```

#### 测试用例 opanai client

文本生成(/completion)、对话(/chat/completion)、向量化(/embedding)。
文本生成和对话包含流式与非流式的调用。
基于最原始的CURL方式实现。

- [创建客户端](src/test/java/test/openai/client/TestOpenAiClient.java)
- [对话](src/test/java/test/openai/client/executor/TestChatCompletion.java)
- [文本生成](src/test/java/test/openai/client/executor/TestCompletion.java)
- [向量化](src/test/java/test/openai/client/executor/TestEmbedding.java)

#### 测试用例 model

对openai client进行简化封装，简化openai api的调用。
在模型中一次性把入参进行配置，后续在发起openai api请求时，都会把入参带上，无需每次请求都进行设置。

- [对话模型](src/test/java/test/openai/model/TestOpenAiChatModel.java)
- [文本生成模型](src/test/java/test/openai/model/TestOpenAiCompletionModel.java)
- [向量化处理模型](src/test/java/test/openai/model/TestOpenAiEmbeddingModel.java)
- [可主动停止响应流](src/test/java/test/openai/model/TestStopStreamModel.java)
- [外部工具调用](src/test/java/test/openai/model/TestToolCallChatModel.java)


#### 测试用例 chain

- AI对话交互链
  - 内置对话记忆
  - 可配置外部工具，交互链会自主完成工具调用，并将结果提供给AI，由AI生成结果内容
  - 可配置向量检索器，通过用户输入文本进行向量化搜索内容，由AI基于检索内容生成结果

- [检索增强生成](src/test/java/test/openai/chain/TestRetrievalChatChain.java)
- [外部工具调用](src/test/java/test/openai/chain/TestSimpleChatChain.java)
- [主动停止响应流](src/test/java/test/openai/chain/TestStopChatChain.java)


#### 更多测试用例

- [更多测试用例](src/test/java/test/openai)