nl2query：用自然语言直接查询数据库的 AI 框架

场景引入：告别手写 SQL 的痛苦

凌晨两点，数据分析师小王接到紧急需求："帮我查一下泰坦尼克号数据集中，票价超过乘客'Alex'平均票价的女性幸存者名单。" 小王熟练地打开数据库客户端，陷入沉思：SELECT ... FROM ... WHERE fare > (SELECT AVG(fare) FROM titanic WHERE name LIKE '%Alex%') AND sex = 'female' AND survived = 1——这个查询不仅需要知道表结构，还要处理嵌套子查询。

但如果小王只需要说一句："list all female passengers who paid more than the average fare paid by passengers with 'Alex' in their name"，数据库就能自动返回正确结果呢？

这就是 nl2query 试图解决的核心问题：让任何人都能用自然语言直接与数据库对话，无需学习 SQL 或其他查询语法。

背景：Text-to-Query 领域的轻量化方案

nl2query 由独立开发者 Chirayu-Tripathi 开发，是一个将自然语言转换为数据库查询语句的 Python 框架。与 OpenAI 的 Text-to-SQL API 或 LangChain 的 SQL Agent 不同，nl2query 是一个本地运行的轻量级工具，核心模型是经过微调的 CodeT5+ 220M 和 Phi2。

这类工具的典型应用场景包括：

• 数据分析师：快速探索数据，无需记忆复杂语法
• 产品经理：直接查询业务数据库，降低技术门槛
• 低代码平台：为无编程经验的用户提供数据查询能力
• 内部工具开发：快速搭建"自然语言数据库助手"

项目采用 MIT 许可证，代码完全开源，用户可以自行部署到私有环境，避免将敏感数据发送给第三方 API。

技术原理：CodeT5+ 和 Phi2 如何理解你的问题

nl2query 的工作流程分为三个步骤：模式注入 → 预处理 → 模型生成。

模式注入（Schema Injection）

在生成查询之前，用户需要提供数据库的结构信息。对于 Pandas DataFrame，直接传入 DataFrame 对象即可；对于 MongoDB，需要提供集合的键名列表或完整的 JSON Schema；对于 Neo4j，需要提供节点标签和关系类型。

以 MongoDB 为例，用户传入集合的键名列表：

from nl2query import MongoQuery
keys = ['_id', 'passengerid', 'survived', 'Pclass', 'name', 'sex', 'age', 'fare']
queryfier = MongoQuery('T5', collection_keys=keys, collection_name='titanic')
queryfier.generate_query('which pclass has the minimum average fare?')

这个过程本质上是在告诉模型："数据库里有这些字段，你可以使用它们来构建查询。"

预处理（Preprocess）

在将问题发送给模型之前，nl2query 会对用户输入进行预处理。主要操作是将数据库的列名/键名嵌入到自然语言问题中，例如将 "which pclass has the minimum average fare?" 转换为包含字段信息的增强文本。这样做的目的是让模型在生成查询时能准确引用数据库的实际字段名，而不是猜测或产生幻觉。

模型生成（Model Generation）

CodeT5+ 220M 是一个 2.2 亿参数的小型代码生成模型，在大量代码数据上预训练后，再针对自然语言到查询语言的转换任务进行了微调。生成时支持多种解码策略：Beam Search（多候选生成）、Top-p 采样、Top-k 采样、重复惩罚等。Phi2 是一个 27 亿参数的微软小型语言模型，在该任务上性能更优，但需要 GPU 支持（通过 4-bit 量化降低显存需求）。

四大数据库引擎支持

nl2query 目前支持四种数据库/数据格式的查询生成：

1. Pandas DataFrame：PandasQuery 类直接接收 DataFrame 对象，生成 Python 表达式，支持 groupby 等聚合操作。

2. MongoDB：MongoQuery 类支持 CodeT5 和 Phi2 两种后端。Phi2 支持传入完整的 JSON Schema（可描述嵌套结构和索引信息），对复杂查询的生成效果更好。

3. Azure Data Explorer (Kusto)：KustoQuery 类接收列名列表和表名，生成 Kusto 查询语言语句，适用于 Azure 云上的时序数据和分析场景。

4. Neo4j Cypher：CypherQuery 类接收节点标签和关系类型列表，生成 Cypher 查询语言，可处理图关系查询。

快速上手：从安装到第一个查询

nl2query 支持 pip 一键安装：

python -m pip install nl2query

安装完成后，三行代码即可完成第一次自然语言查询：

from nl2query import PandasQuery
import pandas as pd

titanic = pd.read_csv('/path/to/titanic.csv')
queryfier = PandasQuery(titanic, 'titanic')
result = queryfier.generate_query(
    'list all people who paid more fare than the fare paid by "Braund, Mr. Owen Harris"'
)

如果使用 Phi2 模型（推荐），则需要 NVIDIA GPU 和 transformers 库，通过 4-bit 量化将显存需求控制在 4GB 以内。

局限与挑战

nl2query 并非银弹，存在几个需要注意的局限：

1. 模型能力上限：CodeT5+ 220M 是一个小型模型，面对复杂的嵌套查询、多表关联时能力有限。README 中明确提到 Phi2 的效果优于 CodeT5+，但 Phi2 需要 GPU 环境。

2. Schema 依赖性强：生成的查询质量高度依赖用户提供的数据库结构信息。如果 Schema 信息不完整或表述不准确，模型很容易生成错误的查询。

3. 无运行时验证：nl2query 本身只负责生成查询语句，不会自动执行或验证生成的查询是否正确。用户需要自己处理可能的语法错误或语义错误。

4. 缺乏生产级工具链：没有提供查询缓存、结果可视化、错误重试等生产环境所需的功能，更像是一个技术验证原型而非企业级产品。

行业意义：小模型在垂直领域的潜力

nl2query 的实践验证了一个趋势：在特定垂直领域（如 Text-to-Query），经过精心微调的小型模型（220M 参数）可以在消费级硬件上达到可用水平。这与当前"越大越好"的大模型军备竞赛形成对比。

对于企业内部数据工具场景，nl2query 的本地化部署特性尤为重要——金融、医疗等行业的敏感数据不适合发送到外部 API，本地运行的 nl2query 提供了一个合规的替代方案。