第二个业务接入检索系统的那天,就是该建网关的日子。第一个业务自己拼管线没什么问题——快、贴身、好改;第二个业务照抄一遍,第三、第四个各拼各的,半年后盘点:权限过滤口径有三个版本,缓存策略有两套,审计日志一个都没有。这篇不讲「要不要做统一搜索入口」的平台叙事,只讲这个统一入口抽象层本身的工程设计:网关该管什么、接口长什么样、演进路上有哪些坑。网关的价值是口径统一——安全、质量、成本三本账只记一次。

网关的职责清单:六个格子
网关坐在业务与检索后端之间,所有检索流量从这里过。它的位置与六格职责如下图:
flowchart TD
B1["客服助手"] --> G
B2["内部搜索门户"] --> G
B3["Agent 检索工具"] --> G
subgraph G["RAG 网关:统一检索入口"]
direction TB
G1["鉴权与租户"]
G2["配额限流"]
G3["查询路由"]
G4["缓存"]
G5["审计日志"]
G6["评测埋点"]
end
G --> H1["向量库"]
G --> H2["BM25 索引"]
G --> H3["GraphRAG 后端"]
鉴权与租户:第一职责是把「业务身份」翻译成「语料可见范围」。调用方带着自己的用户体系来,网关统一对接身份源,在查询侧做权限过滤,保证任何调用方拿到的结果都已经在权限边界内。这层要设计成业务方没有能力绕过——权限过滤收进网关,等于把安全口径收归一处,业务代码里不再出现「我记得要加个权限过滤」这类依赖记忆的安全逻辑。身份到可见范围的映射要做缓存,但缓存失效要跟权限变更的传播对齐:权限收回的传播窗口是另一个专门话题,网关侧至少要做到映射变更后分钟级生效,别让查询侧成为权限体系里最迟钝的一环。
配额限流:按租户或业务设查询配额与并发上限,防止一个业务的突发流量把共享的检索后端打满。配额怎么分才公平,后面单讲。
查询路由:按查询特征——意图、语言、是否表格类——与租户配置,把请求路由到向量库、BM25 或 GraphRAG 等不同后端;后端故障时按降级顺序切换。路由规则是六格里业务语义最重的一格,也是最容易长成谜团的一格——规则要集中声明、可审计,别散在条件分支里。降级顺序要写成静态表:图后端不可用退向量检索,向量库不可用退关键词检索,全不可用返回明确错误而不是空结果——降级路径演练过一遍,故障夜的切换才不是即兴发挥。
缓存:语义缓存放网关侧统一做,命中一次省掉整条管线的成本。网关缓存有一条铁律:缓存键必须包含租户与权限范围。不同权限的调用方查询同一句话,答案的可见内容不同,共享缓存条目等于把权限系统打穿——这是网关缓存特有的坑,单机缓存时代不存在。失效策略也要统一管理:语料更新事件驱动失效,配比 TTL 兜底,两条腿都要有——纯 TTL 的语义缓存,会让过期答案在窗口期内继续被命中。
审计日志:谁在何时查了什么、命中了哪些来源、引用了什么、用的哪个配置版本,一次检索全链路留痕。审计不只是合规需要,它是 bad case 回放与评测集回流的数据底座——没有审计日志的网关,出了问题只能靠猜。
评测埋点:网关是所有查询的必经之路,也是埋点唯一正确的位置。在这里采样落查询日志、记录命中明细与延迟分布,检索质量、成本、安全三本账才有统一的数据来源。埋点要带业务标签——哪个租户、哪条路由、哪个配置版本,没有标签的埋点只能出总量报表,出不了归因结论。六个格子里,鉴权、审计、埋点三格不做将来一定补课,路由、缓存、配额三格做了立刻见效——优先级一目了然。
接口设计:两层 API 与结构化返回
接口分两层。retrieve 返回结构化候选,是可组合的底层——Agent 把它当工具调用,业务方拿结果自己组装;answer 返回整包答案,是省事的形态——业务方不想管管线细节时用。两层共享同一套鉴权、审计与埋点,区别只在网关替你做多少事。
retrieve 的返回必须结构化:每个命中带标识、标题、来源、分数明细与许可字段。分数明细(向量分、关键词分、rerank 分)让调用方能做业务重排,引用结构让答案层能做溯源,许可字段让下游不用再猜能不能引用。answer 走流式协议:正文 token 事件、引用事件、收尾事件三种——引用在正文之后独立下发,前端可以先渲染正文再挂引用,不至于让用户干等引用列表。形状大致如下:
// 网关两层 API 的形状:retrieve 可组合,answer 是整包
interface RetrieveRequest {
query: string;
topK: number;
scope?: Record<string, string[]>; // 元数据过滤,网关校验后透传
route?: "auto" | "vector" | "keyword" | "graph";
}
interface Hit {
chunkId: string;
docId: string;
title: string;
score: number;
scoreDetail: { vector: number; keyword: number; rerank: number };
source: { url?: string; license: string; updatedAt: string };
}
interface RetrieveResponse {
hits: Hit[];
routeTaken: string;
configVersion: string; // 本次检索用的配置快照版本,归因 bad case 靠它
traceId: string;
}
// 流式问答的三种事件:正文先走,引用随后,收尾带用量
type AnswerEvent =
| { type: "token"; text: string }
| { type: "citations"; hits: Hit[] }
| { type: "done"; usage: { latencyMs: number; tokens: number } };
三个设计要点藏在形状里。其一,scope 参数由调用方声明、网关校验后透传——业务方声明要哪类范围,网关核对声明是否越权,而不是把过滤条件原样转发给后端。其二,响应带 configVersion:bad case 归因时能对上「当时哪个配置在跑」,没有这个字段,事后讨论会停在没有结论的互相猜疑里。其三,接口带版本前缀,每个请求带 traceId 贯穿审计日志。版本升级沿用接口设计的常规纪律:只加不改,破坏性变更进新版本并给旧版本明确的退役时间表——网关是全站依赖,每一次破坏性变更都是全业务的协调事件。总原则一句话:语义参数进接口,实现参数留在网关内部——调用方说「要更深的相关性探索」,不说「把某个索引参数调到多少」。错误处理的约定同样属于接口契约:超时统一在网关侧收口,部分失败要显式表达——多路检索有一路失败时,返回可用结果并标注降级状态,而不是假装完整;错误码按「调用方下一步能做什么」分类(重试、换路由、上报),别把堆栈直接抛给业务方。
演进的坑:过早抽象、能力泄漏与配额公平
坑一:过早抽象。只有一个业务时设计的「通用接口」,抽象自想象而非差异;真正有价值的抽象要从第二个业务的差异里长出来——它需要的能力就是接口该支持的,它用不到的就不该进接口。这也是「第二个业务立项时建网关」这条时机建议的技术根据:那时第一个业务的管线已经暴露了哪些是共性、哪些是特例,抽象有了实物参照,不再是想象练习。过早抽象的症状有一份清单:接口里出现「预留字段」,文档里出现「将来可能支持」,参数默认值说不出来源——三样凑齐,说明抽象在设计未来而不是在服务现在。
坑二:后端能力泄漏。接口参数里长出图遍历深度、索引搜索参数、rerank 模型名这类后端专属字段,就是抽象失败的信号——调用方绑定了具体后端的实现细节,换后端就要破坏接口。正确做法是把能力翻译成语义档位:调用方要「更深的图扩展」就传一个抽象档位,网关内部再映射到具体后端的参数;后端换掉,映射改一处,接口不动。
坑三:多租户配额的公平。静态均分最简单也最不公平——轻业务用不满、重业务不够用,空闲配额不流转。常见的改良组合是按权重动态分配加突发队列,再给关键业务留低延迟通道;缓存命中是否计入配额要显式决定,建议计入——否则业务会通过微改编造查询绕过缓存判定来刷配额,配额制度反过来制造了它想防的浪费。配额分层还要给业务重要性留出表达空间:关键业务的配额不是更大,而是更高优先级——流量尖峰时牺牲的是低价值批处理,不是客服对话。三个坑与六格职责的对照如下:
| 职责 | 实现要点 | 常见错误 |
|---|---|---|
| 鉴权与租户 | 身份映射到可见范围,查询侧过滤 | 只在展示层挡,索引层裸奔 |
| 配额限流 | 权重分配加突发队列 | 静态均分,先到先得 |
| 查询路由 | 规则集中声明,语义档位 | 把后端参数当路由开关 |
| 缓存 | 键带租户与权限范围 | 跨租户共享答案条目 |
| 审计日志 | 查询、命中、引用、配置版本全留痕 | 只记错误不记命中 |
| 评测埋点 | 采样落日志,回流评测集 | 埋点只统计调用量 |
落地路径:从半成品收敛到网关
现实里网关很少从零建,多数是从第一个业务的「半成品管线」收敛出来。迁移前先补一步可观测:在现有管线上加统一的审计与埋点,摸清每个业务真实的查询量、延迟与命中分布——没有这份底账,收编的顺序与配额的初值全是拍脑袋。迁移分三步。第一步,剥横切面:把鉴权、审计、埋点从业务管线里抽出来,业务改为调网关的透传模式——行为不变,流量先进网关。第二步,收编缓存与配额:统一语义缓存,上租户配额,业务方的私有缓存下线。第三步,收编路由:多个检索后端挂到网关后面,业务方「指定后端」的参数降级为「指定能力档位」。每一步都不改变业务方的功能,只改变流量的路径;渐进收敛的可行性比推倒重建高一个数量级。
迁移期要有兼容纪律:旧接口保留别名一段时间,网关侧统计旧接口调用量,流量归零再下线。网关自身的高可用要按「全站检索的单一依赖」来设计——它挂了所有业务一起挂,部署、容量、降级方案都要按这个定位配,不能拿普通业务服务的标准对待它。还有一条组织层面的经验:网关的迁移本质是收权,收权的每一步都要给业务方看得见的补偿——省掉的维护工作、多出来的审计能力、共享的缓存收益;补偿讲清楚了,阻力就只剩技术问题,讲不清楚,阻力全来自组织。
小结
网关的价值是口径统一:安全口径——权限过滤与越权拦截只写一次;质量口径——评测埋点覆盖全部查询,评测集有活水;成本口径——配额与缓存的账记在同一处。六格里审计与埋点尤其值得先行:它们是其余四格的判断依据,也是网关从「代理」长成「资产」的种子。职责六格:鉴权租户、配额限流、查询路由、缓存、审计日志、评测埋点;接口两层:retrieve 可组合、answer 省事,结构化返回带分数明细、许可字段与配置版本;演进三坑:过早抽象、后端能力泄漏、配额不公平,对应的解法分别是等第二个业务再抽象、语义档位替代实现参数、权重分配替代静态均分。没有网关,每个业务都会长出自己的检索半成品;有了网关,半成品们收敛成一份资产。三本账只记一次的系统才管得住——这既是网关存在的理由,也是检验网关做没做成的标准。
读者留言
COMMENTS 暂无还没有留言,来说第一句?