77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# GGUF Editor
|
|
|
|
GGUF Editor is a terminal user interface for inspecting and editing the metadata
|
|
stored in GGUF model files. It reads the GGUF header, metadata records and tensor
|
|
directory, then lets you change scalar metadata values without loading the model
|
|
tensors into memory.
|
|
|
|
The tool is intended for small, deliberate metadata changes on existing GGUF
|
|
files. When you save, it writes a new file named `modified_<original-name>` next
|
|
to the source file and streams the original tensor data into the output file.
|
|
|
|
## What it does
|
|
|
|
- Opens GGUF v2 and v3 files.
|
|
- Shows metadata keys, value types and display values in a keyboard-driven table.
|
|
- Shows the GGUF version, tensor count and source file size.
|
|
- Edits scalar metadata values such as strings, booleans, integers and floats.
|
|
- Adds new scalar metadata keys.
|
|
- Deletes metadata keys.
|
|
- Preserves tensor data by copying it from the original file instead of reading
|
|
it all into memory.
|
|
|
|
Array metadata values are displayed but cannot currently be edited directly.
|
|
|
|
## Installation
|
|
|
|
You need Go installed.
|
|
|
|
```sh
|
|
go install github.com/andydixon/gguf-editor@latest
|
|
```
|
|
|
|
For local development from this repository:
|
|
|
|
```sh
|
|
go build .
|
|
```
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
gguf-editor path/to/model.gguf
|
|
```
|
|
|
|
If you built it locally:
|
|
|
|
```sh
|
|
./gguf-editor path/to/model.gguf
|
|
```
|
|
|
|
Inside the interface:
|
|
|
|
- `e` or `Enter` edits the selected scalar value.
|
|
- `a` adds a new scalar metadata key.
|
|
- `d` deletes the selected key.
|
|
- `s` saves to `modified_<original-name>`.
|
|
- `q` quits.
|
|
- `Esc` cancels the current edit, add or confirmation dialogue.
|
|
|
|
Saving never overwrites the input file. For example, opening `model.gguf` and
|
|
pressing `s` writes `modified_model.gguf` in the same directory.
|
|
|
|
## Implementation notes
|
|
|
|
The GGUF parser in `gguf.go` reads the magic value, version, tensor count,
|
|
metadata count, metadata key-value pairs and tensor descriptors using
|
|
little-endian binary reads. Tensor payload data is left on disk until save time.
|
|
|
|
The terminal interface in `main.go` is built with Charmbracelet Bubble Tea,
|
|
Bubbles and Lip Gloss. It keeps a dirty flag for unsaved changes and rebuilds the
|
|
metadata table after edits, additions and deletions.
|
|
|
|
## Licence
|
|
|
|
This project is licensed under the GNU General Public License version 3. See
|
|
`LICENSE` for the full licence text.
|