HTML前端如何对接Fun-ASR后端API？简易集成方案-开发者社区

HTML前端如何对接Fun-ASR后端API？简易集成方案

在语音交互日益普及的今天，越来越多的应用场景需要将用户的语音实时转化为文字——从智能客服到会议纪要，从在线教育到工单录入。然而，自研语音识别系统成本高、门槛高，而市面上许多商用ASR服务又存在价格昂贵或封闭不透明的问题。

有没有一种方式，既能享受大模型带来的高精度识别能力，又能自由控制部署环境、灵活嵌入现有系统？答案是肯定的：Fun-ASR + 原生HTML前端的组合正为此提供了理想路径。

Fun-ASR 是由钉钉与通义联合推出的开源语音识别解决方案，基于先进的端到端模型架构，在中文场景下表现出色。更关键的是，它不仅提供可视化WebUI界面，其底层还暴露了可编程的HTTP接口。这意味着我们完全可以用最轻量的方式——一个纯HTML页面——直接调用它的语音识别能力。

从录音到识别：一条完整的链路是如何打通的？

想象这样一个场景：用户打开浏览器，点击“开始录音”，说完一句话后停止，系统几秒内返回清晰规整的文字结果。整个过程无需安装任何插件，也不依赖复杂框架。这背后究竟发生了什么？

其实流程非常直观：

浏览器通过navigator.mediaDevices.getUserMedia()获取麦克风权限；
使用MediaRecorder API实时采集音频流，并生成二进制 Blob 数据；
将音频数据封装为FormData，通过fetch发送到 Fun-ASR 后端；
后端接收文件，调度 ASR 模型进行推理；
返回 JSON 格式的识别结果（含原始文本和ITN规整后文本）；
前端解析并展示结果。

这条链路的核心优势在于：所有技术组件均为现代浏览器原生支持，无需额外依赖。你不需要会Vue、React，甚至不需要打包工具，一个.html文件就能跑起来。

Fun-ASR 的 API 行为逆向分析

虽然官方尚未发布完整的 OpenAPI 文档，但通过对 WebUI 界面行为的抓包分析（使用浏览器开发者工具的 Network 面板），我们可以准确还原出关键接口的工作机制。

主要接口特征

请求地址：默认为http://localhost:7860/api/transcribe
请求方法：POST
Content-Type：multipart/form-data
参数列表：
audio: 音频文件（Blob 或 File）
language: 语言代码（如zh,en，默认自动检测）
itn_enabled: 是否启用口语到书面语的转换（布尔值字符串）
hotwords: 可选热词列表（以空格分隔）

返回值是一个 JSON 对象，典型结构如下：

{ "text": "今天天气真好我想去公园散步", "itn_text": "今天天气真好，我想去公园散步。", "language": "zh" }

注意：实际字段名可能因版本不同略有差异，建议先运行本地服务并通过 WebUI 提交一次任务来观察响应格式。

跨域问题怎么破？

如果你的前端页面运行在http://localhost:3000，而 Fun-ASR 服务在http://localhost:7860，就会触发浏览器的同源策略限制。

解决方法有两种：

开发阶段：启动 Fun-ASR 时确保后端启用了 CORS 支持。如果使用 Gradio，默认已开启；若为自定义 FastAPI/Flask 服务，需手动添加中间件。
python from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"], )
生产环境：强烈不推荐开放allow_origins=["*"]。应通过 Nginx 反向代理统一域名和端口，例如将/asr-api/路径代理至http://127.0.0.1:7860。

手把手实现一个最小可用前端

下面这个示例页面仅用原生 HTML + JavaScript 实现完整功能，适合快速验证和嵌入已有系统。

<!DOCTYPE html> <html lang="zh"> <head> <meta charset="UTF-8" /> <title>Fun-ASR 对接示例</title> <style> body { font-family: Arial, sans-serif; padding: 20px; max-width: 800px; margin: 0 auto; } button { margin: 10px 5px; padding: 10px 20px; font-size: 16px; cursor: pointer; border-radius: 6px; border: none; background: #007bff; color: white; } button:disabled { background: #ccc; cursor: not-allowed; } #result { margin-top: 20px; white-space: pre-wrap; border: 1px solid #ddd; padding: 15px; min-height: 100px; background: #f9f9f9; border-radius: 6px; } #status { color: #666; font-style: italic; } </style> </head> <body> <h2>🎙️ 语音识别测试（对接 Fun-ASR）</h2> <button id="startRecord">开始录音</button> <button id="stopRecord" disabled>停止录音</button> <button id="sendAudio" disabled>发送识别</button> <div id="status">状态：等待操作</div> <pre id="result">识别结果将显示在这里...</pre> <script> let mediaStream = null; let mediaRecorder = null; let audioChunks = []; const statusEl = document.getElementById('status'); const resultEl = document.getElementById('result'); // 修改为你部署的 Fun-ASR 地址 const FUN_ASR_API = 'http://localhost:7860/api/transcribe'; document.getElementById('startRecord').onclick = async () => { try { mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true }); mediaRecorder = new MediaRecorder(mediaStream); audioChunks = []; mediaRecorder.ondataavailable = event => { audioChunks.push(event.data); }; mediaRecorder.onstop = () => { statusEl.textContent = '录音已停止，可点击【发送识别】'; document.getElementById('sendAudio').disabled = false; }; mediaRecorder.start(1000); // 每1秒触发一次 dataavailable 事件（可选优化点） statusEl.textContent = '🟢 正在录音... 再次点击【停止】结束'; document.getElementById('startRecord').disabled = true; document.getElementById('stopRecord').disabled = false; document.getElementById('sendAudio').disabled = true; } catch (err) { console.error(err); alert('无法访问麦克风：' + (err.message || '权限被拒绝')); } }; document.getElementById('stopRecord').onclick = () => { if (mediaRecorder && mediaRecorder.state !== 'inactive') { mediaRecorder.stop(); mediaStream.getTracks().forEach(track => track.stop()); document.getElementById('startRecord').disabled = false; document.getElementById('stopRecord').disabled = true; } }; document.getElementById('sendAudio').onclick = async () => { if (audioChunks.length === 0) { alert('没有录音数据，请先录音！'); return; } const audioBlob = new Blob(audioChunks, { type: 'audio/webm' }); // 注意格式兼容性 const formData = new FormData(); formData.append('audio', audioBlob, 'recording.webm'); formData.append('language', 'zh'); formData.append('itn_enabled', 'true'); try { statusEl.textContent = '🧠 正在识别中...'; const response = await fetch(FUN_ASR_API, { method: 'POST', body: formData }); if (!response.ok) { const errMsg = await response.text(); throw new Error(`HTTP ${response.status}: ${errMsg}`); } const result = await response.json(); resultEl.innerHTML = ` <strong>🗣️ 原始文本：</strong>${result.text ? result.text : '无内容'}<br><br> <strong>📝 规整后文本：</strong>${result.itn_text ? result.itn_text : '(未返回规整文本)'} `; statusEl.textContent = '✅ 识别完成！'; } catch (err) { resultEl.textContent = '❌ 识别失败：\n\n' + err.message; statusEl.textContent = '⚠️ 错误'; console.error('ASR Request Failed:', err); } }; </script> </body> </html>

关键细节说明

音频编码格式：MediaRecorder在 Chrome 中默认输出audio/webm;codecs=opus，这是高效且广泛支持的格式。Fun-ASR 若无法解析，可在服务端转码（如 ffmpeg）或强制指定 mimeType 为audio/wav（但会增大体积）。
分段上传优化：对于长语音，可以监听ondataavailable并立即上传每个片段，配合 VAD 分割实现“准实时”效果。
错误处理增强：加入了网络异常、HTTP状态码非2xx、JSON解析失败等多重兜底逻辑。
用户体验提示：按钮状态动态更新，避免误操作；状态栏给出明确反馈。

如何应对真实业务中的挑战？

理论可行是一回事，落地应用又是另一回事。以下是几个常见痛点及应对策略：

🔊 麦克风权限被拒怎么办？

这是最常见的问题之一。建议：
- 在页面加载时主动检测权限状态：navigator.permissions.query({ name: 'microphone' })
- 如果被拒，引导用户手动开启（Chrome 设置 > 站点权限）
- 提供“上传已有音频”作为替代入口

📦 大文件导致内存溢出？

Fun-ASR 默认加载整段音频到内存，过长录音容易引发 OOM。对策包括：
- 前端预处理：使用 Web Audio API 结合 VAD（语音活动检测）库（如webvad）切分静音段
- 分块上传：每次只传一个句子长度的片段，后端逐段识别再拼接
- 后端启用流式处理模式（若支持）

🔐 公网暴露有安全风险？

不要让 Fun-ASR 直接对外暴露！正确的做法是：
- 使用 Nginx 做反向代理，统一入口
- 添加 JWT 认证层，校验 token 合法性
- 限制请求频率和并发数，防止滥用
- 日志记录关键操作，便于审计追踪

🌐 Safari 兼容性差？

Safari 对MediaRecorder支持有限（尤其旧版本）。临时方案：
- 引导用户使用 Chrome / Edge
- 或改用<input type="file">上传本地录音文件（牺牲体验换兼容性）

更进一步：不只是“能用”，还要“好用”

当你已经实现了基本功能，下一步可以考虑这些增强特性：

✅ 支持拖拽上传

document.body.addEventListener('dragover', e => e.preventDefault()); document.body.addEventListener('drop', async e => { e.preventDefault(); const file = e.dataTransfer.files[0]; if (!file.type.startsWith('audio/')) return; handleAudioFile(file); // 自定义处理函数 });

✅ 显示波形图

利用Web Audio API创建可视化反馈：

const audioContext = new AudioContext(); const source = audioContext.createMediaStreamSource(mediaStream); const analyser = audioContext.createAnalyser(); source.connect(analyser); // 定期读取 frequencyData 绘制 canvas 波形

✅ 添加热词提升准确率

针对特定场景注入关键词，显著改善专有名词识别：

formData.append('hotwords', '钉钉 通义 FunASR 杭州');

✅ 批量处理多个文件

构造多文件上传表单，循环调用 API 实现批量转写：

for (const file of fileList) { const formData = new FormData(); formData.append('audio', file); const res = await fetch(FUN_ASR_API, { method: 'POST', body: formData }); const result = await res.json(); results.push(result); }