从 curl 到工程封装：文本相似度 API 集成指南

适用场景与背景文本相似度比对是 NLP 中的基础能力广泛应用于以下场景评论/内容审核检测用户提交的评论是否与已有重复或高度近似AI 生成内容检测将 AI 生成文本与原文比对辅助判断抄袭或生成痕迹多语言翻译质量评估翻译后的文本与参考译文计算相似度量化一致性客服话术匹配用户提问与标准答案库中的句子做相似度排序自动返回最佳答案该接口采用纯本地计算的方式无外部上游依赖平均响应 100ms适合对延迟敏感的内部服务、批处理脚本或边缘节点。接口能力边界维度说明请求方法POST端点https://v1.apizero.cn/api/text-similarity单次 QPS10 次/秒文本长度每段 1~5000 字符中英文均按 1 字符计超长保护超过 500 字符自动截取并按比例还原5000×5000 字符比对约 60-80ms鉴权方式可选匿名每日 100 次或 API Key通过X-API-Key或Authorization头具体以文档为准输出指标余弦相似度权重 35%、Jaccard 系数25%、编辑距离归一化20%、LCS 比率20%综合评级5 级几乎相同、高度相似、中度相似、轻度相似、差异较大注意接口底层修复了 PHP 内置levenshtein函数的字节计算 bug自实现mb_levenshtein支持字符级编辑距离避免汉字截断问题。请求参数与鉴权Header 参数参数是否必填类型说明示例Authorization否stringAPI Key 鉴权格式Bearer sk_live_xxxBearer sk_live_xxxxxxxxxxxxxxContent-Type否string支持application/json或application/x-www-form-urlencodedapplication/json鉴权说明匿名调用时可省略 Authorization 头每日额度 100 次建议正式环境使用 API Key 以获取更高配额和稳定性。两种鉴头均可使用具体以API 文档为准。请求体JSON字段类型必填描述示例text1string是第一段文本1~5000 字符今天天气不错适合出门散步text2string是第二段文本1~5000 字符今天天气真好适合出门走走从 curl 开始调试与验证拿到接口后的第一步通常是用 curl 手动发送请求确认网络连通和返回结构。以下示例使用环境变量APIZERO_API_KEY存储密钥匿名时直接去掉对应头即可export APIZERO_API_KEYsk_live_your_key_here curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { text1: 今天天气不错适合出门散步, text2: 今天天气真好适合出门走走 } \ https://v1.apizero.cn/api/text-similarity响应示例成功{ code: 0, msg: 成功, request_id: abc123def456, data: { text1_length: 13, text2_length: 13, truncated: false, metrics: { cosine: 0.5833, jaccard: 0.4118, edit_distance: 4, edit_similarity: 0.6923, lcs_length: 12, lcs_similarity: 0.9231 }, overall_score: 0.6471, similarity_level: moderately_similar, level_name: 中度相似 } }通过 curl 我们可以快速确认接口可通、返回格式符合预期。接下来就需要将这段原始交互封装成工程化代码。工程封装Python 与 PHP 示例Pythonrequests 库import requests import json API_URL https://v1.apizero.cn/api/text-similarity API_KEY sk_live_your_key_here # 匿名调用时设为 None def text_similarity(text1: str, text2: str) - dict: headers { Content-Type: application/json } if API_KEY: headers[X-API-Key] API_KEY payload { text1: text1, text2: text2 } resp requests.post(API_URL, headersheaders, jsonpayload, timeout5) resp.raise_for_status() return resp.json() # 调用示例 result text_similarity(今天天气不错适合出门散步, 今天天气真好适合出门走走) print(json.dumps(result, ensure_asciiFalse, indent2))PHPcURL 扩展接口后台即为 PHP 实现用 PHP 调用更为自然?php function textSimilarity(string $text1, string $text2, ?string $apiKey null): array { $url https://v1.apizero.cn/api/text-similarity; $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_RETURNTRANSFER true, CURLOPT_HTTPHEADER [ Content-Type: application/json, $apiKey ? X-API-Key: . $apiKey : , ], CURLOPT_TIMEOUT 5, ]); $response curl_exec($ch); if (curl_errno($ch)) { throw new RuntimeException(cURL Error: . curl_error($ch)); } curl_close($ch); return json_decode($response, true); } $result textSimilarity(今天天气不错适合出门散步, 今天天气真好适合出门走走); print_r($result);返回值详解成功响应顶层包含code、msg、request_id和data。重点看data对象字段类型说明text1_lengthint第一段文本实际字符长度截取前text2_lengthint第二段文本实际字符长度截取前truncatedbool是否进行了截取仅当某段 500 字符才为truemetrics.cosinefloat余弦相似度取值范围 [0,1]1 表示完全相同metrics.jaccardfloatJaccard 系数基于字符集合交并比范围 [0,1]metrics.edit_distanceint字符级编辑距离莱文斯坦距离metrics.edit_similarityfloat编辑距离归一化后的相似度 1 - (edit_distance / max(len))metrics.lcs_lengthint最长公共子序列LCS的长度metrics.lcs_similarityfloatLCS 长度与较长文本长度的比值overall_scorefloat加权综合评分 0.35cosine 0.25jaccard 0.20edit_similarity 0.20lcs_similaritysimilarity_levelstring英文级别标识nearly_identical,highly_similar,moderately_similar,slightly_similar,differentlevel_namestring中文级别名称评级阈值参考以文档为准级别综合评分范围近似含义几乎相同≥0.95文本高度一致仅有微小差异高度相似[0.80,0.95)核心内容相似可能词汇或语序不同中度相似[0.55,0.80)主题相关但存在一定差异轻度相似[0.30,0.55)仅少部分相同或语义接近差异较大0.30文本几乎无关联错误处理与常见问题错误响应示例{ code: 1001, msg: 参数错误text1 不能为空, request_id: err_req_001, data: null }code含义排查方向0成功-1001参数缺失或格式错误检查text1、text2是否必填确认 JSON 合法性1002文本长度超限保证每段 ≤5000 字符含空格和标点2001鉴权失败检查 API Key 是否正确是否过期匿名调用是否超过每日 100 次5000服务端内部错误联系接口提供方并附带request_id常见问题中文乱码请确保发送请求时使用 UTF-8 编码。Python 的requests库默认使用 UTF-8PHP 用JSON_UNESCAPED_UNICODE选项保证中文不被转义。超长文本当文本超过 500 字符时接口会自动截取前 500 字符并记录truncated: true评分基于截取后的文本计算。如果业务需要精确结果建议客户端先截取后再请求。匿名调用限制每日 100 次超出后返回 2001 错误。生产环境应配置 API Key。工程化注意事项1. 重试与退避网络波动可能造成偶发失败建议在封装层加入指数退避重试逻辑最多 3 次间隔 1s、2s、4s。注意不要重试 4xx 错误如参数问题只重试 5xx 或超时。2. 结果缓存如果对同一对(text1, text2)频繁请求可在应用层使用 LRU 缓存如 Python 的functools.lru_cache缓存结果避免重复网络开销。TTL 可根据业务容忍的数据新鲜度设置。3. 超时设置接口平均耗时 100ms但极端情况下如文本长度 5000 字符可能达到 80ms建议请求超时设为 2~5 秒避免因接口挂起阻塞整个服务。4. 文本预处理去噪去除首尾空格、HTML 标签、多余换行符等减少无关字符对相似度的影响。标准化全角/半角转换统一大小写英文场景。分段如果文本超过 5000 字符需在客户端分段后分别对比或取前 5000 字符。5. 性能考量接口 QPS 为 10 次/s如果需要批量对比大量文本对应当控制并发量如使用信号量限制最大 10 个并发请求或实现批量处理队列避免触发限流。参考文档官方接口文档https://apizero.cn/aidocs/text-similarity原始 Markdown 文档https://apizero.cn/aidocs/text-similarity/raw.md本文所有字段解释和示例均以文档为准调用前请查阅最新文档以获取准确信息。