Best-Known Configs
A Best-Known Config (BKC) is a curated deployment recipe for a specific model and runtime. It captures the settings that usually require the most trial and error, while leaving the final review editable.
Catalog scope
Section titled “Catalog scope”The current source catalog contains 85 vLLM recipes across 80 unique model IDs. It includes model families from NVIDIA, OpenAI, Meta, Google, Mistral, Qwen, DeepSeek, Microsoft, Moonshot AI, Z.ai/GLM, and other publishers.
The catalog is part of the Yokai binary, so recipe changes are versioned and reviewed with the code.
What a recipe contains
Section titled “What a recipe contains”| Field | Purpose |
|---|---|
| ID and name | Stable identity and operator-facing label |
| Workload | vllm or llamacpp catalog type |
| Model ID | Exact Hugging Face repository |
| Image | Tested runtime image or vendor build |
| Port | Default service port |
| Extra arguments | Parser, quantization, parallelism, context, or feature flags |
| Environment and volumes | Runtime inputs and mounted assets |
| Plugins | Model-specific assets and flags |
| Runtime | IPC, shared memory, and ulimits |
| Target devices | Explicitly validated GPU profiles |
| Minimum resources | VRAM per GPU and GPU-count requirements |
| Quantization and architecture | Matching and operator context |
| Source and notes | Provenance and important constraints |
Device-aware matching
Section titled “Device-aware matching”When several recipes target one model, Yokai prefers the most specific entry that names the selected device profile. It then considers minimum GPU count and VRAM. If no exact hardware profile matches, it returns the first resource-compatible recipe and exposes the choice for review.
Supported profile tags include GB10, Jetson Thor, RTX PRO 6000, RTX 5090, RTX 4090, L40S, A100, H100/H100 NVL, H200, H20, B200, GB200, MI300X, MI325X, MI355X, and Radeon AI PRO R9700.
Exact and suggested matches
Section titled “Exact and suggested matches”- Exact: workload and model repository match a catalog entry.
- Suggested: Yokai normalizes the repository owner and model tokens, then ranks a close catalog entry from the same owner.
Always inspect a suggested match before deployment. Similar names do not guarantee identical architecture or runtime requirements.
Apply a BKC
Section titled “Apply a BKC”In the Deploy route, select the model and press B during configuration. Yokai fills the tested values, but you can still change the image, port, flags, GPUs, environment, volumes, plugins, or runtime options before review.
Plugins
Section titled “Plugins”Some models need assets that are not built into the base runtime image. A BKC can reference a Yokai plugin that downloads those assets, mounts them into the container, and appends the required flags. Plugin assets are stored under ~/.local/share/yokai/plugins by default, /var/lib/yokai/plugins for root, or $YOKAI_PLUGIN_DIR when set.
Contributing a recipe
Section titled “Contributing a recipe”BKC entries live in internal/bkc/catalog_*.go. A useful contribution includes:
- the exact model and image versions tested;
- hardware profile, GPU count, and VRAM requirement;
- all runtime flags and environment variables;
- a source link and notes about known constraints;
- tests for lookup and device matching when the entry adds a new edge case.