AI Voice Platform 文档

外观

部署与运行手册 ​

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

环境与前置条件 ​

必备 ​

  • 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 服务，Ollama 服务可访问，且已准备对应模型（出厂配置 qwen3.5:2b）

网络与地址 ​

  • 默认端口（示例，默认监听为 0.0.0.0）
    • callflow-esl ESL：9911
    • callflow-esl HTTP：9912
    • callflow-server：9913
    • ASR：10096 (/health, ws://.../audio)
    • TTS：9080 (/health, /tts, /tts-stream)
    • Emotion：9090 (/health, /analyze)
    • llm-nlu-server：9930 (/health, /api/v1/nlu/capabilities, /api/v1/nlu)
    • llm-chat-server：9931 (/health、/api/v1/chat/*、/api/v1/conversation*)
    • 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:llm-nlu
bun run dev:llm-chat
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-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/emotion-analysis-server/build.sh
  2. 先启动服务进程：sherpa_asr_online_server、sherpa_tts_server、emotion_analysis_server
  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。

生产部署方式 ​

仓库不再提供容器镜像、Docker Compose 编排、一体化部署产物或启停脚本。deploy/ 只保存 配置参考：

text
deploy/
├── config/       # 自研服务部署配置样例
└── freeswitch/   # FreeSWITCH 配置树

部署方需要自行完成以下工作：

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

Debian 12 主机上的具体检查项见 deployment-debian12.md， deploy/ 目录边界见 ../deploy/README.md。

构建前端时需要按目标域名或内网地址设置 API 环境变量；这些值会在构建期固化进 Quasar/Vite 产物，必须是最终用户浏览器可访问的地址。从仓库根目录使用 Bash 构建：

bash
export VITE_CALLFLOW_API_BASE_URL=http://<callflow-api-host>:<port>
export VITE_CALLOUT_API_BASE_URL=http://<callout-api-host>:<port>
bun run --cwd apps/callflow-webpage build
bun run --cwd apps/callout-webpage build
unset VITE_CALLFLOW_API_BASE_URL VITE_CALLOUT_API_BASE_URL

从仓库根目录使用 PowerShell 构建：

powershell
$env:VITE_CALLFLOW_API_BASE_URL = 'http://<callflow-api-host>:<port>'
$env:VITE_CALLOUT_API_BASE_URL = 'http://<callout-api-host>:<port>'
bun run --cwd apps/callflow-webpage build
bun run --cwd apps/callout-webpage build
Remove-Item Env:VITE_CALLFLOW_API_BASE_URL
Remove-Item Env:VITE_CALLOUT_API_BASE_URL

产物分别位于 apps/callflow-webpage/dist/spa/ 和 apps/callout-webpage/dist/spa/。未设置变量时，API 基址分别默认为 http://127.0.0.1:9913 和 http://127.0.0.1:9920。API 地址变化后必须重新构建 对应前端；仅修改静态文件托管服务的运行时环境变量不会更新现有产物。

部署配置样例（deploy/config/）重点校准：

  • callflow-esl.config.json：freeswitch.callbackHost、audioFork.wsUrl、TTS endpoints、 recording.directory、必填 businessConfig["ollama-chat-business"] 的 endpoint / model / requestTimeoutMs、 callout.calloutServer / nlu / chat 各自的 baseUrl / token / requestTimeoutMs、 businessConfig["kb-audio-chat-business"] 的 endpoint / strategy / token；该 endpoint 指向 llm-chat-server 的 /api/v1/conversation，样例策略为 kb-mock
  • callflow-server.config.json：FreeSWITCH / callflow 数据库、callflowEsl.baseUrl、管理台鉴权与日志配置
  • callout-server.config.json：media.freeswitchRecordingBaseUrl、media.emotionAudioBaseUrl、FreeSWITCH inbound ESL
  • llm-nlu-server.config.json：llm.ollamaUrl、llm.model、可选 server.authToken
  • llm-chat-server.config.json：llm.ollamaUrl、llm.model、可选 server.authToken
  • sherpa-tts-server.config.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. llm-nlu-server：GET http://127.0.0.1:9930/health 与 GET http://127.0.0.1:9930/api/v1/nlu/capabilities
  3. llm-chat-server：GET http://127.0.0.1:9931/health，以及带内部 token 的 GET /api/v1/chat/capabilities 和 GET /api/v1/conversation/capabilities
  4. sherpa_tts_server：POST /tts 可返回 wavUrl，并确认 FreeSWITCH 能访问该 URL
  5. sherpa_asr_online_server：通过 WebSocket 客户端工具执行一次连接与 transcription 可见性测试
  6. apps/callflow-esl：配置加载、/outbound-calls 与 runtime 重载接口可用
  7. apps/callflow-server：/health 与 FreeSWITCH DB 视图可读
  8. apps/callout-server：/health、数据库与外呼 dispatcher 可用
  9. 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'

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

  • 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