swift-huggingface: cliente Swift completo para Hugging Face | Keryc
Hugging Face anuncia swift-huggingface, un paquete Swift que ofrece un cliente completo para el Hub. ¿Qué significa eso para ti como desarrollador de iOS, macOS o apps Swift? Descargas fiables, cache compatible con Python, autenticación clara y una API diseñada para la experiencia real de producción.
Qué trae swift-huggingface
swift-huggingface es una reescritura enfocada en confiabilidad y experiencia del desarrollador. No es solo una envoltura: cubre todo el Hub API (modelos, datasets, spaces, colecciones, discusiones), operaciones de archivo robustas y compatibilidad con la estructura de cache que usa Python.
¿Por qué importa? Porque ahora una app Swift puede aprovechar modelos sin que el usuario tenga que descargar manualmente gigabytes o lidiar con descargas que fallan sin forma de reanudar.
Entre las características técnicas clave:
Cobertura completa del Hub API: listado, detalles, colecciones y discusiones.
Descargas robustas: seguimiento de progreso, soporte para reanudar y mejor manejo de errores.
Cache compatible con Python: comparte ~/.cache/huggingface/hub entre clientes Swift y Python.
Autenticación flexible: patrón TokenProvider claro y consistente.
OAuth 2.0 listo para apps con login de usuario.
Soporte Xet (próximamente): deduplicación por chunks para descargas mucho más rápidas.
Autenticación: TokenProvider y OAuth explicado
Uno de los dolores de cabeza más comunes es: ¿de dónde vienen los tokens? swift-huggingface adopta el patrón TokenProvider para que quede explícito y controlable.
Ejemplos simples:
import HuggingFace
// Auto-detección para desarrollo
let client = HubClient.default
// Token explícito para CI
let clientCI = HubClient(tokenProvider: .static("hf_xxx"))
// Leer token desde Keychain para producción
let clientProd = HubClient(tokenProvider: .keychain(service: "com.myapp", account: "hf_token"))
La auto-detección sigue las mismas convenciones que huggingface_hub en Python: HF_TOKEN, HUGGING_FACE_HUB_TOKEN, rutas de archivos estándar y ubicaciones del CLI. Si ya te autenticó hf auth login, el cliente Swift lo detectará.
¿Necesitas login con cuenta de usuario? Hay un manager OAuth completo:
import HuggingFace
let authManager = try HuggingFaceAuthenticationManager(
clientID: "your_client_id",
redirectURL: URL(string: "yourapp://oauth/callback")!,
scope: [.openid, .profile, .email],
keychainService: "com.yourapp.huggingface",
keychainAccount: "user_token"
)
try await authManager.signIn()
let client = HubClient(tokenProvider: .oauth(manager: authManager))
let userInfo = try await client.whoami()
print("Signed in as: \(userInfo.name)")
El manager maneja almacenamiento en Keychain, refresh automático y cierre de sesión seguro. Adiós a la gestión manual de tokens.
Descargas, reanudar y cache compatible con Python
Antes, las descargas grandes eran frágiles: fallaban a medias y no había reanudar. swift-huggingface usa URLSession con tareas de download, delegate, soporte de resumeData y seguimiento fino de metadata.
Ejemplo de descarga con progreso:
let progress = Progress(totalUnitCount: 0)
Task {
for await _ in progress.publisher(for: \.\,fractionCompleted).values {
print("Download: \(Int(progress.fractionCompleted * 100))%")
}
}
let fileURL = try await client.downloadFile(
at: "model.safetensors",
from: "microsoft/phi-2",
to: destinationURL,
progress: progress
)
Y si se interrumpe:
let fileURL = try await client.resumeDownloadFile(
resumeData: savedResumeData,
to: destinationURL,
progress: progress
)
Para repositorios completos existe downloadSnapshot, que compara metadatos y solo descarga lo que cambió:
let modelDir = try await client.downloadSnapshot(
of: "mlx-community/Llama-3.2-1B-Instruct-4bit",
to: cacheDirectory,
matching: ["*.safetensors", "*.json"],
progressHandler: { progress in
print("Downloaded \(progress.completedUnitCount) of \(progress.totalUnitCount) files")
}
)
La estructura de cache es compatible con Python. En disco verás algo como:
Almacenamiento por contenido (ETag) evita duplicados.
Las snapshots usan symlinks para ahorrar espacio.
Para evitar condiciones de carrera cuando varios procesos acceden al mismo cache, el cliente usa bloqueo de archivos (flock(2)). Eso es crucial en entornos donde un pipeline CI y una app local puedan intentar escribir el mismo archivo.
API del Hub y acceso a proveedores de inferencia
El cliente expone todas las operaciones habituales: listar modelos, obtener detalles, manejar colecciones y discusiones.
Ejemplo rápido de uso de la API y del cliente de inferencia:
let client = HubClient.default
let models = try await client.listModels(filter: "library:mlx", sort: "trending", limit: 10)
let model = try await client.getModel("mlx-community/Llama-3.2-1B-Instruct-4bit")
print("Downloads: \(model.downloads ?? 0)")
let infClient = InferenceClient.default
let response = try await infClient.textToImage(
model: "black-forest-labs/FLUX.1-schnell",
prompt: "A serene Japanese garden with cherry blossoms",
provider: .hfInference,
width: 1024,
height: 1024,
numImages: 1,
guidanceScale: 7.5,
numInferenceSteps: 50,
seed: 42
)
try response.image.write(to: URL(fileURLWithPath: "generated.png"))
Integración y cómo empezar hoy
Si ya usas swift-transformers, hay una PR en progreso para reemplazar HubApi por swift-huggingface, lo que llevará descargas fiables a todo el ecosistema Swift.
También están trabajando en soporte para Xet, que promete descargas mucho más rápidas mediante deduplicación por chunks. Si trabajas con modelos grandes, eso puede cambiar la experiencia de principio a fin.
¿Te preocupa migrar o integrar esto en una app existente? Los mantenedores ofrecen ayuda y están abiertos a feedback. Si has tenido problemas con descargas en Swift, tu reporte será útil para priorizar mejoras.
swift-huggingface no es solo una lista de funciones: es una mejora práctica en la forma en que las apps Swift consumen modelos y servicios de Hugging Face. Si trabajas con ML en Apple platforms, vale la pena probarlo y dar feedback.
