docs: std corpus 2026-05 snapshot + batch-1000/4000/remaining log
Snapshot of full oshwhub std corpus delivery: - 12,493 projects total, 12,166 (97.4%) with editor source - 4 sweep batches + 1 early-mixed = 5 zip artifacts in COS GZ + SG buckets - 30-day SG-region presigned URLs for downstream pickup log.md tracks the multi-batch sweep including driver bug postmortem (bash heredoc python3 missed httpx → 26-min run wasted on empty zips, recovered by switching to uv run). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
171
log.md
171
log.md
@@ -4,6 +4,177 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-05-03 07:17 batch-remaining-std：扫完所有未抓 std 项目（7,381），双桶副本
|
||||
|
||||
**Claude 会话**
|
||||
|
||||
收尾批：把 unfetched std 池子（7,381 项）一次扫完。拆 A/B 两批 ~3690 each，按 rank 50/50 切（A 头部、B 长尾），**取消单作者上限 2**（这是 sweep 全量，不需要再做多样性约束）。两批走完整 1-4 步 + zip + 双桶推送。
|
||||
|
||||
### 候选筛选
|
||||
- A：top 3691 by rank（grade 0-4 都有，likes p50=8 / p90=29 / max=275）
|
||||
- B：bottom 3690（几乎全 grade 0/1，likes p50=1 / p90=4 / max=21）
|
||||
- 候选 jsonl：`data/state/oshwhub_remaining_{a,b}_std_candidates.jsonl`
|
||||
|
||||
### 第一轮 driver bug 全军覆没（必读）
|
||||
**症状**：driver 跑了 26 min "顺利完成"，但所有 7,381 项 source 都 0——`source_documents=[]` 全空。两个 zip 才 7 MB / 6.8 MB（只 metadata + description，没 source）。
|
||||
|
||||
**根因**：driver 里 Step 4 用 `python3 - <<PYEOF` 而不是 `uv run python -u -`。
|
||||
- Step 1（`uv run -m crawlers.oshwhub`）走的是项目 venv，httpx 在
|
||||
- Step 4 用 system python3，**`crawlers.oshwhub.crawler` 第一行 `import httpx` 直接 ImportError**
|
||||
- `set -uo pipefail` 没设 `-e`，每个 Step 的 stderr 写到日志后继续走，外面看 zip 也成功 / COS 也成功
|
||||
- driver 不会 fail，但源工程 0 拿到
|
||||
|
||||
**教训**：bash heredoc + 多 venv 项目里，**所有依赖项目代码的 Python 调用必须 `uv run`**，仅 stdlib + 系统 pip 包（`qcloud_cos`、`zipfile`）的可以 system python3。下次写 driver 检查时把每个 PYEOF 块对应的 import 列出来对照。
|
||||
|
||||
### Recovery driver
|
||||
重写 `/tmp/recover_driver.sh`：所有 Python 调用改成 `cat > /tmp/step_X.py <<PYEOF ... && uv run python -u /tmp/step_X.py`（避免 heredoc-stdin 路径，文件式更稳）。Step 1/Step 2 已经成功就跳过，只做 Step 4 + retry + zip + COS。
|
||||
|
||||
| 阶段 | 时间 |
|
||||
|---|---:|
|
||||
| RECOVERY START | 06:18:44 |
|
||||
| batch_remaining_a 收工 | 06:48:55（30 min） |
|
||||
| batch_remaining_b 收工 | 07:17:11（28 min） |
|
||||
| **整 recovery 走时** | **58 min** |
|
||||
|
||||
### 完成度
|
||||
| batch | meta | with_source | attach_only | docs | src bytes |
|
||||
|---|---:|---:|---:|---:|---:|
|
||||
| remaining_a | 3,691 | 3,641 (98.6%) | 50 | 8,877 | 3,317 MB |
|
||||
| remaining_b | 3,690 | 3,570 (96.7%) | 120 | 8,231 | 2,783 MB |
|
||||
|
||||
attach_only 比例（A 1.4% / B 3.3%）比 batch-1000 (3.7%)、batch-4000 (0.05%) 没明显异常，D/E tier 项目被废弃 / upstream 删的比例本来就偏高，正常。
|
||||
|
||||
### 双桶最终状态
|
||||
两个桶现在内容完全一致：
|
||||
|
||||
| 对象 | 大小 |
|
||||
|---|---:|
|
||||
| `batch1000_std.zip` | 471 MB |
|
||||
| `batch4000_std.zip` | 1.38 GB |
|
||||
| `batch_remaining_a.zip` | 1.06 GB |
|
||||
| `batch_remaining_b.zip` | 891 MB |
|
||||
| **每桶合计** | **~3.78 GB** |
|
||||
|
||||
走 GZ→SG 服务端 cross-region copy 链路，完全不碰 dev1↔SG 公网丢包链路。100 GB 套餐占 ~7.6 GB（双桶）。
|
||||
|
||||
### 整体 corpus 落幕
|
||||
- listing 里 origin=std 总数：**12,493**
|
||||
- corpus 里 std 项目：12,493（5,112 旧 + 7,381 本批）—— **100% 覆盖**
|
||||
- corpus 总目录数（含 Pro / 早期混抓）：12,523
|
||||
- dev1 占盘：13 GB（40 GB 总，余 13 GB / 33% free）
|
||||
- license 主流：约 60% GPL 3.0 + 18% Public Domain + 5% MIT + 5% NC variants（混合 batch-1-4 趋势一致）
|
||||
|
||||
### 决策（Why）
|
||||
- **不设作者上限**：sweep 全量批次，多样性已在 batch-1000 / batch-4000 阶段保证；这里要的是 "全部"，不能掉作者。
|
||||
- **batch-A vs batch-B 按 rank 切而不是随机**：万一空间不够，优先保 A（更高质量）；实际两批都顺利完成，但万一中断 A 是先做的更稳。
|
||||
- **不删 GZ 桶副本**：用户有 100 GB 套餐，~3.78 GB 双桶舒适；多副本对未来跨区拉取友好。
|
||||
|
||||
### 下一步建议
|
||||
- crawler 加 `--backfill-uuids-file <path>` 选项替代 `--uuids` 字符串，下次大批量不用绕路写 driver 内嵌 Python（参考 `/tmp/backfill_4000.py` 模式可以直接搬进 crawler）
|
||||
- driver 模板加 sanity check：跑完每个 batch 用 `du -sh /tmp/${SHORT}.zip` 与 raw bytes 比，如果压缩比 < 5% 报警（这次的 7 MB zip 用这个能立即抓到）
|
||||
- 全 std corpus 已落地，下次扩量目标应该是 Pro 项目（93 项飞控 Pro 候选还没动）或扩到 oshwhub 之外站点
|
||||
|
||||
---
|
||||
|
||||
## 2026-05-03 03:58 batch-4000-std：Step 1-4 + zip + COS 链路落地 SG box
|
||||
|
||||
**Claude 会话**
|
||||
|
||||
接 batch-1000-std。再扩 4000 项 std → corpus 142 → 1142 → 5142。本批走完整 1-4 步，zip 后通过 COS 跨区链路拉到 SG box 本地（绕开 dev1↔SG 公网丢包链路）。
|
||||
|
||||
### 候选筛选
|
||||
- 数据源同上
|
||||
- A 档（grade≥3 & like≥10）剩 396 项不够 4000，下沉到 unfetched 全池 11,381 按 rank score 倒排，单作者 ≤ 2，取前 4000
|
||||
- 候选 jsonl 落 dev1 `data/state/oshwhub_batch4000_std_candidates.jsonl`
|
||||
- 质量分布：grade 4: 16 / 3: 448 / 2: 1798 / 1: 1319 / 0: 419；likes p50=10 / p90=42（A 档第三梯队 + B + C 头部）
|
||||
|
||||
### 抓取（dev1，concurrency=5）
|
||||
- **Step 1** 详情扫 license：~24 min，3989/4000 OK + 11 fail（全 "Server disconnected"），重抓 concurrency=2 全过 → 4000/4000 metadata
|
||||
- **Step 2** license 盘点：56% GPL 3.0、20% PD、4.8% MIT、4.8% NC-SA、4.3% unknown（unknown 比例比 batch-1000 高，B/C tier 项目 license 标注更随便）
|
||||
- **Step 4** std-source backfill：~31 min，3983 OK + 17 fail
|
||||
- 15 项 "Server disconnected" 瞬态，重抓全过
|
||||
- 2 项 upstream 真实问题：1× `404 文档未找到`（doc 被删），1× `code 104001`（项目封）。这 2 项保留 metadata-only
|
||||
- 最终：4000/4000 metadata · **3998 含完整 sch/pcb 源工程** · 2 metadata-only
|
||||
|
||||
### 关键修：`--uuids` 撞 ARG_MAX
|
||||
- backfill 路径用 `--uuids "$(jq ... | paste -sd,)"`，4000 UUID × 33B ≈ 132 KB > ARG_MAX (128 KiB)
|
||||
- 现象：`bash: /usr/bin/nohup: Argument list too long`，进程没启动，但 pgrep 误匹配 stale shell
|
||||
- 修：临时脚本 `/tmp/backfill_4000.py`，直接 import `crawlers.oshwhub.crawler` 内部函数（`_run_backfill_concurrent` / `fetch_std_source`），UUID 集从 candidates jsonl 读，绕开命令行
|
||||
- 长期：crawler 应加 `--backfill-uuids-file <path>` 选项，下次扩量再改
|
||||
|
||||
### ZIP 打包（dev1）
|
||||
- 4000 dirs，26,098 文件，4,489 MB raw → **1,445 MB zip**，压缩比 32.2%，99 秒完成
|
||||
- 用 Python `zipfile` + `compresslevel=1`（dev1 没装 `zip` 二进制）
|
||||
|
||||
### 传输链路（COS 三段，0 字节走公网丢包链路）
|
||||
| 段 | 时长 | 速度 | 路径 |
|
||||
|---|---:|---:|---|
|
||||
| dev1 → `facere-gz-1321068335` (ap-guangzhou) | 17s | 166 MB/s | 同区内网 |
|
||||
| GZ 桶 → `facere-1321068335` (ap-singapore) | 23s | — | COS 服务端 copy（VM 不参与） |
|
||||
| SG 桶 → SG box | 8.5s | 201 MB/s | 同区内网 |
|
||||
| **整 1.4 GB 跨地域 ~50 秒** | | | |
|
||||
|
||||
哈希校验穿三段：`a79a87e4a3f5dfbad80d9ba94f557b09010e104f6e0c968ea87eba2267b262b3`。
|
||||
|
||||
### 决策（Why）
|
||||
- **rank-score top-4000 不设硬阈值**：硬过滤太挑会漏，rank score 已综合 like\*3 + grade\*50 + views/100 + comments\*2 + fork\*2 + star，自动平衡。最低 like=0 也进了几百项（多数是 grade≥1 但社区互动少的），可接受。
|
||||
- **不传统 scp，走 COS 三段**：之前飞控-77 33 MB scp 走 dev1↔SG 6.5%-loss 链路要 3 min；这次 1.4 GB 走 COS 50 s 完事，提速 ~150×。COS 跨区复制流量计费 ~¥0.5/GB × 1.4 GB ≈ ¥0.7，零头。
|
||||
- **zip vs tar.gz**：zip 选 level=1，速度 vs 体积平衡；tar.gz 单线程 deflate 跟 zip-l1 体积相近但慢 2-3×。
|
||||
|
||||
### 完成度
|
||||
- corpus 由 1142 项扩到 **5142 项**（+4000）
|
||||
- License: 56% GPL 3.0 主流不变，unknown 比例从 0.4% (batch-1000) 涨到 4.3% (batch-4000)，与 B/C tier 项目低标注度一致
|
||||
- editor 版本从 6.3 全谱系到 6.5.42 都覆盖到了
|
||||
- 源文件体积：dev1 上 `data/raw/oshwhub/` 占 ~10 GB（含全部历史 + 本批）
|
||||
|
||||
### 下一步建议
|
||||
- corpus 已经达 5142 项，足够下游 EPRO2/Std → KiCad 训练数据规模
|
||||
- 真要继续扩，A+B+C 档已基本吃完头部，下沉 D 档（grade=0 或 like=0）质量回报递减，可暂缓
|
||||
- crawler 加 `--backfill-uuids-file` 选项，避免下次 ARG_MAX 撞墙
|
||||
- COS GZ 桶里的 `batch1000_std.zip` + `batch4000_std.zip` 用完可以删（SG 桶副本足够），节省 ~¥0.2/月 存储费
|
||||
|
||||
---
|
||||
|
||||
## 2026-05-03 batch-1000-std：Step 1-4，1000 块标准板源工程入库（dev1）
|
||||
|
||||
**Claude 会话**
|
||||
|
||||
走 batch-200 脚手架抓 1000 项 std A 档剩量。**用户指令"只走 1-4 步"**：不抓附件、不传 SG、不 push gitea，数据留 dev1。
|
||||
|
||||
### 候选筛选
|
||||
- 数据源：`data/state/oshwhub_listing_full.jsonl`（33,695 项）
|
||||
- 过滤：`origin=std AND grade≥3 AND like≥10`（A 档），减去已抓 142 项 → 池子 1,396 项
|
||||
- 排序：rank score 倒序；单作者 ≤ 2 → 取前 1000（791 唯一作者）
|
||||
- 候选 jsonl 落 dev1 `data/state/oshwhub_batch1000_std_candidates.jsonl`（不入 git，可重算）
|
||||
- like p50=43 / p90=170 / max=420（A 档第三梯队，吃掉 1,396 池子的 ~72%）
|
||||
|
||||
### 抓取（dev1 Guangzhou，concurrency=5）
|
||||
- **Step 1** 详情扫 license：~80s，996/1000 OK + 4 "Server disconnected" 瞬态 fail
|
||||
- 4 项重抓 (concurrency=2) 全 OK → 1000/1000 metadata
|
||||
- **Step 2** license 盘点：57% GPL 3.0、19% PD、8.6% CC-BY-NC-SA、5.4% MIT、其它 < 2%。形态与 batch-50 / batch-200 一致。
|
||||
- **Step 3** SKIP：本批 std-only，没有 Pro 候选
|
||||
- **Step 4** std-source backfill：~6 分钟，1000/1000 OK，0 fail
|
||||
|
||||
### 完成度
|
||||
- 1000/1000 metadata
|
||||
- 963 项有完整 std 源工程（2,853 个 sch+pcb doc，平均 2.96 docs/proj）
|
||||
- 37 项 upstream attachments-only（`source_documents=[]` 真实状态，跟飞控-77 4/77 同形态）
|
||||
- 源文件体积：1.47 GB on dev1（按 batch-50 估算 12 MB/项 偏高，实测 1.5 MB/项——A 档第三梯队项目体量比头部小）
|
||||
- editor 版本：194 项 6.4.25 / 91 项 6.5.5 / 77 项 6.5.1，6.4-6.5 全谱系覆盖
|
||||
- corpus 由 142 项扩到 1,142 项（+1000）
|
||||
|
||||
### 决策（Why）
|
||||
- **不传 SG / 不 push gitea**：用户指明只走 1-4 步。数据 1.47 GB 走 dev1↔SG 6.5%-loss link 估 ~3 hr 单 scp，没必要现在花。要传时再走 COS 跨区或 split-parallel-scp。
|
||||
- **concurrency=5 全程**：飞控-77 验证过 std doc endpoint 这个并发安全；实测 Step 1 ~12s/100项、Step 4 ~36s/100项，零限流告警。
|
||||
- **Step 3 跳过**：候选池纯 std-origin，Pro backfill 没数据可处理。
|
||||
|
||||
### 下一步建议
|
||||
- 真要消费这批数据：(a) 在 dev1 直接 push gitea（SSH transport，~10 min @ 1.5 GB），或 (b) 走 COS 跨区同步到 SG。
|
||||
- 该批的 metadata-only 部分（37 项 attachments-only）若想补 sch/pcb，需要回头单独扫 attachment ZIP 看里面是否 bundled 了 EasyEDA 工程，那得改 crawler。
|
||||
- A 档剩余只有 396 项了；下次再扩可以下沉到 B 档（grade≥2 & like≥5，3,884 项 unfetched）。
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-30 19:10 飞控-77：主题定向抓 77 块标准飞控板
|
||||
|
||||
**Claude 会话**
|
||||
|
||||
Reference in New Issue
Block a user