Portable-AI-USB架构深剖：Ollama+AnythingLLM如何搭建私有便携AI

Portable-AI-USB架构深剖：Ollama+AnythingLLM如何搭建私有便携AI

【免费下载链接】Portable-AI-USBA 100% offline, fully portable, zero-trace AI (Ollama + Llama 3 + AnythingLLM) that runs natively from a USB drive on Windows and Mac.项目地址: https://gitcode.com/gh_mirrors/po/Portable-AI-USB

Portable-AI-USB 是一个 100% 离线、完全便携的私有便携 AI 方案：它把 Ollama 推理引擎、GGUF 大模型和 AnythingLLM 聊天界面整套打包进 U 盘，在 Windows、Mac、Linux 上双击即用，全程无需安装、数据零残留、断网也能聊。本文将拆解它的分层架构、安装流水线与"零痕迹"便携机制，帮你彻底看懂这个开源项目是如何运转的。

一、架构总览：三层分工 🧩

整个项目只用了不到 10 个脚本文件，就把"私有 AI"完整搬进了 U 盘。它的分层非常清晰：

U盘根目录 ├── 入口脚本 install.bat / install.sh（只负责调度） ├── 核心脚本 install-core.ps1 / linux/install-core.sh（真正干活） ├── ollama/ ← AI 引擎（Ollama 可执行文件 + data/ 模型库） ├── models/ ← *.gguf 权重 + Modelfile-* 配置 + installed-models.txt ├── anythingllm/ ← 聊天界面本体 └── anythingllm_data/ ← 你的所有数据（100% 便携，拔走即带走）

这种"引擎—模型—界面—数据"四分离的设计是架构的灵魂：每一层都只依赖 U 盘内的路径，互相之间通过本地回环地址（127.0.0.1:11434）通信，因此 U 盘插到哪台电脑上，整套系统就能在哪台电脑运行。

二、安装架构：脚本如何分工协作 🛠️

2.1 入口与核心的两级结构

项目刻意采用"薄入口 + 厚核心"的脚本分层，同一套逻辑跨平台复用：

其中 Linux 侧最有意思的是"预检脚本" linux/preflight-check.sh——它在安装前做四件事：

1. 依赖检查：确认curl、tar、zstd、lsblk等工具齐备；
2. U 盘识别：通过lsblk/findmnt自动探测已挂载的可移动 USB 设备，多盘时让用户选择；
3. 空间与文件系统校验：要求 ≥16 GB 可用空间（推荐 32 GB），并明确拦截 FAT32——因为它单文件 4 GB 上限会挡住 7 GB 的 GGUF 模型，建议 exFAT；
4. 读写速度基准测试：写 128 MB 测试文件实测速度（写入 ≥10 MB/s、读取 ≥20 MB/s 为及格线），并据此推测你的 U 盘是 USB 2.0 还是 3.0，太慢会直接阻断安装。

这套"飞行前检查"（Preflight）的思路借鉴了航空领域：先验硬件，再装软件，避免装到一半才发现 U 盘撑不住。

2.2 六步安装流水线

install-core.ps1 与 linux/install-core.sh 虽然语言不同，但流程完全同构，统一为六步：

流水线结束后还有两个收尾动作，是架构的点睛之笔：

• 模型导入：临时拉起ollama serve，用ollama create把每个 GGUF 注册成 Ollama 模型（如nemomix-local），再停掉服务。模型元数据落在ollama/data下，即数据也留在 U 盘；
• 自动写配置：生成anythingllm_data/storage/.env，把 AnythingLLM 的 LLM 提供商指向外部 Ollama（LLM_PROVIDER=ollama），而非它内置的推理后端——这一步决定了后续对话走的是 U 盘里的模型。

💡 整个安装是幂等的：已下载的文件按大小校验自动跳过，重跑install.bat/install.sh既能补齐失败项，也能追加新模型。

三、核心机制：数据凭什么"零残留" 🔐

"Portable"（便携）与"Zero-trace"（零痕迹）是这个项目的两个卖点，其实现全靠环境变量重定向，几乎零侵入：

3.1 三组关键变量把一切锁进 U 盘

以 Linux 启动器 linux/start-linux.sh 为例，它启动时导出：

• OLLAMA_MODELS→U盘/ollama/data：Ollama 的模型库位置；
• STORAGE_DIR→U盘/anythingllm_data：AnythingLLM 官方可便携化变量；
• XDG_CONFIG_HOME/XDG_DATA_HOME/XDG_CACHE_HOME→ 均指向 U 盘：兜住 Electron 应用的配置/缓存写盘。

Windows 侧 start-windows.bat 更进一步，直接把APPDATA、LOCALAPPDATA甚至USERPROFILE重定向到anythingllm_data/，等于给 Electron 套了一层"沙箱"——应用以为自己写的是系统目录，实际全部落在 U 盘。

3.2 跨机迁移的"缓存清道夫"

Electron 应用会把绝对路径缓存写进config.json、Cache、Code Cache等文件，这是 U 盘插到另一台电脑后弹出 "JavaScript error" 的元凶。三个平台的启动器在每次启动前统一执行清除缓存操作，用"每次抹掉路径记忆"换来了真正的跨机可用。

3.3 各平台的细节妥协

四、运行架构：一次会话的完整生命周期 ⚡

以 linux/start-linux.sh 为例，双击start-windows.bat/start-mac.command后实际发生的事：

1. 读取模型清单：从models/installed-models.txt第一行取出默认模型名，显示已装模型列表；
2. 自愈配置：检查.env，若缺失或误用了 AnythingLLM 内置 Ollama（anythingllm_ollama），则自动重写为外部引擎配置；
3. 健康自检：确认ollama可执行文件与 AnythingLLM 客户端均存在，缺一即提示先跑安装脚本；
4. 清理路径缓存（见上文 3.2）；
5. 拉起引擎：后台执行ollama serve，监听127.0.0.1:11434——只绑回环地址，局域网内其他设备也访问不到，天然安全；
6. 启动界面：用--user-data-dir指向 U 盘数据目录打开 AnythingLLM；
7. 优雅关机：终端按回车后，依次 kill 两个进程并提示"可安全弹出 U 盘"。

仓库里还有一个"进阶版"启动器 optimiced.bat（ELITE EDITION），在标准流程之上增加了：启动前强杀残留进程、对 Ollama 做/api/tags健康轮询、以更高进程优先级启动引擎、并为 AnythingLLM 追加--disable-metrics、--disable-breakpad等关闭遥测的参数——属于同一架构的强化实现，可以当作"二次开发"的参考范本。

五、模型生态：6 个预设 + 自定义 🎛️

模型目录在 install-core.ps1（$ModelCatalog）与 linux/install-core.sh（MODEL_CATALOG）中同构维护，全部采用 Q4_K_M 量化：

每个模型的"人设"由 Modelfile 固化：FROM指向 GGUF 权重、PARAMETER固定 temperature 0.7 / top_p 0.9、SYSTEM写入系统提示词。想调上下文长度，改anythingllm_data/storage/.env里的OLLAMA_MODEL_TOKEN_LIMIT（默认 4096）即可——注意重跑安装脚本会把它重置回 4096。

U 盘容量速查：单个轻量模型 16 GB 起步；装 NemoMix 12B 建议 32 GB；全量 6 模型约 25 GB，建议 64 GB。

六、快速上手：3 步搭好你的私有便携AI 🚀

前提：一块 ≥16 GB 的 U 盘（务必格式化为 exFAT）+ 首次联网下载。

1. 拷贝：把仓库全部文件复制到 U 盘根目录；
2. 安装（一次性）：
   • Windows 双击 install.bat；Linux/Mac 运行 linux/install.sh（会自动先跑预检）；
   • 按菜单选模型 → AnythingLLM 安装界面出现时，Browse 选到 U 盘的anythingllm文件夹→ 等待完成；
3. 启动：
   • Windows 双击 start-windows.bat；
   • Mac 双击 start-mac.command（首次会自动下载 Mac 引擎）；
   • Linux 先chmod +x后运行bash start-linux.sh。

聊天窗口弹出即大功告成。在 AnythingLLM 的 Settings → LLM 中可自由切换 U 盘里的任意模型；用完在终端按任意键安全关机、弹出 U 盘即可。

架构要点回顾 📌

• 四分离 + 回环通信：引擎、模型、界面、数据各自独立目录，仅通过127.0.0.1:11434内网通信，这是"整机可迁移"的基石；
• 薄入口/厚核心：.bat与.sh只做调度，PowerShell 与 Bash 两套核心脚本共享同一套六步流水线，维护成本低；
• 幂等安装：.part临时文件 + 大小校验 + 自动重试，任何一步失败都能安全重跑；
• 环境变量即沙箱：OLLAMA_MODELS、STORAGE_DIR、XDG_*、APPDATA多重重定向，让 Electron 应用在不知不觉中"只写 U 盘"；
• 预检先行：Linux 侧用真实的磁盘速度基准测试代替经验值，把"U 盘太慢"这类隐患挡在安装之前。

不足约千行的脚本，Portable-AI-USB 展示了"用最小代码实现最大可迁移性"的架构思路——对于想给公司、团队或个人打造离线 AI 工具箱的读者，这份源码本身就是一份绝佳的便携软件设计教程。

【免费下载链接】Portable-AI-USBA 100% offline, fully portable, zero-trace AI (Ollama + Llama 3 + AnythingLLM) that runs natively from a USB drive on Windows and Mac.项目地址: https://gitcode.com/gh_mirrors/po/Portable-AI-USB