開発book-knowledge-base

「この資格分野の参考書って蔵書DBに入ってましたっけ」と思い立って book-knowledge-base（全60冊）を覗いたら、その分野の本は1冊も入っていなかった。手元には自炊した参考書がある。市販の参考書で、4分冊・合計655ページ。これを今日、OCRしてDBに取り込み、ページ単位から章・節単位へ整理し直すところまで持っていった。途中、サブエージェントがDB同期で無言のまま固まり、最後にはローカルのレプリカファイルが壊れて80MBの再ダウンロードが走った。順調に終わるかと思った作業が、Embedded Replica運用の地雷を2つ踏んで終わった。

4分冊を「それぞれ独立した書籍」として扱う方針にした

最初に決めたのは、4分冊をどう数えるかだった。1冊として扱うか、4冊として扱うか。分野別に分かれた4冊なので、それぞれ独立した書籍として登録する方針にした。全文検索でヒットしたときに、どの分野の本かがそのまま分かるほうが後で楽だと判断したからだ。

OCRは長丁場になる見込みだったので、走らせる前に各冊の book_id とタイトルだけ先に確定させた。途中で命名がブレて再インポートが発生すると、655ページぶんをやり直すことになる。そこだけは慎重に潰した。

yomitokuのOCRは見積もり60分が15〜20分で終わった

/yomitoku で4分冊のPDFをMarkdownに変換し、本文中の図を画像として抽出させた。最初は計45〜60分かかる長丁場のつもりで、バックグラウンドジョブに投げて待つ構えだった。

ところが起動直後の出力を覗くと、GPUが約1秒/ページで淡々と回っていた。この速度なら合計15〜20分で終わる。見積もりが3倍ずれていた。

時間とディスクを節約するため、診断用の可視化画像出力（-v）は省いた。一方で図の抽出に効く --figure --figure_letter は残した。図がなければ参考書の意味が半減するからだ。

# 可視化画像(-v)は省く / 図抽出のフラグは維持
yomitoku ... --figure --figure_letter

4分冊すべて exit 0 で完了し、生成されたMDの数がページ数と完全に一致した。欠けも重複もない。続いて図ファイル1181枚を一括でリネームした。

4分冊をTursoに640チャンクで格納した

OCRしたテキストを Turso（libSQL/SQLite互換のクラウドDB）へ、ページ単位で640チャンクとして格納させた。再実行したときに同じ本が二重に入らないよう、各冊とも「既存削除→投入」の冪等処理にした。一時スクリプトを書いて流し、終わったら消した。

amazon_metadata の紐付けでひと工夫いった。インポートの過程で自動紐付けが4回発火し、最後に処理した分冊が勝ってしまう状態だった。代表となる1冊の book_id に紐付けを確定し直して、書誌情報とコンテンツの対応を1本に揃えた。

試行錯誤①：init_books_db() がトリガーのSQLでパース失敗した

格納スクリプトを走らせたら、init_books_db() がスキーマSQLのトリガー定義でパースに失敗した。トリガーの BEGIN ... END ブロックの中に ; が含まれていて、文の区切りを誤認していた。

ただ、よく考えればTurso上にはテーブルがもう作成済みだ。この初期化呼び出し自体が不要だった。原因を深追いしてSQLパーサを直すより、いらない呼び出しを削るのが筋だと判断して、その行を消した。これで4分冊のインポートが通り、合計640チャンクが入った。

ページ単位640チャンクを章・節単位74チャンクへ統合した

次に /restructure-book を4冊すべてに適用した。OCR直後はページ単位でぶつ切りのチャンクになっている。これを目次に沿って章・節単位へ統合し、640チャンクを74チャンク（17/15/24/18）へまとめ直した。

DB書き込み、特にFTS（全文検索インデックス）のリビルドは全体を再構築する重い処理で、並列で走らせると衝突する。なので1冊ずつ逐次、各冊を専用のサブエージェントに委譲して、順番に起動しては完了を待った。

試行錯誤②：サブエージェント経由でEmbedded Replicaがsync()でハングした

1冊目（39→17チャンク）の統合自体は終わったのに、サブエージェントが最後の sync() で固まった。Embedded Replicaの同期処理が、無言のまま返ってこない。

これは前から踏んでいる既知の地雷だった。Embedded Replicaは、サブエージェントやバッチ経由で動かすとWALロックでハングする。ローカルにレプリカファイルを持つ方式なので、先行接続が握ったロックが残ると、後続の処理がロック待ちで止まる。タイムアウトもエラーも出ず、ただ待ち続ける。

逃げ道は分かっていた。残り3冊は、サブエージェントに全ステップHTTP直接接続を使わせた。ローカルのレプリカファイルを一切経由せず、Tursoクラウドへ直接書く。これでロックの待ち合わせが起きなくなり、ハングは再発しなかった。

# Embedded Replica（ローカル経由 → サブエージェントだとロックでハング）
conn = libsql.connect("local.db", sync_url=TURSO_URL, auth_token=TOKEN)

# HTTP直接接続（クラウドへ直接 → ロック待ちなし）
conn = libsql.connect(database=TURSO_URL, auth_token=TOKEN)

最大の分冊（242→24チャンク）も含め、残り3冊はHTTP直接接続で詰まらず通った。横断のFTS検索を流すと、CHAPTER01 ... | SEC03 ... のようなクリーンな章/節ラベルでヒットするようになった。ページ番号で引いていた頃とは別物の引き心地だ。

試行錯誤③：クラウドだけ更新してローカルレプリカが陳腐化し、そして壊れた

ハングを避けるためにrestructureを全部HTTP直接接続でやった。その代償が最後に出た。

クラウド側は74チャンクに更新された一方で、ローカルのEmbedded Replicaファイルは旧640チャンクのまま取り残された。次にPython CLIがEmbedded Replicaで繋いだら、差分同期でまたハングしうる。爆弾を残したまま終わるのは気持ち悪い。

健全性を確認しにいくと、レプリカが壊れていた。db file exists but metadata file does not ——レプリカ本体のファイルはあるのに、メタデータの .db-info が欠落していた。これでは整合が取れず、繋いだ瞬間に詰む。

対処は単純だった。データの本体はクラウドにあるので、ローカルのレプリカは退かしても何も失わない。壊れた3ファイルを退避ディレクトリへ移動し、Embedded Replicaで繋ぎ直した。クラウドから約80MBを再ダウンロードして、レプリカがゼロから自動で組み上がった。

最終的に、蔵書74チャンク・全62冊。横断FTS検索もクリーンな章/節ラベルで返り、レプリカも再構築済みで健全な状態に戻った。HTTP直接接続で逃げただけで放置せず、本来のEmbedded Replica経路でも動くところまで見届けて終えた。

学びメモ

  • Embedded Replicaは、サブエージェントやバッチ経由だとsync()でハングする。 ローカルレプリカのWALロック待ちが原因で、エラーも出ずただ固まる。書き込みを連続で回す処理や委譲先のサブエージェントには、最初からHTTP直接接続を使わせるのが安全
  • クラウドだけHTTPで更新すると、ローカルレプリカが陳腐化する。 旧状態のまま取り残されたレプリカは、次に繋いだとき差分同期でハングしたり、メタデータ欠落（.db-info なし）で壊れたりする。HTTP直接接続で更新したら、最後にレプリカの健全性まで確認する
  • 壊れたレプリカは退避すれば自動で再構築される。 データの本体はクラウドにあるので、ローカルファイルを退かすのは非破壊。繋ぎ直せばクラウドから引き直して組み上がる。怖がらずに退避していい
  • 見積もりは外れる前提で、起動直後に実測を取る。 60分のつもりが1秒/ページで15〜20分で終わった。長丁場と決めつけて放置せず、最初の数ページで速度を見ると計画を立て直せる
  • エラーの原因を直すより、いらない処理を消すほうが速いことがある。 トリガーSQLのパース失敗は、テーブル作成済みなら初期化呼び出しごと不要だった