AIAvatarKit Guardrails 护栏机制:并行拦截并实时纠正虚拟形象的错误回答
AIAvatarKit Guardrails 护栏机制:并行拦截并实时纠正虚拟形象的错误回答
AIAvatarKit 是一款帮你快速搭建 AI 对话虚拟形象的工具,而它的 Guardrails 护栏机制能在 LLM 回答出错时并行拦截、实时纠正——既能在提问进入模型前"拦下"危险输入,也能在虚拟形象正说到一半时"打断"并补上一句更正,让它像真人一样"抱歉,刚才说错了"。
🎯 AIAvatarKit Guardrails 护栏机制解决什么问题
大模型会一本正经地答错:说出不该说的内容、编造不存在的功能、或答非所问。在纯文本聊天里这无所谓,但面对语音对话的虚拟形象,一句错误答案会直接被"说"出来,难以挽回。
Guardrails 护栏机制就是虚拟形象的"安全网":
- 请求侧护栏(request):在调用 LLM 之前审查用户输入,可拦截(
block)或改写(replace)。 - 响应侧护栏(response):在 LLM 回答生成后审查,发现问题就打断正在播放的语音并说出更正。
🔄 请求护栏 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 流结束后才运行,但此时虚拟形象几乎肯定还在说话(生成只要一两秒,说几句话却要花更久)。纠正音频恰好落在"原音频还在播放"的窗口里,流水线借此把它切断:
- 护栏返回的纠正响应带有护栏名
guradrail_name; - 流水线照常合成这段音频,并在其元数据上打上
is_guardrail_triggered=True(见 pipeline 组装 chunk); - 适配器看到该标记,调用
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/ 响应侧自打日志)
📚 参考文档与源码路径
- 官方护栏文档:documents/guardrail.md
- 护栏基类与动作定义:aiavatar/sts/llm/base.py
- 并行评估实现(首个触发者胜出):apply_guardrails
- 打断标记与流水线:aiavatar/sts/pipeline.py
- 通道侧停止播放:aiavatar/adapter/websocket/server.py
掌握 applies_to 这个开关与 action 三种动作,你就能为 AIAvatarKit 虚拟形象织起一张并行拦截、实时纠正的护栏网。