Giới thiệu swift-huggingface: Bộ công cụ Swift hoàn chỉnh cho Hugging Face

Hôm nay, chúng tôi công bố swift-huggingface, một gói Swift mới cung cấp bộ công cụ hoàn chỉnh để tương tác với Hugging Face Hub.

Bạn có thể bắt đầu sử dụng nó ngay hôm nay như một gói độc lập và nó sẽ sớm tích hợp vào swift-transformers để thay thế cho việc triển khai HubApi hiện tại của nó.

Vấn đề

Khi chúng tôi phát hành swift-transformers 1.0 vào đầu năm nay, chúng tôi đã nhận được phản hồi rõ ràng từ cộng đồng:

• Tải xuống chậm và không đáng tin cậy. Các tệp mô hình lớn (thường vài gigabyte) có thể bị lỗi giữa chừng mà không có cách nào để tiếp tục. Các nhà phát triển đã phải tải mô hình xuống thủ công và đóng gói chúng cùng với ứng dụng của họ - đi ngược lại mục đích của việc tải mô hình động.
• Không có bộ nhớ đệm chia sẻ với hệ sinh thái Python. Thư viện transformers của Python lưu trữ mô hình trong ~/.cache/huggingface/hub. Các ứng dụng Swift tải xuống một vị trí khác với cấu trúc khác. Nếu bạn đã tải xuống một mô hình bằng CLI Python, bạn sẽ phải tải xuống lại cho ứng dụng Swift của mình.
• Xác thực gây nhầm lẫn. Mã thông báo nên đến từ đâu? Biến môi trường? Tệp? Keychain? Câu trả lời là, “tùy thuộc vào tình huống”, và việc triển khai hiện tại không làm rõ các tùy chọn.

Giới thiệu swift-huggingface

swift-huggingface là một bản viết lại từ đầu tập trung vào độ tin cậy và trải nghiệm nhà phát triển. Nó cung cấp:

• Phạm vi API Hub hoàn chỉnh — mô hình, bộ dữ liệu, không gian, bộ sưu tập, thảo luận và hơn thế nữa.
• Thao tác tệp mạnh mẽ — theo dõi tiến độ, hỗ trợ tiếp tục và xử lý lỗi đúng cách.
• Bộ nhớ đệm tương thích với Python — chia sẻ mô hình đã tải xuống giữa các bộ công cụ Swift và Python.
• Xác thực linh hoạt — một mẫu TokenProvider giúp làm rõ nguồn thông tin xác thực.
• Hỗ trợ OAuth — hỗ trợ hạng nhất cho các ứng dụng hướng tới người dùng cần xác thực người dùng.
• Hỗ trợ backend lưu trữ Xet (Sắp ra mắt!) — loại bỏ trùng lặp dựa trên phân đoạn để tải xuống nhanh hơn đáng kể.

Hãy xem một vài ví dụ.

---

Xác thực linh hoạt với TokenProvider

Một trong những cải tiến lớn nhất là cách hoạt động của xác thực. Mẫu TokenProvider làm rõ nguồn gốc của thông tin xác thực:

swift import HuggingFace

// Đối với phát triển: tự động phát hiện từ môi trường và các vị trí tiêu chuẩn // Kiểm tra HF_TOKEN, HUGGING_FACE_HUB_TOKEN, ~/.cache/huggingface/token, v.v. let client = HubClient.default

// Cho CI/CD: mã thông báo rõ ràng let client = HubClient(tokenProvider: .static(“hf_xxx”))

// Đối với ứng dụng sản xuất: đọc từ Keychain let client = HubClient(tokenProvider: .keychain(service: “com.myapp”, account: “hf_token”))

Việc tự động phát hiện tuân theo các quy ước tương tự như thư viện huggingface_hub của Python:

1. Biến môi trường HF_TOKEN
2. Biến môi trường HUGGING_FACE_HUB_TOKEN
3. Biến môi trường HF_TOKEN_PATH (đường dẫn đến tệp mã thông báo)
4. Tệp $HF_HOME/token
5. ~/.cache/huggingface/token (vị trí CLI HF tiêu chuẩn)
6. ~/.huggingface/token (vị trí dự phòng)

Điều này có nghĩa là nếu bạn đã đăng nhập bằng hf auth login, swift-huggingface sẽ tự động tìm và sử dụng mã thông báo đó.

OAuth cho Ứng dụng hướng tới Người dùng

Bạn đang xây dựng một ứng dụng nơi người dùng đăng nhập bằng tài khoản Hugging Face của họ? swift-huggingface bao gồm một triển khai OAuth 2.0 hoàn chỉnh:

swift import HuggingFace

// Tạo trình quản lý xác thực 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” )

// Đăng nhập người dùng (hiển thị trình duyệt hệ thống) try await authManager.signIn()

// Sử dụng với Hub client let client = HubClient(tokenProvider: .oauth(manager: authManager))

// Mã thông báo được làm mới tự động khi cần let userInfo = try await client.whoami() print(“Đã đăng nhập với tên: (userInfo.name)”)

Trình quản lý OAuth xử lý lưu trữ mã thông báo trong Keychain, làm mới tự động và đăng xuất an toàn. Không còn quản lý mã thông báo thủ công nữa.

Tải xuống Đáng tin cậy

Tải xuống mô hình lớn giờ đây đã trở nên đơn giản với tính năng theo dõi tiến độ thích hợp và hỗ trợ tiếp tục:

swift // Tải xuống với theo dõi tiến độ let progress = Progress(totalUnitCount: 0)

Task { for await _ in progress.publisher(for: .fractionCompleted).values { print(“Tải xuống: (Int(progress.fractionCompleted * 100))%”) } }

let fileURL = try await client.downloadFile( at: “model.safetensors”, from: “microsoft/phi-2”, to: destinationURL, progress: progress )

Nếu quá trình tải xuống bị gián đoạn, bạn có thể tiếp tục:

swift // Tiếp tục từ nơi bạn đã dừng let fileURL = try await client.resumeDownloadFile( resumeData: savedResumeData, to: destinationURL, progress: progress )

Để tải xuống các kho lưu trữ mô hình hoàn chỉnh, downloadSnapshot xử lý mọi thứ:

swift let modelDir = try await client.downloadSnapshot( of: “mlx-community/Llama-3.2-1B-Instruct-4bit”, to: cacheDirectory, matching: [".safetensors", “.json”], // Chỉ tải xuống những gì bạn cần progressHandler: { progress in print(“Đã tải xuống (progress.completedUnitCount) trên (progress.totalUnitCount) tệp”) } )

Hàm snapshot theo dõi siêu dữ liệu cho từng tệp, vì vậy các lần gọi tiếp theo chỉ tải xuống các tệp đã thay đổi.

Bộ nhớ đệm Chia sẻ với Python

Nhớ lại vấn đề thứ hai chúng tôi đã đề cập? “Không có bộ nhớ đệm chia sẻ với hệ sinh thái Python.” Bây giờ đã được giải quyết.

swift-huggingface triển khai cấu trúc bộ nhớ đệm tương thích với Python cho phép chia sẻ liền mạch giữa các bộ công cụ Swift và Python:

~/.cache/huggingface/hub/ ├── models–deepseek-ai–DeepSeek-V3.2/ │ ├── blobs/ │ │ └── # nội dung tệp thực tế │ ├── refs/ │ │ └── main # chứa hash commit │ └── snapshots/ │ └── <commit_hash>/ │ └── config.json # liên kết tượng trưng → ../../blobs/

Điều này có nghĩa là:

• Tải xuống một lần, sử dụng mọi nơi. Nếu bạn đã tải xuống một mô hình bằng hf CLI hoặc thư viện Python, swift-huggingface sẽ tìm thấy nó tự động.
• Lưu trữ theo địa chỉ nội dung. Các tệp được lưu trữ theo ETag của chúng trong thư mục blobs/. Nếu hai phiên bản chia sẻ cùng một tệp, nó chỉ được lưu trữ một lần.
• Liên kết tượng trưng để tăng hiệu quả. Thư mục snapshot chứa các liên kết tượng trưng đến blobs, giảm thiểu việc sử dụng đĩa trong khi vẫn duy trì cấu trúc tệp sạch sẽ.

Vị trí bộ nhớ đệm tuân theo các quy ước biến môi trường tương tự như Python:

1. Biến môi trường HF_HUB_CACHE
2. Biến môi trường HF_HOME + /hub
3. ~/.cache/huggingface/hub (mặc định)

Bạn cũng có thể sử dụng bộ nhớ đệm trực tiếp:

swift let cache = HubCache.default

// Kiểm tra xem một tệp đã được lưu vào bộ nhớ đệm chưa if let cachedPath = cache.cachedFilePath( repo: “deepseek-ai/DeepSeek-V3.2”, kind: .model, revision: “main”, filename: “config.json” ) { let data = try Data(contentsOf: cachedPath) // Sử dụng tệp đã lưu vào bộ nhớ đệm mà không cần yêu cầu mạng nào }

Để ngăn chặn các tình huống chạy đua khi nhiều quy trình truy cập cùng một bộ nhớ đệm, swift-huggingface sử dụng khóa tệp (flock(2)).

Trước và Sau

Đây là những gì việc tải xuống một snapshot mô hình trông như thế nào với HubApi cũ:

swift // Trước: HubApi trong swift-transformers let hub = HubApi() let repo = Hub.Repo(id: “mlx-community/Llama-3.2-1B-Instruct-4bit”)

// Không theo dõi tiến độ, không tiếp tục, lỗi bị bỏ qua let modelDir = try await hub.snapshot( from: repo, matching: [".safetensors", “.json”] ) { progress in // Đối tượng tiến độ tồn tại nhưng không phải lúc nào cũng chính xác print(progress.fractionCompleted) }

Và đây là cùng một hoạt động với swift-huggingface:

swift // Sau: swift-huggingface let client = HubClient.default

let modelDir = try await client.downloadSnapshot( of: “mlx-community/Llama-3.2-1B-Instruct-4bit”, to: cacheDirectory, matching: [".safetensors", “.json”], progressHandler: { progress in // Tiến độ chính xác cho mỗi tệp print("(progress.completedUnitCount)/(progress.totalUnitCount) tệp") } )

API tương tự, nhưng triển khai hoàn toàn khác nhau — được xây dựng dựa trên các tác vụ tải xuống URLSession với xử lý delegate thích hợp, hỗ trợ dữ liệu tiếp tục và theo dõi siêu dữ liệu.

Ngoài Tải xuống

Nhưng đợi đã, còn nữa! swift-huggingface chứa một bộ công cụ Hub hoàn chỉnh:

swift // Liệt kê các mô hình thịnh hành let models = try await client.listModels( filter: “library:mlx”, sort: “trending”, limit: 10 )

// Lấy chi tiết mô hình let model = try await client.getModel(“mlx-community/Llama-3.2-1B-Instruct-4bit”) print(“Lượt tải xuống: (model.downloads ?? 0)”) print(“Lượt thích: (model.likes ?? 0)”)

// Làm việc với các bộ sưu tập let collections = try await client.listCollections(owner: “huggingface”, sort: “trending”)

// Quản lý các cuộc thảo luận let discussions = try await client.listDiscussions(kind: .model, “username/my-model”)

Và đó chưa phải là tất cả! swift-huggingface có mọi thứ bạn cần để tương tác với Hugging Face Inference Providers, cung cấp cho ứng dụng của bạn quyền truy cập tức thì vào hàng trăm mô hình học máy, được cung cấp bởi các nhà cung cấp suy luận đẳng cấp thế giới:

swift import HuggingFace

// Tạo một client (sử dụng thông tin xác thực được phát hiện tự động từ môi trường) let client = InferenceClient.default

// Tạo ảnh từ lời nhắc văn bản let response = try await client.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 )

// Lưu ảnh được tạo try response.image.write(to: URL(fileURLWithPath: “generated.png”))

Kiểm tra README để biết danh sách đầy đủ mọi thứ được hỗ trợ.

Sắp tới

Chúng tôi đang tích cực làm việc trên hai mặt trận:

Tích hợp với swift-transformers. Chúng tôi có một yêu cầu kéo đang chờ xử lý để thay thế HubApi bằng swift-huggingface. Điều này sẽ mang lại các lượt tải xuống đáng tin cậy cho mọi người sử dụng swift-transformers, mlx-swift-lm, và hệ sinh thái rộng lớn hơn. Nếu bạn duy trì một thư viện hoặc ứng dụng dựa trên Swift và muốn được hỗ trợ áp dụng swift-huggingface, hãy liên hệ với chúng tôi — chúng tôi rất sẵn lòng giúp đỡ.

Tải xuống nhanh hơn với Xet. Chúng tôi đang bổ sung hỗ trợ cho backend lưu trữ Xet, cho phép loại bỏ trùng lặp dựa trên phân đoạn và tải xuống nhanh hơn đáng kể cho các mô hình lớn. Sẽ có thêm thông tin về điều này sớm.

Hãy dùng thử

Thêm swift-huggingface vào dự án của bạn:

swift dependencies: [ .package(url: “https://github.com/huggingface/swift-huggingface.git”, from: “0.4.0”) ]

Chúng tôi rất mong nhận được phản hồi của bạn. Nếu bạn đã gặp khó khăn với việc tải mô hình trong Swift, hãy thử cái này và cho chúng tôi biết kết quả. Các báo cáo kinh nghiệm của bạn sẽ giúp chúng tôi ưu tiên những gì cần cải thiện tiếp theo.

Tài nguyên

• swift-huggingface trên GitHub
• swift-transformers
• mlx-swift-examples
• AnyLanguageModel

---

Cảm ơn cộng đồng swift-transformers đã đưa ra phản hồi định hình dự án này, và cảm ơn tất cả những người đã báo cáo sự cố và chia sẻ kinh nghiệm của họ. Đây là dành cho bạn. ❤️

Link bài viết gốc

• Tags:
• Ai
• 05 December 2025
• Huggingface.co