Termux上でのローカルAI Webアプリの構築
Android端末でTermuxを実行し、AI API(特にNaraRouter)と統合し、オプションでHermes Agentを推論バックエンドとして使用するローカルWebアプリケーションを構築し実行します。
使用するタイミング
- ユーザーがスマホ上でローカルAIアシスタント/チャットインターフェースを希望する場合
- TermuxでPython/Flaskを使用してWebアプリを構築する場合
- 説明ベースのルーティングで複数のAI APIを統合する場合
- ブラウザのWeb Speech APIを介した音声モードを追加する場合
- チャット全体でセッションとメモリを管理する場合
- ユーザーが開発ツール(バイナリリリース、Rust/cargo、npm/npx、pip)のインストール手順を貼り付け、「インストールして使って」と言った場合 — まずは電話/Termux環境での実行可能性を評価し、許可を得てからインストールする
アーキテクチャパターン
ブラウザ(Android上のChrome) → Flaskバックエンド(Termux) → AI API
↓
Hermes Agent(オプション、脳として)
主要原則: Webアプリはインターフェース層です。Hermes Agent(使用する場合)は脳です。Flaskバックエンドがそれらを橋渡しします。
クイックスタート
# Termux内で
mkdir ~/sayip && cd ~/sayip
mkdir -p templates static/css static/js storage/sessions
# app.py — 最小限のFlaskスターター
from flask import Flask, render_template, request, jsonify
from pathlib import Path
import json, time, uuid, os
app = Flask(__name__, template_folder="templates")
HERMES_HOME = Path(os.path.expanduser("~/.hermes"))
SAYIP_STORAGE = Path(os.path.expanduser("~/sayip/storage"))
@app.route("/")
def index():
return render_template("chat.html")
@app.route("/api/chat", methods=["POST"])
def chat():
data = request.get_json()
# ... メッセージを処理し、APIを呼び出し、応答を返す
if __name__ == "__main__":
app.run(host="127.0.0.1", port=5000)
# 実行
python3 app.py
# Chromeで開く: http://127.0.0.1:5000
API統合パターン
NaraRouter(推奨)
NaraRouterは53以上のモデルを提供する統合AIゲートウェイで、無料枠があります。
キー形式: sk-nry-...(sk-nry-で始まる)
エンドポイント(すべて同じベースURL + Bearerキー):
| エンドポイント | タイプ | 用途 |
|---|---|---|
https://router.bynara.id/v1/chat/completions | OpenAI互換 | チャット、一般的なタスク |
https://router.bynara.id/v1/messages | Anthropic互換 | Anthropic形式のリクエスト |
https://router.bynara.id/v1/responses | OpenAI Responses | ステートフルな応答API |
https://router.bynara.id/v1/embeddings | OpenAI Embeddings | ベクトル埋め込み |
https://router.bynara.id/v1/models | LIST | プランで利用可能なモデルを取得 |
https://api-images.bynara.id/v1/images/generations | 画像生成 | テキストから画像へ |
https://api-images.bynara.id/v1/images/edits | 画像編集 | 画像編集 |
使用前にキーをテスト:
curl -s -X POST https://router.bynara.id/v1/chat/completions \
-H "Authorization: Bearer sk-nry-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"agnes-2.5-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
動作確認済みの無料枠モデル: agnes-2.5-flash, agnes-2.0-flash
プランのモデルを確認:
curl -s https://router.bynara.id/v1/models \
-H "Authorization: Bearer sk-nry-YOUR_KEY" | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin).get('data',[])]"
重要: 53のモデルすべてがすべてのプランで利用できるわけではありません。deepseek-v4-pro-0813-bynara にはクレジットが必要です。deepseek-v4-flash-free は含まれていない場合があります。設定前に必ずテストしてください。
NVIDIA NIM API(integrate.api.nvidia.com/v1)
NVIDIA NIMは、単一のOpenAI互換エンドポイントを通じて82以上のモデルを提供します。
ベースURL: https://integrate.api.nvidia.com/v1
エンドポイント: https://integrate.api.nvidia.com/v1/chat/completions
キー形式: nvapi-(例: nvapi-_qJeGmEP...)
使用前にキーをテスト:
curl -s -X POST https://integrate.api.nvidia.com/v1/chat/completions \
-H "Authorization: Bearer nvapi-..." \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{"model":"nvidia/nemotron-3.5-lightning-30b-a3b","messages":[{"role":"user","content":"hi"}],"max_tokens":10,"stream":true}'
動作確認済みの無料枠モデル(Termuxモバイルネットワークでテスト済み):
| モデルID | キー | ステータス | メモ |
|---|---|---|---|
nvidia/nemotron-3.5-lightning-30b-a3b | nvapi-... | 動作 | 高速(単純なタスクで約5〜7秒)、強力な推論、思考モード対応。モバイルで最も信頼性が高い。 |
gpt-oss-20b | nvapi-... | 動作 | OpenAI互換 |
deepseek-ai/deepseek-v4-pro-0813 | nvapi-... | タイムアウトのリスク | デスクトップでは動作するが、Termuxモバイルネットワークでは頻繁にタイムアウト |
moonshotai/kimi-k3 | nvapi-... | タイムアウトのリスク | ビジョン対応だが、モバイルネットワークではタイムアウト |
キーの非対称性の警告: すべてのモデルがすべてのキーで利用できるわけではありません。キー1(nvapi-_qJeGmEP...)はより広いアクセス権を持っています。キー2(nvapi-WDb7Rr...)はより制限されています — 一部のモデルは404を返します。設定前に、特定のキーでモデルをテストしてください。
無効なキーの指標:
401 Unauthorized— キーが無効/期限切れ- モデルに対して
404 Not Found— モデルがこのアカウント/キーに存在しない - 接続タイムアウト(30秒以上) — APIが遅い、またはこのネットワークから到達不能
- Teamorouter
sk-teamo-...キー → OpenAIエンドポイント(https://api.teamorouter.com/v1)でinsufficient_balance;Anthropicエンドポイント(https://api.teamorouter.com)ではモデルがサポートされていません。無効。deepseek-v4-pro-freeモデルを提供するが、残高がないと使用不可。
完全な詳細は references/nvidia-api.md を参照してください:モデル固有のPythonパターン(Nemotron思考モード、DeepSeek非ストリーミング、Kimiビジョンマルチモーダル)、ストリーミング reasoning_content 抽出、urllibのスレッドベースのハードタイムアウトパターン、ビジョンペイロード形式。
APIディスパッチエンジン
複数のAPIが設定されている場合、以下のことを行うディスパッチャを構築します:
- タスクを分類する(数学、コーディング、科学、一般)
- 説明テキストに基づいて最適なAPIを選択する
- 呼び出し、結果を返す
- 最初のAPIが失敗した場合、他のAPIにフォールバックする
統合の詳細は references/nararouter-api.md を参照してください。
requests ではなく標準ライブラリ urllib を使用
Termuxでは、pip install requests が大きなダウンロードでタイムアウトする可能性があります。代わりにPythonの標準ライブラリ urllib を使用してください — 常に利用可能で、JSON APIを問題なく処理できます:
import urllib.request, json
def call_api(url, payload, api_key):
data = json.dumps(payload).encode()
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
req = urllib.request.Request(url, data=data, headers=headers, method="POST")
with urllib.request.urlopen(req, timeout=30) as resp:
return json.loads(resp.read())
デザインの好み(ユーザー固有)
ミニマルでプロフェッショナル、AI生成感のない外観:
- ダークテーマ、狭い間隔、グラデーションなし、装飾的なシャドウなし
- 該当する場合は等幅フォント(コード、APIキー、タイムスタンプ)
- チャットバブルは単純な長方形 — 機能的な理由がない限り角を丸めない
- サイドバー = 単純なリスト、意味がない限りアイコンなし
- デザインをゼロから生成するのではなく、参考実装を検索する
- 迷ったら、機能を追加するよりも削除する
具体的なアンチパターン — これらはWebアプリをAI生成に見せるので削除すること:
- すべてのヘッダー/タイル/ボタンでの絵文字(
🤖、⚙、🎭、🔌、🧠、💬、🎤)— 削除。プレーンテキストのラベルのみ。 - ホバー時のアクセントグロー/ボックスシャドウ(
box-shadow: 0 0 12px var(--accent-glow))— 削除。フラットカラーのみ。 - バウンス/パルス/スライドダウンのキーフレームアニメーション(
@keyframes bounce、@keyframes pulse、@keyframes slideDown)— 削除。モーションデザインなし。 - アイコン付きのスプラッシュスクリーンようこそカード(
.welcome-screenとwelcome-icon、welcome-hintsグリッド)— 入力エリアの一行プレースホルダーに置き換える。 - ロゴの横の装飾的なブランドアイコン(
.brand-iconと絵文字)— 削除。 - ヘッダーを飾るリボン、バッジ、ステータスドット(
.health-badge、.health-dot)— 削除するか、純粋に機能的なものにする。 - グラデーション背景、グラスモーフィズム、半透明オーバーレイ — 絶対にしない。
経験則: ブラウザでページを開き、「人間の開発者がユーティリティツールのためにこのCSSを手書きするだろうか?」と自問する。答えが「いいえ」の場合(モーション、グロー、絵文字の装飾があるため)、削除する。通常のツールは、ターミナル、メモアプリ、またはミニマルなチャットのように見えるべきであり、ランディングページのようであってはならない。
音声モード:
- Web Speech API(
SpeechRecognition+SpeechSynthesis)を使用 — 無料、ブラウザ組み込み - テキスト/音声モードを切り替えるトグルボタン
- 音声モードでは:マイクが継続的にリッスン、音声→テキスト→送信、応答→音声
- 音声品質はChrome on Androidが提供するものに限定される — 「Ultronの声」を約束しない
ワークフローの好み(ユーザー固有)
パッケージをインストールする前に確認する: pip install や apt install を実行する前に、まずユーザーに確認する。これは譲れない。
継続的に進捗を表示する: タスクに数分以上かかる場合は、中間結果を表示する。出力なしで長時間姿を消さない。何かで行き詰まったら、その旨と試していることを伝える。
セキュリティに関する講義はしない: ユーザーはAPIキーのリスクを理解している。明示的に尋ねられない限り、キーのセキュリティ、露出、ベストプラクティスについて講義しない。該当する場合は、ユーザー自身が説明を提供している。
完璧なアーキテクチャよりも動作するソリューションを優先する: まずは何かを動かすこと。NaraRouterキーテストがこれを示している — キーをテストし、動作するモデルを見つけ、設定する。過剰に計画しない。
ストレージは揮発性 — 早期にGitHubにバックアップする: Termux/Androidでは、アプリのストレージ(~/sayip/storage/)はサーバー再起動、Termux再起動、またはデバイス再起動時に消去される可能性がある。APIキーと設定をセットアップした後、すぐにSSH経由でプロジェクトをGitHubリポジトリにプッシュして、設定を復元可能にする。セッション内では、storage/ が再起動後も存続することを前提としない — 再起動後は必ず再確認する。SSH-over-port-443のテクニック(references/termux-git-ssh.md を参照)は、モバイルネットワークがポート22をブロックすることが多いため、しばしば必要となる。
音声モードは、完了宣言前にエンドツーエンドでテストする必要がある: chat.js でのWeb Speech APIの配線(setupVoice、startListening、speakText)は、音声モードが機能することと同じではない。実際に電話のマイクに話しかけ、応答が音声で返ってくるのを聞いてテストする。ターゲットブラウザはChrome on Androidであり、それが重要であり、デスクトップChromeではない。
デバッグ
ポート5000が既に使用中:
fuser -k 5000/tcp # ポート5000のプロセスを強制終了
# またはssで確認:
ss -tlnp | grep 5000
Flaskアプリが起動しない/クラッシュする:
- 構文を確認:
python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" - 起動前にポートが空いているか確認する
timeout 15 python3 app.pyで実行して、ブロックせずに起動出力を確認する
APIが401/403/payment_requiredを返す:
- キーが無効、期限切れ、またはモデルがプランに含まれていない可能性がある
- アプリで設定する前に、curlでキーを直接テストする
/v1/modelsをチェックして、プランに実際にどのモデルが含まれているかを確認する
Pipインストールのタイムアウト:
- モバイルのTermuxでは、大きなパッケージに対してネットワークが遅い/不安定な場合がある
- 可能な場合は標準ライブラリの代替を使用する(requestsの代わりにurllib)
- どうしてもインストールする必要がある場合は、
pip3 install --timeout 30 <package>を使用してすぐに失敗するようにする
強制終了されたバックグラウンドFlaskプロセスがポートを一時的に保持する:
pkill -9 -f "[p]ython3 app.py"の後、再起動する前に2〜3秒待つ。- 「Address already in use」が表示された場合、古いプロセスがまだソケットを完全に解放していない — さらに長く待つ。
コード変更を反映するためにFlaskサーバーを再起動する前に、まず古いプロセスを強制終了する:
- パターン:
pkill -9 -f "[p]ython3 app.py" && sleep 3 && cd ~/sayip && python3 app.py & - 強制終了をスキップすると「Address already in use」が発生し、新しいインスタンスが起動しない。
- 再起動後は常に
curl -s --max-time 3 http://127.0.0.1:5000/api/healthで確認する。
ユーザーがWebアプリが壊れている/JSがバグっている/動作しないと報告した場合、次の順序で診断する:
- サーバーが実行中であることを確認:
curl -s --max-time 3 http://127.0.0.1:5000/api/health - 静的ファイルが200を返すことを確認:
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5000/static/style.css(およびapp.js、chat.js、voice.js、settings.js) - サーバーが実際に提供するHTMLを確認:
curl -s http://127.0.0.1:5000/ | grep -E 'static/|style.css|app.js|chat.js|voice.js'— HTML内のパスがFlaskが提供するものと一致することを確認する - 静的ファイルが404を返すが、HTMLリンクが
/static/style.cssではなくstyle.cssのような相対パスを示している場合、それがバグ — 両方のテンプレートを修正して/static/プレフィックスを使用する - JSファイルを読み、すべての
document.querySelector/getElementById/.querySelector呼び出しを、HTMLが実際に含むものと照合する — 要素が欠落するとスクリプト全体がクラッシュする - null参照クラッシュをチェック: ハンバーガー要素のないページでの
el("hamburger")、.wrapが存在しない場合のmessagesEl.querySelector(".wrap")、.composerが存在しない場合のdocument.querySelector(".composer .wrap")— これらはすべてIIFEをクラッシュさせ、ページ全体のJSをダウンさせる - 要素検索をガードする: 結果を使用する前に
var el = document.querySelector(selector); if (!el) return;とする
HTML/テンプレート編集後に、サーバーが実際に提供するものを確認してフロントエンドの修正を検証する:
- ページURLへのcurlと、静的パス(
/static/style.css、/static/js/app.js)のgrepで、修正が反映されたことを確認する。 - 静的ファイルURLへの直接curlで
-o /dev/null -w '%{http_code}'を使用して、200が提供されることを確認する。 - 実行中のサーバーに対して両方のチェックが合格するまで、HTML編集が有効になったと想定しない。
このプロジェクトで最も一般的な「すべてのJSがバグっている」原因:
- HTMLテンプレートが、Flaskの
/static/プレフィックス(/static/style.css、/static/js/app.js、/static/js/chat.js)の代わりに相対的な静的パス(style.css、app.js、chat.js)を使用している。 - ブラウザは
http://127.0.0.1:5000/style.cssをリクエスト → 404。CSSが読み込まれず、JSも読み込まれない → ページはスタイルが適用されず、機能しない。 - 修正: 両方のテンプレート(
templates/chat.html、templates/settings.html、templates/voice.html)にパッチを適用して、すべての静的アセット参照の前に/static/を付ける。
セッションストレージデバッグ
/api/sessions が空のリストを返す(期待されるセッションがない):
- セッションストレージディレクトリが存在し、書き込み可能であることを確認:
ls -la ~/sayip/storage/sessions/ - ディレクトリが存在しない場合、作成する:
mkdir -p ~/sayip/storage/sessions - ユーザーがすでに会話をしている場合にセッションが期待されるが空の場合、問題は
storage/ディレクトリ構造が正しくないか、サーバーがSAYIP_STORAGEパスを間違って解決している可能性がある。 - SQLiteの代わりにJSONファイルベースのストレージを確認:
storage/sessions/内のセッションファイルが.json拡張子で保存されていることを確認する(.txtや拡張子なしではない)。 SAYIP_STORAGEの値と、セッションファイルが書き込まれる実際のパスとの一致を確認: デバッグ出力用にprint(f"STORAGE PATH: {SAYIP_STORAGE}")を追加し、サーバーログで確認する。
file_path = os.path.join(SAYIP_STORAGE, "sessions", f"{session_id}.json") が間違った場所を指している:
os.path.joinの最初の引数が絶対パス(/home/user/sayip/storage)であることを確認する。相対パス(sayip/storage)の場合、CWDが変わると予期しない場所に解決される可能性がある。- 最も安全なパターン:
SAYIP_STORAGE = Path.home() / "sayip" / "storage"を使用して、フルパスが正しく構築されるようにする。 - デバッグ中は、アクセスされた実際のファイルパスを記録する:
logging.debug(f"Reading session file: {file_path}")。
storage/sessions/ ディレクトリが正しいが、セッションが ✗ として表示される:
- セッションファイルに完全な会話履歴が含まれていることを確認する。セッションをロードした後に
messages配列が空である場合、会話の初期化が適切に行われていない可能性がある。 - セッションロードとセーブの両方のコードパスで、メッセージ構造が一貫していることを確認する(すべて
role+content、または元の形式を保持)。 - APIがモデル形式に応じて異なる応答構造を返す場合、応答のマッピングが正しいことを確認する:OpenAI互換APIは
response["choices"][0]["message"]["content"]を使用し、Anthropic互換APIはresponse["content"][0]["text"]または同様の構造を使用する可能性がある。
セッション永続化の解決策 — 根本原因:
- セッションが正しく保存されない最も一般的な原因は、フロントエンドがサーバーが期待する形式で
session_idを送信しないことである。 - 各
fetch呼び出しの本文にsession_idが含まれていることを確認する。 - フロントエンドで
session_idを保存するためにlocalStorageまたはsessionStorageを使用して、ページのリロード後も持続するようにする。 - 新しい会話ごとに新しい
session_idを生成し、それをレスポンスで返して、フロントエンドが後続のリクエストで使用できるようにする。
// セッション処理の例(フロントエンド)
function getOrCreateSession() {
let sessionId = localStorage.getItem('session_id');
if (!sessionId) {
sessionId = crypto.randomUUID();
localStorage.setItem('session_id', sessionId);
}
return sessionId;
}
セキュリティに関する注意
APIキーはプレーンテキストで保存しないでください。 このスターターは概念実証です。実運用では、 .env ファイル、システムキーチェーン、または暗号化されたストレージを使用してください。
すべてのAPIキーをちゃんと管理する:
- NaraRouterキー(
sk-nry-...)は機密情報です。コードや設定ファイルにハードコードしないでください。 - キーをローテーションし、露出を制限します。
- アプリにキーを保存する必要がある場合は、暗号化するか、システムキーチェーン/安全なストレージを使用することを検討してください。
- キーが漏洩した場合、すぐに取り消して再生成してください。
ファイル構造
~/sayip/
├── app.py # メインのFlaskアプリケーション
├── templates/
│ ├── chat.html # メインチャットインターフェース
│ ├── settings.html # 設定ページ
│ └── voice.html # 音声モードページ
├── static/
│ ├── css/
│ │ └── style.css # スタイルシート
│ └── js/
│ ├── app.js # メインアプリケーションロジック
│ ├── chat.js # チャット機能
│ ├── voice.js # 音声機能
│ └── settings.js # 設定機能
├── storage/
│ └── sessions/ # セッションデータ(JSONファイル)
├── references/
│ ├── nararouter-api.md # NaraRouter APIの詳細
│ ├── nvidia-api.md # NVIDIA NIM APIの詳細
│ └── termux-git-ssh.md # TermuxでのSSHとGitの設定
└── README.md # このファイル
テスト
APIキーを設定した後:
- Flaskサーバーを起動:
cd ~/sayip && python3 app.py - Chromeで開く:
http://127.0.0.1:5000 - APIキーをUIで設定
- メッセージを送信してテスト
- セッションが保持されることを確認するためにページをリロード
今後の拡張
- より多くのNaraRouterエンドポイントの統合(画像、埋め込み)
- 応答時間を改善するためのキャッシュ
- Raspberry Pi / サーバーへのデプロイ
- ストリーミング応答
- ファイルアップロード
- マルチモーダル(画像分析)
元のリポジトリとの差分(ある場合)
ライセンス
MITライセンス。詳細は LICENSE ファイルを参照してください。