文本相似度 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否stringAPI Key 鉴权头，格式Bearer sk_live_xxx；匿名调用时省略Bearer sk_live_xxxxxxxxxxxxxx
Content-Type否string支持application/x-www-form-urlencoded或application/jsonapplication/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" }

字段说明

字段类型含义
codeint业务状态码，0 表示成功
msgstring状态描述
request_idstring本次请求唯一标识，便于排障
data.metrics.cosinefloat余弦相似度，取值 [0,1]，权重 35%
data.metrics.jaccardfloatJaccard 系数（交集/并集），权重 25%
data.metrics.edit_distanceint字符级编辑距离（Levenshtein），绝对值
data.metrics.edit_similarityfloat编辑距离归一化相似度，权重 20%
data.metrics.lcs_lengthint最长公共子串长度
data.metrics.lcs_similarityfloatLCS 归一化相似度，权重 20%
data.overall_scorefloat加权综合得分（公式见下方）
data.similarity_levelstring机器可读级别：almost_identical,highly_similar,moderately_similar,slightly_similar,different
data.level_namestring中文级别：几乎相同 / 高度相似 / 中度相似 / 轻度相似 / 差异较大
data.text1_lengthinttext1 实际字符数
data.text2_lengthinttext2 实际字符数
data.truncatedbool是否因超长而截取（超过 500 字符时 true）

加权综合得分 = cosine×0.35 + jaccard×0.25 + edit_similarity×0.20 + lcs_similarity×0.20（素材权重）。

常见错误与处理

1. HTTP 4xx 错误

状态码可能原因排查方法
400缺少必填字段text1或text2；文本超过 5000 字符检查请求体 JSON 格式，确认字段名和类型
401API 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 文档