DB-GPT 集成 DuckDB 数据源嵌入式分析型数据库接入与 Data Analyze 实战指南【免费下载链接】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 官方的 DuckDB 集成文档docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/integrations/duckdb_install.md展开带你完成 DuckDB 数据源在 DB-GPT 中的完整接入安装依赖、准备数据库、启动 Web 服务、在控制台配置数据源。DuckDB 是一个高性能的分析型数据库系统擅长快速高效地执行分析型 SQL 查询同时可以作为嵌入式分析型数据库使用。将 DuckDB 作为 DB-GPT 的数据源可以在一定程度上缓解向量数据库检索带来的不确定性并提升 SQL 问答链路中Schema → SQL → 结果的可解释性。读完本文你既能照步骤跑通接入流程也能从源码层面理解 DB-GPT 是如何通过 SQLAlchemy 把 DuckDB 封装进统一的RDBMSConnector体系的。一、为什么选择 DuckDB 作为 DB-GPT 数据源DB-GPT 的 Data Analyze数据分析场景依赖一个数据源连接器Connector来完成三件事反射reflection出库中的表结构供大模型理解 Schema、执行大模型生成的 SQL、回传查询结果。官方文档明确指出使用 DuckDB 实现数据源可以在一定程度上缓解向量数据库检索带来的不确定性与可解释性问题——因为 DuckDB 走的是真实 Schema 标准 SQL的确定性链路而非语义近邻检索。从源码结构看DuckDB 连接器位于 conn_duckdb.py它属于dbgpt-ext扩展包中的 RDBMS 连接器家族与 MySQL、PostgreSQL、ClickHouse、Hive、MaxCompute 等并列见 connector_manager.py 中on_init方法的集中导入逻辑。这一家族共用的基类是 base.py 中的RDBMSConnector与RDBMSDatasourceParameters。二、安装依赖按照文档第一步是通过uv同步工作区并安装datasource_duckdb附加依赖组uv sync --all-packages \ --extra base \ --extra datasource_duckdb \ --extra rag \ --extra storage_chromadb各 extra 的作用base提供核心运行时datasource_duckdb提供 DuckDB 驱动rag与storage_chromadb为知识库/向量存储场景配套该文档将 DuckDB 接入放在缓解向量检索不确定性的背景下因此一并安装 RAG 相关依赖。在 pyproject.toml 中datasource_duckdb依赖组的具体内容L70-L73为datasource_duckdb [ duckdb, duckdb-engine0.9.1, ]即包含duckdbPython 客户端与固定版本的duckdb-engineSQLAlchemy 方言适配层。这里duckdb-engine0.9.1是被锁定的精确版本意味着连接器代码是按照该方言版本的 API 编写和验证的。三、准备 DuckDB 数据库DuckDB 的特别之处在于它是嵌入式、文件型的分析数据库不需要像 MySQL 那样部署一个常驻的服务端进程一个.duckdb文件或.db文件就是一个完整的数据库。文档建议参考 DuckDB 官方安装指南来准备数据库文件。仓库中提供了两个可直接参考的素材示例数据库文件Walmart_Sales.db 位于docker/examples/dashboard/下是 DB-GPT Dashboard 场景的示例数据集可直接作为分析对象。迁移脚本duckdb2sqlite.py 展示了如何用duckdb.connect(文件路径)打开 DuckDB 文件、cursor.execute(SELECT * FROM 表)读数据并把结果表迁移到 SQLite。你可以把它当作最小可运行的 DuckDB 访问示例来阅读。准备好.duckdb/.db数据库文件后启动 DB-GPT 的 Web 服务。文档给出两种等价的启动方式uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml或uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml两种命令都使用 dbgpt-proxy-openai.toml 作为应用配置该配置通过 OpenAI 代理方式接入 LLM。服务默认监听 5670 端口浏览器访问http://localhost:5670即可进入 Web 控制台。四、在 Web 控制台配置 DuckDB 数据源服务启动后在 Web 界面的数据源管理页新建一个类型Type为duckdb的数据源。配置项不多但每一项都有对应的源码定义理解它们有助于排错pathDuckDB 文件路径必填指向 DuckDB 数据库文件的位置help 文案为 Path to the DuckDB file.。注意这是服务端运行 webserver 的机器能访问到的路径driver驱动名默认为duckdbhelp 文案为 Driver name for DuckDB, default is duckdb.。这些字段定义在DuckDbConnectorParameters数据类中conn_duckdb.py L24-L43。与 MySQL 等需要host / port / user / password的传统 RDBMS 不同DuckDB 参数类没有继承RDBMSDatasourceParameters而是直接继承BaseDatasourceParameters只保留path与driver两个字段——这正是嵌入式文件数据库在参数模型上的直接体现。DuckDbConnector的注册与标识L18-L50auto_register_resource( label_(DuckDB datasource), categoryResourceCategory.DATABASE, tags{order: TAGS_ORDER_HIGH}, description_(In-memory analytical database with efficient query processing.), ) dataclass class DuckDbConnectorParameters(BaseDatasourceParameters): __type__ duckdb path: str field(metadata{help: _(Path to the DuckDB file.)}) driver: str field(defaultduckdb, ...)auto_register_resource把它注册进 AWel 的资源注册表使其出现在前端选择数据源类型的下拉列表中控制台数据源类型列表即由此生成__type__ duckdb是前端/后端识别该类型的键标签label为 DuckDB datasource描述为 In-memory analytical database with efficient query processing.这些文案会直接展示在 Web 界面。五、源码纵深连接建立与 Schema 反射5.1 连接 URL 与 Engine 创建连接建立的入口是db_url()conn_duckdb.py L41-L43def db_url(self, sslFalse, charsetNone): Get the database URL. return f{self.driver}:///{self.path}注意 URL 格式是duckdb:///相对路径或duckdb:///{绝对路径}——没有user:passwordhost:port段。from_parameters直接把该 URI 交给RDBMSConnector.from_uri最终由 SQLAlchemy 的create_engine(duckdb:///...)构建引擎duckdb-engine提供了duckdb方言注册。此外还有一个面向本地文件的快捷构造classmethod def from_file_path(cls, file_path: str, engine_args: Optional[dict] None, **kwargs: Any) - RDBMSConnector: _engine_args engine_args or {} return cls(create_engine(duckdb:/// file_path, **_engine_args), **kwargs)db_type与db_dialect均声明为duckdbL49-L50用于 DB-GPT 内部按方言做 SQL 解析与图表化等处理。5.2 面向 LLM 的表结构反射table_simple_infoData Analyze 链路中把 Schema 喂给 LLM 的核心方法是table_simple_info()L111-L133。它的实现很有代表性_tables_sql SELECT name FROM sqlite_master WHERE typetable with self.session_scope() as session: cursor session.execute(text(_tables_sql)) ... for row in tables_results: table_name row[0] _sql f PRAGMA table_info({table_name}) ... results.append(f{table_name}({,.join(table_colums)});)从源码结构看它查询的是sqlite_master系统表并用PRAGMA table_info取列名——这是 SQLite 方言的做法。之所以 DuckDB 连接器可以复用这一套查询是因为 DuckDB 与 SQLite 在系统表sqlite_master与PRAGMA上保持了相当高的兼容性DuckDB 本身即以嵌入式场景设计兼容 SQLite 的诸多接口。最终每个表被压缩为表名(列1,列2,...);这样的紧凑字符串正是 DB-GPT 拼入 SQL 生成 Prompt 的 Schema 描述形式。5.3 其余元数据方法同一文件还实现了若干RDBMSConnector接口约定方法方法行为说明get_users()(L72-L82)查询sqlite_master中名为duckdb_sys_users的表DuckDB 文件库默认无此表通常返回空列表get_grants()(L84-L86)固定返回[]嵌入式文件库无权限体系get_collation()/get_charset()(L88-L94)固定返回UTF-8简化处理get_table_comments()(L96-L109)从sqlite_master取name, sql返回 (表名, 建表 SQL) 对其中table_simple_info与get_users的实现细节由单测 test_conn_duckdb.py 覆盖测试用临时文件创建连接器验证get_users() []、get_charset() UTF-8、table_simple_info() []以及执行SELECT 42能正确返回[42]——覆盖了元数据反射与 SQL 执行两条主链路。5.4 连接器是如何被服务加载的DB-GPT 服务启动时数据源管理器会通过导入触发各连接器的资源注册。在 connector_manager.py 的on_init()中可以看到from dbgpt_ext.datasource.rdbms.conn_duckdb import DuckDbConnector # noqa: F401也就是说只要你按第二节安装了datasource_duckdb依赖DuckDbConnector就会被导入并注册DuckDB datasource 随即出现在 Web 控制台的数据源类型选项里。若依赖未安装该导入会失败——这也是排查下拉框里没有 duckdb 选项问题的第一落点。六、验证与排错清单依赖检查uv sync --all-packages --extra base --extra datasource_duckdb后确认环境中可import duckdb与duckdb_engine对应 pyproject.toml 中的duckdb与duckdb-engine0.9.1。路径检查确认path填写的是 webserver 所在主机上的路径且文件可读文件型数据库不存在路径可达性问题时的连不上多为路径错误或文件被其他进程独占。启动检查uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml启动后访问http://localhost:5670在数据源管理页选择 duckdb 类型填入 path 后先点连接测试再保存。行为验证新建会话选择 Data Analyze 应用提问示例数据库如 Walmart_Sales.db中的简单统计问题若生成的 SQL 执行成功说明引擎创建、Schema 反射table_simple_info与执行链路全部打通。七、适用前提与限制本文流程以当前仓库代码为准DuckDB 连接器位于dbgpt-ext扩展包依赖组datasource_duckdb锁定duckdb-engine0.9.1升级该方言版本前应先回归 test_conn_duckdb.py 相关测试。DuckDB 数据源本质是文件型嵌入式数据库参数模型中没有 host/port/user/password也没有权限与多租户概念get_grants恒为空不适合替代服务端数据库做多人并发写入场景其定位是轻量、即开即用的分析型数据接入。table_simple_info、get_users等方法复用sqlite_master/PRAGMA语法这是从源码结构看对 DuckDB 与 SQLite 系统接口兼容性的依赖若未来 DuckDB 变更系统表行为这些方法需要优先检查。小结按照 官方 DuckDB 集成文档 的三步走——安装datasource_duckdb依赖、准备.duckdb数据库文件、启动 webserver 并在控制台配置 path——即可让 DuckDB 成为 DB-GPT 的数据源。其底层实现集中在 conn_duckdb.pyduckdb:///path形式的连接 URL、auto_register_resource注册、基于sqlite_master与PRAGMA table_info的紧凑 Schema 反射共同构成了嵌入式分析库 确定性 SQL 链路在 DB-GPT 中的完整落地。【免费下载链接】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 集成 DuckDB 数据源：嵌入式分析型数据库接入与 Data Analyze 实战指南
DB-GPT 集成 DuckDB 数据源嵌入式分析型数据库接入与 Data Analyze 实战指南【免费下载链接】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 官方的 DuckDB 集成文档docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/integrations/duckdb_install.md展开带你完成 DuckDB 数据源在 DB-GPT 中的完整接入安装依赖、准备数据库、启动 Web 服务、在控制台配置数据源。DuckDB 是一个高性能的分析型数据库系统擅长快速高效地执行分析型 SQL 查询同时可以作为嵌入式分析型数据库使用。将 DuckDB 作为 DB-GPT 的数据源可以在一定程度上缓解向量数据库检索带来的不确定性并提升 SQL 问答链路中Schema → SQL → 结果的可解释性。读完本文你既能照步骤跑通接入流程也能从源码层面理解 DB-GPT 是如何通过 SQLAlchemy 把 DuckDB 封装进统一的RDBMSConnector体系的。一、为什么选择 DuckDB 作为 DB-GPT 数据源DB-GPT 的 Data Analyze数据分析场景依赖一个数据源连接器Connector来完成三件事反射reflection出库中的表结构供大模型理解 Schema、执行大模型生成的 SQL、回传查询结果。官方文档明确指出使用 DuckDB 实现数据源可以在一定程度上缓解向量数据库检索带来的不确定性与可解释性问题——因为 DuckDB 走的是真实 Schema 标准 SQL的确定性链路而非语义近邻检索。从源码结构看DuckDB 连接器位于 conn_duckdb.py它属于dbgpt-ext扩展包中的 RDBMS 连接器家族与 MySQL、PostgreSQL、ClickHouse、Hive、MaxCompute 等并列见 connector_manager.py 中on_init方法的集中导入逻辑。这一家族共用的基类是 base.py 中的RDBMSConnector与RDBMSDatasourceParameters。二、安装依赖按照文档第一步是通过uv同步工作区并安装datasource_duckdb附加依赖组uv sync --all-packages \ --extra base \ --extra datasource_duckdb \ --extra rag \ --extra storage_chromadb各 extra 的作用base提供核心运行时datasource_duckdb提供 DuckDB 驱动rag与storage_chromadb为知识库/向量存储场景配套该文档将 DuckDB 接入放在缓解向量检索不确定性的背景下因此一并安装 RAG 相关依赖。在 pyproject.toml 中datasource_duckdb依赖组的具体内容L70-L73为datasource_duckdb [ duckdb, duckdb-engine0.9.1, ]即包含duckdbPython 客户端与固定版本的duckdb-engineSQLAlchemy 方言适配层。这里duckdb-engine0.9.1是被锁定的精确版本意味着连接器代码是按照该方言版本的 API 编写和验证的。三、准备 DuckDB 数据库DuckDB 的特别之处在于它是嵌入式、文件型的分析数据库不需要像 MySQL 那样部署一个常驻的服务端进程一个.duckdb文件或.db文件就是一个完整的数据库。文档建议参考 DuckDB 官方安装指南来准备数据库文件。仓库中提供了两个可直接参考的素材示例数据库文件Walmart_Sales.db 位于docker/examples/dashboard/下是 DB-GPT Dashboard 场景的示例数据集可直接作为分析对象。迁移脚本duckdb2sqlite.py 展示了如何用duckdb.connect(文件路径)打开 DuckDB 文件、cursor.execute(SELECT * FROM 表)读数据并把结果表迁移到 SQLite。你可以把它当作最小可运行的 DuckDB 访问示例来阅读。准备好.duckdb/.db数据库文件后启动 DB-GPT 的 Web 服务。文档给出两种等价的启动方式uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml或uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml两种命令都使用 dbgpt-proxy-openai.toml 作为应用配置该配置通过 OpenAI 代理方式接入 LLM。服务默认监听 5670 端口浏览器访问http://localhost:5670即可进入 Web 控制台。四、在 Web 控制台配置 DuckDB 数据源服务启动后在 Web 界面的数据源管理页新建一个类型Type为duckdb的数据源。配置项不多但每一项都有对应的源码定义理解它们有助于排错pathDuckDB 文件路径必填指向 DuckDB 数据库文件的位置help 文案为 Path to the DuckDB file.。注意这是服务端运行 webserver 的机器能访问到的路径driver驱动名默认为duckdbhelp 文案为 Driver name for DuckDB, default is duckdb.。这些字段定义在DuckDbConnectorParameters数据类中conn_duckdb.py L24-L43。与 MySQL 等需要host / port / user / password的传统 RDBMS 不同DuckDB 参数类没有继承RDBMSDatasourceParameters而是直接继承BaseDatasourceParameters只保留path与driver两个字段——这正是嵌入式文件数据库在参数模型上的直接体现。DuckDbConnector的注册与标识L18-L50auto_register_resource( label_(DuckDB datasource), categoryResourceCategory.DATABASE, tags{order: TAGS_ORDER_HIGH}, description_(In-memory analytical database with efficient query processing.), ) dataclass class DuckDbConnectorParameters(BaseDatasourceParameters): __type__ duckdb path: str field(metadata{help: _(Path to the DuckDB file.)}) driver: str field(defaultduckdb, ...)auto_register_resource把它注册进 AWel 的资源注册表使其出现在前端选择数据源类型的下拉列表中控制台数据源类型列表即由此生成__type__ duckdb是前端/后端识别该类型的键标签label为 DuckDB datasource描述为 In-memory analytical database with efficient query processing.这些文案会直接展示在 Web 界面。五、源码纵深连接建立与 Schema 反射5.1 连接 URL 与 Engine 创建连接建立的入口是db_url()conn_duckdb.py L41-L43def db_url(self, sslFalse, charsetNone): Get the database URL. return f{self.driver}:///{self.path}注意 URL 格式是duckdb:///相对路径或duckdb:///{绝对路径}——没有user:passwordhost:port段。from_parameters直接把该 URI 交给RDBMSConnector.from_uri最终由 SQLAlchemy 的create_engine(duckdb:///...)构建引擎duckdb-engine提供了duckdb方言注册。此外还有一个面向本地文件的快捷构造classmethod def from_file_path(cls, file_path: str, engine_args: Optional[dict] None, **kwargs: Any) - RDBMSConnector: _engine_args engine_args or {} return cls(create_engine(duckdb:/// file_path, **_engine_args), **kwargs)db_type与db_dialect均声明为duckdbL49-L50用于 DB-GPT 内部按方言做 SQL 解析与图表化等处理。5.2 面向 LLM 的表结构反射table_simple_infoData Analyze 链路中把 Schema 喂给 LLM 的核心方法是table_simple_info()L111-L133。它的实现很有代表性_tables_sql SELECT name FROM sqlite_master WHERE typetable with self.session_scope() as session: cursor session.execute(text(_tables_sql)) ... for row in tables_results: table_name row[0] _sql f PRAGMA table_info({table_name}) ... results.append(f{table_name}({,.join(table_colums)});)从源码结构看它查询的是sqlite_master系统表并用PRAGMA table_info取列名——这是 SQLite 方言的做法。之所以 DuckDB 连接器可以复用这一套查询是因为 DuckDB 与 SQLite 在系统表sqlite_master与PRAGMA上保持了相当高的兼容性DuckDB 本身即以嵌入式场景设计兼容 SQLite 的诸多接口。最终每个表被压缩为表名(列1,列2,...);这样的紧凑字符串正是 DB-GPT 拼入 SQL 生成 Prompt 的 Schema 描述形式。5.3 其余元数据方法同一文件还实现了若干RDBMSConnector接口约定方法方法行为说明get_users()(L72-L82)查询sqlite_master中名为duckdb_sys_users的表DuckDB 文件库默认无此表通常返回空列表get_grants()(L84-L86)固定返回[]嵌入式文件库无权限体系get_collation()/get_charset()(L88-L94)固定返回UTF-8简化处理get_table_comments()(L96-L109)从sqlite_master取name, sql返回 (表名, 建表 SQL) 对其中table_simple_info与get_users的实现细节由单测 test_conn_duckdb.py 覆盖测试用临时文件创建连接器验证get_users() []、get_charset() UTF-8、table_simple_info() []以及执行SELECT 42能正确返回[42]——覆盖了元数据反射与 SQL 执行两条主链路。5.4 连接器是如何被服务加载的DB-GPT 服务启动时数据源管理器会通过导入触发各连接器的资源注册。在 connector_manager.py 的on_init()中可以看到from dbgpt_ext.datasource.rdbms.conn_duckdb import DuckDbConnector # noqa: F401也就是说只要你按第二节安装了datasource_duckdb依赖DuckDbConnector就会被导入并注册DuckDB datasource 随即出现在 Web 控制台的数据源类型选项里。若依赖未安装该导入会失败——这也是排查下拉框里没有 duckdb 选项问题的第一落点。六、验证与排错清单依赖检查uv sync --all-packages --extra base --extra datasource_duckdb后确认环境中可import duckdb与duckdb_engine对应 pyproject.toml 中的duckdb与duckdb-engine0.9.1。路径检查确认path填写的是 webserver 所在主机上的路径且文件可读文件型数据库不存在路径可达性问题时的连不上多为路径错误或文件被其他进程独占。启动检查uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml启动后访问http://localhost:5670在数据源管理页选择 duckdb 类型填入 path 后先点连接测试再保存。行为验证新建会话选择 Data Analyze 应用提问示例数据库如 Walmart_Sales.db中的简单统计问题若生成的 SQL 执行成功说明引擎创建、Schema 反射table_simple_info与执行链路全部打通。七、适用前提与限制本文流程以当前仓库代码为准DuckDB 连接器位于dbgpt-ext扩展包依赖组datasource_duckdb锁定duckdb-engine0.9.1升级该方言版本前应先回归 test_conn_duckdb.py 相关测试。DuckDB 数据源本质是文件型嵌入式数据库参数模型中没有 host/port/user/password也没有权限与多租户概念get_grants恒为空不适合替代服务端数据库做多人并发写入场景其定位是轻量、即开即用的分析型数据接入。table_simple_info、get_users等方法复用sqlite_master/PRAGMA语法这是从源码结构看对 DuckDB 与 SQLite 系统接口兼容性的依赖若未来 DuckDB 变更系统表行为这些方法需要优先检查。小结按照 官方 DuckDB 集成文档 的三步走——安装datasource_duckdb依赖、准备.duckdb数据库文件、启动 webserver 并在控制台配置 path——即可让 DuckDB 成为 DB-GPT 的数据源。其底层实现集中在 conn_duckdb.pyduckdb:///path形式的连接 URL、auto_register_resource注册、基于sqlite_master与PRAGMA table_info的紧凑 Schema 反射共同构成了嵌入式分析库 确定性 SQL 链路在 DB-GPT 中的完整落地。【免费下载链接】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），仅供参考