Semantic Search API 数据集概述
基本信息
- API名称：Semantic Search
- 提供者：Colin McGraw
- 类别：Search
- 流行度：8.6 Popularity
- 服务等级：100% Service Level
- 延迟：95ms Latency
- 测试覆盖率：100% Test
订阅计划
- BASIC：$0.00 / 月
- PRO：$7.00 / 月
- ULTRA：$16.00 / 月
功能概述
该API通过TF-IDF向量化和余弦相似度评分理解语义含义，与传统关键词搜索不同。它通过Levenshtein距离处理拼写错误，扩展同义词，并对标题匹配给予更高权重，即使面对杂乱的自然语言查询也能提供精确结果。其将杂乱的用户查询映射到精确的目录项，使用TF-IDF向量相似度和余弦评分，支持同义词扩展、模糊匹配和二元语法分析。
技术特性
- 核心方法：TF-IDF相似度匹配与余弦评分
- 附加功能：模糊匹配、同义词扩展、二元语法分析
- 模型要求：无需机器学习模型
- 处理方式：所有处理均在本地完成，无状态
- 外部依赖：无
- 架构：无状态，不持久化数据
主要端点
- 端点：
POST /api/semantic-search
- 认证：所有请求都需要
X-RapidAPI-Proxy-Secret头（由RapidAPI自动处理）
请求参数
请求体字段
| 字段 |
类型 |
必填 |
描述 |
query |
字符串 |
是 |
搜索查询。可以是杂乱的、包含拼写错误或使用自然语言。 |
items |
数组 |
是 |
要搜索的条目数组 |
items[].id |
字符串 |
是 |
条目的唯一标识符 |
items[].text |
字符串 |
是 |
用于相似性匹配的文本内容 |
items[].title |
字符串 |
否 |
条目标题（在评分中由titleWeight加权） |
items[].category |
字符串 |
否 |
条目类别 |
items[].metadata |
对象 |
否 |
传递给结果的键值元数据 |
topK |
整数 |
否 |
返回的最大结果数。默认值：10 |
minScore |
数字 |
否 |
最小相似度分数阈值。默认值：0.01 |
fuzzyMatch |
布尔值 |
否 |
启用模糊匹配以容忍拼写错误。默认值：true |
synonymExpansion |
布尔值 |
否 |
启用同义词扩展。默认值：true |
titleWeight |
数字 |
否 |
标题匹配的权重乘数。默认值：2.0 |
请求示例
json
{
"query": "wireless noise cancelling headphones",
"items": [
{
"id": "prod_001",
"title": "Sony WH-1000XM5 Wireless Headphones",
"text": "Industry-leading noise cancellation with 30-hour battery life",
"category": "audio"
},
{
"id": "prod_002",
"title": "Bose QuietComfort 45",
"text": "Premium noise cancelling headphones with comfortable fit",
"category": "audio"
}
],
"topK": 10,
"fuzzyMatch": true,
"synonymExpansion": true,
"titleWeight": 2.0
}
响应格式
响应字段
| 字段 |
类型 |
描述 |
query |
字符串 |
原始查询 |
normalizedQuery |
字符串 |
规范化后的查询 |
totalItems |
整数 |
目录中的条目总数 |
matchedItems |
整数 |
匹配的条目数量 |
results |
数组 |
排序后的搜索结果 |
searchDurationMs |
数字 |
搜索持续时间（毫秒） |
结果对象字段
| 字段 |
类型 |
描述 |
id |
字符串 |
条目标识符 |
title |
字符串 或 null |
条目标题 |
category |
字符串 或 null |
条目类别 |
score |
数字 |
相关性分数 |
metadata |
对象 或 null |
传递的元数据 |
响应示例
json
{
"query": "wireless noise cancelling headphones",
"normalizedQuery": "wireless noise cancelling headphones",
"totalItems": 2,
"matchedItems": 2,
"results": [
{
"id": "prod_001",
"title": "Sony WH-1000XM5 Wireless Headphones",
"category": "audio",
"score": 0.87,
"metadata": null
},
{
"id": "prod_002",
"title": "Bose QuietComfort 45",
"category": "audio",
"score": 0.72,
"metadata": null
}
],
"searchDurationMs": 12.45
}
工作原理
- TF-IDF向量化：通过词频和跨目录的唯一性对术语进行加权
- 余弦相似度：测量查询和条目向量之间的语义相关性
- 模糊匹配：Levenshtein距离处理拼写错误和拼写变体
- 同义词扩展：使用相关术语扩展查询以进行更广泛的匹配
- 二元语法分析：捕获多词概念和复合短语
约束
| 约束 |
值 |
| ML模型 |
无 — 使用TF-IDF + 余弦相似度 |
| 外部依赖 |
无 |
| 架构 |
无状态 — 不持久化数据 |
错误响应
| 状态码 |
条件 |
消息 |
| 400 |
缺少查询或条目 |
Required field validation error |
| 401 |
未授权 |
Missing or invalid API key |
使用案例
- 电子商务搜索：匹配产品查询与目录，具有拼写错误容忍度
- 文档搜索：从自然语言问题中找到相关文档
- 内容推荐：将用户兴趣与文章或媒体匹配
- FAQ匹配：将支持查询路由到最相关的FAQ条目
