OpenAI

此仓库包含由 Swift 社区维护的 OpenAI 公共 API 实现。

• 安装
  • Swift 包管理器
• 使用
  • 初始化
  • 除 OpenAI 外的其他提供商使用 SDK
  • 取消请求
• 文本与提示
  • 响应
  • 聊天补全
• 函数调用
• 工具
  • MCP (模型上下文协议)
    • MCP 工具集成
• 图像
  • 创建图像
  • 创建图像编辑
  • 创建图像变体
• 音频
  • 音频创建语音
  • 音频转录
  • 音频翻译
• 结构化输出
• 专用模型
  • 嵌入
  • 审核
• 助手（测试版）
  • 创建助手
  • 修改助手
  • 列出助手
  • 线程
    • 创建线程
    • 创建并运行线程
    • 获取线程消息
    • 添加消息到线程
  • 运行
    • 创建运行
    • 检索运行
    • 检索运行步骤
    • 提交运行工具输出
  • 文件
    • 上传文件
• 其他 API
  • 模型
    • 列出模型
    • 检索模型
  • 工具类
• 支持其他提供商：Gemini, DeepSeek, Perplexity, OpenRouter 等
• 示例项目
• 贡献指南
• 链接
• 许可证

文档

本库的类型和方法的实现与 REST API 文档紧密一致，可在 platform.openai.com 找到。

安装

Swift 包管理器

要使用 Swift Package Manager 将 OpenAI 集成到您的 Xcode 项目中：

1. 在 Xcode 中，前往 File > Add Package Dependencies...
2. 输入仓库 URL：https://github.com/MacPaw/OpenAI.git
3. 选择您想要的依赖规则（例如，“Up to Next Major Version"）。

或者，您可以直接将其添加到您的 Package.swift 文件中：

dependencies: [
    .package(url: "https://github.com/MacPaw/OpenAI.git", branch: "main")
]

使用

初始化

要初始化 API 实例，您需要从您的 OpenAI 组织 获取 API 令牌。

请记住您的 API 密钥是机密！ 不要与他人分享它，也不要将其暴露在任何客户端代码（浏览器、应用）中。生产请求必须通过您自己的后端服务器路由，在那里您可以安全地从环境变量或密钥管理服务加载您的 API 密钥。

一旦您有了令牌，您就可以初始化 OpenAI 类，这是访问 API 的入口点。

⚠️ OpenAI 强烈建议客户端应用程序的开发人员通过单独的后台服务代理请求，以保护其 API 密钥安全。API 密钥可以访问和操作客户计费、用量和组织数据，因此 暴露 它们存在重大风险。

let openAI = OpenAI(apiToken: "YOUR_TOKEN_HERE")

可选地，您可以使用令牌、组织标识符和超时时间间隔初始化 OpenAI。

let configuration = OpenAI.Configuration(token: "YOUR_TOKEN_HERE", organizationIdentifier: "YOUR_ORGANIZATION_ID_HERE", timeoutInterval: 60.0)
let openAI = OpenAI(configuration: configuration)

有关可以在初始化时传递以进行自定义的更多值，请参见 OpenAI.Configuration，例如：host, basePath, port, scheme 和 customHeaders。

一旦您拥有令牌并初始化了实例，您就可以发起请求了。

除 OpenAI 外的其他提供商使用 SDK

此 SDK 更专注于与 OpenAI Platform 配合使用，但也支持与 OpenAI 兼容 API 的其他提供商。

在 Configuration 中使用 .relaxed 解析选项，或在此处查看更多详细信息 #支持其他提供商。

取消请求

对于 Swift Concurrency 调用，您可以简单地取消调用任务，相应的底层 URLSessionDataTask 会自动取消。

let task = Task {
    do {
        let chatResult = try await openAIClient.chats(query: .init(messages: [], model: "asd"))
    } catch {
        // Handle cancellation or error
    }
}
            
task.cancel()

let cancellableRequest = object.chats(query: query, completion: { _ in })
cancellableReques

let subscription = openAIClient
    .images(query: query)
    .sink(receiveCompletion: { completion in }, receiveValue: { imagesResult in })
    
subscription.cancel()

文本与提示

Responses

在 OpenAIProtocol 上使用 responses 变量来调用 Responses API 方法。

public protocol OpenAIProtocol {
    // ...
    var responses: ResponsesEndpointProtocol { get }
    // ...
}

通过向方法传递 CreateModelResponseQuery 来指定参数。获取 ResponseObject 或 ResponseStreamEvent 事件流作为响应。

示例：从简单提示生成文本

let client: OpenAIProtocol = /* client initialization code */

let query = CreateModelResponseQuery(
    input: .textInput("Write a one-sentence bedtime story about a unicorn."),
    model: .gpt4_1
)

let response: ResponseObject = try await client.responses.createResponse(query: query)
// ...

ResponseObject(
  createdAt: 1752146109,
  error: nil,
  id: "resp_686fa0bd8f588198affbbf5a8089e2d208a5f6e2111e31f5",
  incompleteDetails: nil,
  instructions: nil,
  maxOutputTokens: nil,
  metadata: [:],
  model: "gpt-4.1-2025-04-14",
  object: "response",
  output: [
    OpenAI.OutputItem.outputMessage(
      OpenAI.Components.Schemas.OutputMessage(
        id: "msg_686fa0bee24881988a4d1588d7f65c0408a5f6e2111e31f5",
        _type: OpenAI.Components.Schemas.OutputMessage._TypePayload.message,
        role: OpenAI.Components.Schemas.OutputMessage.RolePayload.assistant,
        content: [
          OpenAI.Components.Schemas.OutputContent.OutputTextContent(
            OpenAI.Components.Schemas.OutputTextContent(
              _type: OpenAI.Components.Schemas.OutputTextContent._TypePayload.outputText,
              text: "Under a sky full of twinkling stars, a gentle unicorn named Luna danced through fields of stardust, spreading sweet dreams to every sleeping child.",
              annotations: [],
              logprobs: Optional([])
            )
          )
        ],
        status: OpenAI.Components.Schemas.OutputMessage.StatusPayload.completed
      )
    )
  ],
  parallelToolCalls: true,
  previousResponseId: nil,
  reasoning: Optional(
    OpenAI.Components.Schemas.Reasoning(
      effort: nil,
      summary: nil,
      generateSummary: nil
    )
  ),
  status: "completed",
  temperature: Optional(1.0),
  text: OpenAI.Components.Schemas.ResponseProperties.TextPayload(
    format: Optional(
      OpenAI.Components.Schemas.TextResponseFormatConfiguration.ResponseFormatText(
        OpenAI.Components.Schemas.ResponseFormatText(
          _type: OpenAI.Components.Schemas.ResponseFormatText._TypePayload.text
        )
      )
    ),
    toolChoice: OpenAI.Components.Schemas.ResponseProperties.ToolChoicePayload.ToolChoiceOptions(
      OpenAI.Components.Schemas.ToolChoiceOptions.auto
    ),
    tools: [],
    topP: Optional(1.0),
    truncation: Optional("disabled"),
    usage: Optional(
      OpenAI.Components.Schemas.ResponseUsage(
        inputTokens: 18,
        inputTokensDetails: OpenAI.Components.Schemas.ResponseUsage.InputTokensDetailsPayload(
          cachedTokens: 0
        ),
        outputTokens: 32,
        outputTokensDetails: OpenAI.Components.Schemas.ResponseUsage.OutputTokensDetailsPayload(
          reasoningTokens: 0
        ),
        totalTokens: 50
      )
    ),
    user: nil
  )
)

模型生成的内容数组位于响应的 output 属性中。

[!NOTE] output 数组通常包含多个项！ 它可能包含工具调用、推理模型生成的推理 token 数据以及其他项。假设模型的文本输出存在于 output[0].content[0].text 是不安全的。

由于上述说明，为了安全且完整地读取响应，我们需要对消息及其内容进行切换处理，如下所示：

// ...
for output in response.output {
    switch output {
    case .outputMessage(let outputMessage):
        for content in outputMessage.content {
            switch content {
            case .OutputTextContent(let textContent):
                print(textContent.text)
            case .RefusalContent(let refusalContent):
                print(refusalContent.refusal)
            }
        }
    default:
        // Unhandled output items. Handle or throw an error.
    }
}

聊天补全

使用 OpenAIProtocol 上的 func chats(query:) 和 func chatsStream(query:) 方法与 ChatQuery 配合，利用 Chat Completions API 生成文本。获取 ChatResult 或 ChatStreamResult 作为响应。

示例：从简单提示生成文本

let query = ChatQuery(
    messages: [
        .user(.init(content: .string("Who are you?")))
    ],
    model: .gpt4_o
)

let result = try await openAI.chats(query: query)

print(result.choices.first?.message.content ?? "")
// printed to console:
// I'm an AI language model created by OpenAI, designed to assist with a wide range of questions and tasks. How can I help you today?

(lldb) po result
▿ ChatResult
  - id : "chatcmpl-BgWJTzbVczdJDusTqVpnR6AQ2w6Fd"
  - created : 1749473687
  - model : "gpt-4o-2024-08-06"
  - object : "chat.completion"
  ▿ serviceTier : Optional<ServiceTier>
    - some : OpenAI.ServiceTier.defaultTier
  ▿ systemFingerprint : Optional<String>
    - some : "fp_07871e2ad8"
  ▿ choices : 1 element
    ▿ 0 : Choice
      - index : 0
      - logprobs : nil
      ▿ message : Message
        ▿ content : Optional<String>
          - some : "I am an AI language model created by OpenAI, known as ChatGPT. I\'m here to assist with answering questions, providing explanations, and engaging in conversation on a wide range of topics. If you have any questions or need assistance, feel free to ask!"
        - refusal : nil
        - role : "assistant"
        ▿ annotations : Optional<Array<Annotation>>
          - some : 0 elements
        - audio : nil
        - toolCalls : nil
        - _reasoning : nil
        - _reasoningContent : nil
      - finishReason : "stop"
  ▿ usage : Optional<CompletionUsage>
    ▿ some : CompletionUsage
      - completionTokens : 52
      - promptTokens : 11
      - totalTokens : 63
      ▿ promptTokensDetails : Optional<PromptTokensDetails>
        ▿ some : PromptTokensDetails
          - audioTokens : 0
          - cachedTokens : 0
  - citations : nil

函数调用

有关更多详细信息，请参阅 OpenAI 平台指南：函数调用。

let openAI = OpenAI(apiToken: "...")
// Declare functions which model might decide to call.
let functions = [
    ChatQuery.ChatCompletionToolParam.FunctionDefinition(
        name: "get_weather",
        description: "Get current temperature for a given location.",
        parameters: .init(fields: [
            .type(.object),
            .properties([
                "location": .init(fields: [
                    .type(.string),
                    .description("City and country e.g. Bogotá, Colombia")
                ])
            ]),
            .required(["location"]),
            .additionalProperties(.boolean(false))
        ])
    )
]
let query = ChatQuery(
    messages: [
        .user(.init(content: .string("What is the weather like in Paris today?"
    ],
    model: .gpt4_1,
    tools: functions.map { .init(function: $0) }
)
let result = try await openAI.chats(query: query)
print(result.choices[0].message.toolCalls)

{
  "id": "chatcmpl-1234",
  "object": "chat.completion",
  "created": 1686000000,
  "model": "gpt-3.5-turbo-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call-0",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\n  \"location\": \"Boston, MA\"\n}"
            }
          }
        ]
      },
      "finish_reason": "function_call"
    }
  ],
  "usage": { "total_tokens": 100, "completion_tokens": 18, "prompt_tokens": 82 }
}

图像

给定提示词 (prompt) 和/或输入图像，模型将生成新图像。

随着人工智能 (Artificial Intelligence) 的持续发展，Dall-E 这一引人入胜的概念也在不断演进。由专注于人工智能研究的 OpenAI 实验室开发，Dall-E 被归类为一种能够根据人类提供的描述生成图像的 AI 系统。其潜在应用涵盖动画、插画、设计和工程等领域——更不用说中间无数的可能性——不难理解为何这项新技术会引起如此大的兴奋。

创建图像

请求

struct ImagesQuery: Codable {
    /// A text description of the desired image(s). The maximum length is 1000 characters.
    public let prompt: String
    /// The number of images to generate. Must be between 1 and 10.
    public let n: Int?
    /// The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
    public let size: String?
}

响应

struct ImagesResult: Codable, Equatable {
    public struct URLResult: Codable, Equatable {
        public let url: String
    }
    public let created: TimeInterval
    public let data: [URLResult]
}

示例

let query = ImagesQuery(prompt: "White cat with heterochromia sitting on the kitchen table", n: 1, size: "1024x1024")
openAI.images(query: query) { result in
  //Handle result here
}
//or
let result = try await openAI.images(query: query)

(lldb) po result
▿ ImagesResult
  - created : 1671453505.0
  ▿ data : 1 element
    ▿ 0 : URLResult
      - url : "https://oaidalleapiprodscus.blob.core.windows.net/private/org-CWjU5cDIzgCcVjq10pp5yX5Q/user-GoBXgChvLBqLHdBiMJBUbPqF/img-WZVUK2dOD4HKbKwW1NeMJHBd.png?st=2022-12-19T11%3A38%3A25Z&se=2022-12-19T13%3A38%3A25Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2022-12-19T09%3A35%3A16Z&ske=2022-12-20T09%3A35%3A16Z&sks=b&skv=2021-08-06&sig=mh52rmtbQ8CXArv5bMaU6lhgZHFBZz/ePr4y%2BJwLKOc%3D"

生成的图像

创建图像编辑

给定原始图像和提示词，创建编辑或扩展后的图像。

请求

public struct ImageEditsQuery: Codable {
    /// The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.
    public let image: Data
    public let fileName: String
    /// An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.
    public let mask: Data?
    public let maskFileName: String?
    /// A text description of the desired image(s). The maximum length is 1000 characters.
    public let prompt: String
    /// The number of images to generate. Must be between 1 and 10.
    public let n: Int?
    /// The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
    public let size: String?
}

响应

与 ImagesQuery 类似，使用 ImagesResult 响应。

示例

let data = image.pngData()
let query = ImageEditQuery(image: data, fileName: "whitecat.png", prompt: "White cat with heterochromia sitting on the kitchen table with a bowl of food", n: 1, size: "1024x1024")
openAI.imageEdits(query: query) { result in
  //Handle result here
}
//or
let result = try await openAI.imageEdits(query: query)

创建图像变体

创建给定图像的变体。

请求

public struct ImageVariationsQuery: Codable {
    /// The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.
    public let image: Data
    public let fileName: String
    /// The number of images to generate. Must be between 1 and 10.
    public let n: Int?
    /// The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
    public let size: String?
}

响应

与 ImagesQuery 类似，使用 ImagesResult 响应。

示例

let data = image.pngData()
let query = ImageVariationQuery(image: data, fileName: "whitecat.png", n: 1, size: "1024x1024")
openAI.imageVariations(query: query) { result in
  //Handle result here
}
//or
let result = try await openAI.imageVariations(query: query)

查看 图像文档 以获取更多信息。

音频

语音转文本 API 提供两个端点 (endpoints)：转录 (transcriptions) 和翻译 (translations)，基于我们最先进的开源 large-v2 Whisper 模型。它们可用于：

将音频转录为音频所在的任何语言。 将音频翻译并转录为英语。 文件上传目前限制为 25 MB，支持以下输入文件类型：mp3, mp4, mpeg, mpga, m4a, wav, 和 webm。

音频创建语音

此函数向 OpenAI API 发送 AudioSpeechQuery，使用特定的语音和格式从文本创建音频语音。

了解有关语音的更多信息。
了解有关模型的更多信息。

请求：

public struct AudioSpeechQuery: Codable, Equatable {
    //...
    public let model: Model // tts-1 or tts-1-hd  
    public let input: String
    public let voice: AudioSpeechVoice
    public let responseFormat: AudioSpeechResponseFormat
    public let speed: String? // Initializes with Double?
    //...
}

响应：

/// Audio data for one of the following formats :`mp3`, `opus`, `aac`, `flac`, `pcm`
public let audioData: Data?

示例：

let query = AudioSpeechQuery(model: .tts_1, input: "Hello, world!", voice: .alloy, responseFormat: .mp3, speed: 1.0)

openAI.audioCreateSpeech(query: query) { result in
    // Handle response here
}
//or
let result = try await openAI.audioCreateSpeech(query: query)

OpenAI 创建语音 – 文档

音频创建语音流式传输

可以使用 audioCreateSpeechStream 函数进行音频创建语音。Token 将逐个发送。

闭包（Closures）

openAI.audioCreateSpeechStream(query: query) { partialResult in
    switch partialResult {
    case .success(let result):
        print(result.audio)
    case .failure(let error):
        //Handle chunk error here
    }
} completion: { error in
    //Handle streaming error here
}

Combine

openAI
    .audioCreateSpeechStream(query: query)
    .sink { completion in
        //Handle completion result here
    } receiveValue: { result in
        //Handle chunk here
    }.store(in: &cancellables)

结构化并发（Structured Concurrency）

for try await result in openAI.audioCreateSpeechStream(query: query) {
   //Handle result here
}

音频转录

将音频转录为输入语言。

请求

public struct AudioTranscriptionQuery: Codable, Equatable {
    
    public let file: Data
    public let fileName: String
    public let model: Model
    
    public let prompt: String?
    public let temperature: Double?
    public let language: String?
}

响应

public struct AudioTranscriptionResult: Codable, Equatable {
    
    public let text: String
}

示例

let data = Data(contentsOfURL:...)
let query = AudioTranscriptionQuery(file: data, fileName: "audio.m4a", model: .whisper_1)        

openAI.audioTranscriptions(query: query) { result in
    //Handle result here
}
//or
let result = try await openAI.audioTranscriptions(query: query)

音频翻译

将音频翻译为英语。

请求

public struct AudioTranslationQuery: Codable, Equatable {
    
    public let file: Data
    public let fileName: String
    public let model: Model
    
    public let prompt: String?
    public let temperature: Double?
}    

响应

public struct AudioTranslationResult: Codable, Equatable {
    
    public let text: String
}

示例

let data = Data(contentsOfURL:...)
let query = AudioTranslationQuery(file: data, fileName: "audio.m4a", model: .whisper_1)  

openAI.audioTranslations(query: query) { result in
    //Handle result here
}
//or
let result = try await openAI.audioTranslations(query: query)

查看 音频文档 以获取更多信息。

结构化输出（Structured Outputs）

[!NOTE] 本节侧重于 Responses 和 Chat Completions API 中不使用函数调用（Function Calling）的用例。要了解如何使用结构化输出（Structured Outputs）配合函数调用，请查看 函数调用（Function Calling）。

要配置结构化输出（Structured Outputs），您需要定义一个 JSON Schema（JSON 模式）并将其传递给查询。

此 SDK 支持多种定义模式的方法；请选择您喜欢的一种。

let query = CreateModelResponseQuery(
    input: .textInput("Return structured output"),
    model: .gpt4_o,
    text: .jsonSchema(.init(
        name: "research_paper_extraction",
        schema: .jsonSchema(.init(
            .type(.object),
            .properties([
                "title": Schema.buildBlock(
                    .type(.string)
                ),
                "authors": .init(
                    .type(.array),
                    .items(.init(
                        .type(.string)
                    ))
                ),
                "abstract": .init(
                    .type(.string)
                ),
                "keywords": .init(
                    .type(.array),
                    .items(.init(
                        .type(.string))
                    )
                )
            ]),
            .required(["title, authors, abstract, keywords"]),
            .additionalProperties(.boolean(false))
        )),
        description: "desc",
        strict: false
    ))
)

let response = try await openAIClient.responses.createResponse(query: query)
for output in response.output {
    switch output {
    case .outputMessage(let message):
        for content in message.content {
            switch content {
            case .OutputTextContent(let textContent):
                print("json output structured by the schema: ", textContent.text)
            case .RefusalContent(let refusal):
                // Handle refusal
                break
            }
        }
    default:
        // Handle other OutputItems
        break
    }
}

struct MovieInfo: JSONSchemaConvertible {
    
    let title: String
    let director: String
    let release: Date
    let genres: [MovieGenre]
    let cast: [String]
    
    static let example: Self = {
        .init(
            title: "Earth",
            director: "Alexander Dovzhenko",
            release: Calendar.current.date(from: DateComponents(year: 1930, month: 4, day: 1))!,
            genres: [.drama],
            cast: ["Stepan Shkurat", "Semyon Svashenko", "Yuliya Solntseva"]
        )
    }()
}
enum MovieGenre: String, Codable, JSONSchemaEnumConvertible {
    case action, drama, comedy, scifi
    
    var caseNames: [String] { Self.allCases.map { $0.rawValue } }
}
let query = ChatQuery(
    messages: [
        .system(
            .init(content: .textContent("Best Picture winner at the 2011 Oscars"))
        )
    ],
    model: .gpt4_o,
    responseFormat: .jsonSchema(
        .init(
            name: "movie-info",
            description: nil,
            schema: .derivedJsonSchema(MovieInfo.self),
            strict: true
        )
    )
)
let result = try await openAI.chats(query: query)

struct AnyEncodable: Encodable {
    private let _encode: (Encoder) throws -> Void
    public init<T: Encodable>(_ wrapped: T) {
        _encode = wrapped.encode
    }
    func encode(to encoder: Encoder) throws {
        try _encode(encoder)
    }
}
let schema = [
    "type": AnyEncodable("object"),
    "properties": AnyEncodable([
        "title": AnyEncodable([
            "type": "string"
        ]),
        "director": AnyEncodable([
            "type": "string"
        ]),
        "release": AnyEncodable([
            "type": "string"
        ]),
        "genres": AnyEncodable([
            "type": AnyEncodable("array"),
            "items": AnyEncodable([
                "type": AnyEncodable("string"),
                "enum": AnyEncodable(["action", "drama", "comedy", "scifi"])
            ])
        ]),
        "cast": AnyEncodable([
            "type": AnyEncodable("array"),
            "items": AnyEncodable([
                "type": "string"
            ])
        ])
    ]),
    "additionalProperties": AnyEncodable(false)
]
let query = ChatQuery(
    messages: [.system(.init(content: .textContent("Return a structured response.")))],
    model: .gpt4_o,
    responseFormat: .jsonSchema(.init(name: "movie-info", schema: .dynamicJsonSchema(schema)))
)
let result = try await openAI.chats(query: query)

有关更多信息，请查看 结构化输出文档。

工具

远程 MCP（模型上下文协议）

模型上下文协议（MCP）使 AI 模型能够通过标准化的服务器连接安全地连接到外部数据源和工具。此 OpenAI Swift 库支持 MCP 集成，允许您通过远程工具和扩展模型能力。

您可以使用 MCP Swift 库 连接到 MCP 服务器并发现可用工具，然后将这些工具与 OpenAI 的聊天补全功能集成。

MCP 工具集成

请求

// Create an MCP tool for connecting to a remote server
let mcpTool = Tool.mcpTool(
    .init(
        _type: .mcp,
        serverLabel: "GitHub_MCP_Server",
        serverUrl: "https://api.githubcopilot.com/mcp/",
        headers: .init(additionalProperties: [
            "Authorization": "Bearer YOUR_TOKEN_HERE"
        ]),
        allowedTools: .case1(["search_repositories", "get_file_contents"]),
        requireApproval: .case2(.always)
    )
)

let query = ChatQuery(
    messages: [
        .user(.init(content: .string("Search for Swift repositories on GitHub")))
    ],
    model: .gpt4_o,
    tools: [mcpTool]
)

MCP 工具属性

• serverLabel: MCP 服务器的唯一标识符
• serverUrl: MCP 服务器的 URL 端点
• headers: 服务器所需的身份验证头和其他 HTTP 头
• allowedTools: 要启用的特定工具（可选 - 如果未指定，则所有工具均可用）
• requireApproval: 工具调用是否需要用户批准（.always、.never 或条件性）

使用 MCP Swift 库的示例

import MCP
import OpenAI

// Connect to MCP server using the MCP Swift library
let mcpClient = MCP.Client(name: "MyApp", version: "1.0.0")

let transport = HTTPClientTransport(
    endpoint: URL(string: "https://api.githubcopilot.com/mcp/")!,
    configuration: URLSessionConfiguration.default
)

let result = try await mcpClient.connect(transport: transport)
let toolsResponse = try await mcpClient.listTools()

// Create OpenAI MCP tool with discovered tools
let enabledToolNames = toolsResponse.tools.map { $0.name }
let mcpTool = Tool.mcpTool(
    .init(
        _type: .mcp,
        serverLabel: "GitHub_MCP_Server",
        serverUrl: "https://api.githubcopilot.com/mcp/",
        headers: .init(additionalProperties: authHeaders),
        allowedTools: .case1(enabledToolNames),
        requireApproval: .case2(.always)
    )
)

// Use in chat completion
let query = ChatQuery(
    messages: [.user(.init(content: .string("Help me search GitHub repositories")))],
    model: .gpt4_o,
    tools: [mcpTool]
)

let chatResult = try await openAI.chats(query: query)

MCP 工具调用处理

使用 MCP 工具时，模型可能会生成在远程 MCP 服务器上执行的工具调用。请在响应处理中处理特定的 MCP 输出项：

// Handle MCP tool calls in streaming responses
for try await result in openAI.chatsStream(query: query) {
    for choice in result.choices {
        if let outputItem = choice.delta.content {
            switch outputItem {
            case .mcpToolCall(let mcpCall):
                print("MCP tool call: \(mcpCall.name)")
                if let output = mcpCall.output {
                    print("Result: \(output)")
                }
            case .mcpApprovalRequest(let approvalRequest):
                // Handle approval request if requireApproval is enabled
                print("MCP tool requires approval: \(approvalRequest)")
            default:
                // Handle other output types
                break
            }
        }
    }
}

专用模型

Embeddings (嵌入向量)

获取给定输入的向量表示，该表示可被机器学习模型和算法轻松消费。

请求 (Request)

struct EmbeddingsQuery: Codable {
    /// ID of the model to use.
    public let model: Model
    /// Input text to get embeddings for
    public let input: String
}

响应 (Response)

struct EmbeddingsResult: Codable, Equatable {

    public struct Embedding: Codable, Equatable {

        public let object: String
        public let embedding: [Double]
        public let index: Int
    }
    public let data: [Embedding]
    public let usage: Usage
}

示例 (Example)

let query = EmbeddingsQuery(model: .textSearchBabbageDoc, input: "The food was delicious and the waiter...")
openAI.embeddings(query: query) { result in
  //Handle response here
}
//or
let result = try await openAI.embeddings(query: query)

(lldb) po result
▿ EmbeddingsResult
  ▿ data : 1 element
    ▿ 0 : Embedding
      - object : "embedding"
      ▿ embedding : 2048 elements
        - 0 : 0.0010535449
        - 1 : 0.024234328
        - 2 : -0.0084999
        - 3 : 0.008647452
    .......
        - 2044 : 0.017536353
        - 2045 : -0.005897616
        - 2046 : -0.026559394
        - 2047 : -0.016633155
      - index : 0

(lldb)

查阅 Embeddings 文档 以获取更多信息。

Moderations (内容审核)

给定输入文本，输出模型是否将其分类为违反 OpenAI 的内容政策。

请求 (Request)

public struct ModerationsQuery: Codable {
    
    public let input: String
    public let model: Model?
}    

响应 (Response)

public struct ModerationsResult: Codable, Equatable {

    public let id: String
    public let model: Model
    public let results: [CategoryResult]
}

示例 (Example)

let query = ModerationsQuery(input: "I want to kill them.")
openAI.moderations(query: query) { result in
  //Handle result here
}
//or
let result = try await openAI.moderations(query: query)

查阅 Moderations 文档 以获取更多信息。

其他 API

Models (模型)

模型表示为类型别名 typealias Model = String。

public extension Model {
    static let gpt5_1 = "gpt-5.1"
    static let gpt5_1_chat_latest = "gpt-5.1-chat-latest"

    static let gpt5 = "gpt-5"
    static let gpt5_mini = "gpt-5-mini"
    static let gpt5_nano = "gpt-5-nano"
    static let gpt5_chat = "gpt-5-chat"

    static let gpt4_1 = "gpt-4.1"
    static let gpt4_1_mini = "gpt-4.1-mini"
    static let gpt4_1_nano = "gpt-4.1-nano"

    static let gpt4_turbo_preview = "gpt-4-turbo-preview"
    static let gpt4_vision_preview = "gpt-4-vision-preview"
    static let gpt4_0125_preview = "gpt-4-0125-preview"
    static let gpt4_1106_preview = "gpt-4-1106-preview"
    static let gpt4 = "gpt-4"
    static let gpt4_0613 = "gpt-4-0613"
    static let gpt4_0314 = "gpt-4-0314"
    static let gpt4_32k = "gpt-4-32k"
    static let gpt4_32k_0613 = "gpt-4-32k-0613"
    static let gpt4_32k_0314 = "gpt-4-32k-0314"
    
    static let gpt3_5Turbo = "gpt-3.5-turbo"
    static let gpt3_5Turbo_0125 = "gpt-3.5-turbo-0125"
    static let gpt3_5Turbo_1106 = "gpt-3.5-turbo-1106"
    static let gpt3_5Turbo_0613 = "gpt-3.5-turbo-0613"
    static let gpt3_5Turbo_0301 = "gpt-3.5-turbo-0301"
    static let gpt3_5Turbo_16k = "gpt-3.5-turbo-16k"
    static let gpt3_5Turbo_16k_0613 = "gpt-3.5-turbo-16k-0613"
    
    static let textDavinci_003 = "text-davinci-003"
    static let textDavinci_002 = "text-davinci-002"
    static let textCurie = "text-curie-001"
    static let textBabbage = "text-babbage-001"
    static let textAda = "text-ada-001"
    
    static let textDavinci_001 = "text-davinci-001"
    static let codeDavinciEdit_001 = "code-davinci-edit-001"
    
    static let tts_1 = "tts-1"
    static let tts_1_hd = "tts-1-hd"
    
    static let whisper_1 = "whisper-1"

    static let dall_e_2 = "dall-e-2"
    static let dall_e_3 = "dall-e-3"
    
    static let davinci = "davinci"
    static let curie = "curie"
    static let babbage = "babbage"
    static let ada = "ada"
    
    static let textEmbeddingAda = "text-embedding-ada-002"
    static let textSearchAda = "text-search-ada-doc-001"
    static let textSearchBabbageDoc = "text-search-babbage-doc-001"
    static let textSearchBabbageQuery001 = "text-search-babbage-query-001"
    static let textEmbedding3 = "text-embedding-3-small"
    static let textEmbedding3Large = "text-embedding-3-large"
    
    static let textModerationStable = "text-moderation-stable"
    static let textModerationLatest = "text-moderation-latest"
    static let moderation = "text-moderation-007"
}

支持 GPT-4 模型。

例如：要使用 gpt-4-turbo-preview 模型，请将 .gpt4_turbo_preview 作为参数传递给 ChatQuery 的初始化方法。

let query = ChatQuery(model: .gpt4_turbo_preview, messages: [
    .init(role: .system, content: "You are Librarian-GPT. You know everything about the books."),
    .init(role: .user, content: "Who wrote Harry Potter?")
])
let result = try await openAI.chats(query: query)
XCTAssertFalse(result.choices.isEmpty)

如果您需要使用上述未表示的某个模型，也可以传递自定义字符串。

List Models (列出模型)

列出当前可用的模型。

响应 (Response)

public struct ModelsResult: Codable, Equatable {
    
    public let data: [ModelResult]
    public let object: String
}

示例 (Example)

openAI.models() { result in
  //Handle result here
}
//or
let result = try await openAI.models()

Retrieve Model (检索模型)

检索模型实例，提供所有权信息。

请求 (Request)

public struct ModelQuery: Codable, Equatable {
    
    public let model: Model
}    

响应 (Response)

public struct ModelResult: Codable, Equatable {

    public let id: Model
    public let object: String
    public let ownedBy: String
}

示例 (Example)

let query = ModelQuery(model: .gpt4)
openAI.model(query: query) { result in
  //Handle result here
}
//or
let result = try await openAI.model(query: query)

查阅 Models 文档 以获取更多信息。

工具函数

该组件提供了一些便捷的实用函数来处理向量。

public struct Vector {

    /// Returns the similarity between two vectors
    ///
    /// - Parameters:
    ///     - a: The first vector
    ///     - b: The second vector
    public static func cosineSimilarity(a: [Double], b: [Double]) -> Double {
        return dot(a, b) / (mag(a) * mag(b))
    }

    /// Returns the difference between two vectors. Cosine distance is defined as `1 - cosineSimilarity(a, b)`
    ///
    /// - Parameters:
    ///     - a: The first vector
    ///     - b: The second vector
    public func cosineDifference(a: [Double], b: [Double]) -> Double {
        return 1 - Self.cosineSimilarity(a: a, b: b)
    }
}

示例

let vector1 = [0.213123, 0.3214124, 0.421412, 0.3214521251, 0.412412, 0.3214124, 0.1414124, 0.3214521251, 0.213123, 0.3214124, 0.1414124, 0.4214214, 0.213123, 0.3214124, 0.1414124, 0.3214521251, 0.213123, 0.3214124, 0.1414124, 0.3214521251]
let vector2 = [0.213123, 0.3214124, 0.1414124, 0.3214521251, 0.213123, 0.3214124, 0.1414124, 0.3214521251, 0.213123, 0.511515, 0.1414124, 0.3214521251, 0.213123, 0.3214124, 0.1414124, 0.3214521251, 0.213123, 0.3214124, 0.1414124, 0.3213213]
let similarity = Vector.cosineSimilarity(a: vector1, b: vector2)
print(similarity) //0.9510201910206734

在数据分析中，余弦相似度 (Cosine Similarity) 是衡量两个数字序列之间相似程度的指标。

关于余弦相似度 (Cosine Similarity) 的更多信息请点击这里。

助手

查看 助手文档 以获取更多信息。

创建助手

示例：创建助手

let query = AssistantsQuery(model: Model.gpt4_o_mini, name: name, description: description, instructions: instructions, tools: tools, toolResources: toolResources)
openAI.assistantCreate(query: query) { result in
   //Handle response here
}

修改助手

示例：修改助手

let query = AssistantsQuery(model: Model.gpt4_o_mini, name: name, description: description, instructions: instructions, tools: tools, toolResources: toolResources)
openAI.assistantModify(query: query, assistantId: "asst_1234") { result in
    //Handle response here
}

列出助手

示例：列出助手

openAI.assistants() { result in
   //Handle response here
}

线程

查看 线程文档 以获取更多信息。

创建线程

示例：创建线程

let threadsQuery = ThreadsQuery(messages: [Chat(role: message.role, content: message.content)])
openAI.threads(query: threadsQuery) { result in
  //Handle response here
}

创建并运行线程

示例：创建并运行线程

let threadsQuery = ThreadQuery(messages: [Chat(role: message.role, content: message.content)])
let threadRunQuery = ThreadRunQuery(assistantId: "asst_1234"  thread: threadsQuery)
openAI.threadRun(query: threadRunQuery) { result in
  //Handle response here
}

获取线程消息

查看 消息文档 以获取更多信息。

示例：获取线程消息

openAI.threadsMessages(threadId: currentThreadId) { result in
  //Handle response here
}

向线程添加消息

示例：向线程添加消息

let query = MessageQuery(role: message.role.rawValue, content: message.content)
openAI.threadsAddMessage(threadId: currentThreadId, query: query) { result in
  //Handle response here
}

运行

查看 运行文档 以获取更多信息。

创建运行

示例：创建运行

let runsQuery = RunsQuery(assistantId:  currentAssistantId)
openAI.runs(threadId: threadsResult.id, query: runsQuery) { result in
  //Handle response here
}

检索运行

示例：检索运行

openAI.runRetrieve(threadId: currentThreadId, runId: currentRunId) { result in
  //Handle response here
}

检索运行步骤

示例：检索运行步骤

openAI.runRetrieveSteps(threadId: currentThreadId, runId: currentRunId) { result in
  //Handle response here
}

提交运行的工具输出

示例：提交运行的工具输出

let output = RunToolOutputsQuery.ToolOutput(toolCallId: "call123", output: "Success")
let query = RunToolOutputsQuery(toolOutputs: [output])
openAI.runSubmitToolOutputs(threadId: currentThreadId, runId: currentRunId, query: query) { result in
  //Handle response here
}

文件

查看 文件文档 以获取更多信息。

上传文件

示例：上传文件

let query = FilesQuery(purpose: "assistants", file: fileData, fileName: url.lastPathComponent, contentType: "application/pdf")
openAI.files(query: query) { result in
  //Handle response here
}

支持其他提供商

TL;DR 在配置 (Configuration) 中使用 .relaxed 解析选项

此 SDK (软件开发工具包) 对 Gemini、Perplexity 等其他提供商的支持有限。

此 SDK 的首要目标是 OpenAI，主要规则是所有主要类型必须完全兼容 OpenAI 的 API 参考。如果说明某个字段应为可选，那么在此 SDK 的主要查询/结果 (Query/Result) 类型子集中，该字段也必须是可选的。参考中声明的其他信息（如默认值）也是如此。

尽管如此，我们仍希望为其他提供商提供支持。

选项 1：使用 .relaxed 解析选项

.relaxed 解析选项可以处理响应中缺失和额外的键/值。它应该足以满足大多数用例。如果有任何未覆盖的情况，请告知我们。

选项 2：单独指定解析选项

处理响应中缺失的键

某些提供商返回的响应并不完全符合 OpenAI 的方案。例如，Gemini 聊天完成响应省略了 id 字段，而该字段是 OpenAI API 参考 (API Reference) 文档中的必填字段。

在这种情况下，请使用 fillRequiredFieldIfKeyNotFound 解析选项 (Parsing Option)，如下所示：

let configuration = OpenAI.Configuration(token: "", parsingOptions: .fillRequiredFieldIfKeyNotFound)

处理响应中缺失的值

某些字段在 OpenAI 中要求必须存在（非可选），但其他提供商可能会为它们返回 null。

使用 .fillRequiredFieldIfValueNotFound 来处理缺失的值。

如果提供商返回了额外的字段怎么办？

目前我们通过将额外字段添加到主模型集来简单处理此类情况。这是可行的，因为可选字段不会破坏或与 OpenAI 的方案冲突。目前添加了以下额外字段：

ChatResult

• citations Perplexity

ChatResult.Choice.Message

• reasoningContent Grok, DeepSeek
• reasoning OpenRouter

示例项目

你可以在 Demo 文件夹中找到示例 iOS 应用程序。

贡献指南

请确保你的拉取请求 (Pull Requests) 对任何查看者来说都清晰明了。
将 main 设置为目标分支 (Branch)。

在命名 PR 和分支时使用 约定式提交 (Conventional Commits) 原则：

• Feat: ... 用于新功能和新功能实现。
• Bug: ... 用于错误修复。
• Fix: ... 用于小问题修复，如代码中的拼写错误或不准确之处。
• Chore: ... 用于枯燥的工作，如代码润色、重构、废弃修复等。

PR 命名示例：Feat: Add Threads API handling 或 Bug: Fix message result duplication

分支命名示例：feat/add-threads-API-handling 或 bug/fix-message-result-duplication

按照以下格式编写拉取请求的描述：

• 内容 (What)

  ...

• 原因 (Why)

  ...

• 受影响区域 (Affected Areas)

  ...

• 更多信息 (More Info)

  ...

如果需要且可能，我们很感激你在代码中包含测试。❤️

链接

• OpenAI 文档
• OpenAI Playground
• OpenAI 示例
• Dall-E
• 余弦相似度 (Cosine Similarity)

许可证

MIT License

Copyright (c) 2023 MacPaw Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

OpenAI (Swift SDK) 快速上手指南

本指南基于 MacPaw 维护的 Swift 社区版 OpenAI SDK。该库实现了与 OpenAI 公共 API 兼容的接口，支持在 iOS、macOS 等 Apple 平台上调用大模型服务。

环境准备

• 开发语言: Swift 5+
• 开发环境: Xcode (推荐) 或支持 Swift Package Manager 的编辑器
• 系统要求: iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+
• 前置依赖: 无外部依赖，通过 Swift Package Manager 管理

⚠️ 安全提示: API Token 是敏感信息。请勿将其暴露在任何客户端代码（如浏览器、App）中。生产环境请求应通过您的后端服务器中转，从环境变量或密钥管理服务中安全加载 API Key。

安装步骤

推荐使用 Swift Package Manager 将库集成到 Xcode 项目中。

方法一：Xcode 界面操作

1. 打开 Xcode 项目。
2. 点击菜单栏 File > Add Package Dependencies...。
3. 输入仓库地址：https://github.com/MacPaw/OpenAI.git。
4. 选择依赖规则（例如："Up to Next Major Version"）。
5. 点击 Add Package。

方法二：Package.swift 文件配置

如果您使用命令行构建，可在 Package.swift 中添加以下依赖：

dependencies: [
    .package(url: "https://github.com/MacPaw/OpenAI.git", branch: "main")
]

基本使用

初始化 OpenAI 类是调用 API 的入口。您需要先获取 OpenAI 组织的 API Token。

1. 初始化客户端

最简单的初始化方式如下：

let openAI = OpenAI(apiToken: "YOUR_TOKEN_HERE")

如需自定义配置（如组织 ID、超时时间），可使用 Configuration：

let configuration = OpenAI.Configuration(token: "YOUR_TOKEN_HERE", organizationIdentifier: "YOUR_ORGANIZATION_ID_HERE", timeoutInterval: 60.0)
let openAI = OpenAI(configuration: configuration)

2. 发送聊天请求

使用 chats 方法生成文本。以下是完整的异步调用示例：

let query = ChatQuery(
    messages: [
        .user(.init(content: .string("Who are you?")))
    ],
    model: .gpt4_o
)

let result = try await openAI.chats(query: query)

print(result.choices.first?.message.content ?? "")
// 控制台输出：
// I'm an AI language model created by OpenAI, designed to assist with a wide range of questions and tasks. How can you help you today?

3. 取消请求

对于 Swift Concurrency 调用，直接取消任务即可自动取消底层网络请求：

let task = Task {
    do {
        let chatResult = try await openAIClient.chats(query: .init(messages: [], model: "asd"))
    } catch {
        // Handle cancellation or error
    }
}
            
task.cancel()