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:

   export IFLY_APP_ID="your_app_id"
   export IFLY_API_KEY="your_api_key"
   export IFLY_API_SECRET="your_api_secret"
   

Usage

Basic proofreading

python3 scripts/text_proofread.py "第二个百年目标"

Read from stdin

echo "我们要加强对蓝球运动的推广" | python3 scripts/text_proofread.py -

Read from file

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

# 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 数组里每个元素代表一个错误，来看看怎么读懂它：

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 统计各类错误数量，方便针对性修改～

---

📚 更多资源

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

---

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