文本相似度 API 快速上手：参数解读、示例与注意事项

适用场景

文本相似度计算广泛用于内容审核、评论去重、AI 输出一致性校验、知识库匹配等场景。本文介绍的接口纯 PHP 本地运算，无外部上游依赖，平均响应低于 100 毫秒（根据素材 5000×5000 字符比对约 60-80 ms），适合对实时性要求较高的中小规模应用。

典型用例：

• 论坛评论查重：检测用户是否反复粘贴相同内容。
• AIGC 质量初筛：比对生成文本与 prompt 的语义相似度。
• 翻译回译验证：将译文再译回原文，计算相似度评估翻译是否准确。
• 客服话术匹配：用户输入与标准问句的近似程度判断。

接口能力边界

注意：接口为匿名调用时每日有 100 次调用次数限制（素材表述），但本教程聚焦技术接入，不讨论维护复杂度；开发者可自行查看官方文档获取最新限制。

请求参数与鉴权

Header 参数

若使用 API Key，建议从环境变量读取；若仅测试可匿名调用。

请求体（JSON 格式）

请求体支持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" }

字段说明

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

常见错误与处理

1. HTTP 4xx 错误

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 文档