服务器使用多阶段验证和修复管道，实现 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 |
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 && 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许可证
国际学生中心