SPB Git

Repository Public

GGUFHeader.swift 7.6 KB 148 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatModelHub/Sources/GGUFHeader.swift3// Description: Reads the metadata section of a GGUF file (v2/v3) with a buffered binary reader; large arrays are skipped, not loaded.4import Foundation5import LocalChatCore67public struct GGUFHeader: Sendable, Hashable {8    public var version: UInt329    public var tensorCount: UInt6410    public var metadata: [String: JSONValue]      // scalars and strings; arrays are recorded as their element count under "<key>#count"1112    public var architecture: String? { metadata["general.architecture"]?.stringValue }13    public var name: String? { metadata["general.name"]?.stringValue ?? metadata["general.basename"]?.stringValue }14    public var sizeLabel: String? { metadata["general.size_label"]?.stringValue }15    public var license: String? { metadata["general.license"]?.stringValue }16    public var fileType: Int? { metadata["general.file_type"]?.intValue }17    public var declaredParameterCount: Int64? { metadata["general.parameter_count"]?.numberValue.map { Int64($0) } }18    public var contextLength: Int? { architecture.flatMap { metadata["\($0).context_length"]?.intValue } }19    public var embeddingLength: Int? { architecture.flatMap { metadata["\($0).embedding_length"]?.intValue } }20    public var chatTemplate: String? { metadata["tokenizer.chat_template"]?.stringValue }21    public var hasChatTemplate: Bool { chatTemplate?.isEmpty == false }22    public var isProjector: Bool { architecture == "clip" || metadata["general.type"]?.stringValue == "mmproj" || metadata["general.type"]?.stringValue == "projector" }23    public var poolingType: Int? { architecture.flatMap { metadata["\($0).pooling_type"]?.intValue } }24}2526public enum GGUFError: LocalizedError, Sendable, Equatable {27    case notGGUF, unsupportedVersion(UInt32), truncated, malformed(String)28    public var errorDescription: String? {29        switch self {30        case .notGGUF: "This is not a GGUF file."31        case .unsupportedVersion(let v): "GGUF version \(v) is not supported (versions 2 and 3 are)."32        case .truncated: "The GGUF file is truncated."33        case .malformed(let m): "The GGUF header is malformed: \(m)"34        }35    }36}3738public enum GGUFReader {39    /// Strings longer than this are skipped (only chat templates and names matter here).40    static let maxStringBytes = 1 << 2041    /// A sane header never carries more keys than this.42    static let maxKeys: UInt64 = 100_0004344    public static func readHeader(at url: URL) throws -> GGUFHeader {45        guard let handle = try? FileHandle(forReadingFrom: url) else { throw GGUFError.malformed("the file cannot be opened") }46        defer { try? handle.close() }47        var r = Buffered(handle: handle)48        guard try r.u32() == 0x4655_4747 else { throw GGUFError.notGGUF }   // "GGUF" little-endian49        let version = try r.u32()50        guard version == 2 || version == 3 else { throw GGUFError.unsupportedVersion(version) }51        let tensors = try r.u64(), count = try r.u64()52        guard count <= maxKeys else { throw GGUFError.malformed("\(count) metadata keys") }53        var metadata: [String: JSONValue] = [:]54        for _ in 0..<count {55            guard let key = try r.string(limit: 4096) else { throw GGUFError.malformed("oversized key") }56            let type = try r.u32()57            if type == 9 {58                let elementType = try r.u32(), n = try r.u64()59                try skipArray(&r, type: elementType, count: n)60                metadata[key + "#count"] = .number(Double(n))61            } else if let value = try scalar(&r, type: type) { metadata[key] = value }62        }63        return GGUFHeader(version: version, tensorCount: tensors, metadata: metadata)64    }6566    private static func scalar(_ r: inout Buffered, type: UInt32) throws -> JSONValue? {67        switch type {68        case 0: return .number(Double(try r.u8()))69        case 1: return .number(Double(Int8(bitPattern: try r.u8())))70        case 2: return .number(Double(try r.u16()))71        case 3: return .number(Double(Int16(bitPattern: try r.u16())))72        case 4: return .number(Double(try r.u32()))73        case 5: return .number(Double(Int32(bitPattern: try r.u32())))74        case 6: return .number(Double(Float(bitPattern: try r.u32())))75        case 7: return .bool(try r.u8() != 0)76        case 8: return try r.string(limit: maxStringBytes).map(JSONValue.string)77        case 10: return .number(Double(try r.u64()))78        case 11: return .number(Double(Int64(bitPattern: try r.u64())))79        case 12: return .number(Double(bitPattern: try r.u64()))80        default: throw GGUFError.malformed("unknown value type \(type)")81        }82    }8384    private static func skipArray(_ r: inout Buffered, type: UInt32, count: UInt64) throws {85        let fixed: [UInt32: UInt64] = [0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8]86        if let width = fixed[type] { try r.skip(count &* width); return }87        switch type {88        case 8: for _ in 0..<count { try r.skip(try r.u64()) }89        case 9:90            for _ in 0..<count { let t = try r.u32(), n = try r.u64(); try skipArray(&r, type: t, count: n) }91        default: throw GGUFError.malformed("unknown array type \(type)")92        }93    }9495    /// Sequential reader over a FileHandle with a 1 MB window, so a vocabulary of 250 000 strings costs a few hundred reads, not one per token.96    struct Buffered {97        let handle: FileHandle98        var buffer = Data()99        var offset = 0100        init(handle: FileHandle) { self.handle = handle }101102        private mutating func fill(_ needed: Int) throws {103            if buffer.count - offset >= needed { return }104            var rest = Data(buffer[(buffer.startIndex + offset)...])105            while rest.count < needed {106                guard let chunk = try handle.read(upToCount: max(1 << 20, needed - rest.count)), !chunk.isEmpty else { throw GGUFError.truncated }107                rest.append(chunk)108            }109            buffer = rest; offset = 0110        }111        private mutating func integer<T: FixedWidthInteger>(_: T.Type) throws -> T {112            let size = MemoryLayout<T>.size113            try fill(size)114            var value: T = 0115            let start = buffer.startIndex + offset116            withUnsafeMutableBytes(of: &value) { $0.copyBytes(from: buffer[start..<start + size]) }117            offset += size118            return T(littleEndian: value)119        }120        mutating func u8() throws -> UInt8 { try integer(UInt8.self) }121        mutating func u16() throws -> UInt16 { try integer(UInt16.self) }122        mutating func u32() throws -> UInt32 { try integer(UInt32.self) }123        mutating func u64() throws -> UInt64 { try integer(UInt64.self) }124125        mutating func skip(_ count: UInt64) throws {126            let available = UInt64(buffer.count - offset)127            if count <= available { offset += Int(count); return }128            let beyond = count - available129            let position = try handle.offset()130            let end = try handle.seekToEnd()131            guard position &+ beyond <= end else { throw GGUFError.truncated }132            try handle.seek(toOffset: position + beyond)133            buffer = Data(); offset = 0134        }135136        /// Returns nil (after skipping the bytes) when the string is longer than `limit`.137        mutating func string(limit: Int) throws -> String? {138            let length = try u64()139            guard length <= UInt64(limit) else { try skip(length); return nil }140            let n = Int(length)141            try fill(n)142            let start = buffer.startIndex + offset143            offset += n144            return String(decoding: buffer[start..<start + n], as: UTF8.self)145        }146    }147}148
Files main
Menu

Theme