企业官网建设流程全解析

AIRI 是一个开源的二次元 AI 桌宠项目。在社区流传的称呼里，它常被人叫做“AI女友”或者“AI老婆”，但从工程角度更准确的理解是：一个常驻桌面的、能说话、能陪你聊天的 AI 角色。它的运行方式并不复杂：桌面显示卡通形象，后台调用大模型生成对话，再通过语音识别和语音合成完成交互。相比打开网页和 AI 聊天，AIRI 更强调陪伴感、角色人设和游戏场景。

这篇文章会按一条完整的实践路线来写：先讲清楚 AIRI 由哪些模块组成，再准备好模型 API、语音组件和系统环境，接着完成下载、配置、首次对话验证，然后配置游戏联动，最后给出常见问题排查和长期使用建议。整个流程不需要编程基础，但如果你会看日志和改配置文件，遇到问题时会轻松很多。

要提前说明的是：AIRI 是一个社区项目，不同版本的配置字段、目录结构、功能开关可能有差异。因此文中给出的目录、配置和代码属于“典型参考结构”，你在落地前一定要以自己下载版本的 README 和示例配置为准。

1. 先搞清楚 AIRI 是什么：桌宠不是网页聊天室

很多人第一次看到 AIRI，会把它理解成一个会动的聊天窗口。这个理解不完整。AIRI 的价值不在于“能聊天”，而在于它把角色形象、模型对话、语音交互和桌面窗口管理组合成了一个完整的陪伴型应用。你先理解这一层，后面配置时才不会改错地方。

1.1 从“AI女友”到“桌面AI助手”

“AI女友”是用户称呼，不是产品类型。技术上，AIRI 本质上是一个带有固定角色人设的 AI 对话系统，只是它的交互入口不是一个网页，而是一个桌面悬浮角色。

可以对比看这三类产品的差异：

AIRI 属于第三类。它不会替你做复杂办公任务，也不追求回答问题有多准确，它更看重“角色像不像一个人”“互动是否自然”“能不能在游戏时陪着你”。理解了这一点，你就不会拿“和 ChatGPT 比知识量”的标准去要求它，也不会在配置时忽略掉角色人设和交互体验。

1.2 用技术视角拆解 AIRI 的四个核心模块

无论 AIRI 的代码用哪种语言编写，它的整体架构通常可以拆成四层：

这四个模块不是必须同时工作的。AIRI 的常见使用方式是“先文字，后语音”，也就是先用文字把对话链路跑通，再开启语音识别和语音合成。如果一开始就全开，出了问题你很难判断是模型的问题还是音频设备的问题。

1.3 为什么说它“免费”，但又不是“完全零成本”

AIRI 本身是开源软件，代码和基础功能通常是免费提供的，这是它被称为“白嫖”的最主要原因。但 AIRI 本身不产生智能，它的对话能力来自背后的大模型。大模型服务通常有三种情况：

• 使用云厂商提供的 API：大部分平台会提供一定的新用户免费额度，适合先用起来，额度用完后再按量付费。
• 使用本地模型：在电脑上跑开源模型，如 Ollama 部署的模型，不需要按次付费，但需要足够的内存和显卡资源。
• 使用免费或低价的公益接口：这类接口可用性和稳定性差别很大，不建议作为长期依赖。

所以更准确的说法是：AIRI 软件免费，模型调用可能免费额度，也可能需要成本。你在部署前想清楚自己走哪条路线，后续配置就会顺利很多。

2. 部署前把模型 API、语音组件和系统环境一次备齐

AIRI 的安装本身不难，难点在于它依赖多个外部组件。如果这些前置组件没有准备好，就算程序启动成功，你也会看到角色站在桌面上但怎么说话都不回复。这一节的任务，就是把所有前置项一次检查完。

2.1 系统要求：先判断你的电脑能不能跑

不同类型的桌宠项目对硬件要求差别很大。只跑对话和语音，对性能要求不高；但如果要在本地跑模型，要求就会明显提高。下面是一份参考标准，具体以你下载版本的说明为准：

检查系统时有一个容易被忽略的点：解压路径。AIRI 这类项目对中文字符、空格和特殊符号的路径兼容性较差，建议解压到类似D:\AIRI或者/Users/你的名字/airi这种简单路径下，否则可能遇到模型加载失败、配置文件读取不到的问题。

2.2 准备一个可以调用的大模型 API

AIRI 的对话层需要一个模型接口。新手最容易犯的错误是以为“下载了 AIRI 就能聊天”，实际上你必须先把某个大模型服务的访问凭据准备好。

常见的模型路线如下表：

判断一个接口是否兼容 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.bat，macOS 下执行start.sh。首次启动时，注意看日志窗口的输出，而不是只看桌面有没有出现角色。

推荐的验证顺序是：

1. 程序启动，日志中不出现致命错误。
2. 桌面出现 AIRI 角色形象，能拖动或响应点击。
3. 输入一条文字消息，比如“你好”，角色能给出回复。
4. 如果开启语音，再验证“说话 -> 文字 -> 回复 -> 播报”的完整链路。

如果第 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: "Ctrl+Alt+A" # 显示/隐藏角色 toggle_click_through: "Ctrl+Alt+Q" # 切换鼠标穿透 push_to_talk: "Ctrl+Alt+T" # 按住说话

配置快捷键有一个容易忽略的点：冲突。如果某个组合键已经和游戏按键、输入法快捷键冲突，AIRI 的全局按键可能失效或触发异常。解决办法是避开常用的游戏按键，使用比较偏的组合键，例如带 Ctrl+Alt 的长组合，或者提供自定义能力。

4.3 游戏场景的语音交互：推荐按住说话

语音交互在游戏场景中要注意“自动听讲”和“按住说话”的取舍。

• 自动听讲：角色持续监听麦克风，优点是方便，缺点是在游戏环境里容易把游戏音效、队友语音识别成对话内容，产生误回复。
• 按住说话：只有按下快捷键时才录音，控制更精确，适合打游戏时使用。

AIRI 如果支持按键说话，游戏场景下优先用这种方式。你按一下“说话键”提问，角色识别后生成回复并播报。角色说话时，注意控制音量，避免盖住游戏音效。

4.4 一个完整的游戏联动配置示例

综合以上配置，一个适合游戏场景的 AIRI 配置片段可以是：

app: always_on_top: true transparent: true hotkeys: toggle_visibility: "Ctrl+Alt+A" push_to_talk: "Ctrl+Alt+Space" tts: engine: edge-tts voice: zh-CN-XiaoyiNeural volume: 0.8 asr: engine: whisper language: zh push_to_talk: true

这个配置组合的意思是：角色保持置顶，鼠标穿透；你用Ctrl+Alt+A随时显示或隐藏角色；用Ctrl+Alt+Space按住说话提问；角色回复时声音不覆盖游戏音效。这套组合能覆盖大部分“游戏陪玩”场景。

5. 常见问题排查：从日志和接口一层层定位

部署 AIRI 的过程中，大概率会遇到下面这些典型问题。排查思路比单个解决方案更重要，因为不同版本的报错字段可能不同，但底层链路是一致的。

5.1 常见问题速查表

你会发现，大部分问题都集中在“配置、网络、权限、资源文件”这几类，而不是程序本身的 bug。

5.2 对话无回复的排查链路

遇到对话无回复时，不要反复点按钮试，按下面的顺序排查：

1. 看日志。日志里有错误码或异常关键字，先处理日志中明确的错误。
2. 检测网络。确认电脑能访问你配置的base_url域名。
3. 验证 API Key。用 3.2 的 curl 命令独立测试接口。
4. 检查模型名。确认model字段值和平台文档给出的名称完全一致。
5. 检查配置加载。看启动日志里加载的配置文件是不是你刚改的那个文件。
6. 检查账号额度。如果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 控制成本：这几条最能省钱

很多用户刚开始觉得 AIRI 是“白嫖”，用一段时间后发现自己每天产生大量 token 费用。原因通常是上下文越长，每次调用发送的 token 越多。建议长期使用时给对话历史设置上限，例如只保留最近 20 轮对话。

6.2 隐私与安全：不要给它完整的系统权限

AIRI 作为桌面应用，能读取麦克风、访问网络、读写本地文件，所以需要格外注意权限边界：

• API Key 不要硬编码在代码里，也不要提交到公开仓库。
• 日志文件可能包含对话内容，定期清理logs目录。
• 不要截屏分享包含 API Key、本机用户名、项目路径的完整界面。
• 如果 AIRI 支持工具调用或命令执行，只允许白名单范围内的操作，不要给它完整 shell 权限。

注意：不要为了让桌宠执行命令而把系统 shell 权限完全交给它。代理工具必须使用白名单机制。

6.3 扩展方向：从桌宠变成一个小型 Agent

AIRI 的上限远不止聊天。你可以按下面的路线逐步扩展：

第一，替换形象。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 一个可以照着做的新手练习清单

如果你不知道该从哪个方向继续，可以从下面这个清单开始：

1. 用默认配置跑通文字对话，确定 AIRI 的核心链路正常。
2. 修改角色卡，把 AIRI 的性格改成“直言不讳的游戏队友”，观察回复风格变化。
3. 切换一次语音引擎，换一个音色，理解 TTS 配置的作用。
4. 把模型源从云端 API 切换到 Ollama 本地模型，体验不同硬件要求下的差异。
5. 给 AIRI 增加一个工具调用，比如让它可以查询一个本地 txt 文件里的游戏攻略。
6. 整理一份自己的排错记录，