sakura-ml 0.1.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sakura_ml-0.1.4/.env.template +3 -0
- sakura_ml-0.1.4/.github/workflows/auto-release.yml +106 -0
- sakura_ml-0.1.4/.github/workflows/publish.yml +33 -0
- sakura_ml-0.1.4/.github/workflows/test.yml +32 -0
- sakura_ml-0.1.4/.gitignore +23 -0
- sakura_ml-0.1.4/PKG-INFO +222 -0
- sakura_ml-0.1.4/README.md +182 -0
- sakura_ml-0.1.4/Taskfile.yml +44 -0
- sakura_ml-0.1.4/bert_demo/bench_bert.py +275 -0
- sakura_ml-0.1.4/bert_demo/bench_in_memory_handle.py +145 -0
- sakura_ml-0.1.4/bert_demo/bench_notebook.ipynb +411 -0
- sakura_ml-0.1.4/bert_demo/hf_async_features.ipynb +410 -0
- sakura_ml-0.1.4/compose.yaml +39 -0
- sakura_ml-0.1.4/docker/Dockerfile +71 -0
- sakura_ml-0.1.4/docker/static/redis/run +8 -0
- sakura_ml-0.1.4/docker/static/sakura/run +9 -0
- sakura_ml-0.1.4/main.py +146 -0
- sakura_ml-0.1.4/mnist_demo/__init__.py +0 -0
- sakura_ml-0.1.4/mnist_demo/__main__.py +38 -0
- sakura_ml-0.1.4/mnist_demo/lightning/__init__.py +0 -0
- sakura_ml-0.1.4/mnist_demo/lightning/main.py +78 -0
- sakura_ml-0.1.4/mnist_demo/model.py +31 -0
- sakura_ml-0.1.4/mnist_demo/trainer.py +104 -0
- sakura_ml-0.1.4/mnist_demo/utils.py +36 -0
- sakura_ml-0.1.4/pyproject.toml +73 -0
- sakura_ml-0.1.4/sakura/__init__.py +3 -0
- sakura_ml-0.1.4/sakura/__main__.py +22 -0
- sakura_ml-0.1.4/sakura/config.yaml +16 -0
- sakura_ml-0.1.4/sakura/ddp/__init__.py +348 -0
- sakura_ml-0.1.4/sakura/functional.py +9 -0
- sakura_ml-0.1.4/sakura/huggingface/__init__.py +447 -0
- sakura_ml-0.1.4/sakura/lightning/__init__.py +304 -0
- sakura_ml-0.1.4/sakura/ml/__init__.py +2 -0
- sakura_ml-0.1.4/sakura/ml/async_trainer.py +129 -0
- sakura_ml-0.1.4/sakura/ml/epoch/__init__.py +1 -0
- sakura_ml-0.1.4/sakura/ml/epoch/range.py +20 -0
- sakura_ml-0.1.4/sakura/ml/sakura_trainer.py +56 -0
- sakura_ml-0.1.4/sakura/tensorflow/__init__.py +182 -0
- sakura_ml-0.1.4/taskfiles/bench.yml +25 -0
- sakura_ml-0.1.4/taskfiles/build.yml +54 -0
- sakura_ml-0.1.4/taskfiles/docker.yml +39 -0
- sakura_ml-0.1.4/taskfiles/test.yml +20 -0
- sakura_ml-0.1.4/tests/__init__.py +0 -0
- sakura_ml-0.1.4/tests/conftest.py +29 -0
- sakura_ml-0.1.4/tests/test_async_trainer.py +63 -0
- sakura_ml-0.1.4/tests/test_ddp.py +102 -0
- sakura_ml-0.1.4/tests/test_epoch_range.py +39 -0
- sakura_ml-0.1.4/tests/test_functional.py +30 -0
- sakura_ml-0.1.4/tests/test_huggingface.py +67 -0
- sakura_ml-0.1.4/tests/test_pkg_info.py +12 -0
- sakura_ml-0.1.4/tests/test_sakura_trainer.py +82 -0
- sakura_ml-0.1.4/uv.lock +3997 -0
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
name: Auto-release
|
|
2
|
+
|
|
3
|
+
# On master push: bump patch, tag, create release, and publish the wheel
|
|
4
|
+
# to PyPI. Publishing is inlined (rather than a release-triggered sibling
|
|
5
|
+
# workflow) because releases created by GITHUB_TOKEN don't cascade into
|
|
6
|
+
# other workflows — so the chained approach never fires.
|
|
7
|
+
|
|
8
|
+
on:
|
|
9
|
+
push:
|
|
10
|
+
branches: [master, main]
|
|
11
|
+
paths-ignore:
|
|
12
|
+
- "**.md"
|
|
13
|
+
- "bert_demo/**.ipynb"
|
|
14
|
+
- "mnist_demo/**"
|
|
15
|
+
- ".github/workflows/*.yml"
|
|
16
|
+
workflow_dispatch:
|
|
17
|
+
|
|
18
|
+
permissions:
|
|
19
|
+
contents: write
|
|
20
|
+
|
|
21
|
+
concurrency:
|
|
22
|
+
group: auto-release
|
|
23
|
+
cancel-in-progress: false
|
|
24
|
+
|
|
25
|
+
jobs:
|
|
26
|
+
bump-and-release:
|
|
27
|
+
if: "!contains(github.event.head_commit.message, '[skip release]')"
|
|
28
|
+
runs-on: ubuntu-latest
|
|
29
|
+
outputs:
|
|
30
|
+
tag: ${{ steps.bump.outputs.tag }}
|
|
31
|
+
new_version: ${{ steps.bump.outputs.new_version }}
|
|
32
|
+
steps:
|
|
33
|
+
- uses: actions/checkout@v4
|
|
34
|
+
with:
|
|
35
|
+
fetch-depth: 0
|
|
36
|
+
token: ${{ secrets.GITHUB_TOKEN }}
|
|
37
|
+
|
|
38
|
+
- name: Configure git
|
|
39
|
+
run: |
|
|
40
|
+
git config user.name "github-actions[bot]"
|
|
41
|
+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
|
42
|
+
|
|
43
|
+
- name: Bump patch version
|
|
44
|
+
id: bump
|
|
45
|
+
run: |
|
|
46
|
+
set -euo pipefail
|
|
47
|
+
CURRENT=$(grep -E '^__version__ = ' sakura/__init__.py | sed -E 's/.*"([^"]+)".*/\1/')
|
|
48
|
+
IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
|
|
49
|
+
NEW="${MAJOR}.${MINOR}.$((PATCH + 1))"
|
|
50
|
+
echo " current: $CURRENT"
|
|
51
|
+
echo " new : $NEW"
|
|
52
|
+
sed -i.bak -E "s/^__version__ = \".*\"/__version__ = \"$NEW\"/" sakura/__init__.py
|
|
53
|
+
sed -i.bak -E "s/^version = \".*\"/version = \"$NEW\"/" pyproject.toml
|
|
54
|
+
rm sakura/__init__.py.bak pyproject.toml.bak
|
|
55
|
+
echo "new_version=$NEW" >> "$GITHUB_OUTPUT"
|
|
56
|
+
echo "tag=v$NEW" >> "$GITHUB_OUTPUT"
|
|
57
|
+
|
|
58
|
+
- name: Commit + tag
|
|
59
|
+
run: |
|
|
60
|
+
set -euo pipefail
|
|
61
|
+
git add sakura/__init__.py pyproject.toml
|
|
62
|
+
git commit -m "chore(release): v${{ steps.bump.outputs.new_version }} [skip release]"
|
|
63
|
+
git tag "${{ steps.bump.outputs.tag }}"
|
|
64
|
+
git push origin HEAD:${{ github.ref_name }}
|
|
65
|
+
git push origin "${{ steps.bump.outputs.tag }}"
|
|
66
|
+
|
|
67
|
+
- name: Create GitHub release
|
|
68
|
+
env:
|
|
69
|
+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
70
|
+
run: |
|
|
71
|
+
gh release create "${{ steps.bump.outputs.tag }}" \
|
|
72
|
+
--title "${{ steps.bump.outputs.tag }}" \
|
|
73
|
+
--generate-notes
|
|
74
|
+
|
|
75
|
+
publish-pypi:
|
|
76
|
+
needs: bump-and-release
|
|
77
|
+
runs-on: ubuntu-latest
|
|
78
|
+
environment: release
|
|
79
|
+
steps:
|
|
80
|
+
- uses: actions/checkout@v4
|
|
81
|
+
with:
|
|
82
|
+
ref: ${{ needs.bump-and-release.outputs.tag }}
|
|
83
|
+
|
|
84
|
+
- uses: actions/setup-python@v5
|
|
85
|
+
with:
|
|
86
|
+
python-version: "3.12"
|
|
87
|
+
|
|
88
|
+
- uses: astral-sh/setup-uv@v4
|
|
89
|
+
|
|
90
|
+
- name: Build wheel + sdist
|
|
91
|
+
run: |
|
|
92
|
+
uv venv .venv
|
|
93
|
+
uv pip install --python .venv/bin/python hatchling build twine
|
|
94
|
+
.venv/bin/python -m build --outdir dist
|
|
95
|
+
|
|
96
|
+
- name: Publish to PyPI (API token)
|
|
97
|
+
env:
|
|
98
|
+
TWINE_USERNAME: __token__
|
|
99
|
+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
|
|
100
|
+
run: |
|
|
101
|
+
set -euo pipefail
|
|
102
|
+
if [ -z "${TWINE_PASSWORD:-}" ]; then
|
|
103
|
+
echo "::error::PYPI_API_TOKEN secret is not set on the 'release' environment."
|
|
104
|
+
exit 1
|
|
105
|
+
fi
|
|
106
|
+
.venv/bin/python -m twine upload dist/* --non-interactive
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
publish-pypi:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
environment: release
|
|
11
|
+
permissions:
|
|
12
|
+
id-token: write
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
|
|
16
|
+
- name: Set up Python
|
|
17
|
+
uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: "3.12"
|
|
20
|
+
|
|
21
|
+
- name: Install uv
|
|
22
|
+
uses: astral-sh/setup-uv@v4
|
|
23
|
+
|
|
24
|
+
- name: Build wheel
|
|
25
|
+
run: |
|
|
26
|
+
uv venv .venv
|
|
27
|
+
uv pip install --python .venv/bin/python hatchling build
|
|
28
|
+
.venv/bin/python -m build --wheel --outdir dist
|
|
29
|
+
|
|
30
|
+
- name: Publish to PyPI (trusted publishing)
|
|
31
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
32
|
+
with:
|
|
33
|
+
packages-dir: dist/
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
name: Test
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [master, main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [master, main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
pytest:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.11", "3.12"]
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
19
|
+
uses: actions/setup-python@v5
|
|
20
|
+
with:
|
|
21
|
+
python-version: ${{ matrix.python-version }}
|
|
22
|
+
|
|
23
|
+
- name: Install uv
|
|
24
|
+
uses: astral-sh/setup-uv@v4
|
|
25
|
+
|
|
26
|
+
- name: Install package + test deps
|
|
27
|
+
run: |
|
|
28
|
+
uv venv .venv
|
|
29
|
+
uv pip install --python .venv/bin/python -e '.[huggingface]' pytest
|
|
30
|
+
|
|
31
|
+
- name: Run tests
|
|
32
|
+
run: .venv/bin/pytest tests/ -v
|
sakura_ml-0.1.4/PKG-INFO
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sakura-ml
|
|
3
|
+
Version: 0.1.4
|
|
4
|
+
Summary: Sakura provides asynchronous training for DNN.
|
|
5
|
+
Author-email: ZakuroAI <git@zakuro.ai>
|
|
6
|
+
License-Expression: BSD-3-Clause
|
|
7
|
+
Classifier: Intended Audience :: Developers
|
|
8
|
+
Classifier: Intended Audience :: Education
|
|
9
|
+
Classifier: Intended Audience :: Science/Research
|
|
10
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Topic :: Scientific/Engineering
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
15
|
+
Classifier: Topic :: Software Development
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Requires-Dist: chardet
|
|
20
|
+
Requires-Dist: charset-normalizer==3.1.0
|
|
21
|
+
Requires-Dist: gnutools-python
|
|
22
|
+
Requires-Dist: ipython
|
|
23
|
+
Requires-Dist: lightning
|
|
24
|
+
Requires-Dist: numpy
|
|
25
|
+
Requires-Dist: six
|
|
26
|
+
Requires-Dist: torch
|
|
27
|
+
Requires-Dist: torchvision
|
|
28
|
+
Requires-Dist: tqdm>=4.64.0
|
|
29
|
+
Requires-Dist: zakuro-ai>=0.2.3
|
|
30
|
+
Provides-Extra: bench
|
|
31
|
+
Requires-Dist: accelerate>=0.25.0; extra == 'bench'
|
|
32
|
+
Requires-Dist: datasets>=2.14.0; extra == 'bench'
|
|
33
|
+
Requires-Dist: transformers>=4.40.0; extra == 'bench'
|
|
34
|
+
Provides-Extra: huggingface
|
|
35
|
+
Requires-Dist: datasets>=2.14.0; extra == 'huggingface'
|
|
36
|
+
Requires-Dist: transformers>=4.40.0; extra == 'huggingface'
|
|
37
|
+
Provides-Extra: tensorflow
|
|
38
|
+
Requires-Dist: tensorflow>=2.15.0; extra == 'tensorflow'
|
|
39
|
+
Description-Content-Type: text/markdown
|
|
40
|
+
|
|
41
|
+
<h1 align="center">Sakura</h1>
|
|
42
|
+
|
|
43
|
+
<p align="center">
|
|
44
|
+
ML-framework integrations for <a href="https://github.com/zakuro-ai/zakuro">Zakuro</a> —
|
|
45
|
+
hide evaluation, logging, and checkpointing behind training so the main loop never waits.
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
<p align="center">
|
|
49
|
+
<a href="#quick-start">Quick Start</a> •
|
|
50
|
+
<a href="#installation">Installation</a> •
|
|
51
|
+
<a href="#pytorch-lightning">Lightning</a> •
|
|
52
|
+
<a href="#huggingface-trainer">HuggingFace</a> •
|
|
53
|
+
<a href="#tensorflow--keras">TensorFlow</a> •
|
|
54
|
+
<a href="#benchmarks--notebooks">Benchmarks</a>
|
|
55
|
+
</p>
|
|
56
|
+
|
|
57
|
+
--------------------------------------------------------------------------------
|
|
58
|
+
|
|
59
|
+
## What is Sakura?
|
|
60
|
+
|
|
61
|
+
Sakura wraps the framework you're already using (PyTorch Lightning, HuggingFace `Trainer`, TensorFlow `Model.fit`) with a callback that **dispatches evaluation to a [Zakuro](https://github.com/zakuro-ai/zakuro) worker** instead of running it inline. Training keeps stepping while eval runs on a side pool; metrics come back through a non-blocking queue.
|
|
62
|
+
|
|
63
|
+
The old Sakura used MPI + Redis for this plumbing. The current Sakura uses Zakuro — one `@zk.fn` dispatch per epoch, shared connection, context-aware allocation across a pool of workers. No MPI, no Redis, no `SAKURA_ROLE` fork.
|
|
64
|
+
|
|
65
|
+
## Quick start
|
|
66
|
+
|
|
67
|
+
### Laptop-only (no worker setup)
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
import lightning as L
|
|
71
|
+
from sakura.lightning import SakuraTrainer
|
|
72
|
+
|
|
73
|
+
trainer = SakuraTrainer(
|
|
74
|
+
max_epochs=10,
|
|
75
|
+
accelerator="auto",
|
|
76
|
+
model_factory=MyLightningModule, # rebuilds on the eval worker
|
|
77
|
+
val_loader_factory=lambda: val_loader,
|
|
78
|
+
)
|
|
79
|
+
trainer.run(model, train_loader) # val_compute=None → Zakuro standalone fallback
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
No `zakuro-worker` needed — the eval runs in-process via Zakuro's standalone fallback, but the async dispatch pattern still works.
|
|
83
|
+
|
|
84
|
+
### HuggingFace `Trainer` with a real worker
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from transformers import Trainer, TrainingArguments
|
|
88
|
+
from sakura.huggingface import SakuraHFCallback
|
|
89
|
+
import zakuro as zk
|
|
90
|
+
|
|
91
|
+
trainer = Trainer(
|
|
92
|
+
model=model,
|
|
93
|
+
args=TrainingArguments(..., eval_strategy="no"), # we handle eval
|
|
94
|
+
train_dataset=train_ds,
|
|
95
|
+
callbacks=[
|
|
96
|
+
SakuraHFCallback(
|
|
97
|
+
model_factory=lambda: AutoModelForSequenceClassification.from_config(config),
|
|
98
|
+
eval_fn=my_eval_fn,
|
|
99
|
+
eval_payload=(val_inputs, 32),
|
|
100
|
+
val_compute=zk.Compute(uri="quic://worker:4433"),
|
|
101
|
+
fp16_state_dict=True,
|
|
102
|
+
on_backpressure="skip",
|
|
103
|
+
)
|
|
104
|
+
],
|
|
105
|
+
)
|
|
106
|
+
trainer.train()
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`on_backpressure="skip"` makes the callback consult `AdaptiveCompute.is_backpressured()` before every dispatch — if the allocator reports saturation (the slow eval worker can't keep up), that epoch's eval is dropped rather than blocking training.
|
|
110
|
+
|
|
111
|
+
## Installation
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# Core + HuggingFace integration
|
|
115
|
+
pip install 'sakura-ml[huggingface]'
|
|
116
|
+
|
|
117
|
+
# Everything
|
|
118
|
+
pip install 'sakura-ml[huggingface,tensorflow,bench]'
|
|
119
|
+
|
|
120
|
+
# From source
|
|
121
|
+
git clone https://github.com/zakuro-ai/sakura && cd sakura
|
|
122
|
+
uv pip install -e '.[huggingface]'
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Zakuro is pulled transitively. For a worker (HTTP or QUIC) install the `[worker]` extra on the zakuro package.
|
|
126
|
+
|
|
127
|
+
## PyTorch Lightning
|
|
128
|
+
|
|
129
|
+
`sakura.lightning.SakuraTrainer` — a drop-in replacement for the async-eval case:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from sakura.lightning import SakuraTrainer
|
|
133
|
+
|
|
134
|
+
trainer = SakuraTrainer(
|
|
135
|
+
max_epochs=10,
|
|
136
|
+
accelerator="auto",
|
|
137
|
+
# how the eval worker rebuilds the model:
|
|
138
|
+
model_factory=lambda: MyLightningModule(),
|
|
139
|
+
# how the eval worker rebuilds the dataloader:
|
|
140
|
+
val_loader_factory=lambda: DataLoader(val_ds, batch_size=256),
|
|
141
|
+
# optional: where to run eval
|
|
142
|
+
val_compute=zk.Compute(uri="quic://eval-worker:4433"),
|
|
143
|
+
# optional: where to save the best-loss checkpoint
|
|
144
|
+
model_path="checkpoints/best.pth",
|
|
145
|
+
)
|
|
146
|
+
trainer.run(model, train_loader)
|
|
147
|
+
|
|
148
|
+
print(trainer.history) # [{epoch, val_loss, worker_name, elapsed_secs}, ...]
|
|
149
|
+
print(trainer.best_val_loss)
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## HuggingFace Trainer
|
|
153
|
+
|
|
154
|
+
`sakura.huggingface.SakuraHFCallback` is a `transformers.TrainerCallback` that cloudpickles `state_dict` on `on_epoch_end`, dispatches a remote eval, and lazily reaps futures as they finish. Knobs:
|
|
155
|
+
|
|
156
|
+
| parameter | what it does |
|
|
157
|
+
|---|---|
|
|
158
|
+
| `model_factory` | how the eval worker rebuilds the architecture (weights stream in from the callback) |
|
|
159
|
+
| `eval_fn(model, payload)` | the eval routine itself — runs on the worker, returns a `dict` of metrics |
|
|
160
|
+
| `eval_payload` | anything cloudpickle can serialise — dataset, tokenizer, batch size |
|
|
161
|
+
| `val_compute` | `zk.Compute` or `zk.AdaptiveCompute`; `None` → standalone |
|
|
162
|
+
| `drain="lazy"` *(default)* / `"strict"` | whether `on_epoch_end` blocks to reap the previous future |
|
|
163
|
+
| `cache_key=...` | keep the validator model architecture warm on the worker |
|
|
164
|
+
| `fp16_state_dict=True` | halve the wire bytes |
|
|
165
|
+
| `async_copy=True` *(default, CUDA-only)* | GPU→CPU snapshot on a dedicated stream, ~170 → 75 ms per epoch on x399 4090 |
|
|
166
|
+
| `on_backpressure={"skip","queue","block"}` | policy when `AdaptiveCompute` reports saturation |
|
|
167
|
+
| `max_pending` | cap on in-flight evaluations |
|
|
168
|
+
|
|
169
|
+
In-memory fast path is **automatic**: when `val_compute` resolves to standalone, `torch.save`/`torch.load` are skipped entirely — measured +23.6 % wall on a 3-epoch distilbert fine-tune vs forced serialisation.
|
|
170
|
+
|
|
171
|
+
## TensorFlow / Keras
|
|
172
|
+
|
|
173
|
+
`sakura.tensorflow.SakuraKerasCallback` — a `tf.keras.callbacks.Callback` with the same pattern:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
from sakura.tensorflow import SakuraKerasCallback
|
|
177
|
+
|
|
178
|
+
model.fit(
|
|
179
|
+
x_train, y_train,
|
|
180
|
+
epochs=10,
|
|
181
|
+
callbacks=[SakuraKerasCallback(
|
|
182
|
+
model_factory=lambda: tf.keras.Sequential([...]),
|
|
183
|
+
val_fn=lambda m, p: m.evaluate(*p, verbose=0, return_dict=True),
|
|
184
|
+
val_payload=(x_val, y_val),
|
|
185
|
+
val_compute=zk.Compute(uri="quic://eval-worker:4433"),
|
|
186
|
+
)],
|
|
187
|
+
)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Weights are transferred as numpy arrays via `get_weights()` / `set_weights()` — clean cloudpickle, no TF graph-state serialisation.
|
|
191
|
+
|
|
192
|
+
## Generic async trainer (framework-agnostic)
|
|
193
|
+
|
|
194
|
+
`sakura.ml.async_trainer.AsyncTrainer` — for training loops that aren't Lightning / HF / Keras. Takes any object implementing `train(loader)`, `serialized_state_dict()`, `_epochs`, `_metrics`, plus a `model_factory` and `test_fn(model) -> dict`. Same dispatch mechanics.
|
|
195
|
+
|
|
196
|
+
## Benchmarks & notebooks
|
|
197
|
+
|
|
198
|
+
- **[`bert_demo/hf_async_features.ipynb`](bert_demo/hf_async_features.ipynb)** — every `SakuraHFCallback` knob exercised on distilbert / SST-2. Runs in ~1 min on a laptop. Verified via `jupyter nbconvert --execute`.
|
|
199
|
+
- **[`bert_demo/bench_bert.py`](bert_demo/bench_bert.py)** — serial `Trainer` vs Sakura async, configurable.
|
|
200
|
+
- **[`bert_demo/bench_in_memory_handle.py`](bert_demo/bench_in_memory_handle.py)** — A/B the in-memory-handle fast path against `torch.save`. +23.6 % end-to-end measured.
|
|
201
|
+
|
|
202
|
+
## Measured performance wins (distilbert-base-uncased, 268 MB state_dict)
|
|
203
|
+
|
|
204
|
+
| slice | before | after | measured on |
|
|
205
|
+
|---|---|---|---|
|
|
206
|
+
| blocking `.cpu()` → async CUDA-stream copy | 176 ms / epoch main-thread | **75 ms** / epoch | x399 4090 |
|
|
207
|
+
| cloudpickle → `torch.save` for state_dict | 482 ms / epoch pool | **282 ms** / epoch | x399 CPU |
|
|
208
|
+
| in-memory handle for standalone | 9.12 s wall (3 epochs) | **7.59 s** | Mac MPS |
|
|
209
|
+
|
|
210
|
+
See [`zakuro/PLAN.md`](https://github.com/zakuro-ai/zakuro/blob/master/PLAN.md#measured-results-so-far) for the consolidated numbers across both repos.
|
|
211
|
+
|
|
212
|
+
## Development
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
git clone https://github.com/zakuro-ai/sakura && cd sakura
|
|
216
|
+
uv pip install -e '.[bench]'
|
|
217
|
+
uv run pytest tests/
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## License
|
|
221
|
+
|
|
222
|
+
BSD-3-Clause.
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
<h1 align="center">Sakura</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
ML-framework integrations for <a href="https://github.com/zakuro-ai/zakuro">Zakuro</a> —
|
|
5
|
+
hide evaluation, logging, and checkpointing behind training so the main loop never waits.
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="#quick-start">Quick Start</a> •
|
|
10
|
+
<a href="#installation">Installation</a> •
|
|
11
|
+
<a href="#pytorch-lightning">Lightning</a> •
|
|
12
|
+
<a href="#huggingface-trainer">HuggingFace</a> •
|
|
13
|
+
<a href="#tensorflow--keras">TensorFlow</a> •
|
|
14
|
+
<a href="#benchmarks--notebooks">Benchmarks</a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
--------------------------------------------------------------------------------
|
|
18
|
+
|
|
19
|
+
## What is Sakura?
|
|
20
|
+
|
|
21
|
+
Sakura wraps the framework you're already using (PyTorch Lightning, HuggingFace `Trainer`, TensorFlow `Model.fit`) with a callback that **dispatches evaluation to a [Zakuro](https://github.com/zakuro-ai/zakuro) worker** instead of running it inline. Training keeps stepping while eval runs on a side pool; metrics come back through a non-blocking queue.
|
|
22
|
+
|
|
23
|
+
The old Sakura used MPI + Redis for this plumbing. The current Sakura uses Zakuro — one `@zk.fn` dispatch per epoch, shared connection, context-aware allocation across a pool of workers. No MPI, no Redis, no `SAKURA_ROLE` fork.
|
|
24
|
+
|
|
25
|
+
## Quick start
|
|
26
|
+
|
|
27
|
+
### Laptop-only (no worker setup)
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
import lightning as L
|
|
31
|
+
from sakura.lightning import SakuraTrainer
|
|
32
|
+
|
|
33
|
+
trainer = SakuraTrainer(
|
|
34
|
+
max_epochs=10,
|
|
35
|
+
accelerator="auto",
|
|
36
|
+
model_factory=MyLightningModule, # rebuilds on the eval worker
|
|
37
|
+
val_loader_factory=lambda: val_loader,
|
|
38
|
+
)
|
|
39
|
+
trainer.run(model, train_loader) # val_compute=None → Zakuro standalone fallback
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
No `zakuro-worker` needed — the eval runs in-process via Zakuro's standalone fallback, but the async dispatch pattern still works.
|
|
43
|
+
|
|
44
|
+
### HuggingFace `Trainer` with a real worker
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
from transformers import Trainer, TrainingArguments
|
|
48
|
+
from sakura.huggingface import SakuraHFCallback
|
|
49
|
+
import zakuro as zk
|
|
50
|
+
|
|
51
|
+
trainer = Trainer(
|
|
52
|
+
model=model,
|
|
53
|
+
args=TrainingArguments(..., eval_strategy="no"), # we handle eval
|
|
54
|
+
train_dataset=train_ds,
|
|
55
|
+
callbacks=[
|
|
56
|
+
SakuraHFCallback(
|
|
57
|
+
model_factory=lambda: AutoModelForSequenceClassification.from_config(config),
|
|
58
|
+
eval_fn=my_eval_fn,
|
|
59
|
+
eval_payload=(val_inputs, 32),
|
|
60
|
+
val_compute=zk.Compute(uri="quic://worker:4433"),
|
|
61
|
+
fp16_state_dict=True,
|
|
62
|
+
on_backpressure="skip",
|
|
63
|
+
)
|
|
64
|
+
],
|
|
65
|
+
)
|
|
66
|
+
trainer.train()
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`on_backpressure="skip"` makes the callback consult `AdaptiveCompute.is_backpressured()` before every dispatch — if the allocator reports saturation (the slow eval worker can't keep up), that epoch's eval is dropped rather than blocking training.
|
|
70
|
+
|
|
71
|
+
## Installation
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# Core + HuggingFace integration
|
|
75
|
+
pip install 'sakura-ml[huggingface]'
|
|
76
|
+
|
|
77
|
+
# Everything
|
|
78
|
+
pip install 'sakura-ml[huggingface,tensorflow,bench]'
|
|
79
|
+
|
|
80
|
+
# From source
|
|
81
|
+
git clone https://github.com/zakuro-ai/sakura && cd sakura
|
|
82
|
+
uv pip install -e '.[huggingface]'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Zakuro is pulled transitively. For a worker (HTTP or QUIC) install the `[worker]` extra on the zakuro package.
|
|
86
|
+
|
|
87
|
+
## PyTorch Lightning
|
|
88
|
+
|
|
89
|
+
`sakura.lightning.SakuraTrainer` — a drop-in replacement for the async-eval case:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from sakura.lightning import SakuraTrainer
|
|
93
|
+
|
|
94
|
+
trainer = SakuraTrainer(
|
|
95
|
+
max_epochs=10,
|
|
96
|
+
accelerator="auto",
|
|
97
|
+
# how the eval worker rebuilds the model:
|
|
98
|
+
model_factory=lambda: MyLightningModule(),
|
|
99
|
+
# how the eval worker rebuilds the dataloader:
|
|
100
|
+
val_loader_factory=lambda: DataLoader(val_ds, batch_size=256),
|
|
101
|
+
# optional: where to run eval
|
|
102
|
+
val_compute=zk.Compute(uri="quic://eval-worker:4433"),
|
|
103
|
+
# optional: where to save the best-loss checkpoint
|
|
104
|
+
model_path="checkpoints/best.pth",
|
|
105
|
+
)
|
|
106
|
+
trainer.run(model, train_loader)
|
|
107
|
+
|
|
108
|
+
print(trainer.history) # [{epoch, val_loss, worker_name, elapsed_secs}, ...]
|
|
109
|
+
print(trainer.best_val_loss)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## HuggingFace Trainer
|
|
113
|
+
|
|
114
|
+
`sakura.huggingface.SakuraHFCallback` is a `transformers.TrainerCallback` that cloudpickles `state_dict` on `on_epoch_end`, dispatches a remote eval, and lazily reaps futures as they finish. Knobs:
|
|
115
|
+
|
|
116
|
+
| parameter | what it does |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `model_factory` | how the eval worker rebuilds the architecture (weights stream in from the callback) |
|
|
119
|
+
| `eval_fn(model, payload)` | the eval routine itself — runs on the worker, returns a `dict` of metrics |
|
|
120
|
+
| `eval_payload` | anything cloudpickle can serialise — dataset, tokenizer, batch size |
|
|
121
|
+
| `val_compute` | `zk.Compute` or `zk.AdaptiveCompute`; `None` → standalone |
|
|
122
|
+
| `drain="lazy"` *(default)* / `"strict"` | whether `on_epoch_end` blocks to reap the previous future |
|
|
123
|
+
| `cache_key=...` | keep the validator model architecture warm on the worker |
|
|
124
|
+
| `fp16_state_dict=True` | halve the wire bytes |
|
|
125
|
+
| `async_copy=True` *(default, CUDA-only)* | GPU→CPU snapshot on a dedicated stream, ~170 → 75 ms per epoch on x399 4090 |
|
|
126
|
+
| `on_backpressure={"skip","queue","block"}` | policy when `AdaptiveCompute` reports saturation |
|
|
127
|
+
| `max_pending` | cap on in-flight evaluations |
|
|
128
|
+
|
|
129
|
+
In-memory fast path is **automatic**: when `val_compute` resolves to standalone, `torch.save`/`torch.load` are skipped entirely — measured +23.6 % wall on a 3-epoch distilbert fine-tune vs forced serialisation.
|
|
130
|
+
|
|
131
|
+
## TensorFlow / Keras
|
|
132
|
+
|
|
133
|
+
`sakura.tensorflow.SakuraKerasCallback` — a `tf.keras.callbacks.Callback` with the same pattern:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from sakura.tensorflow import SakuraKerasCallback
|
|
137
|
+
|
|
138
|
+
model.fit(
|
|
139
|
+
x_train, y_train,
|
|
140
|
+
epochs=10,
|
|
141
|
+
callbacks=[SakuraKerasCallback(
|
|
142
|
+
model_factory=lambda: tf.keras.Sequential([...]),
|
|
143
|
+
val_fn=lambda m, p: m.evaluate(*p, verbose=0, return_dict=True),
|
|
144
|
+
val_payload=(x_val, y_val),
|
|
145
|
+
val_compute=zk.Compute(uri="quic://eval-worker:4433"),
|
|
146
|
+
)],
|
|
147
|
+
)
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Weights are transferred as numpy arrays via `get_weights()` / `set_weights()` — clean cloudpickle, no TF graph-state serialisation.
|
|
151
|
+
|
|
152
|
+
## Generic async trainer (framework-agnostic)
|
|
153
|
+
|
|
154
|
+
`sakura.ml.async_trainer.AsyncTrainer` — for training loops that aren't Lightning / HF / Keras. Takes any object implementing `train(loader)`, `serialized_state_dict()`, `_epochs`, `_metrics`, plus a `model_factory` and `test_fn(model) -> dict`. Same dispatch mechanics.
|
|
155
|
+
|
|
156
|
+
## Benchmarks & notebooks
|
|
157
|
+
|
|
158
|
+
- **[`bert_demo/hf_async_features.ipynb`](bert_demo/hf_async_features.ipynb)** — every `SakuraHFCallback` knob exercised on distilbert / SST-2. Runs in ~1 min on a laptop. Verified via `jupyter nbconvert --execute`.
|
|
159
|
+
- **[`bert_demo/bench_bert.py`](bert_demo/bench_bert.py)** — serial `Trainer` vs Sakura async, configurable.
|
|
160
|
+
- **[`bert_demo/bench_in_memory_handle.py`](bert_demo/bench_in_memory_handle.py)** — A/B the in-memory-handle fast path against `torch.save`. +23.6 % end-to-end measured.
|
|
161
|
+
|
|
162
|
+
## Measured performance wins (distilbert-base-uncased, 268 MB state_dict)
|
|
163
|
+
|
|
164
|
+
| slice | before | after | measured on |
|
|
165
|
+
|---|---|---|---|
|
|
166
|
+
| blocking `.cpu()` → async CUDA-stream copy | 176 ms / epoch main-thread | **75 ms** / epoch | x399 4090 |
|
|
167
|
+
| cloudpickle → `torch.save` for state_dict | 482 ms / epoch pool | **282 ms** / epoch | x399 CPU |
|
|
168
|
+
| in-memory handle for standalone | 9.12 s wall (3 epochs) | **7.59 s** | Mac MPS |
|
|
169
|
+
|
|
170
|
+
See [`zakuro/PLAN.md`](https://github.com/zakuro-ai/zakuro/blob/master/PLAN.md#measured-results-so-far) for the consolidated numbers across both repos.
|
|
171
|
+
|
|
172
|
+
## Development
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
git clone https://github.com/zakuro-ai/sakura && cd sakura
|
|
176
|
+
uv pip install -e '.[bench]'
|
|
177
|
+
uv run pytest tests/
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
BSD-3-Clause.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
version: '3'
|
|
2
|
+
|
|
3
|
+
dotenv:
|
|
4
|
+
- .env
|
|
5
|
+
|
|
6
|
+
vars:
|
|
7
|
+
PKG_NAME: sakura
|
|
8
|
+
VERSION:
|
|
9
|
+
sh: python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])"
|
|
10
|
+
|
|
11
|
+
includes:
|
|
12
|
+
build:
|
|
13
|
+
taskfile: taskfiles/build.yml
|
|
14
|
+
optional: true
|
|
15
|
+
docker:
|
|
16
|
+
taskfile: taskfiles/docker.yml
|
|
17
|
+
optional: true
|
|
18
|
+
test:
|
|
19
|
+
taskfile: taskfiles/test.yml
|
|
20
|
+
optional: true
|
|
21
|
+
bench:
|
|
22
|
+
taskfile: taskfiles/bench.yml
|
|
23
|
+
optional: true
|
|
24
|
+
|
|
25
|
+
tasks:
|
|
26
|
+
default:
|
|
27
|
+
desc: Show available tasks
|
|
28
|
+
cmds:
|
|
29
|
+
- task --list
|
|
30
|
+
|
|
31
|
+
help:
|
|
32
|
+
desc: Display project version and usage info
|
|
33
|
+
cmds:
|
|
34
|
+
- echo "{{.PKG_NAME}} v{{.VERSION}}"
|
|
35
|
+
- echo "Usage{{":"}} task {build:wheel, docker:run, ...}"
|
|
36
|
+
- echo "Please check README.md for instructions"
|
|
37
|
+
|
|
38
|
+
setup:
|
|
39
|
+
desc: Install prerequisites and verify environment
|
|
40
|
+
cmds:
|
|
41
|
+
- echo "Checking prerequisites..."
|
|
42
|
+
- cmd: command -v docker >/dev/null && echo "docker OK" || echo "docker NOT FOUND"
|
|
43
|
+
- cmd: command -v uv >/dev/null && echo "uv OK" || echo "uv NOT FOUND"
|
|
44
|
+
- cmd: command -v task >/dev/null && echo "task OK" || echo "task NOT FOUND"
|