gguf

Documentation

Overview

Package gguf provides a shared GGUF v3 writer for serializing model files. It handles binary format concerns (header, metadata KV pairs, tensor info, aligned tensor data) but has zero domain knowledge about model architectures, tensor naming, or tokenizer embedding.

Index

• Constants
• type Writer
  • func NewWriter() *Writer
  • func (w *Writer) AddMetadataBool(key string, value bool)
  • func (w *Writer) AddMetadataFloat32(key string, value float32)
  • func (w *Writer) AddMetadataInt32(key string, value int32)
  • func (w *Writer) AddMetadataInt64(key string, value int64)
  • func (w *Writer) AddMetadataString(key, value string)
  • func (w *Writer) AddMetadataStringArray(key string, values []string)
  • func (w *Writer) AddMetadataUint32(key string, value uint32)
  • func (w *Writer) AddMetadataUint32Array(key string, values []uint32)
  • func (w *Writer) AddMetadataUint64(key string, value uint64)
  • func (w *Writer) AddTensor(name string, typ int, shape []int, data []byte)
  • func (w *Writer) AddTensorF32(name string, shape []int, data []float32)
  • func (w *Writer) Write(out io.Writer) error

Constants

const (
	Magic     = 0x46554747 // "GGUF" in little-endian
	Version   = 3
	Alignment = 32 // tensor data alignment in bytes
)

GGUF v3 format constants.

const (
	TypeF32  = 0
	TypeF16  = 1
	TypeQ4_0 = 2
	TypeQ4_1 = 3
	TypeQ5_0 = 6
	TypeQ5_1 = 7
	TypeQ8_0 = 8
	TypeQ4_K = 12
	TypeQ5_K = 13
	TypeQ6_K = 14
	TypeBF16 = 30
)

GGML tensor types.

const (
	MetaTypeUint8   = 0
	MetaTypeInt8    = 1
	MetaTypeUint16  = 2
	MetaTypeInt16   = 3
	MetaTypeUint32  = 4
	MetaTypeInt32   = 5
	MetaTypeFloat32 = 6
	MetaTypeBool    = 7
	MetaTypeString  = 8
	MetaTypeArray   = 9
	MetaTypeUint64  = 10
	MetaTypeInt64   = 11
	MetaTypeFloat64 = 12
)

GGUF metadata value types.

Types

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer buffers GGUF v3 metadata and tensor data, then writes the complete file in a single Write call.

func NewWriter

func NewWriter() *Writer

NewWriter returns a new GGUF v3 writer.

func (*Writer) AddMetadataBool

func (w *Writer) AddMetadataBool(key string, value bool)

AddMetadataBool adds a bool metadata key-value pair.

func (*Writer) AddMetadataFloat32

func (w *Writer) AddMetadataFloat32(key string, value float32)

AddMetadataFloat32 adds a float32 metadata key-value pair.

func (*Writer) AddMetadataInt32

func (w *Writer) AddMetadataInt32(key string, value int32)

AddMetadataInt32 adds an int32 metadata key-value pair.

func (*Writer) AddMetadataInt64

func (w *Writer) AddMetadataInt64(key string, value int64)

AddMetadataInt64 adds an int64 metadata key-value pair.

func (*Writer) AddMetadataString

func (w *Writer) AddMetadataString(key, value string)

AddMetadataString adds a string metadata key-value pair.

func (*Writer) AddMetadataStringArray

func (w *Writer) AddMetadataStringArray(key string, values []string)

AddMetadataStringArray adds a string array metadata key-value pair.

func (*Writer) AddMetadataUint32

func (w *Writer) AddMetadataUint32(key string, value uint32)

AddMetadataUint32 adds a uint32 metadata key-value pair.

func (*Writer) AddMetadataUint32Array

func (w *Writer) AddMetadataUint32Array(key string, values []uint32)

AddMetadataUint32Array adds a uint32 array metadata key-value pair.

func (*Writer) AddMetadataUint64

func (w *Writer) AddMetadataUint64(key string, value uint64)

AddMetadataUint64 adds a uint64 metadata key-value pair.

func (*Writer) AddTensor

func (w *Writer) AddTensor(name string, typ int, shape []int, data []byte)

AddTensor registers a tensor with raw byte data. shape uses the caller's convention (outermost dimension first); the writer reverses dimensions when serializing per the GGUF spec.

func (*Writer) AddTensorF32

func (w *Writer) AddTensorF32(name string, shape []int, data []float32)

AddTensorF32 is a convenience method that registers a float32 tensor, converting the float32 slice to raw bytes.

func (*Writer) Write

func (w *Writer) Write(out io.Writer) error

Write outputs the complete GGUF v3 file to out.