長時間バッチ処理の作法

大量データのベクトル化など、途中で落ちうる長い処理を堅牢に回すための型（gemini-rag の ingest で確立）。

• 途中再開：処理済みインデックスを progress.json に逐次記録し、再実行で続きから。落ちても賽の河原に しない。
• バッチ＋レート対策：100件ずつ embeddings.create、バッチ間に time.sleep(1)。
• リトライ＋スキップ：失敗は最大3回（sleep(5)後）、超えたら該当だけスキップしてログに残す（全体を 止めない）。
• トークン上限処理：text-embedding-3-small は 8192 上限。tiktoken で計測し、超過は \n\n で段落分割 →再結合で 8000 以内、単一段落でも超えるなら先頭で truncate。
• ベクトルDBは永続クライアント：ChromaDB は PersistentClient(path="./chroma_db")。Client() は プロセス終了で揮発するので使わない。
• ファイル入出力は encoding="utf-8" を明示（→ PythonとWindowsの地雷）。

出典：gemini-rag（gemini-rag/CLAUDE.md Step 1–2）