文本相似度 API 快速上手：参数解读、示例与注意事项
适用场景
文本相似度计算广泛用于内容审核、评论去重、AI 输出一致性校验、知识库匹配等场景。本文介绍的接口纯 PHP 本地运算，无外部上游依赖，平均响应低于 100 毫秒（根据素材 5000×5000 字符比对约 60-80 ms），适合对实时性要求较高的中小规模应用。
典型用例：
- 论坛评论查重：检测用户是否反复粘贴相同内容。
- AIGC 质量初筛：比对生成文本与 prompt 的语义相似度。
- 翻译回译验证：将译文再译回原文，计算相似度评估翻译是否准确。
- 客服话术匹配：用户输入与标准问句的近似程度判断。
接口能力边界
| 项目 | 说明 |
|---|---|
| 请求地址 | https://v1.apizero.cn/api/text-similarity |
| 请求方法 | POST |
| QPS 限制 | 10 次/秒（素材给出） |
| 每段文本长度 | 1～5000 字符（中英文均按 1 字符计） |
| 超长保护 | 超过 500 字符自动截取前 500 字符计算，并按比例还原得分（见下方说明） |
| 输出指标 | 余弦相似度、Jaccard 系数、编辑距离归一化、LCS 比率，以及加权综合评分与 5 级评级 |
注意：接口为匿名调用时每日有 100 次调用次数限制（素材表述），但本教程聚焦技术接入，不讨论维护复杂度；开发者可自行查看官方文档获取最新限制。
请求参数与鉴权
Header 参数
| 参数 | 是否必须 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
Authorization | 否 | string | API Key 鉴权头，格式Bearer sk_live_xxx；匿名调用时省略 | Bearer sk_live_xxxxxxxxxxxxxx |
Content-Type | 否 | string | 支持application/x-www-form-urlencoded或application/json | application/json |
若使用 API Key，建议从环境变量读取；若仅测试可匿名调用。
请求体（JSON 格式）
| 字段 | 必须 | 类型 | 描述 | 示例 |
|---|---|---|---|---|
text1 | 是 | string | 第一段文本，1-5000 字符 | "今天天气不错，适合出门散步" |
text2 | 是 | string | 第二段文本，1-5000 字符 | "今天天气真好，适合出门走走" |
请求体支持application/json或表单格式，本文以 JSON 为例。
curl 调用示例
以下命令演示使用 API Key 鉴权（请将$APIZERO_API_KEY替换为实际密钥）：
curl -sS -X POST \ -H "Authorization: Bearer $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text1":"今天天气不错，适合出门散步","text2":"今天天气真好，适合出门走走"}' \ "https://v1.apizero.cn/api/text-similarity"若匿名调用（每日限额内），可直接去掉-H "Authorization:..."行：
curl -sS -X POST \ -H "Content-Type: application/json" \ -d '{"text1":"今天天气不错，适合出门散步","text2":"今天天气真好，适合出门走走"}' \ "https://v1.apizero.cn/api/text-similarity"返回值解读
成功响应（HTTP 200）示例：
{ "code": 0, "data": { "level_name": "中度相似", "metrics": { "cosine": 0.5833, "edit_distance": 4, "edit_similarity": 0.6923, "jaccard": 0.4118, "lcs_length": 12, "lcs_similarity": 0.9231 }, "overall_score": 0.6471, "similarity_level": "moderately_similar", "text1_length": 13, "text2_length": 13, "truncated": false }, "msg": "成功", "request_id": "abc123def456" }字段说明
| 字段 | 类型 | 含义 |
|---|---|---|
code | int | 业务状态码，0 表示成功 |
msg | string | 状态描述 |
request_id | string | 本次请求唯一标识，便于排障 |
data.metrics.cosine | float | 余弦相似度，取值 [0,1]，权重 35% |
data.metrics.jaccard | float | Jaccard 系数（交集/并集），权重 25% |
data.metrics.edit_distance | int | 字符级编辑距离（Levenshtein），绝对值 |
data.metrics.edit_similarity | float | 编辑距离归一化相似度，权重 20% |
data.metrics.lcs_length | int | 最长公共子串长度 |
data.metrics.lcs_similarity | float | LCS 归一化相似度，权重 20% |
data.overall_score | float | 加权综合得分（公式见下方） |
data.similarity_level | string | 机器可读级别：almost_identical,highly_similar,moderately_similar,slightly_similar,different |
data.level_name | string | 中文级别：几乎相同 / 高度相似 / 中度相似 / 轻度相似 / 差异较大 |
data.text1_length | int | text1 实际字符数 |
data.text2_length | int | text2 实际字符数 |
data.truncated | bool | 是否因超长而截取（超过 500 字符时 true） |
加权综合得分 = cosine×0.35 + jaccard×0.25 + edit_similarity×0.20 + lcs_similarity×0.20（素材权重）。
常见错误与处理
1. HTTP 4xx 错误
| 状态码 | 可能原因 | 排查方法 |
|---|---|---|
| 400 | 缺少必填字段text1或text2；文本超过 5000 字符 | 检查请求体 JSON 格式，确认字段名和类型 |
| 401 | API Key 无效或过期 | 确认Authorization头格式为Bearer sk_live_... |
| 413 | 请求体过大 | （通常不会，5000 字文本体积很小） |
| 429 | 超出 QPS 限制（10 次/秒） | 增加请求间隔或使用队列 |
2. 业务错误码（code非 0）
- 若
code非 0，msg会给出具体原因，例如"文本长度超出限制"。 - 建议始终检查
code，不要仅依赖 HTTP 状态码。
3.data.truncated为 true
当某段文本超过 500 字符时，接口自动截取前 500 字符计算，并按截取比例对overall_score进行还原。还原后分数并非完全精确，适合快速筛选；若需高精度，建议应用层自行分段后取平均。
工程化注意事项
1. 文本长度限制处理
素材说明单段最多 5000 字符，建议客户端在发送前做长度校验，或通过String.length快速截断。若业务中常有超长文本，可考虑分段请求后加权平均。
2. 超长文本的截取策略
- 接口本身在字符数超过 500 时会自动截取前 500 并设置
truncated: true。如果业务场景对长文本相似度精度要求高，更推荐客户端按语义分段（如按句号拆分），分别请求后汇总。 - 注意：截取后只保留前 500 字符，可能丢失后半部分信息，导致相似度偏差。
3. 重试与幂等
- 请求应设置超时时间（建议 5 秒），并在超时或 5xx 错误时重试。
- 接口本身无幂等性保证，多次相同请求可能因负载差异返回略有不同的结果（但理论上一样）；重试不会产生副作用。
4. 缓存策略
若业务中有大量重复比对（如相同两段文本多次请求），可在应用层建立 Map 缓存，以text1 + "|||" + text2为键缓存结果，减少重复调用。
5. 监控与日志
- 记录每次请求的
request_id、overall_score和truncated字段，便于后续分析。 - 关注
truncated为 true 的请求比例，若持续偏高，需考虑调整客户端分割策略。
参考文档
- 接口文档页
- 原始 Markdown 文档