<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 文本相似度

> 纯本地计算的文本相似度比对，输入两段文本（每段 ≤ 5000 字）输出 4 种相似度指标 + 加权综合评分 + 5 级评级。

• **零延迟零成本**：纯 PHP 本地计算，无外部上游依赖，平均响应 < 100ms
• **4 种指标**：余弦相似度（35%）+ Jaccard 系数（25%）+ 编辑距离归一化（20%）+ LCS 比率（20%）
• **5 级评级**：几乎相同 / 高度相似 / 中度相似 / 轻度相似 / 差异较大
• **修复源码 bug**：自实现 mb_levenshtein 字符级编辑距离，杜绝 PHP 内置 levenshtein 按字节计算导致的 85 汉字崩溃问题
• **超长保护**：超过 500 字符自动截取并按比例还原，5000×5000 字符比对约 60-80ms
• **典型场景**：评论查重、AI 生成内容检测、多语言翻译质量评估、客服话术匹配

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `text-similarity` |
| 接口名称 | 文本相似度 |
| 接口地址 | `https://v1.apizero.cn/api/text-similarity` |
| 请求方法 | `POST` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 500 次（已认证用户） |
| 匿名每日额度 | 100 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 100 次、QPS 5；登录用户每日 500 次、QPS 10（全部免费）。零上游成本，纯本地计算。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `text1` | `string` | 是 | 第一段文本，1-5000 字符（中英文均按 1 字符计） | `今天天气不错，适合出门散步` |
| `text2` | `string` | 是 | 第二段文本，1-5000 字符 | `今天天气真好，适合出门走走` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 100 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |
| `Content-Type` | `string` | 否 | 支持 application/x-www-form-urlencoded 或 application/json | `application/json` |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/text-similarity" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text1": "今天天气不错，适合出门散步",
  "text2": "今天天气真好，适合出门走走"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `text1_length` | `number` | text1 字符长度（mb_strlen） | — |
| `text2_length` | `number` | text2 字符长度 | — |
| `overall_score` | `number` | 综合相似度评分 0.0-1.0（保留 4 位小数） | — |
| `similarity_level` | `string` | 相似度等级英文枚举：nearly_identical / highly_similar / moderately_similar / slightly_similar / different | — |
| `level_name` | `string` | 相似度等级中文：几乎相同 / 高度相似 / 中度相似 / 轻度相似 / 差异较大 | — |
| `metrics` | `object` | 详细指标对象 | — |
| `metrics.cosine` | `number` | 余弦相似度 0-1（基于 2-gram 词频向量），权重 35% | — |
| `metrics.jaccard` | `number` | Jaccard 相似系数 0-1（2-gram 集合交并比），权重 25% | — |
| `metrics.edit_similarity` | `number` | 编辑距离归一化相似度 0-1（1 - distance/maxLen），权重 20% | — |
| `metrics.lcs_similarity` | `number` | LCS 最长公共子序列归一化比率 0-1（2 × lcsLen / (len1+len2)），权重 20% | — |
| `metrics.edit_distance` | `number` | 编辑距离原始值（字符数；超过 500 字符截取后按比例还原） | — |
| `metrics.lcs_length` | `number` | LCS 最长公共子序列长度（截取后的实际值） | — |
| `truncated` | `boolean` | edit/LCS 是否经过 500 字符截取近似（仅 cosine/jaccard 始终基于全文） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "text1_length": 13,
        "text2_length": 13,
        "overall_score": 0.6471,
        "similarity_level": "moderately_similar",
        "level_name": "中度相似",
        "metrics": {
            "cosine": 0.5833,
            "jaccard": 0.4118,
            "edit_similarity": 0.6923,
            "lcs_similarity": 0.9231,
            "edit_distance": 4,
            "lcs_length": 12
        },
        "truncated": false
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：text1 / text2 任一为空 / 超过 5000 字符 |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线，纯本地计算无上游依赖
  - 4 种相似度指标加权融合：余弦 35% + Jaccard 25% + Edit 20% + LCS 20%
  - 修复源码 BUG：自实现 mb_levenshtein 按字符（非字节）计算编辑距离，杜绝中文 85 字以上崩溃问题
  - 修复源码 BUG：源码 levenshtein else 分支用 mb_substr(0,200) 截取后仍可能超 255 字节限制 → 已用纯字符级算法替代
  - LCS 空间优化为 O(min(m,n))，5000×5000 比对内存 < 200KB
  - 超过 500 字符自动截取并按比例还原 edit_distance（保证 P99 响应 < 100ms）
  - 新增 truncated 字段，告知前端是否启用了截取近似
  - 新增 metrics.lcs_length 字段，便于查重场景直接读取「连续相同片段长度」
  - 5 级评级：nearly_identical(≥0.9) / highly_similar(≥0.7) / moderately_similar(≥0.4) / slightly_similar(≥0.2) / different
  - 支持 application/json 请求体

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/text-similarity`

Source: `https://apizero.cn/aidocs/text-similarity/raw.md`
Last updated: 2026-05-12T01:31:07+08:00