swift-huggingface 릴리즈 노트 / 새로운 기능

Hugging Face는 swift-huggingface의 출시를 발표했습니다. 이는 Hugging Face Hub용 완전한 클라이언트를 제공하는 새로운 Swift 패키지입니다. 이 라이브러리는 Swift 생태계에서 중요한 신뢰성과 개발자 경험 격차를 해결하며, 특히 대용량 모델 다운로드, Python과의 캐시 동기화, 인증 유연성과 관련됩니다.

신뢰할 수 있는 모델 다운로드 및 재개 지원

swift-huggingface는 URLSession 다운로드 작업을 기반으로 한 강력한 시스템으로 이전의 신뢰할 수 없는 다운로드 메커니즘을 대체합니다. 이는 명시적인 진행 상황 추적과 중단된 다운로드를 재개할 수 있는 기능을 제공하며, 이는 머신러닝에서 흔히 볼 수 있는 multi-gigabyte 파일에 필수적입니다.

주요 다운로드 기능은 다음과 같습니다:

  • 재개 지원: resumeDownloadFile 메서드는 저장된 resume 데이터를 사용하여 개발자가 중단한 지점에서 다운로드를 이어갈 수 있게 합니다.
  • 스냅샷 다운로드: downloadSnapshot 함수는 전체 모델 저장소를 관리하며, 메타데이터를 추적하여 후속 호출에서 변경된 파일만 다운로드하도록 보장합니다.
  • 필터링된 다운로드: 사용자는 패턴(예: *.safetensors, *.json)를 지정하여 저장소에서 필요한 파일만 다운로드할 수 있습니다.

Python 호환 캐시 구조

중복 다운로드를 제거하기 위해, swift-huggingface는 Python huggingface_hub 라이브러리와 호환되는 캐시 구조를 구현합니다. 이를 통해 Swift 애플리케이션은 Python CLI 또는 transformers 라이브러리를 통해 이미 다운로드된 모델을 공유할 수 있습니다.

이 캐시는 파일이 ETag별로 blobs/ 디렉터리에 저장되는 콘텐츠 주소 저장소를 사용합니다. 스냅샷 디렉터리는 이러한 블롭에 대한 심볼릭 링크를 사용하여 디스크 사용량을 최소화합니다. 라이브러리는 캐시 위치에 대한 표준 환경 변수 관례를 따르며, HF_HUB_CACHE, HF_HOME를 확인하고 기본값은 ~/.cache/huggingface/hub입니다. 다중 프로세스 접근 시 경합 조건을 방지하기 위해 라이브러리는 flock(2) 파일 잠금을 사용합니다.

유연한 인증 및 OAuth 2.0

인증은 TokenProvider 패턴을 통해 관리되어 자격 증명 출처를 명시적으로 만듭니다. 이 라이브러리는 여러 인증 흐름을 지원합니다:

  • 자동 감지: 환경 변수(HF_TOKEN, HUGGING_FACE_HUB_TOKEN), 토큰 파일, 또는 표준 HF CLI 위치에서 토큰을 자동으로 찾습니다.
  • 정적 토큰: CI/CD 환경에서 명시적으로 제공되는 토큰
  • Keychain 통합: 시스템 Keychain을 통해 프로덕션 앱에 대한 안전한 저장소
  • OAuth 2.0: 사용자 facing 애플리케이션을 위한 완전한 구현으로, 시스템 브라우저 로그인 처리, Keychain에 토큰 저장, 자동 토큰 갱신을 수행하는 HuggingFaceAuthenticationManager를 포함합니다.

포괄적인 Hub 및 Inference API 지원

파일 작업을 넘어, swift-huggingface는 Hugging Face Hub 및 Inference Provider와 상호작용하는 완전한 클라이언트를 제공합니다:

  • Hub API: 모델, 데이터셋, 스페이스, 컬렉션, 토론의 나열 및 관리를 지원합니다.
  • Inference Client: InferenceClient는 Hugging Face Inference Provider를 통해 수백 개의 모델에 액세스할 수 있게 하며, 텍스트 프롬프트로부터 이미지를 생성하는 textToImage와 같은 기능을 포함합니다.

미래 로드맵 및 통합

swift-transformers와의 통합은 기존 HubApi 구현을 대체하기 위한 풀 리퀘스트를 통해 현재 진행 중입니다. 이 업데이트는 mlx-swift-lm 및 기타 생태계 라이브러리 사용자에게 swift-huggingface의 신뢰성을 확장할 것입니다. 또한, Hugging Face는 Xet 저장소 백엔드 지원을 개발 중이며, 이는 청크 기반 중복 제거를 도입하여 대용량 모델의 다운로드 속도를 더욱 높일 것입니다.

Sources