DB-GPT 数据源指南支持的数据源、Text2SQL 原理与连接配置实战【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文基于 DB-GPT 官方文档《数据源》展开完整覆盖其支持的数据源类型、Text2SQL 工作流程、通过 Web UI 与 REST API 添加数据源的实操步骤并结合当前仓库源码深入剖析数据源参数持久化机制、SQLite 连接器实现与 Datasource REST API 细节帮助你在理解原理的基础上把自然语言数据问答真正跑起来。一、支持的数据源DB-GPT 可以连接多种数据源让你通过自然语言与数据库、电子表格和数据仓库交互。官方文档明确列出以下支持矩阵数据源类型状态SQLiteRelational内置默认MySQLRelational支持PostgreSQLRelational支持ClickHouseOLAP支持DuckDBAnalytical支持MSSQLRelational支持OracleRelational支持ExcelSpreadsheet支持CSVFlat file支持从源码结构看仓库实际提供的连接器覆盖面更广。数据源类型枚举定义在 DBType 枚举除上表类型外还包含数据源类型文件型数据库MySQL / OceanBase / Oracle / MSSQL / PostgreSQL关系型否GaussDB / openGauss / Vertica / Doris / StarRocks关系型 / OLAP否ClickHouse / HiveOLAP / 数据仓库否DuckDB / SQLite / Spark嵌入式 / 分析是is_file_dbTrueMaxCompute云数仓否TuGraph / Neo4j图数据库否每个连接器都有对应的独立实现文件位于 rdbms 连接器目录例如conn_mysql.py、conn_postgresql.py、conn_clickhouse.py、conn_duckdb.py、conn_oracle.py等对于方言特殊的数据库OceanBase、StarRocks、Vertica还单独提供了dialect/子目录。图数据库与 NoSQL 连接器conn_neo4j.py、conn_tugraph.py、redis.py则位于 datasource 根目录。二、工作原理Text2SQL 流程数据源连接建立后DB-GPT 通过 Text2SQL 管线将自然语言问题转化为 SQL 并执行。官方文档给出的流程如下具体步骤用户用自然语言提问Text2SQL引擎分析问题与关联 schema根据问题上下文生成SQL数据库执行查询结果被格式化并返回可选图表。以 SQLite 连接器为例schema 信息的采集依赖连接器的一组元数据方法如 conn_sqlite.py 中的get_fields()通过PRAGMA table_info获取字段、_sync_tables_from_db()从sqlite_master同步表与视图清单、table_simple_info()输出表名(列1,列2,...)形式的紧凑结构描述供模型使用。这些方法正是 Schema Linking 阶段自动将自然语言映射到表名和字段名的底层数据来源。三、添加数据源3.1 通过 Web UI官方文档给出的操作步骤与仓库 Database 界面 一致打开 DB-GPT Web UI在侧边栏进入Data Sources点击Add Data Source右上角按钮选择数据库类型并填写连接信息测试连接并保存。界面上以卡片形式展示所有可连接的数据源类型SQLite、MySQL、PostgreSQL、ClickHouse、DuckDB、Oracle、MSSQL、StarRocks、Vertica、OceanBase、Hive、TuGraph、Neo4j、Redis 等与源码中DBType枚举的注册结果一一对应。3.2 通过 REST API数据源连接也可以通过 REST API 管理端点定义见 Datasource API 文档操作方法端点创建数据源POST/api/v2/serve/datasources更新数据源PUT/api/v2/serve/datasources删除数据源DELETE/api/v2/serve/datasources/{datasource_id}查询单个数据源GET/api/v2/serve/datasources/{datasource_id}数据源列表GET/api/v2/serve/datasources所有请求需携带 API Key 认证Authorization: Bearer $DBGPT_API_KEY。例如删除一个数据源DBGPT_API_KEYdbgpt DATASOURCE_ID{YOUR_DATASOURCE_ID} curl -X DELETE http://localhost:5670/api/v2/serve/datasources/$DATASOURCE_ID \ -H Authorization: Bearer $DBGPT_API_KEY创建/更新时请求体为Datasource Object核心字段如下字段类型说明idstring数据源唯一标识db_namestring数据库名db_typestring数据库类型如sqlite、mysqldb_pathstring文件型数据库的文件路径db_host/db_portstring / int数据库主机与端口db_user/db_pwdstring数据库用户与密码commentstring数据库备注这些字段名并非凭空定义而是源码中参数持久化映射的直接结果。见下文 4.1 节的_persisted_state_mapping()。仓库还提供了完整的客户端示例 datasource_crud_example.py演示了通过dbgpt_client完成数据源增删改查的完整流程。3.3 通过 TOML 配置文件官方文档同时说明数据源连接也可以直接在 TOML 配置文件中设置。可参考仓库中的示例配置 dbgpt-app-config.example.toml 进行本地化配置对于需要容器化部署的数据源如 Hive仓库提供了对应的编排文件 hive docker-compose 示例并附带 Hive 集成测试 等验证脚本。四、源码剖析数据源参数与连接器机制4.1 参数基类与持久化映射所有数据源参数类都继承自 BaseDatasourceParameters位于dbgpt-core包它定义了三类关键能力db_url()抽象方法返回 SQLAlchemy 引擎连接串create_connector()根据参数实例创建对应连接器persisted_state()/from_persisted_state()负责参数在 DB-GPT 数据源服务数据库中的序列化与反序列化。其中_persisted_state_mapping()给出了一套标准的字段映射规则parameter.py参数类字段持久化字段hostdb_hostportdb_portuserdb_userpassworddb_pwddatabasedb_namepathdb_path无法归入上表的字段会被统一收纳进ext_config。另外persisted_state()对文件型数据库有一个贴心处理如果只有db_path而没有db_name会从文件路径中解析数据库名例如/path/to/db.sqlite会解析为sqlite_db即{db_type}_{文件名}形式。这也解释了 Web UI 中数据源命名规则——它恰好与 DBType.parse_file_db_name_from_path 的逻辑保持一致。4.2 以 SQLite 连接器为例SQLite 是 DB-GPT 内置默认数据源其完整实现在 conn_sqlite.py。参数类核心字段__type__ sqlite path: str dataclasses.field( metadata{ help: _( SQLite database file path. Use :memory: for in-memory database ), required: True, } ) check_same_thread: bool dataclasses.field(defaultFalse, ...) driver: str dataclasses.field(defaultsqlite, ...) def db_url(self, ssl: bool False, charset: Optional[str] None): return f{self.driver}:///{self.path}要点path为必填项支持:memory:内存库连接串形如sqlite:///path/to/file.dbcheck_same_thread默认False即允许连接跨线程共享便于 Web 服务多线程场景复用连接器通过auto_register_resource装饰器自动注册到 AWEL 资源中心ResourceCategory.DATABASE分类这正是 Web UI 中Data Sources卡片列表能够自动出现的机制。除标准连接器外该文件还提供SQLiteTempConnectorL242-L354基于临时文件创建一次性 SQLite 库close()时自动删除文件适合在沙箱内临时落表做数据分析。仓库中的 RDBMS 连接器测试 与 集成测试目录覆盖 MySQL、Oracle、ClickHouse、Doris、StarRocks、TuGraph 等可作为各连接器可用性验证的参考。五、Text2SQL 能力与效果优化DB-GPT 擅长将自然语言转换为 SQL 查询官方文档归纳了四大能力Schema linking—— 自动将自然语言映射到表名和字段名多轮对话—— 通过追问逐步修正查询图表生成—— 将查询结果可视化为图表和 dashboard微调—— 针对特定业务域提升 Text2SQL 准确率。提示为了获得更好的 Text2SQL 效果建议数据库表名、字段名和注释都尽量语义清晰。连接建立后可以直接通过chat_data模式对指定数据源发起问答。以 curl 为例DB_NAME为已添加的数据源名DBGPT_API_KEYdbgpt DB_NAME{your_db_name} curl -X POST http://localhost:5670/api/v2/chat/completions \ -H Authorization: Bearer $DBGPT_API_KEY \ -H accept: application/json \ -H Content-Type: application/json \ -d {\messages\:\show space datas limit 5\,\model\:\gpt-4o\, \chat_mode\: \chat_data\, \chat_param\: \$DB_NAME\}也可以直接使用 Python 客户端完整示例见 client_chat_example.pyfrom dbgpt_client import Client DBGPT_API_KEY dbgpt DB_NAME {your_db_name} client Client(api_keyDBGPT_API_KEY) res client.chat( messagesshow space datas limit 5, modelgpt-4o, chat_modechat_data, chat_paramDB_NAME )返回内容中会带有chart-view片段内含 SQL 与查询结果数据前端据此渲染表格与图表即流程图末端响应格式化步骤的落地形态。仓库还内置了多套可直接导入测试库的示例数据如 case_1_student_manager_sqlite.sql配合示例应用即可快速搭建 Text2SQL 演示环境。六、延伸阅读围绕数据源主题仓库中以下文档可继续深入Chat DB —— 与数据库对话Chat Excel —— 与 Excel 文件对话Chat Dashboard —— 生成数据看板Datasource Integrations —— 安装更多连接器Connections Module —— 深入理解数据源管理机制。掌握以上内容后你可以完成从选择数据源类型 → 通过 Web UI / REST API / 配置文件建立连接 → 理解 Text2SQL 从 Schema Linking 到图表输出的完整链路的完整闭环并基于源码中的参数映射与连接器注册机制为自定义数据库方言扩展新的连接器。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DB-GPT 数据源指南：支持的数据源、Text2SQL 原理与连接配置实战
DB-GPT 数据源指南支持的数据源、Text2SQL 原理与连接配置实战【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文基于 DB-GPT 官方文档《数据源》展开完整覆盖其支持的数据源类型、Text2SQL 工作流程、通过 Web UI 与 REST API 添加数据源的实操步骤并结合当前仓库源码深入剖析数据源参数持久化机制、SQLite 连接器实现与 Datasource REST API 细节帮助你在理解原理的基础上把自然语言数据问答真正跑起来。一、支持的数据源DB-GPT 可以连接多种数据源让你通过自然语言与数据库、电子表格和数据仓库交互。官方文档明确列出以下支持矩阵数据源类型状态SQLiteRelational内置默认MySQLRelational支持PostgreSQLRelational支持ClickHouseOLAP支持DuckDBAnalytical支持MSSQLRelational支持OracleRelational支持ExcelSpreadsheet支持CSVFlat file支持从源码结构看仓库实际提供的连接器覆盖面更广。数据源类型枚举定义在 DBType 枚举除上表类型外还包含数据源类型文件型数据库MySQL / OceanBase / Oracle / MSSQL / PostgreSQL关系型否GaussDB / openGauss / Vertica / Doris / StarRocks关系型 / OLAP否ClickHouse / HiveOLAP / 数据仓库否DuckDB / SQLite / Spark嵌入式 / 分析是is_file_dbTrueMaxCompute云数仓否TuGraph / Neo4j图数据库否每个连接器都有对应的独立实现文件位于 rdbms 连接器目录例如conn_mysql.py、conn_postgresql.py、conn_clickhouse.py、conn_duckdb.py、conn_oracle.py等对于方言特殊的数据库OceanBase、StarRocks、Vertica还单独提供了dialect/子目录。图数据库与 NoSQL 连接器conn_neo4j.py、conn_tugraph.py、redis.py则位于 datasource 根目录。二、工作原理Text2SQL 流程数据源连接建立后DB-GPT 通过 Text2SQL 管线将自然语言问题转化为 SQL 并执行。官方文档给出的流程如下具体步骤用户用自然语言提问Text2SQL引擎分析问题与关联 schema根据问题上下文生成SQL数据库执行查询结果被格式化并返回可选图表。以 SQLite 连接器为例schema 信息的采集依赖连接器的一组元数据方法如 conn_sqlite.py 中的get_fields()通过PRAGMA table_info获取字段、_sync_tables_from_db()从sqlite_master同步表与视图清单、table_simple_info()输出表名(列1,列2,...)形式的紧凑结构描述供模型使用。这些方法正是 Schema Linking 阶段自动将自然语言映射到表名和字段名的底层数据来源。三、添加数据源3.1 通过 Web UI官方文档给出的操作步骤与仓库 Database 界面 一致打开 DB-GPT Web UI在侧边栏进入Data Sources点击Add Data Source右上角按钮选择数据库类型并填写连接信息测试连接并保存。界面上以卡片形式展示所有可连接的数据源类型SQLite、MySQL、PostgreSQL、ClickHouse、DuckDB、Oracle、MSSQL、StarRocks、Vertica、OceanBase、Hive、TuGraph、Neo4j、Redis 等与源码中DBType枚举的注册结果一一对应。3.2 通过 REST API数据源连接也可以通过 REST API 管理端点定义见 Datasource API 文档操作方法端点创建数据源POST/api/v2/serve/datasources更新数据源PUT/api/v2/serve/datasources删除数据源DELETE/api/v2/serve/datasources/{datasource_id}查询单个数据源GET/api/v2/serve/datasources/{datasource_id}数据源列表GET/api/v2/serve/datasources所有请求需携带 API Key 认证Authorization: Bearer $DBGPT_API_KEY。例如删除一个数据源DBGPT_API_KEYdbgpt DATASOURCE_ID{YOUR_DATASOURCE_ID} curl -X DELETE http://localhost:5670/api/v2/serve/datasources/$DATASOURCE_ID \ -H Authorization: Bearer $DBGPT_API_KEY创建/更新时请求体为Datasource Object核心字段如下字段类型说明idstring数据源唯一标识db_namestring数据库名db_typestring数据库类型如sqlite、mysqldb_pathstring文件型数据库的文件路径db_host/db_portstring / int数据库主机与端口db_user/db_pwdstring数据库用户与密码commentstring数据库备注这些字段名并非凭空定义而是源码中参数持久化映射的直接结果。见下文 4.1 节的_persisted_state_mapping()。仓库还提供了完整的客户端示例 datasource_crud_example.py演示了通过dbgpt_client完成数据源增删改查的完整流程。3.3 通过 TOML 配置文件官方文档同时说明数据源连接也可以直接在 TOML 配置文件中设置。可参考仓库中的示例配置 dbgpt-app-config.example.toml 进行本地化配置对于需要容器化部署的数据源如 Hive仓库提供了对应的编排文件 hive docker-compose 示例并附带 Hive 集成测试 等验证脚本。四、源码剖析数据源参数与连接器机制4.1 参数基类与持久化映射所有数据源参数类都继承自 BaseDatasourceParameters位于dbgpt-core包它定义了三类关键能力db_url()抽象方法返回 SQLAlchemy 引擎连接串create_connector()根据参数实例创建对应连接器persisted_state()/from_persisted_state()负责参数在 DB-GPT 数据源服务数据库中的序列化与反序列化。其中_persisted_state_mapping()给出了一套标准的字段映射规则parameter.py参数类字段持久化字段hostdb_hostportdb_portuserdb_userpassworddb_pwddatabasedb_namepathdb_path无法归入上表的字段会被统一收纳进ext_config。另外persisted_state()对文件型数据库有一个贴心处理如果只有db_path而没有db_name会从文件路径中解析数据库名例如/path/to/db.sqlite会解析为sqlite_db即{db_type}_{文件名}形式。这也解释了 Web UI 中数据源命名规则——它恰好与 DBType.parse_file_db_name_from_path 的逻辑保持一致。4.2 以 SQLite 连接器为例SQLite 是 DB-GPT 内置默认数据源其完整实现在 conn_sqlite.py。参数类核心字段__type__ sqlite path: str dataclasses.field( metadata{ help: _( SQLite database file path. Use :memory: for in-memory database ), required: True, } ) check_same_thread: bool dataclasses.field(defaultFalse, ...) driver: str dataclasses.field(defaultsqlite, ...) def db_url(self, ssl: bool False, charset: Optional[str] None): return f{self.driver}:///{self.path}要点path为必填项支持:memory:内存库连接串形如sqlite:///path/to/file.dbcheck_same_thread默认False即允许连接跨线程共享便于 Web 服务多线程场景复用连接器通过auto_register_resource装饰器自动注册到 AWEL 资源中心ResourceCategory.DATABASE分类这正是 Web UI 中Data Sources卡片列表能够自动出现的机制。除标准连接器外该文件还提供SQLiteTempConnectorL242-L354基于临时文件创建一次性 SQLite 库close()时自动删除文件适合在沙箱内临时落表做数据分析。仓库中的 RDBMS 连接器测试 与 集成测试目录覆盖 MySQL、Oracle、ClickHouse、Doris、StarRocks、TuGraph 等可作为各连接器可用性验证的参考。五、Text2SQL 能力与效果优化DB-GPT 擅长将自然语言转换为 SQL 查询官方文档归纳了四大能力Schema linking—— 自动将自然语言映射到表名和字段名多轮对话—— 通过追问逐步修正查询图表生成—— 将查询结果可视化为图表和 dashboard微调—— 针对特定业务域提升 Text2SQL 准确率。提示为了获得更好的 Text2SQL 效果建议数据库表名、字段名和注释都尽量语义清晰。连接建立后可以直接通过chat_data模式对指定数据源发起问答。以 curl 为例DB_NAME为已添加的数据源名DBGPT_API_KEYdbgpt DB_NAME{your_db_name} curl -X POST http://localhost:5670/api/v2/chat/completions \ -H Authorization: Bearer $DBGPT_API_KEY \ -H accept: application/json \ -H Content-Type: application/json \ -d {\messages\:\show space datas limit 5\,\model\:\gpt-4o\, \chat_mode\: \chat_data\, \chat_param\: \$DB_NAME\}也可以直接使用 Python 客户端完整示例见 client_chat_example.pyfrom dbgpt_client import Client DBGPT_API_KEY dbgpt DB_NAME {your_db_name} client Client(api_keyDBGPT_API_KEY) res client.chat( messagesshow space datas limit 5, modelgpt-4o, chat_modechat_data, chat_paramDB_NAME )返回内容中会带有chart-view片段内含 SQL 与查询结果数据前端据此渲染表格与图表即流程图末端响应格式化步骤的落地形态。仓库还内置了多套可直接导入测试库的示例数据如 case_1_student_manager_sqlite.sql配合示例应用即可快速搭建 Text2SQL 演示环境。六、延伸阅读围绕数据源主题仓库中以下文档可继续深入Chat DB —— 与数据库对话Chat Excel —— 与 Excel 文件对话Chat Dashboard —— 生成数据看板Datasource Integrations —— 安装更多连接器Connections Module —— 深入理解数据源管理机制。掌握以上内容后你可以完成从选择数据源类型 → 通过 Web UI / REST API / 配置文件建立连接 → 理解 Text2SQL 从 Schema Linking 到图表输出的完整链路的完整闭环并基于源码中的参数映射与连接器注册机制为自定义数据库方言扩展新的连接器。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考