Show HN: Janus – Vulkan経由でAMD/Intel/Nvidia上でGGUFモデルを実行するGoバイナリ
Show HN: Janus – Go binary that runs GGUF models via Vulkan on AMD/Intel/Nvidia (github.com)
要約
Janusは、PythonやDocker、Ollamaを必要としない、単一のGoバイナリでローカルLLMサーバーとOpenAI互換APIを提供するツールです。Vulkan(AMD/Intel/Nvidia GPU)またはCPUフォールバックを使用してGGUFモデルを実行し、モデルのホットスワップやチャットテンプレートの自動検出などの機能を提供します。Windows、Linux、macOSに対応しており、ローカルでのAIモデル実行を簡素化します。
全文翻訳
Janus — ローカルLLMサーバー & OpenAI互換API
Janusは、お使いのマシン(GPUまたはCPU)で.ggufモデルを実行し、OpenAI互換APIを公開する単一のGoバイナリです。Python、Docker、Ollamaは不要です。
お好みの方法で利用してください: コマンドライン(curl、PowerShell、スクリプト)から呼び出すか、Cursor / Cline / その他のOpenAIクライアントに組み込んでください — 同じローカルモデルを、どのようなワークフローにも適合させることができます。
提供される機能
- ローカル推論 — Vulkan(AMD / Intel / NVIDIA)またはCPUフォールバックによるllama.cpp
- OpenAI互換API —
/v1/chat/completions、/v1/models - モデルのホットスワップ — 再起動せずに
.ggufを変更 - 思考モデルサポート —
<think>推論をreasoning_contentに分割 - チャットテンプレート自動検出 — GGUFメタデータからテンプレートを使用
- 依存関係ゼロ — Windowsでは1つの
.exe、PythonやDocker不要
要件
| プラットフォーム | 必要なもの |
|---|---|
| Windows (プライマリ) | Windows 10/11、Go 1.25+、Vulkan対応GPU推奨 |
| Linux | Go 1.25+、curl、tar、Vulkan(Mesa/NVIDIAドライバー;vulkaninfoで確認)またはCPU |
| macOS | Go 1.25+、CPUバックエンド(Vulkanはハードウェアによる) |
ディスク容量: モデルサイズ(モデルあたり通常2〜8 GB)に加えて、Janus + llama.dll用に約50 MBを計画してください。
クイックスタート(Windows)
1. クローンとビルド
git clone https://github.com/Vibra-Ingenn/Janus.git
cd Janus
.\build.ps1
build.ps1は、プリビルドされたllama.cpp Vulkan DLLをダウンロードし、dist\janus.exeをコンパイルします。
2. モデルのダウンロード
.ggufファイルをmodels\フォルダに配置します。付属のダウンローダーを使用します。
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\
または、Hugging Faceから任意のGGUFをダウンロードしてください。
3. 設定
copy .env.example .env
.envを編集します。
INFERENCE_BACKEND=vulkan
JANUS_MODEL_PATH=./models/Llama-3.2-3B-Instruct-Q8_0.gguf
JANUS_MAX_TOKENS=4096
| 変数 | デフォルト | 説明 |
|---|---|---|
INFERENCE_BACKEND | vulkan | vulkan、cpu、またはopenrouter |
JANUS_MODEL_PATH | (必須) | .ggufファイルへのパス |
JANUS_GPU_LAYERS | -1 | -1 = 全レイヤーをGPUにオフロード、0 = CPUのみ |
JANUS_VRAM_CEILING_MB | 9216 | VRAM予算のヒント(MiB) |
JANUS_MAX_TOKENS | 4096 | 返信あたりの最大トークン数 |
JANUS_LISTEN_ADDR | 127.0.0.1:8990 | バインドアドレス |
4. 実行
.\dist\janus.exe
ブラウザでhttp://127.0.0.1:8990が開きます。
5. 確認
curl http://127.0.0.1:8990/health
クイックスタート(Linux)
git clone https://github.com/Vibra-Ingenn/Janus.git
cd Janus
./build.sh # llama.cpp b11146 (Vulkan) を lib/linux にダウンロードし、dist/janus をビルド
cp .env.example .env
# .env を編集 — JANUS_MODEL_PATH を設定(Vulkanがない場合は INFERENCE_BACKEND=cpu も設定)
./dist/janus
build.shはllama.cpp b11146をピン留めします(internal/bridge/llama_dl.goの構造体レイアウトはこのタグと一致します)。./build.sh --version bNNNNは別のバージョンを試します。--skip-downloadはlib/linux/を再利用します。.soファイルはバイナリの隣(dist/)にコピーされます。RUNPATH=$ORIGINにより、LD_LIBRARY_PATHなしで互いを検出します。- Go 1.25+が必要です(Linuxで構造体を値渡しするためにpurego v0.11が必要です)。
GOTOOLCHAIN=auto(デフォルト)では、古いgoが適切なツールチェーンを自分でダウンロードします。 JANUS_GPU_LAYERS=-1(デフォルト)は全てのレイヤーをオフロードします。ログでoffloaded N/N layers to GPUを確認してください。
サポート対象:linux/amd64。arm64/macOSはテストされていません/サポートされていません。
macOS:go build -o dist/janus ./cmd/janusでビルドし、バイナリの隣にlibllama.dylibを提供してください(未テスト)。
OpenAI互換API
curl http://127.0.0.1:8990/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "local",
"messages": [{"role": "user", "content": "Hello!"}]
}'
ベースURL: http://127.0.0.1:8990/v1
エンドポイント
| メソッド | パス | 説明 |
|---|---|---|
| GET | /health | 稼働状況チェック(詳細表示には?deep=true) |
| GET | /v1/models | モデルリスト |
| POST | /v1/chat/completions | チャット(ストリーミング対応) |
| POST | /models/load | モデルのホットスワップ |
| GET | /models/list | 利用可能な.ggufファイル一覧 |
| GET | /engine/status | VRAMとバックエンド情報 |
ストリーミング
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"}]}'
Cursor / Cline / その他のクライアントへの接続
ベースURL: http://127.0.0.1:8990/v1
APIキー: (空白のまま)
トラブルシューティング(苦労して学んだこと)
| 問題 | 原因 | 解決策 |
|---|---|---|
| 「ビルドはできたが、変更が反映されない」 | Windowsでは、実行中の.exeをGoが上書きできない。 | タスクマネージャーで全てのjanus.exeを停止してから、再ビルドしてください。 |
| 「Address already in use」 | 残存プロセスがポート8990を占有している。 | タスクマネージャーで全てのjanus.exeを終了してください。 |
| サーバーは起動するが、チャットが失敗する | JANUS_MODEL_PATHが間違っているか、models/に.ggufファイルがない。 | .envでパスを設定し、ファイルをmodels/に配置してください。 |
| 「local engine failed to start」 | llama.dllの欠落またはGPUドライバーの問題。 | .uild.ps1を実行してください。GPUドライバーを更新するか、INFERENCE_BACKEND=cpuを設定してください。 |
| URLが間違っている | デフォルトはhttp://127.0.0.1:8990であり、8080ではない。 | 8990をブックマークしてください。 |
| 最初の応答が遅すぎる | モデルがVRAMにロードされている — 通常のことです。 | 10〜60秒待ってください。より小さいクオンタイズ(Q4)はロードが速いです。 |
プロジェクト構成
cmd/janus/ メインサーバー(OpenAI互換API)
cmd/modelget/ Hugging Faceモデルダウンローダー
internal/engine/ llama.cpp Vulkan/CPUバックエンド
internal/bridge/ DLLローダーとFFIバインディング
internal/singleton/ シングルインスタンスガード
models/ .ggufファイルをここに配置(コミットしない)
dist/ ビルド後の janus.exe + llama.dll
開発
Get-Process -Name "janus" -ErrorAction SilentlyContinue | Stop-Process -Force
go test ./...
go build -o dist\janus.exe .\cmd\janus
.\dist\janus.exe
または単に. un.ps1を使用します。llama DLLを含む完全なビルドには、.uild.ps1を使用してください。
コントリビューションを歓迎します — CONTRIBUTING.mdを参照してください。
ライセンス
MIT — LICENSEを参照してください。