Implementation:Ggml org Llama cpp Android GgufMetadataReader

Knowledge Sources	Ggml_org_Llama_cpp
Domains	Android, GGUF
Last Updated	2026-02-15 00:00 GMT

Overview

Interface for reading and validating GGUF model file metadata, with factory methods for creating reader instances with configurable options.

Description

Declares three core methods: `ensureSourceFileFormat(File)` and `ensureSourceFileFormat(Context, Uri)` for validating the GGUF magic number from either a file path or Android content URI, and `readStructuredMetadata(InputStream)` for parsing full metadata into a `GgufMetadata` object. The companion object provides `create()` factory methods with configurable `skipKeys` (defaulting to large tokenizer arrays like scores and tokens) and `arraySummariseThreshold` (1000) to control which metadata keys are skipped or summarized during parsing.

Usage

Use this public API interface for GGUF file validation and metadata extraction on Android, enabling the app to verify file format and inspect model properties before attempting to load a model into the inference engine.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: examples/llama.android/lib/src/main/java/com/arm/aichat/gguf/GgufMetadataReader.kt
• Lines: 1-77

Signature

interface GgufMetadataReader {
    suspend fun ensureSourceFileFormat(file: File): Boolean
    suspend fun ensureSourceFileFormat(context: Context, uri: Uri): Boolean
    suspend fun readStructuredMetadata(input: InputStream): GgufMetadata

    companion object {
        fun create(): GgufMetadataReader
        fun create(
            skipKeys: Set<String> = DEFAULT_SKIP_KEYS,
            arraySummariseThreshold: Int = 1_000
        ): GgufMetadataReader
    }
}

class InvalidFileFormatException : IOException()

Import

import android.content.Context
import android.net.Uri
import com.arm.aichat.internal.gguf.GgufMetadataReaderImpl
import java.io.File
import java.io.IOException
import java.io.InputStream

I/O Contract

Inputs

Name	Type	Required	Description
file	File	Yes (overload 1)	Java File pointing to a GGUF file with absolute path
context	Context	Yes (overload 2)	Android context for obtaining ContentProvider
uri	Uri	Yes (overload 2)	Uri to the GGUF file provided by ContentProvider
input	InputStream	Yes (for readStructuredMetadata)	InputStream obtained from a readable GGUF file
skipKeys	Set<String>	No	Keys whose values should be skipped during parsing (default: tokenizer arrays)
arraySummariseThreshold	Int	No	Arrays longer than this are summarized, not materialized (default: 1000)

Outputs

Name	Type	Description
ensureSourceFileFormat return	Boolean	True if the file is a valid GGUF file
readStructuredMetadata return	GgufMetadata	Structured metadata extracted from the GGUF file

Usage Examples

// Create a reader with default configuration
val reader = GgufMetadataReader.create()

// Validate file format
val isValid = reader.ensureSourceFileFormat(file)

// Read structured metadata
val inputStream = file.inputStream()
val metadata = reader.readStructuredMetadata(inputStream)

println("Model: ${metadata.basic.name}")
println("Architecture: ${metadata.architecture?.architecture}")

Related Pages

• Principle:Ggml_org_Llama_cpp_GGUF_Format