Administrator
发布于 2026-11-21 / 3 阅读
0
0

从零搭建 AI + 人工呼叫中心:FreeSWITCH + FCC + mod_taering_stream + 阿里云百炼完整实战

本文是系列教程的主篇。按顺序做完,你会得到一套能真实打通的呼叫中心:来电先由 AI 客服接听,支持边说边打断;客户要求人工时,AI 把电话转进排队系统,由坐席接听。

文章刻意写得很细:每条命令、每个配置项、每行关键代码都会解释为什么这么写。中途卡住时,先看第 14 章 排障手册。


目录


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.10

↑ 回到目录


3. 部署 FreeSWITCH

3.0 两种部署方式

方案 A:Docker 离线包(推荐) 方案 B:源码编译
做法 下载一个离线包,执行 ./start.sh 自行编译 FreeSWITCH,再安装 mod_fcc 和 mod_taering_stream
耗时 几分钟 数小时起,取决于对 FreeSWITCH 的熟悉程度
本文是否提供教程 ✅ 后续所有步骤都基于此方案 ❌ 不提供,仅给出参考资料

为什么推荐 Docker

  1. 不用编译:镜像是预编译好的,目标服务器不需要下载源码,也不需要装编译工具链。FreeSWITCH 的编译依赖多、耗时长,是新手最容易卡住的地方。
  2. 版本组合已验证:FreeSWITCH 1.10.12、mod_fcc、mod_taering_stream 以及 mod_callcenter 等呼叫中心模块打包在同一个镜像里,彼此兼容。自己编译时,版本、编译选项和系统库稍有不同,就可能出现模块加载失败或者行为不一致。
  3. 支持离线部署:整套环境是一个离线包,适合不能访问外网、或者访问 GitHub 很慢的内网服务器。
  4. 配置和程序分离:所有 XML 配置都放在宿主机的 conf/ 目录,升级时换一个镜像即可,配置不会被覆盖;数据库、日志、录音放在命名卷里,重建容器也不会丢。
  5. 环境一致:本文所有命令、路径和截图都基于这个镜像,照着做最不容易出偏差。

方案 B:源码编译(不提供教程)

适合已经有 FreeSWITCH 环境,或者需要自定义编译选项的读者。需要自行完成:

选方案 B 的读者,第 3 章之后的内容依然适用,只需要把文中的 fs 命令换成本机的 fs_cli -x,把 $FS_HOME/conf 换成你自己的 FreeSWITCH 配置目录。

3.1 方案 A:下载、解压并启动

离线包下载地址:

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

项目说明(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.sh

start.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 ~/.bashrc
  • fs <命令>:执行一条 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 第一通电话

  1. 用 1001 拨打 9196:这是 FreeSWITCH 自带的回声测试,你说什么就会听到什么。能听到自己的声音,就说明 SIP 和 RTP 都通了。
  2. 用 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:9000

7.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

  1. 登录阿里云百炼控制台 https://bailian.console.aliyun.com(地域选华北2(北京));
  2. 开通服务;在模型广场确认 Paraformer、CosyVoice、通义千问可用;
  3. 在"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-finished

run-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       # 每帧推进 20ms
  • feed():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>

逐行解释:

  1. fcc_inbound service=ai_hotline:把这通电话注册到 FCC。FCC 会分配一个 call_id,设置通道变量 fcc_call_id,并推送 call.incoming 事件,事件里带有 service=ai_hotline。参数必须写成 service=xxx 的形式,只写 ai_hotline 会被当成 default。fcc_inbound 只做注册,不会应答,也不会改变路由。
  2. park:让通道停在这里,等后端决策。
  3. 兜底: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 {&quot;service&quot;:&quot;ai_hotline&quot;,&quot;caller&quot;:&quot;${caller_id_number}&quot;}"/>
    <action application="execute_extension" data="tutorial_stream_failed XML default"/>
    <action application="park"/>
    <action application="hangup"/>
  </condition>
</extension>
  • 第四个参数是元数据 JSON,会原样出现在 start 帧的 metadata 字段里,机器人可以据此加载不同的话术或客户资料。因为参数按空格切分,JSON 里不能有空格;在 XML 里,双引号要写成 &quot;。
  • 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.10

FreeSWITCH 默认的 internal profile 会把所有注册都归到 $${domain} 下(force-register-domain),所以即使软电话里填的是公网 IP,这里也要用 global_getvar domain 的结果。

用 1002 当坐席:

python -m tools.setup_agent --extension 1002 --domain 192.168.1.10
create: 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 接口:

  1. POST /callcenter/agents:在 mod_callcenter 里创建一个 callback 类型的坐席,并把它加入 support@default 队列(tier)。FCC 会自动生成安全的 contact:[leg_timeout=20]user/1002@<domain>,坐席 20 秒不接就视为未接。
  2. POST /callcenter/agents/1002@default/sign-in:FCC 先检查 1002 是否真的注册了,确认注册了才把状态设为 Available。没注册会返回 409 AGENT_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 end

1002 振铃,接听后就和 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 通用排查顺序

  1. SIP 和 RTP:拨 9196 回声测试,确认基础通话正常;
  2. 推流通路:启动 tools/echo_server.py,拨 9000,确认推流正常;
  3. AI 服务:运行 tools/check_dashscope.py,确认三项服务正常;
  4. 控制面:controller 能否连上 FCC,拨 4000 时能否收到 call.incoming;
  5. 打开日志:在 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 不要提交到代码仓库

相关链接

系列文章

↑ 回到顶部


评论