Module model_files 

SafeTensors and GGUF model files, read as a table of their tensors.

Only the header is read: a 70 GB checkpoint opens as fast as a 7 MB one, because the tensor data is never touched. Both parsers are hand-written over a reader that knows where the header must end, and every length the file states is checked against that before anything is allocated or skipped, so a corrupt or hostile header is an error rather than a multi-gigabyte allocation or a panic.

The rows are a small eager DataFrame (one per tensor) made lazy, as ORC and Excel are. What is not a row — the file’s metadata and the totals — is a ModelSummary, carried to the dataset for the Info panel’s Model tab.

Structs

Header

One file’s header.

ModelSummary

What a model’s header says beyond its tensors, and their totals.

Remote

How a remote model’s files are reached: a source for a URL, and the URL of a file named beside another. open and stop are called from the threads that read shards at once (SHARD_READS).

Tensor

One tensor, as a header describes it.

TypeShare

One dtype’s share of a model.

Enums

MetaValue

One metadata value, as the Model tab shows it.

ModelKind

Which of the two formats a model file is.

RangeError

Why a ranged read stopped.

Constants

FIRST_GGUF_RANGE

The first range a GGUF header is read in. Each read after it is twice the one before, up to [MAX_RANGE], so a header of a few KB costs one request and one with a vocabulary (5 to 10 MB) four or five. Larger, fewer requests fetch up to twice the header; see a_vocabulary_sized_gguf_header_takes_a_few_ranges.

FIRST_SAFETENSORS_RANGE

The first read of a SafeTensors file: its header’s length and, for most files, the whole of its JSON in the same request. A checkpoint shard’s header is a few KB to some tens of KB; one longer than this takes a second request, for the rest of it.

MAX_SAFETENSORS_HEADER

The largest SafeTensors header read: the limit the reference implementation sets.

SHARD_READS

Shards whose headers are read at once. A model hub’s checkpoint is up to some hundreds of shards, each a request or two: one at a time, their round trips add up to minutes. A few at once is most of the gain without a burst at the server.

Traits

RangeSource

Bytes of one remote object, fetched a range at a time: an HTTP server, or an object in a store.

Functions

build

The table and the summary for headers already read; names are their files.

detail

The Model tab: the model’s totals, then its metadata as key and value, every value whole.

is_safetensors_index

Whether path is a SafeTensors index: model.safetensors.index.json.

looks_like_gguf

Whether the first bytes of a file are GGUF’s magic.

looks_like_safetensors

Whether the first bytes of a file are a SafeTensors header: a little-endian length a header could have, then the { that opens its JSON.

parse_header

Parse bytes as whichever model header it starts with. For the fuzz target and the tests: both parsers over a slice, with no file.

read_gguf

Read one GGUF header (versions 2 and 3, either byte order) from reader, which holds len bytes in all.

read_header_ranged

Read one model header from src with ranged requests: SafeTensors as its first FIRST_SAFETENSORS_RANGE and, when its JSON runs past that, the rest of the JSON and no further; GGUF forward in growing ranges until its tensor infos end. Every bound the file readers keep is kept. stop is asked before each request.

read_header_ranged_from

As read_header_ranged, with the first range first (at least the 8 bytes of a SafeTensors length): small, for the fuzz target and the tests, so a header crosses many ranges.

read_model

Read paths — model files, or SafeTensors indexes that name them — as one table of tensors, with a file column when there is more than one file.

read_remote_model

Read urls — remote model files, or SafeTensors indexes that name them — as one table of tensors, as read_model reads files on disk, fetching only their headers. RangeError::NoRanges only for one file named on its own, which can be downloaded instead; for shards it is an error that says so.

read_safetensors

Read one SafeTensors header from reader, which holds len bytes in all.

url_file_name

The last segment of a URL, without a query: what a file’s row and its errors call it.

Type Aliases

Metadata

Metadata as key and value, in the order the file has them.

OpenRanges

A ranged source for a URL.