博查AI Semantic Reranker API 使用指南：提升搜索排序的语义理解能力
·
博查AI Semantic Reranker API 使用指南：提升搜索排序的语义理解能力
一、API简介
Bocha Semantic Reranker是一种基于文本语义的排序模型（Rerank Model），它的主要用途是提升搜索结果的质量。在搜索推荐系统中，Bocha Semantic Reranker可以基于关键字搜索、向量搜索和混合搜索的初步排序结果的质量进行优化。具体来说，在初始的BM25排序或RRF排序之后，Bocha Semantic Reranker会从top-N候选结果中，利用语义信息对文档进行二次排序。这一过程中，模型会根据查询语句与文档内容之间的深层语义匹配情况，给出每个文档的排序结果和得分，从而改善用户的搜索体验。由于这种方法是对初步排序结果进行二次优化，因此被称为“Reranker”。
核心价值：
- 精准排序：80M参数模型媲美世界一线280M、560M参数模型的排序效果；
- 成本优化：比同类模型推理速度更快，成本更低。
二、工作原理
语义评分流程
博查语义排序模型的评分过程是基于查询语句（用户的输入问题）以及与之匹配的文档内容（通常是最高512个tokens的文本）进行的。评分的过程如下：
- 评估语义相关性：模型会评估查询语句与每个文档的语义相关性，判断文档是否能够有效回答用户的查询或与查询意图高度匹配。
- 分配Rerank Score：根据语义相关性，模型为每个文档分配一个rerankScore，分数的范围从0到1。分数越高，表示文档与查询的语义相关性越强，越符合用户需求。通常，分数接近1表示高度相关，分数接近0表示不相关或低相关。
评分标准
| 分数范围 | 相关性级别 | 说明 |
|---|---|---|
| 0.75~1.0 | 高度相关 | 文档完全回答了问题，可能包含额外相关信息 |
| 0.5~0.75 | 相关 | 文档回答了问题但缺乏完整细节 |
| 0.2~0.5 | 部分相关 | 文档只解决了问题的某些方面 |
| 0.1~0.2 | 轻微相关 | 文档仅回答了一小部分问题 |
| 0~0.1 | 不相关 | 文档与问题无关 |
三、快速开始
1. 获取API密钥
-
访问博查AI开放平台，点击「使用排序API」。
-
注册/登录账号
-
进入「API KEY管理」创建密钥
2. 基础使用示例（Python）
import requests
url = "https://api.bochaai.com/v1/rerank"
api_key = "sk-********" # 替换为您的API密钥
payload = {
"model": "gte-rerank", # 使用限时免费模型
"query": "人工智能在医疗领域的应用",
"documents": [
"人工智能在影像诊断中的最新进展...",
"医疗机器人手术系统的技术突破...",
"自然语言处理在电子病历分析中的应用...",
],
"top_n": 2,
"return_documents": True
}
headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
response = requests.post(url, json=payload, headers=headers)
results = response.json()
# 打印排序结果
for item in results['data']['results']:
score = item['relevance_score']
print(f"文档 {item['index']+1} | 相关性: {score:.4f}")
print(f"内容摘要: {item['document']['text'][:100]}...\n")
四、API使用详解
1. API接口
- 接口域名:
https://api.bochaai.com - Endpoint:
https://api.bochaai.com/v1/rerank
2. 请求参数
请求方式: POST
请求头(HEADERS)
| 参数 | 取值 | 说明 |
|---|---|---|
Authorization | Bearer {API KEY} | 鉴权凭证，示例：Bearer xxxxxx，API KEY请先前往博查AI开放平台 --> API KEY 管理中获取。 |
Content-Type | application/json | 请求体格式 |
请求体(BODY)
| 参数名 | 类型 | 必填 | 说明 | 默认值 | 示例值 |
|---|---|---|---|---|---|
model | String | 是 | 使用的排序模型 | - | 排序使用的模型版本。 当前版本模型： bocha-semantic-reranker-cn，邀测中 bocha-semantic-reranker-en，邀测中 gte-rerank，已开放，限时免费使用 |
query | String | 是 | 用户查询语句 | - | "气候变化对农业的影响" |
documents | Array<String> | 是 | 待排序的文档列表（最多50个） | - | ["文档1内容", "文档2内容"] |
top_n | Integer | 否 | 返回的Top文档数量 | 文档总数 | 5 |
return_documents | Boolean | 否 | 是否在结果中返回文档原文 | false | true,false |
3. 响应参数
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 状态码。200 代表调用成功。 |
log_id | String | 请求id。 |
msg | String | 状态信息。 |
data | Object | 返回的结果。 |
data.model | String | 排序使用的模型。 |
data.results | Array | 排序结果。 |
4. 调用示例
请求体:
{
"model": "gte-rerank",
"query": "阿里巴巴2024年的ESG报告",
"top_n": 2,
"return_documents": true,
"documents": [
"阿里巴巴集团发布《2024财年环境、社会和治理（ESG）报告》（下称“报告”），详细分享过去一年在 ESG各方面取得的进展。 报告显示，阿里巴巴扎实推进减碳举措，全集团自身运营净碳排放和价值链碳强度继续实现“双降”。 集团亦持续利用数字技术和平台能力，服务于无障碍、医疗、适老化和中小微企业等普惠发展。 阿里巴巴集团首席执行官吴泳铭在报告中表示：“ESG的核心是围绕如何成为一家更好的公司。 25年来，我们与ESG相关的行动所构成的公司底色，与创造商业价值的阿里巴巴一样重要。 在集团明确‘用户为先’和‘AI 驱动’的两大业务战略的同时，我们也明确ESG作为阿里巴巴基石战略之一的定位不变。 阿里巴巴在减少碳排放上取得扎实进展。",
"ESG的核心是围绕如何成为一家更好的公司。 今年是阿里巴巴成立25年。 25年来，阿里巴巴秉持“让天下没有难做的生意”，协助国内电商繁荣发展；坚持开放生态，魔搭社区已开放了超3800个开源模型；助力乡村振兴，累计派出了29位乡村特派员深入27个县域；推动平台减碳，首创了范围3+减碳方案；坚持全员公益，用“人人3小时”带来小而美的改变……这些行动所构成的公司底色，与创造商业价值的阿里巴巴一样重要。 我希望这个过程中，每一个阿里人都能学会做难而正确的选择，保持前瞻、保持善意、保持务实。 一个更好的阿里巴巴，值得我们共同努力。 阿里巴巴二十多年来坚持不变的使命，是让天下没有难做的生意。 今天，这一使命被赋予了新的时代意义。"
]
}
成功响应(HTTP 200)
{
"code": 200,
"log_id": "56a3067f9b92dfd0",
"msg": null,
"data": {
"model": "gte-rerank",
"results": [
{
"index": 0,
"document": { "text": "文档内容..." },
"relevance_score": 0.8166
},
{
"index": 1,
"document": { "text": "文档内容..." },
"relevance_score": 0.7234
}
]
}
}
五、高级应用场景
1. 结合搜索引擎使用
先使用联网搜索API进行文档搜索，以Bocha Search API为例：
请求体：
{
"query": "阿里巴巴2024年的ESG报告",
"freshness": "noLimit",
"summary": false,
"count": 5
}
响应体：
{
"code": 200,
"log_id": "549facf21552502b",
"msg": null,
"data": {
"_type": "SearchResponse",
"queryContext": {
"originalQuery": "阿里巴巴2024年的ESG报告"
},
"webPages": {
"webSearchUrl": "https://bochaai.com/search?q=阿里巴巴2024年的ESG报告",
"totalEstimatedMatches": 10000000,
"value": [
{
"id": "https://api.bochaai.com/v1/#WebPages.0",
"name": "阿里巴巴：2024年环境、社会和治理（ESG）报告（英文版）.pdf",
"snippet": "阿里巴巴:2024年环境、社会和治理(ESG)报告(英文版).pdf 智库VIP会员,享80万+报告、方案和资料 开通会员 70 MB,200 页,发布者:wx*ce,发布于2024-07-24 加载",
"siteName": "外唐智库",
...
},
{
"id": "https://api.bochaai.com/v1/#WebPages.1",
"name": "2024年环境、社会和治理(ESG)报告",
"snippet": "公众号 『 碳中和报告之家 』 获取完整报告\n报告共186页\n导读: 报告强调了集团的使命——“让天下没有难做的生意”,并通过技术创新和平台能力支持中小微企业的发展。阿里巴巴致力于构建一个包容、可持",
"siteName": "手机搜狐网",
...
},
{
"id": "https://api.bochaai.com/v1/#WebPages.2",
"name": "阿里巴巴发布2024年ESG报告:保持前瞻、保持善意、保持务实_中国经济网——国家经济门户",
"snippet": "当前位置 首页 > 新闻 > 国内时政更多新闻 > 正文 7 月 22 日,阿里巴巴集团发布《 2024 环境、社会和治理报告》(以下简称“ ESG 报告”)。在 ESG 战略方向的指引下,阿里巴巴",
"siteName": "中国经济网",
...
},
{
"id": "https://api.bochaai.com/v1/#WebPages.3",
"name": "2024年环境、社会和治理(ESG)报告_企业_和平台_集团",
"snippet": "公众号 『 碳中和报告之家 』 获取完整报告 报告共186页 导读: 报告强调了集团的使命——“让天下没有难做的生意”,并通过技术创新和平台能力支持中小微企业的发展。阿里巴巴致力于构建一个包容、可持续",
"siteName": "搜狐",
},
{
"id": "https://api.bochaai.com/v1/#WebPages.4",
"name": "阿里巴巴发布2024年ESG报告 持续推进减碳与数字化普惠-阿里巴巴集团",
"snippet": "阿里巴巴集团发布《 2024 财年环境、社会和治理( ESG )报告 》(下称“报告”),详细分享过去一年在 ESG 各方面取得的进展。报告显示,阿里巴巴扎实推进减碳举措,全集团自身运营净碳排放和价值",
"siteName": "阿里巴巴集团官方网站",
...
}
],
"someResultsRemoved": true
},
"images": {
...
},
"videos": null
}
}
将搜索到网页的摘要内容进行语义重排：
响应体：
{
"code": 200,
"log_id": "99056a5d7c5e1542",
"msg": null,
"data": {
"model": "gte-rerank",
"results": [
{
"index": 2,
"document": {
"text": "当前位置 首页 > 新闻 > 国内时政更多新闻 > 正文 7 月 22 日,阿里巴巴集团发布《 2024 环境、社会和治理报告》(以下简称“ ESG 报告”)。在 ESG 战略方向的指引下,阿里巴巴"
},
"relevance_score": 0.7350808762984996
},
{
"index": 4,
"document": {
"text": "阿里巴巴集团发布《 2024 财年环境、社会和治理( ESG )报告 》(下称“报告”),详细分享过去一年在 ESG 各方面取得的进展。报告显示,阿里巴巴扎实推进减碳举措,全集团自身运营净碳排放和价值"
},
"relevance_score": 0.7170636998622928
},
{
"index": 0,
"document": {
"text": "阿里巴巴:2024年环境、社会和治理(ESG)报告(英文版).pdf 智库VIP会员,享80万+报告、方案和资料 开通会员 70 MB,200 页,发布者:wx*ce,发布于2024-07-24 加载"
},
"relevance_score": 0.6958410489237444
},
{
"index": 3,
"document": {
"text": "公众号 『 碳中和报告之家 』 获取完整报告 报告共186页 导读: 报告强调了集团的使命——“让天下没有难做的生意”,并通过技术创新和平台能力支持中小微企业的发展。阿里巴巴致力于构建一个包容、可持续"
},
"relevance_score": 0.6216471810443929
},
{
"index": 1,
"document": {
"text": "公众号 『 碳中和报告之家 』 获取完整报告\n报告共186页\n导读: 报告强调了集团的使命——“让天下没有难做的生意”,并通过技术创新和平台能力支持中小微企业的发展。阿里巴巴致力于构建一个包容、可持"
},
"relevance_score": 0.61456155727624
}
]
}
}
整体流程总结：
# 第一步：获取初始搜索结果
search_results = get_initial_search("Python机器学习库")
# 第二步：提取文档内容
documents = [result['content'] for result in search_results[:20]]
# 第三步：语义重排序
reranked = rerank_documents(
query="Python机器学习库",
documents=documents,
top_n=5
)
# 第四步：使用优化后的结果
for result in reranked['data']['results']:
show_result(search_results[result['index']])
2. 多模型对比分析
models = ["gte-rerank", "bocha-semantic-reranker-cn"]
for model in models:
result = requests.post(RERANK_URL, json={
"model": model,
"query": query,
"documents": documents,
"top_n": 3
}, headers=headers)
print(f"\n=== {model} 排序结果 ===")
for item in result.json()['data']['results']:
print(f"文档 {item['index']} | 得分: {item['relevance_score']:.4f}")
3. 相关性阈值过滤
def filter_relevant_documents(query, documents, threshold=0.5):
reranked = rerank_documents(query, documents)
return [
(item['index'], item['relevance_score'])
for item in reranked['data']['results']
if item['relevance_score'] >= threshold
]
# 使用示例
relevant_docs = filter_relevant_documents(
"区块链技术原理",
documents_list,
threshold=0.6
)
六、错误处理
| 状态码 | 错误信息 | 原因 | 解决方案 |
|---|---|---|---|
| 400 | Missing parameter query | 缺少必要参数 | 检查请求体完整性 |
| 401 | Invalid API KEY | API密钥无效 | 检查/更新API密钥 |
| 429 | Rate limit exceeded | 请求频率超限 | 降低调用频率或升级套餐 |
| 500 | Internal server error | 服务器内部错误 | 联系技术支持 |
七、常见问题
Q1：Reranker与普通搜索排序有何不同？
A：传统搜索（如BM25）基于关键词匹配，而Reranker通过深度学习模型理解查询和文档的语义关系，能更好处理同义词、上下文和相关概念。
Q2：文档长度有限制吗？
A：模型最佳处理长度为前512个token，建议预处理文档时截取关键内容。
Q3：如何处理大规模文档排序？
推荐方案：
- 先用传统方法筛选Top 100文档
- 分批调用Reranker（每次20-50个文档）
- 合并并排序最终结果
立即体验强大搜索能力：前往博查AI开放平台
本文档更新于2025年7月，适用于Semantic Reranker API v1版本
技术咨询：support@bochaai.com
商务合作：business@bochaai.com
北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台
更多推荐
28
0- 0
已为社区贡献1条内容
所有评论(0)