SmartCall 電話客服如何實現 RAG:智能體知識庫的雙通道架構與擴展實踐
在一通电话里做 RAG:智能体知识库的双通道实现与扩展实践
SmartCall 開源 AI 客服的智能體知識庫以門控攔截與 function 工具調用兩條通道實現語音 RAG,並以音訊保持和 fail-open 機制處理檢索與模型搶答的競速。
简介: 本文深度解析 SmartCall 开源 AI 客服中语音场景下的 RAG 实现:直面 500ms 延迟即引发客户质疑的严苛约束,揭示其并非简单“检索+拼 Prompt”,而是一场与大模型抢答的实时竞速。详解双通道架构(门控拦截 vs 工具调用)、音频保持、陈旧守卫、fail-open 设计等核心机制,并提供半小时接入自有知识库的完整路径。(239字)
文本聊天里的 RAG,检索慢 500ms 用户基本感知不到;但在电话里,500ms 的空白足以让客户脱口而出「喂?还在吗?」。
这篇文章拆解 SmartCall(开源 AI 客服呼叫中心)中智能体知识库的完整实现:为什么它在语音场景下不是「检索 + 拼 Prompt」,而是一场和大模型抢答的竞速;以及如何在半小时内把你自己的知识库接进去。
一、先把问题说清楚:语音场景的 RAG 难在哪
1.1 教科书式的 RAG 流程在这里直接失效
标准的 RAG 链路是这样的:
用户提问 → 向量检索 → 片段拼进 Prompt → LLM 生成 → 返回答案
它能成立有一个隐含前提:生成发生在检索之后,生成时机握在我们手里。
但端对端实时语音大模型(OpenAI Realtime、阿里云百炼 Omni 这一类)走的是服务端 VAD 自动应答:音频全双工直连模型,用户话音刚落,模型侧就已经自己开始生成回复了 —— 等你的 ASR 转写文本回来、门控判完、检索跑完,模型的第一帧 PCM 可能早就推到了你的播放队列里,客户已经听到「呃,关于这个问题……」。
于是核心矛盾从「检索得准不准」变成了:
- 检索结果回来时,模型的自动应答已经在播;
- 你必须当场决定:是让它说完(知识库等于白建),还是掐掉重说(客户听到半截话)。
这是文本 RAG 从来不需要面对的问题。1.2 三条硬约束
| 约束 | 具体含义 | 设计后果 |
| --- | --- | --- |
| 延迟预算 | 单库检索必须 < 1.2s,端到端注入 < 1.5s | 检索必须并行、必须有硬超时、query 改写不能调 LLM |
| 绝不阻塞音频线程 | 拦截回调运行在模型事件线程上 | 门控只允许纯内存判定;任何 IO 一律切线程 |
| 绝不死寂 | 电话那头没声音 = 客户直接挂机 | 全链路 fail-open,任何失败都退化为「模型原样自答」 |
第三条是整个系统的第一设计原则。后面你会反复看到它:未命中不注入、超时用部分结果、异常吞掉放行、连「模型不支持指令」都有兜底话术。在电话场景里,「答得不够准」是可接受的降级,「没有声音」是事故。
二、整体架构:两条通道、一层 SPI
2.1 数据模型:一个智能体挂 N 个知识库
同一个智能体可以同时挂多个知识库,每个库独立选择通道、来源、门控与阈值。既可以让「资费库」走确定性门控,又让「售后长尾库」交给模型自主判断。
2.2 双通道:谁来决定「要不要查」
两条通道的差异是本质性的:
| 维度 | 通道 I:interceptor 门控 | 通道 T:function 工具调用 |
| --- | --- | --- |
| 谁决定检索 | 平台规则(关键词 / 疑问词 / 轮次 / 排除项) | 大模型自己 |
| 触发时机 | 用户转写一到就判定,与模型抢答 | 模型推理过程中发 function_call |
| 延迟特征 | 必须音频保持 + 硬超时竞速 | 模型主动等待工具结果,无需保持 |
| query 质量 | 平台侧窗口化拼接消解指代 | 模型自己补全指代(免费获得 query rewrite) |
| 配置成本 | 需要调门控规则 | 只需写好 description |
| 典型风险 | 门控过松 → 无效检索;过严 → 该查不查 | 模型不调用 / 乱调用;多一次协议往返 |
| 适用场景 | 高频、确定性强的业务问答(资费、退款、流程) | 长尾、语义模糊、需要模型权衡的问题 |
2.3 会话级装配:运行期零查库
装配发生在通话建立时(ProcessServiceImpl.realtime):
// 一次性加载 KB 列表(会话装配用,运行期不再查库)
List<agentknowledgedo> agentKbList = agentKnowledgeDao.listByAgentId(agentId);
// 知识库装配(与 skill 平行解耦)+ 合并 interceptors(合并后必须按 order 重排)/handlers
KbBundle kbBundle = knowledgeBaseRegistry.sessionKnowledge(agentKbList);
List<realtimeturninterceptor> interceptors =
CollUtil.unionAll(skillBundle.interceptors(), kbBundle.interceptors());
interceptors.sort(Comparator.comparingInt(RealtimeTurnInterceptor::order));
List<functioncallhandler> handlers =
CollUtil.unionAll(skillBundle.handlers(), kbBundle.handlers());
config.setTools(SkillRegistry.toolDefinitions(handlers));
KnowledgeBaseRegistry 做的事很简单,但有几个刻意的取舍:
- 通道 I 的所有库合并进一个拦截器,而不是每库一个。原因:音频保持窗口是会话级共享资源,多个拦截器各自
hold会互相延长窗口;并行检索也需要统一的超时预算和结果合并点。 - 通道 T 每库一个工具,各自带
code/description,让模型自主多选。 order = 9000,排在所有技能拦截器之后。技能(转人工、挂机等确定性动作)优先认领,知识库只做兜底增强。- 未配 KB 的智能体返回
KbBundle.EMPTY—— 不进拦截器链、不下发工具,行为与没这个功能时完全一致,零侵入。public record KbBundle(List<realtimeturninterceptor> interceptors, List<functioncallhandler> handlers) { /** 无 KB 配置时的空装配结果 */ public static final KbBundle EMPTY = new KbBundle(List.of(), List.of()); }
三、通道 I 深度拆解:门控 → 保持 → 竞速 → 注入
这是整个知识库最有含金量的部分。
3.1 六级门控:为什么全是字符串匹配
KbGate 是一个无状态单例,判定分两层。会话级预过滤(每轮一次):
| 层级 | 判定 | 目的 |
| --- | --- | --- |
| L2 | 归一化后长度 < 4 | 过滤「嗯」「哦」这类无实质内容 |
| L2 | 命中停用词(嗯/好/对/谢谢/再见……) | 过滤寒暄与确认 |
| L2 | 归一化后不含任何字母(noneMatch(Character::isLetter)) | 过滤纯号码、纯序号、纯标点 |
| L1 | 与上次命中轮次间隔 < 1 轮 | 冷却,避免复述时重复检索 |
| L1 | 归一化后与上次 query 相同 | 去重,避免转写切句导致连查两次 |
per-KB 门控(每个库独立判定):
| 层级 | 判定 | 目的 |
| --- | --- | --- |
| L6 | 命中 excludePatterns(如「转人工」「投诉」) | 排除项优先级最高,交给技能处理 |
| L4 | turnMin ≤ turnSeq ≤ turnMax | 轮次窗口(如「只在开场 3 轮内查产品库」) |
| L3 | keywords 领域关键词 / questionMarkers 疑问词 | 按 logic 组合:OR(默认)/ AND / KEYWORD_ONLY |
boolean kw = hitAny(cfg.getKeywords(), norm); // L3 领域关键词
boolean qm = hitAny(cfg.getQuestionMarkers(), norm); // L3 疑问词
return switch (Fc.toStr(cfg.getLogic(), "OR").toUpperCase()) {
case "AND" -> kw && qm;
case "KEYWORD_ONLY" -> kw;
default -> kw || qm; // OR:召回优先,误放由 similarity 阈值兜底
};
三个值得展开的点:
① 为什么全是纯内存字符串判定? 因为门控跑在模型事件线程上(红线 R1)。这里任何一次 HTTP、LLM 调用或 embedding 计算,都会直接拖垮音频投喂节拍和打断检测 —— 表现为「机器人反应变慢」「客户打断不停」。语义相似度的活儿交给检索之后的 similarity 阈值把关,不要在门口做。
② 为什么默认 OR(召回优先)? 误放的代价只是一次 1.2s 内的并行检索 + 阈值过滤,最坏结果是白跑一趟、模型照常自答;漏召的代价是知识库形同虚设,且这种问题极难被发现(用户只会觉得「这机器人什么都不知道」)。代价不对称时,选代价小的那一侧。
③ 归一化(StrMatchUtil.normalize)为什么必要? 语音转写的标点极不稳定,同一句话可能是「退款,怎么弄?」也可能是「退款 怎么弄」。匹配前统一去除标点、符号、分隔符与空白,关键词配置才能稳定命中。
3.2 音频保持(Audio Hold):整个设计的关键
门控命中后,拦截器做的第一件事不是检索,而是申请音频保持:
long seq = context.getTurnSeq().get(); // 陈旧守卫锚点
speaker.requestAudioHold(KbConstants.HOLD_MS); // 1500ms
ThreadUtil.execAsync(() -> retrieveAndInject(context, hit, userText, seq));
return false; // 恒不认领
会话侧(RealtimeCallSession)的实现只有三小块状态,且全部只在单线程控制循环里读写,因此无需任何同步:
/** 音频保持截止时间(ms),0=无保持 */
private long audioHoldUntil;
/** 保持期间的 PCM 缓冲(不投喂给 pacer,仅控制线程访问) */
private final ByteArrayOutputStream audioHoldBuffer = new ByteArrayOutputStream();
private void handleBotAudio(byte[] pcm) {
pipeline.archiveBotAudio(pcm); // 留档始终累积
receivedBytes += pcm.length;
if (interrupted) return;
// 音频保持期间:缓冲不投喂,等待异步判定结果
if (audioHoldUntil > System.currentTimeMillis()) {
audioHoldBuffer.write(pcm, 0, pcm.length);
return;
}
pipeline.feedBotAudio(pcm); // 正常路径:入匀速投喂队列
}
保持窗口有三种结局:
| 结局 | 触发事件 | 缓冲处理 | 客户听到 |
| --- | --- | --- | --- |
| 检索命中 | SkillInstruct | releaseAudioHold(true) 丢弃 + 抢断模型在途响应 | 基于知识库重新组织的应答 |
| 未命中 / 超时 | 巡检心跳发现窗口到期 | releaseAudioHold(false) 补投 pacer | 模型原自答,连贯播放,客户毫无感知 |
| 客户打断 | UserSpeechStarted | releaseAudioHold(true) 丢弃 | 客户自己的声音(barge-in 正常生效) |
「补投」是这套机制能落地的关键:模型音频并没有被丢掉,只是延迟了最多 1.5 秒入队。检索失败时缓冲整块喂回匀速投喂器,客户听到的仍是一句完整的话,只是起音稍晚 —— 而这个「稍晚」恰好被人类对话中正常的思考停顿掩盖了。
时序不变量:RETRIEVE_TIMEOUT_MS(1200) < HOLD_MS(1500)。 留出的 300ms 是给 instruct 的协议往返余量。若检索没能在 hold 内回来,hold 到期自动释放播原答,迟到的检索结果由陈旧守卫丢弃。两套超时互为兜底,系统里不存在「永久卡住」的路径。
3.3 「恒不认领」:return false 的艺术
RealtimeTurnInterceptor.interceptUserText 的契约是:返回 true 表示认领这句话 —— 会话会取消模型本轮自动应答,此后必须由拦截器自己驱动播报。
知识库拦截器永远返回 false。原因很直接:如果认领了,一旦检索未命中,你手上没有任何东西可播,等待你的就是死寂。
不认领意味着:模型继续生成(音频被 hold 缓冲着),检索命中后再通过 instruct 抢断替换。这是把「失败路径」设计成「默认路径」—— 乐观执行 + 可撤销,而不是悲观阻塞 + 必须成功。
3.4 上下文 query:为什么不用 LLM 改写
客户说:「那这个多少钱?」直接把这句拿去检索,必然一无所获。
业界通行做法是 query rewrite —— 再调一次 LLM 补全指代。但这里多一次 LLM 往返就是 300~800ms,直接吃掉整个延迟预算。
替代方案是窗口化拼接:把上一轮机器人说的话和本轮客户说的话拼在一起,截断到 500 字符:
private String buildContextualQuery(TurnContext context, String userText) {
String botText = context.getBotText();
String raw = Fc.isBlank(botText) ? userText : botText + " " + userText;
return StrUtil.subPre(raw, KbConstants.MAX_QUERY_CHARS);
}
成本 0ms,效果对向量检索和混合检索都够用:机器人上一句「我们这边有三款套餐」进了 query,「这个多少钱」就有了明确的锚点。
代价是 query 变长可能引入噪声。在电话短轮次场景下(机器人应答通常被 Prompt 约束在 2 句以内)几乎无副作用。如果未来轮次变长,正确的演进方向是「关键词抽取 + 原问」,而不是继续全文拼接。
3.5 并行检索:虚拟线程 + invokeAll 的部分结果语义
多个知识库必须并行查,且必须容忍其中一部分失败:
private List<kbchunk> parallelRetrieve(List<agentknowledgedo> hit, String query) {
List<callable<list<kbchunk>>> tasks = [hit.stream](http://hit.stream)()
.<callable<list<kbchunk>>>map(kb -> () -> {
try {
KbResult r = retrieverFactory.get(KbSourceEnum.of(kb.getSource()))
.retrieve(new KbQuery()
.setQuery(query).setTopK(kb.getTopNumber())
.setSimilarity(kb.getSimilarity())
.setMode(SearchModeEnum.of(kb.getSearchMode()))
.setConfig(kb.getSearchConfig()));
return r.hit(kb.getSimilarity())
? KbResult.filterByScore(r.getChunks(), kb.getSimilarity())
: List.of();
} catch (Exception e) {
// 单库失败不影响其他库
log.warn("[KB] 单库检索异常(fail-open), kbId={}==>>{}", kb.getId(), e.getMessage());
KbMetrics.error();
return List.of();
}
})
.toList();
List<future<list<kbchunk>>> futures;
try {
futures = kbExecutor.invokeAll(tasks, KbConstants.RETRIEVE_TIMEOUT_MS, TimeUnit.MILLISECONDS);
} catch (InterruptedException ie) {
Thread.currentThread().interrupt();
KbMetrics.timeout();
return List.of();
}
List<kbchunk> all = new ArrayList<>();
boolean timedOut = false;
for (Future<list<kbchunk>> f : futures) {
if (f.isCancelled()) {
timedOut = true; continue; } // 超时的库 → 跳过
try {
all.addAll(f.get()); // 已完成的库:get 立即返回
} catch (Exception e) {
KbMetrics.error();
}
}
if (timedOut) {
KbMetrics.timeout();
log.warn("[KB] 并行检索整体超时({}ms), 采用已到达的部分结果, 命中库数={}",
KbConstants.RETRIEVE_TIMEOUT_MS, hit.size());
}
return all;
}
执行器就是一行(JDK 21):
@Bean(name = KB_RETRIEVAL_EXECUTOR, destroyMethod = "shutdown")
public ExecutorService kbRetrievalExecutor() {
return Executors.newVirtualThreadPerTaskExecutor();
}
为什么是这个组合?把备选方案摆出来对比就很清楚了:
| 方案 | 问题 |
| --- | --- |
| ThreadUtil.execAsync + CountDownLatch + CopyOnWriteArrayList | 超时后孤儿任务继续在跑;COWList 每次写都全量拷贝;倒计时和结果收集全靠手工 |
| 固定大小平台线程池 | 需要定容;CallerRunsPolicy 会在池满时内联执行,直接绕过 invokeAll 的超时语义,把阻塞搬回调用线程 |
| CompletableFuture.allOf + orTimeout | allOf 是「全成才成」,一个库超时就丢掉全部结果;部分结果收集要自己写 |
| 虚拟线程 + invokeAll(tasks, timeout, unit) | 每任务一线程,无需定容排队;内建 bounded 等待;超时任务自动 cancel(true),不留孤儿;返回的 Future 全部 isDone —— 已完成的携结果、超时的 isCancelled,天然的部分结果语义 |
最后一列里「Future 全部 isDone」是个容易被忽略但至关重要的性质:正因如此,遍历时的 f.get() 才不会阻塞,「用已到达的部分结果」才是安全的。
fail-open 在这里有三层:单库异常 catch 成空 List(不牵连其他库)→ 整体超时用部分结果 → 上层拿到空结果就不注入。
> ⚠️ JDK 21 pinning 提醒:虚拟线程在 synchronized 块内做阻塞 IO 会「钉住」载体线程。Hutool HttpUtil、Feign 默认客户端都有这个特征。最坏情况是退化为类平台线程的行为,但不会 hang(每个检索器都有自己的 timeoutMs 兜底)。JDK 24 / JEP 491 已修复该问题。压测时可用 -Djdk.tracePinnedThreads=full 观察。
3.6 陈旧守卫:turnSeq 一票否决
检索是异步的,回来时世界可能已经变了:
// 陈旧/打断守卫:用户已开新句或本轮被打断 → 丢弃,不注入
if (context.getTurnSeq().get() != seq || context.isInterrupted()) {
KbMetrics.staleDropped(); // hold 超时自动释放,模型原音频继续
return;
}
if (Fc.isEmpty(merged)) {
KbMetrics.miss(); // fail-open:无命中→不注入→hold 释放→模型自答
return;
}
context.getSpeaker().instruct(KbPrompt.augment(merged, userText), KbConstants.FALLBACK_TEXT);
context.attr(KbConstants.ATTR_LAST_TURN, seq); // 记录已检索(冷却用)
context.attr(KbConstants.ATTR_LAST_QUERY, StrMatchUtil.normalize(userText)); // 记录归一化问法(去重用)
KbMetrics.hit();
客户完全可能在 1.2 秒内已经说了下一句,或者干脆打断了本轮。这时把上一问的知识片段注入进来,模型就会答非所问 —— 在语音场景里,「错位回答」比「不回答」更糟糕,因为它会让客户觉得机器人根本没在听。
另一个细节:ATTR_LAST_TURN / ATTR_LAST_QUERY 的写入放在守卫之后。只有真正注入成功才记录,否则冷却和去重会被一次「没成功的检索」污染 —— 客户重问一遍时反而被判定为重复而跳过。
跨轮状态一律走 TurnContext.attr(kb: 前缀,避让框架的 skill: 前缀),拦截器本身不持有任何 per-turn 可变字段。这是并发安全的前提(详见第七章踩坑 5)。
3.7 合并、封顶与 Prompt 模板
多库结果合并要做两件事:按正文去重(LinkedHashMap 保序)+ 总量封顶 6 条。封顶既控 token,也防 lost-in-the-middle —— 电话应答本来只需要 2 句话,塞 20 个片段纯属浪费。
注入用的 Prompt 模板值得逐字看:
private static final String AUGMENT_HEADER =
"你是电话客服。请【仅依据】下列“已知信息”回答用户问题;信息不足以回答时,"
+ "坦诚说明并自然引导,严禁编造。回答口语化、简短(≤2 句),适合语音播报。";
public static String augment(List<kbchunk> chunks, String userText) {
return AUGMENT_HEADER + "\n\n已知信息:\n" + formatChunks(chunks) + "\n\n问题:" + StrUtil.nullToEmpty(userText);
}
三个要点:
- 「【仅依据】」+「严禁编造」 —— 抗幻觉的标准手法,方括号强调在实测中比平铺直叙更有效。
- 「口语化、简短(≤2 句)、适合语音播报」 —— 文本 RAG 不需要这句,语音 RAG 必须有。书面语念出来非常怪;长段落播报不仅让客户失去耐心,还会让打断点变得难以预测。
- 「信息不足以回答时,坦诚说明并自然引导」 —— 给模型一个体面的退路。没有这句,模型在片段不相关时更倾向于硬编一个答案。
片段拼接格式统一为#### {title}\n{content},与 MaxKB 原生工作流的data字段同款,方便两边对比调试效果;拼接后按 5000 字符截断(对齐 MaxKB 的max_paragraph_char_number)。instruct的第二个参数是兜底话术 —— 当模型不支持指令驱动生成时,退化为原文朗读:try { session.speakInstruction(instruction); } catch (UnsupportedOperationException e) { session.speakText(fallbackText); // "这个问题我帮您确认一下,请稍等。" }
四、通道 T:把知识库变成一个工具
4.1 工具定义:description 不是备注,是路由提示词
@Override
public Map<string, object> toolDefinition() {
Map<string, object> params = new LinkedHashMap<>();
params.put("type", "object");
params.put("properties", Map.of("query", Map.of(
"type", "string",
"description", "要检索的用户问题;请补全指代(如把“这个”替换为上文的具体对象)后再传入")));
params.put("required", List.of("query"));
Map<string, object> tool = new LinkedHashMap<>();
tool.put("type", "function");
tool.put("name", kb.getCode()); // 模型路由键
tool.put("description", kb.getDescription()); // 模型判定「何时调用」的唯一依据
tool.put("parameters", params);
return tool;
}
这里有个很多人踩过的认知误区:数据库里那个 description 字段不是给运营人员看的备注,而是给模型看的路由提示词。
写成「退款知识库」,模型大概率不会调用;写成「当用户询问退款条件、退款进度、到账时间、退款金额计算方式时调用;不处理换货与投诉」,调用准确率立刻上来。同理,code 也要有语义(kb_refund 优于 kb_1),因为部分模型会参考工具名做判断。query 参数的 description 里还埋了一个钩子:「请补全指代后再传入」—— 让模型自己做 query rewrite。这次改写的成本已经付在模型那一次推理里,不额外增加往返。这正是通道 T 相对通道 I 的天然优势:通道 I 只能用窗口拼接去猜上下文,通道 T 直接拿到了模型理解后的完整问题。
4.2 执行与回传:triggerResponse 恒为 true
@Override
public void handle(FunctionCallRequest request, TurnContext context, Consumer<functioncallresult> callback) {
String callId = request.getCallId();
ThreadUtil.execAsync(() -> {
// handle 跑在模型事件线程,检索须切业务线程
String query = null;
try {
query = extractQuery(request.getArguments());
if (Fc.isBlank(query)) {
callback.accept(FunctionCallResult.success(callId, KbPrompt.noQuery()));
return;
}
KbResult r = retrieverFactory.get(KbSourceEnum.of(kb.getSource()))
.retrieve(new KbQuery()
.setQuery(query).setTopK(kb.getTopNumber())
.setSimilarity(kb.getSimilarity())
.setMode(SearchModeEnum.of(kb.getSearchMode()))
.setConfig(kb.getSearchConfig()));
String output = r.hit(kb.getSimilarity())
? KbPrompt.toolOutput(KbResult.filterByScore(r.getChunks(), kb.getSimilarity()), query)
: KbPrompt.noHit(query);
callback.accept(FunctionCallResult.success(callId, output).setTriggerResponse(true));
} catch (Exception e) {
log.warn("[KB] 工具检索异常(fail-open), code={}==>>{}", kb.getCode(), e.getMessage());
// 异常也 triggerResponse=true → 模型自答,绝不让模型干等
callback.accept(FunctionCallResult.success(callId, KbPrompt.noHit(query)).setTriggerResponse(true));
}
});
}
四种回传情况:
| 情况 | output 内容 | triggerResponse |
| --- | --- | --- |
| query 为空 / JSON 非法 | 提示模型补全后重调,或先自然地向用户询问 | true |
| 检索命中 | 片段 + 「请【仅依据】以下内容,用口语化、简短(≤2 句)的话术回答」 | true |
| 未命中 | 明确告知未检索到 + 「请基于你自身能力自然回答,不确定时坦诚说明」 | true |
| 检索异常 | 同上(走 noHit) | true |
为什么 triggerResponse 必须恒为 true? Function Calling 协议里,回传工具结果之后需要模型再生成一轮,那一轮才是客户听到的话。若置 false,模型拿到结果就停了 —— 客户什么都听不到。这就是通道 T 版本的 fail-open:绝不让模型干等。
另一个细节:异常时回传的是 success + noHit 文案,而不是 failure 结果。因为回传 error 会让部分模型进入「工具坏了」的重试循环,反而更慢、更不可控。把失败包装成一次「没查到」的正常语义,让对话继续往前走。
4.3 通道选型建议
| 场景 | 推荐 | 理由 |
|---|---|---|
| 高频核心业务问答(资费、退款、营业时间) | 通道 I | 不依赖模型的判断力,确定性高,且能压住模型的自由发挥 |
| 长尾、多库、需要模型权衡「查哪个」 | 通道 T | 省掉大量门控调优成本 |
| 强合规(必须严格按知识库口径回答) | 通道 I + 高 similarity + 严格 Prompt |
命中即抢断替换,不给模型自由发挥的机会 |
| 客户说话跳脱、转写质量差 | 通道 T | 模型能自己补全指代,抗噪能力更强 |
两条通道可以在同一个智能体里混用(一部分库走 I、一部分走 T)。但要注意:通道 T 的每个工具定义都会占用模型的 context,库一多就稀释注意力、拖慢推理。经验值是 function 库控制在 5 个以内,超出的部分改成通道 I 或合并成一个「综合检索」工具。
五、检索层:厂商中立的 SPI 设计
5.1 四件套:一个接口 + 三个值对象
public interface KnowledgeRetriever {
/** 本实现支持的来源 */
KbSourceEnum source();
/**
* 同步检索(调用方负责在业务线程池并行调度与超时控制)。
* @return 命中片段;无命中返回 chunks 为空的 KbResult(不返回 null)
*/
KbResult retrieve(KbQuery query);
}
@Accessors(chain = true)
public class KbQuery {
private String query; // 已上下文化的检索问题
private Integer topK; // 来自 AgentKnowledgeDO.topNumber
private Double similarity; // 阈值(部分来源服务端过滤,否则客户端过滤)
private SearchModeEnum mode; // embedding / keywords / hybrid
private SearchConfig config; // 来源专属配置
}
@Accessors(chain = true)
public class KbResult {
private List<kbchunk> chunks = new ArrayList<>(); // 无命中为空列表,不为 null
private Double bestScore; // 命中最高分,用于阈值闸门
/** 是否命中:有片段且(来源无分数 或 最高分达阈值) */
public boolean hit(double threshold) {
return Fc.isNotEmpty(chunks) && (bestScore == null || bestScore >= threshold);
}
}
@Accessors(chain = true)
public class KbChunk {
private String title; // 片段标题
private String content; // 片段正文(RAG 核心)
private Double score; // 相似度得分(可空:来源无分数时)
}
三条设计原则:
- 接口只有两个方法 ——
source()表明身份,retrieve()干活。没有生命周期、没有初始化、没有配置注入,实现者的心智负担极低。 - 实现类必须是无状态单例 —— per-KB 参数全部经
KbQuery传入,检索器不持有任何实例字段。这让它天然线程安全,也天然可被虚拟线程并发调用(一次通话可能同时打 5 个库)。 - 返回不 null,分数可 null ——
hit()里bestScore == null视为命中,把「三方服务不返回相似度分数」这个厂商差异收敛在一处,而不是散落到每个调用点。5.2 工厂自动注册:加来源不改工厂
Spring 把所有@Component public class KbRetrieverFactory { private final Map<kbsourceenum, knowledgeretriever> registry; public KbRetrieverFactory(List<knowledgeretriever> retrievers) { this.registry = [retrievers.stream](http://retrievers.stream)() .collect(Collectors.toMap(KnowledgeRetriever::source, r -> r)); } public KnowledgeRetriever get(KbSourceEnum source) { KnowledgeRetriever retriever = registry.get(source); if (retriever == null) { throw new KbRetrievalException("未支持的检索来源: " + source); } return retriever; } }KnowledgeRetriever实现注入成 List,按source()建索引。新增一个来源 = 新增一个@Component,工厂代码零改动。5.3 术语防腐层:厂商方言必须消化在边界内
内部全程只说public enum SearchModeEnum implements ArrayValuable<string> { EMBEDDING("embedding", "向量检索"), KEYWORDS("keywords", "全文关键词检索"), HYBRID("hybrid", "混合检索"); public String maxKBMode() { return "hybrid".equalsIgnoreCase(this.value) ? "blend" : this.value; } }embedding/keywords/hybrid;MaxKB 的hit_test只认blend,这个映射只在 smart-maxkb 适配层做一次,smart-aster与 Feign 契约全程使用内部术语。
为什么这么讲究?因为厂商术语一旦泄漏,就会渗透进数据库列、前端下拉、Feign DTO、日志和运维手册。如果search_mode字段里存了blend,将来换成 Dify / FastGPT / RAGFlow 时就得洗数据、改前端、兼容历史值。厂商方言必须在适配层边界内消化掉。
同类设计还有序列化:HitTestBO用 camelCase 写 Java 字段,靠全局 JacksonSNAKE_CASE策略自动序列化成query_text/top_number/search_mode,Java 侧一个下划线都不写。5.4 MaxKB 来源:一条完整的调用链
MaxKbRetriever (smart-aster) → Feign: KnowledgeSearchClient POST /feign/knowledge/hitTest → KnowledgeClientController (smart-maxkb) → KnowledgeServiceImpl 术语映射 hybrid→blend + DO→VO → Retrofit: KnowledgeApiClient POST admin/api/workspace/{wid}/knowledge/{kid}/hit_test → MaxKB Server 向量 / 全文 / 混合检索,按 similarity 降序返回段落
四个关键点:@RetrofitClient(baseUrl = "${maxkb.baseUrl}", path = "admin/api", readTimeoutMs = 1000) @Token public interface KnowledgeApiClient { @POST("workspace/{workspaceId}/knowledge/{knowledgeId}/hit_test") @Return List<kbparagraphdo> hitTest(@Path("workspaceId") String workspaceId, @Path("knowledgeId") String knowledgeId, @Body HitTestBO body); }
① 为什么中间要过一层smart-maxkb微服务,而不是让smart-aster直连 MaxKB? 为了把 Token 生命周期、baseUrl、账号密码、重试策略全部内聚在一处(MaxKBProperty+@Token+MaxKBTokenInterceptor)。smart-aster完全不感知鉴权;将来换知识库平台,只改这一个模块。
② 用hit_test而不是chat。hit_test只检索不生成。生成必须由通话侧的实时模型来做 —— 音色、打断、对话上下文、Prompt 全在它手上,MaxKB 生成的文本无法接入实时音频链路。这是语音 RAG 与文本 RAG 的一个重要分野:知识平台只负责「找」,「说」永远是实时模型的事。
③readTimeoutMs = 1000是显式收紧的。 同模块的 chat 客户端用的是readTimeoutMs = 0(无限等待,适合流式对话)。任何进入实时链路的 HTTP 客户端都必须有硬超时,否则一次网络抖动就是一通卡死的电话。
④ Token 自动续期。 Redisson 缓存maxkb:token(3 小时 TTL),拦截器发现业务码1002/1003(Token 过期)时删缓存重取并重试一次;HTTP 层的非 2xx 与 IO 异常由 retrofit 全局重试策略托管(间隔 100ms,最多 2 次)。业务代码里看不到一行鉴权逻辑。5.5 自定义 HTTP 来源:零代码接入三方知识库
CustomHttpKbRetriever的存在理由很实际:很多客户已经有自己的知识库、搜索服务或 ES 网关,不可能为了接个电话就把数据搬到 MaxKB。
它把「怎么调三方接口」全部变成配置:
|search_config字段 | 作用 | 默认值 |
| --- | --- | --- |
|url| 检索接口地址 | 必填,缺失抛KbRetrievalException|
|method|GET/POST|POST(GET 挂查询串,POST 发 JSON body) |
|headers| 请求头(含鉴权) | 无;严禁日志输出 |
|queryParamName| 检索问题在请求中的字段名 |query|
|extraBody| 附加固定参数(topK / mode 等) | 无;作为打底,被 query 覆盖同名字段 |
|resultPath| 响应中片段数组的取值路径 | 空 = 以根为数组;支持点号路径如data.records|
|titleField/contentField/scoreField| 片段字段映射 |title/content/score|
|timeoutMs| 单次检索硬超时 | 对齐RETRIEVE_TIMEOUT_MS,确保不超整体预算 |
一份可直接抄的配置示例(对接一个假想的内部检索服务):
解析层的健壮性设计值得单独说:{ "url": "https://kb.example.internal/api/v1/search ", "method": "POST", "headers": { "X-Api-Key": "${从配置中心注入,切勿硬编码}" }, "queryParamName": "question", "extraBody": { "top_k": 5, "index": "after-sale" }, "resultPath": "data.records", "titleField": "doc_title", "contentField": "snippet", "scoreField": "relevance", "timeoutMs": 800 }
- 元素类型自适应:数组元素是对象就按字段名映射;是纯字符串(如
["片段一", "片段二"])就整体当正文,无标题无分数。 scoreField缺失 →score = null→ 不做阈值过滤直接放行。很多三方服务根本不返回相似度分数,不能因此判为未命中。- 无正文的片段跳过 —— 没有
content的片段对 RAG 毫无价值。 - 非 2xx /
resultPath未命中 / JSON 解析失败 → 返回空KbResult+ warn,绝不抛异常打断通话。 headers只注入不落日志 —— 这是一条硬性红线,密钥泄漏的代价远大于一行调试日志的价值。5.6 留口的艺术:
SystemKbRetriever@Component public class SystemKbRetriever implements KnowledgeRetriever { @Override public KbSourceEnum source() { return KbSourceEnum.SYSTEM; } @Override public KbResult retrieve(KbQuery query) { log.warn("[KB] 系统知识库检索来源未接入, 返回空结果(fail-open), query={}", query == null ? null : query.getQuery()); return new KbResult(); } }source = 0(系统内置库)当期并未实现,但它仍然注册为 Bean。
为什么不能干脆不注册?因为那样KbRetrieverFactory.get(SYSTEM)会抛「未支持的检索来源」,一旦有人在后台误配了source = 0,通话会直接硬失败。
占位实现 + 降级返回,把配置错误的后果从「电话打不通」降到「效果不好」。后续接入真实的系统检索时,替换这个实现即可 —— 装配逻辑、调用链、工厂全部零改动。
这是给未实现的功能留扩展位时非常值得复制的一个模式。
六、扩展指南:四类扩展场景
6.1 扩展一个新的知识库来源(最常见)
以接入 RAGFlow 为例,四步搞定。
第 1 步:枚举加一项
public enum KbSourceEnum implements ArrayValuable<integer> {
SYSTEM(0, "系统"),
MAXKB(1, "MaxKB"),
RAGFLOW(2, "RAGFlow"), // ← 新增
CUSTOM(99, "自定义");
// ...
}
第 2 步:实现 KnowledgeRetriever
> 下面是示意代码:RagFlowApiClient / RetrievalReq / ChunkDTO 需按 RAGFlow 实际接口自行定义,组织方式建议对齐 smart-maxkb(独立适配模块托管 baseUrl、鉴权与重试)。sc.getDatasetId() 依赖第 3 步新增的配置字段。
@Slf4j
@Component
@RequiredArgsConstructor
public class RagFlowKbRetriever implements KnowledgeRetriever {
private final RagFlowApiClient client; // 建议走独立适配模块,同 smart-maxkb 的组织方式
@Override
public KbSourceEnum source() {
return KbSourceEnum.RAGFLOW;
}
@Override
public KbResult retrieve(KbQuery query) {
SearchConfig sc = query.getConfig();
if (sc == null || StrUtil.isBlank(sc.getDatasetId())) {
throw new KbRetrievalException("RAGFlow 检索配置缺失 datasetId");
}
// 术语映射在这里消化:内部 hybrid → RAGFlow 的 similarity_threshold + vector_weight
RetrievalReq req = RetrievalReq.builder()
.question(query.getQuery())
.topK(query.getTopK())
.similarityThreshold(query.getSimilarity())
.build();
List<chunkdto> chunks = client.retrieval(sc.getDatasetId(), req);
List<kbchunk> mapped = (chunks == null ? List.<chunkdto>of() : chunks).stream()
// ⚠️ 分数语义必须归一化到与 similarity 阈值同一量纲
.map(c -> new KbChunk().setTitle(c.getDocName())
.setContent(c.getContent())
.setScore(c.getSimilarity()))
.toList();
Double best = [mapped.stream](http://mapped.stream)().map(KbChunk::getScore)
.filter(Objects::nonNull).max(Double::compare).orElse(null);
return new KbResult().setChunks(mapped).setBestScore(best);
}
}
第 3 步:SearchConfig 加专属字段
// ── source=2 RAGFlow ──
/** RAGFlow 数据集 ID */
private String datasetId;
JSON 列 + JacksonTypeHandler 的好处在这里体现:加字段不用改表结构,老数据不受影响(新字段为 null)。
第 4 步:字典与后台配置
在字典表 KNOWLEDGE_SOURCE 加一项 2 = RAGFlow(前端下拉和列表翻译都靠它,实体上是 @Dict(name = "KNOWLEDGE_SOURCE")),然后在后台建知识库、选来源、填 search_config 即可。
实现时的四条铁律:
- 必须无状态 ——
@Component单例,不留任何实例字段,per-KB 参数一律从KbQuery取。 - 必须有自己的硬超时 —— 不要指望上游的
invokeAll超时来救你;invokeAll的cancel(true)只能中断阻塞点,如果底层 HTTP 客户端不响应中断,任务仍会占着虚拟线程。 - 异常一律抛
KbRetrievalException或返回空KbResult—— 由上游 fail-open 收敛,绝不让异常穿透到会话层。 - 分数语义要和
similarity阈值对齐 —— 这是最容易翻车的一条。如果厂商返回 0~100 的分数而后台阈值按 0~1 配,结果就是「永远命中」;反之则「永远不命中」。归一化必须在检索器内部完成,不要推给配置人员。6.2 扩展门控策略
- 加判定维度:在
KbTriggerConfig加字段(如intentTags、callerLevel、timeRange),在KbGate.matchKb加判定分支。配置字段自动兼容老数据。 - 想上语义门控(embedding 判意图)?别在门控里做。 正确姿势是新增一条通道,在异步侧用语义判定,门控只负责纯内存粗筛。门控一旦阻塞,整通电话的音频投喂和打断检测都会抖动,症状是「机器人变迟钝」「客户打断不停」,且极难定位。
- 门控规则的调优方法:先把
logic设为OR只配questionMarkers(怎么/为什么/能不能/多少钱……),保证召回;再逐步补keywords提精度;最后用excludePatterns把「转人工」「投诉」这类必须走技能的意图剔掉。6.3 扩展检索质量
按投入产出比排序:
| 优化 | 插入位置 | 注意事项 |
| --- | --- | --- |
| Rerank 重排 |parallelRetrieve之后、dedupAndCap之前 | 重排模型必须在 200ms 内返回,否则宁可不做 —— 预算只有 1.2s |
| 多路召回 + RRF 融合 | 给KbChunk加rank字段,在合并层做 reciprocal rank fusion | 向量召回擅长语义、关键词召回擅长专有名词(型号、政策编号),电话场景两者都需要 |
| Query 改写升级 |buildContextualQuery| 演进路径:窗口拼接 → 关键词抽取 → 异步 LLM 改写(通道 T 已免费获得) |
| 会话内结果缓存 |TurnContext.attr| key 必须含kbId+ 归一化 query;客户复述同一问题时省一次检索 |
| 片段裁剪 |KbPrompt.formatChunks| 长文档场景下截断到关键句,比塞整段更有效(语音应答只需 2 句话的信息量) |6.4 扩展观测
现在的KbMetrics是进程级LongAdder+snapshot(),够用于日志排查:
计数发生在并行业务线程,所以用private static final LongAdder HIT = new LongAdder(); // 命中并注入 private static final LongAdder MISS = new LongAdder(); // 无命中放行 private static final LongAdder STALE_DROPPED = new LongAdder(); // 陈旧/打断丢弃 private static final LongAdder TIMEOUT = new LongAdder(); // 检索超时 private static final LongAdder ERROR = new LongAdder(); // 检索/注入异常LongAdder而非AtomicLong(高并发下分段累加,竞争更小)。
接 Prometheus 的改造点:换成Counter/Timer,加agentId/kbId/source维度标签,重点盯四个指标:
| 指标 | 说明 | 异常时的动作 |
| --- | --- | --- |
|hit / (hit + miss)| 命中率 | 偏低 → 门控过严或阈值过高;偏高但客户满意度低 → 阈值过低放进噪声 |
|timeout占比 | 超时率 | 偏高 → 调大HOLD_MS/RETRIEVE_TIMEOUT_MS,或检查三方检索服务 |
|stale占比 | 陈旧丢弃率 | 偏高 → 检索太慢(客户等不及已开新句),或打断率高 |
| 检索 P95 耗时 | 容量规划依据 | 用于反推HOLD_MS的合理值 |
排查单通电话时,日志里已经带了channel、turnSeq、命中库数、片段数,按 channel 过滤即可还原完整时序。
七、踩坑清单
按「翻车严重程度」排序:
| # | 现象 | 根因 | 解法 |
| --- | --- | --- | --- |
| 1 | 电话突然死寂,客户挂机 | 检索器没设硬超时,invokeAll 的 cancel(true) 中断不了不响应中断的 HTTP 客户端 | 每个检索器内部必须有自己的 timeoutMs;readTimeoutMs 显式收紧,别用 0 |
| 2 | 客户听到半句话后被硬生生切断 | HOLD_MS < RETRIEVE_TIMEOUT_MS,模型音频已经播出去了,检索结果才注入 → 变成「自己打断自己」 | 守住时序不变量 RETRIEVE_TIMEOUT_MS < HOLD_MS,并留 300ms 协议余量 |
| 3 | 通道 T 的库模型从来不调用 | description 写成了给人看的备注(「退款知识库」) | 改写成「何时调用 + 覆盖哪些问题 + 不处理什么」的路由提示词 |
| 4 | 阈值配了 0.7,效果完全不对 | MaxKB 混合模式(blend)的综合得分区间是 0~2,可以 > 1 | 明确各来源的分数量纲,在检索器内归一化;后台文案标注取值范围 |
| 5 | 并发通话时 A 客户听到 B 客户的答复 | 拦截器持有了 per-turn 可变字段(多会话共享同一实例) | 拦截器每会话 new,配置用 List.copyOf 做 final 不可变快照,跨轮状态一律进 TurnContext.attr |
| 6 | 三方知识库密钥出现在日志里 | 调试时把整个请求(含 headers)打了出来 | headers 只注入不落日志,这是硬性红线;配置里的密钥走配置中心占位符 |
| 7 | 机器人整体变迟钝、客户打断不停 | 在门控里调了 embedding / LLM / HTTP,阻塞了模型事件线程 | 门控只允许纯内存判定(红线 R1);语义判定放到异步检索侧 |
| 8 | 检索线程越堆越多,内存缓慢上涨 | 用 CountDownLatch + 线程池做并行超时,超时后孤儿任务继续跑 | 改用 invokeAll(tasks, timeout, unit),超时任务自动 cancel(true) |
| 9 | 检索明明命中了,注入的却是上一问的答案 | 缺陈旧守卫,异步结果回来时客户已开新句 | 发起前锚定 turnSeq,注入前比对 turnSeq + isInterrupted |
| 10 | 客户重问一遍,机器人反而不查了 | 冷却/去重状态在检索未成功时也被写入 | ATTR_LAST_TURN / ATTR_LAST_QUERY 只在注入成功后记录 |
八、总结
回过头看,语音场景的知识库和文本 RAG 的差别,不在「检索算法」,而在工程约束:
- 本质矛盾不是「检索准不准」,而是「检索能不能赢过模型的自动应答」。 端对端实时模型的服务端 VAD 会抢答,所以整套设计的核心不是 pipeline,而是竞速 + 择机替换。
- 三个设计支点:
- fail-open —— 未命中、超时、异常、模型不支持指令,全部退化为「模型原样自答」。绝不死寂是最高优先级。
- 音频保持(Audio Hold) —— 把「阻塞式检索」变成「乐观执行 + 可撤销」。模型音频不丢弃只缓冲,赢了就替换,输了就补投,客户两种情况都听不到异常。
- 无状态 + 会话级装配 —— 拦截器每会话 new、配置 final 快照、跨轮状态进
TurnContext.attr、运行期零查库。这是高并发下不出串号事故的前提。
- 扩展性的三个正交边界:
- 触发通道(何时检索):
interceptor门控 /function工具调用 - 检索来源(去哪检索):
KnowledgeRetrieverSPI,加一个@Component即接入 - 门控策略(要不要检索):
KbTriggerConfigJSON 配置,加维度不改表
三者互不影响,可以各自独立演进。
一句话概括这套设计的哲学:把知识库做成一个「可以随时放弃」的增强,而不是一个「必须成功」的依赖。
在电话里,客户永远不会因为「机器人说不知道」而挂机,但一定会因为「电话那头没声音」而挂机。
- 触发通道(何时检索):
SmartCall 是一套基于 AI 大模型 + Asterisk 通信引擎的开源智能客服呼叫中心系统,支持端对端实时语音对话、IVR 可视化流程编排、智能外呼与智能体知识库问答。
- 🎯 开源地址:https://gitee.com/gdzWork/SmartCall
如果这篇文章对你有启发,欢迎点赞、收藏、关注三连;也欢迎到仓库点个 Star ⭐,这是我们持续迭代的最大动力。有问题评论区聊,我会尽量回复每一条。
來源:阿里雲開發者社區 AI · developer.aliyun.com