web-index/doubao-asr-demo/README.md

豆包语音转写演示

本项目提供一个简单的前端页面用于上传音频并调用豆包语音转写接口（submit/get_result），同时包含一个 Node.js 代理服务，避免在前端暴露 API Key 与跨域问题。

项目结构

doubao-asr-demo/
├── index.html          # 前端页面入口
├── main.js             # 前端逻辑
├── styles.css          # 页面样式
├── server/
│   └── index.js        # Node 代理服务（Express）
├── .env.example        # 代理环境变量示例
├── package.json
└── package-lock.json

快速启动

1. 克隆或下载项目后进入目录

cd doubao-asr-demo

2. 安装依赖

npm install

3. 准备环境变量

复制 .env.example 为 .env，填入豆包平台申请的密钥：

cp .env.example .env
# 编辑 .env，至少配置 DOU_BAO_API_KEY

主要变量说明：

• DOU_BAO_API_KEY：豆包开放平台生成的 API Key（必填）
• DOU_BAO_RESOURCE_ID：资源 ID，默认 volc.bigasr.auc
• DOU_BAO_SUBMIT_URL 与 DOU_BAO_RESULT_URL：如无特殊需求保持默认
• PORT：代理服务监听端口，默认 5174

4. 启动代理服务

npm run dev

代理启动后默认监听 http://localhost:5174。

5. 启动静态资源服务

使用任意方式托管静态页面（如 VS Code Live Server、python -m http.server 等），或将页面放入任意静态网站服务器。必须保证页面能访问到代理服务 http://localhost:5174。

示例：

python3 -m http.server 4173

然后在浏览器访问 http://localhost:4173/index.html。

使用方法

1. 在页面选择音频文件，填写必要参数。
2. 如果本地代理已启动且地址为默认值，可将“API 基础地址”留空，前端会自动调用代理接口 /api/asr/...。
3. 若需要直连豆包官方接口，在“API 基础地址”输入官方地址，并确保浏览器环境允许该接口的 CORS（通常不可行）。此时必须在页面中填写 X-Api-Key，否则会提示错误。
4. 点击“提交识别任务”，页面会先提交任务，再自动轮询结果并展示转写文本，同时在“调试日志”中输出详细日志。

注意事项

• 前端直接调用官方接口会暴露密钥且受 CORS 限制，强烈建议通过本项目提供的代理转发。
• 代理只作为演示用途，生产环境请增加鉴权、限流、日志、安全审计等措施。
• 上传音频大小受限于前端与代理的请求体限制（默认 12 MB），可根据实际需要调整。
• 如果豆包接口返回的字段结构与示例不同，请在 main.js 中调整 extractTranscript 解析逻辑。

常见问题

• Failed to fetch：通常因为前端直连被 CORS 拒绝或未启动代理，请使用代理方式或检查网络。
• 服务器未配置 DOU_BAO_API_KEY：请确认 .env 已设置该变量，并在启动代理前加载。
• 轮询超时：可根据实际需求增加 maxAttempts 或 pollIntervalMs，同时检查豆包接口是否正常返回。