快速开始

目标

从零开始，在一台机器上把 4 个服务全部拉起，拨一通电话验证：用户说话能识别到文本、能听到 TTS 合成的应答。

预计耗时：首次 30 ~ 60 分钟（含模型加载与 FreeSWITCH 安装），熟练后 5 分钟。

环境前提

本例为单机部署，全部跑在同一台机器。FS 部署在 Linux + ASR/TTS 部署在 Windows 的常见拓扑见 部署。

Step 1 — 安装 FreeSWITCH + mod_audio_fork

1.1 装 FreeSWITCH

参考 FreeSWITCH 官方文档，本项目验证过 Debian 11 / CentOS 7。装好后能 fs_cli 进 FreeSWITCH 终端。

1.2 编译 mod_audio_fork

1
2
3
4

git clone https://github.com/Wangijun/mod_audio_fork.git
cd mod_audio_fork
chmod +x build.sh
sudo ./build.sh all

完成后 mod_audio_fork.so 会安装到 FS 的 mod 目录。

1.3 启用模块

编辑 conf/autoload_configs/modules.conf.xml：

1

<load module="mod_audio_fork"/>

或运行时：

1

fs_cli -x "load mod_audio_fork"

验证：

1

fs_cli -x "module_exists mod_audio_fork"

返回 true 即成功。

Step 2 — 启动 ASR 服务

2.1 构建

1
2

cd C:\path\to\ai-voice-platform\onnx-platform\sherpa-asr-online-server
.\build.ps1

2.2 检查配置

打开 target\win_x64\config.json，确认：

1
2
3
4
5
6
7
8

{
  "listenHost": "0.0.0.0",       // 监听所有网卡
  "listenPort": 10096,
  "wsPath": "/audio",
  "wsSubprotocol": "audio.drachtio.org",
  "maxSessions": 16,
  "sampleRate": 16000
}

模型路径默认相对解析到 ../models/，无需改。

2.3 启动

1
2

cd target\win_x64
.\sherpa_asr_online_server.exe

启动成功日志：

1
2

[sherpa_asr_online_server] listening on 0.0.0.0:10096 ...
[sherpa_asr_online_server] service ready; press Ctrl+C to stop.

2.4 验证健康检查

新开一个终端：

1

curl http://127.0.0.1:10096/health

返回：

1

{ "ok": true, "service": "sherpa-asr-online-server", "activeSessions": 0, ... }

Step 3 — 启动 TTS 服务

3.1 构建

1
2

cd C:\path\to\ai-voice-platform\onnx-platform\sherpa-tts-server
.\build.ps1

3.2 检查配置

打开 target\win_x64\config.json：

1
2
3
4
5
6
7

{
  "listenHost": "0.0.0.0",
  "listenPort": 9080,
  "publicBaseUrl": "http://<本机IP>:9080",
  "workerThreads": 4,
  "ttsPoolSize": 2
}

3.3 启动

1
2

cd target\win_x64
.\sherpa_tts_server.exe

启动成功日志：

1
2

[sherpa_tts_server] loaded TTS worker in 1234 ms
[sherpa_tts_server] listening on http://0.0.0.0:9080

3.4 验证合成

1
2
3

curl -s -X POST http://127.0.0.1:9080/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"测试语音合成","speakerId":0,"speed":1.0}'

返回：

1

{ "wavUrl": "http://...:9080/wav/tts-xxx.wav", "fileName": "...", "sampleRate": 16000, "cached": false }

浏览器打开 wavUrl 能直接播放即正常。

Step 4 — 启动 PostgreSQL + callflow-esl

4.1 准备 PostgreSQL

1

CREATE DATABASE freeswitch;

记下连接串：postgres://postgres:postgres@127.0.0.1:5432/freeswitch

4.2 安装依赖与初始化 schema

1
2

cd C:\path\to\ai-voice-platform
bun install

打开 apps/callflow-esl/config.json，按你的环境改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "esl-server": { "host": "0.0.0.0", "port": 9911 },
  "http-server": { "host": "0.0.0.0", "port": 9912 },
  "freeswitch": {
    "host": "<FS 机器 IP>",
    "port": 8021,
    "password": "ClueCon",
    "callbackHost": "<本机 IP，FS 能访问的>",
    "callbackPort": 9911
  },
  "audioFork": {
    "wsUrl": "ws://<本机 IP>:10096/audio",
    "bugName": "callflow_asr",
    "mixType": "mono",
    "sampleRate": "16k"
  },
  "tts": {
    "sherpaHttpEndpoint": "http://127.0.0.1:9080/tts",
    "streamingEnabled": true,
    "sherpaStreamEndpoint": "http://127.0.0.1:9080/tts-stream",
    "streamPlaybackPrefix": "shout://",
    "playbackTarget": "wav-url"
  },
  "db": {
    "url": "postgres://postgres:postgres@127.0.0.1:5432/freeswitch"
  }
}

初始化 schema：

1
2
3

cd apps/callflow-esl
bun run db:generate
bun run db:push

4.3 插入一条测试业务路由

callflow-esl 启动时会把代码里的 15 个业务自动同步到
callflow.call_businesses。如果要用被叫号码 1000 命中默认回显业务，可在
PostgreSQL 执行：

1
2
3
4
5
6

INSERT INTO callflow.call_business_number_mappings
  ("destinationNumber", "businessId", "isEnabled", remark)
SELECT '1000', id, 1, 'quickstart'
FROM callflow.call_businesses
WHERE "businessCode" = 'default-call-business'
ON CONFLICT ("destinationNumber") DO NOTHING;

4.4 启动服务

ASR / TTS 已在前面单独起好，这里只起 callflow-esl：

1

bun run dev:callflow-esl

仓库根目录的 bun run dev 会一次并发启动全部 8 个服务（asr / tts / emotion 三个 C++ 服务

• callflow-esl / callflow-server / callflow-webpage / callout-server / callout-webpage，其中三个
  C++ 服务必须已 build.ps1 构建好）。本快速开始只验证最小通话链路，故按服务单独启动。

启动日志：

1
2
3

[callflow-esl] ESL TCP listening on 0.0.0.0:9911
[callflow-esl] HTTP listening on 0.0.0.0:9912
[callflow-esl] db connected

Step 5 — 配置 FreeSWITCH dialplan

编辑 conf/dialplan/default.xml（或自己挂一段）：

1
2
3
4
5
6

<extension name="route-to-callflow">
  <condition field="destination_number" expression="^(.+)$">
    <action application="set" data="hangup_after_bridge=true"/>
    <action application="socket" data="<callflow-esl 机器 IP>:9911 async full"/>
  </condition>
</extension>

重载：

1

fs_cli -x "reloadxml"

Step 6 — 拨打第一通电话

用任意 SIP 客户端（如 Zoiper、MicroSIP）注册到 FreeSWITCH，拨号 1000。

观察 callflow-esl 控制台：

1
2
3
4
5
6

[callflow-esl] outbound session uuid=...
[callflow-esl] route business=default-call-business
[callflow-esl] answered
[callflow-esl] speak text="您好..."
[callflow-esl] audio_fork started ws=ws://.../audio
[callflow-esl] hear timeout=30000

接通后说一段话（中文/英文都行），ASR 服务会返回 partial / final 文本，callflow-esl 会用 TTS 把你说的话回放回来（这是 default-call-business 的行为：echo 业务）。

ASR 服务控制台会看到：

1
2
3

[sherpa_asr_online_server] ws-1 websocket session started on worker=0
[sherpa_asr_online_server] ws-1 metadata={"uuid":"...","direction":"inbound"}
[sherpa_asr_online_server] ws-1 final text=你好世界 reason=endpoint

TTS 服务控制台：

1
2

[sherpa_tts_server] generated public/wav/tts-xxx.wav in 234 ms (rtf=0.45)
[sherpa_tts_server] request textLength=4 cached=false elapsedMs=240

第一通电话成功后

恭喜，端到端链路打通了。下一步：

• 想看更多业务范式 → 业务开发指南
• 想看典型应用场景 → 典型场景
• 想要 Web 后台看数据 / 配号码路由 / 试听 TTS 音色 → 管理控制台
• 想批量自动外呼 → 智能外呼
• 想做生产部署 → 部署拓扑
• 出错了 → FAQ

常见拉起问题速查

更完整的排查表在 FAQ。