feat(safetensors): loadTensorStorageMapped on the sharded reader#582
Merged
michalharakal merged 1 commit intodevelopfrom Apr 30, 2026
Merged
Conversation
Mirrors the existing single-file
`StreamingSafeTensorsReader.loadTensorStorageMapped(tensor, filePath)`
on the sharded reader, removing the need for callers to know which
physical shard contains a given tensor.
Adds two overloads to `StreamingShardedSafeTensorsReader`:
- `loadTensorStorageMapped(tensor: ShardedTensorInfo): TensorStorage`
- `loadTensorStorageMapped(name: String): TensorStorage`
Both return a `TensorStorage` whose `BufferHandle.FileBacked` references
the resolved shard file's tensor byte range — enabling zero-copy /
memory-mapped reads of tensors that exceed the 2 GB JVM `ByteArray`
limit (used by the Gemma 4 PLE token-embedding table; ~4.7 GB BF16 on
E2B). Internally the new methods delegate to the per-shard reader's
existing `loadTensorStorageMapped(streamingTensor, filePath)`.
Adds end-to-end coverage in the new
`StreamingShardedSafeTensorsReaderJvmTest`:
- Build a real single-shard SafeTensors file via `SafeTensorsWriter`,
hand-craft a `model.safetensors.index.json` referencing it, open
via the sharded reader, assert `loadTensorStorageMapped` returns
the expected shape and a `BufferHandle.FileBacked` pointing at the
shard with the right size in bytes.
- Confirm the by-name overload errors with `IllegalArgumentException`
for an unknown tensor.
Motivation: SKaiNET-transformers `Gemma4SafeTensorsMappedPle` currently
opens a `FileChannel` and computes the byte range itself; this upstream
API will let it drop ~30 lines of mmap glue once a release lands.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 30, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
loadTensorStorageMappedtoStreamingShardedSafeTensorsReader, mirroring the existing single-fileStreamingSafeTensorsReader.loadTensorStorageMapped(tensor, filePath). Two overloads: byShardedTensorInfoand by tensor name. Both return aTensorStoragewhoseBufferHandle.FileBackedreferences the resolved shard file's tensor byte range — enabling zero-copy / memory-mapped reads of tensors that exceed the 2 GB JVMByteArraylimit.The new methods delegate internally to the per-shard reader; the caller doesn't need to know which physical shard contains a given tensor.
Motivation: SKaiNET-transformers
Gemma4SafeTensorsMappedPlecurrently opens aFileChanneland computes the byte range itself to mmap the Gemma 4 PLE token-embedding table (~4.7 GB BF16 on E2B, well past the 2 GB ByteArray cap). Once this lands and a release ships, that downstream code drops ~30 lines of JVM mmap glue and consumes the upstreamTensorStoragedirectly.Test plan
./gradlew :skainet-io:skainet-io-safetensors:jvmTest— passes in 6 s including new tests.StreamingShardedSafeTensorsReaderJvmTestcovers:ShardedTensorInfooverloads against a real single-shard SafeTensors fixture (built viaSafeTensorsWriter)TensorStorage.shape,isFileBacked,BufferHandle.FileBacked.path, andsizeInBytescorrectnessIllegalArgumentExceptionon unknown tensor name🤖 Generated with Claude Code