# DuckDB-ML：在 SQL 中直接运行机器学习的 DuckDB 扩展 > duckdb-ml 是一个 DuckDB 扩展，允许用户直接在 SQL 查询中训练、预测和评估机器学习模型。它提供了四个核心表函数：ml_fit、ml_predict、ml_evaluate 和 ml_explain，支持 PCA 等算法，并将模型版本存储在 SQLite 注册表中。 - 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo) - 发布时间: 2026-05-19T19:45:50.000Z - 最近活动: 2026-05-19T19:49:53.162Z - 热度: 112.9 - 关键词: DuckDB, 机器学习, SQL, PCA, 数据库扩展, MLOps, 版本管理 - 页面链接: https://www.zingnex.cn/forum/thread/duckdb-ml-sql-duckdb - Canonical: https://www.zingnex.cn/forum/thread/duckdb-ml-sql-duckdb - Markdown 来源: ingested_event --- # DuckDB-ML：在 SQL 中直接运行机器学习的 DuckDB 扩展\n\n## 项目概述\n\nduckdb-ml 是一个为 DuckDB 数据库设计的机器学习扩展，它将传统上需要 Python 或 R 等外部工具完成的 ML 工作流，直接集成到 SQL 查询中。这种设计理念体现了"数据在哪里，计算就在哪里"的思想，避免了数据在数据库和 ML 框架之间来回传输的开销。\n\n该扩展基于 DuckDB 的官方扩展模板构建，提供了四个核心表函数，覆盖了机器学习生命周期的主要环节：训练、预测、评估和解释。所有模型版本都存储在一个 SQLite 注册表中，支持版本管理和回溯。\n\n## 核心功能：四个表函数\n\nduckdb-ml 通过 SQL 表函数暴露 ML 能力，这种设计保持了 DuckDB 的声明式风格：\n\n### ml_fit：模型训练\n\n`ml_fit(model, options, transforms, table)` 函数接受模型名称、配置选项、转换规则和训练数据，返回包含模型版本信息的单行结果：\n\n- model（模型名称，VARCHAR）\n- version（版本号，BIGINT）\n- timestamp（时间戳，VARCHAR）\n\n每次调用都会创建一个新的不可变版本，确保实验的可重现性。\n\n### ml_predict：推理预测\n\n`ml_predict(model, table[, version])` 函数使用指定模型对新数据进行预测。默认使用最新版本，也可以通过 version 参数指定特定版本（version=0 表示最新，version>0 表示具体版本）。\n\n### ml_evaluate：模型评估\n\n`ml_evaluate(model, table[, version])` 函数计算模型在测试数据上的性能指标，帮助开发者了解模型的泛化能力。\n\n### ml_explain：模型解释\n\n`ml_explain(model, table[, version])` 函数提供模型的可解释性输出，对于理解模型决策过程至关重要。\n\n## 使用示例\n\n以下示例展示了如何在 DuckDB 中完成一个完整的 PCA（主成分分析）工作流：\n\n```sql\n-- 训练 PCA 模型\nSELECT *\nFROM ml_fit(\n 'pca_california',\n {'model_type':'pca', 'num_components':2, 'whiten':false},\n NULL,\n (SELECT * FROM california_train)\n);\n\n-- 使用最新版本进行预测\nSELECT * FROM ml_predict('pca_california', (SELECT * FROM california_test));\n\n-- 评估模型性能\nSELECT * FROM ml_evaluate('pca_california', (SELECT * FROM california_test));\n\n-- 使用特定版本进行预测\nSELECT * FROM ml_predict('pca_california', (SELECT * FROM california_test), version = 1);\n```\n\n这种纯 SQL 的工作流消除了上下文切换的成本，数据分析师可以在熟悉的环境中完成 ML 任务。\n\n## 模型注册表与版本管理\n\nduckdb-ml 使用 SQLite 作为模型注册表，路径按以下优先级解析：\n\n1. PROJECT_DB_PATH 环境变量\n2. 操作系统默认路径：\n - Linux/macOS: `~/.duckdb-ml.db`\n - Windows: `%APPDATA%\\duckdb-ml\\duckdb-ml.db`（回退到 `%USERPROFILE%\\.duckdb-ml.db`）\n\n模型条目存储在扩展拥有的 `duckdb_ml_models` 表中，这种设计确保了：\n\n- **版本隔离**：每个训练调用创建新版本，不影响现有生产模型\n- **可重现性**：可以精确回溯到任何历史版本\n- **原子性**：模型切换是瞬时的，无需停机部署\n\n## 架构设计与技术考量\n\n该扩展基于 DuckDB 的 C++ 扩展框架构建，采用模板化设计以简化开发和分发。构建系统需要编译 DuckDB 核心和单元测试二进制文件，这带来了一定的构建时间开销。\n\n为优化开发体验，项目官方推荐使用 ccache 和 ninja：\n\n```bash\n# 使用 ninja 和 ccache 加速构建\nGEN=ninja make\n```\n\n这样可以确保 DuckDB 核心只需编译一次，后续扩展修改可以快速增量构建。\n\n## 安装与使用\n\n从 S3 安装自定义扩展需要两个步骤：\n\n**1. 启用未签名扩展**\n\nCLI 方式：\n```bash\nduckdb -unsigned\n```\n\nPython 方式：\n```python\ncon = duckdb.connect(':memory:', config={'allow_unsigned_extensions': 'true'})\n```\n\nNode.js 方式：\n```javascript\ndb = new duckdb.Database(':memory:', {\"allow_unsigned_extensions\": \"true\"});\n```\n\n**2. 设置扩展仓库**\n\n```sql\nSET custom_extension_repository='bucket.s3.eu-west-1.amazonaws.com//latest';\n```\n\n**3. 安装并加载**\n\n```sql\nINSTALL ml;\nLOAD ml;\n```\n\n## 开发环境配置\n\n对于使用 CLion 的开发者，项目提供了详细的配置指南：\n\n1. 确保 DuckDB 子模块已初始化\n2. 打开 `./duckdb/CMakeLists.txt`（而非顶层 CMakeLists.txt）作为项目\n3. 通过 Tools → CMake → Change Project Root 将项目根目录指向仓库根目录\n4. 在 CMake 设置中添加构建类型（Debug、Release、RelDebug 等）\n5. 在 CMake Options 中添加 `-DDUCKDB_EXTENSION_CONFIGS=`\n6. 配置 unittest 作为运行目标，添加 `--test-dir ../../.. [sql]` 参数以仅运行扩展特定测试\n\n## 测试策略\n\n项目采用 SQL 测试作为主要测试方式，测试文件位于 `./test/sql` 目录。运行测试的命令为：\n\n```bash\nmake test\n```\n\n这种测试方式与 DuckDB 的测试框架保持一致，确保扩展与核心系统的兼容性。\n\n## 适用场景与价值\n\nduckdb-ml 特别适合以下场景：\n\n- **数据分析师**：无需学习 Python 即可完成常见的 ML 任务\n- **ETL 管道**：在数据转换过程中嵌入 ML 推理\n- **边缘计算**：轻量级部署，无需完整的 Python 环境\n- **原型验证**：快速实验不同模型和参数\n\n通过将 ML 能力直接集成到数据库中，duckdb-ml 降低了机器学习的入门门槛，同时保持了生产环境所需的性能和可靠性。\n\n## 总结\n\nduckdb-ml 代表了数据库内机器学习（In-Database Machine Learning）的一个实践范例。它证明了在保持 SQL 声明式风格的同时，完全可以实现复杂的 ML 工作流。对于已经使用 DuckDB 进行数据分析的团队来说，这个扩展提供了一种自然的能力扩展路径，无需引入额外的技术栈。