Zing Forum

Reading

clickpaca: A Fine-Grained Control Engine for Local LLM Inference

clickpaca is a local large language model (LLM) inference server based on llama.cpp, enabling fine-grained token-level control via NDJSON streaming communication. It supports advanced features such as syntax constraints, logit bias, multi-sequence batch processing, and TurboQuant KV cache compression, filling the gaps in model control present in existing tools.

llama.cpp本地推理token控制KV缓存压缩TurboQuantNDJSON语法约束logit偏置批处理
Published 2026-04-22 08:42Recent activity 2026-04-22 12:01Estimated read 4 min
clickpaca: A Fine-Grained Control Engine for Local LLM Inference
1

Section 01

clickpaca: A Fine-Grained Control Engine for Local LLM Inference (Main Thread)

clickpaca is a local LLM inference server based on llama.cpp, designed to provide token-level fine control via NDJSON streaming communication. It addresses gaps in existing tools (Ollama, LM Studio, llama.cpp HTTP server) by supporting syntax constraints, logit bias, multi-sequence batch processing, and TurboQuant KV cache compression. This thread will break down its design, capabilities, and value.

2

Section 02

Project Background & Design Philosophy

clickpaca's name combines 'Clicker' (from The Last of Us, symbolizing full control) and 'Alpaca' (open-source LLM lineage). It aims to solve limitations of existing tools: Ollama lacks per-request syntax constraints and uses queue processing; LM Studio has no batch API; llama.cpp HTTP server can't combine logit biases or handle real concurrency.

3

Section 03

Architecture: NDJSON Streaming Communication

clickpaca uses NDJSON (Newline Delimited JSON) over stdin/stdout for bidirectional streaming. This balances complexity and maintainability: HTTP requires port management; FFI has API change issues. NDJSON allows easy testing (printf pipes), sub-process replacement, and SSH transport without protocol changes.

4

Section 04

Core Capability: Composable Token Guidance

clickpaca features a unique sampler chain: syntax constraints (zero invalid tokens) → logit bias (adjust distribution) → repeat penalty → sampling. This enables combining enforcing specific output formats (via "JSON Schema" or GBNF) and blocking specific tokens—something mainstream servers can't do.

5

Section 05

Core Capability: Multi-Sequence Batch Processing

Up to 8 concurrent sequences share one llama_decode call, each with independent constraints (e.g., JSON schema, GBNF + logit bias). Unlike HTTP servers (per-request context), this improves resource utilization and throughput for multi-request scenarios.

6

Section 06

Core Capability: TurboQuant KV Cache Compression

TurboQuant (ICLR 2026) uses random Hadamard transforms to redistribute energy before quantization, achieving ~5x compression. clickpaca offers turbo2 (6.1x), turbo3 (4.9x), turbo4 (3.8x) levels. Example: 8 sequences' f16 cache (800MiB) → turbo3 (160MiB), freeing memory for more sequences.

7

Section 07

Performance Benchmarks

WikiText-2 perplexity: turbo4 (50.483) outperforms f16 (52.995). Apple Silicon speed: f16 (48.8 tok/s) vs turbo4 (31.4 tok/s)—a 35% speed trade for 3.8x memory efficiency.

8

Section 08

Application Scenarios & Value

clickpaca excels in structured data generation (JSON Schema compliance), content safety (forbid tokens), domain vocab enhancement, high concurrency, and edge deployment. It uniquely combines all key features in one process/forward pass for developers needing ultimate control.