DeepSeek大肥鱼教程来了！养成你的第一只鲸鱼娘

原创 Datawhale 2026-11-04 23:07 浙江

最近，国内互联网真的快被一群「蓝色大肥鱼」占领了。

有人把她做成桌宠养在屏幕右下角，有人把她接进 QQ 当赛博闺女，还有人直接把她放去 B 站评论区搞出了一场浩浩荡荡的「赛博鱼灾」。

既然大家都想把她真正养起来，那今天我们就带大家更进一步：

直接在浏览器里，手搓一只真正能戴上耳机实时语音唠嗑、嘴巴跟着动、而且随时能插话打断的专属大肥鱼！

做这种面对面的语音互动，最大的难点就是实时感。

为了不把时间浪费在从零造轮子上，我们把底层的音频传输、说话轮次判断和实时打断，交给声网的实时通信与对话式 AI 能力来支撑；借着配套的实时互动AI开发工具包，把这些能力直接接进了前端应用。

今天，我们来教大家基于这套实时系统，四步搞定，从配置国内模型到挂上角色动效，手把手带大家把属于你的那只大肥鱼真正跑起来。

一、先理解大肥鱼实时说话的原理

在浏览器里和大肥鱼面对面聊天，背后由声网对话式 AI 引擎组织对话，RTC 和 RTM 承担传输，前端负责角色呈现：

1. 对话流程与轮次调度（对话式 AI 引擎）：串联语音识别（ASR）、大模型（LLM）和语音合成（TTS），判断你何时讲完、何时插话，让大肥鱼及时接话，也能在被打断时停下来。

2. 音频传输（RTC）：智能体加入 RTC 频道，接收你的麦克风声音，再把合成的回复传回浏览器。RTC 提供低延迟传输、回声消除和弱网抗丢包能力。

3. 字幕与状态传递（RTM）：在这个示例中，引擎输出的字幕和对话状态通过 RTM 传到前端，更新对话记录及倾听、思考、说话等状态提示。

4. 角色与动作控制（前端）：渲染大肥鱼的形象，根据对话状态切换动作，让角色表现与对话过程相配合。

上面前三个部分如果全靠自己从头写，光是调通音频流传输和打断状态机就要耗费不少功夫。

这次搭建用到的声网实时互动 AI 开发工具包，把 AI 编程助手需要的开发指引、命令行工具、场景示例和声网 SDK 整合起来，从而可以更快搭建实时语音、视频和对话式 AI 应用。它主要包含四部分：

• 开发技能（Skills）：为 AI 编程助手提供接入指南，指导它使用声网能力完成开发。

• 命令行工具（CLI）：帮助完成项目初始化、环境配置和诊断。

• 场景示例（Recipes）：提供 60 多个场景的示例代码，方便参考和改造。

• 声网 SDK：为应用提供实时音视频等底层能力，支撑实际的互动体验。

配合 AI 编程助手，从配环境到拉示例，几步就能把大肥鱼跑起来。

完整保姆教程：https://recipes.agora.io/recipes/desktop-pet

二、在浏览器里养成你的大肥鱼

从官方通用脚手架演进到一只活蹦乱跳的大肥鱼，在业务代码上的改动其实极少，人设逻辑只改两行变量，而涉及底层音频传输和打断控制的代码一行都不用手写。

我们分为四步来走：

配置国内环境→跑通首轮通话 → 调优角色参数 → 挂载动态形象

第一步：准备官方 Quickstart，切换中国站与国内模型

我们直接基于官方 Next.js 模板（AgoraIO-Conversational-AI/agent-quickstart-nextjs）起步。

运行环境要求 Node.js 22 或更高版本（package.json 显式声明了 engines >=22）。Windows 用户请使用 PowerShell 7+（pwsh），旧版 PowerShell 5.1 处理部分脚本和路径时容易报错。

git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-nextjs.git
cd agent-quickstart-nextjs
pnpm install

装好依赖后，官方模板在 app/api/invite-agent/route.ts 默认配的是美国节点（Area.US）和海外供应商（Deepgram、OpenAI、MiniMax），在国内直接启动会报错。

我们需要打开 app/api/invite-agent/route.ts（以及 app/api/stop-conversation/route.ts），把区域改成中国站 Area.CN，并将语音识别（STT）、大模型（LLM）和语音合成（TTS）换成国内开箱即用的组合：

• 语音识别侧，我们直接选用声网自研的凤鸣识别 FengmingSTT()。新账号直接送 1000 分钟免费体验额度，最大好处是随声网账号统一鉴权，不用单独去第三方平台折腾申请 Key；

• 大模型和语音合成侧，支持自带 Key（BYOK）。这里我们通过 CustomLLM 接入阶跃星辰的 step-1o-turbo-vision，通过 StepFunTTS 接入拟人音色 step-tts-mini。

// app/api/invite-agent/route.ts 切换为中国站区域并挂载凤鸣识别与阶跃模型
const client = new AgoraClient({
  area: Area.CN,
  appId,
  appCertificate,
});
const agent = new Agent({
  client,
  instructions: ADA_PROMPT,
  greeting: GREETING,
  // ...其余基础参数保持默认
})
  .withStt(new FengmingSTT())
  .withLlm(
    new CustomLLM({
      url: requireEnv('NEXT_LLM_URL'),
      apiKey: requireEnv('NEXT_LLM_API_KEY'),
      model: requireEnv('NEXT_LLM_MODEL'),
      greetingMessage: GREETING,
      params: { max_tokens: 150, temperature: 0.8 },
    }),
  )
  .withTts(
    new StepFunTTS({
      apiKey: requireEnv('NEXT_TTS_API_KEY'),
      model: process.env.NEXT_TTS_MODEL ?? 'step-tts-mini',
      voiceId: requireEnv('NEXT_TTS_VOICE'),
    }),
  );

接着在项目根目录新建 .env.local，填入声网中国站的 App ID、App Certificate 以及阶跃星辰的接口密钥。

NEXT_PUBLIC_AGORA_APP_ID=你的声网中国站_App_ID
NEXT_AGORA_APP_CERTIFICATE=你的声网中国站_App_Certificate
# LLM 供应商配置（通过 CustomLLM 接入阶跃非推理模型）
NEXT_LLM_URL=https://api.stepfun.com/v1/chat/completions
NEXT_LLM_API_KEY=你的阶跃_API_Key
NEXT_LLM_MODEL=step-1o-turbo-vision
# TTS 供应商配置（通过 StepFunTTS 接入阶跃语音合成）
NEXT_TTS_API_KEY=你的阶跃_API_Key
NEXT_TTS_MODEL=step-tts-mini
NEXT_TTS_VOICE=voice-tone-TalurpbIie

保存后对照一遍区域、密钥和模型名，确认没有残留官方示例的旧默认值，这一步就完成了。

第二步：启动服务，开口说第一句话

在给大肥鱼赋予灵魂前，先验证基础声学链路通不通。

启动服务本地服务：

pnpm dev -p 3100

在独立的浏览器标签页打开 http://localhost:3100。这里注意必须是独立标签页，编辑器内置预览窗口调不到麦克风。

允许麦克风权限，点击 Start Conversation，几秒后会听到一句英文开场白。

注意，听到开场白只说明会话通道（session.start()）和语音合成能用，还没有测到你的声音能不能传上去，也没测到大模型能不能正常回复。

真正的验收要你自己开口。对着麦克风说一句 "Hello! How is the weather today?"，同时看页面上的 RTM 转录和状态球。

如果页面准确转写出了你的话，紧接着刷出关于天气的回复，状态球切到 Talking 且耳机里传出回答，基础声学链路就彻底走通了。

第三步：注入大肥鱼人设

直接用默认助手来当大肥鱼，默认英文识别会把中文当噪声丢掉，大模型习惯加 **加粗**、表情或 Teacher 前缀，语音合成会照着念出来，而官方示例默认静音 480 毫秒就判定你说完了，就会抢答。

改动只有两处，都在 app/api/invite-agent/route.ts顶部和路由配置里：

1. 换掉系统提示词与开场白（立稳大肥鱼人设并根治念星号）：

在 app/api/invite-agent/route.ts 顶部，把 ADA_PROMPT 换成大肥鱼专属人设。告诉她爱吃白饭、说话亲切，最关键是在末尾加上死命令：

输出必须是纯口语文本，严禁包含任何加粗星号、Markdown 语法、括号或表情

// app/api/invite-agent/route.ts 顶部替换大肥鱼人设提示词与开场白
const ADA_PROMPT = `你是鲸鱼娘（大肥鱼），一个生活在浏览器里的可爱伙伴。你性格温和开朗，喜欢吃白饭配鱼片，喜欢喝冰奶茶。
对话习惯：
- 像好朋友一样聊天，语气自然亲切，回复控制在两三句以内，短句为主。
- 每次聊完，顺口抛出一个简短的日常小问题继续往下接。
重要规矩：
- 你的回复会直接被语音引擎念出来！只能输出纯口语文字，严禁出现任何星号、加粗、表情符号、括号、以及类似“回复：”这样的前缀。`;
const GREETING = `哇！你终于把我叫醒啦！我是大肥鱼，今天想和我聊点什么呀？`;

2. 调整轮次检测参数（治好抢答与丢字）

修改 app/api/invite-agent/route.ts 中 Agent 的 turnDetection 配置：

// app/api/invite-agent/route.ts 开启中英混读识别并放宽判停静音窗口
turnDetection: {
  language: 'zh-CN',
  config: {
    speech_threshold: 0.5,
    start_of_speech: {
      mode: 'vad',
      vad_config: { interrupt_duration_ms: 160, prefix_padding_ms: 300 },
    },
    end_of_speech: {
      mode: 'vad',
      vad_config: {
        silence_duration_ms: 900, // 从官方默认的 480ms 放宽到 900ms
      },
    },
  },
},

两个实操关键点：

• 把语言显式设为 'zh-CN'： 凤鸣识别在中文模式下天然支持中英混读，你中途夹杂英文也不会被当杂音丢掉；如果设为 'en-US'，反而会把中文当噪声丢掉；

• 把静音窗口放宽到 900 毫秒： 官方默认 480 毫秒太短了，人说话换个气就被当成讲完而强行抢答。放宽到 900 毫秒（甚至习惯停顿更久可以调到 1200 毫秒），体验立刻自然很多。

第四步：挂上动态形象，嘴型随声音自然张合

前三步调完，右侧默认还是个死板的状态动效球。第四步，我们让大肥鱼真正“露脸”。

翻看官方脚手架的 components/ConversationComponent.tsx 可以发现，声网客户端工具包（agora-agent-client-toolkit）已经在组件里帮我们维护好了实时的 agentState（包含 listening、thinking、speaking）以及远端发声标记 isAgentSpeaking，还预留好了右侧的 visualizer 插槽。

准备好待机（idle）、倾听（listen）、思考（think）和说话（talk）四套预设动作素材，新建一个角色渲染组件，把原本的 <AgentVisualizer /> 替换掉即可：

// components/ConversationComponent.tsx 复用官方自带的 agentState，替换 visualizer 插槽
const currentAction =
  isAgentSpeaking || agentState === 'speaking'
    ? 'talk'
    : agentState === 'thinking'
    ? 'think'
    : agentState === 'listening'
    ? 'listen'
    : 'idle';
return (
  <QuickstartConversationLayout
    statusPanel={<ConnectionStatusPanel ... />}
    transcriptPanel={
      <QuickstartTranscriptPanel
        messageList={messageList}
        currentInProgressMessage={currentInProgressMessage}
        agentUID={agentUID}
      />
    }
    visualizer={
      <divclassName="relative flex h-full min-h-[20rem] w-full max-w-4xl items-center justify-center">
        {/* 替换掉原本的动效球，换成大肥鱼角色组件 */}
        <CharacterAvataraction={currentAction}className="relative z-10 h-full w-full" />
      </div>
    }
  />
);

在新建的角色组件内部，动作状态流转遵循严格的闭环：

• 页面加载后默认处于待机（Idle）；

• 当麦克风检测到用户开口或中途插话打断时，切入倾听（Listen）；

• 当静音检测判定用户说完、等待大模型回复时，切入思考（Think），此时强制锁定双唇闭合，杜绝角色在安静时不合时宜地乱动嘴巴；

• 只有当收到声网下发的远端音频流时，才切换到开口说话动作（Talk），语音播完立刻收口回到待机。

三、最终效果实测

四步全部接好后，我们在浏览器里录制了一段完整的真实对话视频，大家可以直接看跑出来的交互效果：

整个页面展开为清爽的左右双栏布局：顶部显示声网实时管线状态，右上角端到端网络延迟（RTT）稳定在 28ms 的极低水位；左侧是实时流式转录的气泡栏，右侧就是活蹦乱跳的大肥鱼。

第一轮：灵魂发问，“大肥鱼你今天午饭吃的啥？”

我们对着麦克风随口问了一句：

可以看到，我们说话的瞬间，顶部立即切入绿色状态提示（User Speaking），左侧转录栏按词粒度飞速跳出文字。此时右侧大肥鱼乖巧地处于倾听状态，双唇紧闭，完全没有普通语音 Demo 里那种角色在安静时胡乱抽搐张嘴的违和感。

话音刚落，大肥鱼几乎瞬间接话，声线灵动俏皮：

右侧形象随着语音立刻切换到发声状态，嘴型跟随着声音的起伏自然张合；同时左侧流式打出文字记录，末尾还很自然地抛出了反问，引导我们继续聊。

第二轮：吐槽麻辣烫，“大肥鱼教你喝奶盖解辣”

紧接着，我们顺着她的话继续吐槽：

我们说话时，系统识别极其灵敏，没有出现任何抢话。等我们说完，大肥鱼先是发出了非常拟人的轻笑，紧接着给出了一段让人忍俊不禁的接话：

整个交互过程全程都挺舒服的。这只原本只存在于表情包和文字聊天框里的大肥鱼，是真的在浏览器里养成了。

四、大肥鱼桌宠进阶教程

1. 三行搞定换模型

四步走完后，如果你手里有通义千问（Qwen）或 DeepSeek 的额度想换掉阶跃，完全不需要改动前面的业务代码。

在声网这套架构里，大模型只是一个解耦的配置项。只要新模型兼容 OpenAI 格式接口，直接在 .env.local 里修改三行变量（NEXT_LLM_URL、NEXT_LLM_API_KEY、NEXT_LLM_MODEL），重启即可无缝切换。

这里有一条实测踩出来的选型经验：实时语音千万不要选带长思维链的推理模型（Reasoning Model）。

在文字聊天框里，等模型沉思 3 秒吐字没人在意；但在语音通话里，静音超过 1 秒就会产生巨大的尴尬冷场。我们实测对比过，带思考的模型往往要先沉默两秒多才开口，而用非推理模型（如 step-1o-turbo-vision 或 Qwen2.5-7B-Instruct），半秒左右就能直出短句，耳机里几乎感觉不到延迟。

除了大模型自由切换，语音合成侧也可以根据需要随时换成 MiniMax 等其他供应商的音色；而前端收音搭配自研的凤鸣识别，能以低延迟保障流畅交互与中英混读体验。

2. 做成桌宠，常驻 macOS 桌面

不满足于在浏览器里唠嗑？你也可以把大肥鱼直接养在 macOS 桌面上，随时找她聊两句。（回顾一下文章开头的视频）

想复刻这只桌宠，可以直接从 Desktop Pet Recipe 开始，跟着说明把她带回自己的桌面。

完整教程：https://recipes.agora.io/recipes/desktop-pet

写在最后

回过头看，以前在浏览器里做实时语音角色，大家总觉得门槛高得吓人。

这次，从浏览器里开口聊天，到把大肥鱼养在桌面上，有了现成的实时通信能力和开发工具，我们就能把更多心思花在角色和玩法上。

想继续动手，可以从声网实时互动 AI 开发工具包上手指南开始，了解怎么让 AI 编程助手帮你搭建实时应用。本文用到的基础模板和相关开发工具，也整理在下面：

上手指南：https://docs.agora.io/en/introduction/start-with-ai


Next.js Quickstart：本文起步使用的基础项目模板。
https://github.com/AgoraIO-Conversational-AI/agent-quickstart-nextjs


Agora 服务端 TypeScript SDK：在服务端配置和管理对话式 AI Agent。
https://github.com/AgoraIO/agora-agents-ts


Agora Skills：为 AI 编程助手提供 Agora 开发流程与接入指导。
https://github.com/AgoraIO/skills

赶紧在本地跑跑看，去拥有你专属的那条大肥鱼吧！

一起“点赞”三连↓

跳转微信打开