Implementation:Ggml_org_Ggml_Gguf_init_empty

Summary

The gguf_init_empty function is the starting point for building a GGUF file programmatically. It allocates and returns an empty gguf_context with no metadata key-value pairs and no tensor information, ready to be populated via the GGUF setter and tensor APIs before being written to disk.

Import

#include "gguf.h"

Dependencies

gguf.h -- public header defining struct gguf_context, the GGUF metadata and tensor management API.
ggml.h -- core GGML header defining struct ggml_tensor and tensor types used when adding tensors to the GGUF context.

Function Signature

struct gguf_context * gguf_init_empty(void);

Source: src/gguf.cpp:L289-291

Parameters

This function takes no parameters.

Return Value

Returns a struct gguf_context * -- an empty GGUF context initialized with:

Version -- set to the current GGUF format version.
Tensor count -- 0 (no tensors registered).
KV count -- 0 (no metadata key-value pairs).
Alignment -- default alignment value for tensor data sections.

The returned context is ready for metadata and tensor addition via the follow-up APIs described below.

Follow-up APIs

After creating an empty context, a typical workflow uses the following functions to populate and write the GGUF file:

gguf_set_val_str

void gguf_set_val_str(
    struct gguf_context * ctx,
    const char          * key,
    const char          * val);

Source: src/gguf.cpp:L969-1039

Sets a string-typed metadata key-value pair on the context. Used for architecture names, tokenizer model identifiers, and other string metadata.

Parameter	Type	Description
ctx	`struct gguf_context *`	The GGUF context to add the metadata entry to.
key	`const char *`	The metadata key string (e.g., `"general.architecture"`).
val	`const char *`	The metadata value string (e.g., `"llama"`).

gguf_add_tensor

void gguf_add_tensor(
    struct gguf_context      * ctx,
    const struct ggml_tensor * tensor);

Source: src/gguf.cpp:L1120-1133

Registers a tensor's metadata (name, shape, type, and data pointer) with the GGUF context. The tensor's data will be included when the context is written to a file.

Parameter	Type	Description
ctx	`struct gguf_context *`	The GGUF context to register the tensor with.
tensor	`const struct ggml_tensor *`	The GGML tensor whose metadata and data will be serialized.

gguf_write_to_file

bool gguf_write_to_file(
    const struct gguf_context * ctx,
    const char                * fname,
    bool                        only_meta);

Source: src/gguf.cpp:L1332-1345

Serializes the GGUF context to a binary file on disk. Writes the header (magic, version, counts), all key-value metadata pairs, tensor info entries, alignment padding, and (optionally) the raw tensor data.

Parameter	Type	Description
ctx	`const struct gguf_context *`	The GGUF context to serialize.
fname	`const char *`	Output file path.
only_meta	`bool`	If `true`, write only the header and metadata without tensor data. Useful for creating metadata-only sidecar files.

Returns true on success, false on failure.

Usage Example

#include "ggml.h"
#include "gguf.h"

// 1. Create an empty GGUF context
struct gguf_context * gguf_ctx = gguf_init_empty();

// 2. Set metadata key-value pairs
gguf_set_val_str(gguf_ctx, "general.architecture", "llama");
gguf_set_val_str(gguf_ctx, "general.name", "My Custom Model");

// 3. Create a GGML context and tensors
struct ggml_init_params params = {
    .mem_size   = 16 * 1024 * 1024,
    .mem_buffer = NULL,
    .no_alloc   = false,
};
struct ggml_context * ctx = ggml_init(params);

struct ggml_tensor * weight = ggml_new_tensor_2d(
    ctx, GGML_TYPE_F32, 4096, 4096);
ggml_set_name(weight, "blk.0.attn_q.weight");

// ... populate weight data ...

// 4. Add tensor to the GGUF context
gguf_add_tensor(gguf_ctx, weight);

// 5. Write the GGUF file to disk
gguf_write_to_file(gguf_ctx, "model.gguf", false);

// 6. Clean up
gguf_free(gguf_ctx);
ggml_free(ctx);

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment