用 Olostep 将 1 万个 URL 变成 AI 参考资料

标签页越积越多，比较却还没开始

要比较的资料都找到了，浏览器里却只开了一大堆标签页。逐页复制正文、再附上原始链接时，真正用来阅读和比较的时间反而越来越少。 看着摘要想“这句话是出自哪里？”时，还得重新翻找标签页。

原本想交给 AI 做的分析，变成了为 AI 准备阅读资料的手工工作。如果下次调研还要重复这项准备，就需要一种能从已找到的链接中一次收集正文和来源的方法。

Olostep Batches 是一项工具，可为每个 URL 命名后提交，并在处理完成后重新获取相应条目的正文。这里将从两份公开文档开始，制作可从 AI 的回答追溯至原文的参考资料。 docs.olostep +2

无需安装，先在浏览器中从两个地址开始

首次收集可以在官方 API 文档的Try it请求页面完成。不需要额外编写代码，但需要准备 Olostep 账户、在仪表板中签发的 API 令牌，以及用于请求的积分。API 请求使用Authorization: Bearer <API-TOKEN>格式进行认证。 docs.olostep

1. 注册或登录 Olostep。 接着在API Keys 页面创建令牌，并在仪表板中确认可用积分。 docs.olostep
2. 打开Create Batch 文档中的 Try it。 请按照页面提示在认证栏中输入 API 令牌。如果所在环境需要手动输入完整请求头，请在Bearer和令牌之间留一个空格。 docs.olostep +1

给两个链接起容易找到的名字

在items中创建两个条目，并分别输入custom_id和url。custom_id是用于以后识别已获取正文来自哪个地址的名称。第一次请求可以将解析器等可选项留空，先确认能够获取 Markdown 正文即可。 docs.olostep +2

请求数据如下所示。

{"items":[
  {"custom_id":"batches-guide","url":"https://docs.olostep.com/features/batches"},
  {"custom_id":"retrieve-guide","url":"https://docs.olostep.com/api-reference/retrieve"}
]}

收到的不只是受理编号，还要拿到正文才算完成

批处理按提交、确认完成、查询条目、获取正文的顺序进行。刚创建后，返回的可能是状态为in_progress的批处理信息而不是正文，因此不能只收到首次响应就结束。 docs.olostep +1

1. 在 Create Batch 中提交两个 URL。 保存响应中新返回的id。该值就是后续请求要使用的batch_id。请务必不要混淆文档中预先展示的示例值与实际响应中的值。 docs.olostep
2. 在Batch Info中确认状态。 使用已保存的batch_id查询，当status为completed时再进入下一步。处理时间可能因目标页面和账户环境而异，因此不要以固定完成时间为前提进行自动化。 docs.olostep
3. 在Batch Items中获取每份文档的编号。 已完成的条目包含custom_id、原始url以及用于获取正文的retrieve_id。失败条目也请使用status=failed单独查询。 docs.olostep
4. 在Retrieve Content中获取正文。 使用每个retrieve_id和formats=markdown进行查询。请将响应中的markdown_content与该条目的custom_id和原始 URL 一起保存。 docs.olostep

如果请求受阻，请先分类错误。401或invalid_api_key表示应检查令牌和 Bearer 格式；402或credits_exhausted表示应检查积分。如果完成列表中没有某份文档，请单独查询失败条目。若出现size_exceeded=true，则需要从提供的托管 URL 获取并保存内容，而不是从响应正文中获取。该 URL 会在 7 天后过期。 docs.olostep +3

本文基于对官方文档和公开请求页面的查阅编写，并非使用有效 API 令牌直接执行批处理创建和正文获取的结果。

read -rs OLOSTEP_API_KEY
export OLOSTEP_API_KEY

curl --fail-with-body --silent --show-error \
  https://api.olostep.com/v1/batches \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"items":[{"custom_id":"batches-guide","url":"https://docs.olostep.com/features/batches"},{"custom_id":"retrieve-guide","url":"https://docs.olostep.com/api-reference/retrieve"}]}' \
  > batch.json
batch_id=$(jq -er '.id' batch.json)

curl --fail-with-body --silent --show-error \
  "https://api.olostep.com/v1/batches/$batch_id" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  | jq -r '.status'

curl --fail-with-body --silent --show-error --get \
  "https://api.olostep.com/v1/batches/$batch_id/items" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  --data-urlencode 'status=completed' \
  --data-urlencode 'limit=50' \
  > items.json
jq '{items, cursor}' items.json

retrieve_id=$(jq -er '.items[] | select(.custom_id == "batches-guide") | .retrieve_id' items.json)
curl --fail-with-body --silent --show-error --get \
  https://api.olostep.com/v1/retrieve \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  --data-urlencode "retrieve_id=$retrieve_id" \
  --data-urlencode 'formats=markdown' \
  > content.json
jq -e '.markdown_content | length > 0' content.json

为收集的资料指定回答格式

拿到正文后，与其宽泛地问“告诉我如何使用 Olostep”，不如要求 AI 仅依据附加资料回答，并标明原始 URL。

请只阅读所附的两份文档，整理新账户的批处理上限和获取正文的步骤。请在每个回答中附上原始文档 URL，并将文档中没有的内容标记为未确认。

在官方文档中可以确认的答案是：新账户每个批处理的上限为 100 个，如需提高上限则必须联系服务提供商。如果需要结构化 JSON，提交批处理时必须指定适合目标的解析器。即使没有解析器，也可以获取 Markdown 或 HTML，但并不保证有适用于所有网站的通用解析器或输出质量。 docs.olostep +1

两个 URL 跑通后，再扩展到 1 万个

Olostep 官方规定的批处理最大数量为 1 万个 URL，但新账户的初始上限是每批 100 个。因此，在两份文档中确认正文和来源的对应关系后，再扩展至 100 个以及更大的批次会更现实。 docs.olostep

• 检查遗漏。 不要只看完成列表；还要单独查询失败列表，并将结果与提交的全部custom_id核对。 docs.olostep
• 将游标读取到最后。 如果 Batch Items 返回cursor，请在下一次请求中传入它。不要只保存第一页最多 50 个条目，就认为整个批处理已完成。 docs.olostep
• 不要相信数组顺序。 请使用custom_id而不是结果位置，将原始 URL 与获取到的正文关联起来。
• 自行保存正文。 托管 URL 会在 7 天后过期，因此应在任务完成后立即将需要重复使用的资料转存到其他存储位置。 docs.olostep

如果已经有 URL 列表，并且需要反复一次收集多个页面，批处理就很合适。如果只需要立即读取一个页面，官方文档介绍的单页抓取方式可能更简单。 docs.olostep

目标不是让 1 万次请求全部成功。而是建立能够为 AI 读过的每段正文重新打开原始地址，并能找出遗漏条目进行重新处理的参考资料。