用途：UMAP（Uniform Manifold Approximation and Projection）是用于可视化与通用非线性降维的技术，可生成快速、可扩展且兼顾局部与全局结构的嵌入，用于监督/半监督学习与聚类预处理，可作为 t-SNE 或 PCA 的替代。
安装：需要 Python 3.9+，依赖 scikit-learn>=1.6、numba、pynndescent、numpy、scipy。当前稳定版为 umap-learn 0.5.12。安装命令：uv pip install umap-learn==0.5.12。参数化 UMAP 需安装额外依赖：uv pip install "umap-learn[parametric-umap]==0.5.12"。聚类工作流需单独安装 hdbscan：uv pip install hdbscan。
主要能力与用法：遵循 scikit-learn 约定，可用 umap.UMAP().fit_transform(scaled_data) 一步拟合转换，或先 fit 再通过 embedding_ 获取嵌入。关键参数：n_neighbors 默认 15，控制局部与全局结构平衡；min_dist 默认 0.1，控制低维空间点的紧密程度；n_components 默认 2，UMAP 在嵌入维度上扩展性较好，2-3 维用于可视化，5-10 维用于聚类预处理，10-50 维用于下游机器学习特征工程；metric 默认 euclidean，支持多种度量，文本/文档向量可用 cosine，二值数据可用 hamming。
监督与半监督：拟合时通过 y 传入标签进行监督降维；半监督时将未标注点按 scikit-learn 约定标为 -1。
聚类：建议聚类时使用 n_neighbors 约 30、min_dist=0.0、n_components 5-10，再配合 HDBSCAN。注意 UMAP 不完全保留密度，可能产生人为的簇划分，需验证结果。
变换新数据：使用 transform() 将新数据投影到已学嵌入空间，并可与 sklearn Pipeline 集成。其假设训练与测试数据在高维空间分布一致，若不成立可考虑参数化 UMAP。
高级功能：ParametricUMAP 使用 TensorFlow/Keras 学习神经网络映射，支持高效变换与重建（逆变换），可用 save() 与 load_ParametricUMAP 保存加载；inverse_transform 可从低维重建高维，但计算开销大且在外推区域效果差；AlignedUMAP 用于时间序列或相关数据集的对齐嵌入，需要提供 relations。
复现性与常见问题：设置 random_state 以获得可复现结果；不设时并行性可能更高。若出现簇分散或碎片化，可调整 n_neighbors、min_dist 或采用聚类专用参数。输入需保证为有限数值，先处理 NaN/inf。避免将文件命名为 umap.py、sklearn.py、hdbscan.py 或 tensorflow.py 以免遮挡真实包导入。DensMAP 在本资料中仅提及名称，具体用法暂未提供。参数化 UMAP 的更多细节可参考官方文档与 api_reference.md。