AIAvatarKit Guardrails 护栏机制:并行拦截并实时纠正虚拟形象的错误回答

原创2026-11-02 19:53:221,895 阅读

AIAvatarKit Guardrails 护栏机制:并行拦截并实时纠正虚拟形象的错误回答

AIAvatarKit 是一款帮你快速搭建 AI 对话虚拟形象的工具,而它的 Guardrails 护栏机制能在 LLM 回答出错时并行拦截、实时纠正——既能在提问进入模型前"拦下"危险输入,也能在虚拟形象正说到一半时"打断"并补上一句更正,让它像真人一样"抱歉,刚才说错了"。

🎯 AIAvatarKit Guardrails 护栏机制解决什么问题

大模型会一本正经地答错:说出不该说的内容、编造不存在的功能、或答非所问。在纯文本聊天里这无所谓,但面对语音对话的虚拟形象,一句错误答案会直接被"说"出来,难以挽回。

Guardrails 护栏机制就是虚拟形象的"安全网":

  • 请求侧护栏(request):在调用 LLM 之前审查用户输入,可拦截(block)或改写(replace)。
  • 响应侧护栏(response):在 LLM 回答生成后审查,发现问题就打断正在播放的语音并说出更正。

AIAvatarKit 语音对话流水线中 Guardrails 护栏机制所处的位置:在 LLM/Tools/Agent 环节前后并行拦截

🔄 请求护栏 vs 响应护栏:一个开关决定"拦截"还是"纠正"

护栏能否"阻止"回答,取决于挂载位置的开关 applies_to。

applies_to 运行时机 能阻止输出吗 适用场景
"request" 调用 LLM 之前 ✅ 能,block 直接终止 绝不能被问起的敏感输入
"response" 回答生成之后 ❌ 只能打断并纠正 可以"事后补救"的错误
"both" 两侧都运行 仅请求侧 同一策略管问和答

💡 为什么响应护栏不能"拦截"?因为 AIAvatarKit 采用流式输出:每生成一句就立刻合成并播出,这是"亚秒级响应"的来源。要等整个回答生成完再检查,就会牺牲首句速度——所以响应护栏选择"边说边改",这也是真人的自然反应。

⚡ 并行评估与"首个触发者胜出"

同一侧的多条护栏并行运行(源码用 asyncio 同时启动所有任务,见 apply_guardrails 实现)。最先返回 is_triggered=True 的护栏胜出,其余任务立即被取消:

  • 添加第二条护栏不会增加额外延迟;
  • 但顺序逻辑请写在同一条护栏内部,别依赖"某条护栏看到另一条的决策";
  • 永远只返回 is_triggered=False 的"观察型"护栏,永远不会赢得这场竞速,也就不会压制别的护栏。

🛠 三种动作 action:replace、block 与 warn

GuardrailRespose 携带一个 action,请求侧与响应侧的处理不同:

action 请求护栏 响应护栏
"replace" 请求文本被替换为 text 后再进 LLM 打断播放,改为播报 text
"block" 本轮短路:播报 text,不再调用 LLM 不做区分,等同 "replace"
其他(如 "warn") 什么都不做,请求原样通过 不做区分,等同 "replace"
  • 请求侧会识别 replace/block,不认识的动动作(如 warn)直接放行 → 天然得到"只记日志、不干预"的观察型护栏。
  • 响应侧不检查 action:只要触发就产生一次"纠正播报"。所以想在响应侧只观察,请在 apply() 里自己打日志并返回"未触发"。

🗣 实时打断语音:边说边改的关键机制

响应护栏在 LLM 流结束后才运行,但此时虚拟形象几乎肯定还在说话(生成只要一两秒,说几句话却要花更久)。纠正音频恰好落在"原音频还在播放"的窗口里,流水线借此把它切断:

  1. 护栏返回的纠正响应带有护栏名 guradrail_name;
  2. 流水线照常合成这段音频,并在其元数据上打上 is_guardrail_triggered=True(见 pipeline 组装 chunk);
  3. 适配器看到该标记,调用 stop_response() 停掉正在播放的内容,再送出纠正音频(见 WebSocket 适配器)。

不同通道的表现:

通道 触发 is_guardrail_triggered 时
WebSocket 先发 stop 再发纠正音频
Twilio Voice 停止播放再发纠正音频
Asterisk 停止播放(纠正音频不发送)
HTTP(SSE) 以 message_replace 替换已显示的文本

✍️ 因为纠正"迟到",请把它写得短小自洽——它会被插进一段已经说开的对话里。

🚀 快速上手:三步接入你的第一条护栏

一条护栏就是你自己的类,继承 Guardrail、实现 apply()、返回 GuardrailRespose,再挂到 llm.guardrails:

from aiavatar.sts.llm import Guardrail, GuardrailRespose

class SensitiveWordGuardrail(Guardrail):
    async def apply(self, context_id, user_id, text, files=None, system_prompt_params=None):
        if "违禁词" in text:
            return GuardrailRespose(
                guardrail_name=self.name,
                is_triggered=True,
                action="block",
                text="这个问题我不能回答哦~"
            )
        return GuardrailRespose(guardrail_name=self.name, is_triggered=False)

service.guardrails.append(SensitiveWordGuardrail(applies_to="request"))

最佳实践:把"廉价快速检查"(关键词表、自托管分类器)放在请求侧把最糟的输入挡在门外;把"昂贵检查"(如 LLM 评审)放在响应侧去兜住漏网之鱼——这样正常对话永远不用为它等待。

📌 适用场景清单

  • 🚫 拦截敏感/越权提问(request + block)
  • ✏️ 把不规范输入改写成标准措辞(request + replace)
  • 🙅 虚拟形象说出某关键词后立刻"口误纠正"(response)
  • 📊 只记录高风险对话用于审计(请求侧 warn / 响应侧自打日志)

📚 参考文档与源码路径

掌握 applies_to 这个开关与 action 三种动作,你就能为 AIAvatarKit 虚拟形象织起一张并行拦截、实时纠正的护栏网。

登录后查看全文
aiavatarkit