sap-hana-ml

用途

本技能用于使用 hana-ml Python 客户端构建机器学习工作流，主要场景包括：使用 PAL/APL 算法、查询 HANA DataFrame、在数据库内训练或评分模型、使用 AutoML、可视化模型输出，以及排查 Python 到 HANA ML 的连接问题。

安装与要求

安装命令：

pip install hana-ml

要求：Python 3.8+，SAP HANA 2.0 SPS03+ 或 SAP HANA Cloud。

包版本：2.22.241011；最后验证时间：2025-11-27。

主要能力

连接与 DataFrame

通过 ConnectionContext 建立连接，示例：

from hana_ml import ConnectionContext

conn = ConnectionContext(
    address='<hostname>',
    port=443,
    user='<username>',
    password='<password>',
    encrypt=True
)

df = conn.table('MY_TABLE', schema='MY_SCHEMA')
print(f"Shape: {df.shape}")
df.head(10).collect()

DataFrame 采用惰性求值（lazy evaluation），在调用 collect() 之前只构建 SQL；支持数据库内处理以获得最佳性能。

PAL（Predictive Analysis Library）

提供 100+ 在数据库内执行的算法，类别包括分类、回归、聚类、时间序列、预处理。关键类：UnifiedClassification、UnifiedRegression、KMeans、ARIMA。

PAL 分类示例：

from hana_ml.algorithms.pal.unified_classification import UnifiedClassification

clf = UnifiedClassification(func='RandomDecisionTree')
clf.fit(train_df, features=['F1', 'F2', 'F3'], label='TARGET')

predictions = clf.predict(test_df, features=['F1', 'F2', 'F3'])
score = clf.score(test_df, features=['F1', 'F2', 'F3'], label='TARGET')

APL（Automated Predictive Library）

提供 AutoML 能力与自动特征工程。关键类：AutoClassifier、AutoRegressor、GradientBoostingClassifier。

APL AutoML 示例：

from hana_ml.algorithms.apl.classification import AutoClassifier

auto_clf = AutoClassifier()
auto_clf.fit(train_df, label='TARGET')
predictions = auto_clf.predict(test_df)

模型持久化

from hana_ml.model_storage import ModelStorage

ms = ModelStorage(conn)
clf.name = 'MY_CLASSIFIER'
ms.save_model(model=clf, if_exists='replace')

可视化

提供 EDA 图表、模型解释、指标等可视化能力，并集成 SHAP 以支持模型可解释性。

常见模式

训练-测试划分：

from hana_ml.algorithms.pal.partition import 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
)

特征重要性：

# APL 模型
importance = auto_clf.get_feature_importances()

# PAL 模型
from hana_ml.algorithms.pal.preprocessing import FeatureSelection
fs = FeatureSelection()
fs.fit(train_df, features=features, label='TARGET')

Pipeline：

from hana_ml.algorithms.pal.pipeline import Pipeline
from hana_ml.algorithms.pal.preprocessing import Imputer, FeatureNormalizer

pipeline = Pipeline([
    ('imputer', Imputer(strategy='mean')),
    ('normalizer', FeatureNormalizer()),
    ('classifier', UnifiedClassification(func='RandomDecisionTree'))
])

最佳实践

使用惰性求值：操作在 collect() 之前只构建 SQL 而不执行。
利用数据库内处理：将数据保留在 HANA 中以获得性能。
使用 Unified 接口：跨算法保持一致的 API。
保存模型：使用 ModelStorage 进行持久化。
解释预测：使用 SHAP 解释器提升可解释性。
监控 AutoML：对长时间运行的任务使用 PipelineProgressStatusMonitor。

错误处理

from hana_ml.ml_exceptions import Error

try:
    clf.fit(train_df, features=features, label='TARGET')
except Error as e:
    print(f"HANA ML Error: {e}")

常见问题排查

连接失败：检查 HANA 主机、端口、TLS/加密、用户权限和网络允许列表。
PAL/APL 算法缺失：确认 HANA 系统已安装并授权所需的 AFL/PAL/APL 库。
DataFrame 收集缓慢：将过滤/投影下推到 HANA，避免将大型 DataFrame 收集到 Python。

文档

官方文档：https://help.sap.com/doc/1d0ebfe5e8dd44d09606814d83308d4b/2.0.07/en-US/hana_ml.html

PyPI 包：https://pypi.org/project/hana-ml/

技能介绍

用途