Skip to content

feat(core): mmap-backed GGUF loading for quantized tensors - #4061

Open
lu-zero wants to merge 1 commit into
huggingface:mainfrom
lu-zero:mmap-quantized-gguf
Open

lu-zero wants to merge 1 commit into
huggingface:mainfrom
lu-zero:mmap-quantized-gguf

Conversation

@lu-zero

@lu-zero lu-zero commented Oct 23, 2026

Copy link
Copy Markdown

Toward #3708. QStorage::Cpu is a Box<dyn QuantizedType>, so from_data copies every tensor into anonymous memory at load. For a multi-GB GGUF that doubles the resident cost of the weights.

QStorage::from_mapped borrows an Arc<Mmap> window. TensorInfo::read_mapped, Content::tensor_mapped, and Content::from_mmap plumb that through the GGUF reader, and VarBuilder::from_gguf uses it. The mapping lives as long as any tensor that holds it. Mapped storage is read-only (from_float returns an error). Non-CPU devices still copy, because the upload needs the bytes. from_gguf_buffer is unchanged.

Breaking change: QuantizedType::from_float and from_float_imatrix now return Result<()>.

Measured on an aarch64 Ampere-1a, Linux, schedutil, caches not dropped, loading flint-Q4_K_M.gguf (22.5 GiB, 779 tensors). Mapping every tensor and not reading them left Anonymous at 25 MB. Reading one 240 MB tensor faulted file pages and did not grow Anonymous. from_data(Cow::Borrowed) of 2.07 GiB grew Anonymous by 2.07 GiB. The mapped tensor matched the copy byte for byte, including through QMatMul.

Tests: mapped_tensor_matches_the_copied_one, mapped_window_is_checked, mapped_tensor_matmuls_like_the_copied_one. No smaps assertion in CI.

QStorage::Cpu is a Box<dyn QuantizedType>, so from_data copies every
tensor into anonymous memory. from_mapped borrows an Arc<Mmap> window
instead: the weights stay file-backed and fault in on use.

QuantizedType::from_float and from_float_imatrix now return Result,
because mapped storage is read-only.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant