中文文本相似度检测接口批量匹配：单文本 vs 候选库如何定位最相似项
# 中文文本相似度检测接口批量匹配：单文本 vs 候选库如何定位最相似项
> 元信息：接口/接入点 批量检测接口（294/2）· 免费 · 请求方式 POST/GET · 返回格式 JSON · 适用人群 开发者、算法/数据工程师 · 阅读时间 约 7 分钟
## 核心要点
- 接入点 2（294/2）是**同步批量**：一次请求传 1 个 `t1` 与一组候选 `t2` 数组，返回**最匹配项的数组下标 `mostLike`** 与相似度 `likeValue`。
- 与接入点 1 不同，接入点 2 不返回 `like`，而是 `likeValue`；`mostLike` 是下标不是分值。
- 它是单次请求内的同步匹配，并非"提交任务 + 异步回调"的批量订阅模型。
## Why：什么时候用批量而不是两两比
当你要把"一条新内容"去和"一个候选库"找最像的那条（标问匹配、知识库查重、意图归类），如果每两条调一次接入点 1，调用次数是 N；用接入点 2 一次请求就能拿到最匹配项，调用次数降到 1，既省额度又省延迟。
## What：批量接口速览
| 项 | 说明 |
|----|------|
| 接口地址 | `https://route.showapi.com/294-2?appKey={your_appKey}` |
| 接入点说明 | 目前暂不支持英文及数字的相似度检测 |
| 必填参数 | `t1`（String，第 1 个文本）、`t2`（**数组**，候选文本列表） |
| 返回字段 | `mostLike`（最匹配下标）、`likeValue`（相似度）、`ret_code` |
| 单文本上限 | 最大 2M 字节 |
## How：一次定位最相似项
### 步骤 1：准备候选数组
`t2` 传 JSON 数组字符串，例如 `['这是测试文本','天天向上']`。下标从 0 开始，`mostLike` 即最匹配项在数组中的位置。
### 步骤 2：调用并解析
**Python**
```python
import requests, json
def batch_most_similar(text, candidates):
r = requests.post(
"https://route.showapi.com/294-2",
params={"appKey": "YOUR_APPKEY"},
data={"t1": text, "t2": json.dumps(candidates, ensure_ascii=False)},
timeout=10,
).json()
b = r["showapi_res_body"]
if b.get("ret_code") != 0:
raise RuntimeError(r.get("showapi_res_error"))
return b["mostLike"], b["likeValue"]
cands = ["如何重置密码", "怎么修改绑定手机", "忘记登录密码怎么办"]
idx, score = batch_most_similar("密码忘了怎么找回", cands)
print("最匹配:", cands[idx], "相似度:", score)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/294-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d 't1=密码忘了怎么找回&t2=["如何重置密码","怎么修改绑定手机","忘记登录密码怎么办"]'
```
**Node.js（fetch）**
```javascript
const cands = ["如何重置密码", "怎么修改绑定手机", "忘记登录密码怎么办"];
const url = "https://route.showapi.com/294-2?appKey=YOUR_APPKEY";
const body = new URLSearchParams({
t1: "密码忘了怎么找回",
t2: JSON.stringify(cands),
});
fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
signal: AbortSignal.timeout(10000),
})
.then((r) => r.json())
.then((res) => {
const b = res.showapi_res_body;
if (b.ret_code === 0) console.log("最匹配下标", b.mostLike, "相似度", b.likeValue);
else console.error("失败", res.showapi_res_error);
})
.catch((e) => console.error("请求异常", e));
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"mostLike": 0,
"ret_code": 0,
"likeValue": 1
}
}
```
- `mostLike: 0` → 候选数组第 0 项（`"如何重置密码"`）与 `t1` 最相似。
- `likeValue: 1` → 对应相似度满分。
> 字段完整定义见[《返回字段全解》](https://www.showapi.com/guides/text-similarity-response-fields-294)。
## 进阶 / 边界
- **候选集别无限大**：虽然单文本上限 2M 字节，但候选数组越长，单次请求体越大、耗时越高。建议按业务维度裁剪候选集（同意图域、同频道）后再比。
- **只给最相似一项**：接口返回的是"最匹配的一个下标 + 其相似度"，不会返回所有候选的排序列表。若要 Top-K，需要把候选分批或自行二次筛选。
- **同步模型**：一次 HTTP 请求内完成匹配并返回，没有回调/订阅；大批量请分批并发并遵守档位 QPS。
## FAQ
**Q1：mostLike 和 likeValue 分别是什么？**
`mostLike` 是最匹配文本在 `t2` 数组中的**下标**；`likeValue` 是 `t1` 与该最匹配项的相似度（0~1）。
**Q2：批量接口是异步的吗？有回调吗？**
不是异步。接入点 2 是同步请求-响应：一次请求传 t1 与 t2 数组，立即返回最匹配下标与相似度，无订阅推送/回调。
**Q3：能返回所有候选的相似度排序吗？**
不能。接口只返回最匹配的一项（mostLike + likeValue）。需要 Top-K 排序时，需分批或自行处理候选集。
**Q4：t2 数组最大能放多少条？**
文档规定单文本最大 2M 字节（适用于 t1、t2 整体请求体级别），未给出数组条数硬上限；实践中建议控制候选集规模以获得稳定时延。
## 下一步阅读
- [中文文本相似度检测接口返回字段全解：like / likeValue / mostLike / ret_code 一文读懂](https://www.showapi.com/guides/text-similarity-response-fields-294)
- [中文文本相似度检测接口实战：UGC 评论 / 文章去重从采集到判重的全链路设计](https://www.showapi.com/guides/text-similarity-dedup-294)
- [免费档位下如何设计缓存节省调用？L0~L4 档位与 QPS 限制下的优化](https://www.showapi.com/guides/text-similarity-cache-cost-294)
- **本系列共 12 篇**：查看[中文文本相似度检测接口指南总目录](https://www.showapi.com/guides/text-similarity-guides-294)
