本地LLM部署指南：让AIri虚拟角色脱离网络限制自由运行

你是否曾因网络波动导致AIri对话中断？担心隐私数据通过云端API泄露？渴望在无网络环境下也能与虚拟角色互动？这些痛点正是本地LLM部署要解决的核心问题。本文将通过"问题-方案-验证"三段式框架，带你构建完全离线的AIri运行环境，让虚拟角色真正做到"时刻陪伴"。

环境层构建：从硬件配置到基础工具链

硬件配置三档对比表

配置类型	最低配置	推荐配置	极致配置
CPU	4核处理器	8核i7/Ryzen 7	12核i9/Ryzen 9
内存	8GB RAM	16GB DDR4	32GB DDR5
显卡	集成显卡	NVIDIA GTX 1660 (6GB)	NVIDIA RTX 4090 (24GB)
存储	30GB SSD	100GB NVMe	500GB NVMe
系统	Windows 10/Linux	Windows 11/Ubuntu 22.04	Ubuntu 22.04 Server

基础工具链安装与验证

为什么需要这些工具？Git用于获取项目源码，Node.js和pnpm管理JavaScript依赖，Rust工具链编译高性能组件，这三者构成AIri运行的基础生态。

安装Git

sudo apt install git -y  # Ubuntu系统
git --version  # 验证安装，应显示2.30+版本

操作难度：★☆☆☆☆

安装Node.js与pnpm

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y
npm install -g pnpm
node -v && pnpm -v  # 验证安装，Node.js应≥18.0.0

操作难度：★☆☆☆☆

安装Rust工具链

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source $HOME/.cargo/env
rustc --version  # 验证安装，应显示1.60+版本

操作难度：★★☆☆☆

克隆项目仓库

git clone https://gitcode.com/GitHub_Trending/ai/airi.git
cd airi
ls -la  # 验证克隆成功，应看到项目文件列表

操作难度：★☆☆☆☆

技术原理速览：本地LLM部署架构

本地LLM部署采用"模型服务-应用接口-前端展示"三层架构。模型服务层由Ollama提供LLM运行环境，MCP服务器作为AIri专用模型管理器；应用接口层通过Node.js服务桥接模型与前端；展示层则是AIri的Live2D/VRM渲染界面。这种架构确保所有数据处理都在本地完成，实现真正的离线运行。

服务层配置：构建本地模型与API服务

部署Ollama模型服务

为什么选择Ollama？它提供一站式LLM管理，支持模型下载、运行和API封装，大幅降低本地部署门槛。

安装Ollama

curl https://ollama.ai/install.sh | sh
ollama --version  # 验证安装，应显示0.1.20+版本

操作难度：★☆☆☆☆

启动服务并验证

ollama serve &  # 后台运行服务
curl http://localhost:11434/api/tags  # 验证服务状态，应返回JSON响应

操作难度：★☆☆☆☆

下载模型（更换示例参数）

ollama pull llama3:8b  # 下载Llama 3 8B模型（替代原Mistral）
ollama pull all-MiniLM-L6-v2  # 下载轻量级嵌入模型（替代原nomic-embed-text）
ollama list  # 验证模型，应显示已下载的2个模型

操作难度：★★☆☆☆ ⚠️此步骤需耐心等待（模型大小约4-8GB）

配置MCP服务器

为什么需要MCP？MCP（Model Control Protocol）是AIri项目专用的模型管理组件，提供模型调度、权限控制和性能优化，是连接Ollama与AIri应用的关键中间件。

编译MCP组件

cd crates/tauri-plugin-mcp
cargo build --release
ls target/release/libtauri_plugin_mcp.so  # 验证编译结果

操作难度：★★★☆☆

修改配置文件（⚙️配置项）

nano src/config.rs  # 修改默认配置
# 将默认端口8080改为8088（避免冲突）
# 设置模型缓存路径：/var/cache/airi-models

操作难度：★★☆☆☆

启动MCP服务

cargo run --release &
curl http://localhost:8088/health  # 验证服务，应返回"OK"

操作难度：★★☆☆☆

高级配置技巧：服务优化与自启动

模型缓存优化

# 创建缓存目录并设置软链接
mkdir -p /var/cache/airi-models
ln -s /var/cache/airi-models ~/.ollama/models
# 验证链接：ls -la ~/.ollama/models

此配置将模型文件迁移到更大容量的分区，避免系统盘空间不足。

服务自启动配置

# 创建systemd服务文件
sudo nano /etc/systemd/system/airi-mcp.service
# 添加以下内容：
[Unit]
Description=AIri MCP Server
After=network.target

[Service]
User=your_username
WorkingDirectory=/path/to/airi/crates/tauri-plugin-mcp
ExecStart=/path/to/airi/crates/tauri-plugin-mcp/target/release/tauri-plugin-mcp
Restart=always

[Install]
WantedBy=multi-user.target

# 启用并启动服务
sudo systemctl enable airi-mcp
sudo systemctl start airi-mcp

操作难度：★★★☆☆

应用层集成：AIri项目配置与依赖管理

环境变量配置（⚙️核心配置项）

为什么需要环境变量？环境变量集中管理敏感信息和服务地址，使AIri能动态适应不同部署环境（开发/生产/本地）。

创建环境配置文件

cd services/telegram-bot
cp .env.example .env.local  # 复制示例配置
nano .env.local  # 编辑配置

关键配置项（更换示例参数）

# LLM配置
LLM_API_BASE_URL='http://localhost:11434/v1/'  # Ollama API地址
LLM_MODEL='llama3:8b'  # 使用Llama 3模型
LLM_MAX_TOKENS=2048  # 增加最大 tokens 限制

# 嵌入模型配置
EMBEDDING_API_BASE_URL='http://localhost:11434/v1/'
EMBEDDING_MODEL='all-MiniLM-L6-v2'  # 轻量级嵌入模型

# 本地服务配置
MCP_SERVER_URL='http://localhost:8088'  # MCP服务地址
LOCAL_STORAGE_PATH='/var/airi/data'  # 本地数据存储路径

操作难度：★★☆☆☆

依赖安装与项目构建

为什么需要pnpm？pnpm采用内容寻址存储，比npm/yarn节省磁盘空间并提高安装速度，特别适合AIri这样的多包项目。

安装项目依赖

cd ../../..  # 返回项目根目录
pnpm install  # 安装所有依赖
pnpm list | grep '@airi/'  # 验证依赖安装，应显示airi相关包

操作难度：★★☆☆☆ ⚠️首次安装可能需要30分钟以上

构建核心模块

pnpm build:core  # 构建核心库
pnpm build:server  # 构建后端服务
ls packages/server-runtime/dist  # 验证构建结果

操作难度：★★★☆☆

前端应用配置

为什么需要单独配置前端？前端需要指向本地API服务，禁用远程资源加载，确保完全离线运行。

修改前端环境配置

cd apps/stage-web
cp .env.example .env.local
nano .env.local

关键前端配置

VITE_API_BASE_URL=http://localhost:8088/api  # 本地API地址
VITE_LOAD_REMOTE_RESOURCES=false  # 禁用远程资源
VITE_OFFLINE_MODE=true  # 启用离线模式
VITE_MODEL_PROVIDER=local  # 使用本地模型

操作难度：★☆☆☆☆

场景化验证流程：确保本地部署有效性

场景一：基础文本对话功能验证

✅ 目标：验证本地LLM模型能否处理文本对话

启动核心服务

# 启动后端API服务
cd packages/server-runtime
pnpm start &

# 启动前端应用
cd ../../apps/stage-web
pnpm dev &

操作难度：★☆☆☆☆

验证步骤

1. 访问 http://localhost:5173（前端默认地址）
2. 在聊天框输入"你好，介绍一下自己"
3. 观察响应：应在5-10秒内收到AIri的文本回复
4. 检查网络活动：通过浏览器开发者工具确认无外部API请求

🔍 检查点：回复内容应包含"AIri"和"本地部署"相关描述

场景二：语音交互功能验证

✅ 目标：验证本地语音识别(ASR)和语音合成(TTS)功能

配置音频服务

cd apps/realtime-audio
pnpm install
pnpm start &

操作难度：★★☆☆☆

验证步骤

1. 在前端界面点击麦克风图标
2. 说出"今天天气怎么样"
3. 观察系统：应显示文字转录并听到AIri的语音回复
4. 检查音频服务日志：确认使用本地模型处理

🔍 检查点：语音识别准确率应>90%，TTS语音自然度良好

场景三：完全离线运行验证

✅ 目标：验证断网状态下的功能完整性

验证步骤

1. 断开网络连接（拔网线或禁用Wi-Fi）
2. 重启所有服务：pnpm restart:all
3. 重复场景一和场景二的验证步骤
4. 检查应用稳定性：连续10次对话无崩溃或超时

🔍 检查点：所有功能应与联网状态下表现一致

故障排除决策树

模型无法加载

模型无法加载
├─ 检查Ollama服务状态 → systemctl status ollama
│  ├─ 服务未运行 → systemctl start ollama
│  └─ 服务运行异常 → 查看日志 journalctl -u ollama
├─ 检查模型是否存在 → ollama list
│  └─ 模型缺失 → 重新拉取 ollama pull [模型名]
└─ 检查资源使用 → htop
   └─ 内存不足 → 关闭其他应用或使用更小模型

API连接失败

API连接失败
├─ 检查MCP服务状态 → curl http://localhost:8088/health
│  └─ 服务未运行 → 重启MCP服务
├─ 检查防火墙设置 → sudo ufw status
│  └─ 端口被阻止 → sudo ufw allow 8088
└─ 检查环境变量配置
   └─ 地址错误 → 修正.env.local中的MCP_SERVER_URL

技术词汇表

• LLM（大语言模型）：基于海量文本训练的AI模型，能理解和生成人类语言
• Ollama：轻量级LLM管理工具，简化本地模型部署和API服务
• MCP（模型控制协议）：AIri项目专用的模型管理组件，协调多模型工作流
• ASR（自动语音识别）：将语音转换为文本的技术，实现语音交互输入
• TTS（文本转语音）：将文本转换为自然语音的技术，实现AI语音输出

扩展阅读路径

1. 模型优化方向：探索模型量化技术（4-bit/8-bit量化）和模型蒸馏，进一步降低硬件需求
2. 自定义技能开发：学习如何为AIri添加本地运行的自定义技能，参考crates/tauri-plugin-mcp/src/skills
3. 多模型协同：研究如何让不同专长的LLM模型协同工作，提升AIri的综合能力

通过本文的步骤，你已成功构建了完全离线的AIri运行环境。这种部署方式不仅解决了网络依赖和隐私顾虑问题，还为定制化AI交互提供了基础。随着本地LLM技术的不断发展，你的AIri将变得越来越智能，真正成为不受限制的虚拟伙伴。