TelCRM(国信)呼叫中心 集成 API 文档 — 大模型故障上报与恢复(knServer 专用)
面向 knServer(大模型网关)侧的对接开发人员。knServer 通过本文的两个 JSON 接口向呼叫中心成对上报大模型故障与恢复;呼叫中心据此在故障期间阻止呼叫进入机器人(排队自动触发与排队确认"按2转机器人"两个入口),恢复后自动放行。
版本前提:本契约自
system.version 3.8.680起生效;部署现场需已安装含本特性的构建并重启(以控制台"启动成功"日志时间晚于 2026-09-13 为准)。对接是拦截效果的上线硬前提
只报故障不报恢复时,一次故障上报 = 两个机器人入口持续拦截,直到恢复上报、意图预测自愈或呼叫中心重启。请务必先完成成对上报再依赖拦截能力。
1. 接口总览
| 接口 | opt | 方向 | 用途 |
|---|---|---|---|
| 大模型故障上报 | emergency.voice.warn | knServer → 呼叫中心 | 大模型故障时上报:记录故障状态 + 发布系统告警 + 向告警组播放紧急语音 |
| 大模型恢复上报 | ai.model.recover | knServer → 呼叫中心 | 大模型恢复时上报:清除故障状态 + 恢复系统告警 + 放行机器人入口(不放音) |
两接口共用同一通道:
URL: http://{cti_host}:12121/bridge/jsoncfg?opt=<opt>&json=<URL编码的JSON>
方法: GET 或 POST
2. 通用约定(两接口一致)
2.1 鉴权(由 /bridge/jsoncfg 容器统一处理)
- IP 白名单(
legitimate.servlet.client.ip.prefix)或 Basic Auth(legitimate.servlet.basic.auth)任一配置即启用; 127.0.0.1本机调用恒放行;- 两者都未配置时降级为全开放(服务端打 warn 日志)——生产环境请至少配置其一。
2.2 响应码(业务码在响应体,HTTP 状态码恒为 200)
响应体为纯文本,与 /bridge/callctrl 系列同风格:
| 响应体 | 含义 |
|---|---|
200 | 请求被接受(幂等,重复调用无害) |
400 | 请求体校验失败(如故障上报的 voiceKey 为空,或防御性类型校验失败) |
420 | 请求体 JSON 反序列化失败(容器统一行为,不会进入业务处理) |
不要用 HTTP 层判断成败,解析响应体文本。
2.3 engine 字段规约(两接口共用)
| 项 | 规约 |
|---|---|
| 类型 | 字符串,可选 |
| 语义 | 大模型引擎名(如 GLM-4),用于系统告警文案(#ENGINE 参数)与日志 |
| 清洗 | 服务端自动截断到 64 字符并滤除控制字符(含换行)——超长/含控制字符的值不会报错,但告警与日志按清洗后文本呈现 |
| 缺省 | 故障上报:缺省 = 通用紧急放音,不置大模型故障状态(见 §3.2);恢复上报:缺省 = 整体恢复,清除全部故障状态 |
3. 接口一:大模型故障上报
URL: http://{cti_host}:12121/bridge/jsoncfg?opt=emergency.voice.warn&json=<JSON>
JSON: {"voiceKey": "<语音配置键>", "engine": "<大模型引擎名>"}
3.1 请求字段
| 字段 | 必填 | 说明 |
|---|---|---|
voiceKey | 是 | 紧急放音的语音配置键(对应呼叫中心 service.properties 中的语音文件名,如 emergency.large.model.fault.voice)。为空时返回 400 且不置任何状态;非空但未配置对应语音文件时返回 200 且照常置状态,仅放音静默跳过 |
engine | 大模型场景必带 | 大模型引擎名。非空才会被识别为大模型故障上报(置故障状态+转换式告警+拦截机器人入口);空 = 通用紧急放音,与大模型无关 |
3.2 服务端行为(处理顺序,对接方需知)
voiceKey 为空? ──是──▶ 返回 400,什么都不做
engine 非空? ──是──▶ 记录大模型故障状态(★在放音限流之前,永不被限流跳过)
首次故障:发布系统告警 WARN_AI_MODEL_FAILURE(#ENGINE=engine)
已在故障中:只更新文案,不重复发告警
1小时内同 voiceKey 重复? ──是──▶ 跳过放音,返回 200(★状态已更新,不受影响)
播放紧急语音到告警组 ──(无在线告警目标/未配置语音文件时静默跳过,仍 200)
关键点:放音去重(1 小时/voiceKey)只作用于语音播放,不作用于故障状态记录——抖动型故障(故障→恢复→1 小时内再故障)的第二次上报即使被限流跳过放音,状态与告警也照常生效。
3.3 示例
# 大模型故障上报(带 engine = 大模型语义)
curl "http://{cti_host}:12121/bridge/jsoncfg?opt=emergency.voice.warn&json=%7B%22voiceKey%22%3A%22emergency.large.model.fault.voice%22%2C%22engine%22%3A%22GLM-4%22%7D"
# 响应体: 200
# 通用紧急放音(engine 缺省,不碰大模型状态)——knServer 正常情况下不用这个形态
curl "http://{cti_host}:12121/bridge/jsoncfg?opt=emergency.voice.warn&json=%7B%22voiceKey%22%3A%22emergency.fire.alarm%22%7D"
# 响应体: 200
# 错误示例:voiceKey 为空(带 engine 也一样)→ 400,不置状态
curl "http://{cti_host}:12121/bridge/jsoncfg?opt=emergency.voice.warn&json=%7B%22engine%22%3A%22GLM-4%22%7D"
# 响应体: 400
4. 接口二:大模型恢复上报
URL: http://{cti_host}:12121/bridge/jsoncfg?opt=ai.model.recover&json=<JSON>
JSON: {"engine": "<大模型引擎名>"} ← engine 可选
4.1 请求字段
| 字段 | 必填 | 说明 |
|---|---|---|
engine | 否 | 仅用于日志。带不带都清除全部故障状态(整体恢复语义:呼叫中心按"knServer 网关级"建模,引擎选择权在 knServer 侧) |
4.2 服务端行为
清除大模型故障状态
├─ 之前处于故障中:发布告警恢复事件(控制台 WARN_AI_MODEL_FAILURE 转为恢复),两个机器人入口放行
└─ 之前本来就正常:无任何副作用(幂等,重复调用/乱序调用无害)
不放音、不限流
4.3 示例
# 恢复上报(engine 缺省 = 整体恢复,推荐用法)
curl "http://{cti_host}:12121/bridge/jsoncfg?opt=ai.model.recover&json=%7B%7D"
# 响应体: 200
# 带引擎名(仅影响日志,效果同上)
curl "http://{cti_host}:12121/bridge/jsoncfg?opt=ai.model.recover&json=%7B%22engine%22%3A%22GLM-4%22%7D"
# 响应体: 200
5. knServer 对接契约(必读)
5.1 上报时机
| knServer 侧事件 | 动作 |
|---|---|
| 大模型故障(任一引擎不可用/网关不可用) | 调 emergency.voice.warn,必须带非空 voiceKey 与非空 engine,可重试(幂等) |
| 大模型恢复 | 调 ai.model.recover(engine 可缺省),可重试(幂等) |
| 重启后状态未知 | 建议重启完成即补发一次当前真实状态(故障则报故障,正常则报恢复),双向幂等保证安全 |
5.2 不成对上报的后果(为什么这是硬前提)
| 场景 | 后果 |
|---|---|
| 只报故障、漏报恢复 | 两个机器人入口持续拦截(排队客户全部走人工),直到恢复上报或呼叫中心重启。现场应急解锁:curl "http://{cti_host}:12121/bridge/jsoncfg?opt=ai.model.recover&json=%7B%7D"(幂等无害,无需重启) |
| 漏报故障 | 拦截不生效,行为同旧版本(呼叫照常进入机器人,可能沟通失败占住授权名额) |
| 呼叫中心重启 | 故障状态归零(与 TTS/ASR 熔断计数同语义);knServer 仍故障需再上报一次(放音去重窗口也随重启清零,不会被拦) |
5.3 对故障上报的补充事实
- 放音需要现场预配置
对应的语音文件名在 service.properties配置、.wav置于<confPath>/voice/目录、告警目标组warn.voice.to.ext.group已配置(或存在在线 FXS 分机)。三者缺一则放音静默跳过——但故障状态与拦截照常生效,语音只是给人听的配套广播,不是对接的依赖项。 - 告警文案:控制台告警编号 61(大模型故障告警),参数
#ENGINE取清洗后的 engine(缺省显示-)。
6. 联调验收清单
| # | 步骤 | 预期 |
|---|---|---|
| 1 | 健康状态下呼入排队(队列超阈值) | 呼叫进入机器人(与旧版一致) |
| 2 | knServer 上报故障(voiceKey+engine) | 返回 200;控制台出现 61 号告警(#ENGINE 正确);新排队呼叫不再进入机器人,继续排队等人工;排队中按 2 重播等待提示、不转机器人 |
| 3 | 1 小时内再报一次故障 | 返回 200;语音不再播(去重);状态与告警不变 |
| 4 | knServer 上报恢复 | 返回 200;控制台 61 号告警转为恢复;新呼叫恢复进入机器人 |
| 5 | 上报故障(engine 非空但 voiceKey 为空) | 返回 400;不置故障状态、不拦截(用于验证 knServer 侧参数校验) |
| 6 | 通用紧急放音(engine 空) | 正常放音与告警,不置大模型状态、不影响机器人入口 |
| 7 | (可选)大模型故障期间,若现场已配置意图预测 URL 且预测成功 | 状态自动清除、告警自动恢复(自愈);未配置预测 URL 的现场无此流量,恢复完全依赖接口二 |
7. 常见问题
Q:两个接口的 JSON 里字段名大小写敏感吗?
A:敏感。必须精确使用 voiceKey、engine(Gson 按字段名反序列化,不匹配等同字段缺省)。
Q:故障上报后多久拦截生效? A:即时。状态是进程内内存标志,上报成功(收到 200)的下一个排队触发即被拦截。已进入机器人沟通中的呼叫不受影响,只拦新进入。
Q:恢复上报需要与故障上报的 engine 一致吗? A:不需要。恢复是整体语义,任何恢复调用(带任意 engine 或不带)都清除全部故障状态。
Q:engine 名变了(如 GLM-4 → GLM-4.5)会影响恢复吗? A:不会,同上一条——不存在按引擎名配对的隐含契约。
Q:HTTP 层返回 401/403 是怎么回事?
A:jsoncfg 容器鉴权未通过(IP 白名单/BasicAuth)。knServer 所在服务器需加入 legitimate.servlet.client.ip.prefix 白名单,或改用 Basic Auth;本机(127.0.0.1)调用不受限。
契约事实源:PbxBusiness/src/com/pbxbusiness/voicewarn/json/JsonEmergencyVoiceWarn.java(类头 javadoc 与实现)、AiModelRecoverReq.java、EmergencyVoiceWarnReq.java、com.pbxbusiness.voicewarn.AiModelFaultState(单布尔网关级状态机);设计文档 docs/superpowers/specs/2026-09-13-robot-entry-ai-health-gate-design.md。本文与实现冲突时,以源码为准。