OpenAI-Kotlin文档详解

开始

创建 client 的实例

ini 复制代码
val openai = OpenAI(
    token = "your-api-key",
    timeout = Timeout(socket = 60.seconds),
    // additional configurations...
)
参数及其类型 说明
token: kotlin.String 必需参数,你的 OpenAI API 密钥。这是访问 OpenAI 服务的身份验证令牌。
logging: com.aallam.openai.client.LoggingConfig 可选参数,配置 HTTP 请求和响应的日志记录。默认值为COMPILED_CODE,表示使用编译时代码提供的默认配置。
timeout: com.aallam.openai.api.http.Timeout 可选参数,配置 HTTP 请求的超时时间,包括连接超时、读取超时和写入超时
organization: kotlin.String? 可选参数,OpenAI 组织 ID。如果你属于多个组织,可以指定此参数以使用特定组织的 API 配额
headers: kotlin.collections.Map<kotlin.String, kotlin.String> 可选参数,额外的 HTTP 请求头。用于添加自定义元数据或扩展功能
host: com.aallam.openai.client.OpenAIHost 可选参数,指定 API 主机地址。默认使用 OpenAI 官方 API 地址,但你可以通过此参数指向自定义代理或兼容 API 的服务
proxy: com.aallam.openai.client.ProxyConfig? 可选参数,配置 HTTP 代理服务器。如果你需要通过代理服务器访问 API,可以设置此参数
retry: com.aallam.openai.client.RetryStrategy 可选参数,配置请求失败时的重试策略。包括重试次数、间隔时间和触发重试的条件
httpClientConfig: io.ktor.client.HttpClientConfig<*>.() -> kotlin.Unit 可选参数,提供 Ktor HTTP 客户端的自定义配置函数。用于更高级的 HTTP 客户端设置

模型

列出模型

列出当前可用的模型,并提供有关每个模型的基本信息,例如所有者和可用性。

kotlin 复制代码
import com.aallam.openai.api.model.Model
//...
val models: List<Model> = openAI.models()

检索模型

检索模型实例,提供有关模型的基本信息,例如所有者和权限。

ini 复制代码
val id = ModelId("text-ada-001")
val model: Model = openAI.model(id)

聊天

给定一个聊天对话,该模型将返回一个聊天完成响应。

创建聊天完成

为聊天消息创建完成。

ini 复制代码
val chatCompletionRequest = ChatCompletionRequest(
    model = ModelId("gpt-3.5-turbo"),
    messages = listOf(
        ChatMessage(
            role = ChatRole.System,
            content = "You are a helpful assistant!"
        ),
        ChatMessage(
            role = ChatRole.User,
            content = "Hello!"
        )
    )
)
val completion: ChatCompletion = openAI.chatCompletion(chatCompletionRequest)
// or, as flow
val completions: Flow<ChatCompletionChunk> = openAI.chatCompletions(chatCompletionRequest)

completion存储对话完成的信息,如果需要访问本次对话具体问题的回答字段,需要以下代码获取

ini 复制代码
response = completion.choices.firstOrNull()?.message?.content

图像

给定提示和/或输入图像,模型将生成新图像。

创建镜像

在给定提示的情况下创建图像。

ini 复制代码
val images = openAI.imageURL( // or openAI.imageJSON
    creation = ImageCreation(
        prompt = "A cute baby sea otter",
        model = ModelId("dall-e-3"),
        n = 2,
        size = ImageSize.is1024x1024
    )
)
prompt 生成图片的提示词
model 生成图片所使用的模型
n 生成图片个数
size 生成图片尺寸,目前只有256x256、512x512、1024x1024三个尺寸,DALL·E 3 特有尺寸:1792x1024和1024x1792

编辑图像

在给定原始图像和提示的情况下创建已编辑或扩展的图像。

ini 复制代码
val images = openAI.imageURL( // or openAI.imageJSON
    edit = ImageEdit(
        image = FileSource(name = "<filename>", source = imageSource),
        model = ModelId("dall-e-2"),
        mask = FileSource(name = "<filename>", source = maskSource),
        prompt = "a sunlit indoor lounge area with a pool containing a flamingo",
        n = 1,
        size = ImageSize.is1024x1024
    )
)
image 原始基础图像
model 默认:dall-e-2
mask 定义原始图像中哪些区域需要修改规则:遮罩区域将被修改非遮罩区域(黑色部分)保持不变必须是 RGBA PNG(带透明通道)
prompt 描述最终图像的文本指令
n 生成不同变体的数量
size 图片尺寸

创建图像变体

创建给定图像的变体。

ini 复制代码
val images = openAI.imageURL( // or openAI.imageJSON
    variation = ImageVariation(
        image = FileSource(name = "<filename>", source = imageSource),
        model = ModelId("dall-e-3"),
        n = 1,
        size = ImageSize.is1024x1024
    )
)

嵌入

获取给定输入的向量表示形式,机器学习模型和算法可以轻松使用该向量表示形式。

创建嵌入

创建表示输入文本的嵌入向量。

ini 复制代码
val embeddings = openAI.embeddings(
    request = EmbeddingRequest(
        model = ModelId("text-similarity-babbage-001"),
        input = listOf("The food was delicious and the waiter...")
    )
)

微调

管理微调作业,以根据您的特定训练数据定制模型。

创建微调作业

创建一个作业,用于从给定数据集微调指定模型。

响应包括已排队作业的详细信息,包括作业状态和完成后微调模型的名称。

无超参数

ini 复制代码
val request = FineTuningRequest(
    trainingFile = FileId("file-abc123"),
    model = ModelId("gpt-3.5-turbo"),
)
val fineTuningJob = client.fineTuningJob(request)

超参数

ini 复制代码
val request = FineTuningRequest(
    trainingFile = FileId("file-abc123"),
    model = ModelId("gpt-3.5-turbo"),
    hyperparameters = Hyperparameters(nEpochs = 2),
)
val fineTuningJob = client.fineTuningJob(request)

验证文件

ini 复制代码
val request = FineTuningRequest(
    trainingFile = FileId("file-abc123"),
    validation_file = FileId("file-def345"),
    model = ModelId("gpt-3.5-turbo"),
)
val fineTuningJob = client.fineTuningJob(request)

列出微调作业

列出组织的微调作业

ini 复制代码
val fineTuningJobs = client.fineTuningJobs(limit = 2)

检索微调作业

获取有关微调作业的信息。

ini 复制代码
val id = FineTuningId("ft-AF1WoRqd3aJAHsqc9NY7iL8F")
val fineTuningJob = client.fineTuningJob(id)

取消微调

立即取消微调作业。

bash 复制代码
val id = FineTuningId("ftjob-abc12")
client.cancel(id)

列出微调事件

获取微调作业的状态更新。

ini 复制代码
val id = FineTuningId("ftjob-abc12")
val fineTuningEvents = client.fineTuningEvents(id)

文件

Files 用于上传可与 Fine-tuning 等功能一起使用的文档。

列出文件

返回属于用户组织的文件列表。

ini 复制代码
val files = openAI.files()

上传文件

上传包含要跨各种端点/功能使用的文档的文件。 目前,一个组织上传的所有文件的大小最大为 1 GB。

ini 复制代码
val file = openAI.file(
    request = FileUpload(
        file = source,
        purpose = Purpose("fine-tune")
    )
)

删除文件

删除文件。

go 复制代码
openAI.delete(fileId)

检索文件

返回有关特定文件的信息。

ini 复制代码
val file = openAI.file(fileId)

检索文件内容

返回指定文件的内容

ini 复制代码
val bytes = openAI.download(fileId)

审核

给定输入文本,如果模型将其归类为违反 OpenAI 的内容策略,则输出。

创建审核

对文本是否违反 OpenAI 的内容策略进行分类

ini 复制代码
val moderation = openAI.moderations(
    request = ModerationRequest(
        input = "I want to kill them."
    )
)

完成

给定提示,模型将返回一个或多个预测完成,并且还可以返回 每个位置的替代代币。

创建完成请求

为提供的提示和参数创建补全

ini 复制代码
val completionRequest = CompletionRequest(
    model = ModelId("text-ada-001"),
    prompt = "Somebody once told me the world is gonna roll me",
    echo = true
)
val completion: TextCompletion = openAI.completion(completionRequest)
// or, as flow
val completions: Flow<TextCompletion> = openAI.completions(completionRequest)

线程

创建助理可以与之交互的线程。

创建线程

创建带有提示和说明的线程。

ini 复制代码
val thread = openAI.thread()

检索线程

检索线程。

ini 复制代码
val thread = openAI.thread(id = ThreadId("thread_abc123"))

修改线程

修改线程。

ini 复制代码
val thread = openAI.thread(
  id = ThreadId("thread_abc123"),
  metadata = mapOf(
    "modified" to "true",
    "user" to "abc123"
  )
)

删除线程

删除线程。

ini 复制代码
openAI.delete(id = ThreadId("thread_abc123"))

消息

在话题中创建消息

创建消息

创建消息。

ini 复制代码
val message = openAI.message(
  threadId = ThreadId("thread_abc123"),
  request = MessageRequest(
    role = Role.User,
    content = "How does AI work? Explain it in simple terms.",
  )
)

检索消息

检索消息。

ini 复制代码
val message = openAI.message(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123")
)

修改消息

修改消息。

ini 复制代码
val message = openAI.message(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123"),
  metadata = mapOf(
    "modified" to "true",
    "user" to "abc123"
  )
)

列出消息

返回给定线程的消息列表。

ini 复制代码
val messages = openAI.messages(threadId = ThreadId("thread_abc123"))

检索消息文件

附加到 message 的文件列表

ini 复制代码
val messageFile = openAI.messageFile(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123"),
  fileId = FileId("file_abc123")
)

列出消息文件

返回消息文件列表。

ini 复制代码
val messageFiles = openAI.messageFiles(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123")
)

运行

表示在线程上运行的执行。

创建运行

创建运行。

ini 复制代码
val run = openAI.createRun(
  threadId = ThreadId("thread_abc123"),
  request = RunRequest(assistantId = AssistantId("assistant_abc123")),
)

检索运行

检索运行。

ini 复制代码
val run = openAI.getRun(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123")
)

修改运行

修改运行。

ini 复制代码
val run = openAI.updateRun(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123"),
  metadata = mapOf("user_id" to "user_abc123")
)

列出运行

返回属于线程的运行列表。

ini 复制代码
val runs = openAI.runs(threadId = ThreadId("thread_abc123"))

取消运行

取消Status.InProgress

ini 复制代码
openAI.cancel(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123")
)

创建线程并运行

创建一个线程并在一个请求中运行它。

ini 复制代码
openAI.createThreadRun(
    request = ThreadRunRequest(
        assistantId = AssistantId("asst_abc123"),
        thread = ThreadRequest(
            messages = listOf(
                ThreadMessage(
                    role = Role.User,
                    content = "Explain deep learning to a 5 year old."
                )
            )
        ),
    )
)

检索运行步骤

检索运行步骤。

ini 复制代码
val runStep = openAI.runStep(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123"),
  stepId = RunStepId("step_abc123")
)

列出运行步骤

返回属于运行的运行步骤列表。

ini 复制代码
val runSteps = openAI.runSteps(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123")
)

事件流式处理

创建一个线程并在一个请求中运行它,并处理流式处理事件

ini 复制代码
openAI.createStreamingThreadRun(
    request = ThreadRunRequest(
        assistantId = AssistantId("asst_abc123"),
        thread = ThreadRequest(
            messages = listOf(
                ThreadMessage(
                    role = Role.User,
                    content = "Explain deep learning to a 5 year old."
                )
            )
        ),
    )
      .onEach { assistantStreamEvent: AssistantStreamEvent -> println(assistantStreamEvent) }
      .collect()
)

从 AssistantStreamEvent 获取数据对象。

kotlin 复制代码
//Type of data for generic type can be found in AssistantStreamEventType
when(assistantStreamEvent.type) {
    AssistantStreamEventType.THREAD_CREATED -> {
        val thread = assistantStreamEvent.getData<Thread>()
        ...
    }
    AssistantStreamEventType.MESSAGE_CREATED -> {
        val message = assistantStreamEvent.getData<Message>()
        ...
    }
    AssistantStreamEventType.UNKNOWN -> {
        //Data field is a string and can be used instead of calling getData
        val data = assistantStreamEvent.data
        //Handle unknown message type
    }
}

如果在更新库之前发布了新的事件类型,则可以通过提供 KSerializer 来创建和反序列化自己的类型。

kotlin 复制代码
when(assistantStreamEvent.type) {
    AssistantStreamEventType.UNKNOWN -> {
        val data = assistantStreamEvent.getDate<MyCustomType>(myCustomSerializer)
        ...
    }
}

详见openai-kotlin的GitHub主页aallam/openai-kotlin:适用于 Kotlin 的 OpenAI API 客户端,具有多平台和协程功能。

相关推荐
sulikey18 小时前
从零配置一个规范的 Python Git 仓库(适用于 Gitee / GitHub)
git·python·pycharm·gitee·github
whysqwhw18 小时前
KuiklyUI声明式组件体系的实现分析
github
whysqwhw19 小时前
ComposeView 的上下游继承关系及相关类/接口分析
github
逛逛GitHub20 小时前
登上 GitHub 热榜!一口气调用多个 AI 大模型开源神器。
github
21号 121 小时前
4.客户端(Redis)
开发语言·数据库·github
梦想CAD控件21 小时前
网页CAD中组(Group)功能的二次开发
前端·javascript·github
米诺zuo1 天前
不同的项目仓库配置不同的github账号
github
修炼室1 天前
如何在GitHub上查看自己提过的Issues
github
CoderJia程序员甲1 天前
GitHub 热榜项目 - 日榜(2025-10-21)
ai·开源·github·ai编程·github热榜
tokepson1 天前
技术 | 在单台电脑上管理多个 GitHub 账户并解决推送问题(测试中)
github·技术·记录