AIRI 安装与配置指南

AIRI 是由开源的虚拟 AI Companion 项目，支持 Web、桌面端及移动端运行形态，具备多模型接入、语音交互、角色驱动等能力。本文整理实际可落地的安装与配置流程，适用于本地开发与测试环境部署。

一、环境准备

在开始之前，请确认以下环境已安装：

1. 基础运行环境

Node.js（建议使用 LTS 版本）
pnpm（包管理工具）
Git

验证方式：

node -v
pnpm -v
git --version

如未安装 pnpm：

npm install -g pnpm

二、获取项目源码

使用 Git 克隆仓库：

git clone https://github.com/moeru-ai/airi.git
cd airi

建议保持仓库为最新版本：

git pull

三、安装依赖

在项目根目录执行：

pnpm install

该命令会安装 monorepo 下所有子包依赖。

如出现依赖异常，可尝试：

rm -rf node_modules
pnpm install

四、启动开发环境

AIRI 提供多种运行模式，根据需求选择。

1. Web 开发模式

pnpm dev

启动后访问终端提示的本地地址（通常为 http://localhost:5173 或类似端口）。

2. 桌面模式（Tamagotchi）

pnpm dev:tamagotchi

用于调试桌面形态的虚拟角色。

3. 移动端模式（Capacitor）

pnpm dev:capacitor

如需打开 iOS 工程：

pnpm open:ios

需要本机已安装 Xcode。

五、模型与 API 配置

AIRI 支持接入多种 LLM 提供商或本地模型。通常通过环境变量进行配置。

在项目根目录创建 .env 文件：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini

如使用兼容 OpenAI 协议的本地服务（如 Ollama / vLLM）：

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=http://localhost:11434/v1
MODEL_NAME=your-local-model

修改后重启开发服务器。

六、目录结构说明

核心目录通常包括：

apps/              # 各端应用入口
packages/          # 公共模块
services/          # 后端服务或接口封装

前端主要基于 Vue + TypeScript 构建，依赖 pnpm workspace 管理。

七、常见问题

1. 端口冲突

如果默认端口被占用，可在启动时指定：

pnpm dev -- --port 3001

或修改项目配置文件。

2. Node 版本不兼容

建议切换到 LTS 版本，例如使用 nvm：

nvm install --lts
nvm use --lts

3. 依赖安装卡住

可以尝试更换镜像源或清理缓存：

pnpm store prune
pnpm install

八、生产部署建议

当前仓库主要面向开发与实验阶段，如需部署到服务器：

使用 pnpm build 生成生产构建
配合 Nginx 进行反向代理
使用 PM2 或 Docker 管理进程
配置 HTTPS

九、小结

AIRI 的基础部署流程可以概括为：

安装 Node 与 pnpm
克隆仓库
安装依赖
配置 API
启动开发环境

完成上述步骤后，即可开始调试或进行二次开发。

如需进一步扩展（如本地模型接入、角色系统定制、语音模块接入），建议直接阅读源码中的 services 与 packages 目录实现逻辑。

Moeru-AI/AIRI 安装与配置完整指南