Janus — Lokale LLM-server & OpenAI-compatibele API

Je kunt Janus naar eigen inzicht gebruiken: roep het aan via de opdrachtregel (curl, PowerShell, scripts) of koppel het aan Cursor, Cline of elke andere OpenAI-client. Gebruik lokale modellen binnen de workflow die het beste bij jou past.

Functionaliteiten

• Lokale inferentie — via llama.cpp met Vulkan (AMD / Intel / NVIDIA) of CPU-fallback.
• OpenAI-compatibele API — ondersteuning voor /v1/chat/completions en /v1/models.
• Hot-swap modellen — wijzig .gguf-bestanden zonder de server te herstarten.
• Ondersteuning voor 'Thinking'-modellen — de <think> redenering wordt gesplitst in reasoning_content.
• Automatische detectie van chat-templates — maakt gebruik van de template uit de GGUF-metadata.
• Geen afhankelijkheden — één .exe op Windows; geen Python of Docker nodig.

Systeemvereisten

Platform	Vereisten
Windows (primair)	Windows 10/11, Go 1.22+, Vulkan-compatibele GPU aanbevolen
Linux	Go 1.22+, Vulkan of CPU
macOS	Go 1.22+, CPU-backend (Vulkan varieert per hardware)

Schijfruimte: Houd rekening met de grootte van het model (vaak 2–8 GB per model) plus ongeveer 50 MB voor Janus en llama.dll.

Snelstart (Windows)

1. Klonen en bouwen

git clone https://github.com/Vibra-Ingenn/Janus.git
cd Janus
.\build.ps1

build.ps1 downloadt vooraf gebouwde llama.cpp Vulkan DLL's en compileert dist\janus.exe.

2. Een model downloaden

Plaats een .gguf-bestand in de models\ map. Je kunt de meegeleverde downloader gebruiken:

go build -o dist\modelget.exe .\cmd\modelget
.\dist\modelget.exe -repo meta-llama/Llama-3.2-3B-Instruct -file Llama-3.2-3B-Instruct-Q8_0.gguf -out .\models\

Alternatief kun je elk GGUF-bestand downloaden van Hugging Face.

3. Configureren

Kopieer het voorbeeldbestand:

copy .env.example .env

Bewerk .env en pas de volgende waarden aan:

INFERENCE_BACKEND=vulkan
JANUS_MODEL_PATH=./models/Llama-3.2-3B-Instruct-Q8_0.gguf
JANUS_MAX_TOKENS=4096

Configuratievariabelen:

Variabele	Standaardwaarde	Betekenis
INFERENCE_BACKEND	vulkan	vulkan, cpu, of openrouter
JANUSMODELPATH	(verplicht)	Pad naar je .gguf-bestand
JANUSGPULAYERS	-1	-1 = alle lagen op GPU, 0 = alleen CPU
JANUSVRAMCEILING_MB	9216	VRAM budget hint (MiB)
JANUSMAXTOKENS	4096	Maximaal aantal tokens per antwoord
JANUSLISTENADDR	127.0.0.1:8990	Bind-adres

4. Uitvoeren

.\dist\janus.exe

Dit opent http://127.0.0.1:8990 in je browser.

5. Verifiëren

curl http://127.0.0.1:8990/health

Snelstart (Linux / macOS)

git clone https://github.com/Vibra-Ingenn/Janus.git
cd Janus
go mod tidy
go build -o dist/janus ./cmd/janus
cp .env.example .env
# Bewerk .env — stel JANUS_MODEL_PATH in en zet INFERENCE_BACKEND=cpu als er geen Vulkan is
./dist/janus

Op Linux moet libllama.so zich naast het binary-bestand bevinden of in de LDLIBRARYPATH staan.

OpenAI-compatibele API

Voorbeeld aanroep

curl http://127.0.0.1:8990/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "local",
"messages": [{"role": "user", "content": "Hello!"}]
}'

Base URL: http://127.0.0.1:8990/v1

Eindpunten

Methode	Pad	Beschrijving
GET	/health	Liveness check (?deep=true voor details)
GET	/v1/models	Lijst met modellen
POST	/v1/chat/completions	Chat (streaming wordt ondersteund)
POST	/models/load	Model hot-swappen
GET	/models/list	Beschikbare .gguf-bestanden
GET	/engine/status	VRAM en backend informatie

Streaming

curl http://127.0.0.1:8990/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"local","stream":true,"messages":[{"role":"user","content":"Tell me a joke"}]}'

Verbinding maken met Cursor / Cline / andere clients

• Base URL: http://127.0.0.1:8990/v1
• API Key: (leeg laten)

Veelvoorkomende problemen (Pitfalls)

Probleem	Oorzaak	Oplossing
"Het is gebouwd maar mijn wijzigingen zijn niet aanwezig"	Op Windows kan Go een draaiend .exe-bestand niet overschrijven.	Stop alle janus.exe processen in Taakbeheer en bouw opnieuw.
"Address already in use"	Een overgebleven proces bezet poort 8990.	Beëindig alle janus.exe in Taakbeheer.
Server start op, maar chat faalt	JANUSMODELPATH is onjuist of er is geen .gguf in models/.	Stel het pad correct in via .env en plaats het bestand in models/.
"local engine failed to start"	Ontbrekende llama.dll of probleem met GPU-driver.	Voer .\build.ps1 uit. Update GPU-drivers of zet INFERENCE_BACKEND=cpu.
Verkeerde URL	De standaardpoort is 8990, niet 8080.	Gebruik http://127.0.0.1:8990.
Het eerste antwoord duurt erg lang	Het model wordt in het VRAM geladen — dit is normaal.	Wacht 10–60 seconden; kleinere quants (Q4) laden sneller.

Projectstructuur

• cmd/janus/: Hoofdserver (OpenAI-compatibele API)
• cmd/modelget/: Downloader voor Hugging Face modellen
• internal/engine/: llama.cpp Vulkan/CPU backend
• internal/bridge/: DLL-loader en FFI-bindings
• internal/singleton/: Guard voor enkelvoudige instantie
• models/: Hier plaats je de .gguf-bestanden (niet opgenomen in git)
• dist/: janus.exe + llama.dll na het bouwen

Ontwikkeling

Om een draaiend proces te stoppen en opnieuw te bouwen op Windows:

Get-Process -Name "janus" -ErrorAction SilentlyContinue | Stop-Process -Force
go test ./...
go build -o dist\janus.exe .\cmd\janus
.\dist\janus.exe

Gebruik .\run.ps1 voor een snelle start of .\build.ps1 voor een volledige build inclusief llama DLL's.

Licentie

Dit project is gelicentieerd onder de MIT-licentie.