llama-tune-ui

llama-serverのパラメータを簡単に調整・最適化するためのCUI管理ツール

概要

llama-tune-uiは、llama-serverの設定を対話的に管理し、自動的に最適なパラメータを見つけるためのツールです。

主な機能

1. パラメータ管理

• 現在の状態表示: サーバーの稼働状況、GPU使用率、メモリ使用量を表示
• パラメータ編集: CTX、GPU layers、Batch、UBatch、Threadsを対話的に編集
• プロファイル管理: 複数の設定プロファイルを保存・切り替え
• モデル選択: /opt/models内のモデルを一覧から選択

2. オートチューニング

複数のパラメータ組み合わせを自動的にテストし、最適な設定を見つけます。

通常モード

• CTX: 65536, 16384, 4096
• GPU layers: 99, 60, 30
• Batch: 512, 128, 32
• 合計: 27通り/モデル

DEBUGモード

• CTX: 4096
• GPU layers: 30
• Batch: 128
• 合計: 1通り/モデル（動作確認用）

機能

• リアルタイム進捗表示（X/Y、経過時間、残り時間、最高スコア）
• 5テストごとに自動保存（途中結果保持）
• 早期打ち切り（token/sec < 5）
• サーバー起動確認（systemd + journalctl）
• SIGINT保護（予期しない中断を防止）

3. ベンチマーク

• 固定プロンプトで推論速度を測定
• token/secを計算して性能を評価
• タイムアウト: 300秒（5分）
• 生成トークン数: 100トークン

4. 結果保存

ベンチマーク結果をMarkdown形式で保存：

/root/llama-tune/benchmark-results.md              # 最新結果
/root/llama-tune/benchmark-results_YYYYMMDD_HHMMSS.md  # タイムスタンプ付き
/root/llama-tune/benchmark-results_temp_YYYYMMDD_HHMMSS.md  # 途中結果（5テストごと）

結果フォーマット

• モデル名
• モデルサイズ（GB/MB）
• CTX、GPU layers、Batch、UBatch
• token/sec（推論速度）
• 備考（正常完了/エラー/最高スコア）

インストール

cd /root/llama-tune
sudo install -m 755 llama-tune-ui /usr/local/bin/llama-tune-ui

使い方

基本操作

llama-tune-ui

メニューから選択：

• 1: 現在の状態を表示
• 2: パラメータを編集（チューニング）
• 3: オートチューニング実行
• 4: オートチューニング実行 (DEBUGモード)
• 5: プロファイルを切り替え
• 6: モデルを選択
• 7: プロファイル一覧を表示
• 8: テストを実行
• 9: llama-server を起動
• 0: llama-server を停止
• q: 終了

オートチューニングの実行

1. llama-tune-uiを起動
2. メニューから「3. オートチューニング実行」を選択
3. テストするモデルを選択（スペースキーで選択/解除）
4. Enterキーで確認
5. 実行確認でEnterキーを押す
6. 完了まで待機（途中で'q'キーで中断可能）

結果の確認

# 最新結果
cat /root/llama-tune/benchmark-results.md

# すべての結果ファイル
ls -lht /root/llama-tune/benchmark-results*.md

# 特定の結果
cat /root/llama-tune/benchmark-results_20260319_003000.md

設定ファイル

/etc/llama-server.local

llama-serverの設定ファイル（systemdから読み込まれる）

LLAMA_MODEL=/opt/models/Qwen3.5-9B.Q4_K_M.gguf
LLAMA_CTX=65536
LLAMA_GPU_LAYERS=99
LLAMA_THREADS=4
LLAMA_BATCH=512
LLAMA_UBATCH=512

プロファイル

/etc/llama-server.local.d/ディレクトリに保存

/etc/llama-server.local.d/high-performance
/etc/llama-server.local.d/balanced
/etc/llama-server.local.d/low-memory

• LLAMA_TUNE_ROOT: ベンチマーク結果やログの保存先ルート（デフォルトはカレントディレクトリ、LLAMA_TUNE_ROOT を設定すれば任意のディレクトリに）
• LLAMA_TUNE_MODEL_DIR: モデルファイル格納ディレクトリ（デフォルト /opt/models）
• LLAMA_TUNE_CONFIG: llama-serverの設定ファイルパス（デフォルト /etc/llama-server.local）

これらの変数を事前にエクスポートすることで、異なるディレクトリに結果やモデルを切り替えられます。例:

export LLAMA_TUNE_ROOT=/data/llama-tune
export LLAMA_TUNE_MODEL_DIR=/data/models
export LLAMA_TUNE_CONFIG=/etc/llama-server-custom.local
llama-tune-ui

トラブルシューティング

オートチューニングが途中で終了する

原因: 予期しないSIGINTシグナル、ターミナル接続の問題

解決策:

1. 新しいターミナルを開く
2. SSH接続を確認
3. デバッグログを確認:

    cat "$LLAMA_TUNE_ROOT/autotune_debug.log"
    cat "$LLAMA_TUNE_ROOT/autotune_error.log"
   

ベンチマーク結果に実行環境を含める

• 実行結果にはCPU、RAM、GPU、VRAMを記録（/proc/* と nvidia-smi を利用）。
• ログに情報が出力されない場合は nvidia-smi が動作するか、LLAMA_TUNE_ROOT 下に書き込み権限があるか確認してください。

Ctrl+C を無視して q のみで終了

• オートチューニング中は KeyboardInterrupt を無視し、q/Q キーでのみ明示的に終了できるようになっています。
• Ctrl+C が効かない場合でも q を入力すれば正常にループを抜けます。

接続エラー時の詳細ログ

• ✗ 接続エラー 発生時には、llama-server の直近ログと例外メッセージを収集してレポートの「詳細」列に追記します。
• journalctl -u llama-server や AUTOTUNE_DEBUG_LOG を確認することで、何が起きているのかを把握できます。

LLAMA_MODEL_PATH を同期

• auto_tune() が設定を書き換える前に LLAMA_MODEL_PATH（systemd 環境変数）を set-environment で更新し、llama-server.service に渡します。
• 環境が LLAMA_MODEL_PATH を参照する構成であれば、本ツールを使うたびに正しいモデルパスが供給されます。

ps aux と llama-tune ps の整合

+- ps aux | grep llama.cpp で期待するモデルパスが確認できない場合、ps 出力の不一致を検出し、ベンチマークレポートの結果サマリーに注意文と 詳細 列の記録を残します。

サーバーが起動しない

原因: メモリ不足、パラメータが大きすぎる

解決策:

1. GPU layers を減らす（99 → 60 → 30）
2. CTX を減らす（65536 → 16384 → 4096）
3. Batch を減らす（512 → 128 → 32）
4. DEBUGモードでテスト

ベンチマークがタイムアウトする

原因: 推論速度が遅い、パラメータが大きすぎる

解決策:

• タイムアウトは300秒（5分）に設定済み
• token/sec < 5 で自動的に早期打ち切り
• より小さいパラメータでテスト

技術仕様

システム要件

• OS: Ubuntu 24.04
• GPU: NVIDIA GPU with CUDA support
• RAM: 16GB以上推奨
• ストレージ: モデルファイル用に十分な空き容量

依存関係

• Python 3.12+
• curses（標準ライブラリ）
• requests（ベンチマーク用）
• systemd（llama-server管理）
• journalctl（ログ確認）

llama-server

• エンドポイント: http://localhost:8080/v1/chat/completions（ps aux で別ポートが指定されていればそちらを優先）
• systemdサービス: llama-server.service
• ラッパースクリプト: /usr/local/bin/llama-server-wrapper

接続ポートのカスタマイズ

• デフォルトではllama-ui側も11430ポートを使いますが、ps aux | grep llama.cpp で --port/-p オプションが設定されている場合はそのポートを優先して使用します。
• LLAMA_TUNE_SERVER_PORTを環境変数で設定すれば手動でポートを指定できます。試行時に自動検出したポートは AUTOTUNE_DEBUG_LOG に記録されます。
• デフォルト未指定時、/etc/llama* や /etc/default/llama* を走査して存在するファイルを自動検出します（LLAMA_CONFIG_PATH へ導出）。

開発

デバッグログ

# オートチューニングのデバッグログ
tail -f /root/llama-tune/autotune_debug.log

# エラーログ
tail -f /root/llama-tune/autotune_error.log

# llama-serverログ
journalctl -u llama-server -f

コード構造

• select_models_for_tuning(): モデル選択UI
• auto_tune(): オートチューニングメインループ
• run_benchmark(): ベンチマーク実行
• save_benchmark_results(): 結果保存
• main_menu(): メインメニュー

ライセンス

このツールはllama.cppプロジェクトと連携して動作します。

関連ドキュメント

• /root/llama.cpp.md: llama.cppのインストールと設定
• /root/llama-tune/benchmark-results.md: 最新のベンチマーク結果