CleverBird

CleverBird 是一个 Swift 包，它提供了一种便捷的方式来与 OpenAI 的聊天 API 交互并执行各种任务，包括 token 计数和编码。该包旨在通过使聊天线程成为交互的中心来提供卓越的开发者体验 (DX)。

CleverBird 包括对文档嵌入和相似性查询的支持。这使其成为适用于广泛应用的通用工具，尤其是在聊天提示需要增强上下文记忆的情况下。

CleverBird 专注于基于聊天的交互，并使其变得非常出色。

请注意，CleverBird 是一个非官方的包，并非由 OpenAI 本身提供。

功能

核心功能

使用 Swift 的 async/await 语法进行异步 API 调用
实时生成内容的流式响应
内置 token 计数，用于使用量限制计算

特殊功能

Token 编码：通过 TokenEncoder 类促进 token 计数和编码。
文档嵌入和相似性查询：利用 EmbeddedDocumentStore 类来管理和查询文档相似性。

使用说明

导入 CleverBird 包

import CleverBird

使用您的 API 密钥初始化一个 OpenAIAPIConnection。请注意，API 密钥应始终从环境变量加载，而不是硬编码到您的源代码中。加载 API 密钥后，将其传递给连接的初始化程序。

let openAIAPIConnection = OpenAIAPIConnection(apiKey: <OPENAI_API_KEY>)

创建一个 ChatThread 实例，并将系统、用户或助手消息添加到聊天线程

let chatThread = ChatThread()
    .addSystemMessage(content: "You are a helpful assistant.")
    .addUserMessage(content: "Who won the world series in 2020?")

使用聊天线程并传递 API 连接来生成完成

let completion = try await chatThread.complete(using: openAIAPIConnection)

complete(using:) 方法还包括各种可选参数

let completion = chatThread.complete(
    using: openAIAPIConnection, 
    model: .gpt4o, 
    temperature: 0.7, 
    maxTokens: 500
)

在上面的示例中，我们使用特定的模型、温度和最大 token 数创建了一个完成。除了 connection 之外的所有参数都是可选的。完整参数列表如下

connection: API 连接对象（必需）。
model: 用于完成的模型。
temperature: 控制随机性。较高的值（最高为 1）生成更随机的输出，而较低的值生成更确定性的输出。
topP: 核采样参数。它指定要用预测覆盖的概率质量。
stop: 一个字符串数组。当模型遇到任何这些字符串时，将停止生成。
maxTokens: 要生成的最大 token 数。
presencePenalty: 对使用已经使用过的 token 的惩罚。
frequencyPenalty: 对使用频繁 token 的惩罚。
functions: 可供模型使用的工具函数（也称为“动作”）。
functionCallMode: 函数调用模式：.auto、.none 或 .specific。

响应消息会自动附加到线程上，因此您只需添加新的用户消息并请求其他完成即可继续与之交互。

如果您愿意，您可以使用同一线程中后续调用中相同参数的不同值来自定义每次对 complete(using:) 的调用

let completion = try await chatThread.complete(
    using: openAIAPIConnection,
    model: .gpt35Turbo, 
    temperature: 0.5, 
    maxTokens: 300
)

使用聊天线程的流式版本生成流式完成

let chatThread = ChatThread().withStreaming()
let completionStream = try await chatThread.complete(using: openAIAPIConnection)
for try await messageChunk in completionStream {
    print("Received message chunk: \(messageChunk)")
}

与非流式完成一样，消息将在完成流式传输后自动附加到线程上，但该流允许您看到它正在通过。

要包含使用量（提示和完成中使用的 token 数），请在 complete 方法中添加设置 streamOptions。使用情况在流完成后可用作 StreamableChatThread 的属性。

let chatThread = ChatThread().withStreaming()
let completionStream = try await chatThread.complete(using: openAIAPIConnection, includeUsage: true)
for try await messageChunk in completionStream {
    print("Received message chunk: \(messageChunk)")
}
if let usage = completionStream.usage {
    print("Usage: \(usage)")
}

计算聊天线程中消息的 token 数

let tokenCount = try chatThread.tokenCount()

如果您需要在聊天线程之外计数 token 或编码/解码文本，请使用 TokenEncoder 类

let tokenEncoder = try TokenEncoder(model: .gpt3)
let encodedTokens = try tokenEncoder.encode(text: "Hello, world!")
let decodedText = try tokenEncoder.decode(tokens: encodedTokens)

使用函数

CleverBird 支持函数调用。这一强大的功能允许开发者定义自己的自定义命令，从而更容易控制 AI 的行为。函数调用可以包含在 ChatThread 中，并在 complete() 方法中使用。

首先，定义您的函数参数和函数本身。 Function.Parameters 类用于设置函数的属性和必需参数。

let getCurrentWeatherParameters = Function.Parameters(
    properties: [
        "location": Function.Parameters.Property(type: .string,
                                                 description: "The city and state, e.g. San Francisco, CA"),
        "format": Function.Parameters.Property(type: .string,
                                               description: "The temperature unit to use. Infer this from the user's location.",
                                               enumCases: ["celsius", "fahrenheit"])
    ],
    required: ["location", "format"])

let getCurrentWeather = Function(name: "get_current_weather",
                                 description: "Get the current weather",
                                 parameters: getCurrentWeatherParameters)

然后，使用您的 API 连接和函数数组初始化您的 ChatThread

let chatThread = ChatThread(functions: [getCurrentWeather])
    .addSystemMessage(content: "You are a helpful assistant.")

最后，调用 complete(using:) 函数以生成响应。如果助手需要在对话期间执行函数，它将使用您提供的函数定义。

请注意，目前只有非流式完成支持函数。

使用嵌入

EmbeddedDocumentStore 类提供了一种便捷的方式来管理和查询基于相似性的文档集合。此类允许您

将文档添加到内部存储。
使用指定的模型为这些文档生成嵌入。
查询存储以查找与给定输入文档相似的文档。

首先，将 EmbeddedDocumentStore 的实例添加到您的代码中

let openAIAPIConnection = OpenAIAPIConnection(apiKey: "your_api_key_here")
let embeddedDocumentStore = EmbeddedDocumentStore(connection: connection)

您可以将单个文档或一批文档添加到存储。

let singleDocument = "My single document"
try await embeddedDocumentStore.embedAndStore(singleDocument)

let documentCollection = ["First document", "Second document", "Third document"]
try await embeddedDocumentStore.embedAndStore(documentCollection)

您可以查询存储以查找与输入文档相似的文档。

let similarityResults = try await embeddedDocumentStore.queryDocumentSimilarity("Query text here")
let mostSimilarResult = similarityResults.first?.document ?? "No result returned"

存储可以保存到文件（以 JSON 格式表示）并从文件加载，以实现持久存储。

embeddedDocumentStore.save(to: fileURL)
embeddedDocumentStore.load(from: fileURL)

许可

CleverBird 由 B.T. Franklin (@btfranklin) 从 2023 年开始编写，并根据 MIT 许可证获得许可。请参阅 LICENSE.md。