runara 0.1.0__py3-none-any.whl
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.
- runara/__init__.py +39 -0
- runara/_futures.py +64 -0
- runara/_http.py +155 -0
- runara/client.py +286 -0
- runara/types.py +111 -0
- runara-0.1.0.dist-info/METADATA +115 -0
- runara-0.1.0.dist-info/RECORD +13 -0
- runara-0.1.0.dist-info/WHEEL +5 -0
- runara-0.1.0.dist-info/top_level.txt +2 -0
- runara_cookbook/__init__.py +11 -0
- runara_cookbook/data.py +88 -0
- runara_cookbook/renderers/__init__.py +60 -0
- runara_cookbook/renderers/base.py +203 -0
runara/__init__.py
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Fine-tune open models on Runara. You write the training loop; we hold the weights.
|
|
2
|
+
|
|
3
|
+
import runara
|
|
4
|
+
|
|
5
|
+
sc = runara.ServiceClient(api_key="rk_live_...")
|
|
6
|
+
tc = sc.create_lora_training_client(base_model="qwen3.5-4b", rank=32)
|
|
7
|
+
|
|
8
|
+
Your data stays on your machine. Only token ids and per-token loss weights
|
|
9
|
+
cross the wire — see `runara_cookbook` for turning your files into those.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from ._futures import Future
|
|
13
|
+
from ._http import InsufficientBalance, RunaraError, SessionClosed
|
|
14
|
+
from .client import ServiceClient, TrainingClient
|
|
15
|
+
from .types import (
|
|
16
|
+
AdamParams,
|
|
17
|
+
Checkpoint,
|
|
18
|
+
Datum,
|
|
19
|
+
ForwardBackwardResult,
|
|
20
|
+
ModelInfo,
|
|
21
|
+
SampleResult,
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
__version__ = "0.1.0"
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"AdamParams",
|
|
28
|
+
"Checkpoint",
|
|
29
|
+
"Datum",
|
|
30
|
+
"ForwardBackwardResult",
|
|
31
|
+
"Future",
|
|
32
|
+
"InsufficientBalance",
|
|
33
|
+
"ModelInfo",
|
|
34
|
+
"RunaraError",
|
|
35
|
+
"SampleResult",
|
|
36
|
+
"ServiceClient",
|
|
37
|
+
"SessionClosed",
|
|
38
|
+
"TrainingClient",
|
|
39
|
+
]
|
runara/_futures.py
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"""Futures that let a training loop stay ahead of the network.
|
|
2
|
+
|
|
3
|
+
A step is two calls — ``forward_backward`` then ``optim_step`` — and a loop
|
|
4
|
+
that awaits each one spends most of its wall-clock time waiting for a round
|
|
5
|
+
trip while the GPU sits idle. The worker already guarantees that calls for one
|
|
6
|
+
session are applied in the order they arrive, so the client can submit both and
|
|
7
|
+
collect later.
|
|
8
|
+
|
|
9
|
+
That ordering guarantee is what makes this safe, and it is the worker's
|
|
10
|
+
per-session lock that provides it. Without it, two in-flight calls would race
|
|
11
|
+
on the same adapter and the optimizer could apply a step before the gradients
|
|
12
|
+
it was meant to apply.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
from concurrent.futures import Future as _Future
|
|
18
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
19
|
+
from typing import Callable, Generic, TypeVar
|
|
20
|
+
|
|
21
|
+
T = TypeVar("T")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class Future(Generic[T]):
|
|
25
|
+
"""A submitted request. Call ``result()`` when you actually need the value.
|
|
26
|
+
|
|
27
|
+
Deliberately thin: it is one outstanding HTTP request, not a task in a
|
|
28
|
+
scheduler. There is no polling, no result store and no reconnection
|
|
29
|
+
protocol, because there is nothing to reconnect to — the request either
|
|
30
|
+
returns or raises.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
def __init__(self, inner: _Future) -> None:
|
|
34
|
+
self._inner = inner
|
|
35
|
+
|
|
36
|
+
def result(self, timeout: float | None = None) -> T:
|
|
37
|
+
"""Block until the worker answers, re-raising whatever it raised."""
|
|
38
|
+
return self._inner.result(timeout)
|
|
39
|
+
|
|
40
|
+
def done(self) -> bool:
|
|
41
|
+
return self._inner.done()
|
|
42
|
+
|
|
43
|
+
def __repr__(self) -> str: # pragma: no cover - debugging convenience
|
|
44
|
+
state = "done" if self.done() else "pending"
|
|
45
|
+
return f"<runara.Future {state}>"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class Submitter:
|
|
49
|
+
"""Runs requests for one session, one at a time, in submission order.
|
|
50
|
+
|
|
51
|
+
A single worker thread rather than a pool: the ordering the protocol
|
|
52
|
+
promises is per session, and a pool would let two requests for the same
|
|
53
|
+
session overlap. Pipelining comes from the client not blocking, not from
|
|
54
|
+
the requests running concurrently.
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
def __init__(self) -> None:
|
|
58
|
+
self._pool = ThreadPoolExecutor(max_workers=1, thread_name_prefix="runara")
|
|
59
|
+
|
|
60
|
+
def submit(self, fn: Callable[..., T], *args, **kwargs) -> Future[T]:
|
|
61
|
+
return Future(self._pool.submit(fn, *args, **kwargs))
|
|
62
|
+
|
|
63
|
+
def close(self) -> None:
|
|
64
|
+
self._pool.shutdown(wait=True)
|
runara/_http.py
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
"""HTTP, with the retry policy spelled out.
|
|
2
|
+
|
|
3
|
+
Two different endpoints with different failure characters:
|
|
4
|
+
|
|
5
|
+
* The **control plane** creates sessions and lists checkpoints. Slow, rare,
|
|
6
|
+
and safe to retry only because session creation is idempotent on a request
|
|
7
|
+
id the client generates.
|
|
8
|
+
* The **worker** runs the training calls. Fast, frequent, and **not** safe to
|
|
9
|
+
retry: a ``forward_backward`` that timed out may well have applied its
|
|
10
|
+
gradients, and sending it again would train on the same batch twice. So the
|
|
11
|
+
worker path retries only on errors that prove the request never arrived.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import json
|
|
17
|
+
import os
|
|
18
|
+
import ssl
|
|
19
|
+
import tempfile
|
|
20
|
+
import time
|
|
21
|
+
import urllib.error
|
|
22
|
+
import urllib.request
|
|
23
|
+
from typing import Any
|
|
24
|
+
|
|
25
|
+
#: Only these are retried on the worker path: the request did not land.
|
|
26
|
+
_CONNECTION_ERRORS = (urllib.error.URLError, TimeoutError, ConnectionError)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class _PinnedWorker:
|
|
30
|
+
"""A TLS context that trusts one worker's certificate and nothing else.
|
|
31
|
+
|
|
32
|
+
A training worker is rented for minutes at an address we do not own, so
|
|
33
|
+
there is no public certificate for it and no DNS name to put in one. The
|
|
34
|
+
control plane, which we do authenticate normally, tells us the exact
|
|
35
|
+
certificate the worker will present; this trusts that and only that.
|
|
36
|
+
|
|
37
|
+
That is stronger than the usual path rather than weaker. A public CA would
|
|
38
|
+
vouch for anyone who could prove control of the address; this vouches for
|
|
39
|
+
the one machine the control plane placed our session on. The alternative
|
|
40
|
+
actually on offer — ``verify=False`` — would leave the training tokens on
|
|
41
|
+
the wire readable by anyone between here and the GPU.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
def __init__(self, cert_pem: str):
|
|
45
|
+
if not cert_pem.startswith("-----BEGIN CERTIFICATE-----"):
|
|
46
|
+
raise ValueError("worker certificate is not PEM")
|
|
47
|
+
# NamedTemporaryFile because SSLContext loads CAs from a path. Written
|
|
48
|
+
# 0600 and removed when the client is done with it.
|
|
49
|
+
handle = tempfile.NamedTemporaryFile(
|
|
50
|
+
"w", suffix=".pem", prefix="runara-worker-", delete=False
|
|
51
|
+
)
|
|
52
|
+
try:
|
|
53
|
+
os.chmod(handle.name, 0o600)
|
|
54
|
+
handle.write(cert_pem)
|
|
55
|
+
finally:
|
|
56
|
+
handle.close()
|
|
57
|
+
self._path = handle.name
|
|
58
|
+
|
|
59
|
+
context = ssl.create_default_context(cafile=self._path)
|
|
60
|
+
context.minimum_version = ssl.TLSVersion.TLSv1_2
|
|
61
|
+
# The certificate carries the worker's IP in its SAN, so the hostname
|
|
62
|
+
# check is a real check and stays on.
|
|
63
|
+
context.check_hostname = True
|
|
64
|
+
context.verify_mode = ssl.CERT_REQUIRED
|
|
65
|
+
self.context = context
|
|
66
|
+
|
|
67
|
+
def close(self) -> None:
|
|
68
|
+
try:
|
|
69
|
+
os.unlink(self._path)
|
|
70
|
+
except OSError:
|
|
71
|
+
pass
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class RunaraError(Exception):
|
|
75
|
+
"""An error the service reported, with its code where there is one."""
|
|
76
|
+
|
|
77
|
+
def __init__(self, message: str, *, status: int | None = None, code: str | None = None):
|
|
78
|
+
super().__init__(message)
|
|
79
|
+
self.status = status
|
|
80
|
+
self.code = code
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class InsufficientBalance(RunaraError):
|
|
84
|
+
"""The organization is out of credit. Training stops until it is topped up."""
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class SessionClosed(RunaraError):
|
|
88
|
+
"""The session has ended, or is ending because the balance ran out."""
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _raise_for(status: int, body: Any, url: str) -> None:
|
|
92
|
+
error = body.get("error") if isinstance(body, dict) else None
|
|
93
|
+
code = error.get("code") if isinstance(error, dict) else (error if isinstance(error, str) else None)
|
|
94
|
+
message = error.get("message") if isinstance(error, dict) else str(error or body)
|
|
95
|
+
|
|
96
|
+
if status == 402 or code == "INSUFFICIENT_BALANCE":
|
|
97
|
+
raise InsufficientBalance(message, status=status, code=code)
|
|
98
|
+
if code in {"session_closed", "session_closing", "session_not_resident"}:
|
|
99
|
+
raise SessionClosed(message, status=status, code=code)
|
|
100
|
+
raise RunaraError(f"{message} ({url.rsplit('/', 1)[-1]})", status=status, code=code)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def request(
|
|
104
|
+
method: str,
|
|
105
|
+
url: str,
|
|
106
|
+
token: str,
|
|
107
|
+
body: dict | None = None,
|
|
108
|
+
*,
|
|
109
|
+
timeout: float = 600.0,
|
|
110
|
+
retries: int = 0,
|
|
111
|
+
ssl_context: ssl.SSLContext | None = None,
|
|
112
|
+
) -> Any:
|
|
113
|
+
"""One request, retried only when it provably did not arrive.
|
|
114
|
+
|
|
115
|
+
`retries` defaults to zero. The caller decides, because only the caller
|
|
116
|
+
knows whether repeating the call is safe — and for a training step it is
|
|
117
|
+
not: a timed-out forward_backward may have already applied its gradients.
|
|
118
|
+
"""
|
|
119
|
+
payload = json.dumps(body).encode() if body is not None else None
|
|
120
|
+
attempt = 0
|
|
121
|
+
while True:
|
|
122
|
+
http_request = urllib.request.Request(
|
|
123
|
+
url,
|
|
124
|
+
data=payload,
|
|
125
|
+
method=method,
|
|
126
|
+
headers={
|
|
127
|
+
"Authorization": f"Bearer {token}",
|
|
128
|
+
"Content-Type": "application/json",
|
|
129
|
+
"User-Agent": "runara-python",
|
|
130
|
+
},
|
|
131
|
+
)
|
|
132
|
+
try:
|
|
133
|
+
with urllib.request.urlopen(
|
|
134
|
+
http_request, timeout=timeout, context=ssl_context
|
|
135
|
+
) as response:
|
|
136
|
+
raw = response.read()
|
|
137
|
+
return json.loads(raw) if raw else {}
|
|
138
|
+
except urllib.error.HTTPError as error:
|
|
139
|
+
try:
|
|
140
|
+
parsed = json.loads(error.read())
|
|
141
|
+
except Exception: # noqa: BLE001 - a non-JSON error body is still an error
|
|
142
|
+
parsed = {"error": {"message": error.reason}}
|
|
143
|
+
# A 503 means the worker is still loading its weights; that is a
|
|
144
|
+
# wait, not a failure, and the request never reached the model.
|
|
145
|
+
if error.code == 503 and attempt < retries:
|
|
146
|
+
attempt += 1
|
|
147
|
+
time.sleep(min(2**attempt, 10))
|
|
148
|
+
continue
|
|
149
|
+
_raise_for(error.code, parsed, url)
|
|
150
|
+
except _CONNECTION_ERRORS as error:
|
|
151
|
+
if attempt < retries:
|
|
152
|
+
attempt += 1
|
|
153
|
+
time.sleep(min(2**attempt, 10))
|
|
154
|
+
continue
|
|
155
|
+
raise RunaraError(f"Could not reach {url.rsplit('/', 2)[0]}: {error}") from error
|
runara/client.py
ADDED
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
"""The client. Four primitives against base weights you never have to host.
|
|
2
|
+
|
|
3
|
+
import runara
|
|
4
|
+
|
|
5
|
+
sc = runara.ServiceClient(api_key="rk_live_...")
|
|
6
|
+
tc = sc.create_lora_training_client(base_model="qwen3.5-4b", rank=32)
|
|
7
|
+
|
|
8
|
+
for batch in batches:
|
|
9
|
+
fb = tc.forward_backward(batch) # submitted, not awaited
|
|
10
|
+
tc.optim_step(runara.AdamParams(1e-4)) # submitted straight after
|
|
11
|
+
print(fb.result().loss) # the loop blocks here
|
|
12
|
+
|
|
13
|
+
tc.save_state(name="support-v1")
|
|
14
|
+
|
|
15
|
+
Your data never leaves your machine as text. The cookbook turns whatever you
|
|
16
|
+
have into `Datum`s locally, and only token ids and loss weights are sent.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import os
|
|
22
|
+
import time
|
|
23
|
+
import uuid
|
|
24
|
+
from dataclasses import dataclass
|
|
25
|
+
|
|
26
|
+
from . import _http
|
|
27
|
+
from ._futures import Future, Submitter
|
|
28
|
+
from .types import (
|
|
29
|
+
AdamParams,
|
|
30
|
+
Checkpoint,
|
|
31
|
+
Datum,
|
|
32
|
+
ForwardBackwardResult,
|
|
33
|
+
ModelInfo,
|
|
34
|
+
SampleResult,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
DEFAULT_BASE_URL = "https://runara.ai/api/v1"
|
|
38
|
+
#: Refresh this far before expiry, so a long call cannot start on a token that
|
|
39
|
+
#: dies mid-flight.
|
|
40
|
+
TOKEN_REFRESH_MARGIN_SECONDS = 120
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class ServiceClient:
|
|
44
|
+
"""Your account. Opens training sessions and reads what you have saved."""
|
|
45
|
+
|
|
46
|
+
def __init__(self, api_key: str | None = None, base_url: str | None = None) -> None:
|
|
47
|
+
key = api_key or os.environ.get("RUNARA_API_KEY")
|
|
48
|
+
if not key:
|
|
49
|
+
raise ValueError(
|
|
50
|
+
"No API key. Pass api_key=... or set RUNARA_API_KEY. "
|
|
51
|
+
"Create one in the Runara console under Settings."
|
|
52
|
+
)
|
|
53
|
+
self.api_key = key
|
|
54
|
+
self.base_url = (base_url or os.environ.get("RUNARA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
|
|
55
|
+
|
|
56
|
+
# -- catalog -----------------------------------------------------------
|
|
57
|
+
|
|
58
|
+
def list_models(self) -> list[ModelInfo]:
|
|
59
|
+
"""Base models open for training, with their per-token prices.
|
|
60
|
+
|
|
61
|
+
A fixed catalog rather than any HuggingFace id: the weights have to be
|
|
62
|
+
already resident on a worker for sessions to share them, which is what
|
|
63
|
+
makes per-token pricing possible at all.
|
|
64
|
+
"""
|
|
65
|
+
body = self._control("GET", "/finetune/models")
|
|
66
|
+
return [
|
|
67
|
+
ModelInfo(
|
|
68
|
+
base_model=row["base_model"],
|
|
69
|
+
repository=row["repository"],
|
|
70
|
+
max_rank=row["max_rank"],
|
|
71
|
+
max_seq_len=row["max_seq_len"],
|
|
72
|
+
default_target_modules=row["default_target_modules"],
|
|
73
|
+
train_usd_per_million=row["train_usd_per_million"],
|
|
74
|
+
sample_usd_per_million=row["sample_usd_per_million"],
|
|
75
|
+
)
|
|
76
|
+
for row in body["data"]
|
|
77
|
+
]
|
|
78
|
+
|
|
79
|
+
def list_checkpoints(self, base_model: str | None = None) -> list[Checkpoint]:
|
|
80
|
+
path = "/finetune/checkpoints"
|
|
81
|
+
if base_model:
|
|
82
|
+
path += f"?base_model={base_model}"
|
|
83
|
+
body = self._control("GET", path)
|
|
84
|
+
return [Checkpoint(**row) for row in body["data"]]
|
|
85
|
+
|
|
86
|
+
# -- sessions ----------------------------------------------------------
|
|
87
|
+
|
|
88
|
+
def create_lora_training_client(
|
|
89
|
+
self,
|
|
90
|
+
base_model: str,
|
|
91
|
+
rank: int = 32,
|
|
92
|
+
*,
|
|
93
|
+
alpha: int | None = None,
|
|
94
|
+
target_modules: list[str] | None = None,
|
|
95
|
+
method: str = "lora",
|
|
96
|
+
request_id: str | None = None,
|
|
97
|
+
) -> "TrainingClient":
|
|
98
|
+
"""Open a session and get a client for it.
|
|
99
|
+
|
|
100
|
+
`request_id` makes this idempotent. One is generated if you do not
|
|
101
|
+
supply it, so a retry after a timeout returns the session you already
|
|
102
|
+
have rather than opening a second one you would also be billed for.
|
|
103
|
+
"""
|
|
104
|
+
payload = {
|
|
105
|
+
"request_id": request_id or f"sdk-{uuid.uuid4().hex}",
|
|
106
|
+
"base_model": base_model,
|
|
107
|
+
"rank": rank,
|
|
108
|
+
"method": method,
|
|
109
|
+
}
|
|
110
|
+
if alpha is not None:
|
|
111
|
+
payload["alpha"] = alpha
|
|
112
|
+
if target_modules is not None:
|
|
113
|
+
payload["target_modules"] = target_modules
|
|
114
|
+
|
|
115
|
+
body = self._control("POST", "/finetune/sessions", payload)
|
|
116
|
+
return TrainingClient(
|
|
117
|
+
service=self,
|
|
118
|
+
session_id=body["session_id"],
|
|
119
|
+
worker_url=body["worker_url"].rstrip("/"),
|
|
120
|
+
token=body["session_token"],
|
|
121
|
+
token_expires_at=body["expires_at"],
|
|
122
|
+
# The worker is rented for minutes at an address nobody owns, so
|
|
123
|
+
# there is no public certificate for it. The control plane, which
|
|
124
|
+
# we authenticate normally, tells us exactly which certificate it
|
|
125
|
+
# will present; we trust that one and refuse anything else.
|
|
126
|
+
worker_cert_pem=body["worker_cert_pem"],
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
# -- plumbing ----------------------------------------------------------
|
|
130
|
+
|
|
131
|
+
def _control(self, method: str, path: str, body: dict | None = None):
|
|
132
|
+
# The control plane is retried: these calls are rare, and the one that
|
|
133
|
+
# mutates anything is idempotent on request_id.
|
|
134
|
+
return _http.request(
|
|
135
|
+
method, self.base_url + path, self.api_key, body, timeout=60.0, retries=2
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
@dataclass
|
|
140
|
+
class _SessionToken:
|
|
141
|
+
value: str
|
|
142
|
+
expires_at: int
|
|
143
|
+
|
|
144
|
+
def stale(self, now_ms: float) -> bool:
|
|
145
|
+
return self.expires_at - now_ms < TOKEN_REFRESH_MARGIN_SECONDS * 1000
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
class TrainingClient:
|
|
149
|
+
"""One training session. The four primitives, and the loop is yours."""
|
|
150
|
+
|
|
151
|
+
def __init__(
|
|
152
|
+
self,
|
|
153
|
+
service: ServiceClient,
|
|
154
|
+
session_id: str,
|
|
155
|
+
worker_url: str,
|
|
156
|
+
token: str,
|
|
157
|
+
token_expires_at: int,
|
|
158
|
+
worker_cert_pem: str,
|
|
159
|
+
) -> None:
|
|
160
|
+
self.service = service
|
|
161
|
+
self.session_id = session_id
|
|
162
|
+
if not worker_url.startswith("https://"):
|
|
163
|
+
# Never negotiable. This connection carries the customer's
|
|
164
|
+
# training tokens, and a plaintext worker_url would hand them to
|
|
165
|
+
# anyone on the path while everything still appeared to work.
|
|
166
|
+
raise ValueError(f"worker_url must be https, got {worker_url!r}")
|
|
167
|
+
self.worker_url = worker_url
|
|
168
|
+
self._token = _SessionToken(token, token_expires_at)
|
|
169
|
+
self._pinned = _http._PinnedWorker(worker_cert_pem)
|
|
170
|
+
self._submitter = Submitter()
|
|
171
|
+
|
|
172
|
+
# -- the primitives ----------------------------------------------------
|
|
173
|
+
|
|
174
|
+
def forward_backward(
|
|
175
|
+
self, data: list[Datum], loss_fn: str = "cross_entropy"
|
|
176
|
+
) -> Future[ForwardBackwardResult]:
|
|
177
|
+
"""Accumulate gradients for one batch. Returns immediately.
|
|
178
|
+
|
|
179
|
+
Submit this and `optim_step` back to back without awaiting: the worker
|
|
180
|
+
applies calls for a session in the order they arrive, so the network
|
|
181
|
+
round trip overlaps your next batch of tokenization instead of
|
|
182
|
+
stalling the GPU.
|
|
183
|
+
"""
|
|
184
|
+
payload = {"data": [datum.to_wire() for datum in data], "loss_fn": loss_fn}
|
|
185
|
+
|
|
186
|
+
def run() -> ForwardBackwardResult:
|
|
187
|
+
body = self._call("forward_backward", payload)
|
|
188
|
+
return ForwardBackwardResult(
|
|
189
|
+
loss=body["loss"],
|
|
190
|
+
metrics=body.get("metrics", {}),
|
|
191
|
+
seq_count=body.get("seq_count", len(data)),
|
|
192
|
+
token_count=body.get("token_count", 0),
|
|
193
|
+
)
|
|
194
|
+
|
|
195
|
+
return self._submitter.submit(run)
|
|
196
|
+
|
|
197
|
+
def optim_step(self, params: AdamParams) -> Future[int]:
|
|
198
|
+
"""Apply the accumulated gradients. Returns the new step number."""
|
|
199
|
+
|
|
200
|
+
def run() -> int:
|
|
201
|
+
return self._call("optim_step", {"adam": params.to_wire()})["step"]
|
|
202
|
+
|
|
203
|
+
return self._submitter.submit(run)
|
|
204
|
+
|
|
205
|
+
def sample(
|
|
206
|
+
self,
|
|
207
|
+
prompts: list[list[int]],
|
|
208
|
+
max_tokens: int = 64,
|
|
209
|
+
temperature: float = 1.0,
|
|
210
|
+
) -> Future[SampleResult]:
|
|
211
|
+
"""Generate from the adapter as it stands, without ending the session."""
|
|
212
|
+
|
|
213
|
+
def run() -> SampleResult:
|
|
214
|
+
body = self._call(
|
|
215
|
+
"sample",
|
|
216
|
+
{"prompts": prompts, "max_tokens": max_tokens, "temperature": temperature},
|
|
217
|
+
)
|
|
218
|
+
return SampleResult(
|
|
219
|
+
sequences=body["sequences"], token_count=body.get("token_count", 0)
|
|
220
|
+
)
|
|
221
|
+
|
|
222
|
+
return self._submitter.submit(run)
|
|
223
|
+
|
|
224
|
+
def save_state(self, name: str) -> Future[dict]:
|
|
225
|
+
"""Save the adapter. Blocks on everything you submitted before it.
|
|
226
|
+
|
|
227
|
+
Ordering matters here more than anywhere: saving before your last
|
|
228
|
+
optim_step has been applied would write a checkpoint one step behind
|
|
229
|
+
what you think you trained. The worker's per-session ordering gives
|
|
230
|
+
that for free, which is why this goes through the same queue.
|
|
231
|
+
"""
|
|
232
|
+
|
|
233
|
+
def run() -> dict:
|
|
234
|
+
return self._call("save_state", {"name": name})
|
|
235
|
+
|
|
236
|
+
return self._submitter.submit(run)
|
|
237
|
+
|
|
238
|
+
# -- session -----------------------------------------------------------
|
|
239
|
+
|
|
240
|
+
def status(self) -> dict:
|
|
241
|
+
return self.service._control("GET", f"/finetune/sessions/{self.session_id}")
|
|
242
|
+
|
|
243
|
+
def close(self) -> None:
|
|
244
|
+
"""End the session and release its slot on the worker.
|
|
245
|
+
|
|
246
|
+
Worth doing explicitly: an abandoned session holds an adapter slot
|
|
247
|
+
until the watchdog reclaims it half an hour later.
|
|
248
|
+
"""
|
|
249
|
+
try:
|
|
250
|
+
self.service._control("DELETE", f"/finetune/sessions/{self.session_id}")
|
|
251
|
+
finally:
|
|
252
|
+
self._submitter.close()
|
|
253
|
+
# The pinned certificate lives in a temp file; remove it.
|
|
254
|
+
self._pinned.close()
|
|
255
|
+
|
|
256
|
+
def __enter__(self) -> "TrainingClient":
|
|
257
|
+
return self
|
|
258
|
+
|
|
259
|
+
def __exit__(self, *_exc) -> None:
|
|
260
|
+
self.close()
|
|
261
|
+
|
|
262
|
+
# -- plumbing ----------------------------------------------------------
|
|
263
|
+
|
|
264
|
+
def _call(self, action: str, payload: dict) -> dict:
|
|
265
|
+
token = self._fresh_token()
|
|
266
|
+
# retries=0: a forward_backward that timed out may already have applied
|
|
267
|
+
# its gradients, and sending it again would train on the batch twice.
|
|
268
|
+
return _http.request(
|
|
269
|
+
"POST",
|
|
270
|
+
f"{self.worker_url}/v1/sessions/{self.session_id}/{action}",
|
|
271
|
+
token,
|
|
272
|
+
payload,
|
|
273
|
+
retries=0,
|
|
274
|
+
ssl_context=self._pinned.context,
|
|
275
|
+
)
|
|
276
|
+
|
|
277
|
+
def _fresh_token(self) -> str:
|
|
278
|
+
if not self._token.stale(time.time() * 1000):
|
|
279
|
+
return self._token.value
|
|
280
|
+
body = self.service._control(
|
|
281
|
+
"POST", f"/finetune/sessions/{self.session_id}/token"
|
|
282
|
+
)
|
|
283
|
+
self._token = _SessionToken(body["session_token"], body["expires_at"])
|
|
284
|
+
# The worker can move between refreshes in principle; follow it.
|
|
285
|
+
self.worker_url = body.get("worker_url", self.worker_url).rstrip("/")
|
|
286
|
+
return self._token.value
|
runara/types.py
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""The wire types.
|
|
2
|
+
|
|
3
|
+
A ``Datum`` is the whole of what leaves your machine for a training call:
|
|
4
|
+
token ids and a per-token loss weight. Not your text, not your filenames, not
|
|
5
|
+
your dataset. The cookbook builds these locally from whatever you have, and
|
|
6
|
+
you can print one before sending it.
|
|
7
|
+
|
|
8
|
+
The alignment convention is the part worth reading twice. ``token_ids`` is the
|
|
9
|
+
input and ``target_tokens`` is what the model should predict at each position,
|
|
10
|
+
already shifted so that position *i* of one lines up with position *i* of the
|
|
11
|
+
other. The cookbook does that shift for you. If you build data by hand and get
|
|
12
|
+
it wrong, nothing errors: the model trains toward the wrong token and the loss
|
|
13
|
+
curve looks entirely normal.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from dataclasses import dataclass, field
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class Datum:
|
|
23
|
+
"""One training example."""
|
|
24
|
+
|
|
25
|
+
token_ids: list[int]
|
|
26
|
+
target_tokens: list[int]
|
|
27
|
+
#: 1.0 for a token to train on, 0.0 to ignore. Prompt tokens are usually 0.
|
|
28
|
+
weights: list[float]
|
|
29
|
+
|
|
30
|
+
def __post_init__(self) -> None:
|
|
31
|
+
if not self.token_ids:
|
|
32
|
+
raise ValueError("Datum has no tokens")
|
|
33
|
+
if not (len(self.token_ids) == len(self.target_tokens) == len(self.weights)):
|
|
34
|
+
raise ValueError(
|
|
35
|
+
"token_ids, target_tokens and weights must be the same length; "
|
|
36
|
+
f"got {len(self.token_ids)}, {len(self.target_tokens)}, {len(self.weights)}. "
|
|
37
|
+
"They describe the same positions, already shifted."
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
@property
|
|
41
|
+
def trained_tokens(self) -> int:
|
|
42
|
+
"""Tokens that carry loss. This is what you are billed for."""
|
|
43
|
+
return sum(1 for weight in self.weights if weight > 0)
|
|
44
|
+
|
|
45
|
+
def to_wire(self) -> dict:
|
|
46
|
+
return {
|
|
47
|
+
"token_ids": self.token_ids,
|
|
48
|
+
"target_tokens": self.target_tokens,
|
|
49
|
+
"weights": self.weights,
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@dataclass(frozen=True)
|
|
54
|
+
class AdamParams:
|
|
55
|
+
"""Optimizer settings for one step. The schedule is yours to decide."""
|
|
56
|
+
|
|
57
|
+
learning_rate: float
|
|
58
|
+
beta1: float = 0.9
|
|
59
|
+
beta2: float = 0.95
|
|
60
|
+
eps: float = 1e-8
|
|
61
|
+
weight_decay: float = 0.0
|
|
62
|
+
|
|
63
|
+
def to_wire(self) -> dict:
|
|
64
|
+
return {
|
|
65
|
+
"learning_rate": self.learning_rate,
|
|
66
|
+
"beta1": self.beta1,
|
|
67
|
+
"beta2": self.beta2,
|
|
68
|
+
"eps": self.eps,
|
|
69
|
+
"weight_decay": self.weight_decay,
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@dataclass(frozen=True)
|
|
74
|
+
class ForwardBackwardResult:
|
|
75
|
+
loss: float
|
|
76
|
+
metrics: dict
|
|
77
|
+
seq_count: int
|
|
78
|
+
#: Trained tokens in this batch — the billable quantity.
|
|
79
|
+
token_count: int
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
@dataclass(frozen=True)
|
|
83
|
+
class SampleResult:
|
|
84
|
+
sequences: list[list[int]]
|
|
85
|
+
token_count: int
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
@dataclass(frozen=True)
|
|
89
|
+
class Checkpoint:
|
|
90
|
+
checkpoint_id: str
|
|
91
|
+
name: str
|
|
92
|
+
kind: str
|
|
93
|
+
step: int
|
|
94
|
+
base_model: str
|
|
95
|
+
base_model_repository: str
|
|
96
|
+
rank: int
|
|
97
|
+
size_bytes: int
|
|
98
|
+
files: list[dict] = field(default_factory=list)
|
|
99
|
+
created_at: int = 0
|
|
100
|
+
expires_at: int | None = None
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
@dataclass(frozen=True)
|
|
104
|
+
class ModelInfo:
|
|
105
|
+
base_model: str
|
|
106
|
+
repository: str
|
|
107
|
+
max_rank: int
|
|
108
|
+
max_seq_len: int
|
|
109
|
+
default_target_modules: list[str]
|
|
110
|
+
train_usd_per_million: float
|
|
111
|
+
sample_usd_per_million: float
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: runara
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Fine-tune open models on Runara. You write the training loop.
|
|
5
|
+
Author: Runara
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://runara.ai
|
|
8
|
+
Project-URL: Source, https://github.com/Runaraai/runara-python
|
|
9
|
+
Keywords: llm,fine-tuning,lora,training
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
14
|
+
Requires-Python: >=3.10
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
Provides-Extra: cookbook
|
|
17
|
+
Requires-Dist: transformers>=4.45; extra == "cookbook"
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
20
|
+
|
|
21
|
+
# runara
|
|
22
|
+
|
|
23
|
+
Fine-tune open models without hosting them. You write the training loop; we
|
|
24
|
+
hold the base weights and run the forward and backward passes.
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install runara runara-cookbook
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
import runara
|
|
32
|
+
from runara_cookbook import renderers
|
|
33
|
+
|
|
34
|
+
sc = runara.ServiceClient(api_key="rk_live_...")
|
|
35
|
+
tc = sc.create_lora_training_client(base_model="qwen3.5-4b", rank=32)
|
|
36
|
+
|
|
37
|
+
renderer = renderers.get("qwen3_5", tokenizer=tc.get_tokenizer())
|
|
38
|
+
rows = [json.loads(line) for line in open("my_tickets.jsonl")] # your disk
|
|
39
|
+
|
|
40
|
+
for epoch in range(3):
|
|
41
|
+
for chunk in batches(rows, 8):
|
|
42
|
+
data = [renderer.to_datum(row["messages"]) for row in chunk]
|
|
43
|
+
fb = tc.forward_backward(data) # submitted, not awaited
|
|
44
|
+
tc.optim_step(runara.AdamParams(1e-4)) # submitted straight after
|
|
45
|
+
print(fb.result().loss) # the loop blocks here
|
|
46
|
+
|
|
47
|
+
tc.save_state(name="support-v1")
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Your data does not leave your machine
|
|
51
|
+
|
|
52
|
+
`open(...)` runs on your computer. The cookbook tokenizes locally and builds a
|
|
53
|
+
per-token loss mask, so what crosses the wire is a list of integers and a list
|
|
54
|
+
of floats — no text, no filenames, no schema. A two-turn conversation is about
|
|
55
|
+
900 bytes of that.
|
|
56
|
+
|
|
57
|
+
You can check this yourself before sending anything:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
datum = renderer.to_datum(messages)
|
|
61
|
+
print(datum.token_ids) # integers
|
|
62
|
+
print(datum.weights) # 0.0 for the prompt, 1.0 for what you train on
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
What we do keep is the adapter you write with `save_state`, plus token counts
|
|
66
|
+
and loss values for billing and the charts in the console.
|
|
67
|
+
|
|
68
|
+
## Why the loop is yours
|
|
69
|
+
|
|
70
|
+
There is no job to submit and no config to fill in. You decide the batching,
|
|
71
|
+
the schedule, when to stop, and what the loss means. That is more work than a
|
|
72
|
+
managed API and it is the point: it is the difference between tuning a model
|
|
73
|
+
and filling in a form.
|
|
74
|
+
|
|
75
|
+
`forward_backward` and `optim_step` both return immediately. Submit them back
|
|
76
|
+
to back and collect later — the worker applies calls for a session in the
|
|
77
|
+
order they arrive, so the round trip overlaps your next batch of tokenization
|
|
78
|
+
instead of stalling the GPU.
|
|
79
|
+
|
|
80
|
+
## What you get out
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
for checkpoint in sc.list_checkpoints():
|
|
84
|
+
print(checkpoint.name, checkpoint.size_bytes, checkpoint.base_model)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Checkpoints are standard PEFT adapters — `adapter_config.json` and
|
|
88
|
+
`adapter_model.safetensors` — so they load in vLLM, SGLang or transformers
|
|
89
|
+
without conversion. Download them from the console, or serve them on Runara
|
|
90
|
+
alongside the base model.
|
|
91
|
+
|
|
92
|
+
## Errors worth catching
|
|
93
|
+
|
|
94
|
+
| | |
|
|
95
|
+
|---|---|
|
|
96
|
+
| `runara.InsufficientBalance` | The organization is out of credit. |
|
|
97
|
+
| `runara.SessionClosed` | The session ended, or is ending because the balance ran out. |
|
|
98
|
+
| `runara.RunaraError` | Everything else, with `.status` and `.code`. |
|
|
99
|
+
|
|
100
|
+
A training call is never retried automatically. One that timed out may already
|
|
101
|
+
have applied its gradients, and sending it again would train on the same batch
|
|
102
|
+
twice.
|
|
103
|
+
|
|
104
|
+
## Checked against the reference
|
|
105
|
+
|
|
106
|
+
The renderers are verified to produce byte-identical tokens, targets and loss
|
|
107
|
+
masks to `tinker-cookbook` for the same conversation and tokenizer. Chat
|
|
108
|
+
templating is the part of fine-tuning that goes wrong silently, so it is
|
|
109
|
+
checked against an independent implementation rather than only against itself.
|
|
110
|
+
|
|
111
|
+
## Installing
|
|
112
|
+
|
|
113
|
+
The client has no dependencies at all — it is stdlib, so installing it cannot
|
|
114
|
+
conflict with whatever `torch`, `transformers` or `numpy` versions your
|
|
115
|
+
training code already pins. The heavy dependencies live in `runara-cookbook`.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
runara/__init__.py,sha256=vWCwHRD9i8ExBjoY2EKDH_vt685LDOxZpoBjBLEKMVE,939
|
|
2
|
+
runara/_futures.py,sha256=LocdNSqEGAb-gY6FeW5J7N8IEvOfUFysCPjO8g3Dv7g,2394
|
|
3
|
+
runara/_http.py,sha256=Q2x16Sybfrjxz-5DpNH9EyeaYw195cH4tzNtyO_sQ6A,6035
|
|
4
|
+
runara/client.py,sha256=p1oT8qmYtB_B2pURT4DAWi0NbqgnDNFFna4uHj1_Iv4,10604
|
|
5
|
+
runara/types.py,sha256=Lrc4d3HjaO9eSBjLrQP52y98526p60SJPsXgyc9MMTM,3206
|
|
6
|
+
runara_cookbook/__init__.py,sha256=5R4tThzuaCZQWW05iQacr365aU7jnFpu1j5AQ2J0GO0,357
|
|
7
|
+
runara_cookbook/data.py,sha256=8wlWJp12Gg_DfZ5u_HB7eD2JTFfB4-TzrHbUxVDhpUg,3322
|
|
8
|
+
runara_cookbook/renderers/__init__.py,sha256=T46yfddq5e2jImr-1DAo8zF3bZ4UbDgUuPnzAFI_1XQ,1462
|
|
9
|
+
runara_cookbook/renderers/base.py,sha256=Gs1GgLcHvgd8ZXYajGlFBbBjzp9iuidmogvneKz5sr8,8460
|
|
10
|
+
runara-0.1.0.dist-info/METADATA,sha256=PkIgngt9Dg6uAYXNtmg3mAPeyy2wgKSOlIm78Li-ltA,4276
|
|
11
|
+
runara-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
12
|
+
runara-0.1.0.dist-info/top_level.txt,sha256=JWRLhgKrXdMvtrLSXitBlr_-9PbMN4FNA-EJS7zwzkQ,23
|
|
13
|
+
runara-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Helpers for fine-tuning on Runara: chat templates, data loading, batching.
|
|
2
|
+
|
|
3
|
+
Open source on purpose. This is the code that decides what your tokens look
|
|
4
|
+
like before they are sent, so it should be code you can read.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from . import data, renderers
|
|
8
|
+
from .renderers import TrainOnWhat
|
|
9
|
+
|
|
10
|
+
__version__ = "0.1.0"
|
|
11
|
+
__all__ = ["data", "renderers", "TrainOnWhat"]
|
runara_cookbook/data.py
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"""Reading your data, on your machine.
|
|
2
|
+
|
|
3
|
+
Nothing here talks to Runara. These helpers open files you already have and
|
|
4
|
+
hand the rows to a renderer; what leaves your machine is whatever the renderer
|
|
5
|
+
produced, which is token ids and floats.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
import random
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from typing import Iterator, Sequence
|
|
14
|
+
|
|
15
|
+
from runara.types import Datum
|
|
16
|
+
|
|
17
|
+
from .renderers.base import Message, Renderer, TrainOnWhat
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def read_jsonl(path: str | Path) -> list[dict]:
|
|
21
|
+
"""Read a JSONL file from your disk. One JSON object per line."""
|
|
22
|
+
rows: list[dict] = []
|
|
23
|
+
with Path(path).open() as handle:
|
|
24
|
+
for number, line in enumerate(handle, start=1):
|
|
25
|
+
line = line.strip()
|
|
26
|
+
if not line:
|
|
27
|
+
continue
|
|
28
|
+
try:
|
|
29
|
+
rows.append(json.loads(line))
|
|
30
|
+
except json.JSONDecodeError as error:
|
|
31
|
+
# Name the line rather than the content: an error message is a
|
|
32
|
+
# place training data leaks into logs by accident.
|
|
33
|
+
raise ValueError(f"{path} line {number} is not valid JSON") from error
|
|
34
|
+
if not rows:
|
|
35
|
+
raise ValueError(f"{path} has no rows")
|
|
36
|
+
return rows
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def conversations(rows: Sequence[dict], key: str = "messages") -> list[list[Message]]:
|
|
40
|
+
"""Pull the chat turns out of raw rows, checking the shape once up front."""
|
|
41
|
+
out: list[list[Message]] = []
|
|
42
|
+
for index, row in enumerate(rows):
|
|
43
|
+
messages = row.get(key)
|
|
44
|
+
if not isinstance(messages, list) or not messages:
|
|
45
|
+
raise ValueError(f"row {index} has no {key!r} list")
|
|
46
|
+
for message in messages:
|
|
47
|
+
if not isinstance(message, dict) or "role" not in message or "content" not in message:
|
|
48
|
+
raise ValueError(
|
|
49
|
+
f"row {index}: every message needs a 'role' and 'content'"
|
|
50
|
+
)
|
|
51
|
+
out.append(messages)
|
|
52
|
+
return out
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def build_data(
|
|
56
|
+
renderer: Renderer,
|
|
57
|
+
conversation_list: Sequence[Sequence[Message]],
|
|
58
|
+
train_on_what: TrainOnWhat = TrainOnWhat.LAST_ASSISTANT_MESSAGE,
|
|
59
|
+
max_tokens: int | None = None,
|
|
60
|
+
) -> list[Datum]:
|
|
61
|
+
"""Render every conversation into a Datum, dropping ones that are too long.
|
|
62
|
+
|
|
63
|
+
Dropped rather than truncated: a truncated conversation ends mid-sentence,
|
|
64
|
+
and training the model to stop there teaches it to do the same.
|
|
65
|
+
"""
|
|
66
|
+
data: list[Datum] = []
|
|
67
|
+
for messages in conversation_list:
|
|
68
|
+
rendered = renderer.build_supervised_example(messages, train_on_what)
|
|
69
|
+
if max_tokens is not None and len(rendered.tokens) > max_tokens:
|
|
70
|
+
continue
|
|
71
|
+
data.append(renderer.to_datum(messages, train_on_what))
|
|
72
|
+
return data
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def batches(items: Sequence[Datum], size: int, shuffle: bool = False, seed: int = 0) -> Iterator[list[Datum]]:
|
|
76
|
+
"""Yield fixed-size batches. The last one may be smaller."""
|
|
77
|
+
if size < 1:
|
|
78
|
+
raise ValueError("batch size must be at least 1")
|
|
79
|
+
order = list(range(len(items)))
|
|
80
|
+
if shuffle:
|
|
81
|
+
random.Random(seed).shuffle(order)
|
|
82
|
+
for start in range(0, len(order), size):
|
|
83
|
+
yield [items[index] for index in order[start : start + size]]
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def token_count(data: Sequence[Datum]) -> int:
|
|
87
|
+
"""Trained tokens across a dataset — what one epoch will cost."""
|
|
88
|
+
return sum(datum.trained_tokens for datum in data)
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""Chat templates per model family.
|
|
2
|
+
|
|
3
|
+
Pick the renderer that matches your base model. Using the wrong one trains on
|
|
4
|
+
a format the model is never prompted with at inference, which costs quality
|
|
5
|
+
with no error and nothing in the loss curve to show for it.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from .base import (
|
|
11
|
+
Message,
|
|
12
|
+
RenderedExample,
|
|
13
|
+
Renderer,
|
|
14
|
+
Tokenizer,
|
|
15
|
+
TrainOnWhat,
|
|
16
|
+
to_datum,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
#: Families whose chat template the base Renderer handles directly. A family
|
|
20
|
+
#: that needs special handling gets its own subclass and an entry here.
|
|
21
|
+
_REGISTRY: dict[str, type[Renderer]] = {
|
|
22
|
+
"qwen3": Renderer,
|
|
23
|
+
"qwen3_5": Renderer,
|
|
24
|
+
"llama3": Renderer,
|
|
25
|
+
"generic": Renderer,
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def get(name: str, tokenizer: Tokenizer) -> Renderer:
|
|
30
|
+
"""Build the renderer for a model family."""
|
|
31
|
+
try:
|
|
32
|
+
cls = _REGISTRY[name]
|
|
33
|
+
except KeyError:
|
|
34
|
+
raise ValueError(
|
|
35
|
+
f"No renderer named {name!r}. Available: {', '.join(sorted(_REGISTRY))}. "
|
|
36
|
+
"Use 'generic' if your tokenizer carries its own chat template."
|
|
37
|
+
) from None
|
|
38
|
+
return cls(tokenizer)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def register(name: str, cls: type[Renderer]) -> None:
|
|
42
|
+
"""Add a renderer for a family we do not ship."""
|
|
43
|
+
_REGISTRY[name] = cls
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def available() -> list[str]:
|
|
47
|
+
return sorted(_REGISTRY)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
__all__ = [
|
|
51
|
+
"Message",
|
|
52
|
+
"RenderedExample",
|
|
53
|
+
"Renderer",
|
|
54
|
+
"Tokenizer",
|
|
55
|
+
"TrainOnWhat",
|
|
56
|
+
"available",
|
|
57
|
+
"get",
|
|
58
|
+
"register",
|
|
59
|
+
"to_datum",
|
|
60
|
+
]
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
"""Turning a conversation into tokens and a loss mask.
|
|
2
|
+
|
|
3
|
+
This is the part of fine-tuning that is easy to get wrong and never tells you.
|
|
4
|
+
Two mistakes in particular:
|
|
5
|
+
|
|
6
|
+
**The shift.** A language model predicts the *next* token, so the targets are
|
|
7
|
+
the inputs moved along by one. `to_datum` does that once, correctly. Doing it
|
|
8
|
+
twice — or not at all — trains the model toward the wrong position, and the
|
|
9
|
+
loss still falls, just toward something useless.
|
|
10
|
+
|
|
11
|
+
**The template.** Every model family wraps a conversation in its own control
|
|
12
|
+
tokens, and training on a format the model does not see at inference quietly
|
|
13
|
+
costs you quality. Which is why the renderer builds the same token sequence
|
|
14
|
+
the model will actually be prompted with, rather than something close to it.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from dataclasses import dataclass
|
|
20
|
+
from enum import Enum
|
|
21
|
+
from typing import Protocol, Sequence
|
|
22
|
+
|
|
23
|
+
from runara.types import Datum
|
|
24
|
+
|
|
25
|
+
Message = dict # {"role": "user" | "assistant" | "system", "content": str}
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class TrainOnWhat(str, Enum):
|
|
29
|
+
"""Which tokens carry loss.
|
|
30
|
+
|
|
31
|
+
The default trains on the last assistant message only, which is what you
|
|
32
|
+
want for most supervised fine-tuning: you are teaching the model to answer,
|
|
33
|
+
not to produce the questions it was asked.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
LAST_ASSISTANT_MESSAGE = "last_assistant_message"
|
|
37
|
+
ALL_ASSISTANT_MESSAGES = "all_assistant_messages"
|
|
38
|
+
ALL_TOKENS = "all_tokens"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True)
|
|
42
|
+
class RenderedExample:
|
|
43
|
+
"""Tokens and their per-token weights, before the shift."""
|
|
44
|
+
|
|
45
|
+
tokens: list[int]
|
|
46
|
+
weights: list[float]
|
|
47
|
+
|
|
48
|
+
def __post_init__(self) -> None:
|
|
49
|
+
if len(self.tokens) != len(self.weights):
|
|
50
|
+
raise ValueError(
|
|
51
|
+
f"tokens and weights must be the same length; "
|
|
52
|
+
f"got {len(self.tokens)} and {len(self.weights)}"
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def to_datum(rendered: RenderedExample) -> Datum:
|
|
57
|
+
"""Shift once, and only once.
|
|
58
|
+
|
|
59
|
+
`token_ids[i]` is the input at position *i*; `target_tokens[i]` is what the
|
|
60
|
+
model should produce there. Because a model predicts the next token, that
|
|
61
|
+
target is the *following* token of the original sequence — so inputs drop
|
|
62
|
+
the last token and targets drop the first.
|
|
63
|
+
|
|
64
|
+
The weights follow the targets, not the inputs: a weight says "score the
|
|
65
|
+
prediction at this position", and the prediction being scored at position
|
|
66
|
+
*i* is of the original token *i+1*. Using `weights[:-1]` instead would
|
|
67
|
+
shift the mask one place against the targets, so the model would be
|
|
68
|
+
trained on the prompt's final token and not on the answer's final token —
|
|
69
|
+
an error of exactly one position, with no symptom at all.
|
|
70
|
+
"""
|
|
71
|
+
if len(rendered.tokens) < 2:
|
|
72
|
+
raise ValueError("need at least two tokens to form an input and a target")
|
|
73
|
+
return Datum(
|
|
74
|
+
token_ids=rendered.tokens[:-1],
|
|
75
|
+
target_tokens=rendered.tokens[1:],
|
|
76
|
+
weights=rendered.weights[1:],
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class Tokenizer(Protocol):
|
|
81
|
+
"""The slice of a HuggingFace tokenizer a renderer needs."""
|
|
82
|
+
|
|
83
|
+
def encode(self, text: str, add_special_tokens: bool = ...) -> list[int]: ...
|
|
84
|
+
|
|
85
|
+
def apply_chat_template(
|
|
86
|
+
self, conversation: Sequence[Message], tokenize: bool = ..., **kwargs
|
|
87
|
+
) -> str: ...
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class Renderer:
|
|
91
|
+
"""Base class. A family-specific renderer overrides the template calls."""
|
|
92
|
+
|
|
93
|
+
def __init__(self, tokenizer: Tokenizer) -> None:
|
|
94
|
+
self.tokenizer = tokenizer
|
|
95
|
+
|
|
96
|
+
# -- what subclasses provide ------------------------------------------
|
|
97
|
+
|
|
98
|
+
def render_prefix(self, messages: Sequence[Message]) -> str:
|
|
99
|
+
"""The prompt text the model would be given for these messages."""
|
|
100
|
+
return self.tokenizer.apply_chat_template(
|
|
101
|
+
list(messages), tokenize=False, add_generation_prompt=True
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
def render_full(self, messages: Sequence[Message]) -> str:
|
|
105
|
+
"""The whole conversation, including the final answer."""
|
|
106
|
+
return self.tokenizer.apply_chat_template(list(messages), tokenize=False)
|
|
107
|
+
|
|
108
|
+
# -- the usable surface ------------------------------------------------
|
|
109
|
+
|
|
110
|
+
def build_supervised_example(
|
|
111
|
+
self,
|
|
112
|
+
messages: Sequence[Message],
|
|
113
|
+
train_on_what: TrainOnWhat = TrainOnWhat.LAST_ASSISTANT_MESSAGE,
|
|
114
|
+
) -> RenderedExample:
|
|
115
|
+
"""Tokens plus a 0/1 mask, in the format this model is served in."""
|
|
116
|
+
if not messages:
|
|
117
|
+
raise ValueError("no messages to render")
|
|
118
|
+
|
|
119
|
+
if train_on_what is TrainOnWhat.ALL_TOKENS:
|
|
120
|
+
tokens = self.tokenizer.encode(
|
|
121
|
+
self.render_full(messages), add_special_tokens=False
|
|
122
|
+
)
|
|
123
|
+
return RenderedExample(tokens, [1.0] * len(tokens))
|
|
124
|
+
|
|
125
|
+
if train_on_what is TrainOnWhat.ALL_ASSISTANT_MESSAGES:
|
|
126
|
+
return self._mask_each_assistant_turn(messages)
|
|
127
|
+
|
|
128
|
+
return self._mask_final_answer(messages)
|
|
129
|
+
|
|
130
|
+
def to_datum(
|
|
131
|
+
self,
|
|
132
|
+
messages: Sequence[Message],
|
|
133
|
+
train_on_what: TrainOnWhat = TrainOnWhat.LAST_ASSISTANT_MESSAGE,
|
|
134
|
+
) -> Datum:
|
|
135
|
+
"""Render and shift in one call. What you send to `forward_backward`."""
|
|
136
|
+
return to_datum(self.build_supervised_example(messages, train_on_what))
|
|
137
|
+
|
|
138
|
+
# -- masking -----------------------------------------------------------
|
|
139
|
+
|
|
140
|
+
def _mask_final_answer(self, messages: Sequence[Message]) -> RenderedExample:
|
|
141
|
+
"""Train on the last message only, with everything before it masked.
|
|
142
|
+
|
|
143
|
+
The split is done on *text* and then tokenized separately, rather than
|
|
144
|
+
tokenizing once and guessing a boundary. Guessing is where off-by-one
|
|
145
|
+
mask errors come from, and they are invisible: the model simply learns
|
|
146
|
+
a little of the prompt along with the answer.
|
|
147
|
+
"""
|
|
148
|
+
prefix_text = self.render_prefix(messages[:-1])
|
|
149
|
+
full_text = self.render_full(messages)
|
|
150
|
+
if not full_text.startswith(prefix_text):
|
|
151
|
+
raise ValueError(
|
|
152
|
+
"this model's chat template does not extend its own prompt; "
|
|
153
|
+
"the renderer for this family needs to override _mask_final_answer"
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
prompt = self.tokenizer.encode(prefix_text, add_special_tokens=False)
|
|
157
|
+
# Trailing whitespace is trimmed because chat templates append a
|
|
158
|
+
# newline after the stop token, and generation ends *at* the stop
|
|
159
|
+
# token. Training on what follows it spends signal teaching the model
|
|
160
|
+
# to emit something it will never be asked to produce. Verified
|
|
161
|
+
# against tinker-cookbook's qwen3 renderer, which trims the same token.
|
|
162
|
+
completion_text = full_text[len(prefix_text) :].rstrip()
|
|
163
|
+
completion = self.tokenizer.encode(completion_text, add_special_tokens=False)
|
|
164
|
+
if not completion:
|
|
165
|
+
raise ValueError("the final message rendered to no tokens")
|
|
166
|
+
|
|
167
|
+
return RenderedExample(
|
|
168
|
+
tokens=prompt + completion,
|
|
169
|
+
weights=[0.0] * len(prompt) + [1.0] * len(completion),
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
def _mask_each_assistant_turn(self, messages: Sequence[Message]) -> RenderedExample:
|
|
173
|
+
"""Train on every assistant turn, masking user and system turns.
|
|
174
|
+
|
|
175
|
+
Boundaries come from rendering the conversation one message longer
|
|
176
|
+
each time and taking the difference. Using the *generation prompt* as
|
|
177
|
+
the running prefix instead looks natural and is wrong: after an
|
|
178
|
+
assistant turn it ends with a dangling header that the next render
|
|
179
|
+
does not extend, so the split silently stops lining up.
|
|
180
|
+
|
|
181
|
+
The assistant's own header falls inside the trained span here, unlike
|
|
182
|
+
the single-answer case which masks it. That is deliberate — across a
|
|
183
|
+
multi-turn conversation the model has to learn where its turns begin.
|
|
184
|
+
"""
|
|
185
|
+
tokens: list[int] = []
|
|
186
|
+
weights: list[float] = []
|
|
187
|
+
previous = ""
|
|
188
|
+
for index, message in enumerate(messages):
|
|
189
|
+
current = self.render_full(messages[: index + 1])
|
|
190
|
+
if not current.startswith(previous):
|
|
191
|
+
raise ValueError(
|
|
192
|
+
"this chat template does not extend its own output; "
|
|
193
|
+
"this family needs its own renderer"
|
|
194
|
+
)
|
|
195
|
+
chunk = self.tokenizer.encode(
|
|
196
|
+
current[len(previous) :], add_special_tokens=False
|
|
197
|
+
)
|
|
198
|
+
tokens.extend(chunk)
|
|
199
|
+
weights.extend(
|
|
200
|
+
[1.0 if message.get("role") == "assistant" else 0.0] * len(chunk)
|
|
201
|
+
)
|
|
202
|
+
previous = current
|
|
203
|
+
return RenderedExample(tokens, weights)
|