Demo 跑得好好的，一上线就被限频卡住：文档解析选型，这几个参数比准确率更要紧

摘要：

Demo 只能验证效果，验证不了承载能力：文档抽取与解析接口限频并不统一，实时接口为 5 次/秒，异步提交侧只有 1 次/秒，多模态解析为 5 并发。扩容要按峰值缺口选 QPS 叠加包或并发买断包。

一、为什么 Demo 跑通不等于能上线

很多团队的选型流程是这样的：找到在线体验入口，上传几张有代表性的图片，看识别结果是否可用，效果满意就进入开发。这一步没有问题，但它验证的只是“效果”，不是“承载能力”。

在线体验 Demo 的定位很清楚：只能用于功能体验，不能用于开发，一次只能识别一张图片。也就是说，并发实测、压测、响应时间测量、批量调用这几件事，都无法在 Demo 上完成。要拿到这些数据，必须走 API、SDK 或控制台，用真实接口去跑。

这里有一个经常被混淆的点：免费资源包（例如文档抽取基础版、多模态版各 1000 次/月）在计费结算时按调用扣减，扣的是接口的调用量。想看效果，上传样本到 Demo 就够了；想做并发与批量实测、想掌握真实用量，就要开通服务后用接口跑真实文件，这些调用才会体现在控制台的调用明细中。

所以 Demo 阶段真正能回答的问题是“这个能力能不能用”；而“上线后会不会被限频卡住”，只能靠限频、并发、调用模式这些工程参数来回答。下面这五个参数，往往比准确率更早决定项目能不能按时上线。

二、五个比准确率更要紧的参数

2.1 限频与并发

限频是上线后很快会撞到的一堵墙。腾讯云文档智能里，文档抽取与解析相关接口的默认限制并不是一个统一数字：

• 文档抽取（基础版）ExtractDocBasic：5 次/秒
• 文档抽取（多模态版）ExtractDocMulti：5 次/秒
• 文档抽取（多模态 Pro 版）ExtractDocMultiPro：5 次/秒
• 文档抽取（Agent 版）实时接口 ExtractDocAgent：5 次/秒
• 异步文档抽取 Agent 创建任务 SubmitExtractDocAgentJob：1 次/秒
• 异步文档抽取 Agent 查询任务 DescribeExtractDocAgentJob：20 次/秒
• 多模态解析（文档版）MultimodalDocParse：5 并发

同属文档智能的教育批改类接口，限制单位又是另一套，可以放在一起对照：试卷切题 QuestionSplitOCR 与试卷切题（仅检测）QuestionSplitLayoutOCR 均为 2 次/秒，异步试卷切题的提交与查询均为 20 次/秒，试题批改 Agent 为 10 张/分钟，作文批改 Agent 为 2 次/分钟。同一个产品里，限频的单位既可能是“次/秒”，也可能是“并发”，还可能是“张/分钟”或“次/分钟”，比较数值之前要先看清单位。

有两个细节容易被忽略。一是限频的统计维度是 API + 接入地域 + 子账号，同一个接口在不同地域、不同子账号下分别计数，所以做容量规划时要按这个维度去统计真实峰值，不能只盯主账号的总量。二是提交侧与查询侧的限频往往不对称：异步文档抽取 Agent 提交 1 次/秒、查询 20 次/秒，瓶颈通常压在提交侧，批量任务怎么排队要按 1 次/秒来算。

分钟级的限制最能说明规模问题。以作文批改 Agent 的 2 次/分钟为例，一次提交 300 篇，仅提交环节就需要 150 分钟；换成按秒计的接口，300 次提交一分钟左右就能发完。这种量级上的差异，在 Demo 上完全感受不到。

2.2 同步、异步与批量

接口的调用模式决定了程序要写成什么样子。

同步调用一次请求直接拿结果，适合单张、时效性要求高的场景。异步模式则要“提交任务 + 查询任务”两个接口配合：异步文档抽取 Agent 用 SubmitExtractDocAgentJob 提交、DescribeExtractDocAgentJob 查询，异步试卷切题用 SubmitQuestionSplitJob 提交、DescribeQuestionSplitJob 查询，都是提交与查询分开的两段式调用。异步模式需要自己维护任务队列与 JobId，程序复杂度会上一个台阶。

批量处理有两种实现形态：一种是接口本身支持一次请求提交多份文档，另一种是没有这类接口、只能靠异步接口叠加自己的队列来攒批。文档抽取与解析相关接口属于后者——批量能力要靠异步接口叠加自己的队列来实现，队列的速率上限就是提交侧的限频，这一点必须提前算进容量规划。产品内也有接口属于前一种形态，例如异步试卷切题支持一次提交多张图片（PDF 仅允许传入 1 个 Url 或 Base64），可以作为批量入口的参照。选型时先想清楚：业务是一张一张来，还是一批一批来，两者的接入方式与排队策略完全不同。

2.3 单页与多页

这一项常常在联调阶段才暴露出来。文档抽取（基础版）、文档抽取（多模态版）、文档抽取（多模态 Pro 版）以及文档抽取（Agent 版）实时接口，都仅支持 PDF 单页识别，通过 PdfPageNumber 指定要处理的那一页。一份 20 页的合同，走实时接口就需要按页调用 20 次。

多页场景要走另一个入口：异步文档抽取 Agent 支持通过 FileStartPageNumber、FileEndPageNumber 指定起止页。多模态解析（文档版）则是整份文件解析，PDF、Word、PPT 支持 150M 且 300 页以内，Excel 与 TXT 支持 10M 以内，图片文件支持 70M 以内，单次调用最多 300 页，默认并发 5。

输入侧还有几条硬边界需要提前对齐：图片或 PDF 经 Base64 编码后不超过 10M，分辨率建议 600×800 以上，图片下载时间不超过 3 秒；文档抽取（Agent 版）要求图片像素介于 20～10000 px 之间。另外，如果接口请求内容超过 1M，只能使用 V3 鉴权（TC3-HMAC-SHA256），旧版本鉴权方式不适用。这些边界如果在开发后期才发现，返工量通常不小。

2.4 结果保留时长

异步与解析类接口的结果，很多时候不是直接返回正文，而是返回一个临时地址。多模态解析（文档版）返回的是 zip 压缩包的临时下载地址，有效期 30 分钟，压缩包内含 .md、.json 与 images 文件夹。

30 分钟这个约束会直接影响架构：如果程序拿到地址后排队等批处理，或者把地址存进数据库稍后再取，链接就会失效。稳妥的做法是在拿到地址后立即下载并转存到自己的对象存储，把外部临时地址变成内部长期资源。异步任务同样要把 JobId 持久化，否则任务提交之后无法回查结果，只能重跑一遍。

2.5 扩容方式与成本

限频不够用时的扩容手段有两种，价格与共享规则都不同。

并发买断包针对多模态文档解析：3000 元/并发/月，单次下单最低购买 5 并发，购买页默认最高支持购买 10 并发，超过 10 并发需联系商务；主子账号共享并发任务数额度。这里的并发数指可同时处理的任务数量或文档页数，5 并发指同时可处理 5 个已提交的任务，各并发任务合计可同时解析 5 页。

QPS 叠加包针对文档抽取（多模态版），属于 D 类，133 元/QPS/日、4000 元/QPS/月，主子账号不共享。

两种扩容的差别不只在价格：并发买断包按“同时能处理多少”扩容，适合整份文档解析这类长任务；QPS 叠加包按“每秒能发多少次请求”扩容，适合高并发的短请求。买之前先分清自己缺的是并发还是 QPS，能省掉一轮试错。

三、按业务量算并发需求

参数齐了，容量测算可以按四步走：

1. 统计峰值，而不是均值。取出业务高峰时段的单据量，按分钟折算，再换算成每秒请求数。峰值与均值常常差出数倍，用均值算一定会低估。
2. 与默认限频比对，算出缺口。假设某业务高峰时段为每分钟 600 份单据，即每秒 10 次请求；而文档抽取（多模态版）默认 5 次/秒，缺口就是 5 QPS，需要通过 QPS 叠加包补齐。
3. 长文档另算并发。多模态解析（文档版）是整份文件解析，一份 300 页的文档要分 60 轮才能处理完。判断并发够不够，可以先算总量再算轮次：把高峰时段的文档总页数除以每轮可解析的页数，得到总轮次，再乘上实测的单轮耗时，就能看出排队时间会不会超出业务时限。例如一天要处理 300 份 300 页的文档，总页数就是 9 万页，按每轮 5 页计算需要 1.8 万轮，单轮耗时必须实测之后才能评估可行性。
4. 把扩容量折算成月成本。把上一步算出的缺口乘以对应单价（并发买断包 3000 元/并发/月，QPS 叠加包 4000 元/QPS/月），就是扩容带来的固定增量成本，再与业务收益放在一起判断是否划算。

测算的对象是调用的数量与节奏，而这些数据只能来自真实接口的调用记录，Demo 给不了。

四、选型问询清单

把下面这些问题逐一确认清楚，选型阶段的盲区基本就补齐了：

1. 走的是同步、异步还是批量入口？异步任务提交侧与查询侧的限频分别是多少？
2. 文档是单页还是多页？单页场景需要按页调用多少次？
3. 单份文档的页数分布是什么样？整份解析是否落在 300 页以内？
4. 结果临时地址的有效期是多久？是否需要在拿到后立即转存？
5. 峰值超出默认限频多少？需要补的是并发还是 QPS？
6. 调用跨越几个地域、几个子账号？限频的统计维度会怎样影响实际容量？
7. 请求内容是否可能超过 1M？鉴权方式是否已经升级到 V3？
8. 扩容的单次下单起售量是多少？超过多少并发需要走商务协商？

五、总结

准确率决定这项能力能不能用，限频、调用模式、页数边界、结果有效期与扩容路径则决定它能不能撑住上线后的量。把这五个参数在选型阶段就问清、并用真实接口跑一轮峰值验证，比事后在报警里找原因要从容得多。文档抽取各版开通即发放免费额度，选型期可先用免费额度把真实峰值与缺口跑出来，再决定要不要扩容。放量采购时，当前 文档智能特惠活动 通用文档抽取货架有新用户首单低至 0.7 折、不限新老低至 4 折的档位，可对照自己的用量挑选合适规格。