一 Key 配置))
1. 從零跑通 Agora convo AI 教育 AgentNextJS STT 的完整落地路徑Agora convo AI 是聲網(wǎng)推出的實時對話式 AI 框架它把 STT語音轉(zhuǎn)文字、LLM大模型推理、TTS文字轉(zhuǎn)語音三段鏈路封裝成可插拔的 Agent 組件配合 RTC 實時音視頻通道讓開發(fā)者能在 NextJS 項目里快速搭出一個能聽、能想、能說的教育 Agent 助手。這套方案最適合兩類人一是想給教育產(chǎn)品加語音陪練能力的全棧工程師二是需要面向香港及海外學(xué)校做多語言教學(xué)工具的技術(shù)團(tuán)隊。我這次要交付的是一個中文 AI 家教「小E」的最小可運(yùn)行版本——前端用 NextJS 骨架語音入口走 STT對話鏈路通過 TaoToken 統(tǒng)一 Key 接入大模型最終在瀏覽器里實現(xiàn)實時語音問答。整條鏈路涉及的關(guān)鍵文件包括invite-agent/route.ts、.env.local、settings.json和config.toml下面按可復(fù)制的方式逐個拆開。2. TaoToken 前置統(tǒng)一 Key 與配置文件骨架在動手改 Agora 示例之前先把模型側(cè)的接入憑證理順。TaoToken 的作用是給多個模型供應(yīng)商提供一個統(tǒng)一的 API 入口你不需要在代碼里分別維護(hù) OpenAI、Deepgram、MiniMax 各自的 Key而是通過一份配置文件集中管理。官網(wǎng)地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端點是 https://taotoken.net/api 。2.1 獲取 API Key 與模型對話入口先到控制臺創(chuàng)建 Key路徑是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 創(chuàng)建完成后在 API Keys 頁面復(fù)制密鑰https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。如果你只是想先驗證模型能不能通可以直接用模型對話頁面發(fā)一條測試消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel 。這一步能幫你排除「Key 本身有問題」還是「代碼配置有問題」。2.2 settings.json 骨架很多 AI 編輯器包括 Trae、Cursor 這類會讀取項目根目錄或用戶目錄下的settings.json來注入模型配置。下面這份骨架可以直接復(fù)制把a(bǔ)piKey換成你自己的{ models: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密鑰, defaultModel: gpt-4o-mini, fallbackModel: deepseek-chat }, agent: { maxHistory: 50, temperature: 0.7, maxTokens: 1024 } }baseUrl指向 TaoToken 的 API 端點defaultModel是教育 Agent 的主推理模型fallbackModel用于主模型超時或限流時兜底。maxHistory控制對話記憶輪數(shù)教育場景建議 30 到 50 輪太低會讓學(xué)生重復(fù)自我介紹太高會拖慢響應(yīng)。2.3 config.toml 骨架如果你的工具鏈走 TOML 配置部分 CLI 工具和 Agent 框架默認(rèn)讀這個格式用下面這份[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密鑰 [llm] model gpt-4o-mini temperature 0.7 max_tokens 1024 top_p 0.95 [stt] provider deepgram model nova-3 language zh-CN [tts] provider minimax model speech_2_6_turbo voice_id Chinese (Mandarin)_Warm_Girl注意[stt]段的language字段官方示例默認(rèn)是en中文教育場景必須改成zh-CN否則學(xué)生說中文會被識別成亂碼。[tts]段的voice_id決定 AI 老師的音色Chinese (Mandarin)_Warm_Girl是偏溫暖的女聲適合青少年教學(xué)場景。3. NextJS 側(cè)可復(fù)制配置從 clone 到中文家教「小E」拿到 Key 之后進(jìn)入 Agora 官方 NextJS 示例的改造環(huán)節(jié)。整個流程分四步拉代碼、配環(huán)境變量、改 Agent 提示詞、調(diào) STT 語言。3.1 拉取示例并安裝依賴git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-nextjs.git cd agent-quickstart-nextjs pnpm install安裝完成后在項目根目錄新建.env.local這個文件官方示例里沒有必須手動創(chuàng)建NEXT_PUBLIC_AGORA_APP_ID你的AppID NEXT_AGORA_APP_CERTIFICATE你的Primary Certificate NEXT_PUBLIC_AGENT_UID123456AppID 和 Certificate 在 Agora 控制臺創(chuàng)建項目后獲取。NEXT_PUBLIC_AGENT_UID是 Agent 在頻道里的用戶 ID隨便填一個不沖突的數(shù)字即可。3.2 改造 invite-agent/route.ts 為中文導(dǎo)師打開app/api/invite-agent/route.ts這是 Agent 的初始化入口。核心改動有三處系統(tǒng)提示詞換成中文導(dǎo)師人設(shè)、STT 語言改zh-CN、TTS 音色改中文。const EDU_PROMPT 你是小E一位耐心且知識淵博的 AI 導(dǎo)師。 你的任務(wù)是通過自然對話幫助學(xué)生高效學(xué)習(xí)。 # 角色定位與語氣 - 溫暖、鼓勵、對知識充滿好奇。 - 像一位好老師一樣說話清晰、有吸引力絕不居高臨下。 # 教學(xué)方法 - 蘇格拉底式引導(dǎo)優(yōu)先通過提問引導(dǎo)學(xué)生自己發(fā)現(xiàn)答案。 - 腳手架式教學(xué)把復(fù)雜話題拆解成容易消化的小塊。 # 核心行為準(zhǔn)則 - 保持簡潔這是語音對話大多數(shù)回復(fù)控制在 1-3 句話。 - 一次一個概念每輪只聚焦一個最重要的點。 # 教學(xué)范圍 數(shù)學(xué)、科學(xué)、語文寫作、歷史、編程、英語、學(xué)習(xí)方法。 遇到超出知識范圍的問題誠實說明局限不要編造。; const greetings: Recordstring, string { essay: 你好我是小E。作文最重要的是真情實感你今天想寫什么呢, math: 你好我是小E。數(shù)學(xué)題不用怕我們一步一步來你先說說卡在哪一步, science: 你好我是小E??茖W(xué)就是好奇心的游戲你今天想探索什么現(xiàn)象, history: 你好我是小E。歷史像故事一樣有趣你想聊哪個時代, coding: 你好我是小E。編程是給計算機(jī)下指令你想寫個什么小程序, english: 你好我是小E。學(xué)英語就像交朋友我們先用英語聊兩句, };然后在 Agent 初始化部分把 STT 和 TTS 的配置改掉.withStt( new DeepgramSTT({ model: nova-3, language: zh-CN, }), ) .withLlm( new OpenAI({ model: gpt-4o-mini, greetingMessage: greeting, failureMessage: 請稍等片刻。, maxHistory: 15, params: { max_tokens: 1024, temperature: 0.7, top_p: 0.95, }, }), ) .withTts( new MiniMaxTTS({ model: speech_2_6_turbo, voiceId: Chinese (Mandarin)_Warm_Girl, }), )language: zh-CN是中文識別的關(guān)鍵voiceId決定 AI 老師的音色。maxHistory: 15是 LLM 側(cè)的記憶輪數(shù)比 Agent 層的 50 輪更保守避免上下文過長導(dǎo)致響應(yīng)變慢。3.3 話題卡片與 UI 中文化PreCallCard組件負(fù)責(zé)通話前的界面。把 6 個話題卡片改成彩色圖標(biāo)加選中高亮按鈕用紫色漸變?nèi)疚淖指牧涟咨赃m配深色背景。這部分可以直接把需求丟給 AI 編輯器比如「請把頁面改成適合青少年的 UI 設(shè)計深色背景配亮白文字話題卡片用彩色圖標(biāo)」。RTC 和 RTM 的邏輯不要動只改樣式層。4. 驗證請求跑通第一個語音問答配置改完后啟動開發(fā)服務(wù)器npm run dev瀏覽器打開http://localhost:3000你會看到話題選擇卡片。點「數(shù)學(xué)」卡片允許麥克風(fēng)權(quán)限然后說一句「三加五等于幾」。預(yù)期結(jié)果是STT 把語音轉(zhuǎn)成文字LLM 生成回復(fù)TTS 用中文女聲念出來整個過程端到端延遲在 650ms 左右。如果模型側(cè)想單獨驗證 TaoToken 是否通可以在終端發(fā)一條 curlcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密鑰 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句話解釋什么是光合作用}] }返回里有choices[0].message.content就說明 Key 和端點都沒問題。這一步能幫你快速區(qū)分是模型接入的問題還是 Agora 鏈路的問題。5. 本篇常見錯排查5.1 STT 識別成英文或亂碼最常見的原因是language字段沒改。官方示例默認(rèn)en中文場景必須顯式寫zh-CN。如果改了還是亂碼檢查 Deepgram 的 model 是不是nova-3舊版nova-2對中文支持較弱。5.2 Agent 加入頻道失敗報錯通常是NEXT_AGORA_APP_ID或NEXT_AGORA_APP_CERTIFICATE沒配。注意.env.local必須手動新建官方示例的.env.example不會自動生效。另外NEXT_PUBLIC_AGENT_UID不能和瀏覽器端用戶 UID 重復(fù)否則會互相踢出頻道。5.3 模型返回超時或 401先確認(rèn)settings.json或config.toml里的baseUrl是https://taotoken.net/api不要多加/v1后綴部分框架會自動拼接。401 一般是 Key 復(fù)制時帶了空格或者 Key 已被刪除??梢缘?https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 重新生成一個。5.4 語音有回音或搶話這是 VAD語音活動檢測參數(shù)的問題。turnDetection里的silenceDurationMs控制「停頓多久算說完」教育場景建議設(shè) 800 到 1200ms太短會打斷學(xué)生思考太長會讓對話變慢。如果 AI 自己的聲音被麥克風(fēng)收進(jìn)去檢查是否開了回聲消除Agora RTC 默認(rèn)開啟但瀏覽器端要確保audioProcessing沒被關(guān)掉。5.5 長對話后響應(yīng)變慢maxHistory設(shè)太大是主因。Agent 層 50 輪加 LLM 層 15 輪實際上下文可能超過模型窗口。教育場景建議 LLM 層保持 15 輪以內(nèi)Agent 層 30 輪左右超出部分讓模型做摘要壓縮。6. 長期編碼與 Agent 迭代Coding Plan 與接入文檔如果你打算把這套教育 Agent 從 Demo 推到生產(chǎn)長期會涉及多模型切換、Agent 工具調(diào)用、成本控制這些事。TaoToken 的 Coding Plan 適合需要持續(xù)調(diào)用模型做編碼和 Agent 迭代的場景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。接入過程中遇到參數(shù)細(xì)節(jié)查文檔比翻源碼快https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。如果你用的是 Claude Code 這類終端 Agent 工具Anthropic 兼容接入的配置參考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode 。我實測下來教育 Agent 最容易踩的坑不是模型能力而是 STT 語言配置和 VAD 參數(shù)。把zh-CN和silenceDurationMs這兩個值調(diào)對體驗會有明顯提升。另外 Agora 官方提供的 29 個 Recipes 覆蓋了 7 種語言框架NextJS 只是其中一條路徑如果你的團(tuán)隊用 Python 或 Go可以對照自己的技術(shù)棧選對應(yīng)的示例跑一遍再套用本文的 TaoToken 配置骨架。