AI Voice Platform 文档

配置参考 ​

配置 ​

运行时配置从 apps/callout-server/config.toml 读取。

  • server.host / server.port：callout HTTP API 监听地址。

  • server.serviceApi.authToken：callflow-esl 等可信服务调用结果回写、进度上报、转人工和运行时脚本接口时使用的共享令牌。为空时不校验，适合本地联调；生产环境建议配置，并让请求头携带 X-Callout-Internal-Token。可用 CALLOUT_SERVICE_API_AUTH_TOKEN 覆盖。

  • auth.enabled / auth.sessionTtlSeconds：管理 API 鉴权开关和会话有效期。config.toml 默认 enabled = true，本地联调可用 CALLOUT_AUTH_ENABLED=false 关闭。启用后会自动创建引导管理员账号（可用 CALLOUT_AUTH_BOOTSTRAP_ADMIN_USERNAME / CALLOUT_AUTH_BOOTSTRAP_ADMIN_PASSWORD 覆盖）。

  • scheduler.enabled / scheduler.intervalMs / scheduler.batchSize：后台派发器开关、轮询间隔和每轮活动批次大小。只有 running 状态的活动会被自动派发。

  • liveMonitor.defaultCapacity / liveMonitor.presenceTtlMs：每个活跃盯屏用户的默认通话容量（默认 5）与页面在线租约时长；也可用 CALLOUT_LIVE_MONITOR_CAPACITY / CALLOUT_LIVE_MONITOR_PRESENCE_TTL_MS 覆盖。

  • lifecycleReconcile.enabled / lifecycleReconcile.intervalMs / lifecycleReconcile.stuckAfterMs：通话生命周期补偿任务配置，用于清理长期停留在 dialing / submitted 的联系人。

  • conferenceReconcile.enabled / conferenceReconcile.intervalMs / conferenceReconcile.graceMs：转人工会议对账任务配置（默认每 30s 一轮，graceMs 60s 宽限期）。用 FreeSWITCH 实时成员数收尾「库里 active、FS 里已无成员」的僵尸会议会话；FreeSWITCH 不可达时整轮跳过，绝不误关。

  • agentRegistrationReconcile.enabled / agentRegistrationReconcile.intervalMs：坐席注册对账任务配置（默认开启、每 30s 一轮）。用 FreeSWITCH show registrations 把「DB 在线 / 空闲但分机未注册」的坐席降级为 offline（记 agent_registration_offline 运行事件）。只降级不升级、busy 不动；仅当 agentDialStringTemplate 按 user/ 分机拨打时生效，FreeSWITCH 不可达时整轮跳过。

  • emotionAnalysis.enabled / endpoint / timeoutMs / intervalMs / maxConcurrency / retryIntervalMs / maxRetries：通话后情绪分析 worker 配置，把已完成的呼叫尝试排队发往 onnx-platform/emotion-analysis-server 的 POST /analyze，结果写回 call_attempts.emotionResult。

  • notifications.webhookUrl / notifications.minLevel / notifications.timeoutMs：运行事件告警 webhook（请求超时默认 5000ms）。payload 支持常见文本 webhook，并附带结构化 level/type/message/payload 字段。可用 CALLOUT_NOTIFICATION_WEBHOOK_URL、CALLOUT_NOTIFICATION_MIN_LEVEL、CALLOUT_NOTIFICATION_TIMEOUT_MS 覆盖。

  • llm.openaiUrl / llm.apiKey / llm.nlu.* / llm.chat.* / llm.script.*：可选的静态固定 LLM 推理后端配置。包含 openaiUrl（OpenAI 兼容推理服务地址）、apiKey 以及按场景划分的模型与超时设置（llm.nlu.model / timeoutMs / maxTokens、llm.chat.model / timeoutMs、llm.script.model / timeoutMs / maxTokens）。支持通过 CALLAI_OPENAI_URL / LLM_OPENAI_URL、CALLAI_API_KEY / LLM_API_KEY 以及场景模型环境变量（如 CALLAI_NLU_MODEL / LLM_NLU_MODEL、CALLAI_CHAT_MODEL / LLM_CHAT_MODEL、CALLAI_SCRIPT_MODEL / LLM_SCRIPT_MODEL、CALLAI_NLU_TIMEOUT_MS、CALLAI_NLU_MAX_TOKENS、CALLAI_CHAT_TIMEOUT_MS、CALLAI_SCRIPT_TIMEOUT_MS、CALLAI_SCRIPT_MAX_TOKENS）覆盖。若未在配置文件中声明 [llm]，服务在运行期会自动从 PostgreSQL callout.ai_llm_configs 数据库表中动态加载已启用的推理配置（可在 Web 端「AI 策略中心 → 模型配置」页面可视化管理）。

  • callflowEsl.baseUrl / callflowEsl.token：浏览器软电话会话代理的 callflow-esl HTTP 地址（其 httpServer 端口，仓库配置 http://127.0.0.1:9912）与共享令牌（对应 callflow-esl httpServer.authToken，代理请求放在 token 头）。可用 CALLOUT_CALLFLOW_ESL_BASE_URL / CALLOUT_CALLFLOW_ESL_TOKEN 覆盖。多 FS 部署时按 cell 配置（见 cells），顶层值作为 cell 省略字段的默认值。

  • softphone.serviceNumber：浏览器 SIP 软电话实际拨打的业务号（代码默认 8800，仓库配置 5020），需在 FreeSWITCH / callflow 侧路由到 browser-softphone-assist-business；见 docs/softphone-sip.md。可用 CALLOUT_SOFTPHONE_SERVICE_NUMBER 覆盖。

  • media.freeswitchRecordingBaseUrl / media.emotionAudioBaseUrl：前端拼接媒体播放 URL 的前缀，通过 GET /api/media/config 下发。响应同时包含 freeswitchRecordingBaseUrlsByCell；前端与情绪分析 worker 按 attempt.cellId 选择录音前缀，cellId 为空时使用默认值，非空但未匹配到 cell 时不生成 URL。

  • freeswitchEvents.enabled / freeswitchEvents.reconnectIntervalMs：FreeSWITCH inbound ESL 事件监听配置，用于接听、挂机事件兜底同步。每个 cell 一个监听器；由 Redis 租约（callout:esl-listener:{cellId}，TTL 取 redis.lockTtlMs）保证每个 cell 只有一个消费者，持有实例崩溃后租约到期自动被其他实例接管。

  • redis：必选依赖，服务启动时主动连接并执行 PING，失败则拒绝启动。url 是必填的完整 redis: / rediss: 连接 URL（例如 redis://default:redis@127.0.0.1:6379/0）；keyPrefix 用于隔离 key，lockTtlMs 控制分布式锁和 FreeSWITCH cell 租约时长。可用 CALLOUT_REDIS_URL、CALLOUT_REDIS_KEY_PREFIX、CALLOUT_REDIS_LOCK_TTL_MS 覆盖。

  • turn.enabled / host / port / realm / sharedSecret / credentialTtlSeconds：浏览器软电话的 coturn 短期凭据下发配置。仓库默认 enabled: false，适用于浏览器与 FreeSWITCH host candidate 直连的内网场景；公网跨运营商必须置 true 并注入真实 sharedSecret（推荐用 CALLOUT_TURN_SHARED_SECRET 环境变量，不要写进仓库配置）。只开开关而缺字段时，短期凭据接口返回 503 ICE_CONFIG_UNAVAILABLE。全部字段有 CALLOUT_TURN_* 环境变量覆盖，部署细节见软电话 WebRTC ICE/TURN 指南。

  • ringbackDetection.*：可选的运营商早期媒体回铃音实时检测。支持 enabled（开关）、wsUrl（ASR WebSocket 地址）、detectionTimeoutMs（最大超时，默认 20000ms）、bugName（默认 "callout_ringback"）、mixType（"mono" / "mixed" / "stereo"，默认 "mono"）、sampleRate（默认 "16k"）、toneDetectionEnabled（是否开启频率信号音检测，默认 true）、toneFrequency（回铃特征频率，默认 "450" Hz）、toneHits（判定命中脉冲数，默认 5）与 toneTimeoutMs。全部字段支持 CALLOUT_RINGBACK_DETECTION_* 环境变量覆盖，运行边界见运行与后台任务 · 回铃音检测。

  • db.url：PostgreSQL 连接串；本地开发默认连接 dev-freeswitch 库，线上生产环境统一连接 freeswitch 库；callout 会从中派生 callout 与 callflow schema 客户端。可用 CALLOUT_DB_URL（以及专用的 CALLOUT_CALLOUT_DB_URL、CALLOUT_CALLFLOW_DB_URL）覆盖。

  • cells：FS cell 列表，每项 = 一台 FreeSWITCH + 与之配对的 callflow-esl 实例，是多 FS 部署时并发额度、事件监听、软电话路由的分片单元。至少一项：

    • cells[].id：cell 稳定标识（必填且全局唯一，缺失或重复会阻止启动）；后续会写入活动/呼叫记录做归属关联，配置后不要变更。
    • cells[].freeswitch.host / port / password：本 cell 的 FreeSWITCH inbound ESL 连接信息。
    • cells[].freeswitch.callbackHost / callbackPort：FreeSWITCH 可访问的、与本 cell 配对的 callflow-esl outbound socket 地址。
    • cells[].freeswitch.originateDialStringTemplate：包含 的拨号串模板。
    • cells[].freeswitch.agentDialStringTemplate：坐席软电话呼出时使用的坐席分机拨号模板，默认 user/。
    • cells[].freeswitch.commandTimeoutMs：inbound ESL 命令超时。
    • cells[].freeswitch.ignoreEarlyMedia：发起普通外呼时是否忽略早期媒体（默认 true，可用 CALLOUT_FREESWITCH_IGNORE_EARLY_MEDIA 覆盖）。开启后严格等待被叫真实摘机（200 OK）再接入 ESL 业务，避免彩铃吃字、漏播首句或未接听误判。
    • cells[].callflowEsl.baseUrl / token：本 cell 配对 callflow-esl 的 HTTP API 地址与令牌。
    • cells[].media.freeswitchRecordingBaseUrl：本 cell 的录音播放 URL 前缀。
    • cells[].maxConcurrency：本 cell 允许的最大并发通话数，0 表示不限制。

    cell 中省略的字段逐字段继承顶层 freeswitch / callflowEsl / media.freeswitchRecordingBaseUrl（含对应环境变量覆盖后的值）；cell 显式字段的优先级高于环境变量。

  • 单 FS 配置：不配置 cells 时，顶层 freeswitch / callflowEsl / media 会被自动包装成唯一的 default cell。运行时顶层 config.freeswitch / config.callflowEsl / config.media.freeswitchRecordingBaseUrl 始终是 cells[0] 的镜像。

带 CALLOUT_ 前缀的环境变量可以覆盖这些值，包括 CALLOUT_FREESWITCH_HOST、CALLOUT_FREESWITCH_PORT、 CALLOUT_FREESWITCH_PASSWORD、CALLOUT_FREESWITCH_CALLBACK_HOST、 CALLOUT_FREESWITCH_CALLBACK_PORT 和 CALLOUT_ORIGINATE_DIAL_STRING_TEMPLATE。注意 CALLOUT_FREESWITCH_* / CALLOUT_CALLFLOW_ESL_* 作用于顶层默认值：未配置 cells 时即生效于唯一 cell；配置了 cells 时只影响各 cell 省略的继承字段。

HTTP 层默认对浏览器全局返回 Access-Control-Allow-Origin: *。这不会放宽登录、Bearer Token、 内部 X-Callout-Internal-Token 等现有鉴权逻辑，只是取消来源白名单限制。

可选回铃音检测功能也提供环境变量（CALLOUT_RINGBACK_DETECTION_*）；运行边界见 运行与后台任务 · 回铃音检测。

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

AI Voice Platform