比一次抓取 10,000 个 URL 更难的，是让智能体能够放心使用这 10,000 条结果。Olostep 的真正价值不在于批量请求本身，而在于将 URL 列表转变为可识别、结构化、验证和再处理的数据管道。
10,000 个 URL 不是抓取任务，而是数据契约问题
Olostep 将单 URL 抓取、网站爬取、URL 地图、大规模批次、搜索和问答作为一套 API 产品提供。其 Product Hunt 介绍也重点强调，将大规模 URL 列表作为生产数据管道处理，并将结果整理为 Markdown、HTML、JSON 等格式的用途。 如果您已有要采集的 URL 列表，/v1/batches 是合适的起点。
一个批次最多可放入 10,000 个 URL，官方文档说明无论批次大小，处理时间大约为 5–8 分钟。不过，新账户最初可能被限制为每批 100 条，因此在实际执行 10,000 条任务前，应先确认账户额度。文档还建议，少于 50 条时，并行发送单次抓取请求可能比使用批次更快。 这个时间只是产品文档中的参考值，不应将其视为反映您的目标网站和网络条件的 SLA。
不要一开始就提交 10,000 条。
更安全的做法是，先使用相同的解析器和字段契约依次跑通 20 条、100 条和 1,000 条，再逐步扩展。登录页、缺货商品、地区差异页面、JavaScript 延迟加载等在小样本中遗漏的类型，可能在批量执行时变成数百条无声错误。
首先要确定的不是 URL，而是一条结果记录的契约。例如，若用于商品监控，应先选择智能体实际会用于判断的字段，如 source_url、canonical_url、title、price、currency、availability 和 observed_at。在 JSON Schema 中，仅将字段写入 properties 并不会自动使其成为必填项，因此必须另行指定 required。如要阻止意外键，也可以明确声明 additionalProperties: false。
Olostep 批次分为提交、完成和获取三个阶段
批次请求中需要放入 items 数组，并为每个项目分配 url 和 custom_id。官方示例展示了从 URL 的 SHA-256 哈希的一部分生成 custom_id 的方法。 在实践中，应先确认是否存在必须保留大小写的路径，然后应用移除跟踪参数、移除片段、规范化主机等规则，再根据结果创建 ID。这样可以减少同一页面以不同 ID 重复存储的情况。
| 管道状态 | 必须保存的值 | 下一步判断 |
|---|---|---|
| 提交前 | custom_id、原始 URL、规范化 URL、模式版本 | 检查重复和采集许可范围 |
| 已创建批次 | batch_id、提交时间、目标数量 | 接收 Webhook 或查询状态 |
| 项目完成 | custom_id、retrieve_id、处理状态 | 获取内容 |
| 验证完成 | 验证结果、错误代码、原始内容保存位置 | 加载或移至再处理队列 |
如果目标是结构化 JSON，创建批次时必须传入适合目标网站的解析器 ID。相反，如果计划稍后用独立逻辑对原文进行结构化，则可以获取 Markdown 或 HTML。可将职责拆分为：解析器将页面结构转换为字段，您的 JSON Schema 验证器检查结果是否遵守内部契约。关键在于，不要将解析成功和通过数据质量检查视为同一种状态。
批次结束后，可通过 GET /v1/batches/{batch_id}/items 获取项目列表。列表 API 支持 completed 和 failed 状态筛选；当结果较多时，将上一个响应的 cursor 传给下一个请求以遍历分页。文档建议每次查询 10–50 条。 为避免只收到前 50 条就将 10,000 条标记为完成，必须持续循环直到不再有游标。
将每个已完成项目的 retrieve_id 传给 /v1/retrieve，即可仅获取所需格式。响应中的 json_content 是字符串，因此还需要再次进行 JSON 解析和模式验证。 官方批次示例说明，托管内容的保留期为 7 天，因此不要只保存链接；任务完成后应立即将需要的原文和结构化结果迁移到自己的存储中，这样更安全。
智能体之前还需要一道验证和再处理闸门
只将成功记录放入智能体读取的数据集，并将采集失败和质量失败分到不同队列。HTTP 错误或超时属于采集失败；价格是字符串却没有货币，或标题为空，则属于质量失败。前者可以使用指数退避重新请求，但后者若不先修复解析器或模式，即使重试也很可能重复相同结果。
| 状态 | 示例 | 处理方式 |
|---|---|---|
| 传输失败 | 连接错误、临时服务器错误 | 设置次数上限的退避重试 |
| 采集失败 | 拦截页面、已删除 URL | 仅将 failed 项目组成单独批次 |
| 解析失败 | JSON 语法错误、字段类型不匹配 | 保留原文后修复解析器 |
| 语义质量失败 | 价格为 0、标题为空、观测值过期 | 通过业务规则验证或人工审核 |
完成检测可以从轮询改为 Webhook。Olostep 会发送 batch.completed 事件，并会在约 30 分钟内对失败投递最多重试 5 次。由于每次重试都会保留相同的事件 ID，接收端必须用该 ID 防止重复处理。 收到 Webhook 后不要立刻执行耗时验证；应快速返回 2xx，再通过内部队列处理。
还有一项安全注意事项。当前 Webhook 文档将加密签名验证标记为“Coming Soon”。 因此，与其只相信 Webhook 正文来确认数据加载，不如将其视为一个触发器：使用通知中的 batch_id 通过已认证 API 再次查询状态和项目。
能够采集并不意味着可以采集。请检查目标网站的使用条款和访问权限，也要检查为自动客户端提供路径访问规则的 /robots.txt。RFC 9309 将 robots.txt 定义为爬虫应遵循的访问规则，而非访问授权或安全机制。 对于个人信息、登录后内容和受版权保护的材料，还需要单独进行法律审查。
实际构建 10,000 URL 管道的顺序
1. 用 20 个黄金样本建立结果契约
除正常页面外，还应混入缺货、已删除、字段为空、地区限制和动态加载页面。确定字段类型、是否必填、可接受的空值和 schema_version，并创建 JSON Schema 验证测试。
2. 创建 URL 清单和固定 ID
在 CSV 或表中保存 custom_id、原始 URL、规范化 URL、目标域名和采集目的。移除重复 URL，并只将已确认 robots.txt、条款和访问权限的记录标记为可提交。
3. 从 100 条开始逐步扩大批次
向 POST /v1/batches 传入 items、解析器 ID，以及必要时的 webhook。确认新账户限制，在 100 条时测量成功率、必填字段满足率和重复率，然后扩大到 1,000 条和 10,000 条。
4. 遍历到最后一个游标并验证结果
查询 /items 直到游标消失，并用每个 retrieve_id 获取结果。只有通过 JSON 解析、模式验证和业务规则验证的记录，才发送到面向智能体的索引或数据库。
5. 按失败原因运营再处理队列
对传输错误进行有限次数重试，搁置被拦截或已删除的 URL，并将字段错误连同原文发送到解析器修复队列。仪表盘应优先展示有效记录比例、必填字段满足率、重复率和再处理后的恢复率，而不是总数量。
如果想进一步深入
Batch Endpoint - Olostep Docs — 可查看批次大小、新账户限制、解析器和 Webhook 用法的核心文档。 docs.olostep.com
Get the content of multiple websites in one go - Olostep Docs — 通过 Python 示例讲解从创建批次、确认状态到查询项目和获取内容的过程。 docs.olostep.com
Batch Items - Olostep Docs — 可查看 completed/failed 筛选和基于游标分页的准确请求字段。 docs.olostep.com
JSON Schema - object — 说明如何利用 required 和 additionalProperties 为结构化结果建立字段契约。 json-schema.org
RFC 9309: Robots Exclusion Protocol — 介绍自动采集前应确认的 robots.txt 标准行为及其限制。 rfc-editor.org
