Add tokenizer longhaul cache

2026-07-30 23:32:52 -05:00
22 changed files with 1678 additions and 28 deletions
@@ -1,9 +1,604 @@
-# Longhaul.cpp
+# llama.cpp
-This is a private fork that I decided to make public due to it working better than I expected.
+![llama](https://raw.githubusercontent.com/ggml-org/llama.brand/refs/heads/master/cover/llama-cpp/cover-llama-cpp-dark.svg)
-Do I recommend you use this for anything important? No. Is it cool? I like to think so.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Release](https://img.shields.io/github/v/release/ggml-org/llama.cpp)](https://github.com/ggml-org/llama.cpp/releases)
 [![Server](https://github.com/ggml-org/llama.cpp/actions/workflows/server.yml/badge.svg)](https://github.com/ggml-org/llama.cpp/actions/workflows/server.yml)
 [![Docker](https://github.com/ggml-org/llama.cpp/actions/workflows/docker.yml/badge.svg)](https://github.com/ggml-org/llama.cpp/actions/workflows/docker.yml)
 [![Winget](https://github.com/ggml-org/llama.cpp/actions/workflows/winget.yml/badge.svg)](https://github.com/ggml-org/llama.cpp/actions/workflows/winget.yml)
-It only supports Metal at the moment.
+[Manifesto](https://github.com/ggml-org/llama.cpp/discussions/205) / [ggml](https://github.com/ggml-org/ggml) / [ops](https://github.com/ggml-org/llama.cpp/blob/master/docs/ops.md) / [maintainer PRs](https://github.com/ggml-org/llama.cpp/issues?q=is%3Apr%20is%3Aopen%20draft%3AFalse%20(author%3Argerganov%20OR%20author%3AKitaitiMakoto%20OR%20author%3Adanbev%20OR%20author%3Aaldehir%20OR%20author%3Amax-krasnyansky%20OR%20author%3ACISC%20OR%20author%3Aggerganov%20OR%20author%3Aam17an%20OR%20author%3Abartowski1182%20OR%20author%3Ahipudding%20OR%20author%3AServeurpersoCom%20OR%20author%3Apwilkin%20OR%20author%3Areeselevine%20OR%20author%3Angxson%20OR%20author%3Ajeffbolznv%20OR%20author%3A0cc4m%20OR%20author%3Aangt%20OR%20author%3AIMbackK%20OR%20author%3Aarthw%20OR%20author%3AJohannesGaessler%20OR%20author%3AORippler%20OR%20author%3Aruixiang63%20OR%20author%3Axctan%20OR%20author%3Aallozaur%20OR%20author%3Ayomaytk%20OR%20author%3Aaendk%20OR%20author%3Agaugarg-nv%20OR%20author%3Ataronaeo%20OR%20author%3Aforforever73%20OR%20author%3Alhez%20OR%20author%3Anetrunnereve%20OR%20author%3Afairydreaming)%20sort%3Aupdated-desc)
-This is a personal project and because of this I have disabled open PRs. If you want to contribute, you can open an issue.
+LLM inference in C/C++
 ## Recent API changes
 - [Changelog for `libllama` API](https://github.com/ggml-org/llama.cpp/issues/9289)
 - [Changelog for `llama-server` REST API](https://github.com/ggml-org/llama.cpp/issues/9291)
 ## Hot topics
 - **Hugging Face cache migration: models downloaded with `-hf` are now stored in the standard Hugging Face cache directory, enabling sharing with other HF tools.**
 - **[guide : using the new WebUI of llama.cpp](https://github.com/ggml-org/llama.cpp/discussions/16938)**
 - [guide : running gpt-oss with llama.cpp](https://github.com/ggml-org/llama.cpp/discussions/15396)
 - [[FEEDBACK] Better packaging for llama.cpp to support downstream consumers 🤗](https://github.com/ggml-org/llama.cpp/discussions/15313)
 - Support for the `gpt-oss` model with native MXFP4 format has been added | [PR](https://github.com/ggml-org/llama.cpp/pull/15091) | [Collaboration with NVIDIA](https://blogs.nvidia.com/blog/rtx-ai-garage-openai-oss) | [Comment](https://github.com/ggml-org/llama.cpp/discussions/15095)
 - Multimodal support arrived in `llama-server`: [#12898](https://github.com/ggml-org/llama.cpp/pull/12898) | [documentation](./docs/multimodal.md)
 - VS Code extension for FIM completions: https://github.com/ggml-org/llama.vscode
 - Vim/Neovim plugin for FIM completions: https://github.com/ggml-org/llama.vim
 - Hugging Face Inference Endpoints now support GGUF out of the box! https://github.com/ggml-org/llama.cpp/discussions/9669
 - Hugging Face GGUF editor: [discussion](https://github.com/ggml-org/llama.cpp/discussions/9268) | [tool](https://huggingface.co/spaces/CISCai/gguf-editor)
 - WebGPU support is now available in the browser, see a blog/demo introducing it [here](https://reeselevine.github.io/llamas-on-the-web/).
 ----
 ## Quick start
 Getting started with llama.cpp is straightforward. Here are several ways to install it on your machine:
 - Install `llama.cpp` using [brew, nix, winget, or conda-forge](docs/install.md)
 - Run with Docker - see our [Docker documentation](docs/docker.md)
 - Download pre-built binaries from the [releases page](https://github.com/ggml-org/llama.cpp/releases)
 - Build from source by cloning this repository - check out [our build guide](docs/build.md)
 Once installed, you'll need a model to work with. Head to the [Obtaining and quantizing models](#obtaining-and-quantizing-models) section to learn more.
 Example command:
 ```sh
 # Use a local model file
 llama-cli -m my_model.gguf
 # Or download and run a model directly from Hugging Face
 llama-cli -hf ggml-org/gemma-3-1b-it-GGUF
 # Launch OpenAI-compatible API server
 llama-server -hf ggml-org/gemma-3-1b-it-GGUF
 ```
 ## Description
 The main goal of `llama.cpp` is to enable LLM inference with minimal setup and state-of-the-art performance on a wide
 range of hardware - locally and in the cloud.
 - Plain C/C++ implementation without any dependencies
 - Apple silicon is a first-class citizen - optimized via ARM NEON, Accelerate and Metal frameworks
 - AVX, AVX2, AVX512 and AMX support for x86 architectures
 - RVV, ZVFH, ZFH, ZICBOP and ZIHINTPAUSE support for RISC-V architectures
 - 1.5-bit, 2-bit, 3-bit, 4-bit, 5-bit, 6-bit, and 8-bit integer quantization for faster inference and reduced memory use
 - Custom CUDA kernels for running LLMs on NVIDIA GPUs (support for AMD GPUs via HIP and Moore Threads GPUs via MUSA)
 - Vulkan and SYCL backend support
 - CPU+GPU hybrid inference to partially accelerate models larger than the total VRAM capacity
 The `llama.cpp` project is the main playground for developing new features for the [ggml](https://github.com/ggml-org/ggml) library.
 <details>
 <summary>Models</summary>
 Typically finetunes of the base models below are supported as well.
 Instructions for adding support for new models: [HOWTO-add-model.md](docs/development/HOWTO-add-model.md)
 #### Text-only
 - [X] LLaMA 🦙
 - [x] LLaMA 2 🦙🦙
 - [x] LLaMA 3 🦙🦙🦙
 - [X] [Mistral 7B](https://huggingface.co/mistralai/Mistral-7B-v0.1)
 - [x] [Mixtral MoE](https://huggingface.co/models?search=mistral-ai/Mixtral)
 - [x] [DBRX](https://huggingface.co/databricks/dbrx-instruct)
 - [x] [Jamba](https://huggingface.co/ai21labs)
 - [X] [Falcon](https://huggingface.co/models?search=tiiuae/falcon)
 - [X] [Chinese LLaMA / Alpaca](https://github.com/ymcui/Chinese-LLaMA-Alpaca) and [Chinese LLaMA-2 / Alpaca-2](https://github.com/ymcui/Chinese-LLaMA-Alpaca-2)
 - [X] [Vigogne (French)](https://github.com/bofenghuang/vigogne)
 - [X] [BERT](https://github.com/ggml-org/llama.cpp/pull/5423)
 - [X] [Koala](https://bair.berkeley.edu/blog/2023/04/03/koala/)
 - [X] [Baichuan 1 & 2](https://huggingface.co/models?search=baichuan-inc/Baichuan) + [derivations](https://huggingface.co/hiyouga/baichuan-7b-sft)
 - [X] [Aquila 1 & 2](https://huggingface.co/models?search=BAAI/Aquila)
 - [X] [Starcoder models](https://github.com/ggml-org/llama.cpp/pull/3187)
 - [X] [Refact](https://huggingface.co/smallcloudai/Refact-1_6B-fim)
 - [X] [MPT](https://github.com/ggml-org/llama.cpp/pull/3417)
 - [X] [Bloom](https://github.com/ggml-org/llama.cpp/pull/3553)
 - [x] [Yi models](https://huggingface.co/models?search=01-ai/Yi)
 - [X] [StableLM models](https://huggingface.co/stabilityai)
 - [x] [Deepseek models](https://huggingface.co/models?search=deepseek-ai/deepseek)
 - [x] [Qwen models](https://huggingface.co/models?search=Qwen/Qwen)
 - [x] [PLaMo-13B](https://github.com/ggml-org/llama.cpp/pull/3557)
 - [x] [Phi models](https://huggingface.co/models?search=microsoft/phi)
 - [x] [PhiMoE](https://github.com/ggml-org/llama.cpp/pull/11003)
 - [x] [GPT-2](https://huggingface.co/gpt2)
 - [x] [Orion 14B](https://github.com/ggml-org/llama.cpp/pull/5118)
 - [x] [InternLM2](https://huggingface.co/models?search=internlm2)
 - [x] [CodeShell](https://github.com/WisdomShell/codeshell)
 - [x] [Gemma](https://ai.google.dev/gemma)
 - [x] [Mamba](https://github.com/state-spaces/mamba)
 - [x] [Grok-1](https://huggingface.co/keyfan/grok-1-hf)
 - [x] [Xverse](https://huggingface.co/models?search=xverse)
 - [x] [Command-R models](https://huggingface.co/models?search=CohereForAI/c4ai-command-r)
 - [x] [SEA-LION](https://huggingface.co/models?search=sea-lion)
 - [x] [GritLM-7B](https://huggingface.co/GritLM/GritLM-7B) + [GritLM-8x7B](https://huggingface.co/GritLM/GritLM-8x7B)
 - [x] [OLMo](https://allenai.org/olmo)
 - [x] [OLMo 2](https://allenai.org/olmo)
 - [x] [OLMoE](https://huggingface.co/allenai/OLMoE-1B-7B-0924)
 - [x] [Granite models](https://huggingface.co/collections/ibm-granite/granite-code-models-6624c5cec322e4c148c8b330)
 - [x] [GPT-NeoX](https://github.com/EleutherAI/gpt-neox) + [Pythia](https://github.com/EleutherAI/pythia)
 - [x] [Snowflake-Arctic MoE](https://huggingface.co/collections/Snowflake/arctic-66290090abe542894a5ac520)
 - [x] [Smaug](https://huggingface.co/models?search=Smaug)
 - [x] [Poro 34B](https://huggingface.co/LumiOpen/Poro-34B)
 - [x] [Bitnet b1.58 models](https://huggingface.co/1bitLLM)
 - [x] [Flan T5](https://huggingface.co/models?search=flan-t5)
 - [x] [Open Elm models](https://huggingface.co/collections/apple/openelm-instruct-models-6619ad295d7ae9f868b759ca)
 - [x] [ChatGLM3-6b](https://huggingface.co/THUDM/chatglm3-6b) + [ChatGLM4-9b](https://huggingface.co/THUDM/glm-4-9b) + [GLMEdge-1.5b](https://huggingface.co/THUDM/glm-edge-1.5b-chat) + [GLMEdge-4b](https://huggingface.co/THUDM/glm-edge-4b-chat)
 - [x] [GLM-4-0414](https://huggingface.co/collections/THUDM/glm-4-0414-67f3cbcb34dd9d252707cb2e)
 - [x] [SmolLM](https://huggingface.co/collections/HuggingFaceTB/smollm-6695016cad7167254ce15966)
 - [x] [EXAONE-3.0-7.8B-Instruct](https://huggingface.co/LGAI-EXAONE/EXAONE-3.0-7.8B-Instruct)
 - [x] [FalconMamba Models](https://huggingface.co/collections/tiiuae/falconmamba-7b-66b9a580324dd1598b0f6d4a)
 - [x] [Jais](https://huggingface.co/inceptionai/jais-13b-chat)
 - [x] [Bielik-11B-v2.3](https://huggingface.co/collections/speakleash/bielik-11b-v23-66ee813238d9b526a072408a)
 - [x] [RWKV-7](https://huggingface.co/collections/shoumenchougou/rwkv7-gxx-gguf)
 - [x] [RWKV-6](https://github.com/BlinkDL/RWKV-LM)
 - [x] [QRWKV-6](https://huggingface.co/recursal/QRWKV6-32B-Instruct-Preview-v0.1)
 - [x] [GigaChat-20B-A3B](https://huggingface.co/ai-sage/GigaChat-20B-A3B-instruct)
 - [X] [Trillion-7B-preview](https://huggingface.co/trillionlabs/Trillion-7B-preview)
 - [x] [Ling models](https://huggingface.co/collections/inclusionAI/ling-67c51c85b34a7ea0aba94c32)
 - [x] [Liquid LFM2 models](https://huggingface.co/collections/LiquidAI/lfm2)
 - [x] [Liquid LFM2.5 models](https://huggingface.co/collections/LiquidAI/lfm25)
 - [x] [Liquid Nanos](https://huggingface.co/collections/LiquidAI/liquid-nanos)
 - [x] [Hunyuan models](https://huggingface.co/collections/tencent/hunyuan-dense-model-6890632cda26b19119c9c5e7)
 - [x] [BailingMoeV2 (Ring/Ling 2.0) models](https://huggingface.co/collections/inclusionAI/ling-v2-68bf1dd2fc34c306c1fa6f86)
 - [x] [Mellum models](https://huggingface.co/JetBrains/models?search=mellum)
 #### Multimodal
 - [x] [LLaVA 1.5 models](https://huggingface.co/collections/liuhaotian/llava-15-653aac15d994e992e2677a7e), [LLaVA 1.6 models](https://huggingface.co/collections/liuhaotian/llava-16-65b9e40155f60fd046a5ccf2)
 - [x] [BakLLaVA](https://huggingface.co/models?search=SkunkworksAI/Bakllava)
 - [x] [Obsidian](https://huggingface.co/NousResearch/Obsidian-3B-V0.5)
 - [x] [ShareGPT4V](https://huggingface.co/models?search=Lin-Chen/ShareGPT4V)
 - [x] [MobileVLM 1.7B/3B models](https://huggingface.co/models?search=mobileVLM)
 - [x] [Yi-VL](https://huggingface.co/models?search=Yi-VL)
 - [x] [Mini CPM](https://huggingface.co/models?search=MiniCPM)
 - [x] [Moondream](https://huggingface.co/vikhyatk/moondream2)
 - [x] [Bunny](https://github.com/BAAI-DCAI/Bunny)
 - [x] [GLM-EDGE](https://huggingface.co/models?search=glm-edge)
 - [x] [Qwen2-VL](https://huggingface.co/collections/Qwen/qwen2-vl-66cee7455501d7126940800d)
 - [x] [LFM2-VL](https://huggingface.co/collections/LiquidAI/lfm2-vl-68963bbc84a610f7638d5ffa)
 </details>
 <details>
 <summary>Bindings</summary>
 - Python: [ddh0/easy-llama](https://github.com/ddh0/easy-llama)
 - Python: [abetlen/llama-cpp-python](https://github.com/abetlen/llama-cpp-python)
 - Go: [go-skynet/go-llama.cpp](https://github.com/go-skynet/go-llama.cpp)
 - Node.js: [withcatai/node-llama-cpp](https://github.com/withcatai/node-llama-cpp)
 - JS/TS (llama.cpp server client): [lgrammel/modelfusion](https://modelfusion.dev/integration/model-provider/llamacpp)
 - JS/TS (Programmable Prompt Engine CLI): [offline-ai/cli](https://github.com/offline-ai/cli)
 - JavaScript/Wasm (works in browser): [tangledgroup/llama-cpp-wasm](https://github.com/tangledgroup/llama-cpp-wasm)
 - Typescript/Wasm (nicer API, available on npm): [ngxson/wllama](https://github.com/ngxson/wllama)
 - Ruby: [yoshoku/llama_cpp.rb](https://github.com/yoshoku/llama_cpp.rb)
 - Ruby: [docusealco/rllama](https://github.com/docusealco/rllama)
 - Rust (more features): [edgenai/llama_cpp-rs](https://github.com/edgenai/llama_cpp-rs)
 - Rust (nicer API): [mdrokz/rust-llama.cpp](https://github.com/mdrokz/rust-llama.cpp)
 - Rust (more direct bindings): [utilityai/llama-cpp-rs](https://github.com/utilityai/llama-cpp-rs)
 - Rust (automated build from crates.io): [ShelbyJenkins/llm_client](https://github.com/ShelbyJenkins/llm_client)
 - C#/.NET: [SciSharp/LLamaSharp](https://github.com/SciSharp/LLamaSharp)
 - C#/VB.NET (more features - community license): [LM-Kit.NET](https://docs.lm-kit.com/lm-kit-net/index.html)
 - Scala 3: [donderom/llm4s](https://github.com/donderom/llm4s)
 - Clojure: [phronmophobic/llama.clj](https://github.com/phronmophobic/llama.clj)
 - React Native: [mybigday/llama.rn](https://github.com/mybigday/llama.rn)
 - Java: [kherud/java-llama.cpp](https://github.com/kherud/java-llama.cpp)
 - Java: [QuasarByte/llama-cpp-jna](https://github.com/QuasarByte/llama-cpp-jna)
 - Zig: [deins/llama.cpp.zig](https://github.com/Deins/llama.cpp.zig)
 - Flutter/Dart: [netdur/llama_cpp_dart](https://github.com/netdur/llama_cpp_dart)
 - Flutter: [xuegao-tzx/Fllama](https://github.com/xuegao-tzx/Fllama)
 - PHP (API bindings and features built on top of llama.cpp): [distantmagic/resonance](https://github.com/distantmagic/resonance) [(more info)](https://github.com/ggml-org/llama.cpp/pull/6326)
 - Guile Scheme: [guile_llama_cpp](https://savannah.nongnu.org/projects/guile-llama-cpp)
 - Swift [srgtuszy/llama-cpp-swift](https://github.com/srgtuszy/llama-cpp-swift)
 - Swift [ShenghaiWang/SwiftLlama](https://github.com/ShenghaiWang/SwiftLlama)
 - Delphi [Embarcadero/llama-cpp-delphi](https://github.com/Embarcadero/llama-cpp-delphi)
 - Go (no CGo needed): [hybridgroup/yzma](https://github.com/hybridgroup/yzma)
 - Android: [llama.android](/examples/llama.android)
 </details>
 <details>
 <summary>UIs</summary>
 *(to have a project listed here, it should clearly state that it depends on `llama.cpp`)*
 - [AI Sublime Text plugin](https://github.com/yaroslavyaroslav/OpenAI-sublime-text) (MIT)
 - [BonzAI App](https://apps.apple.com/us/app/bonzai-your-local-ai-agent/id6752847988) (proprietary)
 - [cztomsik/ava](https://github.com/cztomsik/ava) (MIT)
 - [Dot](https://github.com/alexpinel/Dot) (GPL)
 - [eva](https://github.com/ylsdamxssjxxdd/eva) (MIT)
 - [iohub/collama](https://github.com/iohub/coLLaMA) (Apache-2.0)
 - [janhq/jan](https://github.com/janhq/jan) (AGPL)
 - [johnbean393/Sidekick](https://github.com/johnbean393/Sidekick) (MIT)
 - [KanTV](https://github.com/zhouwg/kantv?tab=readme-ov-file) (Apache-2.0)
 - [KodiBot](https://github.com/firatkiral/kodibot) (GPL)
 - [llama.vim](https://github.com/ggml-org/llama.vim) (MIT)
 - [LARS](https://github.com/abgulati/LARS) (AGPL)
 - [Llama Assistant](https://github.com/vietanhdev/llama-assistant) (GPL)
 - [LlamaLib](https://github.com/undreamai/LlamaLib) (Apache-2.0)
 - [LLMFarm](https://github.com/guinmoon/LLMFarm?tab=readme-ov-file) (MIT)
 - [LLMUnity](https://github.com/undreamai/LLMUnity) (MIT)
 - [LMStudio](https://lmstudio.ai/) (proprietary)
 - [LocalAI](https://github.com/mudler/LocalAI) (MIT)
 - [LostRuins/koboldcpp](https://github.com/LostRuins/koboldcpp) (AGPL)
 - [MindMac](https://mindmac.app) (proprietary)
 - [MindWorkAI/AI-Studio](https://github.com/MindWorkAI/AI-Studio) (FSL-1.1-MIT)
 - [Mobile-Artificial-Intelligence/maid](https://github.com/Mobile-Artificial-Intelligence/maid) (MIT)
 - [Mozilla-Ocho/llamafile](https://github.com/Mozilla-Ocho/llamafile) (Apache-2.0)
 - [nat/openplayground](https://github.com/nat/openplayground) (MIT)
 - [nomic-ai/gpt4all](https://github.com/nomic-ai/gpt4all) (MIT)
 - [ollama/ollama](https://github.com/ollama/ollama) (MIT)
 - [oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui) (AGPL)
 - [PocketPal AI](https://github.com/a-ghorbani/pocketpal-ai) (MIT)
 - [psugihara/FreeChat](https://github.com/psugihara/FreeChat) (MIT)
 - [ptsochantaris/emeltal](https://github.com/ptsochantaris/emeltal) (MIT)
 - [pythops/tenere](https://github.com/pythops/tenere) (AGPL)
 - [ramalama](https://github.com/containers/ramalama) (MIT)
 - [semperai/amica](https://github.com/semperai/amica) (MIT)
 - [withcatai/catai](https://github.com/withcatai/catai) (MIT)
 - [Autopen](https://github.com/blackhole89/autopen) (GPL)
 </details>
 <details>
 <summary>Tools</summary>
 - [akx/ggify](https://github.com/akx/ggify) – download PyTorch models from Hugging Face Hub and convert them to GGML
 - [akx/ollama-dl](https://github.com/akx/ollama-dl) – download models from the Ollama library to be used directly with llama.cpp
 - [crashr/gppm](https://github.com/crashr/gppm) – launch llama.cpp instances utilizing NVIDIA Tesla P40 or P100 GPUs with reduced idle power consumption
 - [gpustack/gguf-parser](https://github.com/gpustack/gguf-parser-go/tree/main/cmd/gguf-parser) - review/check the GGUF file and estimate the memory usage
 - [Styled Lines](https://marketplace.unity.com/packages/tools/generative-ai/styled-lines-llama-cpp-model-292902) (proprietary licensed, async wrapper of inference part for game development in Unity3d with pre-built Mobile and Web platform wrappers and a model example)
 - [unslothai/unsloth](https://github.com/unslothai/unsloth) – 🦥 exports/saves fine-tuned and trained models to GGUF (Apache-2.0)
 </details>
 <details>
 <summary>Infrastructure</summary>
 - [Paddler](https://github.com/intentee/paddler) - Open-source LLMOps platform for hosting and scaling AI in your own infrastructure
 - [GPUStack](https://github.com/gpustack/gpustack) - Manage GPU clusters for running LLMs
 - [llama_cpp_canister](https://github.com/onicai/llama_cpp_canister) - llama.cpp as a smart contract on the Internet Computer, using WebAssembly
 - [llama-swap](https://github.com/mostlygeek/llama-swap) - transparent proxy that adds automatic model switching with llama-server
 - [Kalavai](https://github.com/kalavai-net/kalavai-client) - Crowdsource end to end LLM deployment at any scale
 - [llmaz](https://github.com/InftyAI/llmaz) - ☸️ Easy, advanced inference platform for large language models on Kubernetes.
 - [LLMKube](https://github.com/defilantech/llmkube) - Kubernetes operator for llama.cpp with multi-GPU and Apple Silicon Metal
  support"
 </details>
 <details>
 <summary>Games</summary>
 - [Lucy's Labyrinth](https://github.com/MorganRO8/Lucys_Labyrinth) - A simple maze game where agents controlled by an AI model will try to trick you.
 </details>
 ## Supported backends
 | Backend | Target devices |
 | --- | --- |
 | [Metal](docs/build.md#metal-build) | Apple Silicon |
 | [BLAS](docs/build.md#blas-build) | All |
 | [BLIS](docs/backend/BLIS.md) | All |
 | [SYCL](docs/backend/SYCL.md) | Intel GPU |
 | [OpenVINO [In Progress]](docs/backend/OPENVINO.md) | Intel CPUs, GPUs, and NPUs |
 | [MUSA](docs/build.md#musa) | Moore Threads GPU |
 | [CUDA](docs/build.md#cuda) | Nvidia GPU |
 | [HIP](docs/build.md#hip) | AMD GPU |
 | [ZenDNN](docs/build.md#zendnn) | AMD CPU |
 | [Vulkan](docs/build.md#vulkan) | GPU |
 | [CANN](docs/build.md#cann) | Ascend NPU |
 | [OpenCL](docs/backend/OPENCL.md) | Adreno GPU |
 | [IBM zDNN](docs/backend/zDNN.md) | IBM Z & LinuxONE |
 | [WebGPU](docs/build.md#webgpu) | All |
 | [RPC](https://github.com/ggml-org/llama.cpp/tree/master/tools/rpc) | All |
 | [Hexagon [In Progress]](docs/backend/snapdragon/README.md) | Snapdragon |
 | [VirtGPU](docs/backend/VirtGPU.md) | VirtGPU APIR |
 ## Obtaining and quantizing models
 The [Hugging Face](https://huggingface.co) platform hosts a [number of LLMs](https://huggingface.co/models?library=gguf&sort=trending) compatible with `llama.cpp`:
 - [Trending](https://huggingface.co/models?library=gguf&sort=trending)
 - [LLaMA](https://huggingface.co/models?sort=trending&search=llama+gguf)
 You can either manually download the GGUF file or directly use any `llama.cpp`-compatible models from [Hugging Face](https://huggingface.co/) or other model hosting sites, by using this CLI argument: `-hf <user>/<model>[:quant]`. For example:
 ```sh
 llama-cli -hf ggml-org/gemma-3-1b-it-GGUF
 ```
 By default, the CLI would download from Hugging Face, you can switch to other options with the environment variable `MODEL_ENDPOINT`. The `MODEL_ENDPOINT` must point to a Hugging Face compatible API endpoint.
 After downloading a model, use the CLI tools to run it locally - see below.
 `llama.cpp` requires the model to be stored in the [GGUF](https://github.com/ggml-org/ggml/blob/master/docs/gguf.md) file format. Models in other data formats can be converted to GGUF using the `convert_*.py` Python scripts in this repo.
 The Hugging Face platform provides a variety of online tools for converting, quantizing and hosting models with `llama.cpp`:
 - Use the [GGUF-my-repo space](https://huggingface.co/spaces/ggml-org/gguf-my-repo) to convert to GGUF format and quantize model weights to smaller sizes
 - Use the [GGUF-my-LoRA space](https://huggingface.co/spaces/ggml-org/gguf-my-lora) to convert LoRA adapters to GGUF format (more info: https://github.com/ggml-org/llama.cpp/discussions/10123)
 - Use the [GGUF-editor space](https://huggingface.co/spaces/CISCai/gguf-editor) to edit GGUF meta data in the browser (more info: https://github.com/ggml-org/llama.cpp/discussions/9268)
 - Use the [Inference Endpoints](https://ui.endpoints.huggingface.co/) to directly host `llama.cpp` in the cloud (more info: https://github.com/ggml-org/llama.cpp/discussions/9669)
 To learn more about model quantization, [read this documentation](tools/quantize/README.md)
 ## [`llama-cli`](tools/cli)
 #### A CLI tool for accessing and experimenting with most of `llama.cpp`'s functionality.
 - <details open>
    <summary>Run in conversation mode</summary>
    Models with a built-in chat template will automatically activate conversation mode. If this doesn't occur, you can manually enable it by adding `-cnv` and specifying a suitable chat template with `--chat-template NAME`
    ```bash
    llama-cli -m model.gguf
    # > hi, who are you?
    # Hi there! I'm your helpful assistant! I'm an AI-powered chatbot designed to assist and provide information to users like you. I'm here to help answer your questions, provide guidance, and offer support on a wide range of topics. I'm a friendly and knowledgeable AI, and I'm always happy to help with anything you need. What's on your mind, and how can I assist you today?
    #
    # > what is 1+1?
    # Easy peasy! The answer to 1+1 is... 2!
    ```
    </details>
 - <details>
    <summary>Run in conversation mode with custom chat template</summary>
    ```bash
    # use the "chatml" template (use -h to see the list of supported templates)
    llama-cli -m model.gguf -cnv --chat-template chatml
    # use a custom template
    llama-cli -m model.gguf -cnv --in-prefix 'User: ' --reverse-prompt 'User:'
    ```
    </details>
 - <details>
    <summary>Constrain the output with a custom grammar</summary>
    ```bash
    llama-cli -m model.gguf -n 256 --grammar-file grammars/json.gbnf -p 'Request: schedule a call at 8pm; Command:'
    # {"appointmentTime": "8pm", "appointmentDetails": "schedule a a call"}
    ```
    The [grammars/](grammars/) folder contains a handful of sample grammars. To write your own, check out the [GBNF Guide](grammars/README.md).
    For authoring more complex JSON grammars, check out https://grammar.intrinsiclabs.ai/
    </details>
 ## [`llama-server`](tools/server)
 #### A lightweight, [OpenAI API](https://github.com/openai/openai-openapi) compatible, HTTP server for serving LLMs.
 - <details open>
    <summary>Start a local HTTP server with default configuration on port 8080</summary>
    ```bash
    llama-server -m model.gguf --port 8080
    # Basic web UI can be accessed via browser: http://localhost:8080
    # Chat completion endpoint: http://localhost:8080/v1/chat/completions
    ```
    </details>
 - <details>
    <summary>Support multiple-users and parallel decoding</summary>
    ```bash
    # up to 4 concurrent requests, each with 4096 max context
    llama-server -m model.gguf -c 16384 -np 4
    ```
    </details>
 - <details>
    <summary>Enable speculative decoding</summary>
    ```bash
    # the draft.gguf model should be a small variant of the target model.gguf
    llama-server -m model.gguf -md draft.gguf
    ```
    </details>
 - <details>
    <summary>Serve an embedding model</summary>
    ```bash
    # use the /embedding endpoint
    llama-server -m model.gguf --embedding --pooling cls -ub 8192
    ```
    </details>
 - <details>
    <summary>Serve a reranking model</summary>
    ```bash
    # use the /reranking endpoint
    llama-server -m model.gguf --reranking
    ```
    </details>
 - <details>
    <summary>Constrain all outputs with a grammar</summary>
    ```bash
    # custom grammar
    llama-server -m model.gguf --grammar-file grammar.gbnf
    # JSON
    llama-server -m model.gguf --grammar-file grammars/json.gbnf
    ```
    </details>
 ## [`llama-perplexity`](tools/perplexity)
 #### A tool for measuring the [perplexity](tools/perplexity/README.md) [^1] (and other quality metrics) of a model over a given text.
 - <details open>
    <summary>Measure the perplexity over a text file</summary>
    ```bash
    llama-perplexity -m model.gguf -f file.txt
    # [1]15.2701,[2]5.4007,[3]5.3073,[4]6.2965,[5]5.8940,[6]5.6096,[7]5.7942,[8]4.9297, ...
    # Final estimate: PPL = 5.4007 +/- 0.67339
    ```
    </details>
 - <details>
    <summary>Measure KL divergence</summary>
    ```bash
    # TODO
    ```
    </details>
 [^1]: [https://huggingface.co/docs/transformers/perplexity](https://huggingface.co/docs/transformers/perplexity)
 ## [`llama-bench`](tools/llama-bench)
 #### Benchmark the performance of the inference for various parameters.
 - <details open>
    <summary>Run default benchmark</summary>
    ```bash
    llama-bench -m model.gguf
    # Output:
    # | model               |       size |     params | backend    | threads |          test |                  t/s |
    # | ------------------- | ---------: | ---------: | ---------- | ------: | ------------: | -------------------: |
    # | qwen2 1.5B Q4_0     | 885.97 MiB |     1.54 B | Metal,BLAS |      16 |         pp512 |      5765.41 ± 20.55 |
    # | qwen2 1.5B Q4_0     | 885.97 MiB |     1.54 B | Metal,BLAS |      16 |         tg128 |        197.71 ± 0.81 |
    #
    # build: 3e0ba0e60 (4229)
    ```
    </details>
 ## [`llama-simple`](examples/simple)
 #### A minimal example for implementing apps with `llama.cpp`. Useful for developers.
 - <details>
    <summary>Basic text completion</summary>
    ```bash
    llama-simple -m model.gguf
    # Hello my name is Kaitlyn and I am a 16 year old girl. I am a junior in high school and I am currently taking a class called "The Art of
    ```
    </details>
 ## Contributing
 - Contributors can open PRs
 - Collaborators will be invited based on contributions
 - Maintainers can push to branches in the `llama.cpp` repo and merge PRs into the `master` branch
 - Any help with managing issues, PRs and projects is very appreciated!
 - See [good first issues](https://github.com/ggml-org/llama.cpp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for tasks suitable for first contributions
 - Read the [CONTRIBUTING.md](CONTRIBUTING.md) for more information
 - Make sure to read this: [Inference at the edge](https://github.com/ggml-org/llama.cpp/discussions/205)
 - A bit of backstory for those who are interested: [Changelog podcast](https://changelog.com/podcast/532)
 ## Other documentation
 - [cli](tools/cli/README.md)
 - [completion](tools/completion/README.md)
 - [server](tools/server/README.md)
 - [GBNF grammars](grammars/README.md)
 #### Development documentation
 - [How to build](docs/build.md)
 - [Running on Docker](docs/docker.md)
 - [Build on Android](docs/android.md)
 - [Multi-GPU usage](docs/multi-gpu.md)
 - [Performance troubleshooting](docs/development/token_generation_performance_tips.md)
 - [GGML tips & tricks](https://github.com/ggml-org/llama.cpp/wiki/GGML-Tips-&-Tricks)
 #### Seminal papers and background on the models
 If your issue is with model generation quality, then please at least scan the following links and papers to understand the limitations of LLaMA models. This is especially important when choosing an appropriate model size and appreciating both the significant and subtle differences between LLaMA models and ChatGPT:
 - LLaMA:
    - [Introducing LLaMA: A foundational, 65-billion-parameter large language model](https://ai.facebook.com/blog/large-language-model-llama-meta-ai/)
    - [LLaMA: Open and Efficient Foundation Language Models](https://arxiv.org/abs/2302.13971)
 - GPT-3
    - [Language Models are Few-Shot Learners](https://arxiv.org/abs/2005.14165)
 - GPT-3.5 / InstructGPT / ChatGPT:
    - [Aligning language models to follow instructions](https://openai.com/research/instruction-following)
    - [Training language models to follow instructions with human feedback](https://arxiv.org/abs/2203.02155)
 ## XCFramework
 The XCFramework is a precompiled version of the library for iOS, visionOS, tvOS,
 and macOS. It can be used in Swift projects without the need to compile the
 library from source. For example:
 ```swift
 // swift-tools-version: 5.10
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 import PackageDescription
 let package = Package(
    name: "MyLlamaPackage",
    targets: [
        .executableTarget(
            name: "MyLlamaPackage",
            dependencies: [
                "LlamaFramework"
            ]),
        .binaryTarget(
            name: "LlamaFramework",
            url: "https://github.com/ggml-org/llama.cpp/releases/download/b5046/llama-b5046-xcframework.zip",
            checksum: "c19be78b5f00d8d29a25da41042cb7afa094cbf6280a225abe614b03b20029ab"
        )
    ]
 )
 ```
 The above example is using an intermediate build `b5046` of the library. This can be modified
 to use a different version by changing the URL and checksum.
 ## Completions
 Command-line completion is available for some environments.
 #### Bash Completion
 ```bash
 $ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash
 $ source ~/.llama-completion.bash
 ```
 Optionally this can be added to your `.bashrc` or `.bash_profile` to load it
 automatically. For example:
 ```console
 $ echo "source ~/.llama-completion.bash" >> ~/.bashrc
 ```
 ## Dependencies
 - [yhirose/cpp-httplib](https://github.com/yhirose/cpp-httplib) - Single-header HTTP server, used by `llama-server` - MIT license
 - [stb-image](https://github.com/nothings/stb) - Single-header image format decoder, used by multimodal subsystem - Public domain
 - [nlohmann/json](https://github.com/nlohmann/json) - Single-header JSON library, used by various tools/examples - MIT License
 - [miniaudio.h](https://github.com/mackron/miniaudio) - Single-header audio format decoder, used by multimodal subsystem - Public domain
 - [subprocess.h](https://github.com/sheredom/subprocess.h) - Single-header process launching solution for C and C++ - Public domain
@@ -817,6 +817,15 @@ static bool common_params_parse_ex(int argc, char ** argv, common_params_context
    if (params.load_mode == LLAMA_LOAD_MODE_LONGHAUL && params.longhaul_cache_bytes == 0) {
        throw std::invalid_argument("error: --longhaul requires --longhaul-cache N\n");
    }
    if (params.tokenizer_longhaul != (params.tokenizer_longhaul_cache_bytes != 0)) {
        throw std::invalid_argument(
            params.tokenizer_longhaul
                ? "error: --tokenizer-longhaul requires --tokenizer-longhaul-cache N\n"
                : "error: --tokenizer-longhaul-cache requires --tokenizer-longhaul\n");
    }
    if (params.tokenizer_longhaul && params.token_cache_size_mib == 0) {
        throw std::invalid_argument("error: --tokenizer-longhaul requires an enabled persistent token cache\n");
    }
    postprocess_cpu_params(params.cpuparams,       nullptr);
    postprocess_cpu_params(params.cpuparams_batch, &params.cpuparams);
@@ -2646,6 +2655,23 @@ common_params_context common_params_parser_init(common_params & params, llama_ex
            params.longhaul_cache_bytes = uint64_t(value) * 1024 * 1024 * 1024;
        }
    ).set_env("LLAMA_ARG_LONGHAUL_CACHE"));
    add_opt(common_arg(
        {"--tokenizer-longhaul"},
        "build and page the Qwen3.5/Laguna tokenizer through a bounded cache",
        [](common_params & params) {
            params.tokenizer_longhaul = true;
        }
    ).set_env("LLAMA_ARG_TOKENIZER_LONGHAUL"));
    add_opt(common_arg(
        {"--tokenizer-longhaul-cache"}, "N",
        "tokenizer-longhaul RAM cache size in MiB",
        [](common_params & params, int value) {
            if (value <= 0) {
                throw std::invalid_argument("tokenizer-longhaul cache size must be positive");
            }
            params.tokenizer_longhaul_cache_bytes = uint64_t(value) * 1024 * 1024;
        }
    ).set_env("LLAMA_ARG_TOKENIZER_LONGHAUL_CACHE"));
    add_opt(common_arg(
        {"--numa"}, "TYPE",
        "attempt optimizations that help on some NUMA systems\n"
@@ -1592,6 +1592,8 @@ struct llama_model_params common_model_params_to_llama(common_params & params) {
    mparams.split_mode      = params.split_mode;
    mparams.load_mode       = params.load_mode;
    mparams.longhaul_cache_bytes = params.longhaul_cache_bytes;
    mparams.tokenizer_longhaul = params.tokenizer_longhaul;
    mparams.tokenizer_longhaul_cache_bytes = params.tokenizer_longhaul_cache_bytes;
    mparams.tensor_split    = params.tensor_split;
    mparams.check_tensors   = params.check_tensors;
    mparams.use_extra_bufts = !params.no_extra_bufts;
@@ -486,6 +486,8 @@ struct common_params {
    enum llama_split_mode split_mode = LLAMA_SPLIT_MODE_LAYER; // how to split the model across GPUs
    enum llama_load_mode  load_mode  = LLAMA_LOAD_MODE_MMAP; // how to load the model
    uint64_t longhaul_cache_bytes = 0;
    bool tokenizer_longhaul = false;
    uint64_t tokenizer_longhaul_cache_bytes = 0;
    common_cpu_params cpuparams;
    common_cpu_params cpuparams_batch;
@@ -30,3 +30,24 @@ call `llama_token_cache_flush()`.
 The 5 GiB limit accounts for logical entry payloads. SQLite metadata and bounded
 journal files are not included.
 ## Tokenizer longhaul
 Qwen3.5 MoE and Laguna models can move their reverse-token and BPE-merge indexes
 into a persistent, disk-backed index while keeping a bounded lookup working set:
 ```text
 --tokenizer-longhaul
 --tokenizer-longhaul-cache N
 ```
 `N` is the application-owned lookup cache budget in MiB and is required when
 the mode is enabled. The mode is independent of model `--longhaul`, so the two
 can be used together. The finite tokenizer index builds in the background while
 model loading continues. If tokenizer work arrives first, it waits for atomic
 index publication; build or storage failures are reported instead of silently
 falling back to an unbounded tokenizer.
 The persistent index uses the directory selected by `--token-cache-dir` and is
 subject to `--token-cache-size`. Tokenized-text results continue to be cached
 on demand and therefore do not have a finite completion point.
@@ -360,6 +360,8 @@ extern "C" {
        bool no_alloc;        // only load metadata and simulate memory allocations
        uint64_t longhaul_cache_bytes; // routed expert cache size for LLAMA_LOAD_MODE_LONGHAUL
        bool tokenizer_longhaul;       // page Qwen3.5/Laguna tokenizer indexes through a bounded cache
        uint64_t tokenizer_longhaul_cache_bytes; // tokenizer-longhaul RAM cache budget
    };
    struct llama_sampler_seq_config {
@@ -38,6 +38,7 @@ add_library(llama
            llama-quant.cpp
            llama-sampler.cpp
            llama-token-cache.cpp
            llama-tokenizer-longhaul.cpp
            llama-vocab.cpp
            unicode-data.cpp
            unicode.cpp
@@ -1249,7 +1249,7 @@ void llama_model_base::load_hparams(llama_model_loader & ml) {
 void llama_model_base::load_vocab(llama_model_loader & ml) {
    const auto kv = LLM_KV(arch);
-    vocab.load(ml, kv);
+    vocab.load(ml, kv, params.tokenizer_longhaul, params.tokenizer_longhaul_cache_bytes);
 }
 bool llama_model_base::load_tensors(llama_model_loader & ml) {
@@ -2380,6 +2380,8 @@ llama_model_params llama_model_default_params() {
        /*.no_host                     =*/ false,
        /*.no_alloc                    =*/ false,
        /*.longhaul_cache_bytes        =*/ 0,
        /*.tokenizer_longhaul          =*/ false,
        /*.tokenizer_longhaul_cache_bytes =*/ 0,
    };
    return result;
@@ -214,6 +214,10 @@ public:
        if (!ensure_open()) return params.capacity_bytes == 0;
        std::lock_guard<std::mutex> db_lock(db_mutex);
        if (sqlite3_exec(db, "DELETE FROM entries; PRAGMA incremental_vacuum;", nullptr, nullptr, nullptr) != SQLITE_OK) return db_error();
        std::error_code ec;
        fs::remove_all(fs::path(path).parent_path() / "tokenizer-indexes", ec);
        if (ec) return false;
        sqlite3_exec(db, "INSERT OR REPLACE INTO meta(key,value) VALUES('external_bytes',0)", nullptr, nullptr, nullptr);
        return true;
    }
@@ -239,6 +243,11 @@ public:
                result.bytes_used = sqlite3_column_int64(stmt, 1);
            }
            sqlite3_finalize(stmt);
            if (sqlite3_prepare_v2(db, "SELECT value FROM meta WHERE key='external_bytes'", -1, &stmt, nullptr) == SQLITE_OK &&
                    sqlite3_step(stmt) == SQLITE_ROW) {
                result.bytes_used += static_cast<uint64_t>(sqlite3_column_int64(stmt, 0));
            }
            sqlite3_finalize(stmt);
        }
        return result;
    }
@@ -247,6 +256,45 @@ public:
        if (hit) ++stats.tokenizer_hits; else ++stats.tokenizer_misses;
    }
    std::string database_path() {
        return ensure_open() ? path : std::string();
    }
    uint64_t capacity() const {
        return params.capacity_bytes;
    }
    void set_external_bytes(uint64_t bytes) {
        if (!ensure_open()) return;
        std::lock_guard<std::mutex> db_lock(db_mutex);
        sqlite3_exec(db, "BEGIN IMMEDIATE", nullptr, nullptr, nullptr);
        sqlite3_stmt * stmt = nullptr;
        sqlite3_prepare_v2(db, "INSERT OR REPLACE INTO meta(key,value) VALUES('external_bytes',?1)", -1, &stmt, nullptr);
        sqlite3_bind_int64(stmt, 1, static_cast<sqlite3_int64>(bytes));
        sqlite3_step(stmt);
        sqlite3_finalize(stmt);
        uint64_t total = 0;
        sqlite3_prepare_v2(db, "SELECT COALESCE(SUM(size),0) FROM entries", -1, &stmt, nullptr);
        if (sqlite3_step(stmt) == SQLITE_ROW) total = sqlite3_column_int64(stmt, 0);
        sqlite3_finalize(stmt);
        const uint64_t entry_capacity = bytes >= params.capacity_bytes ? 0 : params.capacity_bytes - bytes;
        while (total > entry_capacity) {
            uint64_t victim_size = 0;
            sqlite3_prepare_v2(db, "SELECT size FROM entries ORDER BY last_access LIMIT 1", -1, &stmt, nullptr);
            if (sqlite3_step(stmt) == SQLITE_ROW) victim_size = sqlite3_column_int64(stmt, 0);
            sqlite3_finalize(stmt);
            if (victim_size == 0 || sqlite3_exec(db,
                    "DELETE FROM entries WHERE rowid=(SELECT rowid FROM entries ORDER BY last_access LIMIT 1)",
                    nullptr, nullptr, nullptr) != SQLITE_OK) {
                break;
            }
            total -= std::min(total, victim_size);
            ++stats.evictions;
        }
        sqlite3_exec(db, "COMMIT", nullptr, nullptr, nullptr);
    }
 private:
    static int64_t now_tick() {
        return std::chrono::duration_cast<std::chrono::microseconds>(
@@ -311,13 +359,22 @@ private:
        sqlite3_bind_int64(stmt, 1, static_cast<sqlite3_int64>(params.capacity_bytes));
        sqlite3_step(stmt);
        sqlite3_finalize(stmt);
        uint64_t external_bytes = 0;
        sqlite3_prepare_v2(db, "SELECT value FROM meta WHERE key='external_bytes'", -1, &stmt, nullptr);
        if (sqlite3_step(stmt) == SQLITE_ROW) {
            external_bytes = static_cast<uint64_t>(sqlite3_column_int64(stmt, 0));
        }
        sqlite3_finalize(stmt);
        const uint64_t entry_capacity = external_bytes >= params.capacity_bytes
            ? 0
            : params.capacity_bytes - external_bytes;
        sqlite3_exec(db, "BEGIN IMMEDIATE", nullptr, nullptr, nullptr);
        while (true) {
            sqlite3_prepare_v2(db, "SELECT COALESCE(SUM(size),0) FROM entries", -1, &stmt, nullptr);
            uint64_t total = 0;
            if (sqlite3_step(stmt) == SQLITE_ROW) total = sqlite3_column_int64(stmt, 0);
            sqlite3_finalize(stmt);
-            if (total <= params.capacity_bytes) break;
+            if (total <= entry_capacity) break;
            if (sqlite3_exec(db,
                    "DELETE FROM entries WHERE rowid=(SELECT rowid FROM entries ORDER BY last_access LIMIT 1)",
                    nullptr, nullptr, nullptr) != SQLITE_OK) {
@@ -355,12 +412,19 @@ private:
        std::lock_guard<std::mutex> db_lock(db_mutex);
        if (sqlite3_exec(db, "BEGIN IMMEDIATE", nullptr, nullptr, nullptr) != SQLITE_OK) { db_error(); return; }
        uint64_t capacity = params.capacity_bytes;
        uint64_t external_bytes = 0;
        sqlite3_stmt * capacity_stmt = nullptr;
        if (sqlite3_prepare_v2(db, "SELECT value FROM meta WHERE key='capacity'", -1, &capacity_stmt, nullptr) == SQLITE_OK &&
                sqlite3_step(capacity_stmt) == SQLITE_ROW) {
            capacity = static_cast<uint64_t>(sqlite3_column_int64(capacity_stmt, 0));
        }
        sqlite3_finalize(capacity_stmt);
        if (sqlite3_prepare_v2(db, "SELECT value FROM meta WHERE key='external_bytes'", -1, &capacity_stmt, nullptr) == SQLITE_OK &&
                sqlite3_step(capacity_stmt) == SQLITE_ROW) {
            external_bytes = static_cast<uint64_t>(sqlite3_column_int64(capacity_stmt, 0));
        }
        sqlite3_finalize(capacity_stmt);
        capacity = external_bytes >= capacity ? 0 : capacity - external_bytes;
        if (item.payload.size() > capacity) {
            sqlite3_exec(db, "ROLLBACK", nullptr, nullptr, nullptr);
            return;
@@ -492,6 +556,18 @@ void llama_token_cache_note_tokenizer_hit(bool hit) {
    cache().note_tokenizer(hit);
 }
 std::string llama_token_cache_database_path() {
    return cache().database_path();
 }
 uint64_t llama_token_cache_capacity() {
    return cache().capacity();
 }
 void llama_token_cache_set_external_bytes(uint64_t bytes) {
    cache().set_external_bytes(bytes);
 }
 llama_token_cache_params llama_token_cache_default_params() {
    return {nullptr, DEFAULT_CAPACITY};
 }
@@ -27,3 +27,8 @@ void llama_token_cache_store(
 void llama_token_cache_note_tokenizer_hit(bool hit);
 // Internal helpers used by tokenizer-longhaul artifacts.
 // Opening the cache here also fixes the configured path for the process.
 std::string llama_token_cache_database_path();
 uint64_t llama_token_cache_capacity();
 void llama_token_cache_set_external_bytes(uint64_t bytes);
@@ -0,0 +1,471 @@
 #include "llama-tokenizer-longhaul.h"
 #include "llama-token-cache.h"
 #include <sqlite3.h>
 #include <algorithm>
 #include <chrono>
 #include <filesystem>
 #include <list>
 #include <mutex>
 #include <thread>
 #include <unordered_map>
 #if defined(_WIN32)
 #  include <process.h>
 #else
 #  include <unistd.h>
 #endif
 namespace fs = std::filesystem;
 namespace {
 constexpr int INDEX_VERSION = 1;
 int process_id() {
 #if defined(_WIN32)
    return _getpid();
 #else
    return getpid();
 #endif
 }
 bool exec_sql(sqlite3 * db, const char * sql, std::string & error) {
    char * message = nullptr;
    if (sqlite3_exec(db, sql, nullptr, nullptr, &message) == SQLITE_OK) {
        return true;
    }
    error = message ? message : sqlite3_errmsg(db);
    sqlite3_free(message);
    return false;
 }
 struct lock_directory {
    fs::path path;
    bool owned = false;
    ~lock_directory() {
        if (owned) {
            std::error_code ec;
            fs::remove(path, ec);
        }
    }
 };
 uint64_t tokenizer_artifact_bytes(const fs::path & directory) {
    uint64_t total = 0;
    std::error_code ec;
    for (const auto & entry : fs::directory_iterator(directory, ec)) {
        if (ec) break;
        if (!entry.is_regular_file(ec) || entry.path().extension() != ".sqlite3") continue;
        total += entry.file_size(ec);
        if (ec) {
            ec.clear();
        }
    }
    return total;
 }
 } // namespace
 struct llama_tokenizer_longhaul_index::impl {
    struct cache_entry {
        int value;
        uint64_t bytes;
        std::list<std::string>::iterator position;
    };
    std::string source_key;
    uint64_t capacity;
    fs::path artifact;
    sqlite3 * db = nullptr;
    std::string id;
    uint64_t merge_count = 0;
    mutable std::mutex mutex;
    mutable uint64_t used = 0;
    mutable std::list<std::string> lru;
    mutable std::unordered_map<std::string, cache_entry> values;
    impl(std::string source_key, uint64_t capacity)
        : source_key(std::move(source_key)), capacity(capacity) {
    }
    ~impl() {
        if (db) {
            sqlite3_close(db);
        }
    }
    bool open_existing(std::string & error) {
        if (!fs::exists(artifact)) {
            return false;
        }
        sqlite3 * opened = nullptr;
        if (sqlite3_open_v2(artifact.string().c_str(), &opened,
                SQLITE_OPEN_READONLY | SQLITE_OPEN_FULLMUTEX, nullptr) != SQLITE_OK) {
            error = opened ? sqlite3_errmsg(opened) : "failed to open tokenizer index";
            if (opened) sqlite3_close(opened);
            return false;
        }
        sqlite3_stmt * stmt = nullptr;
        const char * sql =
            "SELECT version, tokenizer_id, n_merges FROM metadata WHERE complete=1 LIMIT 1";
        bool valid = sqlite3_prepare_v2(opened, sql, -1, &stmt, nullptr) == SQLITE_OK &&
            sqlite3_step(stmt) == SQLITE_ROW &&
            sqlite3_column_int(stmt, 0) == INDEX_VERSION;
        if (valid) {
            const unsigned char * value = sqlite3_column_text(stmt, 1);
            id = value ? reinterpret_cast<const char *>(value) : "";
            merge_count = static_cast<uint64_t>(sqlite3_column_int64(stmt, 2));
            valid = !id.empty();
        }
        sqlite3_finalize(stmt);
        if (!valid) {
            error = "tokenizer index is incomplete or has an unsupported version";
            sqlite3_close(opened);
            return false;
        }
        db = opened;
        sqlite3_busy_timeout(db, 5000);
        return true;
    }
    bool build(
            const std::vector<llama_tokenizer_longhaul_reverse> & reverse,
            const std::vector<llama_tokenizer_longhaul_merge> & merges,
            const std::string & tokenizer_id,
            std::string & error) {
        const fs::path temp = artifact.string() + ".tmp." + std::to_string(process_id());
        std::error_code ec;
        fs::remove(temp, ec);
        sqlite3 * output = nullptr;
        if (sqlite3_open_v2(temp.string().c_str(), &output,
                SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_EXCLUSIVE, nullptr) != SQLITE_OK) {
            error = output ? sqlite3_errmsg(output) : "failed to create tokenizer index";
            if (output) sqlite3_close(output);
            return false;
        }
        auto fail = [&](const std::string & message) {
            error = message;
            sqlite3_close(output);
            output = nullptr;
            std::error_code remove_ec;
            fs::remove(temp, remove_ec);
            return false;
        };
        if (!exec_sql(output,
                "PRAGMA journal_mode=OFF;"
                "PRAGMA synchronous=OFF;"
                "PRAGMA locking_mode=EXCLUSIVE;"
                "CREATE TABLE metadata("
                " version INTEGER NOT NULL,complete INTEGER NOT NULL,tokenizer_id TEXT NOT NULL,"
                " n_reverse INTEGER NOT NULL,n_merges INTEGER NOT NULL);"
                "CREATE TABLE reverse_tokens(text BLOB PRIMARY KEY,id INTEGER NOT NULL) WITHOUT ROWID;"
                "CREATE TABLE merges(left_text BLOB NOT NULL,right_text BLOB NOT NULL,rank INTEGER NOT NULL,"
                " PRIMARY KEY(left_text,right_text)) WITHOUT ROWID;"
                "BEGIN IMMEDIATE;", error)) {
            return fail(error);
        }
        sqlite3_stmt * insert_reverse = nullptr;
        sqlite3_stmt * insert_merge = nullptr;
        if (sqlite3_prepare_v2(output,
                "INSERT INTO reverse_tokens(text,id) VALUES(?1,?2)", -1, &insert_reverse, nullptr) != SQLITE_OK ||
            sqlite3_prepare_v2(output,
                "INSERT INTO merges(left_text,right_text,rank) VALUES(?1,?2,?3)",
                -1, &insert_merge, nullptr) != SQLITE_OK) {
            if (insert_reverse) sqlite3_finalize(insert_reverse);
            if (insert_merge) sqlite3_finalize(insert_merge);
            return fail(sqlite3_errmsg(output));
        }
        for (const auto & item : reverse) {
            sqlite3_bind_blob(insert_reverse, 1, item.text.data(), int(item.text.size()), SQLITE_STATIC);
            sqlite3_bind_int(insert_reverse, 2, item.id);
            if (sqlite3_step(insert_reverse) != SQLITE_DONE) {
                const std::string message = sqlite3_errmsg(output);
                sqlite3_finalize(insert_reverse);
                sqlite3_finalize(insert_merge);
                return fail(message);
            }
            sqlite3_reset(insert_reverse);
            sqlite3_clear_bindings(insert_reverse);
        }
        for (const auto & item : merges) {
            sqlite3_bind_blob(insert_merge, 1, item.left.data(), int(item.left.size()), SQLITE_STATIC);
            sqlite3_bind_blob(insert_merge, 2, item.right.data(), int(item.right.size()), SQLITE_STATIC);
            sqlite3_bind_int(insert_merge, 3, item.rank);
            if (sqlite3_step(insert_merge) != SQLITE_DONE) {
                const std::string message = sqlite3_errmsg(output);
                sqlite3_finalize(insert_reverse);
                sqlite3_finalize(insert_merge);
                return fail(message);
            }
            sqlite3_reset(insert_merge);
            sqlite3_clear_bindings(insert_merge);
        }
        sqlite3_finalize(insert_reverse);
        sqlite3_finalize(insert_merge);
        sqlite3_stmt * metadata = nullptr;
        if (sqlite3_prepare_v2(output,
                "INSERT INTO metadata VALUES(?1,1,?2,?3,?4)", -1, &metadata, nullptr) != SQLITE_OK) {
            return fail(sqlite3_errmsg(output));
        }
        sqlite3_bind_int(metadata, 1, INDEX_VERSION);
        sqlite3_bind_text(metadata, 2, tokenizer_id.c_str(), -1, SQLITE_STATIC);
        sqlite3_bind_int64(metadata, 3, static_cast<sqlite3_int64>(reverse.size()));
        sqlite3_bind_int64(metadata, 4, static_cast<sqlite3_int64>(merges.size()));
        const bool metadata_ok = sqlite3_step(metadata) == SQLITE_DONE;
        sqlite3_finalize(metadata);
        if (!metadata_ok || !exec_sql(output, "COMMIT;", error)) {
            return fail(metadata_ok ? error : sqlite3_errmsg(output));
        }
        sqlite3_close(output);
        output = nullptr;
        const uint64_t persistent_capacity = llama_token_cache_capacity();
        const uint64_t artifact_size = fs::file_size(temp, ec);
        if (ec || artifact_size > persistent_capacity) {
            fs::remove(temp, ec);
            error = "completed tokenizer index does not fit in --token-cache-size";
            return false;
        }
        struct artifact_candidate {
            fs::path path;
            fs::file_time_type modified;
            uint64_t size;
        };
        std::vector<artifact_candidate> candidates;
        uint64_t existing_bytes = 0;
        for (const auto & entry : fs::directory_iterator(artifact.parent_path(), ec)) {
            if (ec) break;
            if (!entry.is_regular_file(ec) || entry.path().extension() != ".sqlite3" ||
                    entry.path() == artifact || entry.path() == temp) {
                continue;
            }
            const uint64_t size = entry.file_size(ec);
            if (ec) {
                ec.clear();
                continue;
            }
            existing_bytes += size;
            candidates.push_back({entry.path(), entry.last_write_time(ec), size});
            if (ec) ec.clear();
        }
        std::sort(candidates.begin(), candidates.end(),
            [](const artifact_candidate & a, const artifact_candidate & b) {
                return a.modified < b.modified;
            });
        for (const auto & candidate : candidates) {
            if (existing_bytes + artifact_size <= persistent_capacity) break;
            fs::remove(candidate.path, ec);
            if (!ec) existing_bytes -= std::min(existing_bytes, candidate.size);
            ec.clear();
        }
        if (existing_bytes + artifact_size > persistent_capacity) {
            fs::remove(temp, ec);
            error = "tokenizer indexes do not fit in --token-cache-size";
            return false;
        }
        fs::rename(temp, artifact, ec);
        if (ec) {
            const std::string rename_error = ec.message();
            // A competing process may have published the same immutable artifact.
            std::error_code remove_ec;
            fs::remove(temp, remove_ec);
            std::string ignored;
            if (open_existing(ignored)) {
                return true;
            }
            error = "failed to publish tokenizer index: " + rename_error;
            return false;
        }
        const bool opened = open_existing(error);
        if (opened) {
            llama_token_cache_set_external_bytes(tokenizer_artifact_bytes(artifact.parent_path()));
        }
        return opened;
    }
    int lookup(const std::string & cache_key, const char * sql,
            const std::string & first, const std::string * second, int missing) const {
        std::lock_guard<std::mutex> lock(mutex);
        auto found = values.find(cache_key);
        if (found != values.end()) {
            lru.splice(lru.begin(), lru, found->second.position);
            return found->second.value;
        }
        sqlite3_stmt * stmt = nullptr;
        int value = missing;
        if (sqlite3_prepare_v2(db, sql, -1, &stmt, nullptr) == SQLITE_OK) {
            sqlite3_bind_blob(stmt, 1, first.data(), int(first.size()), SQLITE_STATIC);
            if (second) {
                sqlite3_bind_blob(stmt, 2, second->data(), int(second->size()), SQLITE_STATIC);
            }
            if (sqlite3_step(stmt) == SQLITE_ROW) {
                value = sqlite3_column_int(stmt, 0);
            }
        }
        sqlite3_finalize(stmt);
        const uint64_t bytes = cache_key.size() + sizeof(cache_entry) + sizeof(std::string);
        if (bytes <= capacity) {
            while (!lru.empty() && used + bytes > capacity) {
                auto victim = values.find(lru.back());
                if (victim != values.end()) {
                    used -= victim->second.bytes;
                    values.erase(victim);
                }
                lru.pop_back();
            }
            lru.push_front(cache_key);
            values.emplace(cache_key, cache_entry{value, bytes, lru.begin()});
            used += bytes;
        }
        return value;
    }
 };
 llama_tokenizer_longhaul_index::llama_tokenizer_longhaul_index(
        std::string source_key, uint64_t cache_bytes)
    : pimpl(std::make_unique<impl>(std::move(source_key), cache_bytes)) {
 }
 llama_tokenizer_longhaul_index::~llama_tokenizer_longhaul_index() = default;
 bool llama_tokenizer_longhaul_index::prepare(
        const std::vector<llama_tokenizer_longhaul_reverse> & reverse,
        const std::vector<llama_tokenizer_longhaul_merge> & merges,
        const std::string & tokenizer_id,
        std::string & error) {
    const std::string cache_db = llama_token_cache_database_path();
    if (cache_db.empty()) {
        error = "persistent token cache is disabled or unavailable";
        return false;
    }
    const fs::path directory = fs::path(cache_db).parent_path() / "tokenizer-indexes";
    std::error_code ec;
    fs::create_directories(directory, ec);
    if (ec) {
        error = "failed to create tokenizer index directory: " + ec.message();
        return false;
    }
    pimpl->artifact = directory / (llama_token_cache_hash(pimpl->source_key) + ".sqlite3");
    if (pimpl->open_existing(error)) {
        if (pimpl->id == tokenizer_id) {
            llama_token_cache_set_external_bytes(tokenizer_artifact_bytes(directory));
            return true;
        }
        sqlite3_close(pimpl->db);
        pimpl->db = nullptr;
        std::error_code stale_ec;
        fs::remove(pimpl->artifact, stale_ec);
    }
    lock_directory lock{pimpl->artifact.string() + ".lock", false};
    lock.owned = fs::create_directory(lock.path, ec);
    if (!lock.owned) {
        // Another process is building. Wait for its atomic publication.
        for (int i = 0; i < 24000; ++i) {
            std::this_thread::sleep_for(std::chrono::milliseconds(25));
            std::string ignored;
            if (pimpl->open_existing(ignored)) {
                if (pimpl->id == tokenizer_id) {
                    llama_token_cache_set_external_bytes(tokenizer_artifact_bytes(directory));
                    return true;
                }
                sqlite3_close(pimpl->db);
                pimpl->db = nullptr;
            }
            if (!fs::exists(lock.path)) {
                lock.owned = fs::create_directory(lock.path, ec);
                if (lock.owned) break;
            }
        }
        if (!lock.owned) {
            error = "timed out waiting for another tokenizer index builder";
            return false;
        }
    }
    error.clear();
    if (pimpl->open_existing(error)) {
        if (pimpl->id == tokenizer_id) {
            llama_token_cache_set_external_bytes(tokenizer_artifact_bytes(directory));
            return true;
        }
        sqlite3_close(pimpl->db);
        pimpl->db = nullptr;
    }
    std::error_code remove_ec;
    fs::remove(pimpl->artifact, remove_ec);
    return pimpl->build(reverse, merges, tokenizer_id, error);
 }
 llama_token llama_tokenizer_longhaul_index::text_to_token(const std::string & text) const {
    const std::string key = "t" + text;
    return pimpl->lookup(key,
        "SELECT id FROM reverse_tokens WHERE text=?1", text, nullptr, LLAMA_TOKEN_NULL);
 }
 int llama_tokenizer_longhaul_index::find_bpe_rank(
        const std::string & left, const std::string & right) const {
    std::string key;
    key.reserve(left.size() + right.size() + 2);
    key.push_back('m');
    key += left;
    key.push_back('\0');
    key += right;
    return pimpl->lookup(key,
        "SELECT rank FROM merges WHERE left_text=?1 AND right_text=?2", left, &right, -1);
 }
 std::vector<std::string> llama_tokenizer_longhaul_index::get_bpe_merges() const {
    std::lock_guard<std::mutex> lock(pimpl->mutex);
    std::vector<std::string> result;
    result.reserve(pimpl->merge_count);
    sqlite3_stmt * stmt = nullptr;
    if (sqlite3_prepare_v2(pimpl->db,
            "SELECT left_text,right_text FROM merges ORDER BY rank", -1, &stmt, nullptr) != SQLITE_OK) {
        return result;
    }
    while (sqlite3_step(stmt) == SQLITE_ROW) {
        const char * left = static_cast<const char *>(sqlite3_column_blob(stmt, 0));
        const int left_size = sqlite3_column_bytes(stmt, 0);
        const char * right = static_cast<const char *>(sqlite3_column_blob(stmt, 1));
        const int right_size = sqlite3_column_bytes(stmt, 1);
        std::string item(left, left_size);
        item.push_back(' ');
        item.append(right, right_size);
        result.push_back(std::move(item));
    }
    sqlite3_finalize(stmt);
    return result;
 }
 uint64_t llama_tokenizer_longhaul_index::cache_bytes_used() const {
    std::lock_guard<std::mutex> lock(pimpl->mutex);
    return pimpl->used;
 }
 uint64_t llama_tokenizer_longhaul_index::cache_capacity() const {
    return pimpl->capacity;
 }
 uint64_t llama_tokenizer_longhaul_index::n_merges() const {
    return pimpl->merge_count;
 }
 const std::string & llama_tokenizer_longhaul_index::tokenizer_id() const {
    return pimpl->id;
 }
@@ -0,0 +1,47 @@
 #pragma once
 #include "llama.h"
 #include <cstdint>
 #include <memory>
 #include <string>
 #include <vector>
 struct llama_tokenizer_longhaul_reverse {
    std::string text;
    llama_token id;
 };
 struct llama_tokenizer_longhaul_merge {
    std::string left;
    std::string right;
    int rank;
 };
 class llama_tokenizer_longhaul_index {
 public:
    llama_tokenizer_longhaul_index(std::string source_key, uint64_t cache_bytes);
    ~llama_tokenizer_longhaul_index();
    llama_tokenizer_longhaul_index(const llama_tokenizer_longhaul_index &) = delete;
    llama_tokenizer_longhaul_index & operator=(const llama_tokenizer_longhaul_index &) = delete;
    bool prepare(
            const std::vector<llama_tokenizer_longhaul_reverse> & reverse,
            const std::vector<llama_tokenizer_longhaul_merge> & merges,
            const std::string & tokenizer_id,
            std::string & error);
    llama_token text_to_token(const std::string & text) const;
    int find_bpe_rank(const std::string & left, const std::string & right) const;
    std::vector<std::string> get_bpe_merges() const;
    uint64_t cache_bytes_used() const;
    uint64_t cache_capacity() const;
    uint64_t n_merges() const;
    const std::string & tokenizer_id() const;
 private:
    struct impl;
    std::unique_ptr<impl> pimpl;
 };
@@ -1,5 +1,6 @@
 #include "llama-vocab.h"
 #include "llama-token-cache.h"
 #include "llama-tokenizer-longhaul.h"
 #include "ggml.h"
 #include "gguf.h"
@@ -13,13 +14,16 @@
 #include <cctype>
 #include <cfloat>
 #include <cmath>
 #include <condition_variable>
 #include <cstdarg>
 #include <cstring>
 #include <forward_list>
 #include <limits>
 #include <map>
 #include <mutex>
 #include <queue>
 #include <set>
 #include <thread>
 #include <unordered_map>
 //
@@ -1846,12 +1850,37 @@ struct llama_vocab::impl {
    std::vector<char> precompiled_charsmap;
    enum class longhaul_state {
        disabled,
        building,
        ready,
        failed,
    };
    bool tokenizer_longhaul = false;
    uint64_t tokenizer_longhaul_cache_bytes = 0;
    uint64_t tokenizer_longhaul_n_merges = 0;
    mutable std::mutex tokenizer_longhaul_mutex;
    mutable std::condition_variable tokenizer_longhaul_ready;
    mutable longhaul_state tokenizer_longhaul_state = longhaul_state::disabled;
    mutable std::string tokenizer_longhaul_error;
    mutable std::unique_ptr<llama_tokenizer_longhaul_index> tokenizer_longhaul_index;
    std::thread tokenizer_longhaul_worker;
    impl(const llama_vocab & vocab) : vocab(vocab) {
    }
-    ~impl() = default;
+    ~impl() {
        if (tokenizer_longhaul_worker.joinable()) {
            tokenizer_longhaul_worker.join();
        }
    }
-    void load(llama_model_loader & ml, const LLM_KV & kv);
+    void load(
            llama_model_loader & ml,
            const LLM_KV & kv,
            bool tokenizer_longhaul,
            uint64_t tokenizer_longhaul_cache_bytes);
    void wait_for_tokenizer_longhaul() const;
    bool load_cache_snapshot(const std::vector<uint8_t> & snapshot);
    void reset_cache_snapshot_state();
@@ -1908,7 +1937,7 @@ struct llama_vocab::impl {
                         bool   special) const;
    // use cached data
-    const std::string & token_to_piece(llama_token token) const;
+    std::string token_to_piece(llama_token token) const;
    int32_t detokenize(
            const llama_token * tokens,
@@ -1928,11 +1957,29 @@ private:
    const llama_vocab & vocab;
 };
-void llama_vocab::impl::load(llama_model_loader & ml, const LLM_KV & kv) {
+void llama_vocab::impl::load(
        llama_model_loader & ml,
        const LLM_KV & kv,
        bool tokenizer_longhaul_value,
        uint64_t tokenizer_longhaul_cache_bytes_value) {
    struct gguf_context * ctx = ml.metadata;
    tokenizer_longhaul = tokenizer_longhaul_value;
    tokenizer_longhaul_cache_bytes = tokenizer_longhaul_cache_bytes_value;
    if (tokenizer_longhaul) {
        if (tokenizer_longhaul_cache_bytes == 0) {
            throw std::runtime_error("tokenizer-longhaul cache budget must be positive");
        }
        if (ml.get_arch() != LLM_ARCH_QWEN35MOE && ml.get_arch() != LLM_ARCH_LAGUNA) {
            throw std::runtime_error("tokenizer-longhaul currently requires a qwen35moe or laguna model");
        }
        if (ml.get_token_cache_source_key().empty()) {
            throw std::runtime_error("tokenizer-longhaul requires a file-backed GGUF model");
        }
    }
    const std::string & source_cache_key = ml.get_token_cache_source_key();
-    if (!source_cache_key.empty()) {
+    if (!tokenizer_longhaul && !source_cache_key.empty()) {
        std::vector<uint8_t> snapshot;
        bool found = llama_token_cache_lookup(LLAMA_TOKEN_CACHE_KIND_TOKENIZER, source_cache_key, snapshot);
        if (found && snapshot.size() == 65 && snapshot[0] == 'A') {
@@ -1958,6 +2005,9 @@ void llama_vocab::impl::load(llama_model_loader & ml, const LLM_KV & kv) {
        ml.get_key(LLM_KV_TOKENIZER_TOKEN_TYPE_COUNT, n_token_types, false);
        if (tokenizer_model == "no_vocab" || tokenizer_model == "none") {
            if (tokenizer_longhaul) {
                throw std::runtime_error("tokenizer-longhaul requires a BPE tokenizer");
            }
            type = LLAMA_VOCAB_TYPE_NONE;
            // default special tokens
@@ -3063,6 +3113,69 @@ void llama_vocab::impl::load(llama_model_loader & ml, const LLM_KV & kv) {
        }
    }
    if (tokenizer_longhaul) {
        if (type != LLAMA_VOCAB_TYPE_BPE ||
                (tokenizer_pre != "qwen35" && tokenizer_pre != "laguna")) {
            throw std::runtime_error(
                "tokenizer-longhaul currently supports only qwen35 and laguna BPE tokenizers");
        }
        std::vector<llama_tokenizer_longhaul_reverse> reverse;
        reverse.reserve(token_to_id.size());
        while (!token_to_id.empty()) {
            auto node = token_to_id.extract(token_to_id.begin());
            reverse.push_back({std::move(node.key()), node.mapped()});
        }
        token_to_id.rehash(0);
        std::vector<llama_tokenizer_longhaul_merge> merges;
        merges.reserve(bpe_ranks.size());
        while (!bpe_ranks.empty()) {
            auto node = bpe_ranks.extract(bpe_ranks.begin());
            auto key = std::move(node.key());
            merges.push_back({std::move(key.first), std::move(key.second), node.mapped()});
        }
        bpe_ranks.rehash(0);
        tokenizer_longhaul_n_merges = merges.size();
        cache_token_to_piece.clear();
        cache_token_to_piece.shrink_to_fit();
        token_cache_id = llama_token_cache_hash(
            std::string("tokenizer-longhaul-v1\n") + source_cache_key);
        {
            std::lock_guard<std::mutex> lock(tokenizer_longhaul_mutex);
            tokenizer_longhaul_state = longhaul_state::building;
        }
        const uint64_t cache_bytes = tokenizer_longhaul_cache_bytes;
        const std::string source_key = source_cache_key;
        const std::string tokenizer_id = token_cache_id;
        tokenizer_longhaul_worker = std::thread(
            [this, source_key, cache_bytes, tokenizer_id,
             reverse = std::move(reverse), merges = std::move(merges)]() mutable {
                auto index = std::make_unique<llama_tokenizer_longhaul_index>(source_key, cache_bytes);
                std::string error;
                const bool ok = index->prepare(reverse, merges, tokenizer_id, error);
                {
                    std::lock_guard<std::mutex> lock(tokenizer_longhaul_mutex);
                    if (ok) {
                        tokenizer_longhaul_index = std::move(index);
                        tokenizer_longhaul_state = longhaul_state::ready;
                        LLAMA_LOG_INFO("%s: tokenizer-longhaul index is ready\n", "llama_vocab");
                    } else {
                        tokenizer_longhaul_error = error.empty()
                            ? "unknown tokenizer-longhaul build error"
                            : std::move(error);
                        tokenizer_longhaul_state = longhaul_state::failed;
                        LLAMA_LOG_ERROR("%s: tokenizer-longhaul index failed: %s\n",
                            "llama_vocab", tokenizer_longhaul_error.c_str());
                    }
                }
                tokenizer_longhaul_ready.notify_all();
            });
        LLAMA_LOG_INFO("%s: tokenizer-longhaul index is building in the background\n", __func__);
        return;
    }
    // Persist a versioned canonical snapshot of the effective tokenizer state.
    // The snapshot also serves as the namespace for text-to-token cache entries.
    {
@@ -3151,6 +3264,23 @@ void llama_vocab::impl::load(llama_model_loader & ml, const LLM_KV & kv) {
    }
 }
 void llama_vocab::impl::wait_for_tokenizer_longhaul() const {
    if (!tokenizer_longhaul) {
        return;
    }
    std::unique_lock<std::mutex> lock(tokenizer_longhaul_mutex);
    if (tokenizer_longhaul_state == longhaul_state::disabled) {
        return;
    }
    tokenizer_longhaul_ready.wait(lock, [this] {
        return tokenizer_longhaul_state == longhaul_state::ready ||
               tokenizer_longhaul_state == longhaul_state::failed;
    });
    if (tokenizer_longhaul_state == longhaul_state::failed) {
        throw std::runtime_error("tokenizer-longhaul failed: " + tokenizer_longhaul_error);
    }
 }
 void llama_vocab::impl::reset_cache_snapshot_state() {
    n_token_types = 0;
    tokenizer_model.clear();
@@ -3282,36 +3412,43 @@ std::string llama_vocab::impl::type_name() const{
 }
 bool llama_vocab::impl::is_normal(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token[id].attr & LLAMA_TOKEN_ATTR_NORMAL;
 }
 bool llama_vocab::impl::is_unknown(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token[id].attr & LLAMA_TOKEN_ATTR_UNKNOWN;
 }
 bool llama_vocab::impl::is_control(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token[id].attr & LLAMA_TOKEN_ATTR_CONTROL;
 }
 bool llama_vocab::impl::is_byte(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token[id].attr & LLAMA_TOKEN_ATTR_BYTE;
 }
 bool llama_vocab::impl::is_user_defined(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token[id].attr & LLAMA_TOKEN_ATTR_USER_DEFINED;
 }
 bool llama_vocab::impl::is_unused(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token[id].attr & LLAMA_TOKEN_ATTR_UNUSED;
 }
 bool llama_vocab::impl::is_eog(llama_token id) const {
    wait_for_tokenizer_longhaul();
    return id != LLAMA_TOKEN_NULL && special_eog_ids.count(id) > 0;
 }
@@ -3339,6 +3476,7 @@ uint8_t llama_vocab::impl::token_to_byte(llama_token id) const {
 }
 llama_token_attr llama_vocab::impl::token_get_attr(llama_token id) const {
    wait_for_tokenizer_longhaul();
    GGML_ASSERT(type != LLAMA_VOCAB_TYPE_NONE);
    return id_to_token.at(id).attr;
 }
@@ -3749,6 +3887,7 @@ std::vector<llama_token> llama_vocab::impl::tokenize(
        const std::string & raw_text,
        bool add_special,
        bool parse_special) const {
    wait_for_tokenizer_longhaul();
    if (raw_text.empty() || token_cache_id.empty()) {
        return tokenize_uncached(raw_text, add_special, parse_special);
    }
@@ -3792,6 +3931,7 @@ std::vector<llama_token> llama_vocab::impl::tokenize(
 }
 int32_t llama_vocab::impl::token_to_piece(llama_token token, char * buf, int32_t length, int32_t lstrip, bool special) const {
    wait_for_tokenizer_longhaul();
    // ref: https://github.com/ggml-org/llama.cpp/pull/7587#discussion_r1620983843
    static const int attr_special = LLAMA_TOKEN_ATTR_UNKNOWN | LLAMA_TOKEN_ATTR_CONTROL;
    const llama_token_attr attr = token_get_attr(token);
@@ -3908,7 +4048,11 @@ int32_t llama_vocab::impl::token_to_piece(llama_token token, char * buf, int32_t
    return 0;
 }
-const std::string & llama_vocab::impl::token_to_piece(llama_token token) const {
+std::string llama_vocab::impl::token_to_piece(llama_token token) const {
    wait_for_tokenizer_longhaul();
    if (tokenizer_longhaul) {
        return token_to_piece_for_cache(token, true);
    }
    return cache_token_to_piece.at(token);
 }
@@ -4027,7 +4171,15 @@ int32_t llama_vocab::impl::detokenize(
 void llama_vocab::impl::print_info() const {
    LLAMA_LOG_INFO("%s: vocab type            = %s\n",     __func__, type_name().c_str());
    LLAMA_LOG_INFO("%s: n_vocab               = %u\n",     __func__, vocab.n_tokens());
-    LLAMA_LOG_INFO("%s: n_merges              = %u\n",     __func__, (uint32_t) bpe_ranks.size());
+    LLAMA_LOG_INFO("%s: n_merges              = %u\n",     __func__,
        (uint32_t) (tokenizer_longhaul ? tokenizer_longhaul_n_merges : bpe_ranks.size()));
    if (tokenizer_longhaul) {
        std::lock_guard<std::mutex> lock(tokenizer_longhaul_mutex);
        LLAMA_LOG_INFO("%s: tokenizer longhaul     = %s, cache = %.2f MiB\n", __func__,
            tokenizer_longhaul_state == longhaul_state::ready ? "ready" :
            tokenizer_longhaul_state == longhaul_state::failed ? "failed" : "building",
            tokenizer_longhaul_cache_bytes / 1024.0 / 1024.0);
    }
    // special tokens
    if (special_bos_id  != LLAMA_TOKEN_NULL)    { LLAMA_LOG_INFO( "%s: BOS token             = %d '%s'\n", __func__, special_bos_id,     id_to_token.at(special_bos_id).text.c_str() );  }
@@ -4060,8 +4212,12 @@ llama_vocab::llama_vocab() : pimpl(new impl(*this)) {
 llama_vocab::~llama_vocab() = default;
-void llama_vocab::load(llama_model_loader & ml, const LLM_KV & kv) {
+void llama_vocab::load(
-    pimpl->load(ml, kv);
+        llama_model_loader & ml,
        const LLM_KV & kv,
        bool tokenizer_longhaul,
        uint64_t tokenizer_longhaul_cache_bytes) {
    pimpl->load(ml, kv, tokenizer_longhaul, tokenizer_longhaul_cache_bytes);
 }
 std::string llama_vocab::get_tokenizer_model() const {
@@ -4131,23 +4287,29 @@ llama_token llama_vocab::byte_to_token(uint8_t ch) const {
        case LLAMA_VOCAB_TYPE_SPM:
        case LLAMA_VOCAB_TYPE_UGM: {
            const char buf[7] = { '<', '0', 'x', hex[ch >> 4], hex[ch & 15], '>', 0 };
-            auto token = pimpl->token_to_id.find(buf);
+            const auto token = text_to_token(buf);
-            if (token != pimpl->token_to_id.end()) {
+            if (token != LLAMA_TOKEN_NULL) {
-                return (*token).second;
+                return token;
            }
            // Try to fall back to just the byte as a string
            const char buf2[2] = { (char)ch, 0 };
-            return pimpl->token_to_id.at(buf2);
+            const auto fallback = text_to_token(buf2);
            if (fallback == LLAMA_TOKEN_NULL) throw std::out_of_range("byte token not found");
            return fallback;
        }
        case LLAMA_VOCAB_TYPE_WPM:
        case LLAMA_VOCAB_TYPE_BPE: {
-            return pimpl->token_to_id.at(unicode_byte_to_utf8(ch));
+            const auto token = text_to_token(unicode_byte_to_utf8(ch));
            if (token == LLAMA_TOKEN_NULL) throw std::out_of_range("byte token not found");
            return token;
        }
        case LLAMA_VOCAB_TYPE_PLAMO2: {
            // PLaMo-2 uses byte tokens in format <0xXX>
            char hex_str[8];
            snprintf(hex_str, sizeof(hex_str), "<0x%02X>", ch);
-            return pimpl->token_to_id.at(hex_str);
+            const auto token = text_to_token(hex_str);
            if (token == LLAMA_TOKEN_NULL) throw std::out_of_range("byte token not found");
            return token;
        }
        default:
            GGML_ABORT("fatal error");
@@ -4156,6 +4318,10 @@ llama_token llama_vocab::byte_to_token(uint8_t ch) const {
 llama_token llama_vocab::text_to_token(const std::string & text) const {
    GGML_ASSERT(pimpl->type != LLAMA_VOCAB_TYPE_NONE);
    pimpl->wait_for_tokenizer_longhaul();
    if (pimpl->tokenizer_longhaul_index) {
        return pimpl->tokenizer_longhaul_index->text_to_token(text);
    }
    auto it = pimpl->token_to_id.find(text);
    if (it != pimpl->token_to_id.end()) {
        return (*it).second;
@@ -4165,16 +4331,19 @@ llama_token llama_vocab::text_to_token(const std::string & text) const {
 const llama_vocab::token_data & llama_vocab::get_token_data(llama_token id) const {
    GGML_ASSERT(pimpl->type != LLAMA_VOCAB_TYPE_NONE);
    pimpl->wait_for_tokenizer_longhaul();
    return pimpl->id_to_token.at(id);
 }
 const char * llama_vocab::token_get_text(llama_token id) const {
    GGML_ASSERT(pimpl->type != LLAMA_VOCAB_TYPE_NONE);
    pimpl->wait_for_tokenizer_longhaul();
    return pimpl->id_to_token.at(id).text.c_str();
 }
 float llama_vocab::token_get_score(llama_token id) const {
    GGML_ASSERT(pimpl->type != LLAMA_VOCAB_TYPE_NONE);
    pimpl->wait_for_tokenizer_longhaul();
    return pimpl->id_to_token.at(id).score;
 }
@@ -4306,6 +4475,10 @@ int llama_vocab::find_bpe_rank(const std::string & token_left, const std::string
    GGML_ASSERT(token_left.find(' ')   == std::string::npos);
    GGML_ASSERT(token_right.find(' ')  == std::string::npos);
    pimpl->wait_for_tokenizer_longhaul();
    if (pimpl->tokenizer_longhaul_index) {
        return pimpl->tokenizer_longhaul_index->find_bpe_rank(token_left, token_right);
    }
    auto it = pimpl->bpe_ranks.find(std::make_pair(token_left, token_right));
    if (it == pimpl->bpe_ranks.end()) {
        return -1;
@@ -4315,6 +4488,10 @@ int llama_vocab::find_bpe_rank(const std::string & token_left, const std::string
 }
 std::vector<std::string> llama_vocab::get_bpe_merges() const {
    pimpl->wait_for_tokenizer_longhaul();
    if (pimpl->tokenizer_longhaul_index) {
        return pimpl->tokenizer_longhaul_index->get_bpe_merges();
    }
    int max_rank = -1;
    for (const auto & pair : pimpl->bpe_ranks) {
        max_rank = std::max(max_rank, pair.second);
@@ -4364,7 +4541,7 @@ std::vector<llama_token> llama_vocab::tokenize(
    return pimpl->tokenize(raw_text, add_special, parse_special);
 }
-const std::string & llama_vocab::token_to_piece(llama_token token) const {
+std::string llama_vocab::token_to_piece(llama_token token) const {
    return pimpl->token_to_piece(token);
 }
@@ -86,7 +86,11 @@ struct llama_vocab {
    llama_vocab();
    ~llama_vocab();
-    void load(llama_model_loader & ml, const LLM_KV & kv);
+    void load(
            llama_model_loader & ml,
            const LLM_KV & kv,
            bool tokenizer_longhaul = false,
            uint64_t tokenizer_longhaul_cache_bytes = 0);
    std::string get_tokenizer_model() const;
    std::string get_tokenizer_pre() const;
@@ -181,7 +185,7 @@ struct llama_vocab {
                         bool   special) const;
    // use cached data
-    const std::string & token_to_piece(llama_token token) const;
+    std::string token_to_piece(llama_token token) const;
    int32_t detokenize(
            const llama_token * tokens,
@@ -259,6 +259,8 @@ set_tests_properties(test-thread-safety PROPERTIES FIXTURES_REQUIRED test-downlo
 llama_build_and_test(test-arg-parser.cpp)
 llama_build_and_test(test-longhaul.cpp)
 llama_build_and_test(test-tokenizer-longhaul.cpp
    ARGS ${PROJECT_SOURCE_DIR}/models/ggml-vocab-qwen35.gguf)
 llama_build_and_test(test-token-cache.cpp)
 target_include_directories(test-token-cache PRIVATE ${PROJECT_SOURCE_DIR}/src)
@@ -160,6 +160,21 @@ static void test(void) {
    assert(params.load_mode == LLAMA_LOAD_MODE_LONGHAUL);
    assert(params.longhaul_cache_bytes == 2ULL * 1024 * 1024 * 1024);
    params.tokenizer_longhaul = false;
    params.tokenizer_longhaul_cache_bytes = 0;
    argv = {"binary_name", "--tokenizer-longhaul"};
    assert(false == common_params_parse(argv.size(), list_str_to_char(argv).data(), params, LLAMA_EXAMPLE_COMMON));
    argv = {"binary_name", "--tokenizer-longhaul", "--tokenizer-longhaul-cache", "64"};
    assert(true == common_params_parse(argv.size(), list_str_to_char(argv).data(), params, LLAMA_EXAMPLE_COMMON));
    assert(params.tokenizer_longhaul);
    assert(params.tokenizer_longhaul_cache_bytes == 64ULL * 1024 * 1024);
    params.tokenizer_longhaul = false;
    params.tokenizer_longhaul_cache_bytes = 0;
    argv = {"binary_name", "--tokenizer-longhaul-cache", "64"};
    assert(false == common_params_parse(argv.size(), list_str_to_char(argv).data(), params, LLAMA_EXAMPLE_COMMON));
    argv = {"binary_name", "--token-cache-size", "256", "--token-cache-dir", "/tmp/llama-token-cache-test.sqlite3"};
    assert(true == common_params_parse(argv.size(), list_str_to_char(argv).data(), params, LLAMA_EXAMPLE_COMMON));
    assert(params.token_cache_size_mib == 256);
@@ -0,0 +1,144 @@
 #include "llama.h"
 #include "../src/llama-token-cache.h"
 #include "../src/llama-tokenizer-longhaul.h"
 #include <chrono>
 #include <cstring>
 #include <filesystem>
 #include <string>
 #include <thread>
 #include <vector>
 #undef NDEBUG
 #include <cassert>
 static std::vector<llama_token> tokenize(const llama_vocab * vocab, const std::string & text) {
    int32_t count = llama_tokenize(vocab, text.data(), int32_t(text.size()), nullptr, 0, false, true);
    assert(count < 0);
    std::vector<llama_token> result(size_t(-count));
    count = llama_tokenize(vocab, text.data(), int32_t(text.size()), result.data(), result.size(), false, true);
    assert(count == int32_t(result.size()));
    return result;
 }
 int main(int argc, char ** argv) {
    namespace fs = std::filesystem;
    const fs::path root = fs::temp_directory_path() /
        ("llama-tokenizer-longhaul-test-" + std::to_string(
            std::chrono::high_resolution_clock::now().time_since_epoch().count()));
    const std::string db = (root / "token-cache.sqlite3").string();
    const llama_token_cache_params params = {
        db.c_str(),
        128 * 1024 * 1024,
    };
    assert(llama_token_cache_configure(params));
    assert(llama_token_cache_clear());
    std::vector<llama_tokenizer_longhaul_reverse> reverse;
    std::vector<llama_tokenizer_longhaul_merge> merges;
    for (int i = 0; i < 200; ++i) {
        reverse.push_back({"token-" + std::to_string(i), i});
        if (i > 0) {
            merges.push_back({
                "token-" + std::to_string(i - 1),
                "token-" + std::to_string(i),
                i - 1,
            });
        }
    }
    {
        llama_tokenizer_longhaul_index index("source:test", 512);
        std::string error;
        assert(index.prepare(reverse, merges, "tokenizer-id", error));
        assert(error.empty());
        assert(index.n_merges() == merges.size());
        for (int i = 0; i < 200; ++i) {
            assert(index.text_to_token("token-" + std::to_string(i)) == i);
        }
        assert(index.text_to_token("missing") == LLAMA_TOKEN_NULL);
        for (int i = 1; i < 200; ++i) {
            assert(index.find_bpe_rank(
                "token-" + std::to_string(i - 1),
                "token-" + std::to_string(i)) == i - 1);
        }
        assert(index.find_bpe_rank("missing", "pair") == -1);
        assert(index.cache_bytes_used() <= index.cache_capacity());
        const auto loaded_merges = index.get_bpe_merges();
        assert(loaded_merges.size() == merges.size());
        assert(loaded_merges.front() == "token-0 token-1");
        assert(loaded_merges.back() == "token-198 token-199");
    }
    // A warm open must use the completed artifact even without rebuild inputs.
    {
        llama_tokenizer_longhaul_index index("source:test", 128);
        std::string error;
        assert(index.prepare({}, {}, "tokenizer-id", error));
        assert(index.text_to_token("token-42") == 42);
        std::vector<std::thread> workers;
        for (int thread = 0; thread < 4; ++thread) {
            workers.emplace_back([&index, thread] {
                for (int i = thread; i < 200; i += 4) {
                    assert(index.text_to_token("token-" + std::to_string(i)) == i);
                }
            });
        }
        for (auto & worker : workers) worker.join();
        assert(index.cache_bytes_used() <= index.cache_capacity());
    }
    if (argc > 1) {
        llama_backend_init();
        llama_model_params normal_params = llama_model_default_params();
        normal_params.vocab_only = true;
        llama_model * normal = llama_model_load_from_file(argv[1], normal_params);
        assert(normal != nullptr);
        llama_model_kv_override overrides[2] = {};
        std::strcpy(overrides[0].key, "general.architecture");
        overrides[0].tag = LLAMA_KV_OVERRIDE_TYPE_STR;
        std::strcpy(overrides[0].val_str, "qwen35moe");
        llama_model_params longhaul_params = llama_model_default_params();
        longhaul_params.vocab_only = true;
        longhaul_params.kv_overrides = overrides;
        longhaul_params.tokenizer_longhaul = true;
        longhaul_params.tokenizer_longhaul_cache_bytes = 1024;
        llama_model * longhaul = llama_model_load_from_file(argv[1], longhaul_params);
        assert(longhaul != nullptr);
        const llama_vocab * normal_vocab = llama_model_get_vocab(normal);
        const llama_vocab * longhaul_vocab = llama_model_get_vocab(longhaul);
        for (const std::string & text : {
                "Hello, world!",
                " tokenizer longhaul",
                "Qwen3.5: 12345\n",
                "<|im_end|>",
                "Unicode: Καλημέρα 世界 🚚",
            }) {
            const auto expected = tokenize(normal_vocab, text);
            const auto actual = tokenize(longhaul_vocab, text);
            assert(actual == expected);
            for (const auto token : actual) {
                assert(std::strcmp(
                    llama_vocab_get_text(normal_vocab, token),
                    llama_vocab_get_text(longhaul_vocab, token)) == 0);
            }
        }
        llama_model_free(longhaul);
        llama_model_free(normal);
        llama_backend_free();
    }
    assert(llama_token_cache_clear());
    std::error_code ec;
    fs::remove_all(root, ec);
    return 0;
 }
@@ -35,6 +35,8 @@
 | `--token-cache-size N` | shared tokenizer and tokenized-text cache size in MiB (default: 5120, 0 = disable)<br/>(env: LLAMA_ARG_TOKEN_CACHE_SIZE) |
 | `--token-cache-dir PATH` | path to the shared tokenizer and tokenized-text cache database<br/>(env: LLAMA_ARG_TOKEN_CACHE_DIR) |
 | `--token-cache-clear` | clear the shared tokenizer and tokenized-text cache before loading the model<br/>(env: LLAMA_ARG_TOKEN_CACHE_CLEAR) |
 | `--tokenizer-longhaul` | build and page the Qwen3.5/Laguna tokenizer through a bounded cache<br/>(env: LLAMA_ARG_TOKENIZER_LONGHAUL) |
 | `--tokenizer-longhaul-cache N` | tokenizer-longhaul RAM cache size in MiB<br/>(env: LLAMA_ARG_TOKENIZER_LONGHAUL_CACHE) |
 | `-fa, --flash-attn [on\|off\|auto]` | set Flash Attention use ('on', 'off', or 'auto', default: 'auto')<br/>(env: LLAMA_ARG_FLASH_ATTN) |
 | `-p, --prompt PROMPT` | prompt to start generation with; for system message, use -sys |
 | `--perf, --no-perf` | whether to enable internal libllama performance timings (default: false)<br/>(env: LLAMA_ARG_PERF) |
@@ -118,6 +118,8 @@ llama-completion.exe -m models\gemma-1.1-7b-it.Q4_K_M.gguf --ignore-eos -n -1
 | `--token-cache-size N` | shared tokenizer and tokenized-text cache size in MiB (default: 5120, 0 = disable)<br/>(env: LLAMA_ARG_TOKEN_CACHE_SIZE) |
 | `--token-cache-dir PATH` | path to the shared tokenizer and tokenized-text cache database<br/>(env: LLAMA_ARG_TOKEN_CACHE_DIR) |
 | `--token-cache-clear` | clear the shared tokenizer and tokenized-text cache before loading the model<br/>(env: LLAMA_ARG_TOKEN_CACHE_CLEAR) |
 | `--tokenizer-longhaul` | build and page the Qwen3.5/Laguna tokenizer through a bounded cache<br/>(env: LLAMA_ARG_TOKENIZER_LONGHAUL) |
 | `--tokenizer-longhaul-cache N` | tokenizer-longhaul RAM cache size in MiB<br/>(env: LLAMA_ARG_TOKENIZER_LONGHAUL_CACHE) |
 | `-fa, --flash-attn [on\|off\|auto]` | set Flash Attention use ('on', 'off', or 'auto', default: 'auto')<br/>(env: LLAMA_ARG_FLASH_ATTN) |
 | `-p, --prompt PROMPT` | prompt to start generation with; for system message, use -sys |
 | `--perf, --no-perf` | whether to enable internal libllama performance timings (default: false)<br/>(env: LLAMA_ARG_PERF) |
@@ -57,6 +57,8 @@ test parameters:
  -ctk, --cache-type-k <t>                  (default: f16)
  -ctv, --cache-type-v <t>                  (default: f16)
  --longhaul-cache <GiB>                    expert cache size for longhaul mode
  --tokenizer-longhaul                      page tokenizer indexes through a bounded cache
  --tokenizer-longhaul-cache <MiB>          tokenizer lookup cache size
  -t, --threads <n>                         (default: system dependent)
  -C, --cpu-mask <hex,hex>                  (default: 0x0)
  --cpu-strict <0|1>                        (default: 0)
@@ -342,6 +342,8 @@ struct cmd_params {
    std::vector<llama_split_mode>    split_mode;
    std::vector<llama_load_mode>     load_mode;
    uint64_t                         longhaul_cache_bytes;
    bool                             tokenizer_longhaul;
    uint64_t                         tokenizer_longhaul_cache_bytes;
    std::vector<int>                 main_gpu;
    std::vector<bool>                no_kv_offload;
    std::vector<llama_flash_attn_type> flash_attn;
@@ -387,6 +389,8 @@ static const cmd_params cmd_params_defaults = {
    /* split_mode           */ { LLAMA_SPLIT_MODE_LAYER },
    /* load_mode            */ { LLAMA_LOAD_MODE_MMAP },
    /* longhaul_cache_bytes */ 0,
    /* tokenizer_longhaul   */ false,
    /* tokenizer_longhaul_cache_bytes */ 0,
    /* main_gpu             */ { 0 },
    /* no_kv_offload        */ { false },
    /* flash_attn           */ { LLAMA_FLASH_ATTN_TYPE_AUTO },
@@ -463,6 +467,8 @@ static void print_usage(int /* argc */, char ** argv) {
    printf("  -dev, --device <dev0/dev1/...>                    (default: auto)\n");
    printf("  -lm, --load-mode <none|mmap|mlock|mmap+mlock|dio|longhaul> (default: %s)\n", join(transform_to_str(cmd_params_defaults.load_mode, llama_load_mode_name), ",").c_str());
    printf("  --longhaul-cache <GiB>                           expert cache size for longhaul mode\n");
    printf("  --tokenizer-longhaul                             page tokenizer indexes through a bounded cache\n");
    printf("  --tokenizer-longhaul-cache <MiB>                 tokenizer lookup cache size (required with --tokenizer-longhaul)\n");
    printf("  -mmp, --mmap <0|1>                                (DEPRECATED IN FAVOUR OF --load-mode)\n");
    printf("  -dio, --direct-io <0|1>                           (DEPRECATED IN FAVOUR OF --load-mode)\n");
    printf("  -embd, --embeddings <0|1>                         (default: %s)\n", join(cmd_params_defaults.embeddings, ",").c_str());
@@ -525,6 +531,8 @@ static cmd_params parse_cmd_params(int argc, char ** argv) {
    params.no_warmup            = cmd_params_defaults.no_warmup;
    params.offline              = cmd_params_defaults.offline;
    params.longhaul_cache_bytes = cmd_params_defaults.longhaul_cache_bytes;
    params.tokenizer_longhaul = cmd_params_defaults.tokenizer_longhaul;
    params.tokenizer_longhaul_cache_bytes = cmd_params_defaults.tokenizer_longhaul_cache_bytes;
    if (const char * env = getenv("HF_TOKEN")) {
        params.hf_token = env;
@@ -801,6 +809,19 @@ static cmd_params parse_cmd_params(int argc, char ** argv) {
                    break;
                }
                params.longhaul_cache_bytes = gib * 1024 * 1024 * 1024;
            } else if (arg == "--tokenizer-longhaul") {
                params.tokenizer_longhaul = true;
            } else if (arg == "--tokenizer-longhaul-cache") {
                if (++i >= argc) {
                    invalid_param = true;
                    break;
                }
                const uint64_t mib = std::stoull(argv[i]);
                if (mib == 0 || mib > UINT64_MAX / 1024 / 1024) {
                    invalid_param = true;
                    break;
                }
                params.tokenizer_longhaul_cache_bytes = mib * 1024 * 1024;
            } else if (arg == "-mg" || arg == "--main-gpu") {
                if (++i >= argc) {
                    invalid_param = true;
@@ -1157,6 +1178,10 @@ static cmd_params parse_cmd_params(int argc, char ** argv) {
        fprintf(stderr, "error: longhaul load mode requires --longhaul-cache N\n");
        exit(1);
    }
    if (params.tokenizer_longhaul != (params.tokenizer_longhaul_cache_bytes != 0)) {
        fprintf(stderr, "error: --tokenizer-longhaul and --tokenizer-longhaul-cache must be used together\n");
        exit(1);
    }
    if (params.main_gpu.empty()) {
        params.main_gpu = cmd_params_defaults.main_gpu;
    }
@@ -1224,6 +1249,8 @@ struct cmd_params_instance {
    llama_split_mode   split_mode;
    llama_load_mode    load_mode;
    uint64_t           longhaul_cache_bytes;
    bool               tokenizer_longhaul;
    uint64_t           tokenizer_longhaul_cache_bytes;
    int                main_gpu;
    bool               no_kv_offload;
    llama_flash_attn_type flash_attn;
@@ -1246,6 +1273,8 @@ struct cmd_params_instance {
        mparams.split_mode    = split_mode;
        mparams.load_mode     = load_mode;
        mparams.longhaul_cache_bytes = longhaul_cache_bytes;
        mparams.tokenizer_longhaul = tokenizer_longhaul;
        mparams.tokenizer_longhaul_cache_bytes = tokenizer_longhaul_cache_bytes;
        mparams.main_gpu      = main_gpu;
        mparams.tensor_split  = tensor_split.data();
        mparams.no_host       = no_host;
@@ -1294,6 +1323,8 @@ struct cmd_params_instance {
               split_mode == other.split_mode &&
               main_gpu == other.main_gpu && tensor_split == other.tensor_split &&
               load_mode == other.load_mode && longhaul_cache_bytes == other.longhaul_cache_bytes &&
               tokenizer_longhaul == other.tokenizer_longhaul &&
               tokenizer_longhaul_cache_bytes == other.tokenizer_longhaul_cache_bytes &&
               devices == other.devices && no_host == other.no_host &&
               vec_tensor_buft_override_equal(tensor_buft_overrides, other.tensor_buft_overrides);
    }
@@ -1368,6 +1399,8 @@ static std::vector<cmd_params_instance> get_cmd_params_instances(const cmd_param
                /* .split_mode            = */ sm,
                /* .load_mode             = */ lm,
                /* .longhaul_cache_bytes  = */ params.longhaul_cache_bytes,
                /* .tokenizer_longhaul    = */ params.tokenizer_longhaul,
                /* .tokenizer_longhaul_cache_bytes = */ params.tokenizer_longhaul_cache_bytes,
                /* .main_gpu              = */ mg,
                /* .no_kv_offload         = */ nkvo,
                /* .flash_attn            = */ fa,
@@ -1405,6 +1438,8 @@ static std::vector<cmd_params_instance> get_cmd_params_instances(const cmd_param
                /* .split_mode            = */ sm,
                /* .load_mode             = */ lm,
                /* .longhaul_cache_bytes  = */ params.longhaul_cache_bytes,
                /* .tokenizer_longhaul    = */ params.tokenizer_longhaul,
                /* .tokenizer_longhaul_cache_bytes = */ params.tokenizer_longhaul_cache_bytes,
                /* .main_gpu              = */ mg,
                /* .no_kv_offload         = */ nkvo,
                /* .flash_attn            = */ fa,
@@ -1442,6 +1477,8 @@ static std::vector<cmd_params_instance> get_cmd_params_instances(const cmd_param
                /* .split_mode            = */ sm,
                /* .load_mode             = */ lm,
                /* .longhaul_cache_bytes  = */ params.longhaul_cache_bytes,
                /* .tokenizer_longhaul    = */ params.tokenizer_longhaul,
                /* .tokenizer_longhaul_cache_bytes = */ params.tokenizer_longhaul_cache_bytes,
                /* .main_gpu              = */ mg,
                /* .no_kv_offload         = */ nkvo,
                /* .flash_attn            = */ fa,
@@ -1484,6 +1521,8 @@ struct test {
    llama_split_mode         split_mode;
    llama_load_mode          load_mode;
    uint64_t                 longhaul_cache_bytes;
    bool                     tokenizer_longhaul;
    uint64_t                 tokenizer_longhaul_cache_bytes;
    int                      main_gpu;
    bool                     no_kv_offload;
    llama_flash_attn_type    flash_attn;
@@ -1524,6 +1563,8 @@ struct test {
        split_mode     = inst.split_mode;
        load_mode      = inst.load_mode;
        longhaul_cache_bytes = inst.longhaul_cache_bytes;
        tokenizer_longhaul = inst.tokenizer_longhaul;
        tokenizer_longhaul_cache_bytes = inst.tokenizer_longhaul_cache_bytes;
        main_gpu       = inst.main_gpu;
        no_kv_offload  = inst.no_kv_offload;
        flash_attn     = inst.flash_attn;
@@ -1591,7 +1632,8 @@ struct test {
            "n_ubatch",       "n_threads",      "cpu_mask",      "cpu_strict",     "poll",
            "type_k",         "type_v",         "n_gpu_layers",  "n_cpu_moe",      "split_mode",
            "main_gpu",       "no_kv_offload",  "flash_attn",    "devices",        "tensor_split",
-            "tensor_buft_overrides",            "load_mode",     "longhaul_cache_bytes", "embeddings",
+            "tensor_buft_overrides",            "load_mode",     "longhaul_cache_bytes",
            "tokenizer_longhaul", "tokenizer_longhaul_cache_bytes", "embeddings",
            "no_op_offload",  "no_host",        "fit_target",    "fit_min_ctx",
            "n_prompt",       "n_gen",          "n_depth",
            "test_time",      "avg_ns",         "stddev_ns",     "avg_ts",         "stddev_ts"
@@ -1607,11 +1649,11 @@ struct test {
            field == "main_gpu" || field == "n_prompt" || field == "n_gen" || field == "n_depth" || field == "avg_ns" ||
            field == "stddev_ns" || field == "no_op_offload" || field == "n_cpu_moe" ||
            field == "fit_target" || field == "fit_min_ctx" || field == "flash_attn" ||
-            field == "longhaul_cache_bytes") {
+            field == "longhaul_cache_bytes" || field == "tokenizer_longhaul_cache_bytes") {
            return INT;
        }
        if (field == "f16_kv" || field == "no_kv_offload" || field == "cpu_strict" ||
-            field == "embeddings" || field == "no_host") {
+            field == "embeddings" || field == "no_host" || field == "tokenizer_longhaul") {
            return BOOL;
        }
        if (field == "avg_ts" || field == "stddev_ts") {
@@ -1688,6 +1730,8 @@ struct test {
                                            tensor_buft_overrides_str,
                                            llama_load_mode_name(load_mode),
                                            std::to_string(longhaul_cache_bytes),
                                            std::to_string(tokenizer_longhaul),
                                            std::to_string(tokenizer_longhaul_cache_bytes),
                                            std::to_string(embeddings),
                                            std::to_string(no_op_offload),
                                            std::to_string(no_host),
@@ -2005,6 +2049,12 @@ struct markdown_printer : public printer {
        if (params.longhaul_cache_bytes != cmd_params_defaults.longhaul_cache_bytes) {
            fields.emplace_back("longhaul_cache_bytes");
        }
        if (params.tokenizer_longhaul != cmd_params_defaults.tokenizer_longhaul) {
            fields.emplace_back("tokenizer_longhaul");
        }
        if (params.tokenizer_longhaul_cache_bytes != cmd_params_defaults.tokenizer_longhaul_cache_bytes) {
            fields.emplace_back("tokenizer_longhaul_cache_bytes");
        }
        if (params.embeddings.size() > 1 || params.embeddings != cmd_params_defaults.embeddings) {
            fields.emplace_back("embeddings");
        }
@@ -56,6 +56,8 @@ For the full list of features, please refer to [server's changelog](https://gith
 | `--token-cache-size N` | shared tokenizer and tokenized-text cache size in MiB (default: 5120, 0 = disable)<br/>(env: LLAMA_ARG_TOKEN_CACHE_SIZE) |
 | `--token-cache-dir PATH` | path to the shared tokenizer and tokenized-text cache database<br/>(env: LLAMA_ARG_TOKEN_CACHE_DIR) |
 | `--token-cache-clear` | clear the shared tokenizer and tokenized-text cache before loading the model<br/>(env: LLAMA_ARG_TOKEN_CACHE_CLEAR) |
 | `--tokenizer-longhaul` | build and page the Qwen3.5/Laguna tokenizer through a bounded cache<br/>(env: LLAMA_ARG_TOKENIZER_LONGHAUL) |
 | `--tokenizer-longhaul-cache N` | tokenizer-longhaul RAM cache size in MiB<br/>(env: LLAMA_ARG_TOKENIZER_LONGHAUL_CACHE) |
 | `-fa, --flash-attn [on\|off\|auto]` | set Flash Attention use ('on', 'off', or 'auto', default: 'auto')<br/>(env: LLAMA_ARG_FLASH_ATTN) |
 | `--perf, --no-perf` | whether to enable internal libllama performance timings (default: false)<br/>(env: LLAMA_ARG_PERF) |
 | `-e, --escape, --no-escape` | whether to process escapes sequences (\n, \r, \t, \', \", \\) (default: true) |