XiYan-DBDescGen：让 Text-to-SQL 读懂你的数据库

痛点引入：Schema 是 Text-to-SQL 的隐形杀手

想象一下产品经理对你说：「帮我查一下上个月华东区域销售额最高的前 10 家门店，以及它们的客单价。」你对着数据库一顿操作，发现表名叫 s, 列名叫 amt、 region_cd、store_id，没有任何注释。你甚至不确定 amt 是含税还是不含税、人民币还是美元——这类问题，正是 Text-to-SQL 系统在实际落地时最常见的「最后一公里」难题。

XiYan-DBDescGen 来自阿里巴巴 XGenerationLab，专门解决这个痛点：它利用大语言模型自动分析数据库结构，在数据库缺乏显式注释的情况下，自动生成高质量的表描述和字段描述，从而显著提升 Text-to-SQL 的生成效果。

方法论：双过程粗细双向增强

项目采用了一种名为「双过程」（Dual-Process）的方法论，分为两个阶段：

第一阶段：粗到细（Coarse-to-Fine）

系统首先对数据库进行宏观理解，识别表与表之间的关联关系、字段的业务语义。它会：

1. 根据字段数据类型（数值型、字符串型、日期型等）进行初步分类
2. 判断字段属于「维度」还是「度量」——这是数据分析领域的基本概念
3. 识别时间字段的最小粒度（年/月/日/小时等）

第二阶段：细到粗（Fine-to-Coarse）

在理解每个字段之后，系统反过来生成全局性的数据库描述。它会综合表名、字段名、样本数据和已生成的字段描述，生成一段连贯的业务语义描述，让 Text-to-SQL 模型能够「读懂」这个数据库的业务背景。

在 BIRD Benchmark 上的实验结果表明：使用 XiYan-DBDescGen 自动生成的描述后，SQL 生成准确率比不使用描述提升了 0.93%，且达到了人类水平的 37%。虽然这个数字看起来不高，但考虑到自动生成描述完全不依赖人工介入，其工程价值依然显著。

核心技术栈

XiYan-DBDescGen 的技术实现构建在以下组件之上：

llama-index 是整个项目的核心框架。它提供了 LLM 与 SQL 数据库之间的标准接口（SQLDatabase 类），同时封装了与各类 LLM Provider 的对接逻辑。项目目前默认使用阿里云 DashScope 的通义千问（Qwen-Plus）作为 LLM 引擎，同时也支持其他 llama-index 兼容的 LLM。

SQLAlchemy 提供数据库连接和 Schema 反射能力，系统支持 SQLite、MySQL、PostgreSQL 和 SQL Server 四种主流数据库方言，通过统一的类型抽象层（TypeEngine）处理不同数据库的类型系统差异。

M-Schema 是项目自定义的数据模型，继承自 SQLAlchemy 的 SQLDatabase。它扩展了标准数据库 Schema，增加了字段描述（comment）、样本数据（examples）、业务分类（category）和维度/度量标记（dim_or_meas）等元信息。最终输出为 JSON 格式的 M-Schema 文件，可以直接供下游 Text-to-SQL 系统使用。

Prompt 工程是系统智能的核心。项目在 default_prompts.py 中预置了 13 类 Prompt 模板，覆盖字段类型判断、字段描述生成、表的业务理解、日期时间粒度识别等关键环节。每个 Prompt 都同时提供中文和英文版本，体现了对国际化场景的考量。

快速上手：三行代码生成数据库描述

项目代码量不大（根目录约 14 个文件），使用方式也非常直接。以下是完整的 Quick Start：

# 1. 连接数据库
import os
from sqlalchemy import create_engine
db_engine = create_engine('sqlite:///your_database.db')

# 2. 配置 LLM（以通义千问为例）
from llama_index.llms.dashscope import DashScope, DashScopeGenerationModels
dashscope_llm = DashScope(model_name=DashScopeGenerationModels.QWEN_PLUS, api_key='YOUR_API_KEY')

# 3. 生成 Schema 描述
from schema_engine import SchemaEngine
schema_engine = SchemaEngine(db_engine, llm=dashscope_llm, db_name='my_db', comment_mode='generation')
schema_engine.fields_category()
schema_engine.table_and_column_desc_generation()
mschema = schema_engine.mschema
mschema.save('./my_db.json')

对于大规模数据库，项目还提供了 parallel_main.py，支持多表并行处理，显著缩短大规模 Schema 增强的等待时间。

现有限制与改进空间

XiYan-DBDescGen 在学术研究和中小规模数据库场景下表现良好，但在实际部署中仍有一些需要注意的地方：

依赖外部 LLM API：项目目前硬编码了 DashScope 作为默认 LLM 调用方式，虽然 llama-index 支持多种 LLM Provider，但实际使用时需要自行修改 call_llamaindex_llm.py 来切换模型，缺少开箱即用的多模型对比支持。

无容器化和 Web UI：作为纯 Python 库，项目没有提供 Docker 镜像或 Web 界面，这使得它在团队协作场景下的部署门槛较高。对于不懂代码的业务人员来说，直接使用存在一定障碍。

评测基准的代表性：实验仅在 BIRD Benchmark 上验证，而 BIRD 主要覆盖英文场景。中文字段名、表名的自动描述效果尚未有充分的公开评测数据支撑。

API 限速风险：生产环境调用通义千问等商业 LLM API 时，需要考虑调用频率限制和成本控制，项目目前没有内置缓存或批量处理优化。

行业意义与增长趋势

Text-to-SQL 是大模型在数据库领域最直观的应用方向之一。随着自然语言到数据库查询需求的增长，自动 Schema 增强工具的价值将进一步凸显。XiYan-DBDescGen 由阿里巴巴 XGenerationLab 维护，该团队同时运营 XiYan-SQL 项目（二者形成上下游关系：XiYan-DBDescGen 生成 Schema 描述 → XiYan-SQL 使用描述生成 SQL），代表了工业界在 Text-to-SQL 全链路上的系统性布局。

从项目定位来看，XiYan-DBDescGen 填补了「数据库缺乏文档注释」这一普遍痛点，尤其适用于遗留数据库的 AI 增强改造、BI 平台的自然语言查询接入等场景。