在 Termux 中執行本機 AI Web 應用程式
在執行 Termux 的 Android 裝置上建置並執行本機 Web 應用程式,整合 AI API(特別是 NaraRouter),並可選擇使用 Hermes Agent 作為推理後端。
使用時機
- 使用者想要在手機上執行本機 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 是一個統一的 AI 閘道,提供 53 個以上的模型,並有免費層級可用。
金鑰格式: 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 失敗,則回退到其他 API
整合詳細資訊請參閱 references/nararouter-api.md。
使用標準函式庫 urllib,而非 requests
在 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(box-shadow: 0 0 12px var(--accent-glow))— 移除。僅使用純色。 - 彈跳 / 脈動 / 滑入的關鍵影格動畫(
@keyframes bounce、@keyframes pulse、@keyframes slideDown)— 移除。不要有動態設計。 - 帶有圖示的啟動畫面歡迎卡片(含有
welcome-icon、welcome-hints網格的.welcome-screen)— 替換為輸入區域中的一行提示佔位文字。 - Logo 旁邊的裝飾性品牌圖示(帶有表情符號的
.brand-icon)— 移除。 - 裝飾標頭的功能帶、徽章、狀態點(
.health-badge、.health-dot)— 移除或使其純粹功能化。 - 漸層背景、毛玻璃效果、半透明疊加層 — 永不使用。
經驗法則: 在瀏覽器中開啟頁面,並問自己:「人類開發者會為一個工具手寫這樣的 CSS 嗎?」如果答案是否定的(因為它有動畫、發光或表情符號裝飾),就刪掉它。正常的工具看起來像終端機、筆記應用程式或極簡的聊天介面 — 而不是像著陸頁。
語音模式:
- 使用 Web Speech API(
SpeechRecognition+SpeechSynthesis)— 免費,瀏覽器內建 - 切換按鈕來切換文字/語音模式
- 在語音模式下:麥克風持續監聽,語音→文字→發送,回應→朗讀
- 語音品質受限於 Android 上 Chrome 提供的功能 — 不要承諾「Ultron 語音」
工作流程偏好(使用者特定)
安裝套件前先詢問: 在執行 pip install 或 apt install 之前,先詢問使用者。這是不可協商的。
持續顯示進度: 如果一個任務需要超過幾分鐘的時間,請顯示中間結果。不要長時間沒有輸出。如果卡住了,請說明情況以及正在嘗試的方法。
無安全說教: 使用者了解 API 金鑰的風險。除非明確要求,否則不要對金鑰安全、暴露或最佳做法進行說教。他們在相關時提供了自己的解釋。
偏好可行的解決方案勝於完美的架構: 先讓東西跑起來。NaraRouter 金鑰測試顯示了這一點 — 測試金鑰,找到可用的模型,進行設定。不要過度規劃。
儲存空間是易失性的 — 儘早備份到 GitHub: 在 Termux/Android 上,應用程式儲存空間(~/sayip/storage/)可能會在伺服器重啟、Termux 重啟或裝置重啟時被清除。在設定 API 金鑰和設定後,立即透過 SSH 將專案推送到 GitHub 儲存庫,以便可以恢復設定。在會話期間,不要假設 storage/ 在重啟後仍然存在 — 在任何重啟後都應重新檢查。由於行動網路會封鎖連接埠 22,通常需要使用 SSH-over-port-443 技巧(請參閱 references/termux-git-ssh.md)。
語音模式必須經過端到端測試才能宣告完成: chat.js 中的 Web Speech API 接線(setupVoice、startListening、speakText)不等同於語音模式可以運作。透過實際對著手機麥克風說話並聽到回應朗讀出來來測試。Android 上的 Chrome 是目標瀏覽器 — 這才是重要的,而非桌面版 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 在安裝大型套件時,網路可能緩慢/不穩定
- 盡可能使用標準函式庫替代方案(urllib 替代 requests)
- 如果必須安裝,請使用
pip3 install --timeout 30 <package>以快速失敗
被強制終止的背景 Flask 程序會短暫保留連接埠:
- 在
pkill -9 -f "[p]ython3 app.py"之後,等待 2-3 秒再重新啟動。 - 如果收到「Address already in use」,表示舊程序尚未完全釋放 socket — 請等待更長時間。
在重新啟動 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 連結顯示相對路徑(如
style.css)而非/static/style.css,這就是錯誤 — 將兩個模板都修補為使用/static/前綴 - 讀取 JS 檔案,並針對 HTML 實際包含的內容檢查每個
document.querySelector/getElementById/.querySelector呼叫 — 缺少元素會使整個腳本崩潰 - 檢查 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,並 grep 尋找靜態路徑(
/static/style.css、/static/js/app.js),即可確認修復已生效。 - 直接對靜態檔案 URL 執行 curl,並使用
-o /dev/null -w '%{http_code}'來確認它回傳 200。 - 在針對執行中的伺服器通過這兩項檢查之前,不要假設 HTML 編輯已生效。
此專案中最常見的「所有 JS 都壞了」原因:
- HTML 模板使用了相對靜態路徑(
style.css、app.js、chat.js),而非 Flask 的/static/前綴(/static/style.css、/static/js/app.js、/static/js/chat.js)。 - 瀏覽器請求
http://127.0.0.1:5000/style.css→ 404。沒有 CSS、沒有 JS 載入 → 頁面沒有樣式且無法運作。 - 修復:修補兩個模板中的路徑...