OpenAI-Kotlin文档详解
开始
创建 client 的实例
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 客户端设置 |
模型
列出模型
列出当前可用的模型，并提供有关每个模型的基本信息，例如所有者和可用性。
import com.aallam.openai.api.model.Model
//...
val models: List<Model> = openAI.models()检索模型
检索模型实例，提供有关模型的基本信息，例如所有者和权限。
val id = ModelId("text-ada-001")
val model: Model = openAI.model(id)聊天
给定一个聊天对话，该模型将返回一个聊天完成响应。
创建聊天完成
为聊天消息创建完成。
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存储对话完成的信息，如果需要访问本次对话具体问题的回答字段，需要以下代码获取
response = completion.choices.firstOrNull()?.message?.content图像
给定提示和/或输入图像，模型将生成新图像。
创建镜像
在给定提示的情况下创建图像。
val images = openAI.imageURL( // or openAI.imageJSONcreation = 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 |
编辑图像
在给定原始图像和提示的情况下创建已编辑或扩展的图像。
val images = openAI.imageURL( // or openAI.imageJSONedit = 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 | 默认： |
| mask | 定义原始图像中哪些区域需要修改 规则： 遮罩区域将被修改 非遮罩区域（黑色部分）保持不变 必须是 RGBA PNG（带透明通道） |
| prompt | 描述最终图像的文本指令 |
| n | 生成不同变体的数量 |
| size | 图片尺寸 |
创建图像变体
创建给定图像的变体。
val images = openAI.imageURL( // or openAI.imageJSONvariation = ImageVariation(image = FileSource(name = "<filename>", source = imageSource),model = ModelId("dall-e-3"),n = 1,size = ImageSize.is1024x1024)
)嵌入
获取给定输入的向量表示形式，机器学习模型和算法可以轻松使用该向量表示形式。
创建嵌入
创建表示输入文本的嵌入向量。
val embeddings = openAI.embeddings(request = EmbeddingRequest(model = ModelId("text-similarity-babbage-001"),input = listOf("The food was delicious and the waiter..."))
)微调
管理微调作业，以根据您的特定训练数据定制模型。
创建微调作业
创建一个作业，用于从给定数据集微调指定模型。
响应包括已排队作业的详细信息，包括作业状态和完成后微调模型的名称。
无超参数
val request = FineTuningRequest(trainingFile = FileId("file-abc123"),model = ModelId("gpt-3.5-turbo"),
)
val fineTuningJob = client.fineTuningJob(request)超参数
val request = FineTuningRequest(trainingFile = FileId("file-abc123"),model = ModelId("gpt-3.5-turbo"),hyperparameters = Hyperparameters(nEpochs = 2),
)
val fineTuningJob = client.fineTuningJob(request)验证文件
val request = FineTuningRequest(trainingFile = FileId("file-abc123"),validation_file = FileId("file-def345"),model = ModelId("gpt-3.5-turbo"),
)
val fineTuningJob = client.fineTuningJob(request)列出微调作业
列出组织的微调作业
val fineTuningJobs = client.fineTuningJobs(limit = 2)检索微调作业
获取有关微调作业的信息。
val id = FineTuningId("ft-AF1WoRqd3aJAHsqc9NY7iL8F")
val fineTuningJob = client.fineTuningJob(id)取消微调
立即取消微调作业。
val id = FineTuningId("ftjob-abc12")
client.cancel(id)列出微调事件
获取微调作业的状态更新。
val id = FineTuningId("ftjob-abc12")
val fineTuningEvents = client.fineTuningEvents(id)文件
Files 用于上传可与 Fine-tuning 等功能一起使用的文档。
列出文件
返回属于用户组织的文件列表。
val files = openAI.files()上传文件
上传包含要跨各种端点/功能使用的文档的文件。 目前，一个组织上传的所有文件的大小最大为 1 GB。
val file = openAI.file(request = FileUpload(file = source,purpose = Purpose("fine-tune"))
)删除文件
删除文件。
openAI.delete(fileId)检索文件
返回有关特定文件的信息。
val file = openAI.file(fileId)检索文件内容
返回指定文件的内容
val bytes = openAI.download(fileId)审核
给定输入文本，如果模型将其归类为违反 OpenAI 的内容策略，则输出。
创建审核
对文本是否违反 OpenAI 的内容策略进行分类
val moderation = openAI.moderations(request = ModerationRequest(input = "I want to kill them.")
)完成
给定提示，模型将返回一个或多个预测完成，并且还可以返回 每个位置的替代代币。创建完成请求
为提供的提示和参数创建补全
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)线程
创建助理可以与之交互的线程。
创建线程
创建带有提示和说明的线程。
val thread = openAI.thread()检索线程
检索线程。
val thread = openAI.thread(id = ThreadId("thread_abc123"))修改线程
修改线程。
val thread = openAI.thread(id = ThreadId("thread_abc123"),metadata = mapOf("modified" to "true","user" to "abc123")
)删除线程
删除线程。
openAI.delete(id = ThreadId("thread_abc123"))消息
在话题中创建消息
创建消息
创建消息。
val message = openAI.message(threadId = ThreadId("thread_abc123"),request = MessageRequest(role = Role.User,content = "How does AI work? Explain it in simple terms.",)
)检索消息
检索消息。
val message = openAI.message(threadId = ThreadId("thread_abc123"),messageId = MessageId("message_abc123")
)修改消息
修改消息。
val message = openAI.message(threadId = ThreadId("thread_abc123"),messageId = MessageId("message_abc123"),metadata = mapOf("modified" to "true","user" to "abc123")
)列出消息
返回给定线程的消息列表。
val messages = openAI.messages(threadId = ThreadId("thread_abc123"))检索消息文件
附加到 message 的文件列表
val messageFile = openAI.messageFile(threadId = ThreadId("thread_abc123"),messageId = MessageId("message_abc123"),fileId = FileId("file_abc123")
)列出消息文件
返回消息文件列表。
val messageFiles = openAI.messageFiles(threadId = ThreadId("thread_abc123"),messageId = MessageId("message_abc123")
)运行
表示在线程上运行的执行。
创建运行
创建运行。
val run = openAI.createRun(threadId = ThreadId("thread_abc123"),request = RunRequest(assistantId = AssistantId("assistant_abc123")),
)检索运行
检索运行。
val run = openAI.getRun(threadId = ThreadId("thread_abc123"),runId = RunId("run_abc123")
)修改运行
修改运行。
val run = openAI.updateRun(threadId = ThreadId("thread_abc123"),runId = RunId("run_abc123"),metadata = mapOf("user_id" to "user_abc123")
)列出运行
返回属于线程的运行列表。
val runs = openAI.runs(threadId = ThreadId("thread_abc123"))取消运行
取消Status.InProgress
openAI.cancel(threadId = ThreadId("thread_abc123"),runId = RunId("run_abc123")
)创建线程并运行
创建一个线程并在一个请求中运行它。
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."))),)
)检索运行步骤
检索运行步骤。
val runStep = openAI.runStep(threadId = ThreadId("thread_abc123"),runId = RunId("run_abc123"),stepId = RunStepId("step_abc123")
)列出运行步骤
返回属于运行的运行步骤列表。
val runSteps = openAI.runSteps(threadId = ThreadId("thread_abc123"),runId = RunId("run_abc123")
)事件流式处理
创建一个线程并在一个请求中运行它，并处理流式处理事件
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 获取数据对象。
//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 getDataval data = assistantStreamEvent.data//Handle unknown message type}
}如果在更新库之前发布了新的事件类型，则可以通过提供 KSerializer 来创建和反序列化自己的类型。
when(assistantStreamEvent.type) {AssistantStreamEventType.UNKNOWN -> {val data = assistantStreamEvent.getDate<MyCustomType>(myCustomSerializer)...}
}详见openai-kotlin的GitHub主页aallam/openai-kotlin：适用于 Kotlin 的 OpenAI API 客户端，具有多平台和协程功能。