SwiftAI

AI 기반 앱을 구축하기 위한 현대적이고 타입 안전한 (type-safe) Swift 라이브러리입니다. SwiftAI는 Apple의 온디바이스 (on-device) 모델부터 OpenAI와 같은 클라우드 기반 서비스에 이르기까지 다양한 AI 모델 전반에서 원활하게 작동하는 통합 API를 제공합니다.

주요 기능 (Features)

• 모델 불가지론 (Model Agnostic): Apple의 온디바이스 (on-device) 모델, OpenAI, MLX 및 커스텀 백엔드(custom backends)를 아우르는 통합 API
• 구조화된 출력 (Structured Output): 컴파일 타임 검증 (compile-time validation)을 포함한 강력한 타입의 구조화된 출력
• 스트리밍 API (Streaming API): 점진적인 콘텐츠 업데이트를 통한 실시간 응답 생성
• 에이전트 도구 루프 (Agent Tool Loop): 도구 사용 (tool use)에 대한 퍼스트 클래스 지원
• 대화 (Conversations): 자동 컨텍스트 관리 (context management) 기능이 포함된 상태 유지형 (stateful) 채팅 세션
• 확장 가능성 (Extensible): 커스텀 모델 및 도구를 위한 플러그인 아키텍처 (plugin architecture)
• Swift 네이티브 (Swift-Native): async/await 및 현대적인 Swift 동시성 (concurrency)을 사용하여 구축됨

빠른 시작 (Quick Start)

import SwiftAI

let llm = SystemLLM()
...

설치 (Installation)

Swift

여기서 무엇이 달라졌나요?

• @Generable은 이 구조체(struct)가 AI에 의해 생성될 수 있음을 SwiftAI에 알려줍니다.
• returning: CityInfo.self는 문자열이 아닌 구조화된 데이터 (structured data)를 원한다는 것을 명시합니다.
• SwiftAI는 AI의 응답을 사용자의 구조체로 자동으로 변환합니다.
• JSON 파싱 (JSON parsing)이 필요하지 않습니다!

💡 핵심 개념: 타입 안전 AI (Type-Safe AI)

SwiftAI는 AI가 코드가 기대하는 정확한 형식으로 데이터를 반환하도록 보장합니다. 만약 AI가 유효한 데이터를 생성할 수 없다면, 손상된 데이터 대신 에러를 받게 됩니다.

3단계: 도구 사용 (Tool Use)

AI가 앱 내의 함수를 호출하여 실시간 정보를 가져올 수 있도록 하세요:

// AI가 사용할 수 있는 도구 생성
struct WeatherTool: Tool {
  let description = "Get current weather for a city"
...

여기서 무엇이 달라졌나요?

• Tool 프로토콜을 통해 AI가 호출할 수 있는 함수를 만들 수 있습니다.
• Arguments 구조체는 도구에 필요한 파라미터 (parameters)를 정의합니다 (이 또한 @Generable입니다).
• AI는 도구를 언제 호출할지 자동으로 결정합니다.
• 도구의 데이터를 포함한 자연어 응답을 돌려받습니다.

💡 핵심 개념: AI 함수 호출 (AI Function Calling)

AI는 도구의 설명을 읽고 이를 호출할지 여부를 자동으로 결정합니다. 사용자가 수동으로 도구를 트리거하는 것이 아니라, AI가 필요할 때 직접 수행합니다.

4단계: 스트리밍 응답 (Streaming Responses)

AI가 콘텐츠를 생성하는 동안 실시간 응답을 받으세요. 채팅 인터페이스에 완벽합니다:

// 텍스트 응답을 실시간으로 스트리밍
let stream = llm.replyStream(to: "Write a short story about a robot")
for try await partialText in stream {
...

구조화된 데이터 스트리밍:

@Generable
struct Story {
  let title: String
...

여기서 무엇이 달라졌나요?

• replyStream()은 완료될 때까지 기다리는 대신 AsyncThrowingStream을 반환합니다.
• 텍스트 필드는 토큰 (tokens)이 생성됨에 따라 점진적으로 스트리밍됩니다.
• 구조화된 필드 (structured fields)는 점진적으로 채워집니다.

💡 핵심 개념: 점진적 생성 (Progressive Generation)

스트리밍은 사용자에게 즉각적인 피드백을 제공하여, AI 상호작용이 더 빠르고 반응성이 좋다고 느끼게 합니다. ChatApp 예제에서 이를 실제로 확인할 수 있습니다.

5단계: 모델 전환 (Model Switching)

각기 다른 AI 모델은 저마다의 강점을 가지고 있습니다. SwiftAI는 모델 전환을 원활하게 만들어 줍니다:

// 가용성에 따라 모델을 선택하세요
let llm: any LLM = {
  let systemLLM = SystemLLM()
...

여기서 새로워진 점은 무엇인가요?

• SystemLLM은 온디바이스 (on-device)에서 실행됩니다 (개인정보 보호, 빠름, 무료)
• OpenaiLLM은 클라우드를 사용합니다 (더 뛰어난 성능, API 키 필요)
• isAvailable은 온디바이스 모델이 준비되었는지 확인합니다
• 동일한 reply() 메서드가 어떤 LLM과도 작동합니다

💡 핵심 개념: 모델 불가지론적 API (Model Agnostic API)

모델을 전환하더라도 코드를 변경할 필요가 없습니다. 이를 통해 앱을 다시 작성하지 않고도 다양한 시나리오(개인정보 보호, 성능, 비용)에 맞춰 최적화할 수 있습니다.

6단계: 대화 (Conversations)

여러 차례 주고받는 대화(multi-turn conversations)를 위해서는 Chat을 사용하여 메시지 간의 문맥(context)을 유지하세요:

// 도구(tools)를 포함한 채팅 생성
let chat = try Chat(with: llm, tools: [weatherTool])

...

여기서 새로워진 점은 무엇인가요?

• Chat은 대화 기록(conversation history)을 자동으로 유지합니다
• send()는 reply()와 유사하지만 이전 메시지들을 기억합니다
• 도구(Tools) 역시 대화 내에서 작동합니다
• AI가 대화 초반의 문맥을 기억합니다

💡 핵심 개념: 상태 유지 vs 상태 비유지 (Stateful vs Stateless)

• reply()는 상태 비유지 (stateless) 방식입니다 - 각 호출이 독립적입니다
• Chat은 상태 유지 (stateful) 방식입니다 - 이전 대화를 바탕으로 구축됩니다

7단계: 고급 제약 조건 (Advanced Constraints)

AI 생성을 가이드하기 위해 검증 규칙과 설명을 추가하세요:

@Generable
struct UserProfile {
  @Guide(description: "문자로 시작하는 유효한 사용자 이름", .pattern("^[a-zA-Z][a-zA-Z0-9_]{2,}$"))
...

여기서 새로워진 점은 무엇인가요?

• @Guide는 필드에 제약 조건과 설명을 추가하여 LLM이 좋은 콘텐츠를 생성하도록 돕습니다
• .pattern()은 LLM에게 정규 표현식(regex)을 따르도록 지시합니다
• .minimum() 및 .maximum()은 숫자를 제한합니다
• .minimumCount() 및 .maximumCount()는 배열 크기를 제어합니다

💡 핵심 개념: 검증된 생성 (Validated Generation)

제약 조건은 AI가 사용자의 비즈니스 규칙을 따르도록 보장합니다.

MLX를 사용한 로컬 AI (실험적 기능)

MLX 백엔드는 Apple의 MLX 프레임워크를 통해 로컬 언어 모델 (Language Models)에 대한 접근을 제공합니다.

설정 (Setup):

// Package.swift의 타겟에 SwiftAIMLX를 추가하세요
targets: [
  .target(
...

사용법 (Usage):

import SwiftAI
import SwiftAIMLX
import MLXLLM
...

참고: 구조화된 출력 생성 (Structured output generation)은 아직 MLX 모델에서 지원되지 않습니다.

🎯 빠른 참조 (Quick Reference)

원하는 기능	사용할 것	예시
간단한 텍스트 응답	reply(to:)	reply(to: "Hello")
...

🔧 지원되는 모델 (Supported Models)

모델	유형	개인정보 보호	기능	비용
SystemLLM	온디바이스 (On-device)	🔒 비공개 (Private)	좋음	🆓 무료 (Free)
...

📖 예제 (Examples)

• ChatApp: 10개 이상의 모델을 사용하는 대화형 채팅 앱
• ReadMitAI: AI 기반 기능을 갖춘 에세이 읽기 앱

🤝 기여하기 (Contributing)

기여를 환영합니다! 기여 가이드라인 (Contributing Guidelines)을 읽어주세요.

개발 환경 설정 (Development Setup)

git clone https://github.com/your-org/SwiftAI.git
cd SwiftAI
swift build
...

📄 라이선스 (License)

SwiftAI는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.

⚠️ 알파 (Alpha) ⚠️

SwiftAI는 알파 (alpha) 🚧 단계입니다. 미흡한 부분이나 파괴적 변경 (breaking changes)이 발생할 수 있습니다.

---

Swift 커뮤니티를 위해 ❤️로 제작되었습니다.