余弦相似度原理与API实现详解

1. 余弦相似度计算基础

在自然语言处理和机器学习领域，余弦相似度是衡量两个向量方向相似性的重要指标。它通过计算两个向量夹角的余弦值来评估它们的相似程度，完全相同的向量得分为1，正交向量为0，相反方向为-1。

1.1 数学原理详解

余弦相似度的计算公式为：

cos(θ) = (A·B) / (||A|| × ||B||)

其中：

• A·B 表示向量A和B的点积
• ||A|| 和 ||B|| 分别表示向量的L2范数（欧几里得长度）

这个公式本质上计算的是两个向量在方向上的相似性，而不考虑它们的绝对大小。这使得它特别适合用于文本相似度比较，因为文本向量的长度往往与文档长度相关，而方向更能反映内容语义。

关键点：余弦相似度对向量长度不敏感的特性，使其成为比较不同长度文本嵌入向量的理想选择。

1.2 向量归一化的重要性

在实际应用中，我们通常会对向量进行归一化处理（即将向量长度调整为1）。这样计算余弦相似度时，分母就变为1，公式简化为：

cos(θ) = A·B

这种优化不仅简化计算，还能提高数值稳定性。归一化后的向量比较在推荐系统、语义搜索等场景中尤为常见。

2. 余弦相似度API实现

2.1 接口设计与参数说明

基于RESTful API设计，我们实现了一个计算余弦相似度的服务端点：

python复制POST http://127.0.0.1:8000/api/knowledge/similarity/calculate

请求参数示例：

json复制{
    "x_collection": "demo_knowledge_base",
    "y_collection": "demo_knowledge_base", 
    "x_max_items": 30,
    "y_max_items": 30
}

参数说明：

• x_collection/y_collection: 指定要比较的两个向量集合名称
• x_max_items/y_max_items: 限制每个集合返回的最大项目数

2.2 响应数据结构解析

API返回的JSON结构包含丰富的信息：

json复制{
    "success": true,
    "res