26eac83f76
* feat(switch): model-default resolver + user-pinnable defaults
Add a two-layer default scheme on top of the existing <engine>/default map.
<engine>/default stays the maintainer's recommendation (read-only to users);
the new <model>/default is the user's preference — their .env pin if set,
else a curated pick for the detected topology.
compose_registry.py: two maintainer knobs next to DEFAULTS —
RECOMMENDED_DEFAULT_MODELS (short opt-in shortlist, not an exhaustive
ranking; new models are NOT auto-added) and ENGINE_PREFERENCE (per-topology
engine order). Plus resolver helpers (curated_default_target,
community_default_target stub, model_default_pin_key, engine_set/model_set,
slug_topology, model_of_slug).
registry-emit.sh: shared resolver model_default_target(root, model, topology)
— the single injection point for both launchers. Precedence ladder: --variant
(caller) -> .env pin -> community seam (None today) -> curated ENGINE_PREFERENCE
walk (skips non-functional (NA) slugs) -> degradation (notice + nearest-lower
topology, else a clear "pick explicitly" message; never crashes). Plus
x_default_dispatch: X/default with X in engine-set -> engine rec; X in
model-set -> model default; else error (engines + model-ids are disjoint).
switch.sh: <model>/default token; --set-default <slug> / --clear-default
<model> (round-trip the .env pin CLUB3090_DEFAULT_<MODELID>); a Defaults view
appended to --list (also standalone via --defaults) marking user-pin vs
curated. PR-A's grouping/markers/counts and the --force gate preserved.
launch.sh: bare invocation -> first installed shortlist model -> its
<model>/default (no full wizard); a pinned fast-path ("Launch your default
<slug>? [Y/n]"); a post-boot offer ("Make <slug> your default? [y/N]"). Any
narrowing flag keeps the explicit wizard path. Also load CLUB3090_DEFAULT_*
pin keys from .env even when MODEL_DIR is exported in the shell (the existing
.env loader is MODEL_DIR-gated, which would otherwise hide the pin).
Pin validation is warn + fall back, never blocking: unknown slug / wrong
model / topology-mismatch / (NA) status -> notice + curated default.
Tests: new test-model-default-resolver.sh (curated walk, (NA) skip,
degradation, X/default dispatch, pin override + all validation paths,
community seam skipped, .env round-trip); test-default-resolver.sh extended
with <model>/default launch.sh dispatch. Full suite green (only the
pre-existing test-submit-bench.sh fixture failure remains); 45 entries
unchanged; kv-calc calibration 17/17.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* docs: document the model-default resolver + user pins
Ship the user/contributor docs alongside the resolver code (repo convention —
update existing docs, no new top-level doc).
- README: single-card realign (ik-llama = fastest blessed single default,
llama.cpp = cliff-immune alternative — matches ENGINE_PREFERENCE single
order); add "pin your default" + <model>/default to Quick start.
- CLAUDE.md (= AGENTS.md): document RECOMMENDED_DEFAULT_MODELS +
ENGINE_PREFERENCE + the shared resolver as maintainer knobs next to DEFAULTS.
- FAQ: extend "switch to a different model" with <model>/default; new "How do
I set my own default config?" Q (two-layer model, --set-default/--clear-
default/--defaults, .env key, warn+fallback validation).
- SINGLE_CARD / DUAL_CARD: the resolver + the per-topology engine order; pin
hint.
- GETTING_STARTED: first-run uses <model>/default + the in-flow "set as
default?" prompt.
- ADDING_MODELS: a new model resolves via ENGINE_PREFERENCE; add a DEFAULTS row
per engine; RECOMMENDED_DEFAULT_MODELS is not auto-grown.
- UPSTREAM: beellama Docker-image row (gates beellama onboarding; the resolver
skips it today and it auto-promotes to single default on catalog).
- models/qwen3.6-27b/CHANGELOG: dated PR-B entry.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: noonghunna <[email protected]>
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
# Getting started — zero to `curl` in 5 minutes
|
|
|
|
The fastest path from `git clone` to serving your first response. No decisions, no menus — just commands.
|
|
|
|
> New to local AI and the terms below feel like jargon? Read [LOCAL_AI_PRIMER.md](LOCAL_AI_PRIMER.md) first — how hardware, engines, model sizes, and quants fit together in plain English.
|
|
|
|
```bash
|
|
# 1. Clone
|
|
git clone https://github.com/noonghunna/club-3090.git
|
|
cd club-3090
|
|
|
|
# 2. Download the model (Qwen3.6-27B, ~18 GB)
|
|
bash scripts/setup.sh qwen3.6-27b
|
|
|
|
# 3. Boot the default config for this model on your hardware
|
|
# (auto-picks: single-card → ik-llama/iq4ks-mtp; dual → vllm/dual)
|
|
bash scripts/launch.sh --variant qwen3.6-27b/default
|
|
|
|
# 4. Test it
|
|
curl -sf http://localhost:8020/v1/chat/completions \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"model":"qwen3.6-27b-autoround","messages":[{"role":"user","content":"Capital of France?"}],"max_tokens":200}'
|
|
```
|
|
|
|
If you see `Paris` in the response, you're up and running.
|
|
|
|
> After the boot finishes, `launch.sh` asks **"Make `<slug>` your default for `qwen3.6-27b`? [y/N]"**. Say `y` and a bare `bash scripts/launch.sh` next time goes straight to that exact config — no flags, one keypress to launch. (Change or clear it anytime: `bash scripts/switch.sh --set-default <slug>` / `--clear-default qwen3.6-27b`.)
|
|
|
|
---
|
|
|
|
## Next steps
|
|
|
|
| You want | Go here |
|
|
|----------|---------|
|
|
| **Pick a config by workload** (long context, vision, dual-card, etc.) | [`docs/SINGLE_CARD.md`](SINGLE_CARD.md) or [`docs/DUAL_CARD.md`](DUAL_CARD.md) |
|
|
| **Understand the jargon** (TPS, KV, MTP, TP) | [`docs/GLOSSARY.md`](GLOSSARY.md) |
|
|
| **Client code snippets** (Python, curl, IDE setup) | [`docs/EXAMPLES.md`](EXAMPLES.md) |
|
|
| **Run the canonical benchmark** | `bash scripts/bench.sh` |
|
|
| **Update to the latest** | `bash scripts/update.sh` |
|
|
| **Hardware questions** (power caps, NVLink, 4090/5090) | [`docs/HARDWARE.md`](HARDWARE.md) |
|
|
| **File an issue or share bench numbers** | `bash scripts/report.sh --full > my-rig.md` and open an issue |
|