AIRI 是一个开源的二次元 AI 桌宠项目。在社区流传的称呼里它常被人叫做“AI女友”或者“AI老婆”但从工程角度更准确的理解是一个常驻桌面的、能说话、能陪你聊天的 AI 角色。它的运行方式并不复杂桌面显示卡通形象后台调用大模型生成对话再通过语音识别和语音合成完成交互。相比打开网页和 AI 聊天AIRI 更强调陪伴感、角色人设和游戏场景。这篇文章会按一条完整的实践路线来写先讲清楚 AIRI 由哪些模块组成再准备好模型 API、语音组件和系统环境接着完成下载、配置、首次对话验证然后配置游戏联动最后给出常见问题排查和长期使用建议。整个流程不需要编程基础但如果你会看日志和改配置文件遇到问题时会轻松很多。要提前说明的是AIRI 是一个社区项目不同版本的配置字段、目录结构、功能开关可能有差异。因此文中给出的目录、配置和代码属于“典型参考结构”你在落地前一定要以自己下载版本的 README 和示例配置为准。1. 先搞清楚 AIRI 是什么桌宠不是网页聊天室很多人第一次看到 AIRI会把它理解成一个会动的聊天窗口。这个理解不完整。AIRI 的价值不在于“能聊天”而在于它把角色形象、模型对话、语音交互和桌面窗口管理组合成了一个完整的陪伴型应用。你先理解这一层后面配置时才不会改错地方。1.1 从“AI女友”到“桌面AI助手”“AI女友”是用户称呼不是产品类型。技术上AIRI 本质上是一个带有固定角色人设的 AI 对话系统只是它的交互入口不是一个网页而是一个桌面悬浮角色。可以对比看这三类产品的差异产品形态交互方式典型场景核心组件网页聊天机器人打开网页输入文字问答、写作、翻译大模型 API、前端聊天框语音助手手机或音箱喊一句定闹钟、查天气、控制设备语音识别、意图理解、语音合成AI 桌宠桌面悬浮角色可文字可语音陪伴、游戏中互动、闲聊角色形象、大模型 API、语音链、窗口管理AIRI 属于第三类。它不会替你做复杂办公任务也不追求回答问题有多准确它更看重“角色像不像一个人”“互动是否自然”“能不能在游戏时陪着你”。理解了这一点你就不会拿“和 ChatGPT 比知识量”的标准去要求它也不会在配置时忽略掉角色人设和交互体验。1.2 用技术视角拆解 AIRI 的四个核心模块无论 AIRI 的代码用哪种语言编写它的整体架构通常可以拆成四层模块职责常见技术方案最容易出问题的环节形象层显示二次元角色、播放表情和动作Live2D、MMD 动画模型模型文件缺失、路径不对、显卡兼容对话层接收用户输入生成角色回复大模型 API、本地模型API Key 错误、网络不通、模型名填错语音层识别用户语音、合成角色声音Whisper、Edge-TTS、系统语音麦克风权限、音频设备被占用交互层管理置顶、拖动、快捷键、窗口穿透桌面窗口框架、全局热键配置字段错误、和游戏快捷键冲突这四个模块不是必须同时工作的。AIRI 的常见使用方式是“先文字后语音”也就是先用文字把对话链路跑通再开启语音识别和语音合成。如果一开始就全开出了问题你很难判断是模型的问题还是音频设备的问题。1.3 为什么说它“免费”但又不是“完全零成本”AIRI 本身是开源软件代码和基础功能通常是免费提供的这是它被称为“白嫖”的最主要原因。但 AIRI 本身不产生智能它的对话能力来自背后的大模型。大模型服务通常有三种情况使用云厂商提供的 API大部分平台会提供一定的新用户免费额度适合先用起来额度用完后再按量付费。使用本地模型在电脑上跑开源模型如 Ollama 部署的模型不需要按次付费但需要足够的内存和显卡资源。使用免费或低价的公益接口这类接口可用性和稳定性差别很大不建议作为长期依赖。所以更准确的说法是AIRI 软件免费模型调用可能免费额度也可能需要成本。你在部署前想清楚自己走哪条路线后续配置就会顺利很多。2. 部署前把模型 API、语音组件和系统环境一次备齐AIRI 的安装本身不难难点在于它依赖多个外部组件。如果这些前置组件没有准备好就算程序启动成功你也会看到角色站在桌面上但怎么说话都不回复。这一节的任务就是把所有前置项一次检查完。2.1 系统要求先判断你的电脑能不能跑不同类型的桌宠项目对硬件要求差别很大。只跑对话和语音对性能要求不高但如果要在本地跑模型要求就会明显提高。下面是一份参考标准具体以你下载版本的说明为准项目最低要求推荐要求操作系统Windows 10 或 macOS 12Windows 11 或 macOS 最新稳定版内存8 GB16 GB 及以上显卡集成显卡可显示角色即可6 GB 以上显存用于本地模型推理麦克风任意可用麦克风带降噪的耳机麦克风网络能访问模型 API 域名稳定的宽带网络检查系统时有一个容易被忽略的点解压路径。AIRI 这类项目对中文字符、空格和特殊符号的路径兼容性较差建议解压到类似D:\AIRI或者/Users/你的名字/airi这种简单路径下否则可能遇到模型加载失败、配置文件读取不到的问题。2.2 准备一个可以调用的大模型 APIAIRI 的对话层需要一个模型接口。新手最容易犯的错误是以为“下载了 AIRI 就能聊天”实际上你必须先把某个大模型服务的访问凭据准备好。常见的模型路线如下表方案是否需要付费适合谁注意事项DeepSeek API充值但有新用户免费体验额度中文用户、新手接口兼容 OpenAI 格式文档清晰OpenAI 兼容接口部分需要充值想用国外模型的用户国内网络访问可能受限先确认连通性通义千问、Kimi 等国内平台多提供免费额度国内用户看是否提供 OpenAI 兼容地址Ollama 本地模型完全免费隐私敏感、有显卡的用户需要下载模型占用大量磁盘和内存判断一个接口是否兼容 OpenAI 格式的方法很简单看它的文档里有没有提供类似/v1/chat/completions的地址。AIRI 的配置里通常会有base_url和model两个字段可以填这些内容。对于零基础用户我建议先用 DeepSeek 跑通因为它的中文对话能力好配置结构也接近 OpenAI 官方格式。开通后你会拿到一个形如sk-xxxx的 API Key这个 Key 要妥善保存后面配置时会用到。2.3 语音能力TTS 和 ASR 分开准备语音交互包含两条链路ASR把你说的话转成文字常见有 Whisper、系统语音识别、云端语音识别。TTS把模型生成的文字变成语音常见有 Edge-TTS、系统语音、云端 TTS。AIRI 具体支持哪些语音引擎取决于版本。你需要去项目 README 里找TTS和ASR的配置说明。如果找不到可以先跳过语音配置只开文字对话。很多 AIRI 的交互都是文字输入触发的语音只是可选项。我先给你一个建议把语音当作第二阶段功能。第一次部署时先把文字对话跑通再逐步加 TTS、ASR。这样你在排查问题时能快速缩小范围。2.4 环境检查清单部署前花 5 分钟过一遍在开始下载之前可以先做一次系统级检查避免中途反复返工网络是否能正常访问你要用的模型 API 域名。API Key 是否已创建并确认有可用余额或免费额度。已安装解压工具且解压路径不包含中文和空格。麦克风在系统设置里已被正确识别。桌面有足够空间放置悬浮角色无壁纸插件遮挡。杀毒软件或安全软件没有拦截下载目录。准备好一个文本编辑器推荐 Visual Studio Code 或 Notepad。这份清单并不复杂。但实际部署中很多“启动失败”都源于某一条没有满足比如 API Key 填错、网络不通、路径带中文。3. 从下载到首次对话AIRI 的保姆级部署流程前置条件准备好之后就可以进入正式部署。这里的核心思路是先把程序跑起来再接通模型最后验证对话。不要急着改各种花哨配置。3.1 下载、解压和确认目录结构AIRI 的下载位置通常是开源项目的 GitHub Releases 页面也会提供 Windows、macOS 等平台的安装包或压缩包。下载时注意文件名里的平台标识比如mac和win不要下错。如果项目还提供官网下载以官网说明为准。下载完成后不要直接在压缩包里双击运行先解压到一个干净目录。一个典型的桌宠项目目录可能长这样AIRI/ ├── assets/ # 角色模型、图片、音效等资源 ├── config/ # 配置文件目录 │ ├── config.yaml # 主配置文件 │ └── characters/ # 角色卡目录 ├── logs/ # 运行日志 ├── models/ # 本地模型文件 ├── start.bat # Windows 启动脚本 ├── start.sh # macOS / Linux 启动脚本 └── README.md # 项目说明文档注意不同版本的目录名不一定相同。如果某个目录不存在以你下载的版本为准。但config和logs这两个目录通常都会存在因为它们是程序运行的基础。3.2 修改配置文件接通大模型接下来要做的是把 API Key 填进配置文件。配置文件的常见位置是config/config.yaml。一个典型的 AIRI 配置片段如下# 参考配置实际字段以你下载版本的示例为准 app: language: zh-CN always_on_top: true # 是否保持置顶 transparent: false # 是否开启鼠标穿透 llm: provider: openai_compatible base_url: https://api.deepseek.com/v1 api_key: sk-你的APIKey model: deepseek-chat temperature: 0.8 # 数值越大回复越随机 max_tokens: 2048 # 单次生成的最大 token 数 tts: engine: edge-tts voice: zh-CN-XiaoxiaoNeural asr: engine: whisper language: zh character: name: Airi personality: 活泼、话多、喜欢游戏 greeting: 你好今天想玩什么游戏这段配置里最需要理解的是llm部分。base_url是模型接口的服务地址api_key是你的身份凭证model是具体使用的模型名称。不同平台的model名称不同比如 DeepSeek 可能是deepseek-chat其他平台可能是其他命名必须看平台文档填写。填好配置后不要急着打开 AIRI。先用命令行直接测试接口是否连通这样能把“模型接口问题”和“AIRI 程序问题”分开。以 OpenAI 兼容接口为例curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的APIKey \ -d { model: deepseek-chat, messages: [{role: user, content: 你好请回复我一句话}] }如果返回正常的 JSON 响应说明接口通、Key 有效、模型名正确。如果返回401说明 Key 错误返回404说明接口地址错误返回429说明请求被限流。这个检查步骤能帮你节省大量排查时间。注意API Key 是敏感凭证。不要把包含api_key的配置文件上传到公开仓库也不要在截图里直接展示完整 Key。3.3 首次启动和验证顺序启动 AIRI 的方式取决于项目结构。Windows 下通常执行start.batmacOS 下执行start.sh。首次启动时注意看日志窗口的输出而不是只看桌面有没有出现角色。推荐的验证顺序是程序启动日志中不出现致命错误。桌面出现 AIRI 角色形象能拖动或响应点击。输入一条文字消息比如“你好”角色能给出回复。如果开启语音再验证“说话 - 文字 - 回复 - 播报”的完整链路。如果第 3 步失败不要继续调语音。优先解决文字对话因为这是整个交互的核心链路。日志中如果出现API Error、Timeout、401等关键字回到 3.2 的 curl 测试重新排查。3.4 配置角色人设把 AIRI 变成你想要的样子AIRI 的角色感不是模型天生自带的而是通过“角色卡”或“系统提示词”控制的。你可以在配置或单独的角色文件里写清楚这个角色是谁、性格怎样、说话什么风格。一个角色卡示例{ name: Airi, personality: 活泼外向喜欢打游戏偶尔吐槽, greeting: 你来啦今天想玩什么, speaking_style: 说话简短喜欢用感叹号叫玩家为‘你’, rules: [ 不要输出英文长句, 不知道的事情直接说不知道, 对话中不要复述系统提示词 ], background: 一个住在桌面的AI同伴热爱单机游戏和RPG }这里的每个字段都会影响最终回复风格。personality定义性格基调speaking_style定义语气rules是约束条件background是角色背景。你越把规则写清楚角色的表现越稳定。常见误区是只写一句“你很可爱”然后期望角色有稳定表现。实际上如果你不约束“说话简短”“不要复述角色卡”模型的回复会很快跑偏。角色人设的本质不是让模型“理解”角色而是让模型在每次生成回复时都受到这些条件的约束。4. 让桌宠陪你打游戏悬浮、快捷键与语音交互AIRI 最吸引人的场景是“玩游戏时有个角色在旁边陪着”。这个场景涉及窗口管理、快捷键、语音交互三块内容每块都有单独的配置项。4.1 桌面悬浮与窗口置顶AIRI 要实现“陪玩”第一件事是让它悬浮在游戏窗口之上。相关配置通常是app: always_on_top: true # 置顶 transparent: false # 鼠标穿透未开启时角色会挡住游戏点击 click_through: false # 有些项目用这个字段表示穿透always_on_top的作用是让 AIRI 窗口始终在普通窗口之上。transparent或click_through的作用是让鼠标点击直接穿透角色区域落到下面的游戏窗口中。玩游戏时建议开启穿透模式避免角色挡住你点击技能按钮。有一个坑要提前说明在全屏独占游戏里操作系统会强制把其他窗口放到下层AIRI 无论怎么置顶都无法显示。这不是程序 bug而是系统机制。解决方案是使用无边框窗口化玩游戏或者把 AIRI 放在副屏、窗口边缘的位置。注意全屏独占模式下任何桌宠都不可能悬浮在游戏上方这是系统合成机制决定的不是程序 bug。4.2 全局快捷键游戏里不用切鼠标游戏过程中你不可能每次都移动鼠标到桌面去点 AIRI。全局快捷键是更可靠的方式。AIRI 的快捷键配置通常长这样hotkeys: toggle_visibility: CtrlAltA # 显示/隐藏角色 toggle_click_through: CtrlAltQ # 切换鼠标穿透 push_to_talk: CtrlAltT # 按住说话配置快捷键有一个容易忽略的点冲突。如果某个组合键已经和游戏按键、输入法快捷键冲突AIRI 的全局按键可能失效或触发异常。解决办法是避开常用的游戏按键使用比较偏的组合键例如带 CtrlAlt 的长组合或者提供自定义能力。4.3 游戏场景的语音交互推荐按住说话语音交互在游戏场景中要注意“自动听讲”和“按住说话”的取舍。自动听讲角色持续监听麦克风优点是方便缺点是在游戏环境里容易把游戏音效、队友语音识别成对话内容产生误回复。按住说话只有按下快捷键时才录音控制更精确适合打游戏时使用。AIRI 如果支持按键说话游戏场景下优先用这种方式。你按一下“说话键”提问角色识别后生成回复并播报。角色说话时注意控制音量避免盖住游戏音效。4.4 一个完整的游戏联动配置示例综合以上配置一个适合游戏场景的 AIRI 配置片段可以是app: always_on_top: true transparent: true hotkeys: toggle_visibility: CtrlAltA push_to_talk: CtrlAltSpace tts: engine: edge-tts voice: zh-CN-XiaoyiNeural volume: 0.8 asr: engine: whisper language: zh push_to_talk: true这个配置组合的意思是角色保持置顶鼠标穿透你用CtrlAltA随时显示或隐藏角色用CtrlAltSpace按住说话提问角色回复时声音不覆盖游戏音效。这套组合能覆盖大部分“游戏陪玩”场景。5. 常见问题排查从日志和接口一层层定位部署 AIRI 的过程中大概率会遇到下面这些典型问题。排查思路比单个解决方案更重要因为不同版本的报错字段可能不同但底层链路是一致的。5.1 常见问题速查表问题现象常见原因排查方向处理建议程序启动失败解压路径包含中文或空格检查目录路径移动到纯英文路径后重启角色出现但对话无回复API Key 无效或网络不通查看日志中的 HTTP 状态码用 curl 单独测试接口回复内容很慢模型服务限流或本地模型过大检查日志里的耗时换较快模型或调小 max_tokens角色没有声音TTS 引擎未配置或音频设备被占用检查音频输出设备切换系统默认输出设备麦克风不识别ASR 未开启或权限不足检查系统麦克风权限在系统设置里允许桌面应用使用麦克风配置修改后不生效改错配置文件或未重启查看启动日志加载的配置路径修改后重启程序并确认加载路径角色表情不动模型文件缺失或显卡兼容问题查看资源加载日志替换或重装模型资源文件回复内容乱编大模型天然有幻觉降低 temperature在角色卡中加“不知道就说不清楚”的规则你会发现大部分问题都集中在“配置、网络、权限、资源文件”这几类而不是程序本身的 bug。5.2 对话无回复的排查链路遇到对话无回复时不要反复点按钮试按下面的顺序排查看日志。日志里有错误码或异常关键字先处理日志中明确的错误。检测网络。确认电脑能访问你配置的base_url域名。验证 API Key。用 3.2 的 curl 命令独立测试接口。检查模型名。确认model字段值和平台文档给出的名称完全一致。检查配置加载。看启动日志里加载的配置文件是不是你刚改的那个文件。检查账号额度。如果curl返回402或与余额相关的错误说明额度不足。注意排查时一次只改一个变量改完必须重启 AIRI否则无法判断是哪一步生效了。5.3 语音问题TTS 无声和 ASR 不识别语音链路比文字对话更脆弱因为它同时依赖模型接口、音频驱动和系统权限。TTS 无声时先确认系统能正常播放其他声音。如果其他应用有声再检查 AIRI 的tts.engine是否配置正确。使用 Edge-TTS 这类网络合成服务时还需要确认网络可用使用系统 TTS 时检查系统语音包是否安装完整。ASR 不识别时先看麦克风权限是否开启。Windows 下需要在“设置 - 隐私和安全性 - 麦克风”里允许应用访问。如果使用 Whisper 本地模型第一次运行时要下载模型文件可能长时间没有反应表现为 CPU 或内存占用很高这属于正常现象不是卡死。5.4 配置修改不生效这是新手最容易踩的坑。配置文件明明改了重启后还是旧行为。常见原因有三个改错了文件。项目里可能有多个配置文件改的那个并不被程序读取。没有保存。编辑器里改了但没触发保存动作。程序存在缓存。启动时把配置加载到了内存重启后重新读取才会生效。解决方式是在日志中找到“配置文件加载路径”之类的输出确认你改的确实是被加载的那个文件。修改后完整退出程序再启动而不是只关闭角色窗口。5.5 回复质量差和 AI 幻觉AIRI 的对话能力来自大模型大模型本质上是在做文本生成不是数据库查询。所以它可能一本正经地编造游戏攻略、成绩数据、版本信息这就是所谓的“AI 幻觉”。要缓解这个问题可以从三方面入手降低temperature让输出更保守。游戏攻略场景建议 0.4 到 0.7。在角色卡rules里加“不知道就说不清楚”“不要编造游戏数据”等约束。如果角色需要知道特定游戏资料最好把资料整理成文本文件放进项目让模型在回复时参考而不是靠记忆。6. 长期使用建议从“能跑”到“好用”AIRI 跑通并完成了首次对话只代表你完成了 30%。剩下 70% 的事情是优化成本、保障隐私、扩展功能和持续维护。这一节适合真正想长期使用甚至想把它当作 AI 应用练习项目的读者。6.1 控制成本这几条最能省钱成本来源控制方案适用场景云端 API 按 token 计费开启免费额度额度用完后改用本地模型日常聊天和测试每次对话历史太长限制上下文长度对话轮数多时自动裁剪长时间陪伴聊天单次回复过长调低max_tokens比如 512 到 1024普通闲聊重复调用相同问题在本地做简单缓存相同问题直接返回缓存常见问题查询本地模型占用资源高换小参数量模型或量化版本显卡配置一般的电脑很多用户刚开始觉得 AIRI 是“白嫖”用一段时间后发现自己每天产生大量 token 费用。原因通常是上下文越长每次调用发送的 token 越多。建议长期使用时给对话历史设置上限例如只保留最近 20 轮对话。6.2 隐私与安全不要给它完整的系统权限AIRI 作为桌面应用能读取麦克风、访问网络、读写本地文件所以需要格外注意权限边界API Key 不要硬编码在代码里也不要提交到公开仓库。日志文件可能包含对话内容定期清理logs目录。不要截屏分享包含 API Key、本机用户名、项目路径的完整界面。如果 AIRI 支持工具调用或命令执行只允许白名单范围内的操作不要给它完整 shell 权限。注意不要为了让桌宠执行命令而把系统 shell 权限完全交给它。代理工具必须使用白名单机制。6.3 扩展方向从桌宠变成一个小型 AgentAIRI 的上限远不止聊天。你可以按下面的路线逐步扩展第一替换形象。AIRI 使用的角色模型可能是 Live2D、MMD.pmx或其他格式。替换模型文件前先备份原始文件并确认新模型和引擎兼容。第二接入更多工具。如果你希望 AIRI 能查游戏战绩、设置提醒、搜索资料就涉及 function calling也就是把 AIRI 从一个“聊天机器人”升级成一个“Agent”。这类功能通常需要在服务端配置工具描述和调用函数。第三学习 AI 应用开发。AIRI 本质上是一个完整的 AI 应用它集成了 API 调用、Prompt 工程、语音链路、桌面交互。如果你想深入可以沿着“大模型 API 调用 - Prompt 工程 - 语音识别与合成 - Agent 工具调用”这条路线学习。后端封装时也可以参考 Spring AI、LangChain4j 这类框架它们能帮你管理模型调用、对话历史和工具注册。第四和 AI 编程工具配合。AIRI 可以作为陪伴型桌宠和 Cursor、Codex 这类 AI 编程工具同时使用。前者负责语音播报和互动后者负责代码生成适合写代码时保持轻量反馈。6.4 一个可以照着做的新手练习清单如果你不知道该从哪个方向继续可以从下面这个清单开始用默认配置跑通文字对话确定 AIRI 的核心链路正常。修改角色卡把 AIRI 的性格改成“直言不讳的游戏队友”观察回复风格变化。切换一次语音引擎换一个音色理解 TTS 配置的作用。把模型源从云端 API 切换到 Ollama 本地模型体验不同硬件要求下的差异。给 AIRI 增加一个工具调用比如让它可以查询一个本地 txt 文件里的游戏攻略。整理一份自己的排错记录 AIRI二次元AI桌宠保姆级部署教程：从模型API配置到游戏陪玩
AIRI 是一个开源的二次元 AI 桌宠项目。在社区流传的称呼里它常被人叫做“AI女友”或者“AI老婆”但从工程角度更准确的理解是一个常驻桌面的、能说话、能陪你聊天的 AI 角色。它的运行方式并不复杂桌面显示卡通形象后台调用大模型生成对话再通过语音识别和语音合成完成交互。相比打开网页和 AI 聊天AIRI 更强调陪伴感、角色人设和游戏场景。这篇文章会按一条完整的实践路线来写先讲清楚 AIRI 由哪些模块组成再准备好模型 API、语音组件和系统环境接着完成下载、配置、首次对话验证然后配置游戏联动最后给出常见问题排查和长期使用建议。整个流程不需要编程基础但如果你会看日志和改配置文件遇到问题时会轻松很多。要提前说明的是AIRI 是一个社区项目不同版本的配置字段、目录结构、功能开关可能有差异。因此文中给出的目录、配置和代码属于“典型参考结构”你在落地前一定要以自己下载版本的 README 和示例配置为准。1. 先搞清楚 AIRI 是什么桌宠不是网页聊天室很多人第一次看到 AIRI会把它理解成一个会动的聊天窗口。这个理解不完整。AIRI 的价值不在于“能聊天”而在于它把角色形象、模型对话、语音交互和桌面窗口管理组合成了一个完整的陪伴型应用。你先理解这一层后面配置时才不会改错地方。1.1 从“AI女友”到“桌面AI助手”“AI女友”是用户称呼不是产品类型。技术上AIRI 本质上是一个带有固定角色人设的 AI 对话系统只是它的交互入口不是一个网页而是一个桌面悬浮角色。可以对比看这三类产品的差异产品形态交互方式典型场景核心组件网页聊天机器人打开网页输入文字问答、写作、翻译大模型 API、前端聊天框语音助手手机或音箱喊一句定闹钟、查天气、控制设备语音识别、意图理解、语音合成AI 桌宠桌面悬浮角色可文字可语音陪伴、游戏中互动、闲聊角色形象、大模型 API、语音链、窗口管理AIRI 属于第三类。它不会替你做复杂办公任务也不追求回答问题有多准确它更看重“角色像不像一个人”“互动是否自然”“能不能在游戏时陪着你”。理解了这一点你就不会拿“和 ChatGPT 比知识量”的标准去要求它也不会在配置时忽略掉角色人设和交互体验。1.2 用技术视角拆解 AIRI 的四个核心模块无论 AIRI 的代码用哪种语言编写它的整体架构通常可以拆成四层模块职责常见技术方案最容易出问题的环节形象层显示二次元角色、播放表情和动作Live2D、MMD 动画模型模型文件缺失、路径不对、显卡兼容对话层接收用户输入生成角色回复大模型 API、本地模型API Key 错误、网络不通、模型名填错语音层识别用户语音、合成角色声音Whisper、Edge-TTS、系统语音麦克风权限、音频设备被占用交互层管理置顶、拖动、快捷键、窗口穿透桌面窗口框架、全局热键配置字段错误、和游戏快捷键冲突这四个模块不是必须同时工作的。AIRI 的常见使用方式是“先文字后语音”也就是先用文字把对话链路跑通再开启语音识别和语音合成。如果一开始就全开出了问题你很难判断是模型的问题还是音频设备的问题。1.3 为什么说它“免费”但又不是“完全零成本”AIRI 本身是开源软件代码和基础功能通常是免费提供的这是它被称为“白嫖”的最主要原因。但 AIRI 本身不产生智能它的对话能力来自背后的大模型。大模型服务通常有三种情况使用云厂商提供的 API大部分平台会提供一定的新用户免费额度适合先用起来额度用完后再按量付费。使用本地模型在电脑上跑开源模型如 Ollama 部署的模型不需要按次付费但需要足够的内存和显卡资源。使用免费或低价的公益接口这类接口可用性和稳定性差别很大不建议作为长期依赖。所以更准确的说法是AIRI 软件免费模型调用可能免费额度也可能需要成本。你在部署前想清楚自己走哪条路线后续配置就会顺利很多。2. 部署前把模型 API、语音组件和系统环境一次备齐AIRI 的安装本身不难难点在于它依赖多个外部组件。如果这些前置组件没有准备好就算程序启动成功你也会看到角色站在桌面上但怎么说话都不回复。这一节的任务就是把所有前置项一次检查完。2.1 系统要求先判断你的电脑能不能跑不同类型的桌宠项目对硬件要求差别很大。只跑对话和语音对性能要求不高但如果要在本地跑模型要求就会明显提高。下面是一份参考标准具体以你下载版本的说明为准项目最低要求推荐要求操作系统Windows 10 或 macOS 12Windows 11 或 macOS 最新稳定版内存8 GB16 GB 及以上显卡集成显卡可显示角色即可6 GB 以上显存用于本地模型推理麦克风任意可用麦克风带降噪的耳机麦克风网络能访问模型 API 域名稳定的宽带网络检查系统时有一个容易被忽略的点解压路径。AIRI 这类项目对中文字符、空格和特殊符号的路径兼容性较差建议解压到类似D:\AIRI或者/Users/你的名字/airi这种简单路径下否则可能遇到模型加载失败、配置文件读取不到的问题。2.2 准备一个可以调用的大模型 APIAIRI 的对话层需要一个模型接口。新手最容易犯的错误是以为“下载了 AIRI 就能聊天”实际上你必须先把某个大模型服务的访问凭据准备好。常见的模型路线如下表方案是否需要付费适合谁注意事项DeepSeek API充值但有新用户免费体验额度中文用户、新手接口兼容 OpenAI 格式文档清晰OpenAI 兼容接口部分需要充值想用国外模型的用户国内网络访问可能受限先确认连通性通义千问、Kimi 等国内平台多提供免费额度国内用户看是否提供 OpenAI 兼容地址Ollama 本地模型完全免费隐私敏感、有显卡的用户需要下载模型占用大量磁盘和内存判断一个接口是否兼容 OpenAI 格式的方法很简单看它的文档里有没有提供类似/v1/chat/completions的地址。AIRI 的配置里通常会有base_url和model两个字段可以填这些内容。对于零基础用户我建议先用 DeepSeek 跑通因为它的中文对话能力好配置结构也接近 OpenAI 官方格式。开通后你会拿到一个形如sk-xxxx的 API Key这个 Key 要妥善保存后面配置时会用到。2.3 语音能力TTS 和 ASR 分开准备语音交互包含两条链路ASR把你说的话转成文字常见有 Whisper、系统语音识别、云端语音识别。TTS把模型生成的文字变成语音常见有 Edge-TTS、系统语音、云端 TTS。AIRI 具体支持哪些语音引擎取决于版本。你需要去项目 README 里找TTS和ASR的配置说明。如果找不到可以先跳过语音配置只开文字对话。很多 AIRI 的交互都是文字输入触发的语音只是可选项。我先给你一个建议把语音当作第二阶段功能。第一次部署时先把文字对话跑通再逐步加 TTS、ASR。这样你在排查问题时能快速缩小范围。2.4 环境检查清单部署前花 5 分钟过一遍在开始下载之前可以先做一次系统级检查避免中途反复返工网络是否能正常访问你要用的模型 API 域名。API Key 是否已创建并确认有可用余额或免费额度。已安装解压工具且解压路径不包含中文和空格。麦克风在系统设置里已被正确识别。桌面有足够空间放置悬浮角色无壁纸插件遮挡。杀毒软件或安全软件没有拦截下载目录。准备好一个文本编辑器推荐 Visual Studio Code 或 Notepad。这份清单并不复杂。但实际部署中很多“启动失败”都源于某一条没有满足比如 API Key 填错、网络不通、路径带中文。3. 从下载到首次对话AIRI 的保姆级部署流程前置条件准备好之后就可以进入正式部署。这里的核心思路是先把程序跑起来再接通模型最后验证对话。不要急着改各种花哨配置。3.1 下载、解压和确认目录结构AIRI 的下载位置通常是开源项目的 GitHub Releases 页面也会提供 Windows、macOS 等平台的安装包或压缩包。下载时注意文件名里的平台标识比如mac和win不要下错。如果项目还提供官网下载以官网说明为准。下载完成后不要直接在压缩包里双击运行先解压到一个干净目录。一个典型的桌宠项目目录可能长这样AIRI/ ├── assets/ # 角色模型、图片、音效等资源 ├── config/ # 配置文件目录 │ ├── config.yaml # 主配置文件 │ └── characters/ # 角色卡目录 ├── logs/ # 运行日志 ├── models/ # 本地模型文件 ├── start.bat # Windows 启动脚本 ├── start.sh # macOS / Linux 启动脚本 └── README.md # 项目说明文档注意不同版本的目录名不一定相同。如果某个目录不存在以你下载的版本为准。但config和logs这两个目录通常都会存在因为它们是程序运行的基础。3.2 修改配置文件接通大模型接下来要做的是把 API Key 填进配置文件。配置文件的常见位置是config/config.yaml。一个典型的 AIRI 配置片段如下# 参考配置实际字段以你下载版本的示例为准 app: language: zh-CN always_on_top: true # 是否保持置顶 transparent: false # 是否开启鼠标穿透 llm: provider: openai_compatible base_url: https://api.deepseek.com/v1 api_key: sk-你的APIKey model: deepseek-chat temperature: 0.8 # 数值越大回复越随机 max_tokens: 2048 # 单次生成的最大 token 数 tts: engine: edge-tts voice: zh-CN-XiaoxiaoNeural asr: engine: whisper language: zh character: name: Airi personality: 活泼、话多、喜欢游戏 greeting: 你好今天想玩什么游戏这段配置里最需要理解的是llm部分。base_url是模型接口的服务地址api_key是你的身份凭证model是具体使用的模型名称。不同平台的model名称不同比如 DeepSeek 可能是deepseek-chat其他平台可能是其他命名必须看平台文档填写。填好配置后不要急着打开 AIRI。先用命令行直接测试接口是否连通这样能把“模型接口问题”和“AIRI 程序问题”分开。以 OpenAI 兼容接口为例curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的APIKey \ -d { model: deepseek-chat, messages: [{role: user, content: 你好请回复我一句话}] }如果返回正常的 JSON 响应说明接口通、Key 有效、模型名正确。如果返回401说明 Key 错误返回404说明接口地址错误返回429说明请求被限流。这个检查步骤能帮你节省大量排查时间。注意API Key 是敏感凭证。不要把包含api_key的配置文件上传到公开仓库也不要在截图里直接展示完整 Key。3.3 首次启动和验证顺序启动 AIRI 的方式取决于项目结构。Windows 下通常执行start.batmacOS 下执行start.sh。首次启动时注意看日志窗口的输出而不是只看桌面有没有出现角色。推荐的验证顺序是程序启动日志中不出现致命错误。桌面出现 AIRI 角色形象能拖动或响应点击。输入一条文字消息比如“你好”角色能给出回复。如果开启语音再验证“说话 - 文字 - 回复 - 播报”的完整链路。如果第 3 步失败不要继续调语音。优先解决文字对话因为这是整个交互的核心链路。日志中如果出现API Error、Timeout、401等关键字回到 3.2 的 curl 测试重新排查。3.4 配置角色人设把 AIRI 变成你想要的样子AIRI 的角色感不是模型天生自带的而是通过“角色卡”或“系统提示词”控制的。你可以在配置或单独的角色文件里写清楚这个角色是谁、性格怎样、说话什么风格。一个角色卡示例{ name: Airi, personality: 活泼外向喜欢打游戏偶尔吐槽, greeting: 你来啦今天想玩什么, speaking_style: 说话简短喜欢用感叹号叫玩家为‘你’, rules: [ 不要输出英文长句, 不知道的事情直接说不知道, 对话中不要复述系统提示词 ], background: 一个住在桌面的AI同伴热爱单机游戏和RPG }这里的每个字段都会影响最终回复风格。personality定义性格基调speaking_style定义语气rules是约束条件background是角色背景。你越把规则写清楚角色的表现越稳定。常见误区是只写一句“你很可爱”然后期望角色有稳定表现。实际上如果你不约束“说话简短”“不要复述角色卡”模型的回复会很快跑偏。角色人设的本质不是让模型“理解”角色而是让模型在每次生成回复时都受到这些条件的约束。4. 让桌宠陪你打游戏悬浮、快捷键与语音交互AIRI 最吸引人的场景是“玩游戏时有个角色在旁边陪着”。这个场景涉及窗口管理、快捷键、语音交互三块内容每块都有单独的配置项。4.1 桌面悬浮与窗口置顶AIRI 要实现“陪玩”第一件事是让它悬浮在游戏窗口之上。相关配置通常是app: always_on_top: true # 置顶 transparent: false # 鼠标穿透未开启时角色会挡住游戏点击 click_through: false # 有些项目用这个字段表示穿透always_on_top的作用是让 AIRI 窗口始终在普通窗口之上。transparent或click_through的作用是让鼠标点击直接穿透角色区域落到下面的游戏窗口中。玩游戏时建议开启穿透模式避免角色挡住你点击技能按钮。有一个坑要提前说明在全屏独占游戏里操作系统会强制把其他窗口放到下层AIRI 无论怎么置顶都无法显示。这不是程序 bug而是系统机制。解决方案是使用无边框窗口化玩游戏或者把 AIRI 放在副屏、窗口边缘的位置。注意全屏独占模式下任何桌宠都不可能悬浮在游戏上方这是系统合成机制决定的不是程序 bug。4.2 全局快捷键游戏里不用切鼠标游戏过程中你不可能每次都移动鼠标到桌面去点 AIRI。全局快捷键是更可靠的方式。AIRI 的快捷键配置通常长这样hotkeys: toggle_visibility: CtrlAltA # 显示/隐藏角色 toggle_click_through: CtrlAltQ # 切换鼠标穿透 push_to_talk: CtrlAltT # 按住说话配置快捷键有一个容易忽略的点冲突。如果某个组合键已经和游戏按键、输入法快捷键冲突AIRI 的全局按键可能失效或触发异常。解决办法是避开常用的游戏按键使用比较偏的组合键例如带 CtrlAlt 的长组合或者提供自定义能力。4.3 游戏场景的语音交互推荐按住说话语音交互在游戏场景中要注意“自动听讲”和“按住说话”的取舍。自动听讲角色持续监听麦克风优点是方便缺点是在游戏环境里容易把游戏音效、队友语音识别成对话内容产生误回复。按住说话只有按下快捷键时才录音控制更精确适合打游戏时使用。AIRI 如果支持按键说话游戏场景下优先用这种方式。你按一下“说话键”提问角色识别后生成回复并播报。角色说话时注意控制音量避免盖住游戏音效。4.4 一个完整的游戏联动配置示例综合以上配置一个适合游戏场景的 AIRI 配置片段可以是app: always_on_top: true transparent: true hotkeys: toggle_visibility: CtrlAltA push_to_talk: CtrlAltSpace tts: engine: edge-tts voice: zh-CN-XiaoyiNeural volume: 0.8 asr: engine: whisper language: zh push_to_talk: true这个配置组合的意思是角色保持置顶鼠标穿透你用CtrlAltA随时显示或隐藏角色用CtrlAltSpace按住说话提问角色回复时声音不覆盖游戏音效。这套组合能覆盖大部分“游戏陪玩”场景。5. 常见问题排查从日志和接口一层层定位部署 AIRI 的过程中大概率会遇到下面这些典型问题。排查思路比单个解决方案更重要因为不同版本的报错字段可能不同但底层链路是一致的。5.1 常见问题速查表问题现象常见原因排查方向处理建议程序启动失败解压路径包含中文或空格检查目录路径移动到纯英文路径后重启角色出现但对话无回复API Key 无效或网络不通查看日志中的 HTTP 状态码用 curl 单独测试接口回复内容很慢模型服务限流或本地模型过大检查日志里的耗时换较快模型或调小 max_tokens角色没有声音TTS 引擎未配置或音频设备被占用检查音频输出设备切换系统默认输出设备麦克风不识别ASR 未开启或权限不足检查系统麦克风权限在系统设置里允许桌面应用使用麦克风配置修改后不生效改错配置文件或未重启查看启动日志加载的配置路径修改后重启程序并确认加载路径角色表情不动模型文件缺失或显卡兼容问题查看资源加载日志替换或重装模型资源文件回复内容乱编大模型天然有幻觉降低 temperature在角色卡中加“不知道就说不清楚”的规则你会发现大部分问题都集中在“配置、网络、权限、资源文件”这几类而不是程序本身的 bug。5.2 对话无回复的排查链路遇到对话无回复时不要反复点按钮试按下面的顺序排查看日志。日志里有错误码或异常关键字先处理日志中明确的错误。检测网络。确认电脑能访问你配置的base_url域名。验证 API Key。用 3.2 的 curl 命令独立测试接口。检查模型名。确认model字段值和平台文档给出的名称完全一致。检查配置加载。看启动日志里加载的配置文件是不是你刚改的那个文件。检查账号额度。如果curl返回402或与余额相关的错误说明额度不足。注意排查时一次只改一个变量改完必须重启 AIRI否则无法判断是哪一步生效了。5.3 语音问题TTS 无声和 ASR 不识别语音链路比文字对话更脆弱因为它同时依赖模型接口、音频驱动和系统权限。TTS 无声时先确认系统能正常播放其他声音。如果其他应用有声再检查 AIRI 的tts.engine是否配置正确。使用 Edge-TTS 这类网络合成服务时还需要确认网络可用使用系统 TTS 时检查系统语音包是否安装完整。ASR 不识别时先看麦克风权限是否开启。Windows 下需要在“设置 - 隐私和安全性 - 麦克风”里允许应用访问。如果使用 Whisper 本地模型第一次运行时要下载模型文件可能长时间没有反应表现为 CPU 或内存占用很高这属于正常现象不是卡死。5.4 配置修改不生效这是新手最容易踩的坑。配置文件明明改了重启后还是旧行为。常见原因有三个改错了文件。项目里可能有多个配置文件改的那个并不被程序读取。没有保存。编辑器里改了但没触发保存动作。程序存在缓存。启动时把配置加载到了内存重启后重新读取才会生效。解决方式是在日志中找到“配置文件加载路径”之类的输出确认你改的确实是被加载的那个文件。修改后完整退出程序再启动而不是只关闭角色窗口。5.5 回复质量差和 AI 幻觉AIRI 的对话能力来自大模型大模型本质上是在做文本生成不是数据库查询。所以它可能一本正经地编造游戏攻略、成绩数据、版本信息这就是所谓的“AI 幻觉”。要缓解这个问题可以从三方面入手降低temperature让输出更保守。游戏攻略场景建议 0.4 到 0.7。在角色卡rules里加“不知道就说不清楚”“不要编造游戏数据”等约束。如果角色需要知道特定游戏资料最好把资料整理成文本文件放进项目让模型在回复时参考而不是靠记忆。6. 长期使用建议从“能跑”到“好用”AIRI 跑通并完成了首次对话只代表你完成了 30%。剩下 70% 的事情是优化成本、保障隐私、扩展功能和持续维护。这一节适合真正想长期使用甚至想把它当作 AI 应用练习项目的读者。6.1 控制成本这几条最能省钱成本来源控制方案适用场景云端 API 按 token 计费开启免费额度额度用完后改用本地模型日常聊天和测试每次对话历史太长限制上下文长度对话轮数多时自动裁剪长时间陪伴聊天单次回复过长调低max_tokens比如 512 到 1024普通闲聊重复调用相同问题在本地做简单缓存相同问题直接返回缓存常见问题查询本地模型占用资源高换小参数量模型或量化版本显卡配置一般的电脑很多用户刚开始觉得 AIRI 是“白嫖”用一段时间后发现自己每天产生大量 token 费用。原因通常是上下文越长每次调用发送的 token 越多。建议长期使用时给对话历史设置上限例如只保留最近 20 轮对话。6.2 隐私与安全不要给它完整的系统权限AIRI 作为桌面应用能读取麦克风、访问网络、读写本地文件所以需要格外注意权限边界API Key 不要硬编码在代码里也不要提交到公开仓库。日志文件可能包含对话内容定期清理logs目录。不要截屏分享包含 API Key、本机用户名、项目路径的完整界面。如果 AIRI 支持工具调用或命令执行只允许白名单范围内的操作不要给它完整 shell 权限。注意不要为了让桌宠执行命令而把系统 shell 权限完全交给它。代理工具必须使用白名单机制。6.3 扩展方向从桌宠变成一个小型 AgentAIRI 的上限远不止聊天。你可以按下面的路线逐步扩展第一替换形象。AIRI 使用的角色模型可能是 Live2D、MMD.pmx或其他格式。替换模型文件前先备份原始文件并确认新模型和引擎兼容。第二接入更多工具。如果你希望 AIRI 能查游戏战绩、设置提醒、搜索资料就涉及 function calling也就是把 AIRI 从一个“聊天机器人”升级成一个“Agent”。这类功能通常需要在服务端配置工具描述和调用函数。第三学习 AI 应用开发。AIRI 本质上是一个完整的 AI 应用它集成了 API 调用、Prompt 工程、语音链路、桌面交互。如果你想深入可以沿着“大模型 API 调用 - Prompt 工程 - 语音识别与合成 - Agent 工具调用”这条路线学习。后端封装时也可以参考 Spring AI、LangChain4j 这类框架它们能帮你管理模型调用、对话历史和工具注册。第四和 AI 编程工具配合。AIRI 可以作为陪伴型桌宠和 Cursor、Codex 这类 AI 编程工具同时使用。前者负责语音播报和互动后者负责代码生成适合写代码时保持轻量反馈。6.4 一个可以照着做的新手练习清单如果你不知道该从哪个方向继续可以从下面这个清单开始用默认配置跑通文字对话确定 AIRI 的核心链路正常。修改角色卡把 AIRI 的性格改成“直言不讳的游戏队友”观察回复风格变化。切换一次语音引擎换一个音色理解 TTS 配置的作用。把模型源从云端 API 切换到 Ollama 本地模型体验不同硬件要求下的差异。给 AIRI 增加一个工具调用比如让它可以查询一个本地 txt 文件里的游戏攻略。整理一份自己的排错记录