AIRI Web 版使用指南：从对话提供商接入到语音与角色卡配置

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本文基于 Project AIRI 官方 Web 版手册（docs/content/en/docs/manual/web/index.md）整理而成，并结合仓库源码补充实现细节。你将学会：在浏览器中首次启动 AIRI、选择并验证聊天提供商与模型、完成首次对话，以及如何开启 TTS 语音输出、ASR 语音输入等交互能力，最后掌握角色卡（Character Card）的切换与自定义。

首次启动：选择语言与接入方式

在浏览器中打开 AIRI Web 版后，界面右上角有一个地球（globe）按钮，可以随时切换界面语言。首次使用时，你有两种接入方式可选：

• Setup with your provider：使用你自己的大模型 API 提供商（推荐自托管场景）。
• Sign in：登录并使用 AIRI 官方提供商（official provider），无需自行准备 API Key。

从仓库的引导流程测试 onboarding.browser.test.ts 可以看到，这两个入口分别触发"官方登录"与"自带提供商"两条配置路径：Sign in按钮走认证登录，Setup with your provider则进入提供商选择卡片，其中OpenAI Compatible是测试覆盖的典型选项（const providerCard = screen.getByText('OpenAI Compatible')）。无论走哪条路径，最终配置结果都会持久化到本地localStorage（键为settings/providers/configured），下次打开会自动回填表单。

选择 Chat 提供商

点击Setup with your provider后，进入提供商选择界面。可直接选择官方列表中的聊天提供商，例如：

• OpenAI
• DeepSeek
• Ollama（本地部署）

如果你的服务实现了 OpenAI API 协议但不在预设列表中，请选择OpenAI Compatible，然后分别填写：

1. API Key：提供商签发的访问令牌，粘贴完整 key，不要加引号或多余空格；
2. Base URL：该服务文档中记录的基础接口地址。

下图是手册中给出的 API 配置示例（截图以 SiliconFlow 为例，展示 OpenAI Compatible 形式下 API Key 与 Base URL 的填写位置）：

关于这些通用字段的取值规范，仓库的通用配置指南 common.md 有更完整的说明：远程服务一律使用https://，仅在可信的本地服务上使用http://；Base URL 需要与提供商官方文档逐字符比对，否则验证会失败。

选择模型并保存

选定提供商后，从模型列表中选择一个兼容的聊天模型，然后点击Save and Continue完成向导。

提示：推理模型（Reasoning models）的响应耗时通常更长。如果你更看重对话速度，可以选择非推理模型。

模型选择与提供商配置是两个独立步骤：Providers 页面负责保存凭据，Modules 页面的模型列表才决定实际使用的模型。AIRI 会在切换提供商后自动重新拉取该提供商的模型目录（providerModels与isLoadingModels状态），详见 provider.ts 中的模型列表逻辑。

开始第一次对话

配置完成后，在主页底部的聊天输入框中输入文本并发送，AIRI 就会基于你选择的模型进行回复。

对话会话由chatstore 管理（chat.ts），发送的消息会携带当前角色卡与模块上下文进入对话流程。

让 AIRI 拥有眼睛、耳朵和嘴巴

除了纯文本对话，AIRI Web 版还支持语音合成（说话）、语音识别（听）等交互能力。这些能力分为提供商配置与模块启用两步，入口统一在右上角Settings → Modules。

让 AIRI 说话（TTS）

1. 打开Settings → Providers → Speech，选择一个语音提供商并填写凭据；
2. 打开Settings → Modules → Speech，选择刚才配置的提供商、模型（model）和音色（voice）。

从源码看，语音模块（speech.ts）是 Web 版语音能力的核心 store，值得了解的实现细节包括：

• 配置项持久化：activeSpeechProvider、activeSpeechModel、activeSpeechVoiceId分别持久化在settings/speech/active-provider、settings/speech/active-model、settings/speech/voice三个 localStorage 键中；
• 额外调节参数：pitch（音高，默认 0）、rate（语速，默认 1）、ssmlEnabled（SSML 开关，默认关闭）；
• SSML 支持：目前仅 ElevenLabs、Microsoft Speech、Azure Speech，以及阿里云 cosyvoice-v2（alibaba-cloud-model-studio）等提供商支持 SSML 语法（supportsSSML计算属性）；
• 语音目录动态加载：切换提供商或模型时会通过loadVoicesForProvider拉取对应音色列表（availableVoices），并根据模型重新推荐默认音色；
• 合成链路：最终通过generateSpeech（来自@xsai/generate-speech）发起 TTS 请求；对双向 WebSocket 传输的流式提供商（如官方流式 TTS），则走streamSpeech流式管线（streaming-pipeline.ts）。

启用语音输入（ASR/STT）

1. 打开Settings → Providers → Transcription，选择转写提供商并填写凭据；
2. 打开Settings → Modules → Hearing，选择提供商与模型，并选择一个可用的麦克风；
3. 返回主页，点击麦克风按钮即可打开听力（Hearing）控制面板。

听力模块（hearing.ts）的实现要点：

• 配置持久化：activeTranscriptionProvider/activeTranscriptionModel持久化在settings/hearing/active-provider、settings/hearing/active-model；
• 自动发送：autoSendEnabled（默认关闭）与autoSendDelay（默认 2000ms）控制识别文本是否自动作为消息发出；
• 置信度过滤：confidenceThreshold用于按verbose_json分段的平均对数概率（avg_logprob）过滤低置信度文本，CONFIDENCE_THRESHOLD_DISABLED = -3表示关闭过滤；
• 实时与文件双模式：支持流式输入（inputAudioStream，PCM16 编码）与录音文件（WAV）两种转写输入；Web Speech API、Sherpaw、Apple Speech、阿里云 NLS 等走STREAM_TRANSCRIPTION_EXECUTORS注册的流式执行器；
• 浏览器内置方案：选择browser-web-speech-api时无需模型即可直接使用浏览器语音识别能力（configured恒为 true）。

两种能力的完整配置与排错流程，可进一步阅读仓库中的 audio.md（语音输入输出总览）与各提供商的专项文档，例如 speech/openai.md、transcription/openai.md。

视觉捕获目前仅限桌面版

屏幕与窗口捕获（Vision Capture）目前仅在Desktop 版可用，Web 版暂不支持。若需为 AIRI 配置视觉理解能力，请参见：

• 视觉提供商与模型配置：vision.md
• 桌面版 Vision Capture 工作流：见该文档中的桌面开发者工具指引

视觉模块在 Web 侧仍可通过 vision.ts 配置提供商与模型（如图像理解模型、捕获间隔 Capture interval），但实际的屏幕帧采集入口仅在桌面端（System → Developer → Vision Capture）提供。

角色卡：定义 AIRI 的身份与行为

AIRI 内置了一张名为ReLU的角色卡（其立绘素材见 relu.avif）。你可以：

• 使用主页右上角的角色切换器在不同角色间切换；
• 或在Settings中管理（创建、编辑、删除、搜索）角色卡。

角色管理页面位于 Web 端设置中心（apps/stage-web/src/pages/settings/characters/index.vue），提供关键词搜索（按角色的英文名与描述过滤）、新建角色、编辑与删除等操作，删除需要二次确认。

角色卡内容

一张角色卡定义 AIRI 的：

• name（名字）
• description（描述）
• personality（性格）
• scenario（场景设定）
• greetings（开场问候语）

这些字段共同决定了 AIRI 的身份与行为风格。从角色卡 store（airi-card.ts）的系统提示词拼装逻辑可以看到，systemPrompt、description、personality、scenario以及 Artistry 模块的widgetInstruction会被依次拼接（以空行分隔）作为发送给模型的系统提示词（resolveSystemPrompt），因此这几项内容会直接影响每次对话的上下文。

角色卡设置与模块偏好

角色卡不仅可以描述身份，还能存储模块偏好——例如某个角色偏好使用特定的语音提供商、音色、模型选择。因此，切换配置文件时可以同时切换角色及其关联的模型选择，实现"角色 × 模型 × 语音"的一体化切换。

这在实现层面由两处状态共同支撑：

• airi-card-active-id：当前激活的角色卡 ID（默认default）；
• airi-card-module-defaults：各模块（speech、hearing、vision、artistry、consciousness 等）的默认选择快照，切换角色卡时会以该快照覆盖运行时模块设置。

应用卡片时会通过resolveModuleSelection把卡片内嵌的模块选择应用到各运行时 store（useRuntimeModuleStores中注册了 artistry、consciousness、speech、stageModel、vision 五个模块），实现"切卡即切配置"。

配置验证与常见排查

配置完成后，可按以下顺序验证链路是否可用（详细字段与排错步骤见 common.md）：

1. 聊天：在输入框发送消息，确认模型正常回复；
2. 语音输出：进入 Speech 模块，点击播放预览音色；无声音时依次检查提供商/模型/音色是否已选、系统输出设备与音量、API Key 与账户额度；
3. 语音输入：在 Hearing 模块点击Start Monitoring后说一句短句，确认识别区出现对应文字；无输出时检查麦克风权限与输入设备选择；
4. 视觉（桌面版）：捕获一个不含敏感信息的窗口，触发一次视觉分析，确认 AIRI 能收到画面描述。

如果验证失败，通用排查顺序为：确认账户有额度/配额 → 重新复制 API Key（去掉首尾空格与换行）→ 恢复默认 Base URL 并与官方文档比对 → 确认网络、代理、防火墙可达 → 选择提供商明确支持且支持图像输入的模型（不要用显示名当模型 ID）。

结语

至此，你已经掌握 AIRI Web 版从首次启动、接入任意 OpenAI 兼容聊天提供商、完成首次对话，到开启 TTS 语音输出与 ASR 语音输入、以及基于角色卡切换"角色 + 模型 + 语音"配置的完整路径。更深入的提供商专项配置（Speech / Transcription / Vision / Artistry 等）可继续阅读 docs/content/en/docs/manual/config/index.md 目录下的各提供商文档。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手