AI Voice Platform 文档

部署与运行手册 ​

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

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

环境与前置条件 ​

必备 ​

  • Bun 1.x
  • PostgreSQL：线上生产环境统一使用核心数据库 freeswitch，本地开发环境默认使用隔离库 dev-freeswitch；统一承载 callflow / callout 业务 Schema（线上另含 FreeSWITCH 软交换状态的 public Schema）
  • Rust 稳定版工具链（1.80+，通过 rustup 安装），用于构建 ONNX 平台各 Rust 语音服务；Windows 上需配合 MSVC 工具链与 PowerShell 7 (pwsh)，Linux 上需基础编译工具
  • FreeSWITCH 1.11.2 + mod_audio_fork（ASR 通路要求）
  • 若使用流式 TTS，ffmpeg 在服务运行路径可见（或配置 mp3EncoderPath）
  • 若使用 NLU / Chat / Script 能力，需可访问 OpenAI 兼容推理后端（GPUStack / vLLM / Ollama 等）， 并准备好 callout-server 中配置的模型（出厂默认 NLU / Chat qwen3.5-2b、Script qwen3.6-27b-fp8）

语音模型资产一键同步 (ModelScope + uv) ​

由于语音推理模型（FunASR、Sherpa-ONNX、Silero VAD、Kokoro、Matcha、Emotion 等）总体积约 4.37 GB，项目镜像与 Git 仓均不包含大模型二进制。在目标机器（开发机、WSL 集群或 Debian 12 生产宿主机）上，通过内置的 onnx-platform/models/model-down/ 脚本基于 uv 与 ModelScope (魔搭社区) 一键下载：

bash
# 1. 确保已安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# 2. 进入工具目录并同步依赖
cd onnx-platform/models/model-down
uv sync

# 3. 拉取全量模型到指定部署目录 (如 WSL/Linux 生产挂载路径 /data/ai-voice/models)
uv run download.py --model-id wlf213/ai-voice-platform-models --target-dir /data/ai-voice/models

# 本地开发时默认拉取至上一级目录 (即还原为 onnx-platform/models/)
uv run download.py --model-id wlf213/ai-voice-platform-models

网络与地址 ​

默认端口与服务名称以服务目录为唯一来源，本文不再维护重复端口表。跨机部署不要直接把 127.0.0.1 替换成同一个 IP，先按 逐连接矩阵确认真正的调用者。

  • 远端联调场景必须保证 apps/callflow-esl/config.toml 中 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:audio-fork:air
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 语音服务并确认目标平台目录（dist/<win_x64|linux_x64>）已生成交付产物 Windows (PowerShell 7):
    • cd onnx-platform\sherpa-asr-server; pwsh .\build.ps1
    • cd onnx-platform\sherpa-tts-server; pwsh .\build.ps1
    • cd onnx-platform\emotion-analysis-server; pwsh .\build.ps1
    • cd onnx-platform\funasr-asr-server; pwsh .\build.ps1 Linux x64:
    • bash onnx-platform/sherpa-asr-server/build.sh
    • bash onnx-platform/sherpa-tts-server/build.sh
    • bash onnx-platform/emotion-analysis-server/build.sh
    • bash onnx-platform/funasr-asr-server/build.sh
  2. 先启动基础语音服务进程：asr、tts、emotion、audio-fork
  3. 启动 Bun 服务：callflow-esl / callflow-server / callout-server（按需再启动可视化 web）
  4. 校验各健康接口（见下）

注意：bun run dev:asr/tts/emotion 调用的是各子项目的 run-server.ts，从各自的 dist/<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 平台 Rust 服务的目标平台产物；WSL Linux x64 的 Bun 后端必须分别执行 bun run --cwd apps/<服务名> build:linux（例如 callflow-server 与 callout-server），产物位于 apps/<服务名>/dist/linux_x64/；
  2. 安装并维护 PostgreSQL、Redis、OpenAI 兼容推理后端、FreeSWITCH、ffmpeg 等运行依赖；
  3. 把 deploy/aliyun/*/ 与 deploy/wsl-docker/configs/*.toml 复制到各服务实际读取的位置并按目标环境修改；ONNX ASR、TTS、Emotion 均从各自 dist/linux_x64/ 自包含交付目录完整分发，并按 deploy/wsl-docker/docker-compose.yml（参考 WSL 集群部署）核对宿主目录和模型挂载；
  4. 按 FreeSWITCH 安装方式部署 deploy/freeswitch/ 的容器化基线包，或从 deploy/aliyun/freeswitch/ 现场快照逐项合并；无论哪种方式都不要覆盖现场的网关、证书和号码配置；
  5. 使用 systemd、Docker Compose 或既有运维平台管理启动顺序、重启、日志和开机自启。

阿里云节点与 WSL 集群的逐步操作分别见 ../deploy/aliyun/README.md 与 ../deploy/wsl-docker/README.md； 生产环境实机与具体检查项见 production-deployment.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

产物分别位于 apps/callflow-webpage/dist/spa/ 与 apps/callout-webpage/dist/spa/（其中 callout-webpage 已包含「AI 策略中心」三栏话术策略工作台）。使用默认值时，生产环境需要为每个前端站点配置同域反向代理：

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

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

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

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

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

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

云端兼容网关（按需） ​

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

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

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

  1. GET /health：sherpa-asr-server（10096 / 10095）、funasr-asr-server（10099 / 10094）、sherpa-tts-server（9080）、emotion-analysis-server（9090）
  2. apps/callout-server：GET http://127.0.0.1:9920/health，以及分别携带 token 的 NLU、Chat 与 Conversation capabilities
  3. sherpa_tts_server：POST /tts 可返回 wavUrl，并确认 FreeSWITCH 能访问该 URL
  4. sherpa_asr_server：通过 WebSocket 客户端工具执行一次连接与 transcription 可见性测试
  5. apps/callflow-esl：配置加载、/outbound-calls 与 POST /freeswitch/reloadxml 可用
  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_server','funasr_asr_server','sherpa_tts_server','emotion_analysis_server','audio_fork_server','air','node','bun') } | Format-Table Id,ProcessName

关闭后再确认端口回收：

powershell
netstat -ano | Select-String '10096|10095|10099|10094|10091|9080|9090|9911|9912|9913|9920|19913|19920'

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

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

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

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

升级与切换建议 ​

  • 新增/升级模型后，先在 demo 或单次联调脚本验证识别率与延迟，再切换线上 profile。
  • 调整端口、鉴权、wsPath、mp3EncoderPath、freeswitch.callbackHost 时，先补齐停机窗口和回滚方案。
  • 涉及数据库 Schema 升级时，建议先执行数据库备份，并通过 db:push 完成表结构同步后再重启对应服务。

快速排障入口 ​

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

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

AI Voice Platform