本文是系列教程的主篇。按顺序做完,你会得到一套能真实打通的呼叫中心:来电先由 AI 客服接听,支持边说边打断;客户要求人工时,AI 把电话转进排队系统,由坐席接听。
文章刻意写得很细:每条命令、每个配置项、每行关键代码都会解释为什么这么写。中途卡住时,先看第 14 章 排障手册。
目录
- 0. 你将得到什么
- 1. 架构:一通电话是怎么走完的
- 2. 准备服务器
- 3. 部署 FreeSWITCH(Docker 推荐 / 源码编译)
- 4. 安全基线:先改掉所有默认口令
- 5. 注册软电话,打通第一通电话
- 6. 获取配套代码,准备 Python 环境
- 7. 第一次推流:用回声后端验证媒体通路
- 8. 开通阿里云百炼,单独验证 ASR / TTS / LLM
- 9. AI 机器人:代码逐段讲解
- 10. 控制面:用 FCC 接管来电
- 11. 人工坐席与排队
- 12. 全链路联调
- 13. 打断(Barge-in)的原理与调参
- 14. 排障手册
- 15. 上生产前要做的事
- 16. 后续系列
- 附录 A:命令速查
- 附录 B:mod_taering_stream 媒体协议速查
- 附录 C:文件清单
0. 你将得到什么
做完本文,你可以用一部软电话拨打 4000,体验下面这段对话:
AI :您好,这里是智能客服小安,请问有什么可以帮您?
你 :你们的宽带有哪些套餐?
AI :我们有 100M 每月 59 元、300M 每月 89 元和 1000M 每月 129 元三种套餐,您想了解哪一种?
你 :300M 的话多久能装—— ← 你中途插话,AI 立刻停下来听你说
AI :预约后 48 小时内会有师傅上门安装。
你 :我要投诉,给我转人工。
AI :好的,马上为您转接人工客服。
(排队音乐响起,坐席分机振铃,坐席接听,人工通话开始)整套系统由四个部分组成:
| 组件 | 做什么 | 来源 |
|---|---|---|
| FreeSWITCH 1.10.12 | 电话交换:SIP 注册、呼叫路由、RTP 媒体、排队(mod_callcenter) | freeswitch-docker(https://github.com/taering365/freeswitch-docker) 离线镜像 |
| mod_fcc | 通话控制面:用 HTTP/WebSocket 接管来电、转接、管理坐席、推送事件 | mod_fcc(https://github.com/taering365/mod_fcc)(MIT 开源,镜像内置) |
| mod_taering_stream | AI 媒体面:把通话音频实时推给 AI 后端,再把 AI 的声音注入通话,支持打断 | freeswitch_stream_mod(https://github.com/taering365/freeswitch_stream_mod)(商业模块,镜像内置,试用版 1 路并发) |
| AI 后端 | 实时识别(ASR)、大模型(LLM)、语音合成(TTS) | 本文配套代码 + 阿里云百炼 |
适合谁读
- 懂一点 Linux 和 Python,但没碰过 FreeSWITCH 的 AI 应用开发者;
- 熟悉 FreeSWITCH,但没做过实时语音 AI 的 VoIP 工程师;
- 想快速评估"AI 客服 + 人工兜底"方案可行性的技术负责人。
你需要准备
| 项目 | 要求 |
|---|---|
| 一台 Linux 服务器 | x86_64,2 核 4G 起步,Debian 12 / Ubuntu 22.04+ / CentOS Stream 9+ 均可 |
| 两部软电话 | 一部当"客户",一部当"坐席"。可以是两台电脑,也可以一台电脑 + 一部手机 |
| 阿里云账号 | 用于开通百炼,获取 API Key |
| freeswitch-docker 离线包 | freeswitch-1.10.12-fcc1.2.1-taering0.55-offline-bundle.tar.gz,下载地址见第 3 章 |
| 配套代码 | ai-callcenter-demo.zip,下载地址见第 6 章 |
| 时间 | 第一次完整走通约 1~2 小时 |
1. 架构:一通电话是怎么走完的
1.1 组件关系
┌─────────────────────────── 服务器(Docker host 网络)──────────────────────────┐
│ │
客户软电话 1001 ──SIP/RTP──► FreeSWITCH │
│ ├─ 拨号计划 4000 ─ fcc_inbound ──────────┐ │
│ ├─ 拨号计划 8000 ─ taering_stream start ─┼──► ws://127.0.0.1:9000 │
│ ├─ 拨号计划 7000 ─ callcenter 排队 │ AI 机器人 bot/server.py │
│ │ │ ├─► 百炼 Paraformer ASR │
│ ├─ mod_fcc ── HTTP/WS 127.0.0.1:18080 ◄───┤ ├─► 通义千问 LLM │
│ │ │ └─► 百炼 CosyVoice TTS │
│ └─ mod_callcenter ── 呼叫坐席 ──┐ │ │
│ │ 控制面 controller.py ◄── FCC 事件 │
坐席软电话 1002 ◄─────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘记住一句话:FCC 管"电话往哪走",mod_taering_stream 管"声音怎么进出 AI"。两者互不重叠:
- FCC 不处理音频。它把接听、转接、挂机、坐席签入这些控制动作封装成 HTTP 接口,并把通话状态变化推送成 WebSocket 事件。
- mod_taering_stream 不做呼叫控制。它只负责在一通已经存在的通话上挂一个"媒体钩子",把音频双向桥接到 WebSocket。
1.2 一通电话的完整时序
客户1001 FreeSWITCH FCC controller.py AI 机器人 百炼 坐席1002
│ 拨 4000 │ │ │ │ │ │
├───────────────►│ fcc_inbound │ │ │ │ │
│ ├───────────────────►│ call.incoming ─────►│ │ │ │
│ │ park(等待决策) │ │ 决策:去 AI │ │ │
│ │◄──── transfer 8000 ┤◄── POST /transfer ──┤ │ │ │
│ │ answer │ │ │
│ │ taering_stream start ──── WebSocket 连接 + start 帧 ─────►│ │ │
│◄═══ 欢迎语 ════╡◄══════════════════ PCM(TTS) ═════════════════════════════╡◄══ CosyVoice ═╡ │
╞═══ 客户说话 ══►│════════════════════ PCM(上行)════════════════════════════►│══ Paraformer ►│ │
│ │ │◄── 识别文字 ──┤ │
│ │ │── 通义千问 ──►│ │
│◄═══ AI 回答 ═══╡◄══════════════════ PCM(TTS) ═════════════════════════════╡◄══ CosyVoice ═╡ │
│ "转人工" │ │ LLM 输出 [转人工] │
│ │◄──────── transfer 7000 ──── POST /calls/{uuid}/transfer ───┤ │ │
│ │ taering_stream stop ─────────────── stop 帧,连接关闭 ────►│ │ │
│ │ callcenter support@default │ │
│◄═══ 排队音乐 ══╡──────────────────────────── 呼叫坐席 ────────────────────────────────────────────────────►│
│ │ │ queue.agent_offered / queue.bridged ──► controller 打印 │
╞════════════════╪═══════════════════════════ 人工通话 ════════════════════════════════════════════════════════╡为什么入口 4000 不直接接 AI,而要先绕一圈 FCC?
- 业务决策点:真实业务里,来电要先查黑名单、判断营业时间、识别 VIP,再决定去 AI 还是直接转人工。这些逻辑应该写在你的后端里,而不是写死在 XML 里。
- 全程可观测:通话一旦被
fcc_inbound注册,后续的应答、转接、排队、坐席接听、挂机都会作为事件推送给你,并关联到同一个call_id。 - AI 能"动手":AI 机器人拿着通话的 uuid 调用 FCC 的转接接口,就能把电话送去人工,不需要碰 ESL。
1.3 端口一览
| 端口 | 谁监听 | 对外开放? |
|---|---|---|
| 5060 TCP/UDP | FreeSWITCH internal profile(软电话注册) | 只对你的软电话所在网络开放 |
| 5080 TCP/UDP | FreeSWITCH external profile(运营商线路) | 本文不用 |
| 16384–32768 UDP | RTP 媒体 | 与 5060 同样的范围开放 |
| 8021 TCP | Event Socket(fs_cli) | 不开放,默认只监听 127.0.0.1 |
| 18080 TCP | FCC HTTP/WS | 不开放,默认只监听 127.0.0.1 |
| 9000 TCP | AI 机器人 | 不开放,只给本机 FreeSWITCH 连 |
2. 准备服务器
2.1 选哪种机器
- 局域网虚拟机或一台闲置 PC(最推荐第一次用):软电话和服务器在同一网段,没有 NAT 问题,最不容易出现"有一方听不到声音"。
- 云服务器:也可以,但必须额外处理公网 IP(见 4.3),并在安全组放行 SIP 和 RTP 端口。
- macOS / Windows 上的 Docker Desktop、WSL2:不要用。freeswitch-docker 使用 host 网络传输 SIP/RTP,这些环境下 host 网络的行为和 Linux 不同,而且镜像只提供 x86_64 版本,Apple Silicon(M 系列)跑不了。用 Mac 的读者请在 Mac 上跑一个 x86_64 Linux 虚拟机,或者直接用云服务器。
2.2 安装 Docker
以 Debian 12 / Ubuntu 为例(其他发行版见 freeswitch-docker 的 README):
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
. /etc/os-release
curl -fsSL https://download.docker.com/linux/$ID/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/$ID $VERSION_CODENAME stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker
docker compose version # 能看到 v2.x 即可国内服务器访问 download.docker.com 较慢时,可以把源换成阿里云镜像:
https://mirrors.aliyun.com/docker-ce/linux/$ID。
2.3 放行端口
以 ufw 为例,假设软电话所在网段是 192.168.1.0/24:
sudo ufw allow from 192.168.1.0/24 to any port 5060 proto udp
sudo ufw allow from 192.168.1.0/24 to any port 5060 proto tcp
sudo ufw allow from 192.168.1.0/24 to any port 16384:32768 proto udp云服务器还要在安全组里做同样的放行。不要放行 8021、18080、9000。
2.4 准备 Python
Debian 12 自带 Python 3.11,Ubuntu 22.04 自带 3.10,都满足要求:
sudo apt-get install -y python3 python3-venv python3-pip git
python3 --version # ≥ 3.103. 部署 FreeSWITCH
3.0 两种部署方式
| 方案 A:Docker 离线包(推荐) | 方案 B:源码编译 | |
|---|---|---|
| 做法 | 下载一个离线包,执行 ./start.sh |
自行编译 FreeSWITCH,再安装 mod_fcc 和 mod_taering_stream |
| 耗时 | 几分钟 | 数小时起,取决于对 FreeSWITCH 的熟悉程度 |
| 本文是否提供教程 | ✅ 后续所有步骤都基于此方案 | ❌ 不提供,仅给出参考资料 |
为什么推荐 Docker
- 不用编译:镜像是预编译好的,目标服务器不需要下载源码,也不需要装编译工具链。FreeSWITCH 的编译依赖多、耗时长,是新手最容易卡住的地方。
- 版本组合已验证:FreeSWITCH 1.10.12、mod_fcc、mod_taering_stream 以及 mod_callcenter 等呼叫中心模块打包在同一个镜像里,彼此兼容。自己编译时,版本、编译选项和系统库稍有不同,就可能出现模块加载失败或者行为不一致。
- 支持离线部署:整套环境是一个离线包,适合不能访问外网、或者访问 GitHub 很慢的内网服务器。
- 配置和程序分离:所有 XML 配置都放在宿主机的
conf/目录,升级时换一个镜像即可,配置不会被覆盖;数据库、日志、录音放在命名卷里,重建容器也不会丢。 - 环境一致:本文所有命令、路径和截图都基于这个镜像,照着做最不容易出偏差。
方案 B:源码编译(不提供教程)
适合已经有 FreeSWITCH 环境,或者需要自定义编译选项的读者。需要自行完成:
- 编译安装 FreeSWITCH 1.10.12,并确保加载 mod_callcenter、mod_event_socket 等模块;
- 编译安装 mod_fcc,步骤见其仓库 README:https://github.com/taering365/mod_fcc
- 安装 mod_taering_stream(以预编译
.so形式分发,要求 Debian 12 x86_64、FreeSWITCH 1.10.x,并安装 libwebsockets 和 OpenSSL 3.x),说明见:https://github.com/taering365/freeswitch_stream_mod
选方案 B 的读者,第 3 章之后的内容依然适用,只需要把文中的
fs命令换成本机的fs_cli -x,把$FS_HOME/conf换成你自己的 FreeSWITCH 配置目录。
3.1 方案 A:下载、解压并启动
离线包下载地址:
项目说明(GitHub):https://github.com/taering365/freeswitch-docker
在服务器上直接下载(服务器访问 GitHub 慢的话,可以先在电脑上下载,再用 scp 上传到服务器):
cd /opt
sudo wget "https://github.com/Taering365/freeswitch-docker/releases/download/v1.10.12-fcc1.2.1/freeswitch-1.10.12-fcc1.2.1-taering0.55-offline-bundle.tar.gz"
sudo tar -xzf freeswitch-1.10.12-fcc1.2.1-taering0.55-offline-bundle.tar.gz
ls # 找到解压出的目录
cd freeswitch-*/
ls # 应该能看到 compose.yaml、.env.example、start.sh、conf/、镜像 tar 包
sudo ./start.shstart.sh 会依次完成:加载镜像 tar 包、生成 .env 和 conf/、执行 docker compose up -d --no-build。之后重复执行它也安全:已有的容器会被重启,宿主机上的 XML 配置会保留。
本文后面用
$FS_HOME指代这个部署目录,也就是上面cd进去的那个目录。建议现在就设置好:export FS_HOME=$(pwd) echo "export FS_HOME=$FS_HOME" >> ~/.bashrc
3.2 确认容器在运行
cd $FS_HOME
sudo docker compose ps记下 NAME 列的容器名,后面会频繁用到。为了少打字,定义一个 fs 命令:
export FS_CONTAINER=<上面看到的容器名>
echo "export FS_CONTAINER=$FS_CONTAINER" >> ~/.bashrc
cat >> ~/.bashrc <<'EOF'
fs() { sudo docker exec -i "$FS_CONTAINER" /usr/local/freeswitch/bin/fs_cli -x "$*"; }
fscli(){ sudo docker exec -it "$FS_CONTAINER" /usr/local/freeswitch/bin/fs_cli; }
EOF
source ~/.bashrcfs <命令>:执行一条 FreeSWITCH 命令并返回结果,例如fs status;fscli:进入交互式控制台,能实时看日志,按Ctrl+D或输入/exit退出。
如果提示找不到
fs_cli,进容器用which fs_cli找到实际路径再替换。如果你按第 4 章改了 Event Socket 密码,要在命令里加上-p <密码>。
3.3 检查三个关键模块
fs status
fs module_exists mod_fcc # → true
fs module_exists mod_callcenter # → true
fs taering_stream version # → +OK module=taering_stream version=... barge_in=... license=enabled
fs taering_stream license # 查看授权状态关于授权:mod_taering_stream 首次启动时会联网校验授权。授权生效前状态显示为 pending,此时推流无法启动;授权生效后会自动激活,不需要重启。服务器必须能访问授权服务。试用版功能完整,但只允许 1 路并发推流,本文所有演示都在 1 路内完成。
商业授权(不限并发):联系作者 taering@vip.qq.com 购买,完成在线授权后即可使用,无并发限制。
3.4 认识配置目录
宿主机的 $FS_HOME/conf/ 映射到容器内的 /usr/local/freeswitch/etc/freeswitch。以后改配置都在宿主机上改,改完再让 FreeSWITCH 重新加载。
$FS_HOME/conf/
├── vars.xml 全局变量:默认密码、域名、公网 IP、编码偏好
├── autoload_configs/
│ ├── modules.conf.xml 开机加载哪些模块
│ ├── mod_fcc.conf.xml FCC 配置
│ ├── mod_taering_stream.conf.xml 推流模块配置
│ ├── callcenter.conf.xml 排队与坐席
│ ├── event_socket.conf.xml fs_cli / ESL
│ └── acl.conf.xml
├── directory/default/ SIP 用户(1000~1019)
├── dialplan/default/ 拨号计划
└── sip_profiles/ internal(5060) / external(5080)不同的修改需要不同的生效方式:
| 改了什么 | 怎么生效 |
|---|---|
| 拨号计划、用户目录、callcenter 队列以外的大多数 XML | fs reloadxml |
mod_fcc.conf.xml |
fs reload mod_fcc |
mod_taering_stream.conf.xml |
fs reload mod_taering_stream(会断开当前所有推流;只执行 reloadxml 不会生效) |
callcenter.conf.xml 里新增队列 |
fs reloadxml 后执行 fs callcenter_config queue load <队列名> |
vars.xml、SIP 监听端口、TLS |
sudo docker compose restart |
4. 安全基线:先改掉所有默认口令
只要 SIP 端口暴露在公网上,几分钟内就会有扫描器来尝试注册分机、盗打国际长途。不要跳过这一章。
4.1 SIP 分机默认密码
cd $FS_HOME
grep -n 'default_password' conf/vars.xml把 default_password 的值从 1234 改成一个强密码:
<X-PRE-PROCESS cmd="set" data="default_password=Your-Strong-Pass-2026"/>然后执行 sudo docker compose restart。所有分机(1000~1019)都会改用这个新密码。
4.2 FCC Token
生成一个随机 Token:
openssl rand -hex 32编辑 conf/autoload_configs/mod_fcc.conf.xml:
<param name="api_token" value="上一步生成的随机串"/>fs reload mod_fcc
curl -sS -H "Authorization: Bearer 上一步生成的随机串" http://127.0.0.1:18080/api/v1/health
# {"code":"OK","data":{"status":"ok","module":"mod_fcc","version":"1.2.1-open",...}}这个 Token 后面要填到配套代码的 .env 文件里。
FCC 对鉴权失败有保护:同一个 IP 在 60 秒内失败 5 次,会被锁定 300 秒,期间返回 HTTP 429
AUTH_LOCKED。测试时如果 Token 填错几次,等 5 分钟就会恢复。
4.3 Event Socket
确认 conf/autoload_configs/event_socket.conf.xml 中 listen-ip 是 127.0.0.1,并把 password 从默认的 ClueCon 改掉。改完后,fs 命令需要带上 -p <新密码>,可以修改 ~/.bashrc 里的函数定义。
4.4 云服务器:设置公网 IP
云服务器的网卡上只有内网 IP。如果不告诉 FreeSWITCH 公网 IP,它会把内网 IP 写进 SDP,结果就是通话接通了,但一方或双方听不到声音。
编辑 conf/vars.xml,把 stun 那两行改成你的公网 IP:
<X-PRE-PROCESS cmd="set" data="external_rtp_ip=1.2.3.4"/>
<X-PRE-PROCESS cmd="set" data="external_sip_ip=1.2.3.4"/>然后执行 sudo docker compose restart。局域网部署不用改这一项。
5. 注册软电话,打通第一通电话
5.1 选软电话
| 平台 | 推荐 |
|---|---|
| Windows | MicroSIP:https://www.microsip.org |
| macOS / Linux / Windows | Linphone:https://www.linphone.org;Zoiper:https://www.zoiper.com |
| Android / iOS | 应用商店搜索 Linphone 或 Zoiper |
5.2 注册两个分机
本文约定:1001 当客户,1002 当坐席。
| 字段 | 1001(客户) | 1002(坐席) |
|---|---|---|
| 用户名 / 分机号 | 1001 |
1002 |
| 密码 | 4.1 设置的 default_password |
同左 |
| 域名 / 服务器 | 服务器 IP | 服务器 IP |
| 端口 / 传输 | 5060 / UDP | 5060 / UDP |
在服务器上确认两个分机都已注册:
fs show registrations
# 能看到 1001 和 1002 两行5.3 第一通电话
- 用 1001 拨打 9196:这是 FreeSWITCH 自带的回声测试,你说什么就会听到什么。能听到自己的声音,就说明 SIP 和 RTP 都通了。
- 用 1001 拨打 1002:1002 振铃,接起来后两边能互相听到。
这一步不通,后面就都不用做了,先看排障手册里"听不到声音"的部分。
5.4 编码与采样率(后面会用到)
fs show channels 能看到每路通话的编码(read_codec)。不同编码对应的采样率如下,这个采样率会直接成为推流的采样率:
| 编码 | 采样率 | 对 AI 的影响 |
|---|---|---|
| PCMA / PCMU(G.711) | 8000 Hz | 运营商线路最常见,识别效果尚可 |
| G722 | 16000 Hz | 推荐用于测试:宽带音质,识别更准 |
| OPUS | 48000 Hz | 可用,但带宽和计算量更大 |
建议在软电话的编码设置里把 G722 排到第一位。配套代码会自动按实际采样率工作,三种编码都能用。
6. 获取配套代码,准备 Python 环境
配套代码打包为 ai-callcenter-demo.zip,下载地址:https://www.liaoxinghui.com/upload/ai-callcenter-demo.zip
cd /opt
sudo wget -O ai-callcenter-demo.zip "https://www.liaoxinghui.com/upload/ai-callcenter-demo.zip" # 或在电脑上下载后用 scp 上传
sudo apt-get install -y unzip
sudo unzip ai-callcenter-demo.zip
sudo chown -R $USER ai-callcenter-demo
cd ai-callcenter-demo
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt # 只有 websockets 和 httpx 两个依赖
cp .env.example .env先编辑 .env,填入 FCC Token(百炼 Key 留到第 8 章再填):
FCC_API_TOKEN=第4.2节生成的随机串目录结构:
ai-callcenter-demo/
├── config.py 所有配置,从 .env 读取
├── controller.py 控制面:消费 FCC 事件,决定来电去向
├── bot/ AI 机器人
│ ├── server.py mod_taering_stream 的 WebSocket 后端(主程序)
│ ├── asr.py 百炼 Paraformer 实时识别
│ ├── tts.py 百炼 CosyVoice 流式合成
│ ├── llm.py 通义千问流式对话
│ ├── player.py 下行音频:帧对齐 + 实时节奏 + 打断
│ └── fcc.py FCC HTTP 封装
├── tools/
│ ├── echo_server.py 回声后端
│ ├── check_dashscope.py
│ └── setup_agent.py 创建并签入坐席
└── conf/ 要复制进 FreeSWITCH 的配置
├── dialplan/default/00_ai_callcenter.xml
├── autoload_configs/mod_taering_stream.conf.xml
└── apply-conf.sh以后每打开一个新终端,都要先
cd /opt/ai-callcenter-demo && source .venv/bin/activate。
7. 第一次推流:用回声后端验证媒体通路
接 AI 之前,先用一个最简单的后端验证"电话 → 模块 → 后端 → 模块 → 电话"这条双向通路。回声后端把收到的声音原样送回去,不依赖任何外部服务。这一步通了,后面出问题就可以排除 FreeSWITCH 和推流模块。
7.1 安装教程配置
cd /opt/ai-callcenter-demo
chmod +x conf/apply-conf.sh
./conf/apply-conf.sh $FS_HOME/conf $FS_CONTAINER脚本会先备份原文件,再复制两份配置,然后执行 reloadxml 和 reload mod_taering_stream。
先看推流模块的配置(conf/autoload_configs/mod_taering_stream.conf.xml),每一项都有它的原因:
<param name="default_ws_url" value="ws://127.0.0.1:9000/stream"/>后端地址。容器使用 host 网络,所以容器里的 FreeSWITCH 访问 127.0.0.1:9000,就是访问宿主机上的 Python 程序。
<param name="default_mix_type" value="mono"/>推哪些声音。三种取值:
mono:只推来电者的声音,最适合 ASR,因为识别结果里不会混进机器人自己的声音;mixed:两边混成一路;stereo:左声道是来电者,右声道是对方,适合质检时区分说话人。
<param name="default_sample_rate" value="16000"/>期望的采样率。实际采样率以通话编码为准(见 5.4),模块不做重采样。后端必须读取 start 帧里的 sample_rate,不能自己假设。
<param name="enable_barge_in" value="true"/>允许后端发送 {"type":"clear"} 清空播放队列,这是实现打断的前提。
<param name="packet_ms" value="20"/>
<param name="rx_buffer_ms" value="1000"/>这两项决定下行缓冲的大小,非常重要。模块的下行缓冲能装 rx_buffer_ms / packet_ms 帧,默认值是 80/20,也就是只有 4 帧、80 毫秒。后端如果一次性把几秒的 TTS 音频全塞过去,缓冲会溢出,模块会丢弃最旧的帧,听起来就是"吞字"。配套代码会按实时节奏发送,最多领先 200ms,所以这里把缓冲放大到 1000ms,留出足够的余量应对网络抖动。
再看回声测试的拨号计划(00_ai_callcenter.xml 中的 9000):
<extension name="tutorial_echo_test">
<condition field="destination_number" expression="^9000$">
<action application="answer"/>
<action application="taering_stream" data="start - mono 16k"/>
<action application="log" data="INFO taering_stream_result=${taering_stream_result}"/>
<action application="park"/>
<action application="hangup"/>
</condition>
</extension>taering_stream start - mono 16k:参数依次是 URL、声道模式、采样率,-表示用 XML 里配置的默认值。这条命令会立即返回,WebSocket 连接在后台建立。taering_stream_result:启动结果。成功是+OK,失败是-ERR(常见原因是没配 URL,或授权未生效)。park:start立即返回后,必须让通道"停住",否则拨号计划会直接走到hangup。推流在后台持续进行;之后要转接或挂机,由 FCC(uuid_transfer/uuid_kill)打断park即可。
7.2 启动回声后端
python -m tools.echo_server
# INFO echo: echo backend on ws://127.0.0.1:90007.3 拨 9000
用 1001 拨打 9000,说几句话,应该能听到自己的声音,延迟大约几十到一两百毫秒。终端里会看到:
INFO echo: start frame: {'type': 'start', 'uuid': '5f1c...', 'stream_id': '...', 'external_id': '', 'sample_rate': 16000, 'mix_type': 'mono'}
INFO echo: first audio frame: 640 bytes (20 ms @ 16000 Hz)
...
INFO echo: call 5f1c... ended, 512 frames echoed读懂这几行输出
- start 帧:每条连接建立后,模块发出的第一条文本消息,包含通话
uuid、stream_id、实际的sample_rate和mix_type。如果拨号计划里传了元数据,还会多一个metadata字段。 - 640 字节:PCM16LE 每个采样点占 2 字节,所以 16000 Hz × 2 字节 × 0.02 秒 = 640 字节。如果编码是 PCMA,这里会是 8000 × 2 × 0.02 = 320 字节。
- 结束:挂机时模块会直接关闭 WebSocket 连接;只有显式执行
taering_stream stop(或通过 API 停止)时,才会先发送一条type=stop的文本消息再关闭。所以后端要把"收到 stop"和"连接关闭"都当作通话结束来处理。
7.4 回声测试不通?
| 现象 | 检查 |
|---|---|
| 拨 9000 直接挂断 | fscli 看日志:taering_stream_result=-ERR 说明授权或 URL 有问题,执行 fs taering_stream license |
| 接通了但完全没声音,echo 终端没有任何输出 | 后端没启动,或者监听地址不是 127.0.0.1:9000 |
| echo 有输出,但听不到回声 | 执行 fs reload mod_taering_stream 确认配置已加载;fs taering_stream stats 看下行丢帧计数 |
| 回声断断续续 | 服务器 CPU 或网络繁忙;执行 fs taering_stream stats 查看丢帧计数 |
8. 开通阿里云百炼,单独验证 ASR / TTS / LLM
8.1 为什么选百炼
一个 API Key 能同时调用本文需要的三项服务,读者只需要注册一个平台:
| 能力 | 模型 | 接口 |
|---|---|---|
| 实时语音识别 | paraformer-realtime-v2(支持任意采样率,8k 和 16k 电话音频都能用) |
WebSocket |
| 流式语音合成 | cosyvoice-v3-flash,音色 longanyang |
WebSocket(与 ASR 同一个地址) |
| 大模型 | qwen-plus |
OpenAI 兼容 HTTP,流式 SSE |
想换成其他国内服务(讯飞、火山引擎、腾讯云、DeepSeek 等)?只需要替换
bot/asr.py、bot/tts.py、bot/llm.py这三个文件,接口约定见第 9 章。
8.2 获取 API Key
- 登录阿里云百炼控制台 https://bailian.console.aliyun.com(地域选华北2(北京));
- 开通服务;在模型广场确认 Paraformer、CosyVoice、通义千问可用;
- 在"API-KEY"页面创建一个 Key(形如
sk-xxxx)。
把 Key 填进 .env:
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx百炼正在推广"业务空间专属域名",形如
{WorkspaceId}.cn-beijing.maas.aliyuncs.com,官方说法是性能和稳定性更好;原来的dashscope.aliyuncs.com仍可正常使用。想切换的话,修改.env里的DASHSCOPE_WS_URL和DASHSCOPE_HTTP_BASE。
8.3 不打电话,先单独测试三项服务
python -m tools.check_dashscope[1/3] LLM qwen-plus ...
回复: 我是通义千问,阿里云研发的大语言模型。
[2/3] TTS cosyvoice-v3-flash / longanyang ...
合成 3.2 秒音频,已保存 tts_test.wav
[3/3] ASR paraformer-realtime-v2 ...
识别: 我是通义千问,阿里云研发的大语言模型。
全部完成。这个脚本的逻辑是:先让 LLM 生成一句话,再用 TTS 把它合成成音频,最后把这段音频按每 20 毫秒一帧送进 ASR,模拟电话上行的节奏。三步都成功,说明 Key、网络和模型权限都没问题。把 tts_test.wav 下载下来,还能听听音色。
| 报错 | 原因 |
|---|---|
| 握手失败,HTTP 401/403 | Key 填错,或者 Key 不属于北京地域 |
task-failed + Model not found / 无权限 |
该模型未开通 |
| LLM HTTP 400 | 模型名写错 |
| 识别结果为空 | 检查 tts_test.wav 是否有声音 |
9. AI 机器人:代码逐段讲解
这一章是全文的核心。代码不长,但每个设计都对应一个实际会踩的坑。
9.1 整体结构
一通电话对应一条 WebSocket 连接,对应一个 CallSession 对象:
┌──────────────────── CallSession(每通电话一个) ────────────────────┐
模块 ─PCM──► │ ws 收消息 ──► asr.send_audio ──► Paraformer │
│ │ │
│ on_partial(中间结果)── 机器人正在说话? → barge_in 打断 │
│ on_final(一句话说完)── reply() │
│ │ │
│ llm.stream_chat ──► 按标点切句 ──► tts.say ──► CosyVoice │
│ │ │
模块 ◄─PCM─ │ ◄── player(整帧 + 实时节奏) ◄── player.feed ◄── 音频分片 ┘ │
│ │
│ 回复里有 [转人工] → 等最后一句播完 → FCC transfer 7000 │
└─────────────────────────────────────────────────────────────────────────┘9.2 入口:处理 start 帧(bot/server.py)
async def handler(ws) -> None:
first = await asyncio.wait_for(ws.recv(), timeout=10)
start = json.loads(first)
if start.get("type") != "start":
return
session = CallSession(ws, start)
await session.run()class CallSession:
def __init__(self, ws, start: dict):
self.uuid = start["uuid"] # FreeSWITCH 通道 uuid,转接时要用
self.sample_rate = int(start["sample_rate"]) # 实际采样率,ASR/TTS 都按它来
self.metadata = start.get("metadata") or {} # 拨号计划传入的业务信息关键点:sample_rate 必须从 start 帧读取。拨号计划里写的 16k 只是"期望值",如果通话实际用的是 PCMA,这里就是 8000。ASR 的输入采样率和 TTS 的输出采样率都必须和它一致,否则声音会变调或者识别不出来。
主循环把上行音频交给 ASR。收到 stop,或者连接被关闭(挂机时模块直接关连接),循环都会结束,然后统一清理:
async def run(self) -> None:
greeting, prompt = await scenes.prepare(self.metadata) # 按场景选开场白和提示词(外呼见系列 3)
self.history[0] = {"role": "system", "content": prompt}
self.reply_task = asyncio.create_task(self.speak_fixed(greeting)) # 欢迎语与 ASR 并行启动
await self.asr.start()
try:
async for msg in self.ws:
if isinstance(msg, bytes):
await self.asr.send_audio(msg) # 二进制 = 来电者的 PCM
else:
if json.loads(msg).get("type") == "stop":
break
finally:
await self.cleanup()9.3 实时识别(bot/asr.py)
百炼 Paraformer 的 WebSocket 协议分四步:
连接(Authorization: Bearer <key>)
→ 发送 run-task(模型、格式、采样率)
← 收到 task-started ← 收到之前不能发音频
→ 持续发送二进制音频
← 收到 result-generated(sentence_end=false:中间结果;true:一句话结束)
→ 发送 finish-task
← 收到 task-finishedrun-task 的参数:
"parameters": {
"format": "pcm",
"sample_rate": self.sample_rate,
"language_hints": ["zh"],
"semantic_punctuation_enabled": False, # 关闭语义断句
"max_sentence_silence": 600, # 静音 600ms 就判定一句话结束
}- 为什么关闭语义断句:语义断句要等语义完整才出结果,在会议场景里更准确,但电话对话需要尽快响应。改用静音断句后,客户停顿 600ms 就判定一句话说完,机器人可以马上回答。客户语速慢、句中停顿多的话,可以调大到 800~1000。
- 攒包:电话侧每 20ms 来一帧,官方建议每包约 100ms,所以
send_audio先攒够 100ms(16k 时是 3200 字节)再发,消息数量减少到原来的五分之一。 - 心跳包:
result-generated里如果heartbeat为 true,直接跳过。
结果分两种,分别交给两个回调:
if sentence.get("sentence_end"):
await self.on_final(text) # 一句话结束 → 生成回复
else:
await self.on_partial(text) # 中间结果 → 用于判断是否打断9.4 大模型(bot/llm.py)
用百炼的 OpenAI 兼容接口,直接用 httpx 解析 SSE 流,不需要安装 openai SDK:
async with _client.stream("POST", f"{config.DASHSCOPE_HTTP_BASE}/chat/completions",
headers={"Authorization": f"Bearer {config.DASHSCOPE_API_KEY}"},
json={"model": config.LLM_MODEL, "messages": messages, "stream": True}) as resp:
async for line in resp.aiter_lines():
if line.startswith("data:"):
...
yield delta # 逐段产出文本系统提示词在 config.py 里,有几条是专门为电话场景写的:
- 每次不超过两句、口语化、不用 Markdown:TTS 会把
**、-这类符号也念出来,回复太长客户也记不住; - 结束标记
[转人工]/[挂机]:让大模型在回复末尾输出约定好的标记,代码识别到标记后执行对应的动作。这是最简单、最容易调试的"意图到动作"方案。生产环境可以改用 Function Calling。
9.5 边生成边合成(bot/server.py 的 reply)
延迟主要来自三段:等 ASR 判定一句话结束、等 LLM 生成、等 TTS 出第一段音频。为了让客户尽快听到声音,不等 LLM 全部生成完,切出一句就送一句去合成:
SENTENCE_END = re.compile(r"[。!?;!?;\n]")
async for delta in llm.stream_chat(self.history):
full += delta
pending += delta
while True:
m = SENTENCE_END.search(pending)
if not m:
break
sentence, pending = pending[:m.end()], pending[m.end():]
marker = marker or self._find_marker(sentence)
await tts.say(MARKER.sub("", sentence).strip()) # 去掉标记再合成
await tts.say(MARKER.sub("", pending).strip()) # 最后的半句
await tts.finish()
await self.player.end_of_turn()标记会从要合成的文本里去掉,客户听不到 [转人工] 这几个字,但代码记住了这个意图。
9.6 流式合成(bot/tts.py)
CosyVoice 的协议和 ASR 很像:
→ run-task(text_type=PlainText,voice,format=pcm,sample_rate)
← task-started
→ continue-task {"input":{"text":"第一句"}}
→ continue-task {"input":{"text":"第二句"}}
← 二进制音频分片(陆续返回)
→ finish-task
← task-finished两个参数最关键:
"format": "pcm":直接返回裸 PCM16LE,可以原样交给推流模块;"sample_rate": self.sample_rate:和通话采样率保持一致。CosyVoice 支持 8000、16000、22050、24000、44100、48000,正好覆盖 PCMA、G722 和 OPUS。
被打断时,发送带 directive: cancel 的 finish-task,服务端会立即结束任务,不再返回音频:
{"header": {"action": "finish-task", ...}, "payload": {"input": {"directive": "cancel"}}}两次 continue-task 之间的间隔不能超过 23 秒,否则连接会超时。本文每轮回复都新开一个合成任务,不会碰到这个限制。
9.7 下行音频:最容易踩坑的地方(bot/player.py)
TTS 返回的音频不能直接 ws.send 给推流模块,原因有三个,都来自模块的实际行为:
① 必须按整帧发送。 模块把下行音频切成 packet_ms 长度的帧放进缓冲,每条消息末尾不足一帧的部分会补零。TTS 返回的分片长度是任意的,如果直接转发,每个分片的结尾都会被插进一小段静音,听起来就是连续的"咔哒"声。
② 必须按实时节奏发送。 下行缓冲只有 rx_buffer_ms 那么长。TTS 合成速度远快于实时,一秒钟就能返回好几秒的音频,全部塞过去会溢出,模块会丢弃最旧的帧。
③ 打断时两边都要清空。 已经在模块缓冲里的音频,要靠 {"type":"clear"} 清掉;还没发出去的音频,要在本地丢弃。
PcmPlayer 就是解决这三个问题的:
self.frame_bytes = sample_rate * 2 * packet_ms // 1000 # 16k/20ms = 640 字节
async def _run(self):
while True:
frame = <从缓冲取出一整帧,不够就等>
now = loop.time()
if self._next_t < now: # 空闲后重新计时
self._next_t = now
lead = self._next_t - now
if lead > self.max_lead: # 最多领先实时 200ms
await asyncio.sleep(lead - self.max_lead)
await self.ws.send(frame)
self._next_t += self.frame_sec # 每帧推进 20msfeed():TTS 的音频分片先追加到本地缓冲;end_of_turn():一轮说完,把最后不足一帧的尾巴补齐成整帧,确保最后几十毫秒也能播出来;clear():清空本地缓冲,并给模块发送{"type":"clear"};busy():判断音频是否还在播放(本地还有没发的,或者已经发出去但电话里还没播完)。转人工之前要用它等最后一句播完。
领先量和缓冲的关系:后端领先实时 200ms(
MAX_LEAD_MS),模块缓冲 1000ms(rx_buffer_ms),后者必须明显大于前者。领先量越大越抗网络抖动,但打断时要清掉的音频也越多。
9.8 转人工与挂机(finish_call)
async def finish_call(self, marker: str) -> None:
self.ending = True # 不再响应新的话
await self.player.wait_drained() # 等"正在为您转接"这句播完
if marker == "转人工":
await fcc.transfer(self.uuid, config.QUEUE_EXTENSION) # POST /calls/{uuid}/transfer
else:
await asyncio.sleep(0.5)
await fcc.hangup(self.uuid)FCC 的 {call_id} 参数可以直接传 FreeSWITCH 的 uuid,所以机器人不需要知道 FCC 的 call_id,用 start 帧里的 uuid 就行。前提是这通电话已经被 fcc_inbound 注册过,第 10 章会讲。
转接之后,7000 的拨号计划第一步就是 taering_stream stop,模块会给机器人发 stop,CallSession 随之结束,释放 ASR 和 TTS 连接。
9.9 启动机器人
先停掉回声后端(Ctrl+C),因为两者监听同一个端口:
python -m bot.server
# INFO bot: AI bot listening on ws://127.0.0.1:9000此时用 1001 拨 9000(回声测试的分机),就已经能和 AI 对话了。这个分机没有经过 FCC,所以说"转人工"时转接会失败,日志里会看到 FCC 返回 CALL_NOT_FOUND,这是预期的。下一章把完整的入口接上。
10. 控制面:用 FCC 接管来电
10.1 入口拨号计划
<extension name="tutorial_ai_hotline">
<condition field="destination_number" expression="^4000$">
<action application="fcc_inbound" data="service=ai_hotline"/>
<action application="park"/>
<action application="log" data="WARNING FCC decision timeout, fallback to human queue"/>
<action application="transfer" data="7000 XML default"/>
</condition>
</extension>逐行解释:
fcc_inbound service=ai_hotline:把这通电话注册到 FCC。FCC 会分配一个call_id,设置通道变量fcc_call_id,并推送call.incoming事件,事件里带有service=ai_hotline。参数必须写成service=xxx的形式,只写ai_hotline会被当成default。fcc_inbound只做注册,不会应答,也不会改变路由。park:让通道停在这里,等后端决策。- 兜底:FCC 有一个决策超时(
inbound_decision_timeout_ms,默认 5000ms)。超时后,如果inbound_timeout_action=continue_dialplan(默认值),FCC 会打断park,拨号计划继续往下执行,这通电话就会直接进人工队列。所以就算 controller 挂了,客户也不会被晾着。
10.2 AI 分机
<extension name="tutorial_ai_bot">
<condition field="destination_number" expression="^8000$">
<action application="answer"/>
<action application="taering_stream" data="start - mono 16k {"service":"ai_hotline","caller":"${caller_id_number}"}"/>
<action application="execute_extension" data="tutorial_stream_failed XML default"/>
<action application="park"/>
<action application="hangup"/>
</condition>
</extension>- 第四个参数是元数据 JSON,会原样出现在 start 帧的
metadata字段里,机器人可以据此加载不同的话术或客户资料。因为参数按空格切分,JSON 里不能有空格;在 XML 里,双引号要写成"。 tutorial_stream_failed:如果taering_stream_result以-ERR开头(授权未生效、没配 URL),直接转人工。注意:start成功只代表推流会话已经创建,WebSocket 是在后台连接的。如果后端没启动,start依然返回+OK,模块会按reconnect_base_ms/reconnect_max_ms退避重连。所以生产环境还需要在业务侧做超时兜底。
10.3 controller.py
controller 是你"业务后端"的雏形。它和 FCC 保持一条 WebSocket 长连接,接收所有通话事件:
async with connect(config.FCC_WS_URL,
additional_headers={"Authorization": f"Bearer {config.FCC_API_TOKEN}"},
ping_interval=None) as ws:
await ws.send(json.dumps({
"type": "client.hello", "request_id": "controller-hello",
"client_id": "tutorial-controller", "protocol_version": 1,
"last_sequence": load_seq(),
}))- 第一帧必须是
client.hello,否则 FCC 会返回HELLO_REQUIRED并断开连接。没有完成握手的连接收不到任何事件。 last_sequence实现断线续传:每个事件都带有全局递增的sequence,处理完一个事件就把它写进.fcc_last_sequence文件。重连时把这个值发给 FCC,FCC 会从内存里的 4096 条事件中补发之后的事件。ping_interval=None:心跳由 FCC 负责,它每 15 秒发一次 Ping,websockets库会自动回 Pong。
收到 call.incoming 后做决策:
async def on_incoming(data: dict) -> None:
call_id, caller, service = data["call_id"], data.get("caller", ""), data.get("service", "")
if service != config.AI_SERVICE_NAME:
return
if caller in BLACKLIST:
await fcc.action(call_id, "reject", {"cause": "CALL_REJECTED"})
return
await fcc.transfer(call_id, config.AI_EXTENSION) # 转到 8000这里就是你放业务规则的地方:营业时间外直接转留言,VIP 客户直接转人工,按号码归属地分到不同的话术……
FCC 动作返回 200 只代表"命令已提交",不代表已经成功。要确认结果,看随后的
action.accepted/action.failed事件,或者调用GET /calls/{call_id}查询。
10.4 启动 controller
新开一个终端:
cd /opt/ai-callcenter-demo && source .venv/bin/activate
python controller.py
# INFO controller: connected to FCC 1.2.1-open完整的 FCC 接口说明见 FCC 双语文档(https://github.com/taering365/mod_fcc)。
11. 人工坐席与排队
11.1 队列
FreeSWITCH 默认的 callcenter.conf.xml 里已经定义了一个 support@default 队列,确认一下:
grep -n 'support@default' $FS_HOME/conf/autoload_configs/callcenter.conf.xml
fs callcenter_config queue list队列里最常用的几个参数:
<queue name="support@default">
<param name="strategy" value="longest-idle-agent"/> <!-- 分配给空闲最久的坐席 -->
<param name="moh-sound" value="$${hold_music}"/> <!-- 排队音乐 -->
<param name="max-wait-time" value="0"/> <!-- 最长等待秒数,0=不限 -->
<param name="max-wait-time-with-no-agent" value="0"/> <!-- 没有坐席在线时最多等多久 -->
<param name="discard-abandoned-after" value="60"/>
</queue>演示时建议把
max-wait-time-with-no-agent设成 30。这样坐席都不在线时,客户等 30 秒就会出队,不会一直听排队音乐。改完执行fs reloadxml和fs callcenter_config queue reload support@default。
11.2 队列入口
<extension name="tutorial_human_queue">
<condition field="destination_number" expression="^7000$">
<action application="taering_stream" data="stop"/>
<action application="set" data="hangup_after_bridge=true"/>
<action application="answer"/>
<action application="callcenter" data="support@default"/>
<action application="hangup"/>
</condition>
</extension>taering_stream stop必须放在第一行。从 AI 转过来的通话上还挂着推流,不停掉的话,AI 会继续听客户和坐席的对话,甚至插嘴。如果通话本来就没有推流,这一行只会把taering_stream_result设成-ERR,不影响后续执行。hangup_after_bridge=true:坐席或客户任意一方挂机,整通电话结束。
11.3 创建坐席并签入
坐席的 domain 必须和软电话实际注册所在的域一致。先查一下:
fs global_getvar domain
# 例如:192.168.1.10FreeSWITCH 默认的 internal profile 会把所有注册都归到
$${domain}下(force-register-domain),所以即使软电话里填的是公网 IP,这里也要用global_getvar domain的结果。
用 1002 当坐席:
python -m tools.setup_agent --extension 1002 --domain 192.168.1.10create: 200 OK
sign-in: 200 OK
{
"agent_id": "1002@default",
"status": "Available",
"state": "Waiting",
"registered": true,
"sip_contact": "sofia/internal/sip:1002@192.168.1.20:5060",
"contact": "[leg_timeout=20]user/1002@192.168.1.10"
}脚本调用了两个 FCC 接口:
POST /callcenter/agents:在 mod_callcenter 里创建一个 callback 类型的坐席,并把它加入support@default队列(tier)。FCC 会自动生成安全的 contact:[leg_timeout=20]user/1002@<domain>,坐席 20 秒不接就视为未接。POST /callcenter/agents/1002@default/sign-in:FCC 先检查 1002 是否真的注册了,确认注册了才把状态设为Available。没注册会返回 409AGENT_NOT_REGISTERED。
其他操作:
python -m tools.setup_agent --extension 1002 --domain 192.168.1.10 --action pause # 小休,不再分配新电话
python -m tools.setup_agent --extension 1002 --domain 192.168.1.10 --action resume
python -m tools.setup_agent --extension 1002 --domain 192.168.1.10 --action sign-out
python -m tools.setup_agent --extension 1002 --domain 192.168.1.10 --action status三个状态要分清:员工是否登录了你的业务系统、软电话是否完成了 SIP 注册、坐席是否签入了队列。FCC 只负责第三个,并在签入时校验第二个。第一个(以及员工心跳、超时自动签出)由你的业务后端负责。
12. 全链路联调
12.1 启动顺序
需要三个终端,或者用 tmux 分三个窗格:
# 终端 1:AI 机器人
cd /opt/ai-callcenter-demo && source .venv/bin/activate && python -m bot.server
# 终端 2:控制面
cd /opt/ai-callcenter-demo && source .venv/bin/activate && python controller.py
# 终端 3:FreeSWITCH 日志(可选,排障时很有用)
fscli开打之前的检查清单:
12.2 拨打 4000
用 1001 拨打 4000,按第 0 章的对话脚本聊几句,最后说"我要转人工"。
controller 终端(事件流,示例输出,ID 会不同):
call.incoming call=call_8b2e... caller=1001 status=incoming detail=None
route call_8b2e... (caller=1001) to AI extension 8000
action.accepted call=call_8b2e... caller=1001 status=incoming detail=transfer
call.answered call=call_8b2e... caller=1001 status=answered detail=None
action.accepted call=call_8b2e... caller=1001 status=answered detail=transfer ← AI 发起的转人工
queue.joined call=call_8b2e... queue=support@default agent=None
queue.agent_offered call=call_8b2e... queue=support@default agent=1002@default
queue.bridged call=call_8b2e... queue=support@default agent=1002@default
queue.bridge_ended call=call_8b2e... queue=support@default agent=1002@default
queue.completed call=call_8b2e... queue=support@default agent=1002@default
call.hangup call=call_8b2e... caller=1001 status=hangup detail=NORMAL_CLEARING机器人终端:
[8b2e...] call start rate=16000 metadata={'service': 'ai_hotline', 'caller': '1001'}
ASR started model=paraformer-realtime-v2 rate=16000
[8b2e...] USER: 你们的宽带有哪些套餐?
[8b2e...] BOT: 我们有100M每月59元、300M每月89元和1000M每月129元三种套餐,您想了解哪一种?
[8b2e...] barge-in by partial: 300
[8b2e...] USER: 300M的话多久能装?
[8b2e...] BOT: 预约后48小时内会有师傅上门安装。
[8b2e...] USER: 我要投诉,给我转人工。
[8b2e...] BOT: 好的,马上为您转接人工客服。 <转人工>
[8b2e...] transfer to queue 7000
FCC transfer 5f1c... -> 200 OK
[8b2e...] stream stop received
[8b2e...] call end1002 振铃,接听后就和 1001 进入人工通话。
12.3 再试几个场景
| 场景 | 操作 | 预期 |
|---|---|---|
| 打断 | AI 说长句时直接插话 | AI 立即停止,回答你的新问题 |
| 主动结束 | 说"没问题了,再见" | AI 道别后挂机 |
| 坐席不在线 | 先把 1002 签出(sign-out),再拨 4000 并要求转人工 | 客户听排队音乐;queue.timeout 或客户挂机后出现 queue.abandoned |
| controller 不在线 | 停掉 controller,再拨 4000 | 等 5 秒后直接进人工队列(拨号计划兜底) |
| 机器人不在线 | 停掉机器人,再拨 4000 | 电话接通但没有声音,模块在后台重连(见 10.2 的说明) |
| 黑名单 | 把 1001 加进 BLACKLIST |
来电被拒接 |
13. 打断(Barge-in)的原理与调参
13.1 打断的完整过程
机器人正在说话 ──── 客户开口 ──► ASR 返回中间结果(≥2 个字)
│
▼
on_partial → barge_in()
├─ 取消 reply 任务(停止 LLM 生成)
├─ tts.cancel()(发送 finish-task + directive=cancel)
└─ player.clear()
├─ 丢弃本地还没发的音频
└─ 发送 {"type":"clear"} ──► 模块清空下行缓冲
并推送 taering_stream::play 事件
Play-State=interrupted
Played-Ms=已经播放的毫秒数
▼
客户说完 → on_final → 生成新的回复13.2 为什么用"中间结果"触发
- 如果等一句话结束(
sentence_end)才打断,客户说完一整句后机器人才闭嘴,体验很差; - 如果用"有声音"就打断,咳嗽、背景噪音、"嗯嗯"这类附和都会打断机器人;
- 用"ASR 中间结果至少 2 个字"是一个简单实用的折中:既有真实内容,又足够早。
13.3 可调参数
| 参数 | 位置 | 调大 | 调小 |
|---|---|---|---|
中间结果字数阈值(len(text) >= 2) |
bot/server.py on_partial |
更不容易误打断,但反应更慢 | 更灵敏,更容易被噪音打断 |
max_sentence_silence |
bot/asr.py |
允许客户句中停顿更久 | 回复更快,但可能把一句话切成两半 |
MAX_LEAD_MS |
.env |
更抗网络抖动 | 打断时要清掉的音频更少 |
rx_buffer_ms |
mod_taering_stream.conf.xml |
必须大于 MAX_LEAD_MS |
— |
13.4 进阶:让大模型知道自己被打断在哪里
clear 之后,模块会推送 taering_stream::play 事件,Played-Ms 字段表示被打断前已经播放了多少毫秒。如果你的后端通过 ESL 订阅这个事件,就能把对话历史中机器人的回复精确截断到客户实际听到的部分,避免大模型以为客户已经听完了整段话。本文用的是简化做法:被打断的回复在历史里标注"(被打断)"。
14. 排障手册
14.1 通用排查顺序
- SIP 和 RTP:拨 9196 回声测试,确认基础通话正常;
- 推流通路:启动
tools/echo_server.py,拨 9000,确认推流正常; - AI 服务:运行
tools/check_dashscope.py,确认三项服务正常; - 控制面:controller 能否连上 FCC,拨 4000 时能否收到
call.incoming; - 打开日志:在
fscli里执行console loglevel debug;推流模块可以临时把log_debug改成true后reload mod_taering_stream。
14.2 症状对照表
| 症状 | 可能原因 | 处理 |
|---|---|---|
| 软电话注册失败 403 | 密码错误 | 检查 default_password,改完要 docker compose restart |
| 软电话注册超时 | 防火墙或安全组没放行 5060 | 放行 UDP/TCP 5060 |
| 接通后单向或双向无声 | NAT:SDP 里是内网 IP;RTP 端口没放行 | 设置 external_rtp_ip / external_sip_ip(4.4),放行 16384–32768/UDP |
| 拨 4000 后 5 秒才有反应,然后进了人工队列 | controller 没运行,或者 Token 错误 | 查看 controller 日志;如果是 AUTH_LOCKED,等 5 分钟 |
| controller 连接后收不到任何事件 | 没有发 client.hello,或者拨号计划没执行到 fcc_inbound |
检查 hello 是否返回 code=OK;在 fscli 日志里确认 4000 匹配到了 tutorial_ai_hotline |
taering_stream_result=-ERR |
授权未生效(pending)、并发已满(试用版 1 路)、URL 为空 |
fs taering_stream license、fs taering_stream stats;检查是否有另一通推流没结束 |
接通后没有欢迎语,机器人日志没有 call start |
机器人没运行,或端口不对 | 确认机器人监听 127.0.0.1:9000,与 default_ws_url 一致 |
机器人日志有 call start,但听不到声音 |
TTS 失败;采样率不支持 | 查看机器人日志里的 TTS task failed;确认 start 帧的 sample_rate |
| 声音变调(像花栗鼠或很低沉) | TTS 采样率和通话采样率不一致 | 不要写死采样率,必须用 start 帧里的 sample_rate |
| 声音里有规律的"咔哒"声 | 下行音频没有按整帧对齐 | 必须经过 PcmPlayer 发送,不要直接转发 TTS 分片 |
| 吞字,一句话中间丢了几段 | 下行缓冲溢出 | 确认 rx_buffer_ms 已改为 1000 并 reload mod_taering_stream;MAX_LEAD_MS 不要大于它 |
| 识别不出来,或者结果很差 | 采样率不对;用了 8k 编码 | 首选 G722;8k 线路可以试试 paraformer-realtime-8k-v2 |
| AI 自己打断自己 | 推流模式不是 mono,机器人听到了自己的声音 |
改回 mono |
| 回答很慢(超过 2 秒) | 静音断句阈值太大;LLM 模型偏慢 | 调小 max_sentence_silence;换更快的模型,比如 qwen-flash |
| 说"转人工"后没有反应 | 大模型没有输出 [转人工] 标记 |
查看机器人日志里 BOT 那一行末尾有没有 <转人工>;加强提示词 |
转人工时 FCC 返回 CALL_NOT_FOUND |
这通电话没有经过 fcc_inbound(比如直接拨的 9000) |
从 4000 进线 |
| 转到人工后 AI 还在说话 | 7000 的拨号计划里没有 taering_stream stop |
补上 |
坐席签入返回 AGENT_NOT_REGISTERED |
domain 不对;软电话没注册 |
fs global_getvar domain;在 fscli 里执行 sofia_contact 1002@<domain> |
| 坐席已签入但不振铃 | 队列不存在;坐席没加入队列(tier) | fs callcenter_config queue list agents support@default |
| 改了推流配置没生效 | 只执行了 reloadxml | 必须 fs reload mod_taering_stream |
14.3 常用诊断命令
fs show registrations # 谁注册了
fs show channels # 当前通话,以及每路的编码
fs taering_stream stats # 推流会话数、丢帧、授权状态
fs taering_stream license
fs callcenter_config queue list agents support@default # 队列里的坐席
fs callcenter_config agent list # 坐席状态
curl -sS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18080/api/v1/health
curl -sS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18080/api/v1/calls/<call_id>/events
fs sofia global siptrace on # 在 fscli 里打开 SIP 抓包15. 上生产前要做的事
本文的代码是教学用参考实现,目的是让你看清每个环节。上生产之前,至少要过一遍下面这些项:
安全
容量与授权
可靠性
接入真实线路
合规
16. 后续系列
主篇追求"先跑通"。下面这些主题会在系列文章里展开:
| 篇目 | 内容 | 地址 |
|---|---|---|
| 系列 1:mod_taering_stream 媒体协议详解 | start / stop 帧、帧长计算、三种声道模式、采样率与编码、play 事件与播放进度、HTTP / ESL / 拨号计划三种控制方式 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-01-stream-protocol |
| 系列 2:FCC 控制面深入 | 事件模型、幂等、断线续传与对账、入呼决策超时策略 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-02-fcc |
| 系列 3:AI 外呼 | FCC 外呼的三种路由模式、loopback 通道上的推流方向、接通后再分配坐席、动态并发池 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-03-outbound |
| 系列 4:实时质检与坐席辅助 | 在 bridge 通话上用 stereo 分轨推流、实时转写、话术提示 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-04-qa-assist |
| 系列 5:延迟优化 | TTS 连接复用、首句预合成、更快的模型、端到端延迟测量 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-05-latency |
| 系列 6:接入运营商线路 | 网关、NAT、编码协商、号码路由 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-06-carrier |
| 系列 7:生产化 | 多实例与高可用、监控(Prometheus)、授权与容量规划 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-07-production |
| 系列 8:排障手册(完整版) | 按症状组织的全链路问题定位 | https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-08-troubleshooting |
附录 A:命令速查
# FreeSWITCH
fs status
fs reloadxml
fs reload mod_fcc
fs reload mod_taering_stream
fs show registrations
fs show channels
fs global_getvar domain
# 推流模块
fs taering_stream version
fs taering_stream stats
fs taering_stream license
fs taering_stream <uuid> stop
fs taering_stream <uuid> interrupt_play
# 坐席与队列
fs callcenter_config agent list
fs callcenter_config queue list agents support@default
fs callcenter_config queue list members support@default
# FCC
TOKEN=你的Token; BASE=http://127.0.0.1:18080/api/v1
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/health
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/calls/<call_id>
curl -sS -H "Authorization: Bearer $TOKEN" $BASE/callcenter/agents/1002@default
curl -sS -X POST -H "Authorization: Bearer $TOKEN" $BASE/calls/<call_id>/hangup
# 配套代码
python -m tools.check_dashscope
python -m tools.echo_server
python -m bot.server
python controller.py
python -m tools.setup_agent --extension 1002 --domain <domain> [--action sign-in|sign-out|pause|resume|status]附录 B:mod_taering_stream 媒体协议速查
| 方向 | 类型 | 内容 |
|---|---|---|
| 模块 → 后端 | 文本(第一条) | {"type":"start","uuid":"...","stream_id":"...","external_id":"...","sample_rate":16000,"mix_type":"mono","metadata":{...}} |
| 模块 → 后端 | 二进制 | PCM16LE,每帧 packet_ms 毫秒;mono 16k 时为 640 字节;stereo 时为左右声道交织 |
| 模块 → 后端 | 文本 | {"type":"stop",...}:仅在显式执行 stop 时发送;直接挂机时模块不发 stop,而是直接关闭连接 |
| 后端 → 模块 | 二进制 | 单声道 PCM16LE,采样率与 start 帧一致;按整帧发送,按实时节奏发送 |
| 后端 → 模块 | 文本 | {"type":"clear"}:清空播放(需要 enable_barge_in=true) |
| 后端 → 模块 | 文本 | 其他 JSON:模块以 taering_stream::json 事件转发,ESL 程序可以订阅 |
拨号计划应用:
taering_stream start [ws://url|-] [mono|mixed|stereo|-] [8k|16k|-] [metadata_json]
taering_stream stop
taering_stream clear
结果写入通道变量 taering_stream_result:+OK / +OK already started / -ERR事件:taering_stream::connect、::disconnect、::json、::error、::play(Play-State:queued / start / done / interrupted 等,Played-Ms,Played-Samples)。
附录 C:文件清单
| 文件 | 作用 | 复制到 |
|---|---|---|
conf/dialplan/default/00_ai_callcenter.xml |
拨号计划 9000 / 4000 / 8000 / 7000 | $FS_HOME/conf/dialplan/default/ |
conf/autoload_configs/mod_taering_stream.conf.xml |
推流模块配置 | $FS_HOME/conf/autoload_configs/ |
bot/*.py |
AI 机器人 | 在宿主机运行 |
controller.py |
控制面 | 在宿主机运行 |
tools/*.py |
回声、检查、坐席工具 | 在宿主机运行 |
.env |
Key 与 Token | 不要提交到代码仓库 |
相关链接
- mod_fcc(开源呼叫控制模块,含双语接口文档):https://github.com/taering365/mod_fcc
- freeswitch-docker(Docker 离线部署):https://github.com/taering365/freeswitch-docker
- freeswitch_stream_mod(mod_taering_stream 推流模块):https://github.com/taering365/freeswitch_stream_mod
- 商业授权联系:taering@vip.qq.com
- 阿里云百炼控制台:https://bailian.console.aliyun.com
- Paraformer 实时识别 WebSocket API:https://help.aliyun.com/zh/model-studio/websocket-for-paraformer-real-time-service
- CosyVoice WebSocket API:https://help.aliyun.com/zh/model-studio/cosyvoice-websocket-api
- 百炼 OpenAI 兼容接口:https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope
系列文章
- 主篇:从零搭建 AI + 人工呼叫中心:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- 系列 1:mod_taering_stream 媒体协议详解:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-01-stream-protocol
- 系列 2:FCC 控制面深入:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-02-fcc
- 系列 3:AI 外呼:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-03-outbound
- 系列 4:实时质检与坐席辅助:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-04-qa-assist
- 系列 5:延迟优化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-05-latency
- 系列 6:接入运营商线路:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-06-carrier
- 系列 7:生产化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-07-production
- 系列 8:排障手册:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-08-troubleshooting