免费中文分词（文本处理）：语义距离接入点边界——distance 取极大值是什么意思？
免费中文分词文本处理中文NLPAPI教程ShowAPI # 免费中文分词（文本处理）：语义距离接入点边界——distance 取极大值是什么意思？
> 接口：语义距离（2663-10）｜是否免费：是（含档位限制）｜返回格式：JSON｜适用人群：做语义相似/聚类的中高级开发者｜阅读时间：约 6 分钟
## 核心要点
- 语义距离（2663-10）传入 `word1` + `word2`，返回单个数值 `distance`：**越小表示词义越相近**。
- 实测发现：对不相关的词对，接口返回 `distance = 9223372036854775807`（即 Long.MAX_VALUE），表示「极不相近 / 未收录」，**这不是错误码、也不是 0**。
- 用阈值做「相近 / 无关」判据时，必须先识别这个极大值边界，避免误判。
## Why
做同义词归并、 query 改写、文本聚类时，常常需要量化「这两个词有多相关」。语义距离接口直接给你一个数字。但坑在于：当两个词毫无关系或词库未收录时，它不会报错，而是返回一个极大的距离值——如果你把它当成「普通的大距离」去归一化，可能污染整条相似度流水线。本文把这个边界讲清楚，让你少踩坑。
## What
**接口速览**
| 项 | 值 |
|------|------|
| 接口地址 | `https://route.showapi.com/2663-10` |
| 必填参数 | `word1`、`word2` |
| 返回 | `distance`: Number（越小越相近） |
## How
带边界判断的调用：
```python
import requests
LONG_MAX = 9223372036854775807 # 接口对「极不相近/未收录」返回的极大值
def semantic_distance(w1, w2):
resp = requests.post(
"https://route.showapi.com/2663-10",
params={"appKey": "YOUR_APPKEY"},
data={"word1": w1, "word2": w2},
timeout=10,
).json()
body = resp["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(body.get("remark"))
return body.get("distance")
def is_related(w1, w2, threshold=10):
d = semantic_distance(w1, w2)
if d >= LONG_MAX:
return False, "未收录/极不相近"
return d <= threshold, f"distance={d}"
print(is_related("苹果", "水果")) # 相近
print(is_related("苹果", "香蕉")) # 实测返回 LONG_MAX -> 极不相近
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/2663-10?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "word1=苹果" \
--data-urlencode "word2=香蕉"
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": 0,
"remark": "成功",
"distance": 9223372036854775807
}
}
```
> 上例「苹果」与「香蕉」实测返回的 `distance` 即为 `9223372036854775807`（Long.MAX_VALUE）。`ret_code` 为 0、请求完全成功，只是这两个词在语义模型里被判为「极不相近 / 未收录」。
## 进阶 / 边界
- **极大值的含义**：`9223372036854775807` 是 64 位有符号整数上限，接口用它表示「无法计算有效距离 / 词义极不相近」，等价于「不相关」，不是异常。
- **不要直接归一化**：若把该极大值当普通距离参与 `1/(1+d)` 之类计算，会得到接近 0 的假相似度，污染结果。先判等 `>= LONG_MAX` 再过滤。
- **阈值是业务参数**：「多小算相近」没有统一答案，建议用你的真实词对做标定。
- **免费档限制**：默认档位下仍可能返回该极大值或空结果，见 [免费档位与调用策略](https://www.showapi.com/guides/cnseg-free-tier-2663)。
## FAQ
**Q1：distance 是负数吗？**
距离非负；越小越相近，极大值（Long.MAX_VALUE）表示极不相近/未收录。
**Q2：返回极大值是不是接口挂了？**
不是。`ret_code` 为 0 表示调用成功，极大值是「不相关」的语义表示。
**Q3：怎么判断两个词相关？**
先排除 `distance >= 9223372036854775807`，再按你的业务阈值比较大小。
**Q4：距离有单位吗？**
无单位，仅为相对相近度，数值越小越近；绝对值含义随词对而异。
**Q5：免费档也返回极大值吗？**
会，极大值与档位无关；但档位限制下也可能直接返回空业务数据。
## 相关能力 / 下一步阅读
- [免费中文分词（文本处理）：文本推荐接入点怎么用？](https://www.showapi.com/guides/cnseg-recommend-2663)
- [免费中文分词（文本处理）：免费档位到底能调多少？](https://www.showapi.com/guides/cnseg-free-tier-2663)
- [免费中文分词（文本处理）：返回结构与公共字段全解](https://www.showapi.com/guides/cnseg-response-2663)
> 本系列共 14 篇：查看[免费中文分词（文本处理）API 指南总目录](https://www.showapi.com/guides/cnseg-guides-2663)
