二次开发指南：基于CAM++ WebUI扩展自定义功能

1. 引言：为什么需要二次开发？

你已经成功部署了CAM++ 说话人识别系统，并能通过 WebUI 完成语音验证和特征提取。但如果你希望将这套能力集成到自己的项目中——比如做一个企业级身份核验平台、智能客服声纹比对模块，或者批量处理上千条录音文件，原生界面的功能就显得不够用了。

这时候，二次开发就成了关键一步。

本文将带你深入 CAM++ 的 WebUI 架构，手把手教你如何在不破坏原有功能的前提下，安全地扩展出属于你自己的定制化功能。无论你是想添加新页面、新增 API 接口，还是对接数据库保存 Embedding 向量，都能在这篇文章里找到实现路径。

你能学到什么？

理解 CAM++ WebUI 的技术结构与运行机制
如何安全修改前端界面并添加新功能按钮
扩展后端逻辑以支持自定义任务（如批量比对、结果导出）
实现一个完整的“声纹入库”功能示例
避免常见坑点：版权保留、路径冲突、依赖缺失

提示：本文假设你已成功运行镜像，并熟悉基础操作。若尚未启动，请先执行/bin/bash /root/run.sh。

2. 系统架构解析：WebUI 是怎么工作的？

要进行二次开发，必须先搞清楚 CAM++ WebUI 的整体架构。它并不是一个复杂的工程，而是典型的“前后端一体化”Gradio 应用，结构清晰、易于修改。

2.1 整体架构图

用户浏览器 ↓ (HTTP 请求) Gradio 前端界面 ←→ Python 后端逻辑 ↓ 模型推理引擎 (CAM++) ↓ 输出结果 → 显示 + 保存至 outputs/

2.2 核心目录结构

进入容器后，关键路径如下：

/root/speech_campplus_sv_zh-cn_16k/ ├── app.py # 主程序入口，Gradio UI 定义在这里 ├── inference.py # 模型推理核心代码 ├── scripts/ │ └── start_app.sh # 启动脚本 ├── models/ # 存放预训练模型文件 ├── outputs/ # 输出结果目录（每次生成带时间戳的子目录） └── static/ # 可选静态资源（图标、CSS等）

其中最值得关注的是app.py，它是整个 WebUI 的心脏。

2.3 Gradio 工作原理简析

CAM++ 使用 Gradio 构建交互式界面，其特点是：

用 Python 函数直接绑定 UI 组件
自动封装为 Web 页面
支持上传、录音、滑块、按钮等控件

例如，在app.py中你会看到类似这样的代码片段：

with gr.Tab("说话人验证"): with gr.Row(): audio1 = gr.Audio(label="参考音频", type="filepath") audio2 = gr.Audio(label="待验证音频", type="filepath") threshold = gr.Slider(0.1, 0.9, value=0.31, label="相似度阈值") btn_verify = gr.Button("开始验证") output_text = gr.Textbox(label="结果") btn_verify.click(fn=verify_speakers, inputs=[audio1, audio2, threshold], outputs=output_text)

这段代码定义了一个标签页、两段音频输入、一个滑动条、一个按钮和一个文本框，并通过.click()将点击事件绑定到verify_speakers函数上。

这意味着：只要我们能写一个 Python 函数，就可以把它挂到界面上变成新功能！

3. 修改前准备：环境检查与备份策略

在动手之前，务必做好准备工作，避免改坏原功能或丢失数据。

3.1 查看当前运行状态

确认服务正在运行：

ps aux | grep python

你应该能看到类似：

python app.py --server_port 7860

3.2 备份原始文件

强烈建议在修改前备份主程序：

cp /root/speech_campplus_sv_zh-cn_16k/app.py /root/app.py.bak

万一改出问题，可以直接恢复：

cp /root/app.py.bak /root/speech_campplus_sv_zh-cn_16k/app.py

3.3 开发工具推荐

你可以使用以下任意方式编辑文件：

容器内命令行：nano或vim
挂载宿主机目录：通过-v参数映射本地文件夹
VS Code Remote SSH 插件连接服务器

推荐使用后者，体验最佳。

4. 功能扩展实战：添加“声纹入库”功能

现在我们来做一个真实场景的扩展：将提取的 Embedding 向量存入数据库，构建企业级声纹库。

这个功能在安防、金融、客服等领域非常实用。比如银行可以通过声纹确认客户身份，无需密码。

4.1 功能设计目标

我们要实现：

新增一个“声纹入库”标签页
用户上传音频 + 输入姓名/ID
提取 Embedding 并保存到 SQLite 数据库
支持查看已有声纹列表

4.2 创建数据库

首先创建一个简单的数据库用于存储声纹信息：

cd /root/speech_campplus_sv_zh-cn_16k sqlite3 speaker_db.sqlite

执行建表语句：

CREATE TABLE speakers ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE, embedding BLOB NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP );

退出数据库：.quit

4.3 修改 app.py：添加新 Tab

打开/root/speech_campplus_sv_zh-cn_16k/app.py，找到with gr.Blocks() as demo:区域，在最后添加一个新的 Tab：

import sqlite3 import numpy as np import os def save_embedding_to_db(name, emb): # 将 numpy array 转为 bytes 存储 emb_bytes = emb.tobytes() conn = sqlite3.connect('speaker_db.sqlite') cursor = conn.cursor() try: cursor.execute("INSERT OR REPLACE INTO speakers (name, embedding) VALUES (?, ?)", (name, emb_bytes)) conn.commit() return f"✅ 声纹已保存：{name}" except Exception as e: return f"❌ 错误：{str(e)}" finally: conn.close() def list_speakers(): conn = sqlite3.connect('speaker_db.sqlite') cursor = conn.cursor() cursor.execute("SELECT name, created_at FROM speakers ORDER BY created_at DESC") rows = cursor.fetchall() conn.close() if not rows: return "暂无声纹记录" return "\n".join([f"{row[0]} ({row[1]})" for row in rows]) with gr.Tab("声纹入库"): gr.Markdown("## 录入新说话人声纹") with gr.Row(): spk_name = gr.Textbox(label="请输入姓名或ID") spk_audio = gr.Audio(label="上传语音（3-10秒）", type="filepath") db_save_btn = gr.Button("提取并入库") db_result = gr.Textbox(label="操作结果") db_save_btn.click( fn=lambda name, audio: save_embedding_to_db(name, extract_embedding(audio)), inputs=[spk_name, spk_audio], outputs=db_result ) gr.Markdown("## 当前声纹库列表") refresh_btn = gr.Button("刷新列表") speaker_list = gr.Textbox(label="已录入人员") refresh_btn.click(fn=list_speakers, inputs=None, outputs=speaker_list)

⚠️ 注意：上面的extract_embedding(audio)需确保你在inference.py中已暴露该函数。如果未暴露，请从原逻辑中复制或导入。

4.4 补充依赖（如有需要）

虽然 CAM++ 已包含 NumPy 和 PyTorch，但 SQLite 是标准库，无需安装。

4.5 重启服务测试

保存app.py后，重启应用：

cd /root/speech_campplus_sv_zh-cn_16k bash scripts/start_app.sh

访问http://localhost:7860，你会看到多了一个“声纹入库”标签页！

尝试上传一段音频并输入名字，点击“提取并入库”，应显示“✅ 声纹已保存”。

刷新列表，即可看到刚录入的人员。

5. 更进一步：实现“声纹比对”功能

有了声纹库，下一步自然是要做“比对”——判断某段语音是否属于某个已知用户。

5.1 功能逻辑

用户选择一个已注册的名字
上传一段待验证语音
系统从数据库加载该用户的 Embedding
计算余弦相似度
返回匹配结果

5.2 添加“声纹比对”Tab

继续在app.py中追加：

def get_embedding_by_name(name): conn = sqlite3.connect('speaker_db.sqlite') cursor = conn.cursor() cursor.execute("SELECT embedding FROM speakers WHERE name=?", (name,)) row = cursor.fetchone() conn.close() if row: return np.frombuffer(row[0], dtype=np.float32) return None def verify_against_db(name, audio_path): if not name or not audio_path: return "请填写姓名并上传音频" db_emb = get_embedding_by_name(name) if db_emb is None: return f"❌ 未找到 {name} 的声纹记录" current_emb = extract_embedding(audio_path) similarity = cosine_similarity(db_emb, current_emb) if similarity > 0.6: return f"✅ 匹配成功！相似度：{similarity:.4f}（阈值0.6）" else: return f"❌ 不匹配。相似度：{similarity:.4f}" with gr.Tab("声纹比对"): gr.Markdown("## 对比语音是否属于指定人员") with gr.Row(): select_name = gr.Dropdown(choices=get_all_names(), label="选择已注册人员") test_audio = gr.Audio(label="上传待测语音", type="filepath") verify_db_btn = gr.Button("开始比对") verify_result = gr.Textbox(label="比对结果") verify_db_btn.click( fn=verify_against_db, inputs=[select_name, test_audio], outputs=verify_result )