Skip to content

feat(engines): add ExLlamaV3 backend via TabbyAPI#168

Open
OnlyTerp wants to merge 7 commits into
sybil-solutions:mainfrom
OnlyTerp:terp/exllamav3-engine
Open

feat(engines): add ExLlamaV3 backend via TabbyAPI#168
OnlyTerp wants to merge 7 commits into
sybil-solutions:mainfrom
OnlyTerp:terp/exllamav3-engine

Conversation

@OnlyTerp

@OnlyTerp OnlyTerp commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Summary

The repo description promises "Control panel for VLLM, Sglang, llama.cpp, exllamav3" — this delivers the missing fourth engine as a fifth EngineSpec.

  • Contract: adds "exllamav3" to the Backend/EngineBackend unions; selected_runtime_target_ids now keys off EngineBackend instead of an inline union.
  • Engine spec (specs/exllamav3-spec.ts): launches TabbyAPI via python <tabby_api_dir>/main.py --host --port --model-name <basename(model_path)>, reusing the existing (previously dead) tabby_api_dir config key. Health path /health. Python resolution follows the mlx/sglang pattern (env override → managed venv → python3). Install follows the llama.cpp pattern: env-configured command via LOCAL_STUDIO_EXLLAMAV3_UPGRADE_CMD, clear message when unset.
  • Runtime targets/info: TabbyAPI directory shows up as a configured runtime target with an installed/missing probe; SystemRuntimeInfo.backends.exllamav3 reports dir presence + python version. Docker image pattern registered for target discovery.
  • Frontend: ExLlamaV3 appears in the recipe backend picker, engine capabilities (conservative: general/model/environment/command tabs only), engines settings, and the server logs backend list.
  • Deliberately excluded: /environments (no official pinned Docker image) and managed-venv installs (TabbyAPI is a checkout, not a pip package).

Test plan

  • bun test tests/controller/integration/exllamav3-spec.test.ts — 6/6 (buildCommand shape, unconfigured-dir error, extra_args passthrough, detectInvocation, served-model-name extraction, install-unconfigured error)
  • Existing engine tests still green (engine-managed-runtime-command, process-utilities, vllm-docker-image — 9/9)
  • bun run typecheck (controller + cli), tsc --noEmit + typecheck:desktop (frontend)
  • knip, jscpd, ui-structure, cycles, depcheck, production build (pre-push check:quality)

@OnlyTerp OnlyTerp requested a review from 0xSero as a code owner July 2, 2026 01:22
@OnlyTerp OnlyTerp force-pushed the terp/exllamav3-engine branch from 1a37556 to f8345da Compare July 2, 2026 01:33
@OnlyTerp

OnlyTerp commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto current main. Note: be37a00 stripped the vestigial tabby_api_dir config while this was in flight — this PR restores it (LOCAL_STUDIO_TABBY_API_DIR) since the ExLlamaV3 spec now actually uses it as the TabbyAPI launch root. All gates + 6/6 spec tests green post-rebase.

@OnlyTerp

OnlyTerp commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Live hardware validation — RTX 5090 (Blackwell, SM 12.0)

Dogfooded this branch end-to-end on a real workstation: RTX 5090 32GB, CUDA 12.8 driver, TabbyAPI checkout at ~/ai-stack/tabbyAPI (torch 2.9.0+cu128 / exllamav3 0.0.43 wheels from TabbyAPI's own [cu12] extra, python 3.13 venv), model turboderp/Llama-3.2-1B-Instruct-exl3 @ 4.0bpw.

Full lifecycle through the controller:

POST /recipes            → {"success":true,"id":"llama32-1b-exl3"}   (backend: "exllamav3")
POST /launch/…           → {"success":true} — healthy in ~5s
GET  /status             → {"pid":108929,"backend":"exllamav3","model_path":"Llama-3.2-1B-Instruct-exl3-4.0bpw","port":8189}
GET  /v1/models  (proxy) → {"id":"llama32-1b-exl3","owned_by":"local-studio","active":true,"max_model_len":32768}
POST /v1/chat/completions (proxy) → completion OK, finish_reason "stop"
POST /evict              → clean shutdown, VRAM back to desktop baseline (7.8GB → 2.2GB)

Perf (from the controller-captured launch log): first request 17.8 T/s (kernel warmup), warmed generation 514.9 T/s on the 1B @ 4bpw. TabbyAPI stdout streams into the standard per-recipe log file and logs: SSE channel with zero extra wiring.

Two real bugs found and fixed by the dogfood run:

  1. fix(engines): accept exllamav3 in recipe and runtime job validators — the runtime Schema.Literals in recipe-serializer.ts and RUNTIME_JOB_BACKENDS still hardcoded four backends; the typechecker can't see runtime literal lists, only a live POST /recipes could.
  2. fix(engines): prefer the TabbyAPI venv python when launching exllamav3buildCommand fell through to system python3 (→ ModuleNotFoundError: loguru); it now prefers <tabby_api_dir>/venv/bin/python, with a spec test covering the resolution order (7/7 tests).

Recipe used, for reproduction:

{
  "id": "llama32-1b-exl3",
  "backend": "exllamav3",
  "model_path": "/home/terp/models/exl3/Llama-3.2-1B-Instruct-exl3-4.0bpw",
  "host": "127.0.0.1", "port": 8189,
  "extra_args": { "model-dir": "/home/terp/models/exl3", "disable-auth": "true" }
}

Env: LOCAL_STUDIO_TABBY_API_DIR=~/ai-stack/tabbyAPI. Full check:quality green on push.

@0xSero

0xSero commented Jul 12, 2026

Copy link
Copy Markdown
Collaborator

This is exactly how a fifth engine should land — everything inside an EngineSpec, registry-table touches matching the llamacpp precedent, and it even fixes the selected_runtime_target_ids inline-union wart. Needs a rebase: 7 files conflict, all mechanical (repo-wide prettier churn plus EngineCapabilities interface drift — the EXLLAMAV3 object needs regenerating against the current interface). One real request: pass --model-dir dirname(recipe.model_path) alongside --model-name so launches don't silently depend on TabbyAPI's own config.yml agreeing with Local Studio's models dir — that's a first-run failure that's very hard to diagnose from the UI.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants