DB-GPT 接入 DuckDB 数据源完整指南安装、配置与源码解析【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPTDuckDB 是一款高性能的嵌入式分析型数据库DB-GPT 将其作为 Datasource 接入后可以通过 SQL 直接查询本地分析型数据从一定程度上缓解向量数据库检索带来的不确定性与可解释性问题。本文以官方集成文档为核心结合当前仓库的源码实现完整讲解依赖安装、服务启动、连接配置三个环节并深入剖析DuckDbConnector的底层连接原理与查询执行机制帮助你快速在 DB-GPT 中使用 DuckDB 完成可解释的 Text2SQL 数据查询。DuckDB 作为 DB-GPT Datasource 的价值DuckDB 是一个面向分析场景设计的高性能数据库系统专注于快速、高效地执行分析型 SQL 查询同时可以作为嵌入式分析数据库直接集成到应用程序进程中。在 DB-GPT 的 数据源连接模块 中DuckDB 是被官方列为 Yes已支持的分析型数据源之一。将 DuckDB 接入 DB-GPT Datasource 的核心价值在于当模型需要回答数据类问题时向量数据库检索本质上是基于相似度匹配的近似检索存在结果不确定、推理链路难以解释的问题而使用 DuckDB 这样的关系型分析数据库查询过程是确定的 SQL 执行结果可复现、可校验从而提升了 Text2SQL 场景的确定性uncertainty与可解释性interpretability。从源码结构看DuckDB 属于 DB-GPT 数据源体系中的文件型数据库file-based DB在 packages/dbgpt-ext/src/dbgpt_ext/datasource/schema.py 中DuckDb DbInfo(duckdb, True)即声明了它以本地.db文件形式存在无需独立部署数据库服务。安装依赖要启用 DuckDB 数据源首先需要安装dbgpt duckdb datasource相关的依赖库。在仓库根目录执行以下命令uv sync --all-packages \ --extra base \ --extra datasource_duckdb \ --extra rag \ --extra storage_chromadb各 extra 的作用说明extra作用base安装 DB-GPT 基础运行依赖是启动核心服务的前提datasource_duckdb安装 DuckDB 数据源驱动即duckdb与duckdb-enginerag安装 RAG 检索相关依赖文档涉及 DuckDB 与向量检索协同的场景storage_chromadb安装 ChromaDB 向量存储后端其中datasource_duckdb的具体依赖清单定义在 packages/dbgpt-ext/pyproject.tomldatasource_duckdb [ duckdb, duckdb-engine0.9.1, ]duckdb提供数据库内核duckdb-engine则实现 SQLAlchemy 方言dialect使 DB-GPT 能够通过统一的 SQLAlchemy 引擎访问 DuckDB。由于版本已锁定请确保按此命令同步安装避免方言与内核版本不匹配导致的连接异常。准备 DuckDB 数据库DuckDB 无需部署独立的数据库服务。你可以先安装 DuckDB 官方工具如 CLI通过duckdb命令或任意支持该格式的工具创建/打开一个本地数据库文件例如duckdb my_analytics.duckdb随后在 DuckDB 交互环境中执行建表、导入 CSV/Parquet 等操作将分析数据落盘到该.db文件中。之后 DB-GPT 只需要指向这个文件路径即可完成连接。当前仓库的示例数据目录docker/examples中也提供了基于 SQLite 的演示数据如Walmart_Sales.db可作为建表与导入的参考范例。启动 DB-GPT WebServer安装依赖并准备好 DuckDB 数据库文件后即可启动 DB-GPT WebServer。官方文档提供了两种方式任选其一方式一通过uv run启动推荐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两种方式等价均使用 configs/dbgpt-proxy-openai.toml 作为配置文件。该配置以 OpenAI 兼容的代理模型接入 LLM你同样可以根据自己的模型服务替换为仓库configs/目录下的其他配置文件例如dbgpt-local-vllm.toml、dbgpt-proxy-ollama.toml等。DuckDB 连接配置详解启动 WebServer 后在 DB-GPT 的数据库/数据源管理界面中新建数据源类型选择DuckDB需要配置以下两个字段参数类型必填默认值说明pathstring是无DuckDB 数据库文件路径如my_analytics.duckdbdriverstring否duckdbDuckDB 驱动名称默认即duckdb这两个参数由DuckDbConnectorParameters定义于 packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_duckdb.py并在 DuckDB datasource Configuration 参考文档 中同步生成。参数如何转化为连接地址DuckDbConnectorParameters.db_url()将上述参数拼接为 SQLAlchemy 连接 URLdef db_url(self, sslFalse, charsetNone): Get the database URL. return f{self.driver}:///{self.path}即默认生成duckdb:///path形式的连接串。也就是说配置界面的path直接决定了create_engine(duckdb:/// file_path)所打开的数据库文件——它可以是已存在的数据文件也可以是不存在的路径DuckDB 会按需创建。从源码结构看driver字段保留了自定义驱动名的扩展能力但当前仓库实现中默认值duckdb即为唯一标准选项一般无需修改。源码级原理解析DuckDbConnector 的类层级DuckDbConnector继承自 DB-GPT 的关系型数据库基类RDBMSConnector声明如下关键标识class DuckDbConnector(RDBMSConnector): db_type: str duckdb db_dialect: str duckdbdb_type duckdb是数据源注册表中识别该连接器的唯一标识db_dialect duckdb用于在基类中按方言分发查询执行策略。其核心工厂方法from_file_path()通过create_engine(duckdb:/// file_path)构建 SQLAlchemy 引擎——这正印证了文件型数据库的设计连接成本极低没有网络、端口、用户认证环节。连接器如何被注册与调度DuckDB 连接器在 DB-GPT 中由ConnectorManager统一管理注册逻辑位于 packages/dbgpt-serve/src/dbgpt_serve/datasource/manages/connector_manager.pyfrom dbgpt_ext.datasource.rdbms.conn_duckdb import DuckDbConnector # noqa: F401该组件启动时加载全部连接器类当用户配置的数据源被查询时_build_connector()会根据db_type判断若db_type.is_file_db()为真DuckDB 正是此类则走from_file_path(db_path)分支直接以文件路径构建连接器。同时ConnectorManager对已构建的连接器做了 30 分钟 TTL 的缓存并针对同一数据库的并发首次访问使用 per-db 锁避免重复执行昂贵的 schema 反射MetaData.reflect从而显著降低多轮对话场景下的连接开销。查询执行与超时控制作为嵌入式 OLAP 数据库DuckDB 查询可能耗时较长因此 DB-GPT 在基类 packages/dbgpt-core/src/dbgpt/datasource/rdbms/base.py 中为duckdb方言实现了独立的超时策略elif self.dialect duckdb: # DuckDB: Use ThreadPoolExecutor for timeout with ThreadPoolExecutor(max_workers1) as executor: future executor.submit(_execute_query, session, sql, params) try: return future.result(timeouttimeout) except FutureTimeoutError: raise TimeoutError( fQuery exceeded timeout of {timeout} seconds )DuckDB 不像 MySQLSET SESSION MAX_EXECUTION_TIME或 PostgreSQLSET statement_timeout那样提供会话级超时指令因此 DB-GPT 采用线程池 future.result(timeout...)的方式实现查询超时兜底超时后抛出TimeoutError。理解这一点有助于你在配置数据源时合理设置查询超时参数避免长查询拖垮交互。元数据能力为了支撑 Text2SQL 中根据表结构生成 SQL的能力DuckDbConnector重写了若干元数据方法见 conn_duckdb.pyget_users()/get_grants()通过查询sqlite_master中的duckdb_sys_users表获取用户列表权限列表返回空get_charset()/get_collation()固定返回UTF-8get_table_comments()从sqlite_master读取所有表的名称与建表 SQLtable_simple_info()遍历每张表用PRAGMA table_info(table)提取字段名产出表名(字段1,字段2,...);形式的紧凑 schema 摘要——这正是模型进行 SQL 生成所需的上下文。之所以复用sqlite_master系统表是因为 DuckDB 的 catalog 结构与该查询兼容这也是嵌入式分析数据库提供的轻量元数据读取方式。单元测试验证仓库为 DuckDB 连接器提供了完整的单元测试见 packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/tests/test_conn_duckdb.py覆盖了以下行为def test_get_charset(db): assert db.get_charset() UTF-8 def test_get_table_comments(db): assert db.get_table_comments(test) [] def test_table_simple_info(db): assert db.table_simple_info() [] def test_execute(db): assert list(db.run(SELECT 42)[0]) [42]测试通过tempfile.NamedTemporaryFile生成临时.db文件构建连接器验证空库场景下用户列表、表清单、schema 摘要均返回空集合并验证run(SELECT 42)这类基础查询能正确执行。你可以在安装依赖后于仓库内通过 pytest 复现这些验证快速确认 DuckDB 数据源在本地的可用性。使用建议与注意事项路径权限path指向的数据库文件需保证 DB-GPT 进程具备读写权限否则首次查询会因文件无法打开而失败。schema 缓存若在 DuckDB 文件中新增了表可通过 DB-GPT 数据源管理界面刷新/重建连接触发连接器缓存失效ConnectorManager.invalidate_connector以重新执行 schema 反射。查询超时DuckDB 方言依赖线程池实现超时长耗时分析查询请结合数据规模设置合理的超时阈值。定位差异DuckDB 适合确定性 SQL 查询场景可与向量检索形成互补——将可精确计算的统计类问题交给 DuckDB将语义模糊检索交给向量库从而兼顾准确性与灵活性。至此你已经可以按照本文完成 DuckDB 数据源的安装、服务启动、连接配置并理解其底层连接与查询机制将其投入 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 数据源完整指南安装、配置与源码解析【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPTDuckDB 是一款高性能的嵌入式分析型数据库DB-GPT 将其作为 Datasource 接入后可以通过 SQL 直接查询本地分析型数据从一定程度上缓解向量数据库检索带来的不确定性与可解释性问题。本文以官方集成文档为核心结合当前仓库的源码实现完整讲解依赖安装、服务启动、连接配置三个环节并深入剖析DuckDbConnector的底层连接原理与查询执行机制帮助你快速在 DB-GPT 中使用 DuckDB 完成可解释的 Text2SQL 数据查询。DuckDB 作为 DB-GPT Datasource 的价值DuckDB 是一个面向分析场景设计的高性能数据库系统专注于快速、高效地执行分析型 SQL 查询同时可以作为嵌入式分析数据库直接集成到应用程序进程中。在 DB-GPT 的 数据源连接模块 中DuckDB 是被官方列为 Yes已支持的分析型数据源之一。将 DuckDB 接入 DB-GPT Datasource 的核心价值在于当模型需要回答数据类问题时向量数据库检索本质上是基于相似度匹配的近似检索存在结果不确定、推理链路难以解释的问题而使用 DuckDB 这样的关系型分析数据库查询过程是确定的 SQL 执行结果可复现、可校验从而提升了 Text2SQL 场景的确定性uncertainty与可解释性interpretability。从源码结构看DuckDB 属于 DB-GPT 数据源体系中的文件型数据库file-based DB在 packages/dbgpt-ext/src/dbgpt_ext/datasource/schema.py 中DuckDb DbInfo(duckdb, True)即声明了它以本地.db文件形式存在无需独立部署数据库服务。安装依赖要启用 DuckDB 数据源首先需要安装dbgpt duckdb datasource相关的依赖库。在仓库根目录执行以下命令uv sync --all-packages \ --extra base \ --extra datasource_duckdb \ --extra rag \ --extra storage_chromadb各 extra 的作用说明extra作用base安装 DB-GPT 基础运行依赖是启动核心服务的前提datasource_duckdb安装 DuckDB 数据源驱动即duckdb与duckdb-enginerag安装 RAG 检索相关依赖文档涉及 DuckDB 与向量检索协同的场景storage_chromadb安装 ChromaDB 向量存储后端其中datasource_duckdb的具体依赖清单定义在 packages/dbgpt-ext/pyproject.tomldatasource_duckdb [ duckdb, duckdb-engine0.9.1, ]duckdb提供数据库内核duckdb-engine则实现 SQLAlchemy 方言dialect使 DB-GPT 能够通过统一的 SQLAlchemy 引擎访问 DuckDB。由于版本已锁定请确保按此命令同步安装避免方言与内核版本不匹配导致的连接异常。准备 DuckDB 数据库DuckDB 无需部署独立的数据库服务。你可以先安装 DuckDB 官方工具如 CLI通过duckdb命令或任意支持该格式的工具创建/打开一个本地数据库文件例如duckdb my_analytics.duckdb随后在 DuckDB 交互环境中执行建表、导入 CSV/Parquet 等操作将分析数据落盘到该.db文件中。之后 DB-GPT 只需要指向这个文件路径即可完成连接。当前仓库的示例数据目录docker/examples中也提供了基于 SQLite 的演示数据如Walmart_Sales.db可作为建表与导入的参考范例。启动 DB-GPT WebServer安装依赖并准备好 DuckDB 数据库文件后即可启动 DB-GPT WebServer。官方文档提供了两种方式任选其一方式一通过uv run启动推荐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两种方式等价均使用 configs/dbgpt-proxy-openai.toml 作为配置文件。该配置以 OpenAI 兼容的代理模型接入 LLM你同样可以根据自己的模型服务替换为仓库configs/目录下的其他配置文件例如dbgpt-local-vllm.toml、dbgpt-proxy-ollama.toml等。DuckDB 连接配置详解启动 WebServer 后在 DB-GPT 的数据库/数据源管理界面中新建数据源类型选择DuckDB需要配置以下两个字段参数类型必填默认值说明pathstring是无DuckDB 数据库文件路径如my_analytics.duckdbdriverstring否duckdbDuckDB 驱动名称默认即duckdb这两个参数由DuckDbConnectorParameters定义于 packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_duckdb.py并在 DuckDB datasource Configuration 参考文档 中同步生成。参数如何转化为连接地址DuckDbConnectorParameters.db_url()将上述参数拼接为 SQLAlchemy 连接 URLdef db_url(self, sslFalse, charsetNone): Get the database URL. return f{self.driver}:///{self.path}即默认生成duckdb:///path形式的连接串。也就是说配置界面的path直接决定了create_engine(duckdb:/// file_path)所打开的数据库文件——它可以是已存在的数据文件也可以是不存在的路径DuckDB 会按需创建。从源码结构看driver字段保留了自定义驱动名的扩展能力但当前仓库实现中默认值duckdb即为唯一标准选项一般无需修改。源码级原理解析DuckDbConnector 的类层级DuckDbConnector继承自 DB-GPT 的关系型数据库基类RDBMSConnector声明如下关键标识class DuckDbConnector(RDBMSConnector): db_type: str duckdb db_dialect: str duckdbdb_type duckdb是数据源注册表中识别该连接器的唯一标识db_dialect duckdb用于在基类中按方言分发查询执行策略。其核心工厂方法from_file_path()通过create_engine(duckdb:/// file_path)构建 SQLAlchemy 引擎——这正印证了文件型数据库的设计连接成本极低没有网络、端口、用户认证环节。连接器如何被注册与调度DuckDB 连接器在 DB-GPT 中由ConnectorManager统一管理注册逻辑位于 packages/dbgpt-serve/src/dbgpt_serve/datasource/manages/connector_manager.pyfrom dbgpt_ext.datasource.rdbms.conn_duckdb import DuckDbConnector # noqa: F401该组件启动时加载全部连接器类当用户配置的数据源被查询时_build_connector()会根据db_type判断若db_type.is_file_db()为真DuckDB 正是此类则走from_file_path(db_path)分支直接以文件路径构建连接器。同时ConnectorManager对已构建的连接器做了 30 分钟 TTL 的缓存并针对同一数据库的并发首次访问使用 per-db 锁避免重复执行昂贵的 schema 反射MetaData.reflect从而显著降低多轮对话场景下的连接开销。查询执行与超时控制作为嵌入式 OLAP 数据库DuckDB 查询可能耗时较长因此 DB-GPT 在基类 packages/dbgpt-core/src/dbgpt/datasource/rdbms/base.py 中为duckdb方言实现了独立的超时策略elif self.dialect duckdb: # DuckDB: Use ThreadPoolExecutor for timeout with ThreadPoolExecutor(max_workers1) as executor: future executor.submit(_execute_query, session, sql, params) try: return future.result(timeouttimeout) except FutureTimeoutError: raise TimeoutError( fQuery exceeded timeout of {timeout} seconds )DuckDB 不像 MySQLSET SESSION MAX_EXECUTION_TIME或 PostgreSQLSET statement_timeout那样提供会话级超时指令因此 DB-GPT 采用线程池 future.result(timeout...)的方式实现查询超时兜底超时后抛出TimeoutError。理解这一点有助于你在配置数据源时合理设置查询超时参数避免长查询拖垮交互。元数据能力为了支撑 Text2SQL 中根据表结构生成 SQL的能力DuckDbConnector重写了若干元数据方法见 conn_duckdb.pyget_users()/get_grants()通过查询sqlite_master中的duckdb_sys_users表获取用户列表权限列表返回空get_charset()/get_collation()固定返回UTF-8get_table_comments()从sqlite_master读取所有表的名称与建表 SQLtable_simple_info()遍历每张表用PRAGMA table_info(table)提取字段名产出表名(字段1,字段2,...);形式的紧凑 schema 摘要——这正是模型进行 SQL 生成所需的上下文。之所以复用sqlite_master系统表是因为 DuckDB 的 catalog 结构与该查询兼容这也是嵌入式分析数据库提供的轻量元数据读取方式。单元测试验证仓库为 DuckDB 连接器提供了完整的单元测试见 packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/tests/test_conn_duckdb.py覆盖了以下行为def test_get_charset(db): assert db.get_charset() UTF-8 def test_get_table_comments(db): assert db.get_table_comments(test) [] def test_table_simple_info(db): assert db.table_simple_info() [] def test_execute(db): assert list(db.run(SELECT 42)[0]) [42]测试通过tempfile.NamedTemporaryFile生成临时.db文件构建连接器验证空库场景下用户列表、表清单、schema 摘要均返回空集合并验证run(SELECT 42)这类基础查询能正确执行。你可以在安装依赖后于仓库内通过 pytest 复现这些验证快速确认 DuckDB 数据源在本地的可用性。使用建议与注意事项路径权限path指向的数据库文件需保证 DB-GPT 进程具备读写权限否则首次查询会因文件无法打开而失败。schema 缓存若在 DuckDB 文件中新增了表可通过 DB-GPT 数据源管理界面刷新/重建连接触发连接器缓存失效ConnectorManager.invalidate_connector以重新执行 schema 反射。查询超时DuckDB 方言依赖线程池实现超时长耗时分析查询请结合数据规模设置合理的超时阈值。定位差异DuckDB 适合确定性 SQL 查询场景可与向量检索形成互补——将可精确计算的统计类问题交给 DuckDB将语义模糊检索交给向量库从而兼顾准确性与灵活性。至此你已经可以按照本文完成 DuckDB 数据源的安装、服务启动、连接配置并理解其底层连接与查询机制将其投入 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），仅供参考
