AI Voice Platform 文档

外观

部署与运行手册 ​

面向本地联调和生产前部署的统一说明。默认按“环境准备 → 启动顺序 → 健康检查 → 服务管理”执行，先对齐基础能力，再做联通验证，再落地上线。

跨主机调用方向、监听 / 连接 / 公开地址的区别、端口放行、反向代理、WebRTC、FRP 和多 FreeSWITCH cell 配置统一见部署网络拓扑与配置手册。本文保留 构建、启动顺序和通用运行检查，不重复维护网络拓扑事实。

环境与前置条件 ​

必备 ​

  • Bun 1.x
  • PostgreSQL（callflow / callout schema）
  • Windows 上构建 C++ 时需 Visual Studio 2022 C++ 工作负载与 CMake
  • Linux x64 上构建 C++ 时需 CMake、Ninja、C++ 编译器；推荐按目标系统选择 onnx-platform/Dockerfile.ubuntu22、onnx-platform/Dockerfile.debian12 或 onnx-platform/Dockerfile.debian13
  • FreeSWITCH 1.10.x + mod_audio_fork（ASR 通路要求）
  • 若使用流式 TTS，ffmpeg 在服务运行路径可见（或配置 mp3EncoderPath）
  • 若使用 NLU / Chat / Script 能力，需可访问 OpenAI 兼容推理后端（GPUStack / vLLM / Ollama 等）， 并准备好 callai-server 中配置的模型（出厂默认 NLU / Chat qwen3.5-2b、Script qwen3.6-27b-fp8）

网络与地址 ​

默认端口以服务目录为唯一来源；以下列表仅用于本地启动时快速对照。 跨机部署不要直接把 127.0.0.1 替换成同一个 IP，先按 逐连接矩阵确认真正的调用者。

  • 默认端口（示例，默认监听为 0.0.0.0）
    • callflow-esl ESL：9911
    • callflow-esl HTTP：9912
    • callflow-server：9913
    • FunASR 流式 ASR (2-pass)：10099 (/health, ws://.../audio)
    • FunASR 离线 ASR：10094 (/health, /asr, /v1/audio/transcriptions)
    • Sherpa 流式 ASR：10096 (/health, ws://.../audio)
    • Sherpa 离线 ASR：10095 (/health, /asr, /v1/audio/transcriptions)
    • TTS：9080 (/health, /tts, /tts-stream)
    • Emotion：9090 (/health, /analyze)
    • callai-server：9930 (/health、/api/v1/nlu/*、/api/v1/chat/*、/api/v1/script/*、/api/v1/ai/*)
    • callai-webpage：19930
    • callout-server：9920
    • callout-webpage：19920
    • callflow-webpage：19913
  • 远端联调场景必须保证 apps/callflow-esl/config.json 中 freeswitch.callbackHost 对应 的地址可被 FreeSWITCH 访问。

启动与启动顺序 ​

基础方式（一次启动） ​

bash
bun install
bun run dev

默认并发进程及标签以服务目录为准。

手工启动（按顺序） ​

bash
bun run dev:asr
bun run dev:tts
bun run dev:emotion
bun run dev:callai-server
bun run dev:callai-webpage
bun run dev:callflow-esl
bun run dev:callflow-server
bun run dev:callout-server
bun run dev:callflow-webpage
bun run dev:callout-webpage

推荐顺序（排障更稳定） ​

  1. build ONNX C++ 服务并确认目标平台目录已生成可执行文件 Windows:
    • cd onnx-platform\sherpa-asr-online-server; .\build.ps1
    • cd onnx-platform\sherpa-asr-offline-server; .\build.ps1
    • cd onnx-platform\fanasr-asr-online-server; .\build.ps1
    • cd onnx-platform\fanasr-asr-offline-server; .\build.ps1
    • cd onnx-platform\sherpa-tts-server; .\build.ps1
    • cd onnx-platform\emotion-analysis-server; .\build.ps1 Linux x64:
    • bash onnx-platform/sherpa-tts-server/build.sh
    • bash onnx-platform/sherpa-asr-online-server/build.sh
    • bash onnx-platform/sherpa-asr-offline-server/build.sh
    • bash onnx-platform/fanasr-asr-online-server/build.sh
    • bash onnx-platform/fanasr-asr-offline-server/build.sh
    • bash onnx-platform/emotion-analysis-server/build.sh
  2. 先启动基础语音服务进程：asr、tts、emotion
  3. 启动 Bun 服务：callflow-esl / callflow-server / callout-server（按需再启动可视化 web）
  4. 校验各健康接口（见下）

注意：bun run dev:asr/tts/emotion 调用的是 onnx-platform/run-server.mjs，该脚本只从 target/<win_x64|linux_x64> 拉起编译产物；若编译产物不存在会直接退出，建议先执行对应 build.ps1 或 build.sh。

生产部署方式 ​

deploy/ 保存当前生产（阿里云公网节点）与本地运行环境（WSL /data/ai-voice）的部署配置、 服务定义与编排文件：

text
deploy/
├── aliyun/        # 阿里云公网节点：Nginx、callflow-esl、FRPS、coturn、文档站、FreeSWITCH 现场配置
├── freeswitch/    # FreeSWITCH 配置参考树（新环境合并部署用基线）
├── wsl-docker/    # WSL 计算集群：Dockerfile、docker-compose.yml、各服务 config、FRPC
└── softphone-webrtc-ice-turn-guide.md

这些资产面向当前这套双主机拓扑，不是通用的一体化交付包：镜像不含业务二进制与模型 （均为外部挂载），systemd unit、Compose 与 Nginx 配置中的地址、端口、路径和凭据都需要按 目标环境重新校准。部署方仍需自行完成：

  1. 构建或准备 Bun 后端、Quasar 前端和 ONNX C++ 服务的目标平台产物；
  2. 安装并维护 PostgreSQL、Redis、OpenAI 兼容推理后端、FreeSWITCH、ffmpeg 等运行依赖；
  3. 把 deploy/aliyun/*/ 与 deploy/wsl-docker/configs/*.json 复制到各服务实际读取的位置并按目标环境修改；
  4. 按 FreeSWITCH 安装方式合并或部署 deploy/freeswitch/，不要覆盖现场的网关、证书和号码配置；
  5. 使用 systemd、Docker Compose 或既有运维平台管理启动顺序、重启、日志和开机自启。

阿里云节点与 WSL 集群的逐步操作分别见 ../deploy/aliyun/README.md 与 ../deploy/wsl-docker/README.md； Debian 12 主机上的具体检查项见 deployment-debian12.md， 完整网络设计见network-topology-deployment.md， deploy/ 目录边界见 ../deploy/README.md。

三个 Quasar 前端的 API 根地址都在构建期注入，默认值为同域 /api。默认配置下从仓库 根目录构建：

bash
bun run --cwd apps/callflow-webpage build
bun run --cwd apps/callout-webpage build
bun run --cwd apps/callai-webpage build

产物分别位于 apps/callflow-webpage/dist/spa/、apps/callout-webpage/dist/spa/ 和 apps/callai-webpage/dist/spa/。使用默认值时，生产环境需要为每个前端站点配置同域反向代理：

  • callflow 前端站点的 /api 转发到 callflow-server（默认 127.0.0.1:9913）；
  • callout 前端站点的 /api 转发到 callout-server（默认 127.0.0.1:9920）；
  • callai 前端站点的 /api 转发到 callai-server（默认 127.0.0.1:9930）。

代理必须保留 /api 路径。多个前端若同时部署，需使用能够分别配置 upstream 的不同 站点或 origin；同一 origin 下的同一个 /api 无法同时转发到多个后端。

需要自定义代理前缀或浏览器可访问的后端地址时，在构建前分别设置 VITE_CALLFLOW_API_BASE_URL、VITE_CALLOUT_API_BASE_URL 和 VITE_CALLAI_API_BASE_URL。 值推荐明确以 /api 结尾；API 根地址变化后必须重新构建并替换对应前端产物。

部署配置样例（deploy/aliyun/、deploy/wsl-docker/configs/）重点校准：

  • callflow-esl.config.json：freeswitch.callbackHost、audioFork.wsUrl、TTS endpoints、 recording.directory、businessConfig["llm-chat-business"] 的 endpoint / apiKey / model / requestTimeoutMs（endpoint 是 OpenAI 兼容后端的完整 /v1/chat/completions 地址）、 callout.calloutServer / nlu / chat 各自的 baseUrl / token / requestTimeoutMs（后两组都指向 callai-server）、 businessConfig["kb-audio-chat-business"] 的 endpoint / strategy / token；该 endpoint 指向 callai-server 的 /api/v1/conversation，样例策略为 kb-mock
  • callflow-server.json：FreeSWITCH / callflow 数据库、databases.freeswitch.configDir（FreeSWITCH 配置根目录）、callflowEsl.baseUrl、管理台鉴权与日志配置
  • callout-server.json：media.freeswitchRecordingBaseUrl、media.emotionAudioBaseUrl、FreeSWITCH inbound ESL、callai.baseUrl / token
  • callai-server.json：PostgreSQL callai 连接、server.authToken、callout.baseUrl 与用量记录配置； 推理后端地址可写死在 llm.openaiUrl，也可留空由数据库 callai.ai_llm_configs 中启用的记录提供
  • sherpa-tts-server.json：server.publicBaseUrl，必须是 FreeSWITCH 可访问地址

样例中可能包含面向特定部署目录的相对路径和示例地址，不能直接视为生产默认值。数据库密码、 鉴权 token 和云端凭据应通过环境变量或运维密钥系统注入，不要提交真实值。

云端兼容网关（按需） ​

  • bun run dev:aliyun-speech（10097 / 9081）
  • bun run dev:azure-speech（10098 / 9082）

健康检查清单（启动后必须执行） ​

建议按依赖顺序检查，避免上游未就绪导致下游误判：

  1. GET /health：sherpa-asr-online-server（10096）、sherpa-tts-server（9080）、emotion-analysis-server（9090）
  2. callai-server：GET http://127.0.0.1:9930/health，以及分别携带 token 的 NLU、Chat 与 Conversation capabilities
  3. sherpa_tts_server：POST /tts 可返回 wavUrl，并确认 FreeSWITCH 能访问该 URL
  4. sherpa_asr_online_server：通过 WebSocket 客户端工具执行一次连接与 transcription 可见性测试
  5. apps/callflow-esl：配置加载、/outbound-calls 与 runtime 重载接口可用
  6. apps/callflow-server：/health 与 FreeSWITCH DB 视图可读
  7. apps/callout-server：/health、数据库与外呼 dispatcher 可用
  8. apps/callout-server：GET /api/media/config 返回浏览器可访问的录音和情绪音频 baseUrl

启用 kb-audio-chat-business 时，还需直接向其 businessConfig 子项的 endpoint 验证一次带 strategy 的 action=start 和 action=query，并确认返回 answerText 后本地 TTS 可播放。

详细模块级验证步骤，请继续参考各模块 README 与 docs/troubleshooting.md。

服务关闭（可选） ​

统一脚本启动（bun run dev）在单个终端中托管默认启动组；关闭时对该终端执行 Ctrl+C 即可触发子进程退出。默认进程范围见服务目录。 如改为拆分启动，建议：

  • 先确认无活跃通话再停止服务；
  • 按 Ctrl+C 逐个关闭子进程；
  • Windows 可用 Get-Process + Stop-Process 做补充清理，例如：
powershell
Get-Process | Where-Object { $_.ProcessName -in @('sherpa_asr_online_server','sherpa_tts_server','emotion_analysis_server','node','bun') } | Format-Table Id,ProcessName

关闭后再确认端口回收：

powershell
netstat -ano | Select-String '10096|9080|9090|9930|9911|9912|9913|9920|19913|19920|19930'

服务配置建议（最小变更） ​

  • listenHost / 监听 host 建议按部署网卡绑定，不要默认只绑 127.0.0.1 影响联通。
  • publicBaseUrl / publicUrl 等需要 FreeSWITCH 可达，不要使用本机只回环地址。
  • 数据库密码与签名密钥不落到版本库，优先环境变量或运维注入。
  • C++ 服务建议固定日志目录并结合宿主日志采集（可按天滚动）。

服务管理要求（仓库约定） ​

  • 所有服务可重复启动与重启；测试结束后请关闭本地手动启动实例，避免端口/资源残留。
  • C++ 服务为前台常驻，Ctrl+C 是常见停止方式；停止前建议先确认无活跃通话/长连接。

升级与切换建议 ​

  • 新增/升级模型后，先在 demo 或单次联调脚本验证识别率与延迟，再切换线上 profile。

  • 调整端口、鉴权、wsPath、mp3EncoderPath、freeswitch.callbackHost 时，先补齐停机窗口和回滚方案。

  • 从异步号码导入升级到小批量同步导入时，必须停止或摘流全部旧 callout-server 实例、备份数据库， 手工删除三张旧导入历史表后再部署新版本，避免旧 worker 访问已删除表（辅助 SQL 脚本已随旧能力移除）：

    sql
    DROP TABLE IF EXISTS "callout"."import_job_errors";
DROP TABLE IF EXISTS "callout"."import_job_rows";
DROP TABLE IF EXISTS "callout"."import_jobs";

快速排障入口 ​

  • 模块级故障排查：troubleshooting.md
  • 模块 README 快速入口：
    • apps/callflow-esl/README.md
    • onnx-platform/sherpa-asr-online-server/README.md
    • onnx-platform/sherpa-tts-server/README.md
    • apps/callout-server/README.md

文档与代码在同一仓库维护，现有 Markdown 是唯一内容源。

AI Voice Platform