diff --git a/README.md b/README.md index f3f53aa..9f587d8 100644 --- a/README.md +++ b/README.md @@ -6,257 +6,193 @@ [![Binary Size](https://img.shields.io/badge/binary-305%20KB-brightgreen)](TECHNOLOGY.md) [![Backends](https://img.shields.io/badge/backends-19-orange)](ARCHITECTURE.md) -**Better output from the same model.** +**Run AI on your own computer. Private. Free. No internet.** -One binary routes any AI model to any hardware — from a microcontroller to a datacenter. Fused computation, adaptive precision, surgical expert loading. No dependencies. No framework. No vendor lock-in. - -305 KB. 19 hardware backends. Any model. Any scale. - -Built in Morocco by [Salka Elmadani](https://x.com/ElmadaniSa13111). - -> *In the Anti-Atlas, our ancestors built khettaras — underground water channels that deliver pure water to villages without pumps, without electricity, without filtration. The water arrives cleaner than any treated supply because the path itself is the filter. Inference-X works the same way: the shortest path produces the cleanest signal.* +Inference-X is a tiny file (305 KB) that lets any computer run AI models locally. It works on old laptops, phones, Raspberry Pi, and datacenters — same file, no setup. Your questions stay on your machine. Nobody sees them. **[Website](https://inference-x.com)** · **[How it works](TECHNOLOGY.md)** · **[Benchmarks](BENCHMARKS.md)** · **[Vision](VISION.md)** · **[Sponsor](https://github.com/sponsors/ElmadaniS)** --- +## Start in 30 seconds + +```bash +git clone https://github.com/ElmadaniS/inference-x +cd inference-x && make +./inference-x model.gguf +``` + +That's it. Download a `.gguf` model from [HuggingFace](https://huggingface.co/models?sort=trending&search=gguf), run the command, talk to AI. No account. No API key. No internet. + +Add `--serve 8080` to get a web interface at `localhost:8080`. + +--- + +## What can your computer run? + +| Your RAM | Models you can run | What it can do | +|---|---|---| +| **2 GB** | SmolLM2 135M | Simple assistant, quick answers | +| **4 GB** | Phi-3 Mini 3.8B, Llama 3.2 3B | Smart conversations, code help, translations | +| **8 GB** | Mistral 7B, Llama 3.1 8B | Creative writing, analysis, reasoning | +| **16 GB** | DeepSeek R1 14B | Advanced reasoning, expert-level answers | +| **32 GB** | Qwen 2.5 32B | Professional-grade AI | +| **64 GB** | Llama 3.1 70B, DeepSeek V3 MoE | Frontier performance, locally | + +Every model runs privately, offline, with no subscription. + +--- + +## Why local AI matters + +When you use AI online, your words travel to a server in another country. Someone can read them. You pay per word. The service can shut down. + +With Inference-X, your questions stay on your desk. The answer is computed by your own processor. Nothing leaves. Nothing is stored. It works without internet. It's free forever. + +--- + ## What makes it different -Most inference engines add layers between the model and the hardware: frameworks, runtime allocators, intermediate buffers, uniform precision pipelines. Each layer adds computational overhead that degrades the model's original signal. +Most inference engines add layers between the model and the hardware: frameworks, runtime allocators, intermediate buffers. Each layer degrades the model's signal. Inference-X removes those layers. -**Fused computation** — Dequantization and matrix multiply happen in a single instruction loop. No intermediate FP32 buffer. Fewer rounding operations means output closer to the model's theoretical FP32 maximum. +**Fused computation** — Dequantization and matrix multiply happen in a single instruction loop. No intermediate FP32 buffer. Output closer to the model's theoretical maximum. -**Adaptive precision** — Each query is analyzed before inference. Simple questions get compressed early layers and full-precision decision layers. Complex reasoning gets full precision throughout. The model adapts its depth to the question — same file, same binary, different computational path. +**Adaptive precision** — Each query is analyzed before inference. Simple questions get compressed early layers and full-precision decision layers. Complex reasoning gets full precision throughout. -**Surgical expert loading** — For Mixture-of-Experts models, only active experts exist in memory. Inactive experts are evicted at the OS level. Result: a 1-trillion-parameter model runs on 17 GB of RAM. The signal path contains only what contributes to the current token. +**Surgical expert loading** — For Mixture-of-Experts models, only active experts exist in memory. A 1-trillion-parameter model runs on 64 GB of RAM. -The result: **the same model produces higher-fidelity output through a cleaner computation path.** Or equivalently: a smaller model through Inference-X can match a larger model through a conventional engine. +The result: **the same model produces better output through a cleaner computation path.** A smaller model through Inference-X can match a larger model through a conventional engine. → [Full technical explanation](TECHNOLOGY.md) --- -## What it is +## How it works -TCP/IP routes data packets to any network, any hardware, any destination. The protocol doesn't care about the wire. +TCP/IP routes data packets to any network. Inference-X routes intelligence to any silicon. -Inference-X routes intelligence to any silicon. The protocol doesn't care about the chip. - -One function call enters `kernel_dispatch.h`. On the other side: CPU, GPU, TPU, LPU, IPU, FPGA, DSP, or WSE. The caller doesn't know. Doesn't need to. The model runs. The answer comes back. +One function call enters `kernel_dispatch.h`. On the other side: CPU, GPU, TPU, LPU, IPU, FPGA, DSP, or WSE. The model runs. The answer comes back. ``` Model (any GGUF) → Inference-X (305 KB) → Silicon (any of 19 backends) → Response ``` -The model describes itself. The engine reads the description. The engine never assumes. - - -## Quick Start - -```bash -git clone https://github.com/ElmadaniS/inference-x -cd inference-x -make - -# Download a model (any GGUF from Hugging Face) -./inference-x model.gguf -p "Hello, world" +``` +Architecture: + infer.cpp (570 lines) — Orchestrator. Chat templates. Server mode. + transformer_v6.h — Forward pass. Dense + MoE + MLA unified. + kernel_dispatch.h — Routes GEMM to the right silicon. + moe_mla.h — Expert selection. Prefetch. Eviction. + gemm.h — Fused dequant × matmul kernels. + backends.h — 19 hardware targets. One interface. ``` -That's it. One binary. One command. Any model. - - -## Why it matters - -Running a model today requires choosing a stack: CUDA for NVIDIA, ROCm for AMD, Metal for Apple, TensorRT for serving, vLLM for throughput, Ollama for local. Each stack locks you to a vendor, a way of thinking, and adds its own computational overhead between the model and the result. - -Inference-X eliminates the stack. There is no stack. There's a model file, a binary, and your hardware — whatever it is. - -``` -GPU cluster: 1T parameters on 8× H100 ~5.6 kW, $200,000+/year -Inference-X: 1T parameters on 256 GB RAM ~300 W, €4,800/year - -Same model. Cleaner output. 97% less cost. -``` - -This isn't about replacing GPUs. It's about making the choice of silicon irrelevant to the act of thinking — and getting *better* results from the silicon you already have. - - -## Who is this for - -**Every organization that runs AI models — or wants to.** - -| Sector | Problem | What IX does | -|--------|---------|-------------| -| **Healthcare** | Patient data can't leave the hospital. Cloud inference = compliance risk. | Air-gapped inference on hospital hardware. Zero network calls. HIPAA/GDPR by architecture. | -| **Defense & Government** | Sovereign AI requires sovereign infrastructure. | Runs on government-owned hardware. No vendor dependency. No telemetry. Auditable source. | -| **Finance** | Trading models need low latency and full auditability. | On-premise inference, deterministic output, no external calls. | -| **Telecom** | Edge inference at cell towers for real-time processing. | 305 KB binary deploys on edge hardware. Adaptive precision matches available power. | -| **Automotive** | In-vehicle AI needs minimal footprint and guaranteed response. | Runs on ARM/Snapdragon. No framework overhead. Fits in L2 cache. | -| **Startups** | GPU costs eat runway. $200K/year for inference infrastructure. | Same model quality at 97% lower cost. CPU-only. Scale when you're ready. | -| **Enterprise** | Vendor lock-in across NVIDIA, AMD, Intel, cloud providers. | 19 backends. One binary. Switch hardware without changing code. | -| **Research & Education** | Limited compute budgets. Students can't afford H100s. | Free under BSL-1.1. Run 14B models on a €20/month server. | -| **Embedded / IoT** | AI on microcontrollers with KB-level memory budgets. | Compiles for ESP32. Surgical loading keeps memory minimal. | -| **Cloud Providers** | Offering inference services at competitive margins. | Higher output quality per compute dollar. 19 backends = any customer hardware. | - -Inference-X has zero friction with existing infrastructure. It doesn't replace your hardware — it makes your hardware work better. - - -## Get started - -```bash -# Build (30 seconds) -git clone https://github.com/ElmadaniS/inference-x.git -cd inference-x && make -j$(nproc) - -# Chat with any GGUF model -./inference-x model.gguf -i - -# Or start a web interface -python3 web/ix_server.py - -# Or run as an OpenAI-compatible API -./inference-x model.gguf --serve --port 8080 -``` - -Three commands. No dependencies. No Docker. No Python packages. No GPU drivers. Just `make` and run. +12,571 lines of C++17. 6 architectures (Llama, Qwen2, Gemma2, Phi, DeepSeek MoE, MLA). 23 quantization formats. One binary. +--- ## Benchmarks -Real numbers on a €20/month AMD EPYC server. CPU-only. No GPU. Cold start. +AMD EPYC Rome · 17 GB RAM · 6 cores · CPU-only · €20/month server -| Model | Params | Quant | tok/s | -|-------|--------|-------|-------| -| SmolLM2 | 135M | Q8_0 | **130.23** | -| Llama 3.2 | 3B | Q4_K_M | **3.82** | -| Qwen 2.5 | 3B | Q4_K_M | **3.85** | -| Mistral 7B | 7B | Q4_K_M | **2.06** | -| Qwen 2.5 | 7B | Q4_K_M | **1.82** | -| Llama 3.1 | 8B | Q4_K_M | **1.75** | -| Gemma 2 | 9B | Q4_K_M | **1.28** | -| DS-R1 Qwen | 14B | Q4_K_M | **0.97** | +| Model | Params | Quant | tok/s | Prefill | +|---|---|---|---|---| +| SmolLM2 | 135M | Q8_0 | **130.23** | 87 ms | +| Qwen 2.5 | 3B | Q4_K_M | **3.85** | 16.5 s | +| Llama 3.2 | 3B | Q4_K_M | **3.82** | 3.8 s | +| Mistral 7B | 7B | Q4_K_M | **2.06** | 39.2 s | +| Llama 3.1 | 8B | Q4_K_M | **1.75** | 43.0 s | +| DeepSeek R1 | 14B | Q4_K_M | **0.97** | 74.1 s | -9/10 architectures passing. Chat templates auto-detected. Zero manual configuration. +9 models · 4 architectures · Same binary · Zero configuration -→ [Full benchmark details](BENCHMARKS.md) +→ [Full benchmarks](BENCHMARKS.md) +--- ## Supported Hardware -| Backend | Silicon | Status | -|---------|---------|--------| -| CPU (AVX2/AVX-512) | Intel, AMD | ✅ Production | +| Backend | Target | Status | +|---|---|---| +| CPU AVX2/512 | Intel, AMD | ✅ Production | | CUDA | NVIDIA GPU | ✅ Production | | ROCm | AMD GPU | ✅ Production | | Metal | Apple Silicon | ✅ Production | -| Vulkan | Cross-platform GPU | ✅ Production | -| ARM NEON | ARM processors | ✅ Production | -| Snapdragon | Qualcomm (GPU+DSP+NEON) | 🔧 Ready | -| Hexagon HVX | Qualcomm DSP | 🔧 Ready | -| OpenCL | Cross-platform | 🔧 Ready | -| WebGPU | Browser | 🔧 Ready | -| TPU | Google | 🔧 Ready | -| Inferentia | AWS | 🔧 Ready | -| Gaudi | Intel HPU | 🔧 Ready | -| Maia | Microsoft | 🔧 Ready | -| SambaNova RDU | SambaNova | 🔧 Ready | -| Graphcore IPU | Graphcore | 🔧 Ready | -| Groq LPU | Groq | 🔧 Ready | -| FPGA (Xilinx) | Xilinx | 🔧 Ready | -| Cerebras WSE | Cerebras | 🔧 Ready | +| Vulkan | Cross-platform | ✅ Production | +| ARM NEON | ARM (Pi, phones) | ✅ Production | +| Snapdragon | Qualcomm | 🔶 Ready | +| Hexagon HVX | Qualcomm DSP | 🔶 Ready | +| TPU | Google | 🔶 Ready | +| Inferentia | AWS | 🔶 Ready | +| Gaudi | Intel HPU | 🔶 Ready | +| Maia | Microsoft | 🔶 Ready | +| SambaNova RDU | SambaNova | 🔶 Ready | +| Graphcore IPU | Graphcore | 🔶 Ready | +| Groq LPU | Groq | 🔶 Ready | +| Cerebras WSE | 850K cores | 🔶 Ready | +| FPGA | Xilinx | 🔶 Ready | +| WebGPU | Browser | 🔶 Ready | +| OpenCL | Universal | 🔶 Ready | +The Makefile detects your hardware. You don't configure it. -## Architecture - -``` -infer.cpp ← Entry point (571 lines) -├── runtime/ -│ ├── gguf.h ← GGUF parser + config extraction -│ ├── tokenizer.h ← Tokenizer with byte-level BPE -│ ├── transformer_v6.h ← Universal forward pass -│ ├── attention.h ← GQA attention -│ ├── moe_mla.h ← MoE + MLA (DeepSeek V3) -│ ├── gemm.h ← Fused GEMV kernels -│ ├── kernels.h ← RMS norm, softmax, RoPE, SiLU -│ ├── kernel_dispatch.h ← Hardware routing layer -│ ├── server.h ← OpenAI-compatible API server -│ └── ... -├── core/ -│ ├── iq_tables.h ← IQ quantization lookup tables -│ └── z_core.h ← Mathematical foundation -└── backends/ - └── q4_kernels/ ← Per-hardware kernel implementations -``` - -One forward pass handles: dense transformers, Mixture-of-Experts, Multi-head Latent Attention, grouped-query attention, fused QKV tensors, and every combination. - -→ [Detailed architecture](ARCHITECTURE.md) · [How the technology works](TECHNOLOGY.md) - - -## Features - -- **Higher fidelity output** — Fused dequant+dot kernels eliminate intermediate buffers. Fewer rounding operations = output closer to the model's FP32 theoretical maximum. -- **Adaptive precision** — Shannon entropy analysis determines per-layer quantization. Simple queries run faster. Complex reasoning gets full depth. The model breathes. -- **Surgical expert loading** — MoE models load only active experts. 48× I/O reduction. Clean signal path with zero interference from unused parameters. -- **Universal model support** — LLAMA, QWEN2, PHI3, GEMMA2, DEEPSEEK, KIMI. Dense and MoE. The model changes, the protocol doesn't. -- **23 native quantization formats** — Q2_K through FP32. No format conversion. The engine speaks the model's native dialect. -- **19 hardware backends** — CPU, GPU, TPU, LPU, IPU, FPGA, DSP, WSE. One binary, every silicon. -- **305 KB binary** — Fits in L2 cache. The engine is invisible. You hear the model, not the framework. -- **Auto chat template** — ChatML, Llama 3, Mistral, Gemma, Phi-3, Kimi. Detected from GGUF metadata. Zero configuration. -- **OpenAI-compatible API** — `./inference-x model.gguf --serve` gives you `/v1/chat/completions`. Drop-in replacement. -- **Web interface** — Built-in chat UI. `python3 web/ix_server.py` and open your browser. - +--- ## API Server -```bash -./inference-x model.gguf --serve --port 8080 -``` - -Drop-in replacement for OpenAI: +Start with `--serve 8080`. OpenAI-compatible API. Any client library works. ```python from openai import OpenAI client = OpenAI(base_url="http://localhost:8080/v1", api_key="none") -response = client.chat.completions.create( +resp = client.chat.completions.create( model="local", - messages=[{"role": "user", "content": "Hello"}] + messages=[{"role": "user", "content": "Hello!"}], + stream=True ) ``` - -## Contributing - -We welcome contributions: - -- **Backends** — Port kernel implementations to new hardware -- **Models** — Add new architectures and quantization formats -- **Benchmarks** — Run benchmarks on diverse hardware -- **Documentation** — Tutorials, guides, translations - -See [CONTRIBUTING.md](CONTRIBUTING.md) for details. - - -## License - -[Business Source License 1.1](LICENSE) — Free for individuals, researchers, and small teams. Commercial use requires a license. Converts to open source in 2030. - -See [NOTICE](NOTICE) for full terms. - - -## Acknowledgments - -- **[Infomaniak](https://infomaniak.com)** — Swiss hosting partner -- **[Hetzner](https://hetzner.com)** — High-performance compute +Endpoints: `POST /v1/chat/completions` · `POST /v1/completions` · `GET /v1/models` · `GET /health` --- -

- inference-x.com · - @ElmadaniSa13111 · - Sponsor -

- Built in Morocco for the world. -

+## Features + +- **Universal GGUF** — Any model, any architecture, auto-detected from metadata +- **Chat templates** — 7 formats auto-detected (Llama, ChatML, Alpaca, Gemma, Phi, Mistral, DeepSeek) +- **Multi-EOS** — Correct stop tokens for every architecture +- **Server mode** — OpenAI-compatible API, streaming, health check +- **Air-gapped** — No network calls during inference. No telemetry. Ever. +- **Zero configuration** — Download a model, run it. Templates, tokens, architecture: auto. + +--- + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). Run `make` to build. Run `make test` to test. Submit a PR. + +We welcome contributions from everyone, regardless of experience level. If you're new to open source, look for issues tagged `good first issue`. + +--- + +## License + +[BSL-1.1](LICENSE) — Business Source License + +**Free for**: individuals, researchers, students, open-source projects, organizations under $1M revenue. + +**Change date**: February 12, 2030 → [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) + +After 2030, everything becomes fully open source. Patents remain protected. + +--- + +## Acknowledgments + +Built in Morocco for the world by [Salka Elmadani](https://x.com/ElmadaniSa13111). + +> *In the Anti-Atlas, our ancestors built khettaras — underground water channels that deliver pure water to villages without pumps, without electricity. The water arrives cleaner than any treated supply because the path itself is the filter. Inference-X works the same way: the shortest path produces the cleanest signal.* + +**[Website](https://inference-x.com)** · **[Sponsor](https://github.com/sponsors/ElmadaniS)** · **[Contact](mailto:Elmadani.SALKA@proton.me)**