企业官网建设流程全解析

接口定位与适用场景

文本相似度接口用于接收两段中文或英文文本，返回一组可量化的相似度指标。它不依赖外部服务，请求到达后由服务端本地完成计算。适合在内容审核、评论去重、翻译一致性检查、客服话术匹配等场景中作为辅助判断工具。

接口的定位是“输入两段文本，输出多个维度的相似度分数”，而不是一个简单的“是否相似”布尔值。因此调用方需要根据自身业务设定阈值，例如将综合评分高于 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 参数

匿名调用有限额，如果已经申请到 API Key，建议在请求头中显式携带。注意素材给出的 curl 示例使用了X-API-Key，而 Header 参数表中列出的是Authorization，两种方式在部分网关中都可能被接受，但文档页中明确给出的鉴权头以Authorization为准，实际使用时建议先查看最新文档确认。

请求体字段

请求体为一个对象，包含两个必填字段：

示例请求体：

{ "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 对象

metrics 子字段

这里需要特别说明的是edit_distance是一个绝对值，它的大小与文本长度相关，不能直接用于横向比较。edit_similarity和lcs_similarity才是 0 到 1 之间的归一化指标。

评级与综合评分的映射关系

接口将结果分为五级，英文标识与中文名称对应如下：

具体阈值没有在素材中列出，需要以文档页为准。建议开发者在后端维护一张阈值表，而不是硬编码在客户端。

常见错误与处理思路

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，作为缓存 key，TTL 设置为 24 小时，能够显著减少 API 调用量，同时降低响应延迟。

5. 记录 request_id

每次调用的request_id应写入日志。遇到结果异常或超时，可以通过 request_id 向接口提供方反馈，加快问题定位。

完整调用流程小结

一次完整的接入流程可以概括为：

1. 确认文本长度在 1-5000 字符之间，编码为 UTF-8。
2. 构造 JSON 请求体，包含 text1、text2。
3. 设置 Content-Type 为 application/json，按需携带 Authorization 头。
4. 发起 POST 请求到接口地址。
5. 解析响应 JSON，读取data.overall_score和data.metrics。
6. 判断data.truncated，确认是否有截断。
7. 根据业务阈值映射评级，记录 request_id。

参考文档

• 接口文档页：https://apizero.cn/aidocs/text-similarity
• 原始文档：https://apizero.cn/aidocs/text-similarity/raw.md