Project AIRI Web 版入门指南从 Provider 接入、语音交互到角色卡配置【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇指南以 Project AIRI 官方手册的 Web 版本快速上手文档 为核心骨架系统讲解 Web 版 AIRI 的完整上手流程如何选择并配置 Chat Provider、完成首次对话如何为 AIRI 配置耳朵与嘴巴语音识别与语音合成以及如何使用内置与自定义角色卡。读完本文你将掌握 AIRI Web 版的完整配置路径、Provider 通用字段语义、语音模块接入步骤与角色卡机制并能对照仓库源码理解各模块的实现位置。首次启动选择语言与接入方式AIRI 第一次打开时界面右上角有一个地球按钮globe button可用来切换界面语言满足多语言用户需求。语言能力由 Web 端的前端国际化模块承载对应实现位于 apps/stage-web/src/modules/i18n.ts模块注册与 packages/i18n多语言资源。切换语言后首次启动面临两种接入方式的选择Setup with your provider使用你自己的模型服务商自托管场景的首选与项目self hosted, you-owned的定位一致Sign in登录并使用官方 AIRI Provider。无论选择哪种方式核心目标都是让 AIRI 获得一个可用的 Chat Provider 与模型从而具备文本对话能力。第一步选择 Chat Provider进入配置流程后需要先选择一个 Chat Provider。官方手册推荐的三类典型起点为起点适用场景参考配置文档OpenAI使用 OpenAI 官方服务Configure chat modelDeepSeek国内可用、成本友好的对话模型DeepSeek ProviderOllama本地运行模型服务完全离线Ollama Provider如果使用的是其他实现了 OpenAI API 的服务例如手册中作为示例的 SiliconFlow则应选择OpenAI Compatible然后同时填入API Key服务商签发的访问令牌Base URL该服务商文档中声明的 API 根地址必须包含完整的https://或http://前缀。注意不要凭猜测填写 Base URL、模型 ID 或区域参数这些字段因服务商而异务必以对方官方文档为准。仓库中为大量兼容 OpenAI API 的服务商提供了独立配置页例如 openai.md、siliconflow 相关服务商文档 目录下的各 Provider 页面可直接按需查阅。第二步选择模型并保存Provider 凭证填好后选择该 Provider 支持的一个聊天模型然后点击Save and Continue进入下一步。手册特别提示了关于推理模型Reasoning models的注意事项Reasoning models may take longer to respond. Choose a non-reasoning model if you prefer faster conversation.即推理模型如具备思维链能力的模型响应耗时更长如果追求更快的对话速度建议选择非推理模型。Provider 验证机制在保存过程中AIRI 会对表单进行自动验证。验证强度因 Provider 而异详见 通用配置说明仅校验必填字段格式拉取模型列表当 Provider 支持列出模型时提供Ping API按钮发送一次真实的小额请求进行连通性测试可能消耗少量额度。若验证通过但模型列表为空说明该 Provider 不支持列出模型或 API Key 缺少相应权限此时可在Settings → Modules → Consciousness中手动输入与官方文档完全一致的模型 ID。第三步开始第一次对话配置完成后在主界面的聊天框中输入文本并发送即可与 AIRI 对话。若发送Hello后能收到回复说明 Provider 与模型链路已全部打通。若 AIRI 无响应优先检查Settings → Modules → Consciousness中是否同时选中了 Provider 与模型——仅保存 Provider 凭证并不会自动启用该 Provider。眼睛、耳朵与嘴巴多模态交互除文本对话外AIRI 还支持语音输出嘴巴、语音输入耳朵与视觉理解眼睛。所有功能入口集中在右上角的Settings → Modules。Web 端音频能力在源码中有对应实现例如 apps/stage-web/src/composables/audio-input.ts 与 audio-record.ts 承担麦克风输入与录音相关逻辑。让 AIRI 说话TTS 语音合成配置分两步配置语音服务商打开Settings → Providers → Speech选择一个语音合成TTS服务商并填入凭证若服务商提供 playground可先合成一句短句测试。在模块中启用打开Settings → Modules → Speech选择刚配置的 Provider、模型与音色Voice。注意先选模型、再选该模型支持的音色二者的支持范围需与服务商能力一致。详细步骤见 配置语音输入与输出。启用语音输入ASR/STT 语音识别同样分两步配置转写服务商打开Settings → Providers → Transcription选择自动语音识别ASR/STT服务商并填入凭证在模块中启用打开Settings → Modules → Hearing选择 Provider 与模型再选择一个可用的麦克风。主页上的麦克风按钮会展开 Hearing 控制面板。在 Hearing 页面点击Start Monitoring并说一句简短的话确认识别结果区域正确出现文字即配置成功。若 ASR 无输出请检查 AIRI 是否获得麦克风权限、所选输入设备是否正确以及浏览器/系统权限是否被撤销。语音输入与输出相互独立可按需分别配置详见 配置语音输入与输出 与 通用配置说明。视觉捕获目前仅限桌面版屏幕与窗口捕获Vision Capture目前仅在Desktop 版中可用。Web 用户如需为 AIRI 配置视觉理解能力可参考 配置视觉理解 完成 Provider 与模型的设置再在桌面端按 Vision Capture 工作流启用。视觉模块的要点包括Vision Provider 的表单字段与 Chat 表单相同API Key、Base URL、Azure 资源信息、AWS Region 等但保存值是独立的——在 Chat 中保存凭证不会自动填充到 Vision 中必须选择明确支持图片输入的模型在Settings → Modules → Vision中可设置Capture interval控制视觉采集频率桌面端还需在System → Developer → Vision Capture中授予屏幕录制权限、选择窗口/显示器并启动 ticker。Character Card角色的身份与偏好AIRI 内置一张名为ReLU的角色卡你也可以创建自己的角色卡。通过主页面右上角的角色切换器或在 Settings 中切换卡片即可在不同角色之间切换。角色卡的内容一张角色卡定义 AIRI 的name角色名称description角色简介personality性格设定scenario场景设定greetingsfirst_mes / alternate_greetings开场问候语。通过这些字段角色卡可以完整定制 AIRI 的身份与行为方式。AIRI 的角色卡遵循 Character Card V3chara_card_v3规范仓库提供了完整的 角色卡模板其中card.json的结构如下{ spec: chara_card_v3, spec_version: 3.0, data: { name: Example Character, nickname: Example, description: A short description of who this character is., personality: Curious, warm, and a little playful., scenario: This character is meeting the user for the first time., first_mes: Hello! Nice to meet you., alternate_greetings: [], creator_notes: , character_version: 1.0.0, system_prompt: , post_history_instructions: , extensions: {} } }需要特别留意的是AIRI 角色卡以.zip包形式导入包根目录必须同时包含manifest.json与card.json两个文件单独上传 JSON 文件会失败。最小化manifest.json如下{ format: airi-character-card, version: 1, card: { path: card.json, spec: chara_card_v3 } }若角色卡附带展示模型AIRI 导出的包还会在models/目录下包含模型文件并在manifest.json中描述它不含模型的卡片只需上面两个文件即可。注意AIRI 角色卡并非 CCv3 的无损备份。导入时仅保留白名单内的角色字段与 AIRI 模块设置group_only_greetings、mes_example、creator、tags等不支持的 CCv3 元数据以及extensions.airi中的第三方扩展会被丢弃如需无损备份请另行保留原始卡片。角色卡的设置角色卡还可以存储模块偏好module preferences。因此切换角色profile时会连同该角色关联的模型选择一起切换——即一个角色一套模型配置不同角色可以使用不同的 Provider 与模型组合这在多角色、多模型混合使用的场景下非常实用。附录Provider 配置的通用要点以下要点来自 通用配置说明适用于 Chat、Vision、Speech、Transcription、Artistry 全部五类 Provider标准配置流程打开Settings → Providers→ 选择类别 → 选择 Provider 并填写凭证 → 必要时在高级设置中修改 Base URL → 等待自动验证或使用 Ping API 实测→ 在Settings → Modules对应页面中选择该 Provider 与模型/音色。常见字段语义字段含义填写指引API Key服务商签发的访问令牌完整粘贴不要加引号或多余空格Base URLProvider API 根地址仅在官方文档要求时修改需包含完整https://或http://前缀Model对话、语音或识别所用的模型 ID优先使用 AIRI 列表中的模型列表不可加载且字段允许自定义时填写官方文档中的精确 IDVoice语音合成所用音色 ID先选模型再选该模型支持的音色Region部分云服务的部署区域与 Provider 控制台中的项目/资源区域保持一致验证失败时的排查顺序确认账户对服务有访问权限且额度/配额充足重新复制 API Key检查首尾是否有空格或换行恢复默认 Base URL或与官方文档逐字符比对确认网络、代理与防火墙可访问该 Provider选择 Provider 明确支持的模型不要用展示名当作模型 ID。凭证安全所有凭证与 Provider 设置均保存在当前设备的本地设置中切勿在截图、日志、Issue 或聊天消息中泄露 API Key 等敏感信息。从文档到源码Web 版实现位置速览结合仓库源码结构可以快速定位上文各功能在 Web 端apps/stage-web的实现载体多语言切换apps/stage-web/src/modules/i18n.tsPWA 支持apps/stage-web/src/modules/pwa.ts 与 apps/stage-web/src/stores/pwa.tsWeb 端可安装运行音频输入/录音apps/stage-web/src/composables/audio-input.ts、apps/stage-web/src/composables/audio-record.ts背景与开发者工具状态apps/stage-web/src/stores/background.ts、apps/stage-web/src/stores/devtools-lag.ts。各服务商的具体接入说明Chat / Vision / Speech / Transcription / Artistry 分类可继续查阅 Provider 配置指南 及 config/providers 目录下的各页面。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考