Documentation
¶
Overview ¶
Package builtin is Hermod's built-in ML engine: datasets, training, versions and predictions in Hermod's own process, in pure Go, with no hermod-ml worker to run.
It speaks the worker's contract. Engine is an http.Handler that answers the worker's routes (ml/worker/hermod_ml/app.py) with the same JSON, and Client returns a pkg/ml/worker client that reaches it without a network, so everything Hermod builds on the worker (jobs, versions and going live, serving keys, quotas, retraining, the Collect Dataset sink, monitoring) works on it unchanged. A prediction does not go through JSON at all: the client's Local hands Predict to the ML service directly.
It trains the common cases: linear (ridge and logistic regression), random_forest, gradient_boosting and mlp (a small neural network) for classification and regression, auto among them, and recommendations (als and item_similarity). Everything else the worker trains (extra_trees, hist_gradient_boosting, xgboost, the PyTorch and Keras networks, custom scripts and recommendation scenarios) needs the worker, and is refused here with a message that says so.
Index ¶
- Constants
- Variables
- func Capabilities() worker.Capabilities
- func CloseBlobs(b Blobs) error
- type Blob
- type Blobs
- type Config
- type Engine
- func (e *Engine) Capabilities() worker.Capabilities
- func (e *Engine) Client() *worker.Client
- func (e *Engine) Close() error
- func (e *Engine) Predict(ctx context.Context, vhost, name, version string, rows []map[string]any) ([]map[string]any, error)
- func (e *Engine) Route(remote *worker.Client) *worker.Client
- func (e *Engine) ServeHTTP(w http.ResponseWriter, r *http.Request)
Constants ¶
const ( DefaultMaxTrainRows = 1_000_000 DefaultMaxUploadBytes = 200 << 20 )
Defaults of the configuration.
const NeedsWorker = "needs the hermod-ml worker"
NeedsWorker is the reason a worker-only algorithm, scenario or script is refused here.
Variables ¶
var ( ErrBlobNotFound = errors.New("blob not found") ErrBlobExists = errors.New("blob already exists") // ErrBlobTooLarge is a blob over what the store keeps in one: a dataset // sent in one piece too large, or a model too large to keep. ErrBlobTooLarge = errors.New("too large to keep") )
The errors a Blobs answers with.
Functions ¶
func Capabilities ¶
func Capabilities() worker.Capabilities
Capabilities is what the built-in engine trains, by itself.
func CloseBlobs ¶
CloseBlobs releases what a Blobs holds, if anything.
Types ¶
type Blobs ¶
type Blobs interface {
// Put stores data under key, replacing what was there; a reader sees
// the old blob or the new one.
Put(ctx context.Context, vhost, key string, data []byte) error
// Create stores data under key only if nothing is there yet, and
// returns ErrBlobExists otherwise.
Create(ctx context.Context, vhost, key string, data []byte) error
// Get returns the blob under key, or ErrBlobNotFound.
Get(ctx context.Context, vhost, key string) ([]byte, error)
// List returns the blobs whose key starts with prefix (ending in "/"),
// ordered by key, with their data when withData is set.
List(ctx context.Context, vhost, prefix string, withData bool) ([]Blob, error)
// Delete removes the blobs whose key starts with prefix (ending in "/")
// and returns how many there were.
Delete(ctx context.Context, vhost, prefix string) (int, error)
}
Blobs is where the engine keeps its datasets and model versions: named blobs per vhost, keyed by "/"-separated segments. Hermod keeps them in its metadata store, so every replica sees the same ones and they outlive a server's disk (internal/ml); DirBlobs keeps them in a directory, for a single server or a test.
The engine writes most blobs once under a fresh key (a dataset part, a version's artifact), claims version numbers with Create, and replaces only small pointers with Put, so it needs no transactions.
type Config ¶
type Config struct {
// Blobs keeps the datasets and model versions. Hermod gives the engine
// its metadata store, so every replica shares them; without one they
// are kept in Dir.
Blobs Blobs
// Dir keeps the datasets and model versions when Blobs is nil.
Dir string
// MaxTrainings is how many trainings run at once; another is refused as
// busy, as the worker refuses one.
MaxTrainings int
// MaxTrainRows is the most rows a training reads; a larger dataset is
// sampled down to it, with a warning on the version.
MaxTrainRows int
// Workers bounds the goroutines one training uses (a forest's trees).
Workers int
// MaxUploadBytes bounds a request body: an uploaded file, or rows.
MaxUploadBytes int64
}
Config is how the engine runs.
func ConfigFromEnv ¶
ConfigFromEnv reads the engine's settings: HERMOD_ML_BUILTIN (false turns the engine off; on otherwise), HERMOD_ML_BUILTIN_DIR (none by default: Hermod keeps the engine's data in its metadata store, and uses the directory only with a store that cannot), HERMOD_ML_BUILTIN_MAX_TRAININGS (default 1), HERMOD_ML_BUILTIN_MAX_ROWS (default 1,000,000) and HERMOD_ML_BUILTIN_THREADS (default: the CPUs Go may use). on is false when the engine is turned off.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the built-in engine. It is safe for concurrent use.
func (*Engine) Capabilities ¶
func (e *Engine) Capabilities() worker.Capabilities
Capabilities is what the engine trains, as the worker's capabilities route says it.
func (*Engine) Close ¶
Close releases the directory the engine opened, if it opened one. The engine must not be used after.
func (*Engine) Predict ¶
func (e *Engine) Predict(ctx context.Context, vhost, name, version string, rows []map[string]any) ([]map[string]any, error)
Predict scores rows with a version of a model, one prediction per row: {"label", "probability"} for a classifier (a whole-number label as a number), {"value"} for a regression, as the worker's serving answers. A missing or null number takes its training median; a value that is not a number for a number feature is refused, as the worker refuses it.
func (*Engine) Route ¶
Route returns a client of the engine and the hermod-ml worker remote together, as Hermod runs them: connecting or disconnecting the worker never changes which engine holds a model's versions.
- A version is served by the engine that trained it, which its id says (worker.IsBuiltinVersion).
- A training with a built-in algorithm runs in-process; one only the worker trains, and auto, run on the worker.
- Datasets are kept in the engine's store and copied to the worker when it trains on them; one only the worker has (from before the engine kept datasets) stays there and is listed beside the engine's.
With no worker it is the engine alone.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package learn holds the built-in ML engine's algorithms, in pure Go: ridge and logistic regression, a random forest, gradient-boosted trees and a small multilayer perceptron, over the same preprocessing the hermod-ml worker applies (ml/worker/hermod_ml/training.py build_pipeline): a missing number gets the training median, numbers are standardised for the linear model and the network, and text is one-hot encoded.
|
Package learn holds the built-in ML engine's algorithms, in pure Go: ridge and logistic regression, a random forest, gradient-boosted trees and a small multilayer perceptron, over the same preprocessing the hermod-ml worker applies (ml/worker/hermod_ml/training.py build_pipeline): a missing number gets the training median, numbers are standardised for the linear model and the network, and text is one-hot encoded. |
|
Package table is the built-in ML engine's dataset in memory: typed columns, read from JSON rows, CSV or Excel, with the hermod-ml worker's typing rules (ml/worker/hermod_ml/datasets.py), so the same file gives the same columns on either engine.
|
Package table is the built-in ML engine's dataset in memory: typed columns, read from JSON rows, CSV or Excel, with the hermod-ml worker's typing rules (ml/worker/hermod_ml/datasets.py), so the same file gives the same columns on either engine. |