操作
機能 #415
完了
機能 #396: ゲーム内常駐ペット育成機能の追加
自然文曲検索用ローカルLLMモデルの同梱・パッケージングと実モデル動作検証 (#404 follow-up)
機能 #415:
自然文曲検索用ローカルLLMモデルの同梱・パッケージングと実モデル動作検証 (#404 follow-up)
説明
背景 / 目的¶
#404（自然文による曲検索）のフォローアップ。#404 では検索ロジック＋API層を実装済みだが、ローカルLLM（de.kherud:llama / GGUF）のモデルファイル本体は未同梱で、未配置時は常にルールベースへフォールバックする状態。LLM経路を実際に有効化・検証し、リリース物に含めるための作業を本チケットで扱う。
作業内容¶
- 推奨する小型GGUF Instructモデル（例: Qwen2.5-0.5B/1.5B-Instruct Q4等）の選定とライセンス確認
-
jpackage/ zip・msi へのモデル同梱（build.gradle の prepareJpackageContent 等）と配置パス規約（-Dbeatoraja.songsearch.model）の確定 -
LlamaCppInferenceの防御的リフレクション実装（TODO #404）をde.kherud:llamaの実 API に合わせて確定 - 推論のスレッドモデル化：選曲画面でのロード/推論をバックグラウンドスレッドで実行し、ゲームプレイ中（judgeタイミング）に影響させない
- 実Windowsホストでの実モデル動作検証（代表クエリでの出力品質・CPU/メモリ/ロード時間・GPU使用の有無）
- CPU推論を既定とし、GPUオフロードを使う場合はレンダリング（libGDX/LWJGL3）との競合評価
完了条件 (DoD)¶
- リリース物にモデルが同梱され、代表的な自然文クエリでLLM経路が期待どおり動作する
- モデル未同梱/ロード失敗時は従来通りルールベースにフォールバックし例外が生じない
- 推論がゲームプレイ中の動作（judgeタイミング・フレーム）に影響を与えない
- ユニットテストがすべて通る
エージェント ちゃん さんが11日前に更新
- 期日 を 2026/06/24 にセット
- 開始日 を 2026/06/25 から 2026/06/24 に変更
- 次のチケットに後続 機能 #404: 自然文による曲検索 を追加
エージェント ちゃん さんが11日前に更新
- ステータス を 未着手 から 実装中 に変更
- 進捗率 を 0 から 10 に変更
実装に着手しました。
- ブランチ:
feature/415 - 対応方針: ローカルLLM経路を実有効化する。
de.kherud:llama4.1.0 の実API（LlamaModel(ModelParameters)/InferenceParameters）に合わせてLlamaCppInferenceのリフレクションを確定し、CPU推論を既定・モデルロード/推論をバックグラウンドスレッド化（選曲/judgeに非干渉）。モデル本体（Qwen2.5-1.5B-Instruct Q4_K_M, Apache-2.0）はビルド時DLで zip/msi に同梱し、配置パスは-Dbeatoraja.songsearch.model（既定model/）。未同梱/失敗時は従来通りルールベースへフォールバック。実Windowsホストでベストエフォート動作検証。
エージェント ちゃん さんが11日前に更新
- ステータス を 実装中 から 完了 に変更
- 進捗率 を 10 から 100 に変更
対応が完了しました。
概要¶
#404 のフォローアップとして、自然文曲検索のローカルLLM（de.kherud:llama）経路を実有効化。モデル同梱・スレッド化・設定UI・精度/速度改善・LoRA微調整までを実装し、未配置/失敗時はルールベースへフォールバックしてjudgeに干渉しない。
変更点¶
-
LLM経路の実有効化:
de.kherud:llama4.1.0 の実API（LlamaModel(ModelParameters)/InferenceParameters）に合わせて防御的リフレクションを確定。CPU推論既定、ロード/推論をバックグラウンドスレッド化。 -
モデル同梱: Qwen2.5-1.5B-Instruct Q4_K_M（Apache-2.0）をビルド時DLで zip/msi の
model/に同梱（SHA-256照合）。配置パスは-Dbeatoraja.songsearch.model。 -
設定UI: 選曲コンフィグにモデル選択 ComboBox（
model/内 *.gguf 自動検出・Config永続化）。 -
精度改善(A): ルール辞書/正規表現拡張＋ルール明示シグナル優先でLLM出力をマージする
HybridQueryInterpreter。 - 速度改善(C): ルールが十分抽出できたクエリはLLMを呼ばず即返すショートサーキット。ctx縮小・setCachePrompt/flashAttn。
- パターン語彙(B): GBNF文法とプロンプトに patternWeights（縦連→JACK 等）を露出。
-
意味照合(E, オプトイン): textScore を
SemanticTextScorerで差し替え可能化。埋め込みモデル指定時のみ意味照合、未指定は従来挙動。 -
LoRA(D): 学習用
tools/songsearch-lora/（合成データ生成＋PEFT/TRL学習＋GGUF変換）。model/内*lora*.ggufを自動検出し base に適用（exe運用でフラグ不要）、ビルドで app-image に同梱。
テスト¶
-
.\gradlew.bat test: 成功（JavaFXスモーク含むフルスイート緑）。 - 実Windowsホスト検証: 20件の日本語ゴールデンセットで rule-only 63.9% / llm-only 44.4% → hybrid 100%。LoRA適用で llm単体 74%→100%・3638ms→2504ms。
関連 MR¶
- !97 (feature/415 → develop) マージ済
操作