LangChain新增SchemagateRetriever：按需检索表格，Text-to-SQL提示词瘦身92.9%

Text-to-SQL 应用长期面临一个尴尬的现实：数据库越大，提示词越臃肿。把整库 schema 一股脑塞进 LLM 上下文，既浪费 token，又容易让模型在数十张表中「迷路」。LangChain 官方文档最新收录的 SchemagateRetriever 试图从检索层面解决这个问题——只把问题真正需要的表交给模型。

它解决什么问题：从「全量投喂」到「按需检索」

传统 text-to-SQL 流程中，开发者常把完整 DDL 拼进 prompt。当表数量达到 50 张以上时，提示词体积会迅速失控，模型选错表、写错 JOIN 的概率也随噪声上升。

SchemagateRetriever 的思路是检索而非硬塞：给定自然语言问题，它从 schema 目录中挑选少量相关表，并以 Document 形式返回这些表的 DDL。更关键的是，它只返回调用用户有权看到的表——权限过滤发生在检索阶段，而不是等模型生成 SQL 后再拦截。

据作者在 Reddit 帖中的说明，在包含 50 张以上表的 Snowflake 和 BigQuery schema 上测试（Spider 2.0 基准），提示词体积中位数缩减了 92.9%。表少的时候收益有限，在 BIRD 的七表数据库上仅缩减 8.8%。这也符合直觉：检索的价值随候选集规模增长而放大。

BM25 是一种经典的稀疏检索算法，基于词频（TF）与逆文档频率（IDF）对查询和文档做相关性打分，并用文档长度做归一化。它不依赖向量表示，计算成本低、可解释性强，在关键词匹配明确的场景（如表名、列名与问题中的实体重合）表现稳健。SchemagateRetriever 把 BM25 用于 schema 表的初筛，正是看中它对专有名词（表名、字段名）的精确匹配能力，而小型 embedder 则补充语义层面的模糊匹配。两者结合，既避免了调用大模型的开销，又比纯关键词检索更能覆盖同义表述。

Spider 2.0 是 text-to-SQL 领域广泛使用的评测基准，其特点是面向真实企业级数据库，schema 规模大、跨多个方言（如 BigQuery、Snowflake），单库表数常达数十甚至上百张，并包含复杂的多表 JOIN 与嵌套查询。相比早期 Spider 1.0 的小型学术数据集，Spider 2.0 更贴近生产环境，因此常被用来衡量 schema 检索与上下文裁剪方案在「大候选集」下的实际收益。文中 92.9% 的提示词缩减正是在这一基准的 50+ 表 schema 上测得，这也解释了为何小库场景收益不明显。

技术实现：离线选择，不调用模型

SchemagateRetriever 的选择过程完全离线，依赖 BM25 加一个小型 embedder，不发起任何模型调用。这一点对成本和延迟都友好：检索发生在 prompt 组装之前，不会引入额外的 LLM 往返。

它继承 LangChain 的 BaseRetriever，因此可以直接接入现有链式组合。作者给出的用法示例：

from schemagate import Catalog, Principal
from langchain_schemagate import SchemagateRetriever, prompt_fragment

cat = Catalog().bootstrap("postgresql://localhost/app")
retriever = SchemagateRetriever(
    catalog=cat,
    top_k=6,
    principal=Principal("okta:jdoe", roles={"finance"}),
)
docs = retriever.invoke("revenue by month")

返回结果是一张表一个 Document，每份 Document 包含该表的 DDL。由于是标准 BaseRetriever，它可以这样组合：

retriever | RunnableLambda(prompt_fragment) | prompt | llm

Principal 参数承载调用者身份与角色（示例中为 finance 角色），配合 top_k=6 控制候选表上限。这种设计把「谁能看哪些表」和「问题需要哪些表」两个维度合并进同一次检索，权限边界清晰。

BaseRetriever 是 LangChain 中检索器的抽象基类，定义了 invoke、batch 等标准调用接口，并返回 Document 对象列表。继承它意味着任何实现了该接口的组件都能无缝接入 LangChain 的 Runnable 协议，从而用管道符 | 与 prompt 模板、LLM、输出解析器组合成链。这也是 SchemagateRetriever 能与 prompt_fragment、prompt、llm 直接串联的原因——它把「选表」抽象成一次标准检索步骤，而非侵入式地改造 SQL 生成流程。

实测数据与能力边界

从作者公布的数字看，收益与数据库规模强相关：大 schema 上提示词缩减接近两个数量级的中位数水平，小 schema 上几乎无感。这意味着它更适合企业级多表环境，而非轻量应用。

需要留意的是，92.9% 与 8.8% 均为作者自测的中位数，且仅在 Spider 2.0 与 BIRD 的特定 schema 上得出，尚未看到第三方独立复现。作者本人也在帖中坦言，希望社区反馈「它在哪些地方选错了表」——检索召回失败是这类方案的核心风险：一旦正确的表没被选进来，后续 SQL 生成再强也无济于事。

与现有方案的差异

LangChain 生态里已有若干 schema 检索思路，SchemagateRetriever 的差异点在于三点：权限感知的检索（principal + roles）、离线轻量选择（BM25 + 小 embedder，无模型调用）、以及标准 Retriever 接口带来的可组合性。它没有试图替代 SQL 生成环节，而是专注做「上下文裁剪」这一件事。

安装方式为 pip install langchain-schemagate，源码托管在 GitHub（ashishsinha1602/schemagate），LangChain 文档已将其列入 Retrievers 分类。

适用场景与上手建议

对于表数量在数十张以上的分析型数据库，这个组件值得纳入 text-to-SQL 流水线评估。上手时建议重点验证两点：一是 top_k 取值与召回率的平衡，二是权限过滤是否覆盖了行级与列级的实际安全需求（当前示例展示的是角色级过滤）。

若你的数据库只有几张表，收益有限；若你正被超大 schema 的提示词成本困扰，它是一个低成本可试的检索层方案。作者在 Reddit 开放了讨论，检索错表的案例反馈对项目迭代尤其有价值。