SwiftOpenAI – OpenAI API용 Swift 네이티브 클라이언트

무엇인가

SwiftOpenAI는 모든 공개 OpenAI 엔드포인트(채팅, 오디오, 이미지, 임베딩, 파인튜닝 등)와 Azure OpenAI, Anthropic, Gemini, Ollama, Groq, xAI, OpenRouter, DeepSeek, AIProxy와 같은 호환 서비스를 래핑하는 Swift 패키지입니다. iOS, macOS, watchOS, Linux 앱이 네이티브 Swift 타입, async/await, 그리고 스트리밍, 함수 호출, 비전, 새로운 Realtime 음성 채팅 API에 대한 내장 지원을 사용하여 API를 호출할 수 있게 합니다.

대상 사용자

• AI 지원 앱을 구축하는 Swift 개발자 – 채팅 어시스턴트, 음성 에이전트, 이미지 생성기, 전사 도구 등.
• HTTP 요청을 수동으로 만들지 않고 타입 안전하고 async 우선인 래퍼가 필요한 팀.
• Apple 플랫폼 또는 Linux에서 실행되는 프로젝트(예: Vapor 백엔드).

주요 기능(README에 설명된 대로)

영역	패키지가 제공하는 것
핵심 API 범위	모든 OpenAI 엔드포인트: 오디오(전사, 번역, 음성 합성, Realtime), 채팅(함수 호출, 구조화된 출력, 비전), 임베딩, 파인튜닝, 배치, 파일, 이미지, 모델, 모더레이션.
Beta/Assistants	Assistant 객체, 스레드, 메시지, 실행, 스트리밍 델타, 벡터 저장소, 에이전트 – OpenAI의 Assistants API를 미러링.
Realtime 음성	WebSocket 기반 저지연 양방향 오디오, VAD, 도구 호출, 사용자 정의 음성 선택, 구성 가능한 오디오 형식.
스트리밍	채팅, 오디오, Assistants 등을 위한 서버 전송 이벤트 스타일 스트리밍을 비동기 시퀀스로 노출.
크로스 플랫폼	iOS 15+, macOS 13+, watchOS 9+, Linux에서 작동(URLSession 버그를 피하기 위해 AsyncHTTPClient 사용).
OpenAI 호환 제공자	OpenAIServiceFactory를 통해 Azure OpenAI, Anthropic, Gemini, Ollama, Groq, xAI, OpenRouter, DeepSeek, AIProxy 및 사용자 정의 URL용 헬퍼 이니셜라이저.
오류 처리	APIError.responseUnsuccessful이 HTTP 상태 코드(예: 429 속도 제한)를 제공.
설치	Swift Package Manager – Xcode 또는 swift package로 추가. README는 Xcode의 기본 상한 버전과 올바르게 설정하는 방법에 대해 경고합니다.
CLI 및 MCP	별도 저장소가 핵심 라이브러리 위에 구축된 명령줄 인터페이스와 "MCP"(아마 macOS 호환 패키지)를 제공.

사용 방법(README의 빠른 예제)

import SwiftOpenAI

let apiKey = "sk‑…"
let service = OpenAIServiceFactory.service(apiKey: apiKey)

let chatParams = ChatCompletionParameters(
    messages: [.init(role: .user, content: .text("Hello, world!"))],
    model: .gpt4o)

do {
    let response = try await service.startChat(parameters: chatParams)
    print(response.choices.first?.message.content?.text ?? "no reply")
} catch APIError.responseUnsuccessful(let desc, let code) {
    print("Error \(code): \(desc)")
}

동일한 패턴이 오디오 전사, 음성 합성, 이미지 생성 등에도 적용되며, 매개변수 구조를 교체하고 service에서 해당 메서드를 호출합니다.

이 라이브러리를 선택해야 할 때

• 이미 Swift로 작업 중이며 OpenAI의 진화하는 API 표면을 따라잡는 단일 종속성을 원할 때.
• 많은 일반 HTTP 래퍼에 없는 스트리밍 또는 Realtime 음성 지원이 필요할 때.
• 앱이 Apple 플랫폼을 대상으로 하며 Combine이나 콜백보다 네이티브 async/await를 선호할 때.
• 코드를 변경하지 않고 클라이언트를 Azure 또는 다른 OpenAI 호환 백엔드로 가리킬 수 있는 유연성도 원할 때.

주의할 점

• README는 베타 Assistants API를 언급합니다 – OpenAI가 사양을 확정함에 따라 이러한 타입은 변경될 수 있습니다.
• Realtime 음성에는 AVFoundation 및 마이크 권한이 필요합니다. Linux에서는 사용할 수 없습니다.
• 패키지 버전이 Xcode의 기본 상한(2.0.0)을 초과할 수 있으므로 패키지를 추가할 때 하한을 수동으로 설정해야 합니다.

---

위의 모든 정보는 저장소의 README에서 직접 가져온 것이며 추가 기능은 가정되지 않았습니다.