SPB Git

Repository Public

ModelMetadataResolver.swift 11.2 KB 163 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatModelHub/Sources/ModelMetadataResolver.swift3// Description: Turns a Hub repository into downloadable candidates (one MLX model, or one per GGUF file) with sizes, quantization and capability rules.4import Foundation5import LocalChatCore67/// Something the user can download: a descriptor, the exact files that will be fetched, and what is known to be a problem.8public struct ModelCandidate: Sendable, Hashable, Identifiable {9    public var descriptor: ModelDescriptor10    public var files: [HubFile]11    public var projector: HubFile?            // GGUF vision projector (mmproj) found in the repository, downloaded with the model12    public var isGated: Bool13    public var unsupportedReason: String?     // set when the architecture is known not to be implemented by the backend14    public var notes: [String]15    public var id: String { descriptor.id }16    public var downloadBytes: Int64 { files.reduce(0) { $0 + ($1.size ?? 0) } }17}1819public struct ModelMetadataResolver: Sendable {20    /// `config.json` model types the MLX backend implements (LLM, VLM and embedders). Nil = unknown, no verdict is given.21    public var supportedMLXArchitectures: Set<String>?22    /// GGUF `general.architecture` values the llama.cpp backend supports. Nil = unknown.23    public var supportedGGUFArchitectures: Set<String>?2425    public init(supportedMLXArchitectures: Set<String>? = MLXArchitectures.all, supportedGGUFArchitectures: Set<String>? = nil) {26        self.supportedMLXArchitectures = supportedMLXArchitectures; self.supportedGGUFArchitectures = supportedGGUFArchitectures27    }2829    public func candidates(for model: HubModel) -> [ModelCandidate] {30        var out: [ModelCandidate] = []31        if let mlx = mlxCandidate(for: model) { out.append(mlx) }32        out.append(contentsOf: ggufCandidates(for: model))33        return out34    }3536    public func unsupportedMLXReason(architecture: String?) -> String? {37        guard let supported = supportedMLXArchitectures, let architecture else { return nil }38        return supported.contains(architecture) ? nil : "The architecture “\(architecture)” is not implemented in MLX Swift."39    }4041    // MARK: MLX4243    static let weightExtensions: Set<String> = ["safetensors"]44    static let auxiliaryExtensions: Set<String> = ["json", "jinja", "txt", "model", "tiktoken"]45    static let allowedSubfolders: Set<String> = ["1_Pooling", "2_Dense", "2_Normalize"]   // sentence-transformers modules the embedders read4647    /// Files of an MLX (or safetensors embedder) repository that are needed to run it.48    public static func mlxFiles(in model: HubModel) -> [HubFile] {49        model.files.filter { file in50            let parts = file.path.split(separator: "/")51            if parts.count > 2 || (parts.count == 2 && !allowedSubfolders.contains(String(parts[0]))) { return false }52            let name = file.fileName.lowercased(), ext = (name as NSString).pathExtension53            if name.hasPrefix(".") || name == "license.txt" || name == "notice.txt" || name == "requirements.txt" { return false }54            if ["training_args.json", "trainer_state.json", "all_results.json", "eval_results.json", "train_results.json"].contains(name) { return false }55            if weightExtensions.contains(ext) { return !name.contains("adapter") && !name.hasPrefix("optimizer") }56            return auxiliaryExtensions.contains(ext)57        }58    }5960    public func mlxCandidate(for model: HubModel) -> ModelCandidate? {61        let files = Self.mlxFiles(in: model)62        let hasWeights = files.contains { $0.path.hasSuffix(".safetensors") }63        let hasConfig = files.contains { $0.path == "config.json" }64        guard hasWeights, hasConfig else { return nil }65        let isMLX = model.tags.contains("mlx") || model.libraryName == "mlx"66        let hasVisionConfig = model.config?["vision_config"] != nil || ["image-text-to-text", "video-text-to-text"].contains(model.pipelineTag ?? "")67        let caps = ModelNaming.capabilities(name: model.id, pipelineTag: model.pipelineTag, tags: model.tags, chatTemplate: model.chatTemplate,68                                            hasVisionConfig: hasVisionConfig)69        // Plain safetensors repositories are only offered when they are embedders: MLX Swift loads those from the original weights.70        guard isMLX || caps == [.embeddings] else { return nil }7172        let configBits = model.config?["quantization_config"]?["bits"]?.intValue ?? model.config?["quantization"]?["bits"]?.intValue73        let quant = ModelNaming.mlxQuantization(fromName: model.name, configBits: configBits)74        var parameters = model.safetensorsParameters; var provenance: Provenance = parameters == nil ? .unknown : .declared75        if parameters == nil, let p = ModelNaming.parameterCount(fromName: model.name) { parameters = p; provenance = .inferred }76        let size = files.reduce(Int64(0)) { $0 + ($1.size ?? 0) }77        var notes: [String] = []78        if !isMLX { notes.append("Not an MLX conversion: the original safetensors weights are used.") }79        if files.contains(where: { $0.size == nil }) { notes.append("Some file sizes are unknown; the download size is a lower bound.") }80        if model.isGated { notes.append("Gated repository: accept its license on huggingface.co and add your token in Settings.") }81        let context = model.config?["max_position_embeddings"]?.intValue ?? model.config?["text_config"]?["max_position_embeddings"]?.intValue82        let descriptor = ModelDescriptor(83            id: "mlx:\(model.id)", name: model.name, repoID: model.id, revision: model.commit, backend: .mlx, format: .mlx,84            architecture: model.modelType, parameterCount: parameters, parameterProvenance: provenance, quantization: quant?.label,85            bitsPerWeight: quant?.bitsPerWeight, contextLength: context, capabilities: caps, license: model.license,86            sizeBytes: size > 0 ? size : nil)87        return ModelCandidate(descriptor: descriptor, files: files, projector: nil, isGated: model.isGated,88                              unsupportedReason: unsupportedMLXReason(architecture: model.modelType), notes: notes)89    }9091    // MARK: GGUF9293    /// "name-00001-of-00003.gguf" → ("name", 1, 3)94    static func splitPart(_ fileName: String) -> (stem: String, index: Int, total: Int)? {95        guard let regex = try? NSRegularExpression(pattern: "^(.*)-([0-9]{5})-of-([0-9]{5})\\.gguf$", options: [.caseInsensitive]) else { return nil }96        guard let m = regex.firstMatch(in: fileName, range: NSRange(fileName.startIndex..., in: fileName)),97              let s = Range(m.range(at: 1), in: fileName), let i = Range(m.range(at: 2), in: fileName), let t = Range(m.range(at: 3), in: fileName),98              let index = Int(fileName[i]), let total = Int(fileName[t]) else { return nil }99        return (String(fileName[s]), index, total)100    }101102    public func ggufCandidates(for model: HubModel) -> [ModelCandidate] {103        let gguf = model.files.filter { $0.path.lowercased().hasSuffix(".gguf") }104        guard !gguf.isEmpty else { return [] }105        let projectors = gguf.filter { $0.fileName.lowercased().contains("mmproj") }106        let weights = gguf.filter { !$0.fileName.lowercased().contains("mmproj") }107        // prefer a half-precision projector: it is what llama.cpp examples ship by default108        let projector = projectors.first { $0.fileName.lowercased().contains("f16") } ?? projectors.first109110        // group split files; a group is only offered when every part is present111        var groups: [(first: HubFile, parts: [HubFile])] = []; var splits: [String: [(Int, Int, HubFile)]] = [:]; var order: [String] = []112        for file in weights {113            if let part = Self.splitPart(file.fileName) {114                let key = (file.path as NSString).deletingLastPathComponent + "/" + part.stem115                if splits[key] == nil { order.append(key) }116                splits[key, default: []].append((part.index, part.total, file))117            } else { groups.append((file, [file])) }118        }119        for key in order {120            let parts = splits[key]!.sorted { $0.0 < $1.0 }121            if let total = parts.first?.1, parts.count == total, parts.map(\.0) == Array(1...total) { groups.append((parts[0].2, parts.map(\.2))) }122        }123124        let architecture = model.gguf?["architecture"]?.stringValue ?? model.modelType125        let declared = Self.int64(model.gguf?["total"])126        let context = Self.int64(model.gguf?["context_length"]).map(Int.init)127        let template = model.chatTemplate128        var unsupported: String?129        if let supported = supportedGGUFArchitectures, let architecture, !supported.contains(architecture) {130            unsupported = "The architecture “\(architecture)” is not supported by this build of llama.cpp."131        }132        return groups.map { group in133            let name = group.first.fileName134            let quant = ModelNaming.ggufQuantization(fromName: name)135            var parameters = declared; var provenance: Provenance = declared == nil ? .unknown : .declared136            if parameters == nil, let p = ModelNaming.parameterCount(fromName: name) ?? ModelNaming.parameterCount(fromName: model.name) { parameters = p; provenance = .inferred }137            var caps = ModelNaming.capabilities(name: model.id, pipelineTag: model.pipelineTag, tags: model.tags, chatTemplate: template,138                                                hasVisionConfig: false, hasProjector: projector != nil)139            if projector == nil { caps.remove(.vision) }   // a GGUF language model cannot see without its projector file140            var files = group.parts; var notes: [String] = []141            if let projector, caps.contains(.vision) { files.append(projector); notes.append("Includes the vision projector \(projector.fileName).") }142            if group.parts.count > 1 { notes.append("Split in \(group.parts.count) parts.") }143            if model.isGated { notes.append("Gated repository: accept its license on huggingface.co and add your token in Settings.") }144            let size = files.reduce(Int64(0)) { $0 + ($1.size ?? 0) }145            let display = (name as NSString).deletingPathExtension.replacingOccurrences(of: "-00001-of-\(String(format: "%05d", group.parts.count))", with: "")146            let descriptor = ModelDescriptor(147                id: "gguf:\(model.id):\(group.first.path)", name: display, repoID: model.id, revision: model.commit, fileName: group.first.path,148                backend: .gguf, format: .gguf, architecture: architecture, parameterCount: parameters, parameterProvenance: provenance,149                quantization: quant?.label, bitsPerWeight: quant?.bitsPerWeight, contextLength: context, capabilities: caps,150                license: model.license, sizeBytes: size > 0 ? size : nil)151            return ModelCandidate(descriptor: descriptor, files: files, projector: caps.contains(.vision) ? projector : nil,152                                  isGated: model.isGated, unsupportedReason: unsupported, notes: notes)153        }.sorted { ($0.descriptor.sizeBytes ?? 0) < ($1.descriptor.sizeBytes ?? 0) }154    }155156    /// The Hub sends GGUF numbers sometimes as numbers, sometimes as strings.157    static func int64(_ value: JSONValue?) -> Int64? {158        if let n = value?.numberValue { return Int64(n) }159        if let s = value?.stringValue { return Int64(s) }160        return nil161    }162}163
Files main
Menu

Theme