录音导入与语音质检
从网页或服务端上传原始录音,跟踪文件识别、确认说话人并执行可核验的质检。
接入流程
- 上传原音
创建任务并分块上传,保留私有原音。
- 异步转写
校验真实时长后提交百炼文件识别;持久化供应商任务号。
- 确认角色
声道和说话人编号先作为未知身份,人工映射客户、坐席或AI。
- 分析与复核
选择已发布分析方案,查看逐字证据、字段、风险、评分及人工复核。
准备条件
- 平台为企业开通洞察;网页操作者须为具备服务与报表权限的企业管理员。API还需开放平台权限,并给密钥明确授权对应insights.audio操作。
- 管理员在「语音引擎 → 洞察 ASR」独立配置百炼北京密钥、文件识别模型和企业授权,不必配置或修改语音智能体。也可在录音上传时明确选择复用已授权的语音 ASR。仅一个独立资源时优先使用;多个独立资源须明确选择。旧 cn 语音资源按北京处理。
- 文件识别使用语音分钟额度,提交前预留、识别成功后按已验证文件时长向上取整分钟结算;文本模型分析另走已有模型计费。
- 在洞察设置中选择当前企业可用的分析模型;本地规则检查也可运行,但不能视为模型语义质检。
文件与容量
支持WAV、MP3、M4A、AAC、FLAC、OGG和WebM,单文件100MB、单/双声道、最长2小时;逐次上传1MiB分块。非标准PCM WAV需要服务端ffprobe解码校验(macOS本地预览可使用系统afinfo);工具缺失或解码失败时明确拒绝,不假装识别成功。
每个企业最多300个尚未清理原音的录音任务、声明原音总量2GiB;列表只加载最近100个任务,原音不写入会话JSON或公开目录。原音清理后释放相应上传容量,任务、转写、质检和复核记录独立保留。
单会话语义质检最多1000段、6万字。大文件识别超过此范围保留失败状态,不能截断后伪装完整质检。
原始音频保留时间
- 进入洞察 → 配置管理 → 工作区设置,由企业管理员设置原始音频保留期。默认365天,支持1–3650天,例如5天。API上传也遵循上传时的企业策略。
- 默认只影响之后上传的录音;每个任务保存当时的保留期和到期时间,后续改设置不会自动修改已有录音。期限以任务创建(开始上传)时间计算,不以录音发生时间计算。
- 需要调整已有录音时,单独勾选历史范围,先查看影响数量、将立即到期的数量与容量,再明确确认。配置或任务变化会拒绝旧预览,重新核对后再保存。已到期或已清理原音不能通过延长期限恢复。
- 到期立即停止回听、上传续传和新识别/重试,原音访问返回410。已有供应商识别任务可查回已经产生的转写,不重新提交。后台维护按索引分批清理平台保存的原始音频,不把大量清理放进页面请求。
- 保留转写、纪要、质检、复核及费用核对记录;原音到期后显示明确状态。此设置不承诺删除供应商侧副本,也不等于删除原始业务渠道自身保留的录音。
API操作与状态
| 操作 | 方法及路径 | 用途 |
|---|---|---|
| 创建任务 | POST /v1/operations/insights.audio.create | requestId、filename、bytes、source、startedAt、channels、asrResourceId、asrModel |
| 上传分块 | POST /v1/operations/insights.audio.chunk | jobId、从0开始的index、纯Base64 data;同序号同内容可重放 |
| 完成上传 | POST /v1/operations/insights.audio.complete | jobId;校验完整分块、格式和时长,随后异步处理 |
| 查询任务 | GET /v1/operations/insights.audio.read?jobId=任务ID | 查询任务、conversation的转写/质检结果/复核及说话人片段;不传jobId返回最近任务 |
| 推进/接续 | POST /v1/operations/insights.audio.advance | jobId;服务重启或浏览器关闭后可接续已有供应商任务 |
| 确认角色 | POST /v1/operations/insights.audio.roles | jobId、当前会话revision、roles对象;使用返回的speaker键 |
| 执行质检 | POST /v1/operations/insights.audio.analyze | jobId、会话revision、requestId、engine=model或local、planMode=bound或latest |
| 人工复核 | POST /v1/operations/insights.audio.review | jobId、revision、score(0–100)、reason(1–3000字依据);不覆盖模型原结论 |
| 明确重试 | POST /v1/operations/insights.audio.retry | jobId、confirmProviderRetry=true;可补asrResourceId/asrModel,先核对供应商任务和费用 |
状态与恢复
uploading表示原音未传完;queued表示已保存待识别;submitting表示可能已调用供应商;recognizing表示已保存供应商任务号;transcribed表示已转写待角色与质检;completed表示当前会话已有未过期分析。
failed不代表业务质检不合格,通常是配置/识别未完成。uncertain表示提交结果未知,必须先核对供应商控制台和费用,再明确重试;禁止自动重复提交。明确未提交/供应商明确失败释放预留,未知结果保留待核对;再次提交使用新的预留凭证,原未知预留会在任务中显示,不自动冒充退款。分析失败仍保留原音及转写,可以在同一会话重新分析或恢复已有模型回执。
当前音频只作为证据回放与ASR输入。语义模型只接收转写,不把文字推断成音量、噪声、静音或抢话的声学测量;这些信息需结合原音人工核查。
可下载的上传示例
本节下方及下载中心提供标准库Python导入示例(insights-audio-import.py)下载。密钥从环境变量读取,不写入源码。
所有写请求需要8–100位Idempotency-Key。每个分块保持稳定key;advance每次使用新key,否则网关会重放旧状态。相同requestId不能对应不同文件元数据。
运行前
run-import.sh · 命令文件
- 先下载 insights-audio-import.py,与本脚本放在同一目录。
- 设置脚本列出的环境变量;时间、声道和文件必须对应自己的已授权录音。
完整代码 · 10 行
#!/bin/sh
# Copy beside insights-audio-import.py; set all values for your own authorized recording.
set -eu
: "${YUNFU_BASE_URL:?Set the service HTTPS origin}" "${YUNFU_API_KEY:?Set the server API key}"
: "${YUNFU_RECORDING_STARTED_AT:?Set the actual recording timestamp with timezone}"
: "${YUNFU_AUDIO_PATH:?Set the recording file}" "${YUNFU_ASR_RESOURCE_ID:?Set the authorized ASR resource}"
: "${YUNFU_CHANNELS:?Set the actual channel count}" "${YUNFU_REQUEST_ID:?Retain one stable ID for this import}"
python3 ./insights-audio-import.py "$YUNFU_AUDIO_PATH" --origin "$YUNFU_BASE_URL" \
--resource "$YUNFU_ASR_RESOURCE_ID" --channels "$YUNFU_CHANNELS" \
--request-id "$YUNFU_REQUEST_ID" --wait 600使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
先下载 insights-audio-import.py,与本脚本放在同一目录。 设置脚本列出的环境变量;时间、声道和文件必须对应自己的已授权录音。
- 在项目中使用
run-import.sh · 命令文件
- 核对结果
执行会上传录音并等待状态;未知结果沿用原 requestId 核对,不重新创建导入。
预期结果:执行会上传录音并等待状态;未知结果沿用原 requestId 核对,不重新创建导入。
验收与错误处理
- 上传一个自有、已获授权的短录音;核对bytes、声道及真实时长,确认跨企业jobId返回404。
- 等待transcribed后,按原音确认说话人角色;unknown不会自动变为客户或坐席,未确认不能执行质检。
- 核对质检采用的方案/模型、原话证据、字段缺失和规则unknown;模型成功不代表服务已解决。
- 人工复核保留说明及历史,再按原有整改任务跟进。400/413为输入问题,402为额度,403为开通/权限,409为版本冲突,422为配置/解码,429为并发限制。
实现依据 · 仓库内路径
backend/services/insights/insights-audio-service.tsbackend/services/insights/insights-audio-provider.tsbackend/services/insights/insights-audio-retention.tsdatabase/stores/insights-audio-retention-store.tsapp/api/insights-audio/route.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。