使用 SAP HANA 数据库内机器学习（hana-ml）时…

在 SAP HANA 2.0 SPS03+ 或 SAP HANA Cloud 上用 Python hana-ml 构建数据库内机器学习工作流时适用。

适用场景

解决思路

1. 安装：运行 `pip install hana-ml`。
2. 连接 HANA：从 `hana_ml` 导入 `ConnectionContext`，用 `ConnectionContext(address='<hostname>', port=443, user='<username>', password='<password>', encrypt=True)` 创建连接。
3. 创建 HANA DataFrame：调用 `conn.table('MY_TABLE', schema='MY_SCHEMA')`；用 `print(f"Shape: {df.shape}")` 查看形状；用 `df.head(10).collect()` 取前 10 行。
4. 训练 PAL 分类模型：从 `hana_ml.algorithms.pal.unified_classification` 导入 `UnifiedClassification`；实例化 `UnifiedClassification(func='RandomDecisionTree')`；调用 `clf.fit(train_df, features=['F1', 'F2', 'F3'], label='TARGET')`。
5. PAL 分类预测与评分：调用 `clf.predict(test_df, features=['F1', 'F2', 'F3'])`；调用 `clf.score(test_df, features=['F1', 'F2', 'F3'], label='TARGET')`。
6. APL AutoML 分类：从 `hana_ml.algorithms.apl.classification` 导入 `AutoClassifier`；实例化 `AutoClassifier()`；调用 `auto_clf.fit(train_df, label='TARGET')`；调用 `auto_clf.predict(test_df)`。
7. 模型持久化：从 `hana_ml.model_storage` 导入 `ModelStorage`；创建 `ms = ModelStorage(conn)`；设置 `clf.name = 'MY_CLASSIFIER'`；调用 `ms.save_model(model=clf, if_exists='replace')`。
8. PAL 使用：选择分类、回归、聚类、时间序列、预处理等 100+ 数据库内算法；关键类包括 `UnifiedClassification`、`UnifiedRegression`、`KMeans`、`ARIMA`；完整列表见 `references/PAL_ALGORITHMS.md`。
9. APL 使用：用 AutoML 自动特征工程；关键类包括 `AutoClassifier`、`AutoRegressor`、`GradientBoostingClassifier`；详情见 `references/APL_ALGORITHMS.md`。
10. DataFrame 使用：采用惰性求值，操作构建 SQL 直到调用 `collect()`；在数据库内处理以优化性能；完整 API 见 `references/DATAFRAME_REFERENCE.md`。
11. 可视化：使用 EDA 图、模型解释和指标；集成 SHAP 进行模型可解释性；14 个可视化模块见 `references/VISUALIZERS.md`。
12. 训练-测试-验证拆分：从 `hana_ml.algorithms.pal.partition` 导入 `train_test_val_split`；调用 `train, test, val = train_test_val_split(data=df, training_percentage=0.7, testing_percentage=0.2, validation_percentage=0.1)`。
13. 特征重要性（APL）：调用 `auto_clf.get_feature_importances()`。
14. 特征选择（PAL）：从 `hana_ml.algorithms.pal.preprocessing` 导入 `FeatureSelection`；实例化 `fs = FeatureSelection()`；调用 `fs.fit(train_df, features=features, label='TARGET')`。
15. 构建 Pipeline：从 `hana_ml.algorithms.pal.pipeline` 导入 `Pipeline`；从 `hana_ml.algorithms.pal.preprocessing` 导入 `Imputer, FeatureNormalizer`；用 `Pipeline([('imputer', Imputer(strategy='mean')), ('normalizer', FeatureNormalizer()), ('classifier', UnifiedClassification(func='RandomDecisionTree'))])` 创建流水线。
16. 最佳实践 1：使用惰性求值，操作构建 SQL 直到调用 `collect()` 才执行。
17. 最佳实践 2：利用数据库内处理，将数据保留在 HANA 中以获得性能。
18. 最佳实践 3：使用 Unified 接口，获得跨算法一致的 API。
19. 最佳实践 4：用 `ModelStorage` 保存模型以实现持久化。
20. 最佳实践 5：用 SHAP explainers 解释预测以提高可解释性。
21. 最佳实践 6：用 `PipelineProgressStatusMonitor` 监控长时间运行的 AutoML 作业。
22. 错误处理：从 `hana_ml.ml_exceptions` 导入 `Error`；在 `try` 块中执行 `clf.fit(train_df, features=features, label='TARGET')`；在 `except Error as e` 中打印 `f"HANA ML Error: {e}"`。
23. 排查连接失败：检查 HANA host、port、TLS/加密、用户权限和网络 allowlists。
24. 排查算法缺失：确认 HANA 系统已安装并许可所需的 AFL/PAL/APL 库。
25. 排查 DataFrame 收集慢：将过滤/投影下推到 HANA，避免将大 DataFrame 收集到 Python。
26. 参考文件 `references/DATAFRAME_REFERENCE.md`（479 行）：ConnectionContext API、DataFrame 操作、SQL 生成。
27. 参考文件 `references/PAL_ALGORITHMS.md`（869 行）：完整 PAL 算法参考（100+ 算法），分类、回归、聚类、时间序列、预处理。
28. 参考文件 `references/APL_ALGORITHMS.md`（534 行）：AutoML 能力、自动特征工程，AutoClassifier、AutoRegressor、GradientBoosting 类。
29. 参考文件 `references/VISUALIZERS.md`（704 行）：14 个可视化模块（EDA、SHAP、指标、时间序列），绘图类型、配置、导出选项。
30. 参考文件 `references/SUPPORTING_MODULES.md`（626 行）：模型存储、空间分析、图算法、文本挖掘、统计、错误处理。
31. 查阅官方文档：https://help.sap.com/doc/1d0ebfe5e8dd44d09606814d83308d4b/2.0.07/en-US/hana_ml.html 和 PyPI 包：https://pypi.org/project/hana-ml/。

适用边界 · 注意事项

• 没有 SAP HANA 2.0 SPS03+ 或 SAP HANA Cloud 环境，或没有 hana-ml 及 PAL/APL 许可时，不适用。
• 只需要本地/其他平台通用 Python ML 库（如 scikit-learn）处理小数据，且不需要数据库内计算时，不适用。
• 使用非 SAP HANA 的数据库或云厂商 ML 服务时，不适用。