nearestneighbors适合高维向量（如文本嵌入、图像特征）中多查询、静态数据集的top-k近邻检索，通过建索引加速搜索，但不支持动态增删；metric需依场景选择——余弦相似度任务应先l2归一化再用euclidean，algorithm据维度与规模选auto/ball_tree/kd_tree/brute。

NearestNeighbors 适合什么场景

当你要在高维向量集合（比如文本嵌入、图像特征）中快速找 Top-K 最近邻，且查询点数量多、数据集相对静态时，NearestNeighbors 比纯 scipy.spatial.distance.cdist 或手动循环快得多。它不计算全量距离矩阵，而是建索引后做近似/精确搜索，内存换速度。

注意：它只返回距离和索引，不直接输出余弦相似度——得自己转；也不支持动态增删样本（fit 后不能 update）。

如何正确设置 metric 和 algorithm

metric 决定“近”怎么算："euclidean" 是默认，适合 L2 归一化前的特征；但语义向量常用余弦相似度，这时别设 metric="cosine"，而应先对训练数据和查询向量做 L2 归一化，再用 metric="euclidean"——因为归一化后欧氏距离和余弦距离单调等价，且更稳定、更快。

algorithm 选型看数据规模和维度：

• 小数据（"brute"，简单可靠，避免树结构开销
• 中等数据（10k–100k，"kd_tree" 或 "ball_tree" 都可，后者对非均匀分布更鲁棒
• 高维（>500 维）或超大数据：必须用 "brute"，kd/ball 树在高维会退化成暴力搜索

别盲目选 "auto"——它内部按维度和样本数启发式选，但有时选错（比如误用 kd_tree 处理 768 维 BERT 向量），反而变慢。

fit 之后怎么高效批量查询

fit() 只能调用一次，传入全部训练向量（shape: (n_samples, n_features)）。后续所有查询必须用 kneighbors()，别反复 fit 单个向量。

Python Sdk

inference.sh 的 Python SDK：运行 AI 应用、构建智能体，并集成 150 多个模型。包名：inferencesh (pip install inferencesh)。支持同步/异步……

下载

批量查询比单次循环快一个数量级：

• 把多个查询向量堆成二维数组，如 queries.shape = (batch_size, n_features)
• 调用 nn.kneighbors(queries, n_neighbors=5)，一次性返回所有结果
• 如果只关心最近邻索引，加 return_distance=False 省掉距离计算

错误做法：对每个 query 调用一次 kneighbors()，Python 层开销大，还可能触发重复索引重建（某些 backend 下）。

如何从距离转成余弦相似度

NearestNeighbors 默认返回欧氏距离，但你想要 [−1, 1] 区间的余弦相似度。前提是训练和查询向量都已 L2 归一化：

from sklearn.preprocessing import normalize
X_train_norm = normalize(X_train, norm='l2', axis=1)
X_query_norm = normalize(X_query, norm='l2', axis=1)

此时欧氏距离 d 和余弦相似度 s 满足：s = 1 - d²/2。所以拿到 distances 后直接算：

cosine_similarities = 1 - (distances ** 2) / 2

别用 1 - distances 或其它线性变换——数学上不成立。另外注意：如果没归一化就硬套这个公式，结果完全不可信。

高维稀疏向量（如 TF-IDF）建议用 metric="manhattan" + algorithm="brute"，余弦转换不适用，得另走 sklearn.metrics.pairwise.cosine_similarity 路线。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！