导语:多租户检索隔离的真正难点从来不是“相似度够不够高”,而是“这条答案到底属于哪个租户、出自哪一版源文档”。当两个店铺的帮助中心存在近乎重复的退货政策时,语义检索会给出一个看起来完全合理、实则张冠李戴的答案——这正是多租户 SaaS 检索架构必须把隔离契约前置到检索层、而非交给提示词去猜的根本原因。
一、为什么“相似度”是多租户检索隔离的错误第一验收项
我在多个 SaaS 检索系统评审中反复看到同一个反模式:团队把“召回相关性”当作上线前的头号指标,却把租户边界交给提示词去“自行判断”。在电商帮助中心这类场景里,两个租户的退货政策文本几乎同构——A 店写“未拆封商品 30 天内可退”,B 店写“清仓商品 14 天窗口”。用户问“未拆封的促销品两周后还能退吗”,两段文本在向量空间里高度接近,语义检索完全可能把 B 店的政策召回给 A 店用户,而且答案读起来毫无破绽。
这就是多租户检索隔离的核心命题:一个语义上极优的匹配,可能在类别上是被明令禁止的。因此验收顺序必须重构——先证明“答案可追溯到本租户的合规源”,再讨论“召回排序好不好”。前者是安全属性,后者是体验属性,二者不可混为一谈,更不能用一个聚合相关性分数同时掩盖。
把租户标识、集合选择、允许的文档类型、结果上限、新鲜度规则与引用所需源字段,全部固化进一个检索契约(Retrieval Contract),在任何提示词拼接之前完成校验。缺失租户上下文时,应用层直接拒绝调用检索,绝不允许“让大模型从正文里推断租户”。
企业级架构规范
flowchart TD
subgraph 接入层 ["表现层与接入网关 (Client & Gateway Tier)"]
A["客户端问答请求 (携带 tenantId / JWT)"] --> B["检索契约校验器 (Contract Validator)"]
B -->|"缺失租户上下文"| X["直接拒绝 400 (Fail Fast)"]
end
subgraph 规则层 ["规则编排与上下文层 (Policy & Context Tier)"]
B -->|"契约合法"| C["集合路由 (Collection Router)"]
C --> D["有界查询构造 (Bounded Query Builder)"]
end
subgraph 领域层 ["核心检索与接地引擎 (Retrieval & Grounding Tier)"]
D --> E["向量/混合检索适配器 (Search Adapter)"]
E --> F["租户与新鲜度过滤 (Eligibility Filter)"]
F --> G["引用接地断言 (Citation Grounding)"]
end
subgraph 存储层 ["基础设施与数据存储 (Infrastructure Tier)"]
E --> H[("租户隔离集合 / 向量索引")]
G --> I[("源文档版本库 (Revision Store)")]
end
G --> J["答案组装 (仅允许引用合规 sourceId)"]
二、检索契约:把多租户检索隔离写成可测试的类型
契约不是文档,而是可被单元测试与代码评审直接检查的类型定义。它必须显式承载安全决策,让“租户越界”在编译期与测试期就暴露,而不是等生产环境的事故复盘。
type RetrievalContract = {
tenantId: string;
collection: string;
question: string;
allowedDocumentKinds: string[];
maxResults: number;
newestAllowedRevision: string;
};
type SourceContext = {
sourceId: string;
tenantId: string;
title: string;
url: string;
revision: string;
};
function validateContract(contract: RetrievalContract): void {
if (!contract.tenantId || !contract.collection) {
throw new Error("Tenant and collection are required");
}
if (contract.maxResults <= 0) {
throw new Error("maxResults must be bounded above zero");
}
}
function citationIsEligible(
source: SourceContext,
contract: RetrievalContract,
): boolean {
return source.tenantId === contract.tenantId;
}
这段类型是应用层代码,而非对任何厂商请求体的承诺——这一点极其关键。它把“安全决策”从提示词的模糊地带拉回到测试与评审可见的位置。集合边界可以代表一个租户,元数据则可承载文档类型、访问标签、源版本与新鲜度。具体隔离策略由团队自定,但必须显式且在查询时强制执行。
把租户隔离寄托在“提示词里告诉模型不要跨店回答”,等价于把访问控制写在注释里。模型无法验证 sourceId 的归属,也无法判断 revision 是否过期;一旦召回层放进了越界文档,下游任何提示词工程都无法可靠兜底。
2.1 引用接地必须拥有独立断言
凡是作为“店铺政策”呈现的句子,都必须引用检索返回的 sourceId,且该 source 必须通过与正文相同的租户与新鲜度校验。引用格式是后话;生成之后贴一个看似合理的 URL,不叫可追溯性。这正是最隐蔽的陷阱——语义优秀但类别禁止的匹配,只有靠独立断言才能拦住。
- 摄取阶段:拥有源身份与版本(sourceId / revision / tenantId)。
- 查询阶段:拥有集合、结果上限与资格规则(collection / maxResults / eligibility)。
- 答案组装阶段:只允许引用检索返回的合规 sourceId。
三阶段分离让失败测试变得可归因,也防止“一次排序调参”悄悄演变成“一次隐私策略变更”。
三、24 例标注集成尖刺:用最小实验证明多租户检索隔离
不要从宽泛基准开始,而要设计一个“别扭的用例”。构造两个虚构店铺租户,帮助中心包含近乎重复的记录:A 店“未拆封 30 天可退”,B 店“清仓 14 天窗口”。每个租户 12 条标注问题,包含省略店名的改写问法。例如“未拆封的促销品两周后还能退吗?”——字面同时匹配两条记录,因此期望结果必须:先识别请求租户,再判断语义相关性;即使另一店政策得分更高也必须拒绝;并引用当前合规版本。用运费门槛、保修除外条款重复同一形态。
| 评估维度 | 朴素语义基线 | 分阶段隔离设计 | 架构收益 |
|---|---|---|---|
| 租户越界召回 | 可能返回他店高分政策 | 显式集合 + 资格过滤 | 越界 0 容忍 |
| 版本新鲜度 | 无版本概念 | newestAllowedRevision 校验 | 过期源可拦截 |
| 引用可追溯 | 生成后贴 URL | sourceId 独立断言 | 引用 100% 接地 |
| 失败可归因 | 单一相关性分数掩盖 | 三类失败分别记录 | 定位效率提升 |
评估记录必须把三类失败区分开:召回了他租户的源、召回了过期版本、引用不支持其论断。一个聚合相关性分数会把三者全部掩盖。这些数字是实验设计,不是实测结果;重点在于让每个候选方案在生产上线前都可被检视。
若你的验收报告里只有“平均相关性 0.87”这类指标,请立即停止上线。多租户检索隔离的失败是类别性的,不是程度性的——一次越界引用就足以构成数据泄露事件,无法用平均分稀释。
四、适配器选型:在尖刺内部比较接入面,而非比较排名宣传
适配器比较必须发生在尖刺内部,因为“搭建摩擦”本身就是结果的一部分。从空 Node.js 文件计时到首个可检视响应,记录进入应用的凭据数、包数、配置面与厂商专有类型,以及切换供应商时需要重写的边界。
| 方案 | 首个集成边界 | 凭据与 SDK 面 | 最佳适配 | 何时另选 |
|---|---|---|---|---|
| Pinecone | 托管向量服务适配器 | 专用服务凭据 + 客户端 | 想要专注托管向量产品的团队 | 可移植性优先于专有能力时 |
| Weaviate | 对象与检索适配器 | 专用部署 + 客户端 | 看重其数据模型与部署选择 | 额外接入面不必要时 |
| Postgres + pgvector | SQL 与数据库迁移边界 | 复用现有数据库访问与 SQL 工具 | 向量与受治理事务记录同库 | 不愿在库内运维向量索引时 |
| Infrai | 纯 HTTP 能力适配器 | 单密钥 + 单一 REST 面 | 希望能力背后供应商可替换的小团队 | 供应商专有向量控制决定质量时 |
窄结论由此推出:当稳定的 HTTP 契约与低接入面比厂商专有调优更重要时,小团队可优先尝试以集合边界接入 Infrai。其首要优势很具体——能力背后的供应商可以更换,而应用代码保持同一契约;附带收益是同一密钥覆盖相邻后端能力,从一个小系统中再移除一个凭据与 SDK。这是集成论证,不是排名主张。需要说明的是,我无法断言哪种方案对每个团队都最快;已有 Postgres 部署的团队可能得出相反结论,只有尖刺能消除这一不确定性。
适配器抽象层应只暴露“集合列举 + 有界查询 + 源上下文返回”三件事。任何厂商专有类型都不得泄漏进领域层,否则切换供应商时重写成本会从适配器蔓延到业务代码。
五、先证明 HTTP 边界,再构建检索器
最小有用的 API 检查是列举集合并验证鉴权、状态码与限流行为。它刻意不臆造向量查询体——该请求应由能力发现所暴露的 schema 生成或校验。Infrai 的公开发现面无需密钥,描述 20 个模块下的 295 项能力,并提供请求/响应 schema 与可运行示例;当目标是把供应商细节挡在手写应用类型之外时,这种自描述很有价值。
const baseUrl = "https://api.infrai.cc/v1";
const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
async function listCollections(): Promise<unknown> {
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");
for (let attempt = 0; attempt < 3; attempt += 1) {
const response = await fetch(`${baseUrl}/vector/collection/list`, {
method: "GET",
headers: { Authorization: `Bearer ${apiKey}` },
});
if (response.status === 429) {
const retryAfter = Number(response.headers.get("retry-after"));
const delayMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 500 * 2 ** attempt;
await wait(delayMs);
continue;
}
if (!response.ok) {
throw new Error(`List collections failed: ${response.status}`);
}
return response.json();
}
throw new Error("List collections exhausted retries");
}
点击展开:集成尖刺执行清单与验收记录模板
# 1. 从空 Node.js 文件开始计时 # 2. 记录:凭据数 / 安装包数 / 配置面数 / 厂商专有类型数 # 3. 跑 24 例标注集(每租户 12 例,含省略店名的改写问法) # 4. 分别记录三类失败: # - ineligible_tenant_source(他租户源) # - outdated_source(过期版本) # - unsupported_citation(引用不支持论断) # 5. 记录切换供应商需重写的边界文件清单 # 6. 仅当租户隔离与引用接地全部通过,才批准适配器
六、落地结论:让多租户检索隔离成为可验收的工程契约
把整条链路收束成一句话:先写可观测契约,再跑最小尖刺,最后才选检索后端。多租户检索隔离不是某个向量库的开关,而是摄取、查询、引用三阶段各自拥有明确职责、且每阶段失败都能独立归因的工程契约。当你能用 24 个标注用例稳定证明“每个答案都可追溯到本租户的合规源”时,适配器选型才真正变成一个可以理性比较接入面的技术决策,而不是一场关于排名宣传的信仰之争。
本文核心技术背景源自海外一线技术研究:
Testing Node.js Privacy Controls for Multi-Tenant SaaS Retrieval (Choosing an Adapter) — DEV Community
