CLIでLLMモデルの実行・管理ができる「cortex.cpp」を試す
kun432こういう記事を見かけた
流石にAI・LLM関連のものが多い。で8割ぐらいは過去に触った or ざっくり見かけて知ってる、ものなんだけども、いくつか知らないものがあった。その中の1つが「jan」。
Jan - ローカルのAIアシスタント
Janは、あなたのデバイス上で100％オフラインで動作するChatGPTの代替です。私たちの目標は、素人でも簡単にLLMをダウンロードして実行し、完全なコントロールとプライバシーでAIを利用できるようにすることです。
Janは、あらゆるハードウェア上で動作する組み込み可能なローカルAIエンジンCortexを搭載しています。PCからマルチGPUクラスタまで、Jan & Cortexはユニバーサルなアーキテクチャをサポートします：
- NVIDIA GPU （高速）
- Apple Mシリーズ（高速）
- Apple Intel
- Linux Debian
- Windows x64
特徴：
- Llama、Gemma、Mistral、Qwenのような一般的なLLMを備えたモデルライブラリ
- GroqやOpenRouterのようなリモートAI APIへの接続
- OpenAI相当のAPIを備えたローカルAPIサーバー
- Janをカスタマイズするための拡張機能
まあローカルで動くChatGPT互換インタフェースという感じで、これだけだと他にも候補はいろいろありそうな気もするのだが、このコアになっているのが「Cortex.cpp」
ざっと見た感じは、OllamaとかMLX-LMっぽい雰囲気を感じるが、
Janは、あらゆるハードウェア上で動作する組み込み可能なローカルAIエンジンCortexを搭載しています。PCからマルチGPUクラスタまで、Jan & Cortexはユニバーサルなアーキテクチャをサポートします：
- NVIDIA GPU （高速）
- Apple Mシリーズ（高速）
というところが気になるので、少し触ってみる。
kun432GitHubレポジトリ
ただ概要の説明は公式ドキュメントのほうが詳しい。
Cortex概要
Cortex は、ロボットのためのオープンソースの脳です：視覚、音声、言語、表形式、そしてアクション -- クラウドはオプションです。
主要な機能:
- 直感的な CLI（Ollama にインスパイアされている）
- 完全な C++ 実装で、デスクトップおよびモバイルアプリにパッケージ化可能
- Huggingface から、または Cortex のビルトインモデルライブラリからの取得可能
- ユニバーサルファイル形式で保存されるモデル（BLOB 形式ではない）
- 交換可能な推論バックエンド（デフォルト:
llamacppおよびONNXRuntime）- Cortex は、スタンドアロンの API サーバとして、または Jan.ai のようなアプリに統合して展開可能
- サーバ用の自動 API ドキュメント生成
Cortex のロードマップには、OpenAI API の完全な互換性の実装が含まれており、それには Tools、Runs、マルチモーダルおよびリアルタイム API が含まれます。
推論バックエンド
- デフォルト: llama.cpp: クロスプラットフォームで、ほとんどのノートパソコン、デスクトップおよび OS をサポート
- 将来: ONNX Runtime: Windows Copilot+ PC や NPU、および従来の機械学習モデルをサポート
GPU ハードウェアが利用可能な場合、Cortex はデフォルトで GPU アクセラレーションが有効です。
モデル
Cortex.cpp は、ユーザーが複数の Model Hub からモデルをプルできるようにし、柔軟性と広範なモデルアクセスを提供します。
注意
一般的なガイドラインとして、3B モデルを実行するには 8 GB 以上の RAM、7B モデルには 16 GB、14B モデルには 32 GB の RAM が必要です。Cortex Built-in Models & Quantizations
Model /Engine llama.cpp Command phi-4 ✅ cortex run phi-4llama3.2 ✅ cortex run llama3.2llama3.1 ✅ cortex run llama3.1codestral ✅ cortex run codestralgemma2 ✅ cortex run gemma2mistral ✅ cortex run mistralministral ✅ cortex run ministralqwen2 ✅ cortex run qwen2.5openhermes-2.5 ✅ cortex run openhermes-2.5tinyllama ✅ cortex run tinyllamaCortex Built-in Models の全リストは こちら をご覧ください。
Cortex は各モデルに対して複数の量子化をサポートしています。
cortex pull phi-4Downloaded models: bartowski:phi-4-GGUF:phi-4-Q3_K_S.gguf Available to download: 1. phi-4:14.7b-gguf-q2-k 2. phi-4:14.7b-gguf-q3-kl 3. phi-4:14.7b-gguf-q3-km 4. phi-4:14.7b-gguf-q3-ks 5. phi-4:14.7b-gguf-q4-km (default) 6. phi-4:14.7b-gguf-q4-ks 7. phi-4:14.7b-gguf-q5-km 8. phi-4:14.7b-gguf-q5-ks 9. phi-4:14.7b-gguf-q6-k 10. phi-4:14.7b-gguf-q8-0 Select a model (1-10):
なるほど、推論部分はllama.cppが使えるが将来的にはONNXも使えるということ。ということは、環境ごとに最適なエンジンを使えて、操作感はOllama、という感じのラッパーなのかも。
インストール
Cortexは、Windows / Mac / Linuxのどれにも対応している。今回はローカルのMac（M2）でやる。
インストーラをダウンロードして普通にインストールする。HomebrewとかはまだなくてIssueはあがってる。
これでCLIがインストールされる
cortex --version
v1.0.12
Usageも。
cortex --help
Cortex.cpp CLI
Usage:
cortex [options] [subcommand]
Options:
-h,--help Print this help message and exit
--verbose Get verbose logs
--config_file_path TEXT Configure .rc file path
--data_folder_path TEXT Configure data folder path
-v,--version Get Cortex version
Common Commands:
pull Download models by HuggingFace Repo/ModelIDSee built-in models: https://huggingface.co/cortexso
run Shortcut: pull, start & chat with a model
Models:
models Subcommands for managing models
Engines:
engines Subcommands for managing engines
Hardware:
hardware Subcommands for managing hardware
Server:
start Start the API server
stop Stop the API server
ps Show active model statuses
update Update cortex version
Configurations:
config Subcommands for managing configurations
サーバの起動
サーバを起動
cortex start
Set log level to INFO
Host: 127.0.0.1 Port: 39281
Server started
API Documentation available at: http://127.0.0.1:39281
39281番ポートで起動するみたい。
APIドキュメントは以下にあるが、とりあえず後で。
モデルのダウンロード・推論
モデルの推論は runで行う。モデルがダウンロードされていない場合は自動的にダウンロードされる。試しにGemma3をダウンロードして使ってみる。
cortex run gemma3
対話形式になっていて、使用するモデルの候補が表示される。
Available to download:
1. gemma3:12b
2. gemma3:1b
3. gemma3:27b
4. gemma3:4b (default)
Select a model (1-4):
今回はデフォルトの4Bを使用してみる。何も入力せずにENTER。
ダウンロードが開始される
Start downloading..
metadata.yml 100%[==================] 00m:00s 47.00 B/47.00 B
model.gguf 4%[> ] 05m:04s 118.71 MB/2.32 GB
model.yml 100%[==================] 00m:00s 862.00 B/862.00 B
モデルダウンロードが終わると対話式のチャットが開く。
Model gemma3:4b downloaded successfully!
In order to exit, type `exit()`
>
> 競馬の魅力を5つリストアップして。
出力。もちろんストリーミング。
競馬の魅力はたくさんありますが、特に以下の5つが挙げられます。
スピードとドラマの融合: 芝やダートという地面の上を、馬が全速力で駆け抜ける姿は、まさにスピードの極みです。その中で、予想外の展開やドラマが生まれる可能性があり、手に汗握る展開は競馬ならではの魅力と言えるでしょう。
数字と予想のロマン: 過去のレース結果や馬の能力、調教の様子など、様々なデータを分析して予想を立てる行為自体が、ロマンを感じさせます。的中すれば喜びが倍増し、外れた場合は新たな知識を身につける良い機会にもなります。
馬と騎手のコンビ: 馬と騎手は、長年の鍛錬と信頼関係によって結ばれた最強のコンビです。その二人の絆や、騎手の巧みな騎手技がレースを左右する場面は、見る者を感動させます。
勝負の連続: 競馬は、一瞬の判断が勝敗を分ける勝負です。常に変化する展開に対応し、冷静な判断を下す必要があり、その緊張感とスリルが魅力の一つです。
社会との繋がり: 競馬は、単なるスポーツとしてだけでなく、社会現象としても注目を集めます。地方の経済を活性化させたり、多くの人々を巻き込んだイベントとして開催されたりするなど、社会との繋がりを感じられることも魅力です。
これらの要素が組み合わさることで、競馬は多くの人々を魅了し続けているのです。<end_of_turn>
>
マルチターンで会話できるようなのでコンテキストが維持されているかを確認
> 私の趣味は競馬なんですよ。
それは素晴らしいですね！競馬がお好きなんですね。どんなところが好きですか？
- 好きな馬はいますか？ 応援している馬について教えてください。
- 普段、どのように競馬を楽しんでいますか？ 予想をしているのか、レース映像を見ているのか、など教えていただけると嬉しいです。
- 競馬で一番盛り上がる瞬間はどんな時ですか？ 例えば、応援する馬が勝利した時、予想外の結果が出た時など、具体的なエピソードがあれば教えてください。
競馬の話、楽しそうにお話を聞かせてください！<end_of_turn>
> 日本の総理大臣は誰？
現在の日本の総理大臣は、岸田文雄（きしだ ふみお） さんです。
2021年10月4日に就任されました。
より詳しい情報は、以下のサイトで確認できます。
- 内閣人事室: https://www.casio.go.jp/data/cabinet/><end_of_turn>
> 私の趣味ってなんでしたっけ？
私の会話履歴から、あなたの趣味は競馬だと分かっていますね。
競馬がお好きなんですね！ 😊
他に何かご興味のあることや、普段の過ごし方など、何か教えていただけると、あなたについてより深く理解できます。例えば、好きな食べ物、音楽、映画、スポーツなど、どんなことでも構いませんよ。<end_of_turn>
会話履歴が引き継がれている。
終了する場合は
> exit()
またはCtrl+cとかCtrl＋dで。
ダウンロードだけ行う場合はpullを使う。
cortex pull gemma3
既にダウンロード済モデル以外のモデルがリストアップされる。
Downloaded models:
gemma3:4b
Available to download:
1. gemma3:12b
2. gemma3:1b
3. gemma3:27b
Select a model (1-3):
モデルの管理
モデルハブ
Cortexでモデルをダウンロードする方法は２つ。
Cortexが用意しているモデルハブを使う方法。この場合は単純にモデル名だけを指定すれば良い。
cortex pull gemma3
ビルトインで使用できるモデルのリストはここにある
が、実際にはどうやら以下を見ている様子で、上のリストよりも多くのモデルがあるように見える。
例えばGemma3だとこれ
・・・なのだけど、実際には量子化のバリエーションはもっと多い様子。これらをダウンロードするにはどうすればいいか？
ということで、もう一つのダウンロード方法としてHuggingFaceから直接ダウンロードする方法がある。
例えば以下のモデルの場合
モデルパスを指定すると以下のように量子化のバリエーションを選択できる。
cortex pull mmnga/sarashina2.2-0.5b-instruct-v0.1-gguf
Select an option
1. sarashina2.2-0.5b-instruct-v0.1-IQ1_M.gguf
2. sarashina2.2-0.5b-instruct-v0.1-IQ1_S.gguf
3. sarashina2.2-0.5b-instruct-v0.1-IQ2_M.gguf
4. sarashina2.2-0.5b-instruct-v0.1-IQ2_S.gguf
5. sarashina2.2-0.5b-instruct-v0.1-IQ2_XS.gguf
6. sarashina2.2-0.5b-instruct-v0.1-IQ2_XXS.gguf
7. sarashina2.2-0.5b-instruct-v0.1-IQ3_M.gguf
8. sarashina2.2-0.5b-instruct-v0.1-IQ3_S.gguf
9. sarashina2.2-0.5b-instruct-v0.1-IQ3_XS.gguf
10. sarashina2.2-0.5b-instruct-v0.1-IQ3_XXS.gguf
11. sarashina2.2-0.5b-instruct-v0.1-IQ4_NL.gguf
12. sarashina2.2-0.5b-instruct-v0.1-IQ4_XS.gguf
13. sarashina2.2-0.5b-instruct-v0.1-Q2_K.gguf
14. sarashina2.2-0.5b-instruct-v0.1-Q3_K_L.gguf
15. sarashina2.2-0.5b-instruct-v0.1-Q3_K_M.gguf
16. sarashina2.2-0.5b-instruct-v0.1-Q3_K_S.gguf
17. sarashina2.2-0.5b-instruct-v0.1-Q4_0.gguf
18. sarashina2.2-0.5b-instruct-v0.1-Q4_K_M.gguf
19. sarashina2.2-0.5b-instruct-v0.1-Q4_K_S.gguf
20. sarashina2.2-0.5b-instruct-v0.1-Q5_0.gguf
21. sarashina2.2-0.5b-instruct-v0.1-Q5_K_M.gguf
22. sarashina2.2-0.5b-instruct-v0.1-Q5_K_S.gguf
23. sarashina2.2-0.5b-instruct-v0.1-Q6_K.gguf
24. sarashina2.2-0.5b-instruct-v0.1-Q8_0.gguf
Select an option (1-24):
ただしGGUFのレポジトリでないと上記のようにはならない。上記のGGUFの元であるレポジトリの場合。
cortex pull sbintuitions/sarashina2.2-0.5b-instruct-v0.1
エラーになる
Not a GGUF model. Currently, only GGUF single file is supported.
ただ、ビルトインモデルの場合はどうやらモデルパスから「ビルトイン」と解釈するようなので、量子化バリエーションが選択できないように見える・・・
cortex pull cortexso/gemma3
Downloaded models:
gemma3:1b
gemma3:4b
Available to download:
1. gemma3:12b
2. gemma3:27b
Select a model (1-2):
ドキュメントにはURLを直接指定する方法が書かれているのだが、
cortex pull https://huggingface.co/cortexso/gemma3/blob/main/gemma-3-1b-it-q4_k_m.gguf
なぜかまるっとダウンロードしようとする・・・
Start downloading..
gemma-3-12b-it-q2_k.[> ]
gemma-3-12b-it-q3_k_[> ]
gemma-3-12b-it-q3_k_[> ]
gemma-3-12b-it-q3_k_[> ]
gemma-3-12b-it-q4_k_[> ]
gemma-3-12b-it-q4_k_[> ]
gemma-3-12b-it-q5_k_[> ]
gemma-3-12b-it-q5_k_[> ]
gemma-3-12b-it-q6_k.[> ]
gemma-3-12b-it-q8_0.[> ]
gemma-3-1b-it-q2_k.g[> ]
gemma-3-1b-it-q3_k_l[> ]
gemma-3-1b-it-q3_k_m[> ]
せっかく量子化バージョンが揃っているのに選択できないのはちょっともったいない。
ダウンロード済モデルの一覧
cortex models list
+---------+-----------+
| (Index) | ID |
+---------+-----------+
| 1 | gemma3:4b |
+---------+-----------+
| 2 | gemma3:1b |
+---------+-----------+
もうちょっと詳細に見たい・・・
ダウンロードされたモデルは、Macの場合は $HOME/cortex/models以下にあった。
tree ~/cortexcpp -ls
[ 288] /Users/kun432/cortexcpp
├── [ 64] assistants
├── [ 45056] cortex.db
├── [ 96] engines
│ └── [ 96] cortex.llamacpp
│ └── [ 96] mac-arm64
│ └── [ 128] v0.1.55
│ ├── [ 3740464] libengine.dylib
│ └── [ 31] version.txt
├── [ 64] files
├── [ 128] logs
│ ├── [ 1051597] cortex-cli.log
│ └── [ 165187] cortex.log
├── [ 96] models
│ └── [ 96] cortex.so
│ └── [ 128] gemma3
│ ├── [ 160] 1b
│ │ ├── [ 47] metadata.yml
│ │ ├── [ 806058144] model.gguf
│ │ └── [ 1505] model.yml
│ └── [ 160] 4b
│ ├── [ 47] metadata.yml
│ ├── [ 2489757760] model.gguf
│ └── [ 1506] model.yml
└── [ 64] threads
14 directories, 11 files
モデルの量子化バリエーションがわからないのでメタデータを開いてみると、Q4_K_Mだった。
cat ~/cortexcpp/models/cortex.so/gemma3/1b/metadata.yml
version: 1
name: gemma3
default: 1b-gguf-q4-km
なお、チャットテンプレートやパラメータをカスタマイズしたい場合はこのmetadata.yamlを修正すれば良いみたい。
kun432モデルの状態
読み込んだモデルの状態を確認するにはcortex ps
cortex ps
+-----------+-----------------+--------+---------+-------------------------------+
| Model | Engine | RAM | VRAM | Up time |
+-----------+-----------------+--------+---------+-------------------------------+
| gemma3:4b | cortex.llamacpp | 0.00 B | 2.83 GB | 1 hour, 32 minutes, 4 seconds |
+-----------+-----------------+--------+---------+-------------------------------+
なるほど、今回はMacを使用しているのだけども、llama.cppエンジンなのでMetalによるGPUオフロードが効いている様子。
kun432エンジンの管理
ここまで見た感じ、cortexの裏ではllama.cppが動いている。他のオプションとしてはONNXランタイムがある様子。
まず現在インストール済みのエンジンを確認
cortex engines list
+---+-----------+---------+-----------+---------+
| # | Name | Version | Variant | Status |
+---+-----------+---------+-----------+---------+
| 1 | llama-cpp | v0.1.55 | mac-arm64 | Default |
+---+-----------+---------+-----------+---------+
ONNXランタイムエンジンをインストールしてみる。
cortex engine install onnxruntime
The following arguments were not expected: onnxruntime install engine
Run with --help for more information.
んー、ダメっぽい？どうやら今後サポートされる様子。
ここまでチラホラドキュメントどおりに動かないなーと思っていたら、こんなことが書いてあった。
🚧 Cortex.cpp is currently under development. Our documentation outlines the intended behavior of Cortex, which may not yet be fully implemented in the codebase.
あぁ・・・なるほど・・・ちょっと現時点ではドキュメントはあまり当てにならないかも。
kun432ここまでの所感
なるだけ簡単にローカルモデルが使えるように、という思想なのだろうと思うが、いかんせんできることが現時点では少ないように思える。あとできないことがドキュメントに書いてあるのは辛いなぁ・・・
Ollamaにインスパイアされて、というだけあって、非常にOllamaと似ている。じゃあOllamaでなにかフロントエンド建てればいいやん、という気がしなくもないが、冒頭の記事で「Jan」が話題になっていることや「Cortex」使い方などを見ていると、もしかするとOllamaですら一般層にはまだまだ難しいということなのかもしれないなぁと感じたり。
現時点では、もうちょっといろいろ揃ってから、でいいような気はする。
kun432「Jan」を使っていないので、その点でちゃんとメリットを感じきれていない可能性はある、とは思う。
あとはまあllama.cppを使えばいいのか、ollamaを使えばいいのか、とか、どのモデルを使えばいいのか、とか、そのあたりは初めて触る場合には迷うかも知れないね。