适用场景文本相似度计算广泛用于内容审核、评论去重、AI 输出一致性校验、知识库匹配等场景。本文介绍的接口纯 PHP 本地运算无外部上游依赖平均响应低于 100 毫秒根据素材 5000×5000 字符比对约 60-80 ms适合对实时性要求较高的中小规模应用。典型用例论坛评论查重检测用户是否反复粘贴相同内容。AIGC 质量初筛比对生成文本与 prompt 的语义相似度。翻译回译验证将译文再译回原文计算相似度评估翻译是否准确。客服话术匹配用户输入与标准问句的近似程度判断。接口能力边界项目说明请求地址https://v1.apizero.cn/api/text-similarity请求方法POSTQPS 限制10 次/秒素材给出每段文本长度15000 字符中英文均按 1 字符计超长保护超过 500 字符自动截取前 500 字符计算并按比例还原得分见下方说明输出指标余弦相似度、Jaccard 系数、编辑距离归一化、LCS 比率以及加权综合评分与 5 级评级注意接口为匿名调用时每日有 100 次调用次数限制素材表述但本教程聚焦技术接入不讨论维护复杂度开发者可自行查看官方文档获取最新限制。请求参数与鉴权Header 参数参数是否必须类型说明示例Authorization否stringAPI Key 鉴权头格式Bearer sk_live_xxx匿名调用时省略Bearer sk_live_xxxxxxxxxxxxxxContent-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,differentdata.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非 0msg会给出具体原因例如文本长度超出限制。建议始终检查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 文档