AI导哈

自然语言转SQL查询服务

一个基于本地LLMs的MCP服务器，将自然语言问题转换为PostgreSQL查询，适用于企业ERP系统等复杂数据库场景。

  • by noah-collins1
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 noah-collins1/NL2SQL

使用说明

A. MCP（模型上下文协议） 该服务器通过Ollama使用本地LLM将自然语言问题转换为PostgreSQL查询。将其连接到任何兼容MCP的客户端-- Librechat, 克劳德桌面版，或您自己的内部应用程序，让用户用简单的英语查询数据库。

服务器使用多阶段验证和修复管道，实现 SQL准确率92% 在2000+表的企业ERP上-完全在本地硬件上运行，没有云API调用。

平台： 所有设置和运行脚本的目标 Linux（Bash）.MOSX可能需要稍作调整才能工作；Windows需要WSL。

演出

数据库 表 问题 SQL准确性 注释
企业ERP 86 60 88.3% qwen2.5编码器：7b
企业ERP（扩展版，V2） 2377 500 SQL占92.0%，总体占86.6% V2考试：无证据，模糊评分；86.6%包括30个无法回答的歧义问题
TrulinX（真实ERP） 883 79 91.1% 真正的SQL Server ERP迁移到PostgreSQL

这些结果与 大型企业数据库 （一个包含8+模块的ERP系统）。这与基准测试不同，例如 鸟 该测试涵盖了跨越37个域的95个中小型数据库。看 基准环境 了解详情。

MCP集成

此服务器实现 模型上下文协议 并公开了三个工具：

工具 目的
nl_query SQL的自然语言——主要管道
query 执行原始SQL（角色门控：读/插入/写/管理）
checkpoint 数据库检查点管理（撤消/重做）

它还公开了用于模式浏览的资源(postgres://tables, postgres://tables/{name}/schema).

连接到LibreChat

将服务器添加到您的 librechat.yaml:

mcpServers:
  nl2sql:
    type: stdio
    command: npx
    args:
      - tsx
      - /path/to/nl2sql-project/mcp-server-nl2sql/src/stdio.ts
    env:
      DB_PASSWORD: "your_password"
      OLLAMA_MODEL: "qwen2.5-coder:7b"
    timeout: 60000

重新启动LibreChat。这 nl_query 工具将出现在工具列表中。

有关完整的LibreChat MCP配置详细信息，请参阅 Librechat MCP文档.

连接到克劳德桌面

添加到您的Claude Desktop MCP配置(~/.claude/mcp.json 或通过UI）：

{
  "mcpServers": {
    "nl2sql": {
      "command": "npx",
      "args": ["tsx", "/path/to/nl2sql-project/mcp-server-nl2sql/src/stdio.ts"],
      "env": {
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

连接到任何MCP客户端

服务器通过以下方式进行通信 标准 （标准输入/标准输出）。任何实现MCP客户端协议的应用程序都可以连接。入口点是 mcp-server-nl2sql/src/stdio.ts.

建筑

MCP Client (LibreChat, Claude Desktop, custom app)
     |  (MCP protocol over stdio)
     v
+---------------------------+     +---------------------+     +--------+
| TypeScript MCP Server     |---->| Python Sidecar      |---->| Ollama |
|                           |     | (FastAPI :8001)      |     | (LLM)  |
| 1. Module Routing         |     |                     |     +--------+
| 2. Schema Retrieval (RAG) |     | - Parallel K-SQL    |
| 3. Prompt Construction    |     |   generation        |
|    (glosses + linker +    |     | - Repair prompts    |
|     join planner)         |     +---------------------+
| 4. Multi-Candidate Eval   |
|    (validate + EXPLAIN +  |     +---------------------+
|     score + rerank)       |     | PostgreSQL          |
| 5. Repair Loop (max 3)   |---->| - Target DB (query) |
|    (surgical whitelist)   |     | - pgvector (RAG)    |
| 6. Execute on PostgreSQL  |     +---------------------+
+---------------------------+
     |
     v
  SQL Results (returned to MCP client)

快速开始

需要Linux/Bash。 看 先决条件 在......下面

# 1. Clone
git clone <repo-url> && cd nl2sql-project

# 2. Run the demo (~5 min — installs deps, sets up DB, runs 10 questions)
./demo/demo.sh

# 3. Or step by step:
./scripts/setup-deps.sh          # Check prereqs, install npm/pip, pull model
./demo/setup-db.sh               # Create DB, load data, populate embeddings
./scripts/start-sidecar.sh --bg  # Start Python sidecar
./demo/run-exam.sh               # Run full 60-question exam

先决条件

  • Linux （或Windows上的WSL）-所有shell脚本都使用Bash
  • PostgreSQL 14+，带pgvector扩展
  • Node.js>=18
  • Python>=3.10
  • Ollama（支持型号）

项目结构

nl2sql-project/
+-- config/                    # Unified YAML configuration
|   +-- config.yaml            # Default settings (committed)
|   +-- config.example.yaml    # Template for new setups
+-- mcp-server-nl2sql/         # TypeScript MCP server (core pipeline)
|   +-- src/                   # Source files
|   +-- scripts/               # Exam runners, embedding tools
+-- python-sidecar/            # Python FastAPI service (LLM interface)
+-- scripts/                   # Generic scripts (any database)
|   +-- setup-deps.sh          # Install prerequisites
|   +-- start-sidecar.sh       # Start/stop Python sidecar
+-- demo/                      # Demo databases + exams
|   +-- enterprise-erp/        # 86-table ERP schema, data, RAG setup
|   +-- schema_gen/            # 2000-table schema generation (Jinja)
|   +-- data_gen/              # 2000-table data generation
|   +-- exam/                  # Exam CSVs, templates, grading
|   +-- validation/            # DB validation scripts
|   +-- demo.sh                # One-command demo
|   +-- setup-db.sh            # DB setup orchestrator
|   +-- run-exam.sh            # Exam runner
+-- docs/                      # Documentation
+-- STATUS.md                  # Current performance numbers

配置

所有设置均已生效 config/config.yaml.用以下内容覆盖：

  • config/config.local.yaml （gitignored，用于本地秘密/调整）
  • 环境变量（名称与之前相同： OLLAMA_MODEL, DB_PASSWORD等等）

优先： ENV>config.local.yaml>config.yaml

看 docs/CONFIG.md 以获取完整参考。

主要特点

  • MCP服务器 --插入LibreChat、Claude Desktop或任何MCP客户端
  • 架构RAG --pgvector相似度搜索+BM25+RRF融合从2000中检索相关表+
  • 多候选人生成 --K个并行LLM调用（temp=0.3），确定性评分，无LLM判断
  • 手术白名单修复 --用于列错误（42703）恢复的两层门控
  • 管道升级 --模式注释、模式链接器、连接计划器、PG规范化、候选重新链接器
  • 模块布线 --关键字+嵌入分类将检索范围缩小到1-3个模块

SQL方言支持

该管道目前 PostgreSQL特定关键PG耦合组件：

|组件|PG特定？MySQL/SQLite会有什么变化| |-----------|-------------|-------------------------------------| |LLM提示|是--“生成PostgreSQL SELECT”|在提示模板中参数化方言| | sql_validation.ts （PG normalize）|是--将MySQL/Oracle语法转换为PG |按方言编写反向规范化器| |解释验证|是--使用 EXPLAIN (FORMAT JSON) |使用方言本地EXPLAIN| |pgvector（嵌入存储）|是--PG扩展|使用外部向量数据库（松果等）| | sql_validation.ts （验证器）|大多便携|交换PG特定危险功能列表| |模式自省|主要是可移植的|使用标准 information_schema |

如果你的目标数据库是MySQL，但你可以在RAG/嵌入层运行PostgreSQL，主要工作是交换提示模板和规范化器。pgvector嵌入存储和目标查询数据库今天位于同一个PostgreSQL实例上，但在架构上它们可以分开——RAG层只需要向量相似性搜索，而查询执行需要目标数据库。

看 docs/zhen-DIALECTS.md 获取方言支持的完整指南。

基准环境

我们的评估测试a 单个大型企业数据库 （一个ERP模式有86个基表，可扩展到20个部门的2377个表）。这衡量了系统处理以下问题的能力：

  • 大型模式检索（从2000+中查找正确的5-10个表）
  • 复杂的模块间连接（人力资源+财务+项目）
  • 肮脏/模糊的命名约定

这是对基准的补充，例如 鸟，测试范围 涵盖37个域的95个数据库 （医疗保健、金融、体育等）共有12751个问题。BIRD衡量跨领域泛化和外部知识需求。我们的基准测试衡量单个复杂模式中的深度。

基准 数据库 表（总计） 问题 焦点
我们的（86桌） 1 86 60 单数据库深度，企业ERP
我们的（2377桌，V2） 1 2377 500 大模式检索，无证据，歧义分级
我们的（TrulinX） 1 883 79 实际生产ERP（SQL Server迁移到PG）
鸟 95 ~5000 12751 跨域广度，脏数据
蜘蛛 200 ~1000 10181 跨域、干净的模式

文档

文档 描述
MCP_INTEGRATION.md 连接到LibreChat、Claude Desktop和自定义应用程序
建筑.md 分阶段管道演练+研究起源
CONFIG.md 完整的YAML配置参考
MODELS.md 测试模型以及如何交换
EXAMS.md 运行和创建考试
DateTimeDIALECTS.md SQL方言支持以及如何添加新方言
ADDING_A_DATABASE.md 如何添加新数据库
故障排除.md 常见问题和修复
REFACTOR_PLAN.md 未来的改进

运行考试

# 86-table (60 questions)
./demo/run-exam.sh

# 2,377-table V2 (500 questions, or subset)
./demo/run-exam.sh --db=2000
./demo/run-exam.sh --db=2000 --max=10

# TrulinX real ERP (79 questions)
./demo/run-exam.sh --db=trulinx

# Multiple runs for statistical mean (86-table only)
./demo/run-exam.sh --runs=3

许可证

国际学生中心

相关 MCP