Webから10件だけ情報を集めるなら、途中で止まっても最初からやり直せます。

でも、対象が1000件、3000件、数万件へ増えた瞬間、問題は「どう取得するか」だけではなくなります。

どこまで確定したか分からない
最後に表示されたPage番号と、実際の保存済み成果がズレる
Retryすると同じ対象を二重取得する
0 byteや書込み途中Fileを「完了」と誤認する
APIのNext Tokenを失って最初から戻る
Manifestが壊れたら、取得済みShardまで信用できなくなる
再開までの間に対象側が変わり、同じCursorでも別の集合を読む
AIエージェントが「続きから」と言いながら、既処理範囲を再読する

ここで必要なのは高速化ではありません。

「現在地」「確定成果」「次の再開位置」を別々に持つこと。

本教材では、長時間のWeb収集を、

Task
↓
Fetch
↓
Validate
↓
Temporary Save
↓
Readback
↓
Commit
↓
Advance Cursor

という順序へ分解します。

そして、

予定Task
-
確定済みTask
=
残件

を作れる状態へ持っていきます。

目標は「絶対に止まらないCrawler」ではありません。

止まっても、確定した仕事を残し、壊れたManifestや中断したRuntimeから続きを組み立て直せる収集です。

30秒診断――いま電源を切っても「続き」が分かりますか？

現在の収集処理について、次へ答えてみてください。

1. 次に処理すべきTaskは何か
2. 何を「完了」とみなすか
3. 保存済みFileが本当に完成していると確認できるか
4. 同じTaskを再実行しても成果が増殖しないか
5. 進捗Fileが消えても、成果物から完了範囲を戻せるか
6. 再開までに対象側が変わった可能性を検知できるか

last_page = 37 だけでは弱いです。

37ページ目を保存し終えたのか、処理中に落ちたのかで再開位置が違うからです。

この教材で持ち帰るもの

Task ID
Cursor / Offset / Next Token
Checkpoint
Shard
.part とAtomic Commit
Committed Task Set
Manifestの役割
Manifest破損時の再構築案
Retryable / Blocked分離
Idempotent Retry
Drift / Observation Time
Identity Key / Content Hash
Run ID
Committed Ratio
Task-linked Log
Dataset Card / Run Card
Failure Injection
Fetch / Validate / Commit分離
Agentへ渡す再開規則
3000件収集の復旧例
開始・Commit・再開・引継ぎChecklist

1. 「途中停止」は失敗ではない

長時間収集は普通に止まります。

通信切断。
PC終了。
Notebook Runtime消失。
API一時障害。
Rate limit。
手動停止。
対象側の形式変更。

ここで、

止まらない仕組みを作ろう

だけに寄せると、不自然になります。

長時間処理で重要なのは、

止まることを前提に、どこまで確定したかを残すこと。

です。

5000件を最後に一つの巨大Fileへ保存する設計なら、4999件目で落ちたときの損失が大きい。

小さな単位で確定成果を残せば、再実行範囲を狭くできます。

ただし、「100件ごと」などの件数自体が正解ではありません。

大事なのは、

処理中と確定済みを区別できる保存単位があることです。

2. CursorとCheckpointを同じものにしない

Cursor

次にどこから読むか。

page = 37
offset = 1800
next_token = "..."
last_seen_id = "post_1842"

Checkpoint

ここまでの成果は確定済み、と判断できる保存点。

Cursor
= 次に読む位置

Checkpoint
= ここまで確定したという境界

Cursorだけ保存しても、成果物が保存されていなければ戻れません。

成果物だけあっても、次の位置が分からなければ再開が重くなります。

両方を分けて持ちます。

3. Taskを先に定義する

再開可能な収集では、「1回の処理」を名前にします。

例：

source = example_api
query = "生成AI"
period = 2026-08
page = 37

一URL一Taskでも構いません。

重要なのは、

あとから同じTaskを再生成・識別できること。

です。

決定論的Task ID

example_api__生成AI__2026-08__page-0037

でもよいし、

hash(source + query + period + cursor_identity)

でも構いません。

必要条件は、

同じTask → 同じID
別Task → 区別可能

です。

実行順序番号だけでは、RetryやShard変更で意味がズレます。

4. 「処理中」と「確定済み」をFileで分ける

保存途中で停止する可能性があります。

そこで直接完成Fileへ書かず、

shard_0037.json.part

へ書きます。

書込み後に、

読み直せる
期待Format
Task ID一致
必須項目あり
正常0件と取得失敗を区別

を確認します。

通ったら、

shard_0037.json

へ確定します。

.part は存在していても未完了。

0 byte、Parse不能、Task不明、必須Metadata欠損も完了へ入れません。

File Exists ≠ Committed

です。