接口定位与适用场景文本相似度接口用于接收两段中文或英文文本返回一组可量化的相似度指标。它不依赖外部服务请求到达后由服务端本地完成计算。适合在内容审核、评论去重、翻译一致性检查、客服话术匹配等场景中作为辅助判断工具。接口的定位是“输入两段文本输出多个维度的相似度分数”而不是一个简单的“是否相似”布尔值。因此调用方需要根据自身业务设定阈值例如将综合评分高于 0.8 的结果视为高度相似低于 0.3 视为差异较大。接口能力边界在使用之前需要明确该接口的几个硬性约束单次请求携带 text1、text2 两段文本每段长度限制在 1 到 5000 字符之间中英文均按单个字符计数。接口的 QPS 限制为 10 次/秒超过后可能返回限流错误调用方应做好退避重试。内部实现中超过 500 字符的文本会被自动截取并按比例还原最终得分响应中的truncated字段会标记是否发生了截取。相似度指标包括余弦相似度、Jaccard 系数、编辑距离归一化值和 LCS 比率综合分按 35%、25%、20%、20% 加权得到。这些边界决定了接口适合处理中等长度的文本比对不适合对整篇长文档做全文相似度计算。如果需要比较长文本建议先分段再逐段调用。请求参数与鉴权方式接口地址为https://v1.apizero.cn/api/text-similarity请求方法为POST。Header 参数参数是否必填类型说明Authorization否stringAPI Key 鉴权头格式为Bearer sk_live_xxx匿名调用时可省略Content-Type否string支持application/x-www-form-urlencoded或application/json匿名调用有限额如果已经申请到 API Key建议在请求头中显式携带。注意素材给出的 curl 示例使用了X-API-Key而 Header 参数表中列出的是Authorization两种方式在部分网关中都可能被接受但文档页中明确给出的鉴权头以Authorization为准实际使用时建议先查看最新文档确认。请求体字段请求体为一个对象包含两个必填字段字段类型必填说明text1string是第一段文本1-5000 字符text2string是第二段文本1-5000 字符示例请求体{ text1: 今天天气不错适合出门散步, text2: 今天天气真好适合出门走走 }使用 curl 调用接口下面是一个可直接复制的 curl 示例使用 API Key 鉴权curl -sS \ -X POST \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ -H Content-Type: application/json \ -d {text1: 今天天气不错适合出门散步, text2: 今天天气真好适合出门走走} \ https://v1.apizero.cn/api/text-similarity如果没有 API Key也可以移除 Authorization 头进行匿名调用但需要注意匿名额度限制。在 Windows 环境下如果使用 cmd 而不是 PowerShell建议将请求体写入临时文件避免引号转义问题curl -sS -X POST -H Content-Type: application/json -d body.json https://v1.apizero.cn/api/text-similarity其中body.json内容即为包含 text1、text2 的 JSON 对象。响应字段解读正常响应时 HTTP 状态码为 200响应体是一个 JSON 对象结构如下{ code: 0, msg: 成功, request_id: abc123def456, 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 } }顶层字段code业务状态码0 表示成功非 0 表示失败。msg状态描述成功时为“成功”。request_id本次请求的唯一标识排查问题时可以提供给服务端。data 对象字段类型含义level_namestring中文评级例如“中度相似”similarity_levelstring英文评级标识例如moderately_similaroverall_scorenumber加权综合评分范围 0 到 1metricsobject各维度相似度指标详见下表text1_lengthnumbertext1 实际参与计算的字符数text2_lengthnumbertext2 实际参与计算的字符数truncatedboolean是否发生截断true 表示输入超过 500 字符被截取metrics 子字段字段类型说明cosinenumber余弦相似度基于分词或字符向量计算jaccardnumberJaccard 系数交集字符数 / 并集字符数edit_distancenumber字符级编辑距离原始值edit_similaritynumber编辑距离归一化后的相似度lcs_lengthnumber最长公共子序列长度lcs_similaritynumberLCS 长度归一化后的比率这里需要特别说明的是edit_distance是一个绝对值它的大小与文本长度相关不能直接用于横向比较。edit_similarity和lcs_similarity才是 0 到 1 之间的归一化指标。评级与综合评分的映射关系接口将结果分为五级英文标识与中文名称对应如下英文标识中文名称可能的取值范围以文档为准almost_same几乎相同综合分接近 1highly_similar高度相似综合分较高moderately_similar中度相似综合分中等slightly_similar轻度相似综合分较低different差异较大综合分很低具体阈值没有在素材中列出需要以文档页为准。建议开发者在后端维护一张阈值表而不是硬编码在客户端。常见错误与处理思路1. code 非 0 的返回当请求参数缺失或格式错误时接口会返回非 0 的code。此时应优先检查text1、text2 是否为空字符串或 null字段名拼写是否正确不要写成text_1请求体是否为合法 JSON且 Content-Type 头与实际内容一致。2. 文本长度超限如果 text1 或 text2 超过 5000 字符接口可能直接拒绝请求也可能返回参数错误。建议在客户端先做长度校验超出后截断或分片。3. 匿名调用被限流匿名调用有每日额度超出后可能返回 429 或自定义限流错误。可以通过响应码识别并在代码中实现重试机制例如指数退避。4. 编码问题在发送包含中文的请求时务必确保终端或代码环境使用 UTF-8 编码。如果使用application/x-www-form-urlencoded需要将中文进行 URL 编码。PHP 代码接入示例由于接口内部使用 PHP 实现这里给出一段 PHP 调用代码便于服务端开发者直接参考?php function textSimilarity(string $text1, string $text2, string $apiKey ): array { $url https://v1.apizero.cn/api/text-similarity; $headers [ Content-Type: application/json, ]; if ($apiKey ! ) { $headers[] Authorization: Bearer . $apiKey; } $payload json_encode([ text1 $text1, text2 $text2, ], JSON_UNESCAPED_UNICODE); $ch curl_init($url); curl_setopt_array($ch, [ CURLOPT_POST true, CURLOPT_POSTFIELDS $payload, CURLOPT_HTTPHEADER $headers, CURLOPT_RETURNTRANSFER true, CURLOPT_TIMEOUT 5, ]); $response curl_exec($ch); $errno curl_errno($ch); $error curl_error($ch); curl_close($ch); if ($errno) { return [error curl error: $error]; } return json_decode($response, true) ?? [error invalid json response]; } $result textSimilarity( 今天天气不错适合出门散步, 今天天气真好适合出门走走, sk_live_xxxxxxxxxxxxxx ); print_r($result);这段代码做了基础的超时设置和错误捕获但没有处理限流退避。正式环境里建议配合队列或信号量控制请求频率。工程化注意事项1. 处理截断标记当truncated为 true 时表示实际参与计算的文本并不是完整内容得到的分数只能代表截断后文本的相似度。在需要严格比对全文的场景下应提前将文本按 500 字符切分再对分段结果做聚合而不是直接信任单个结果。2. 自定义阈值策略不要把level_name直接展示给用户。不同业务对相似度的容忍度不同例如评论去重可能要求综合分大于 0.9 才算重复而客服话术匹配可能 0.6 就够。建议在服务端将overall_score映射为业务自己的等级。3. 请求频率控制接口 QPS 上限为 10即每 100 毫秒最多发送一个请求。如果业务需要批量比对必须引入限流组件例如在 PHP 端使用usleep(100000)控制单请求间隔或使用 Redis 计数器做全局限流。4. 缓存计算结果对于相同文本对的重复查询可以使用哈希缓存将text1 \n text2做 md5作为缓存 keyTTL 设置为 24 小时能够显著减少 API 调用量同时降低响应延迟。5. 记录 request_id每次调用的request_id应写入日志。遇到结果异常或超时可以通过 request_id 向接口提供方反馈加快问题定位。完整调用流程小结一次完整的接入流程可以概括为确认文本长度在 1-5000 字符之间编码为 UTF-8。构造 JSON 请求体包含 text1、text2。设置 Content-Type 为 application/json按需携带 Authorization 头。发起 POST 请求到接口地址。解析响应 JSON读取data.overall_score和data.metrics。判断data.truncated确认是否有截断。根据业务阈值映射评级记录 request_id。参考文档接口文档页https://apizero.cn/aidocs/text-similarity原始文档https://apizero.cn/aidocs/text-similarity/raw.md