Repository Public
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