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 讯飞控制台 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#

FlagShortDescriptiontextText to proofread (use - for stdin)--file``-fRead text from a file--rawOutput 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无产品权限还没开通公文校对服务哦！去 讯飞控制台 开通一下吧～107授权失败API密钥可能过期或错误，检查一下环境变量吧！108模型加载失败服务端问题，稍后再试一次吧～

3️⃣ 解析结果好迷茫？来，手把手教你～ (｡･ω･｡)

返回的 detail 数组里每个元素代表一个错误，来看看怎么读懂它：

text

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: 去讯飞官方平台就好啦～

• 📖 控制台入口
• 💰 价格详情

---

🎉 使用小贴士#

1. 批量处理：长文本可以拆分成多条请求，结果合并起来就好啦～
2. 实时反馈：可以配合编辑器插件，实现输入即校对功能哦！
3. 错误分类：利用 belongId 统计各类错误数量，方便针对性修改～

---

📚 更多资源#

• 官方文档： 讯飞公文校对
• 控制台： 讯飞开放平台
• 价格说明： 计费方式

---

祝大家校对顺利！有问题随时来问哦～ (´▽`)ﾉ 💕