Overview
gguf_add_tensor is a concrete tool for adding tensor metadata and data references to a GGUF serialization context, provided by the GGML library. Together with gguf_write_to_file, it forms the primary API for serializing tensors into the GGUF binary format.
Description
The gguf_add_tensor function registers a tensor within a GGUF context by recording its name, number of dimensions, dimension sizes (ne[4]), data type, and data offset. The tensor's raw data is not immediately written to disk; instead, the context accumulates tensor information entries that are later flushed when gguf_write_to_file is called. This two-phase approach (register then write) allows the caller to add an arbitrary number of tensors and metadata key-value pairs before committing everything to a single, correctly structured GGUF file.
The companion function gguf_write_to_file takes the fully populated context and writes the complete GGUF file: header, metadata key-value pairs, tensor info array, alignment padding, and concatenated tensor data. An only_meta flag allows writing just the header and metadata without the tensor data payload, useful for creating metadata-only files or split-file workflows.
Code Reference
Source Location
- Repository
ggml-org/ggml- File
src/gguf.cpp
gguf_add_tensor
- Lines
- L1120--1133
void gguf_add_tensor(
struct gguf_context * ctx,
const struct ggml_tensor * tensor
);
gguf_write_to_file
- Lines
- L1332--1345
bool gguf_write_to_file(
const struct gguf_context * ctx,
const char * fname,
bool only_meta
);
Import
Language
C
I/O Contract
gguf_add_tensor
Inputs
| Name |
Type |
Required |
Description
|
ctx |
struct gguf_context * |
Yes |
GGUF context created by gguf_init_empty(); accumulates tensor info and metadata
|
tensor |
const struct ggml_tensor * |
Yes |
A fully initialized ggml_tensor with name, shape (ne[4]), type, and data pointer set
|
Output
| Type |
Description
|
void |
Adds the tensor's info (name, n_dims, ne[4], type, data offset) to the context's internal tensor list. No data is written to disk at this point.
|
gguf_write_to_file
Inputs
| Name |
Type |
Required |
Description
|
ctx |
const struct gguf_context * |
Yes |
GGUF context populated with metadata and tensor info via gguf_add_tensor and related functions
|
fname |
const char * |
Yes |
Output file path for the GGUF file
|
only_meta |
bool |
Yes |
If true, write only the header, metadata, and tensor info without the tensor data payload
|
Output
| Type |
Description
|
bool |
Returns true on success, false on failure (e.g., file I/O error)
|
Dependencies
| Header |
Purpose
|
gguf.h |
Declares gguf_context, gguf_init_empty, gguf_add_tensor, gguf_write_to_file, and related GGUF API functions
|
ggml.h |
Declares ggml_tensor, ggml_nbytes, ggml_type, and other tensor-related types and utilities
|
Usage Examples
Writing a Model to GGUF
#include "gguf.h"
#include "ggml.h"
// Create an empty GGUF context
struct gguf_context * ctx = gguf_init_empty();
// Add metadata key-value pairs
gguf_set_val_str(ctx, "general.architecture", "llama");
gguf_set_val_u32(ctx, "llama.context_length", 4096);
// Add tensors (assumes tensors are already created and filled)
gguf_add_tensor(ctx, weight_tensor); // e.g., "blk.0.attn_q.weight"
gguf_add_tensor(ctx, bias_tensor); // e.g., "blk.0.attn_q.bias"
// Write the complete GGUF file (header + metadata + tensor data)
bool success = gguf_write_to_file(ctx, "model.gguf", false);
// Clean up
gguf_free(ctx);
Writing Metadata Only
// Write only the header and metadata (no tensor data)
bool success = gguf_write_to_file(ctx, "model-meta.gguf", true);
Related Pages
