Guide

LLM Local Chat

ローカルLLM（llama.cpp）＋ Whisper音声認識＋ Windows SAPIを組み合わせた日本語AIチャットアプリです。
必要な依存ライブラリとモデルを取得済みの場合、推論・音声認識・音声合成・会話処理はローカルで実行されます。Biologと家計簿API連携は、別プロセスのローカルHTTP APIを任意で利用します。

ローカル処理を重視した構成です。機密情報を扱う業務環境へ導入する場合は、端末のアクセス制御、Windowsユーザープロファイル、ディスク暗号化、Dockerポート、依存ライブラリ、バックアップ方法を含め、組織の情報セキュリティ担当者による事前評価を行ってください。

詳しい実装の解説は コード解説 を参照してください。

Python 3.12.10 Version 1.8.5 Platform: Windows License: MIT

主な機能

重要な用語

READMEでは、このアプリを使うときに特に目にしやすい用語だけを簡潔に説明します。

用語説明
Python本アプリのプログラム本体を動かすために使っているプログラミング言語です。LLM Local ChatはPython 3.12系を前提にしており、各種ライブラリ（他のプログラムから利用できる機能部品）もPythonから利用します。
LLM / モデルLLMは「大規模言語モデル」の略で、文章を処理して応答を生成するAIモデルです。本アプリでは、利用者が用意したモデルファイルをPC上で読み込み、チャットの応答生成に使います。
ローカルLLMインターネット上の生成AIサービスへ会話を送るのではなく、自分のPC上でLLMを実行する方式です。本アプリの通常のLLM推論はローカルで行います。
推論（Inference）読み込んだモデルへ入力を渡し、そのモデルから応答を生成する処理です。このREADMEで「LLM推論」と書いている場合は、主にチャットの回答を生成する処理を指します。
プロンプト（Prompt）LLMへ渡す指示や入力文のことです。利用者の入力だけでなく、System Prompt、会話履歴、要約、添付内容などが組み合わされてモデルへ渡される場合があります。
GGUFllama.cpp 系で利用されるモデルファイル形式です。本リポジトリにはGGUFモデル本体を同梱していないため、利用者が別途用意します。
量子化（Quantization）モデルの重みを少ないビット数で表現し、モデル容量やRAM・VRAM使用量を抑える方式です。Q4_K_M、Q8_0などが量子化形式の例です。
llama.cppGGUF形式のLLMをCPUやGPUで実行するための推論エンジンです。本アプリではllama-cpp-pythonを介して利用します。
llama-cpp-pythonPythonからllama.cppを利用するためのライブラリです。本アプリはこれを通してGGUFモデルを読み込み、LLMへ入力を渡して応答を生成します。
CPUPCの汎用的な計算処理を担当するプロセッサです。本アプリはGPUを使えない場合やGPUメモリが不足した場合、LLMやWhisperの処理をCPU側で行うことがあります。
RAMWindowsやアプリが使用するPC本体側のメモリです。モデルをCPUで動かす場合や各種処理で使用され、容量が不足すると動作が遅くなったり処理を続けにくくなったりします。
GPUもともとは画像処理向けのプロセッサですが、LLMの大量計算にも向いています。対応するNVIDIA GPUを使うと、CPUだけで実行するより生成が速くなる場合があります。
VRAMGPU専用メモリです。GPUへ配置したモデル、生成処理、Whisperなどが使用します。不足するとGPU配置を減らしたりCPUへ切り替えたりする場合があります。
CUDANVIDIA GPUを汎用計算に利用するための基盤です。本アプリのGPU向け構成では、CUDA対応のllama-cpp-pythonなどを利用します。
コンテキスト / コンテキスト長 (n_ctx)コンテキストは、LLMがその生成時に参照する会話履歴、今回の入力、system prompt、添付内容などをまとめた情報です。コンテキスト長は、それらと生成予定分を含めて1回の推論で扱える量の上限です。
トークンLLMが文章を分割して処理する単位です。1トークン＝1文字ではなく、日本語や英語、記号などによって分割のされ方が変わります。コンテキスト長や生成上限も主にトークン数で管理されます。
GPUオフロード / GPU Layersモデル内部のレイヤーの一部または全部をGPUへ配置して処理することです。本アプリではFull GPU、約75%・50%・25%の部分オフロード、CPUを選択できます。GPUへ多く配置するほど一般に高速化しやすい一方、より多くのVRAMを使います。
フォールバック希望した方法で処理できない場合に、安全に別の方法へ切り替えることです。本アプリでは、VRAM不足などに応じてGPU配置を減らしたりCPUへ切り替えたりする経路があります。
APIアプリ同士が決められた形式でデータをやり取りするための窓口です。本アプリではBiologやkakeibo-bridgeなど、別プロセスで動くローカルサービスとの連携にAPIを使用します。
POSTAPIへデータを送信するときに使われる方法の1つです。本アプリでは、利用者が内容を確認した後に健康記録や家計簿候補をローカルAPIへPOSTします。
Whisper音声を文字へ変換する音声認識モデルです。本アプリではマイク入力の文字起こしに使用します。設定や空きVRAMに応じてCPUまたはGPUを利用します。
TTS / Windows SAPI5TTSはText-to-Speechの略で、文章を音声として読み上げる仕組みです。本アプリではWindowsのSAPI5を利用します。
System Prompt / PersonaAIの基本的な応答方針、役割、話し方などを指定する情報です。chat_settings.jsonや外部promptファイルから設定できます。
Vision / projector / mmproj画像入力をLLMで扱うための機能と補助モデルです。Vision対応モデルを使用し、対応するprojector / mmprojを設定した場合に画像を扱えます。
DPAPIWindowsが提供するデータ保護機構です。本アプリでは通常の会話履歴を現在のWindowsユーザースコープで暗号化して保存します。
.shiro-export会話履歴を別環境へ持ち出すためのパスフレーズ付き暗号化エクスポート形式です。保存済み添付ファイル本体は含みません。

もっと詳しく知りたい方へ

このREADMEでは、利用時に特に重要な用語だけを説明しています。LLMの読み込み、コンテキスト、GPU / VRAM、Whisper、API連携、暗号化、各ファイルの役割などをさらに詳しく知りたい場合は、コード解説（やさしい版）を参照してください。

動作環境

項目 要件
OS Windows 11（64bit）
Python 3.12.10（64bit）
GPU NVIDIA GPU推奨（VRAM 8GB以上）／CPUのみでも動作可
RAM 8GB以上推奨
Biolog API（任意） BIOLOG_URLで指定するローカルAPI（既定値：http://localhost:8766）
家計簿API連携（任意） 別途用意したローカルのkakeibo-bridge API（既定値：http://127.0.0.1:8767/api/kakeibo/record）

Mac・Linuxは非対応です。
TTSにWindows SAPI（win32com）を使用しているため、Windows専用となっています。
Biologは別プロジェクトです。標準ComposeではAPIの8766とUIの8501を127.0.0.1だけに公開します。認証は実装されていないため、公開範囲を変更する場合はBiolog側のセキュリティ説明を確認してください。

⚠️ 必ずお読みください

音声入力について

音声入力は周囲の音（テレビ・エアコン・会話等）を拾うことがあります。
これにより意図しない発話が送信されるハルシネーションが発生する場合があります。

対処方法：

免責事項

セットアップ

推奨：自動セットアップランチャー

通常は、同梱の Easy_LLM_Local_Chat.bat を使用してください。
Python 3.12（64bit）の確認、.venv の作成、GPU / CPU向け依存ライブラリの選択とインストール、アプリ起動までをまとめて行います。

事前準備：Python 3.12.10（64bit）
Python本体は自動ダウンロードしません。あらかじめ公式配布のPython 3.12.10（64bit）をインストールしてください。
https://www.python.org/downloads/release/python-31210/
インストール時は 「Add Python to PATH」 を有効にすることを推奨します。

使い方

  1. ZIP版は任意のフォルダへ展開します。Gitで取得した場合はリポジトリルートへ移動します。
  2. Easy_LLM_Local_Chat.bat をダブルクリックします。
  3. 初回だけ .venv を作成し、必要な依存ライブラリをインストールします。初回は数GB規模のダウンロードが発生する場合があります。
  4. セットアップ完了後、そのままLLM Local Chatを起動します。
  5. 2回目以降は、使用するrequirementsファイルに変更がなければ依存ライブラリの再インストールを省略して起動します。

ランチャーは nvidia-smi.exe でNVIDIA GPUを確認できた場合は requirements.txt（CUDA 12.4）、確認できない場合は requirements-cpu.txt を選びます。判定を固定したい場合はコマンドプロンプトまたはPowerShellから次のように実行できます。

Easy_LLM_Local_Chat.bat -Backend cu124
Easy_LLM_Local_Chat.bat -Backend cpu

依存ライブラリの導入には --no-cache-dir を使用するため、pip共有キャッシュの権限問題を回避しやすい構成です。管理者権限は不要で、Windows全体のPowerShell実行ポリシーも変更しません。Go、Inno Setupなどの追加ビルドツールも使用しません。

既存の.venvについて：
既存の.venvがPython 3.12（64bit）でない場合、ランチャーは勝手に削除せず停止します。必要に応じて既存環境を退避または削除してから再実行してください。

NVIDIA GPUを使用する場合：
requirements.txtはCUDA 12.4対応のビルド済みwheelを使用します。対応するNVIDIAドライバーが必要です。自動判定で問題がある場合は -Backend cpu でCPU版を選択できます。

手動でインストールする場合

以下は、従来どおり仮想環境と依存ライブラリを自分で管理する場合の手順です。

事前準備①：Pythonのインストール
Python 3.12.10（64bit） をインストールしてください。
https://www.python.org/downloads/release/python-31210/

コマンドからpythonを使用する場合は、インストーラーの 「Add Python to PATH」 を有効にしてください。

Python 3.12の公式サポート予定（2026年7月28日確認）

公式情報：

事前準備②：Git（GitHubからcloneする場合のみ）
ZIP版を展開して使う場合、Gitは不要です。GitHubからcloneする場合は以下からGitをインストールしてください。
https://git-scm.com/download/win

事前準備③：NVIDIA GPUを使用する場合
本リポジトリのrequirements.txtは、CUDA 12.4対応のビルド済みwheelを使用する構成です。対応するNVIDIAドライバーが必要です。
CUDA Toolkit本体は、ビルド済みwheelだけで動作する環境では常に必須とは限りませんが、ソースからビルドする場合や実行環境によっては必要です。CUDA関連のエラーが出る場合は、使用するwheel・ドライバー・CUDA環境の対応関係を確認してください。
CPUのみで使用する場合、CUDA Toolkitは不要です。requirements-cpu.txtを使用してください。

1. リポジトリを取得

Gitを使用する場合：

git clone https://github.com/shinosan1/LLM_Local_Chat.git
cd LLM_Local_Chat

ZIP版の場合は展開したフォルダを開いてください。

2. 仮想環境の作成

python -m venv .venv

PowerShellの実行ポリシーを変更せず、以降は仮想環境のPythonを直接指定します。

3. 依存ライブラリのインストール

NVIDIA GPU・CUDA 12.4を使用する場合：

.\.venv\Scripts\python.exe -m pip install --no-cache-dir -r requirements.txt

CPUのみで使用する場合：

.\.venv\Scripts\python.exe -m pip install --no-cache-dir -r requirements-cpu.txt

別のCUDAバージョンを使用する場合：
どちらのファイルもそのまま適用せず、torch関連とllama-cpp-pythonを利用環境に対応する公式配布へ変更してください。

PyAudioのインストールでエラーが出る場合：
PythonとPyAudioの対応バージョンを確認し、PyPIで配布されている公式wheelを利用してください。非公式インストーラーを経由した導入は推奨しません。

4. GGUFモデルを用意する

Hugging Face など信頼できる配布元から、対応する.gguf形式のモデルをダウンロードしてください。保存場所は任意ですが、管理しやすいようmodels/フォルダへの配置を推奨します。 動作確認済み：gemma-3-4b-it-q4_k_m.gguf、gemma-4-E4B-it-Q4_K_M.gguf

⚠️ 初回起動時の注意：
起動時マイクを有効にしている場合、音声認識用Whisperモデルが初回ロード時に自動ダウンロードされます。目安はsmallが約0.5GB、mediumが約1.5GBですが、モデルの版により変動します。設定とVRAM状況によっては両方が必要になるため、十分なディスク空き容量を確保してください。ダウンロード時はインターネット接続が必要です。マイク無効時はWhisperをロードしません。

動作確認済みモデル一覧

本アプリで動作確認済みのGGUFモデルの一覧です。
すべて Hugging Face からダウンロードできます。
ファイルは任意の場所に保存できます。管理しやすいようmodels/フォルダへの配置を推奨します。

⚠️ ダウンロードについて：
モデルによってはHugging Faceへのアカウント登録および利用規約への同意が必要です。
各モデルのページで確認してからダウンロードしてください。

⚠️ 免責：
各モデルの利用規約・ライセンスはモデルごとに異なります。
ダウンロード前に必ず各モデルのHugging Faceページで利用規約を確認してください。
本アプリはモデルの利用に関して一切の責任を負いません。

量子化形式の目安： Q4_K_Mは、品質・容量・速度のバランスを取りやすい一般的な候補です。最適な形式はモデルと実行環境により異なります。

モデル名 パラメータ 備考 ダウンロード
gemma-3-4b-it-q4_k_m 4B 動作確認済み リンク
gemma-4-E4B-it-Q4_K_M 8B（有効4B） 動作確認済み リンク
phi-3.5-Q8_0 3.8B 動作確認済み リンク
LFM2.5-1.2B-Instruct-Q4_K_M 1.2B 動作確認済み（起動時に警告が出ますが動作に問題なし） リンク

リンク切れの場合はHugging Face（https://huggingface.co/）でモデル名を直接検索してください。

5. アバター画像を用意する（任意）

以下の4枚のPNG画像を avatars/ フォルダに配置してください：

ファイル名 内容
default_avatar.png 通常状態
speaking_avatar.png 口を開けた状態
blink_avatar.png 目を閉じた状態
blink_speaking_avatar.png 目を閉じ口を開けた状態

画像がない場合は透明画像で代替されます（アバターなしで動作します）。

6. モデルを設定する

chat_settings.jsonがない場合も、アプリはコード既定値で起動を試みます。既定のモデルが見つからない場合は読込エラーが表示されますが、メイン画面の「ファイル」→「設定」を開き、「参照」ボタンから用意したGGUFモデルを選択して適用できます。保存した設定はchat_settings.jsonへ記録されます。

起動前に手動設定したい場合だけ、chat_settings.json.exampleをchat_settings.jsonへコピーし、model_pathなどを編集してください。

パーソナライズとVisionは、設定画面ではなくchat_settings.jsonで設定します。既存の設定ファイルに次のキーがなくても従来どおり起動します。

{
  "system_prompt": "",
  "user_personalization": "",
  "response_language": "回答は必ず日本語のみで行ってください。",
  "reasoning_visibility_instruction": "内部の思考過程、分析、推論、計画は表示せず、ユーザーに見せる最終回答だけを出力してください。",
  "external_prompt_files": {
    "system_prompt": "prompts/system.md",
    "user_personalization": "",
    "user_profile": "prompts/profile.txt",
    "instructions": []
  },
  "vision_enabled": false,
  "vision_handler": "gemma4",
  "vision_projector_path": ""
}

外部promptはUTF-8の.txt / .mdに対応し、相対パスはアプリ配置フォルダ基準です。inline system → external system → inline personalization → external personalization → response language → reasoning visibility → external profile/instructionsの順で併用し、完全に同一の文章と同一ファイルだけを重複挿入しません。外部promptの欠損・形式・文字コード・サイズのエラーは警告を表示し、inline設定を含む読める設定だけで起動を継続します。

Visionを使う場合は、現在のllama-cpp-python 0.3.34で利用できるgemma4またはllava15を指定し、対象モデルに対応するprojector / mmproj GGUFをvision_projector_pathへ設定してください。vision_enabledの既定値はfalseです。

7. 起動

自動セットアップランチャーを使用する場合は、以後も Easy_LLM_Local_Chat.bat を実行してください。依存関係に変更がなければ、そのままアプリを起動します。

手動インストールの場合：

.\.venv\Scripts\python.exe LLM_Local_Chat.py

⚠️ 起動時間について
起動後、LLMモデルの読み込みに30秒〜数分かかります（モデルサイズ・環境によります）。
ステータスバーに「⏳ モデル読込中…」と表示されている間はチャットできません。
また音声認識（Whisper）の初期化にも別途数秒〜10秒程度のタイムラグがあります。
マイクアイコンが有効になるまでしばらくお待ちください。

8. 家計簿API連携を使用する場合（任意）

本リポジトリ単体では、家計簿台帳への登録はできません。LLM Local Chat内で取引候補を生成・検証・確認できますが、確認済み候補の送信には、別途用意して起動したローカルのkakeibo-bridge APIが必要です。

本リポジトリには、これらの外部コンポーネントの入手・起動スクリプトはありません。家計簿API連携を使用しない場合、通常のチャット機能はこのAPIを必要としません。

使い方

基本操作

起動するとメインウィンドウとアバターウィンドウが開きます。
ステータスバーが「✅ 待機中」になったらチャット可能です。

テキスト入力欄にメッセージを入力して Enter キーまたは「送信」ボタンで送信します。
Shift + Enter で改行できます。

ファイル添付

入力欄上の「📎 ファイルを添付」から、TXT / MD / JSON / CSVまたはPNG / JPEGを選択できます。本文あり・添付あり、本文だけ、添付だけのいずれも送信できます。本文も添付もない場合は送信しません。添付は通常チャットだけで使用でき、最大8件、画像はそのうち1枚までです。同名でも内容が異なるファイルは内部IDで区別し、data.csv、data.csv (2)のように表示します。

添付時点の内容はchat_logs/attachments/<session-id>/以下のアプリ管理領域へ、元ファイル名ではなく内部IDを使ってコピーします。送信後も「チャット添付: ファイル名」の表示が残り、「続けてください」などの後続質問へ同じ内容を1ターン内で重複させず再投入します。新しいチャットを開始しても元チャットの添付は削除されず、別チャットを開けばそのチャット固有の添付へ切り替わります。保存済みチャットを再読込したときとアプリ再起動後にも復元します。

保存済み添付は元ファイルとは別コピーです。元ファイルを編集・移動・改名・削除しても自動更新されません。最新版を使う場合は、現在チャットの古い添付を解除して再添付してください。添付は重要ファイルのバックアップシステムではなく、アプリ内添付を唯一の保存場所として利用しないでください。

入力欄の「添付解除」は、確認ダイアログで同意した場合に、現在のチャットに紐づくすべての添付と対応するアプリ管理領域のコピーを削除します。会話本文とAI回答、元ファイル、別チャットの添付は削除しません。チャット自体を削除した場合は、そのチャット専用の添付も内部ID・セッションIDで削除します。削除した添付は過去チャットから再参照できず、アプリによる復元は保証されません。

保存管理の操作経路は、ファイル → 設定 → 保存済み添付ファイル → 選択した添付を削除または保存済み添付ファイルをすべて削除です。一覧ではファイル名、種類、サイズ、紐づくチャット、状態、総件数、合計容量を確認できます。一括削除は現在のアプリ保存領域で管理される全チャットの保存済み添付が対象で、通常の会話履歴は残ります。部分失敗時は成功・失敗・スキップ・再試行待ち件数を表示し、完了していないのに「すべて削除しました」とは表示しません。

履歴JSONへ直接保存するのは、内部ID、basename、種類、サイズ、SHA-256等の復元用メタデータだけです。元ファイル絶対パス、TXT / MD / JSON / CSV本文、画像bytes、base64、data URIは埋め込みません。ただし、LLMが添付内容やファイル名を回答へ引用・要約した場合、そのAI回答は通常の会話履歴として保存され、後の要約メモリにも含まれる可能性があります。

本アプリはユーザーアカウント単位の添付分離・認証・権限管理を提供しません。同じWindowsアカウント、同一PC、共有フォルダ等で同じアプリデータ保存領域を複数人が使用する場合、一括削除はその保存領域を利用する他のユーザーを含む全チャット添付へ影響する可能性があります。Windowsの別ユーザーであっても同じ保存先を共有する場合は、ユーザー単位の保護を保証しません。ローカルLLMであることだけで、PCへの不正アクセス、マルウェア、同一アカウントの別利用者、アクセス権を持つプロセスから完全に安全になるわけではありません。

個人情報、業務機密、パスワード、APIキー、アクセストークン、秘密鍵等を含むファイルは不用意に添付しないでください。TXT / MD / JSON / CSV内のPowerShell、shell、Python、JavaScript等は自動実行せず、LLMへの入力データとして扱います。一方、文書内の「これまでの指示を無視してください」のような文章がprompt injectionとして回答へ影響する可能性はあります。外部から取得した文書を信頼できる命令として扱わず、生成結果を確認せず重要な操作へ利用しないでください。拡張子、UTF-8、ファイルサイズ、画像形式・画素数の検査は異常入力の影響を抑える制限であり、ファイルや回答の安全性を完全には保証しません。

テキストは1ファイル1MiB、画像は1ファイル10MiBかつ16メガピクセル以下です。上限超過やUTF-8で読めないテキストは切り捨てずに拒否します。添付がある間は、system prompt・要約・全会話履歴・添付・新規入力・応答予約を合わせてcontextへ収まらない場合、履歴を黙って省略せず警告します。画像入力では4,096画像トークンを事前予約しますが、モデル固有の実トークン数を送信前に完全保証できないため、実行時にcontext超過として拒否される場合があります。

保存済み添付はアプリ終了後も残るため、画像や多数の添付を使い続けるとディスク使用量が増えます。自動期限削除、自動容量削減、ごみ箱、自動バックアップ、添付暗号化は提供しません。設定画面の件数・合計容量・個別削除・一括削除を使って管理してください。実体欠損、読込不能、サイズ不一致、保存済みSHA-256との不一致を検出した添付はLLMへ渡さず、警告します。

.shiro-exportには添付実体も添付メタデータも含まれません。インポート後のチャットへ添付は復元されないため、.shiro-exportを添付ファイルのバックアップとして使用しないでください。

音声入力

コード上の既定値とchat_settings.json.exampleでは、起動時のマイク・TTS読み上げはともにOFFです。「ファイル」→「設定」で次回起動時の状態を変更できます。 マイクボタンをクリックするとONになります。
ONの状態で一定以上の音量を検知すると自動的に録音を開始し、Whisperで文字起こしして送信します。
再度クリックするとOFFに戻ります。

起動時マイクを有効にする設定とWhisper実行モードは、次回起動時に反映されます。初回のWhisperダウンロード・ロードには時間がかかる場合があります。 TTS読み上げ中はハウリング防止のため音声入力が自動的に抑制されます。

TTS（読み上げ）

AIの返答をWindows SAPIで読み上げます。起動時はOFFがデフォルトです。
メニューからTTSのON/OFFを切り替えられます。
読み上げ中は「停止」ボタンで中断できます（タイミングによっては中断できない場合があります）。

健康記録モード（Biolog連携） — v1.1.0

💪ボタンをクリックすると健康記録モードがONになります。
このモードでは、計測値・食事・活動内容・メモを話しかけると、確認後にBiolog APIへデータをPOSTします。食事ログ、行動ログ、メモだけの登録にも対応します。

入力例：

体重65kg、体脂肪20%、朝はオートミールを食べた

動作結果：

事前準備： Biolog側の文書とComposeを確認してAPIを起動し、LLM Local Chatを実行するPCからヘルスチェックへ接続できることを確認してください。 標準ComposeではBiolog APIを127.0.0.1:8766に限定して公開します。

curl http://localhost:8766/api/health/health

環境変数でエンドポイントを変更できます：

$env:BIOLOG_URL = "http://localhost:8766"  # デフォルト
.\.venv\Scripts\python.exe LLM_Local_Chat.py

計測値・食事ログ・行動ログ・メモがすべて空の場合だけ送信しません。食事ログ・行動ログ・メモを明示した入力は、ユーザー原文から決定的に解析されます。

ゲストモード

「ゲストモード: OFF」ボタンをクリックするとゲストモードがONになります。
ゲストモードがONのとき、会話履歴はchat_logs/へ自動保存されず、ゲスト会話を暗号化エクスポートすることもできません。ただし、実行中のメモリ、標準出力やOS側のログ、連携先APIへ送信したデータまで消去・保護する機能ではありません。 プライベートな会話や一時的な用途に使用してください。
再度クリックすると通常モードに戻り、新しいセッションが開始されます。

チャット履歴

左ペインに過去の会話一覧が表示されます。クリックで読み込めます。
上部の検索欄でタイトル・要約の部分一致検索ができます。
右クリックで個別削除が可能です。
履歴はアプリ配置フォルダ内のchat_logs/へ、DPAPI暗号化されたJSONエンベロープとして保存されます。ファイル名、件数、サイズ、更新日時は暗号化されません。 設定画面で保存期間を選択できます。有限期間を初めて適用するときは削除候補件数を表示し、確認後すぐに削除します。外部バックアップは自動削除されないため、バックアップ側の保持期間も別途管理してください。

要約メモリ

一定ターン数ごとに会話の要約が自動生成され、次の応答に注入されます。
長期会話でもコンテキストが維持されやすくなっています。

設定

メニューから「ファイル」→「設定」を開くと、以下の項目を変更できます。

項目 内容 推奨値 / アドバイス
モデルファイル 使用する GGUF モデルのパスを指定します。 「参照」ボタンから任意の場所にある対応GGUFファイルを選択できます。
LLM GPUオフロード モード 自動・Full GPU・約75%・約50%・約25%・CPUから希望配置を選びます。 保存後、旧モデルを解放してからバックグラウンドで再読み込みし、再起動なしで反映します。安全条件を満たさない上位配置は下位へフォールバックします。
現在の実行状態 実際にロード成功したGPUオフロード率・配置レイヤー数・Full/Partial/CPUを表示します。 読み取り専用です。「GPU配置を再評価」は自動モードの配置を現在のVRAMから選び直します。
コンテキスト長 AIが一度に記憶・処理できる情報の長さ（n_ctx）です。 通常は 8192 を推奨。VRAM不足で動作が不安定な場合は数値を下げてください。
最大返答トークン数 AIが一度の返答で出力する最大トークン数です。文字数とは一致しません。 短い会話なら 256〜512、長文が必要なら 1024 程度が目安です。VRAM状況により実効値が自動的に削減される場合があります。
会話の自由度 AIの回答の多様性を調整します（temperature）。 0.1〜0.5: 堅実・正確（事実確認向き）<br>0.7〜1.0: 標準的（自然な雑談向き）<br>1.2〜1.5: 独創的（アイデア出し向き）
音声検出感度 マイクが音声を拾う際のしきい値（RMS 閾値）です。 数値が小さいほど高感度になります。周囲の音で誤作動する場合は 200〜300 程度に上げてください。

アバター

アバターウィンドウはドラッグで自由に移動できます。
右クリックで表示/非表示を切り替えられます。

VRAM安全フィルタ（v1.2.0）

LLM（Gemma 4 E4B、総8B／有効4B）とWhisper mediumを同一GPUで動かす際のVRAM競合を緩和します。

設計思想

「VRAMを管理する」ではなく「VRAMから逃げる」 — OOMの完全防止は不可能です。 この機能は「クラッシュではなく性能劣化」で済ませることを目標としています。

自動フォールバックの仕組み

状況 動作
LLMロード前の空き容量がGGUFサイズ+予約領域以上 n_gpu_layers=-1で全層GPUオフロードを要求
Full条件未満でGGUF総レイヤー数を取得できる モデルサイズの概算と予約領域から約75%→50%→25%を順に検討
CUDA非対応、GPU情報取得不能、partial条件も満たさない n_gpu_layers=0（CPU実行）にフォールバック
GPUロード時の明示的なVRAM不足、またはロード後の最低予約量不足 安全に解放して一段低い候補を検討
Whisperモードauto・空き4096MB以上 GPU版mediumを使用
Whisperモードauto・空き2048〜4095MB GPU版smallを使用
Whisperモードauto・空き2048MB未満 CPU版smallのみで運用
推論時の実空き容量 < 予約領域（512MBまたは総容量の6%） 自動モードでは旧LLMを解放後、現在より低いoffloadへ再配置して同じ入力を1回だけ継続。安全に再配置できない場合だけエラー表示
推論時の実空き容量 512〜1024MB max_tokens を25%に削減
推論時の実空き容量 1024〜1536MB max_tokens を50%に削減
GPU使用率 > 88% Whisper を CPU に切替（ヒステリシス付き）
GPU版Whisperロード済みでGPU使用率 < 70% Whisper を GPU に切替復帰

DEBUGログの見方

.\.venv\Scripts\python.exe -c "import logging; logging.basicConfig(level=logging.DEBUG); exec(open('LLM_Local_Chat.py').read())"
プレフィックス 内容
[Monitor] VRAM瞬時値・GPU% の収集ログ
[GPU] CUDAバックエンド対応と要求したGPUレイヤー数
[VRAM] LLMロード前後と推論直前の総量・使用量・実空き容量
[Whisper] GPU→CPU / CPU→GPU 切替ログ
[Whisper] CPU/GPUモデルのロード・スキップ理由

既知の限界

Whisper実行モードは設定画面で自動・GPU small・GPU medium・CPU smallから選択でき、次回起動時に反映されます。手動GPU指定でも安全な空き容量を満たさない場合はCPU smallへフォールバックします。実際に使用中のモデルは、生成設定の「現在のWhisperモデル」で確認できます。

生成設定では、希望するLLM GPUオフロード モードを選択し、アプリを再起動せず反映できます。実際にロード成功したGPUオフロード率と配置レイヤー数（例: 76%（32 / 42層・Partial GPU・自動選択））は別の読み取り専用欄で確認できます。これはLLMレイヤーの配置割合であり、WindowsのGPU使用率ではありません。希望モードだけを設定ファイルへ保存し、実配置のruntime stateは保存しません。

よくある質問

Q. OllamaやLM Studioを使わないのはなぜですか？
A. llama.cppをPythonバインディング（llama-cpp-python）から直接呼び出し、LLM推論をローカルで実行するためです。必要な依存ライブラリとモデルを取得済みで、オプションのBiolog・家計簿API連携も別プロセスのローカルAPIへ限定した構成では、通常の会話処理に外部のLLMサービスを使用しません。セットアップ、モデル取得、外部リンクの閲覧にはインターネット接続が必要です。

Q. CPUだけでも動きますか？
A. CPU実行へフォールバックできます。CPU専用PCでは、セットアップ時にrequirements-cpu.txtを使用してください。応答速度はモデルサイズ、量子化形式、CPU、メモリ帯域、コンテキスト長などに大きく依存し、実用的な速度になるとは一律に保証できません。

Q. Whisperのモデルは自動でダウンロードされますか？
A. 起動時マイクを有効にした場合、初回ロード時にWhisperモデルが自動的にダウンロードされます。マイク無効時は、TTSが有効でもWhisperをロードしません。

Q. TTSには何を使用していますか？ A. win32com.client.Dispatch("SAPI.SpVoice") により、Windows SAPI5をワーカースレッドから直接制御しています。

実装構成とテスト

LLM_Local_Chat.py をエントリーポイントとし、生成制御は controller.py、LLM実行は llm_service.py、プロンプト構築は prompt_builder.py、履歴管理は session_store.py、音声処理は audio_workers.py に分割されています。

回帰テストは標準ライブラリの unittest で実行できます。

テストファイルは tests/ 配下にまとめてあります（.venv がプロジェクト直下にあるため、素の unittest discover -v を使うと .venv 内の依存パッケージのテストまで収集してしまいます。-s tests で収集範囲を限定し、-t . でプロジェクトルートをトップレベルディレクトリに指定してください）。

.\.venv\Scripts\python.exe -m unittest discover -s tests -t . -p "test*.py" -v

導入・運営責任者の方へ

本アプリを業務環境に導入される際は、以下のセキュリティ上の特性を情報セキュリティ担当者と共有・確認してください。

脆弱性を報告する場合はSECURITY.mdを確認し、詳細を公開Issueへ投稿しないでください。

セキュリティ上の特性

確認済みの範囲

⚠️ 使用するモデルについての注意：
GGUFモデルファイル自体が独立して通信や攻撃を行うものではありません。ただし、信頼できない、または破損したファイルがモデル読み込みライブラリの脆弱性を突く可能性があります。信頼できる配布元から取得し、llama.cppおよびllama-cpp-pythonを定期的に更新してください。モデルの仕様・ライセンスも確認してください。

導入・運営前に確認すべき点

推奨事項

免責事項

本アプリは個人が学習・研究目的で開発したものです。
動作保証・サポートは一切行っておりません。利用により生じたいかなる損害についても作者は責任を負いません。

ライセンス

本ソフトウェアはMIT Licenseで公開しています。利用、複製、変更、結合、公開、配布、サブライセンスおよび販売は、MIT Licenseの条件に従って許可されます。

GGUFモデル、音声モデル、依存ライブラリおよび生成物には、それぞれ別のライセンスや利用条件が適用される場合があります。利用者自身で配布元の条件を確認してください。

本ソフトウェアは現状有姿で提供され、動作・出力内容・AI回答の正確性を保証しません。詳細な保証の否認はLICENSEを参照してください。

関連文書

バージョン情報

現在のアプリバージョンは v1.8.5 です。 最新の変更内容と過去バージョンの詳細は CHANGELOG.md を参照してください。