pdf-brain-ingest

PDF Brain Ingest v2（ADR-0234）

采用分阶段制品链的流水线，使用持久化 NAS 存储、nomic 嵌入和工作负载队列编排。

流水线 v2 架构

PDF (source, immutable)
  → Stage 1: CONVERT — opendataloader-pdf → {docId}.md (NAS artifact)
  → Stage 2: CLASSIFY + SUMMARIZE — taxonomy + LLM summary → {docId}.meta.json (NAS artifact)
  → Stage 3: CHUNK — markdown-native headings, no overlap → {docId}.chunks.jsonl (NAS artifact)
  → Stage 4: INDEX — upsert to docs + docs_chunks_v2 (nomic-embed-text-v1.5, 768-dim)

关键特性：

• 持久化：制品存储在 NAS RAID5 上，可在重启或崩溃后保留
• 可续跑：每个阶段都会检查现有制品，若已存在则跳过
• 可恢复：可从现有制品重新运行任意阶段，无需重新提取
• 可观测：每本书的每个阶段都会生成一个 OTEL 事件

制品目录：${DOCS_ARTIFACTS_DIR}/{docId}/，使用 ~/.config/system-bus.env 中的机器本地值

• {docId}.md — 结构化 Markdown 提取结果
• {docId}.meta.json — 分类体系、摘要、元数据
• {docId}.chunks.jsonl — 分块记录，每行一条

核心工作流

1) 预检

joelclaw status
joelclaw docs status

状态现在会同时显示 v1 和 v2 的集合统计信息以及制品可用情况。

2) 单文件摄取（v1 流水线）

joelclaw docs add "/absolute/path/to/file.pdf"
joelclaw docs add "/absolute/path/to/file.pdf" --title "Title" --tags "tag1,tag2" --category programming

3) 单文件 v2 重建索引（制品流水线）

joelclaw docs reindex-v2 "/absolute/path/to/file.pdf"
joelclaw docs reindex-v2 "/absolute/path/to/file.pdf" --title "Title" --skip-existing

触发 docs/reindex-v2.requested → 4 阶段制品流水线 → NAS 制品 + docs_chunks_v2。

4) 批量重建索引（完整资料库）

# Reindex all PDFs from the configured NAS book root
joelclaw docs batch-reindex --skip-existing

# Reindex from existing Typesense docs collection
joelclaw docs batch-reindex --from-collection --skip-existing

触发 docs/reindex-batch.requested → 扫描 NAS/集合 → 以 10 个为一批分发单独的 reindex-v2 事件，并发数为 3。

--skip-existing 会跳过 NAS 上已具备全部 3 个制品的书籍（默认为 true）。

5) 监控进度

# Artifact count on NAS (load machine-local config without printing it)
set -a; . ~/.config/system-bus.env; set +a
find "$DOCS_ARTIFACTS_DIR" -mindepth 1 -maxdepth 1 -type d | wc -l

# v2 collection chunk count
joelclaw docs status

# OTEL events from pipeline
joelclaw otel search "docs.reindex" --hours 4
joelclaw o11y session system-bus --hours 4

# Individual run trace
joelclaw runs --count 10
joelclaw run <run-id>

6) 检查制品

# Read the extracted markdown
joelclaw docs markdown <doc-id>

# Read the summary + taxonomy metadata
joelclaw docs summary <doc-id>

# Or directly on NAS after loading machine-local config
set -a; . ~/.config/system-bus.env; set +a
cat "$DOCS_ARTIFACTS_DIR/<docId>/<docId>.md"
cat "$DOCS_ARTIFACTS_DIR/<docId>/<docId>.meta.json" | jq
wc -l "$DOCS_ARTIFACTS_DIR/<docId>/<docId>.chunks.jsonl"

7) 从 v2 检索

# Search uses docs_chunks_v2 (nomic 768-dim) by default
joelclaw docs search "distributed consensus" --limit 8

# Context expansion
joelclaw docs context <chunk-id> --mode snippet-window
joelclaw docs context <chunk-id> --mode parent-section
joelclaw docs context <chunk-id> --mode section-neighborhood

8) 覆盖范围对账

joelclaw docs reconcile --sample 20

9) 恢复

如果批处理停滞或书籍处理失败：

• Inngest 会自动重试每个步骤（默认重试策略）
• --skip-existing 表示重新触发批处理时只会处理未完成的书籍
• 查看 OTEL 错误：joelclaw otel list --level error --hours 4
• 单独重试：joelclaw docs reindex-v2 "/path/to/failed.pdf"

提取详情

• 主要方案：opendataloader-pdf v2.0.0（基于 Java，在基准测试中排名第 1，准确率为 0.90）
• 备用方案：pypdf（Java 不可用时进行基础文本提取）
• 要求：Java 11+（panda 上已安装 OpenJDK 25，PATH 已在 worker start.sh 中配置）
• 速度：在 M4 Pro 上每本书约 2.5 秒

嵌入模型

• v2：通过 ollama 使用 nomic-embed-text（在 M4 Pro 上由 GPU 加速，768 维，针对检索调优）。摄取时预先计算，并以原始 float[] 向量存储。速度约为 Typesense CPU 自动嵌入的 150 倍。
• v1：ts/all-MiniLM-L12-v2 — 384 维，通用型，由 Typesense 自动嵌入（旧版，仍在 docs_chunks 中）
• Ollama 在 panda 上运行，地址为 localhost:11434。System-bus-worker（主机进程）在摄取时生成嵌入。

分块策略（ADR-0234）

• 基于 Markdown 的标题检测（使用 # 标记，而非启发式方法）
• 对超出目标 token 数的章节进行递归拆分
• 不重叠（arxiv R100-0 研究结果：精确率提高 45%）
• 两级层级结构：章节分块 + 摘录子分块
• heading_path 根据实际 Markdown 标题级别生成
• 上下文继承：retrieval_text 包含 [DOC: title] [SUMMARY: ...] [PATH: heading > path] [CONCEPTS: ...]

获取流水线（aa-book → 摄取）

joelclaw send pipeline/book.download -d '{
  "query": "designing data-intensive applications",
  "format": "pdf",
  "reason": "library expansion"
}'

通过 aa-book 下载 → 备份到 NAS → 触发 docs/ingest.requested 以立即处理。

Inngest 事件

事件	函数	用途
docs/ingest.requested	docs-ingest	v1 流水线（单文件）
docs/reindex-v2.requested	docs-reindex-v2	v2 制品流水线（单文件）
docs/reindex-batch.requested	docs-reindex-batch	批处理编排器（全部 PDF）
docs/backlog.requested	docs-backlog	基于旧版清单的回填
docs/enrich.requested	docs-enrich	为现有文档重新丰富元数据
pipeline/book.download	book-download	获取并摄取新书