ifly-text-proofread

# ifly-text-proofread Proofread Chinese text using iFlytek's Official Document Proofreading API (公文校对). Detects 27 types of errors across three categories: **文字标点差错**: 错别字、多字、少字、语义重复、语序错误、句式杂糅、标点符号、量词单位、数字差错、句子查重、序号检查 **知识性差错**: 地理名词、机构名称、专有名词及术语、常识差错、媒体报道禁用词和慎用词 **内容导向风险**: 涉低俗辱骂、其他敏感内容 ## Setup 1. Create an app at [讯飞控制台](https://console.xfyun.cn) with 公文校对 service enabled 2. Set environment variables: ```bash export IFLY_APP_ID="your_app_id" export IFLY_API_KEY="your_api_key" export IFLY_API_SECRET="your_api_secret" ``` ## Usage ### Basic proofreading ```bash python3 scripts/text_proofread.py "第二个百年目标" ``` ### Read from stdin ```bash echo "我们要加强对蓝球运动的推广" | python3 scripts/text_proofread.py - ``` ### Read from file ```bash python3 scripts/text_proofread.py --file document.txt ``` ### Options | Flag | Short | Description | |------|-------|-------------| | `text` | | Text to proofread (use `-` for stdin) | | `--file` | `-f` | Read text from a file | | `--raw` | | Output decoded JSON response | ### Examples ```bash # Proofread a sentence python3 scripts/text_proofread.py "我国加强蓝球运动的推广力度" # Proofread a long document from file python3 scripts/text_proofread.py -f report.txt # Pipe from clipboard or other tools pbpaste | python3 scripts/text_proofread.py - # Raw JSON for debugging python3 scripts/text_proofread.py --raw "测试文本" ``` ## Output - **✅ 无错误** — text passed proofreading with no issues - **🔍 发现 N 处问题** — lists each error with: - Error word + category - Explanation - Context in the original text - Position and length - Suggested action (标记/替换/删除) - Correction suggestions ## Notes - **Max text length**: 220,000 characters per request (auto-truncated with warning) - **Auth**: HMAC-SHA256 signed URL (host + date + request-line → signature → authorization) - **Endpoint**: `POST https://cn-huadong-1.xf-yun.com/v1/private/s37b42a45` - **Env vars**: `IFLY_APP_ID`, `IFLY_API_KEY`, `IFLY_API_SECRET` - **No pip deps**: Uses only Python stdlib (`urllib`, `hmac`, `hashlib`, `json`, etc.) - **Text is base64-encoded** in the request body; response text field is also base64-encoded --- ## 常见问题 ### ❓ 错误能力ID对照表 在使用API时，返回的 `belongId` 字段对应以下错误类型： | belongId | 说明 | 常见场景 | |----------|------|----------| | 9 | 错别字、词 | 「蓝球」→「篮球」、「的」「地」「得」混淆 | | 31 | 多字错误 | 「大大大大力」→ 删除多余字 | | 32 | 少字错误 | 「中国成立」→ 「中华人民共和国成立」 | | 35 | 语义重复 | 「大力大力发展」→ 语义重复 | | 34 | 语序错误 | 「很好很强大」→ 「很强大很好」 | | 39 | 量和单位差错 | 「3斤米」→ 「3公斤米」 | | 36 | 数字差错 | 「第十几个」→ 数据不一致 | | 20 | 句式杂糅 | 「原因是由于...」→ 句式杂糅 | | 21 | 标点符号差错 | 顿号逗号混用、书名号错误 | | 24 | 句子查重 | 文档内部重复句子 | | 119 | 重要讲话引用 | 领导人讲话用词规范 | | 123 | 地理名词 | 省市区名称、行政区划 | | 19 | 机构名称 | 党政机关、企事业单位名称 | | 124 | 专有名词及术语 | 专业术语、科技术语 | | 122 | 媒体报道禁用词 | 敏感词、违规词检测 | | 6 | 常识差错 | 明显与事实不符的内容 | | 111 | 涉低俗辱骂 | 低俗内容、辱骂词汇 | | 118 | 其他敏感内容 | 各类敏感信息检测 | --- ### 🔧 出现错误怎么办？— 用户视角引导 #### 1️⃣ 收到错误响应不要慌～ (´▽`) - **首先检查**：环境变量 `IFLY_APP_ID`、`IFLY_API_KEY`、`IFLY_API_SECRET` 是否都设置好了呢？ฅ•̀∀•́ฅ - **然后看这里**： - 返回的 `code` 字段：`0` = 成功，其他 = 失败 (详见下文错误码表) - 响应里的 `data` 字段包含检测结果，`message` 字段有详细说明哦～ #### 2️⃣ 常见错误码一览 ✧(•̀ω•́)✧ | code | 说明 | 解决方法 | |------|------|----------| | 0 | 成功 | 完美！继续使用吧～ ✨ | | 101 | 参数缺失 | 快检查一下 `text` 参数有没有传呀？ | | 102 | 参数无效 | 文本内容有问题，看看是不是太长了（≤220000字符）？ | | 103 | 请求超长 | 文本太长了啦！分段处理试试吧～ | | 104 | 超过并发 | 访问太频繁啦，休息一下再试试呗～ ⏳ | | 105 | 无配额 | 配额用完了...去讯飞控制台看看还能不能用吧 (｡•́︿•̀｡) | | 106 | 无产品权限 | 还没开通公文校对服务哦！去 [讯飞控制台](https://console.xfyun.cn/services/s37b42a45) 开通一下吧～ | | 107 | 授权失败 | API密钥可能过期或错误，检查一下环境变量吧！ | | 108 | 模型加载失败 | 服务端问题，稍后再试一次吧～ | #### 3️⃣ 解析结果好迷茫？来，手把手教你～ (｡･ω･｡) 返回的 `detail` 数组里每个元素代表一个错误，来看看怎么读懂它： ``` detail[i].word → 错误的内容是什么 detail[i].type → 错误类型ID（对应上面的对照表哦） detail[i].position → 错误开始位置（从0开始计数） detail[i].length → 错误内容的长度 detail[i].suggestion → 纠错建议 detail[i].ruleName → 具体触发的规则名称 ``` 📍 **小技巧**：想知道错误在哪里结束吗？`position + length` 就是结束位置啦！这样就可以精准定位错误咯～ --- ### 💡 常见问题解答 #### Q1: 公文校对与文本纠错、文本合规有哪些区别？ **A**: 文本纠错主要偏向通用领域（如写作、出版）文本进行纠错，公文校对在公文写作使用等领域效果更佳，同时也适合通用领域～ 文本合规对各类场景风险拦截更全面哦！(`･ω･´)ゞ #### Q2: 公文校对的position仅标记开始位置，结束位置怎么计算呢？ **A**: 超简单的啦！讯飞已经给了 `position` 和 `length`，用 `position + length` 就是对应错误词在文本中的结束位置咯～ ✧٩(ˊᗜˋ*)و✧ #### Q3: 公文校对的文本有什么要求吗？ **A**: 有的呢～ 原请求的校对文本： - ✨ 不能为空 - ✨ 不能超过 **220,000个字符** - ✨ 汉字、英文字符、数字、标点都算做一个字符哦！ > 💡 **小提示**：如果文本太长，建议拆分成多条请求处理，这样效果会更好呀～ #### Q4: 为什么返回的结果是空的呀？(｡•́︿•̀｡) **A**: 可能的原因： - 1. 文本太短，没有检测到错误（这是好事！说明文本很棒棒～） - 2. API调用失败了，检查一下 `code` 是不是 0 呢 - 3. 网络波动导致的，再试一次看看吧！ #### Q5: 如何开通或购买服务？ **A**: 去讯飞官方平台就好啦～ - 📖 [控制台入口](https://console.xfyun.cn/services/s37b42a45) - 💰 [价格详情](https://www.xfyun.cn/services/textCorrectionOfficial?target=price) --- ### 🎉 使用小贴士 1. **批量处理**：长文本可以拆分成多条请求，结果合并起来就好啦～ 2. **实时反馈**：可以配合编辑器插件，实现输入即校对功能哦！ 3. **错误分类**：利用 `belongId` 统计各类错误数量，方便针对性修改～ --- ### 📚 更多资源 - 官方文档：[讯飞公文校对](https://www.xfyun.cn/services/textCorrectionOfficial) - 控制台：[讯飞开放平台](https://console.xfyun.cn) - 价格说明：[计费方式](https://www.xfyun.cn/services/textCorrectionOfficial?target=price) --- 祝大家校对顺利！有问题随时来问哦～ (´▽`)ﾉ 💕