coreai_opt.palettization.config.VectorKMeansConfig¶
- class coreai_opt.palettization.config.VectorKMeansConfig[source]¶
Bases:
BaseModelK-means settings for vector palettization (
cluster_dim > 1).Vector palettization clusters each palettization block’s
cluster_dim-long weight vectors into2 ** n_bitscentroids with k-means. Each run seeds the centroids with k-means++, then runs Lloyd iterations (assign every vector to its nearest centroid, move each centroid to the mean of its vectors) until the block converges. These settings trade clustering quality for speed.Where clustering runs:
CUDA GPU: all blocks of a weight tensor are clustered together in one batch. Unweighted clustering (post-training palettization) uses flash-kmeans for the Lloyd iterations when it is installed, and otherwise a batched PyTorch loop. Sensitivity-weighted clustering (
calibration_mode()) always uses the PyTorch loop, because flash-kmeans has no per-point weights.CPU: scikit-learn, one block at a time. If scikit-learn is not installed, the batched PyTorch loop runs on CPU instead and a warning is issued; it gives the same results but is several times slower.
Every backend uses the same seeding, the same stopping rule, and a seed derived from each tensor’s contents, so results are reproducible across runs.
- n_local_trials¶
Number of candidate centroids sampled at each k-means++ seeding step. The candidate that most reduces the clustering error is kept.
1is standard k-means++. Larger values (“greedy” k-means++) usually give lower clustering error, and seeding time grows roughly in proportion.Noneuses scikit-learn’s default,2 + int(log(n_clusters)). Default:None.- Type:
int | None
- n_init¶
How many times k-means is run from scratch on each block, each time starting from a different set of initial centroids. Because the result depends on where k-means starts, more runs make it likelier to find a good one; the run with the lowest clustering error is kept. Time grows linearly with
n_init. Default: 5.- Type:
int
- max_iter¶
Maximum number of Lloyd iterations per run. Default: 300.
- Type:
int
- tol¶
Convergence tolerance. A block stops iterating once its clustering error (inertia) improves by less than
tol, or whenmax_iteris reached. Default:1e-4.- Type:
float
Example
>>> # Defaults: greedy k-means++, 5 runs, convergence-based stopping. >>> default = VectorKMeansConfig() >>> # Fast, approximate clustering, e.g. to check that a model exports. >>> fast = VectorKMeansConfig(n_local_trials=1, n_init=1, max_iter=1) >>> # More runs for a sensitive model. >>> thorough = VectorKMeansConfig(n_init=12)