Kotlin 的 OpenAI API 客户端

适用于 OpenAI API 的 Kotlin 客户端，具备多平台和协程支持。

📦 设置

1. 通过将以下依赖项添加到 build.gradle 文件中来安装 OpenAI API Kotlin 客户端：

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.aallam.openai:openai-client:4.1.0"
}

2. 从 Ktor 的引擎 中选择一个并将其添加到您的依赖项中。

BOM

或者，您也可以使用 openai-client-bom，只需将以下依赖项添加到 build.gradle 文件中：

dependencies {
    // 导入 Kotlin API 客户端 BOM
    implementation platform('com.aallam.openai:openai-client-bom:4.1.0')

    // 定义不带版本号的依赖项
    implementation 'com.aallam.openai:openai-client'
    runtimeOnly 'io.ktor:ktor-client-okhttp'
}

多平台

在多平台项目中，将 openai 客户端依赖项添加到 commonMain，并为每个目标选择一个 引擎。

Maven

Gradle 是支持多平台所必需的，但您仍然可以在 Maven 项目中使用 JVM 客户端。不过，您仍需将 Ktor 的引擎 添加到您的依赖项中。

<dependencies>
    <dependency>
        <groupId>com.aallam.openai</groupId>
        <artifactId>openai-client-jvm</artifactId>
        <version>4.1.0</version>
    </dependency>
            
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp-jvm</artifactId>
        <version>3.0.0</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

BOM 不支持 Maven 项目。

⚡️ 入门

[!NOTE] OpenAI 建议使用环境变量来存储 API 密钥。 了解更多。

创建一个 OpenAI 客户端实例：

val openai = OpenAI(
    token = "your-api-key",
    timeout = Timeout(socket = 60.seconds),
    // 其他配置...
)

或者，您也可以使用预先配置的 OpenAIConfig 创建 OpenAI 实例：

val config = OpenAIConfig(
    token = apiKey,
    timeout = Timeout(socket = 60.seconds),
    // 其他配置...
)

val openAI = OpenAI(config)

使用您的 OpenAI 实例发送 API 请求。了解更多。

支持的功能

• 响应
• 模型
• 聊天
• 图片
• 嵌入
• 文件
• 微调
• 内容审核
• 音频
• 批处理

测试版

• 助手
• 线程
• 消息
• 运行
• 向量存储

已弃用

• 完成
• 微调
• 编辑

正在寻找分词器吗？试试 ktoken，一个用于文本分词的 Kotlin 库。

📚 指南

通过以下指南开始使用并深入了解如何使用 Kotlin 的 OpenAI API 客户端：

• 入门
• 聊天与工具调用
• 文件源指南
• 助手

ℹ️ 示例应用

示例应用位于 sample 目录下，请查看 README 以获取运行说明。

🔒 ProGuard / R8

特定规则已打包到 Jar 文件中，R8 可以自动解析这些规则。

📸 快照

repositories {
   //...
   maven { url 'https://central.sonatype.com/repository/maven-snapshots/' }
}

🛠️ 故障排除

有关常见问题及其解决方案，请参阅 故障排除指南。

🧪 测试

openai-client 的测试是实时集成测试，可能会产生需要付费的 API 流量。

• 默认设置（不计费）：禁用实时测试。
• 开启实时测试：设置 OPENAI_LIVE_TESTS=1 和 OPENAI_API_KEY。

示例：

# 免费/离线检查
./gradlew :openai-core:jvmTest :openai-core:jsTest :openai-core:wasmJsTest :openai-core:apiCheck :openai-client:apiCheck

# 实时冒烟测试（计费）
OPENAI_LIVE_TESTS=1 OPENAI_API_KEY=... ./gradlew :openai-client:jvmTest --tests "*.TestModels"

⭐️ 支持

喜欢这个项目吗？您可以这样帮助我们：

1. Star：在右上角给它点个赞吧！这对我们意义重大。
2. 贡献：发现 bug 或有功能建议？提交 PR 吧。
3. 反馈：有任何建议？开个 issue 或发起讨论吧。

📄 许可证

OpenAI Kotlin API 客户端是一个开源软件，采用 MIT 许可证授权。 这是一个非官方库，与 OpenAI 无关联，也未得到其认可。欢迎贡献。

openai-kotlin 快速上手指南

环境准备

• 运行环境：JDK 8+ 或 Kotlin Multiplatform 项目
• 构建工具：Gradle（推荐，支持多平台）或 Maven（仅支持 JVM）
• 前置依赖：需引入 Ktor HTTP Client 的任意引擎（如 ktor-client-okhttp）
• API 密钥：请提前在 OpenAI 平台 获取 API Key，建议通过环境变量管理

💡 提示：国内开发者若遇到网络延迟，可配置代理或在 Ktor 引擎中设置代理地址。

安装步骤

方式一：Gradle (推荐)

在 build.gradle 文件中添加以下配置：

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.aallam.openai:openai-client:4.1.0"
    // 必须添加一个 Ktor 引擎，例如 OkHttp
    runtimeOnly 'io.ktor:ktor-client-okhttp:3.0.0'
}

或使用 BOM 管理版本：

dependencies {
    // 导入 BOM
    implementation platform('com.aallam.openai:openai-client-bom:4.1.0')

    // 定义依赖（无需指定版本）
    implementation 'com.aallam.openai:openai-client'
    runtimeOnly 'io.ktor:ktor-client-okhttp'
}

方式二：Maven (仅 JVM)

在 pom.xml 中添加：

<dependencies>
    <dependency>
        <groupId>com.aallam.openai</groupId>
        <artifactId>openai-client-jvm</artifactId>
        <version>4.1.0</version>
    </dependency>
            
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp-jvm</artifactId>
        <version>3.0.0</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

基本使用

1. 初始化客户端

推荐使用环境变量存储密钥以确保安全。

import com.aallam.openai.api.OpenAI
import com.aallam.openai.api.logging.LogLevel
import kotlinx.coroutines.time.Timeout
import kotlin.time.Duration.Companion.seconds

// 方式 A：直接传入 Token
val openai = OpenAI(
    token = "your-api-key", 
    timeout = Timeout(socket = 60.seconds),
    logging = LogLevel.None // 生产环境建议关闭日志或设为 Body/Headers 以便调试
)

// 方式 B：使用配置对象
val config = OpenAIConfig(
    token = System.getenv("OPENAI_API_KEY"), // 从环境变量读取
    timeout = Timeout(socket = 60.seconds)
)
val openai = OpenAI(config)

2. 调用 Chat 接口示例

import com.aallam.openai.api.chat.ChatCompletionRequest
import com.aallam.openai.api.chat.ChatMessage
import com.aallam.openai.api.chat.ChatRole

suspend fun main() {
    val request = ChatCompletionRequest(
        model = "gpt-3.5-turbo",
        messages = listOf(
            ChatMessage(role = ChatRole.User, content = "你好，请用中文介绍你自己。")
        )
    )

    val response = openai.chatCompletion(request)
    println(response.choices.first().message.content)
    
    openai.close() // 使用完毕后关闭客户端
}

支持的核心功能

• Chat: 对话补全 (chatCompletion)
• Models: 模型列表 (models)
• Images: 图像生成 (imageGeneration)
• Embeddings: 向量嵌入 (embeddings)
• Audio: 语音转文字/文字转语音 (audioTranscription, audioSpeech)
• Assistants (Beta): 助手、线程与消息管理