Frosty40's picture
Treebeard 0.1.1 launcher refresh (pkg4): reasoning + speculation controls
98dd39a
|
Raw History Blame Contribute Delete
6.54 kB

Package contract

Model package: https://huggingface.co/Frosty40/Treebeard-Qwen3.6-35B-A3B-GGUF

GitHub repository: https://github.com/newjordan/treebeard

MoE algorithm explainer: https://newjordan.github.io/treebeard/moe-routing.html

Treebeard pkg3 follows a standard Hugging Face GGUF layout. The complete GGUF model and official Qwen configuration and tokenizer files live at repository root. Runtimes, launch tools, and evidence are additive directories.

User paths

There are two supported ways to use the package:

  1. install.sh downloads the one model file and the single runtime selected for the host. This is the smallest and easiest installation path.
  2. A full repository download includes every runtime, the optional projector, all standard model metadata, and all evidence. It is self-contained after download and does not fetch weights at launch time.

The installed treebeard command provides serve, doctor, verify, status, report, and version commands. run.sh remains the direct launcher and accepts additional llama-server arguments.

The CLI invokes packaged shell components through bash, so full-package downloads remain usable when an archive client does not preserve executable permission bits. bash ./treebeard serve is always a valid entry point.

Required root files

  • Qwen3.6-35B-A3B-UD-Q5_K_XL.gguf;
  • mmproj-F16.gguf for the full multimodal package;
  • config.json, generation_config.json, and configuration.json;
  • tokenizer.json, tokenizer_config.json, vocab.json, and merges.txt;
  • chat_template.jinja;
  • preprocessor_config.json and video_preprocessor_config.json;
  • install.sh, treebeard, run.sh, and verify.sh;
  • PACKAGE.json, SHA256SUMS, and runtime/SHA256SUMS.

Runtime selection

run.sh and install.sh use the same ordered selection:

  1. CUDA on Linux ARM64 when a working NVIDIA device is present;
  2. SYCL on Linux x86_64 when a Level Zero GPU is present;
  3. the portable CPU runtime on Linux x86_64.

Explicit selection uses TREEBEARD_BACKEND=cpu|sycl|cuda. The CPU runtime was built on Ubuntu 22.04 with GCC 11, glibc 2.35, GGML_NATIVE=OFF, dynamic backend loading, and 14 x86_64 CPU variants. The runtime selects the best compatible variant on the destination host.

The selected archive is SHA-256 verified and extracted under the user cache. Its internal manifest is checked on first extraction. The launcher never silently selects an unsupported architecture.

Verification

verify.sh checks the complete repository against SHA256SUMS. The installer creates INSTALL-SHA256SUMS for the selected subset, and treebeard verify checks the appropriate manifest automatically.

run.sh checks exact model size at each launch and verifies its hash once per stable device/inode/size/mtime fingerprint by default. Set TREEBEARD_VERIFY=always to rehash it on every launch. Runtime archives are always hashed before extraction.

Compatibility

Directory Target External requirement
runtime/cpu-linux-x86_64 Linux x86_64 glibc 2.35+
runtime/sycl-linux-x86_64 Linux x86_64 Intel oneAPI 2026 and Level Zero
runtime/cuda-linux-aarch64 Linux ARM64 CUDA 13 runtime, cuBLAS, and compatible NVIDIA driver

The CUDA and SYCL archives use vendor libraries installed on the host. GPU toolkits are not redistributed. NVIDIA x86_64 acceleration is not included in RC3; those systems select the portable CPU runtime.

Adding another target requires a runtime directory, an entry in runtime/SHA256SUMS, build provenance, internal file hashes, CPU-oracle correctness where applicable, and a real server/API package smoke test.

Resource contract

  • text install download: about 26.7 GB;
  • multimodal add-on: about 0.9 GB;
  • minimum memory check: 32 GB, with an explicit low-memory override;
  • default CPU profile: 32,768 context tokens and one slot;
  • default validated GPU profile: 262,144 context tokens and one slot.

The model supports up to 262,144 context tokens, but actual usable context is bounded by available device or system memory. The launcher exposes overrides instead of claiming every host can sustain the maximum profile.

Reasoning and speculative decoding

The validated profiles retain their existing context, slot, batch, and KV settings. Reasoning and speculation are independent, explicit controls layered on those resource profiles:

Setting Behavior
TREEBEARD_REASONING=off Default. Disables thinking in the server template while preserving explicit per-request overrides.
TREEBEARD_REASONING=bounded Enables thinking with a default 64-token GPU or 16-token CPU budget.
TREEBEARD_REASONING=unrestricted Enables thinking without a token budget.
TREEBEARD_SPECULATION=off Default. Leaves the runtime's no-speculation default unchanged.
TREEBEARD_SPECULATION=ngram Conservative ngram-map-k prompt-reuse drafting.
TREEBEARD_SPECULATION=mtp Conservative two-token drafting with the model's native MTP head.
TREEBEARD_SPECULATION=hybrid Tries n-gram drafting first, then native MTP.

Set TREEBEARD_REASONING_BUDGET to a positive integer to override the bounded default. The off setting is the server default; API clients can still opt an individual request into thinking with request-level chat-template and budget controls. Qwen3.6's native one-layer MTP head is carried by the GGUF, so mtp and hybrid do not require another model. Additional llama-server arguments may still be appended after treebeard serve for controlled experiments.

On the pinned b9624 runtime, selective OpenAI-compatible thinking must set both chat_template_kwargs.enable_thinking=true and thinking_budget_tokens=N on the request while the launcher remains in its default off mode. The request's max_tokens limit includes both thought and answer tokens, and every model turn after a tool result starts with a fresh budget. Global bounded reasoning works on b9624, but overriding that global budget with a smaller request budget requires the newer request-precedence fix. The packaged RC3 binaries also predate newer Anthropic thinking-control translations; they require a runtime rebuild and are not claimed by this launcher-only change.

The package makes no default speculative speed claim. N-gram hit rate, MTP acceptance, verification cost, memory pressure, and reasoning quality are workload-dependent and need matched evaluation before deployment.