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 客户端，具有多平台和协程功能。