53b7648984
Why:
- Charles 点名把该 HF 数据集纳入第一批。它是已预处理包（非待爬网站），
和 oshwhub 的抓取逻辑不一样，先把决策面在 plan 里讲清楚，再动手拉。
- 与 oshwhub (EasyEDA 生态) 互补，补 KiCad 原生路径。
What:
- docs/sources/hf_bshada_open_schematics.md: 调研文档
- 78 parquet shards, 6.4 GB 总量
- CC-BY-4.0 商用友好
- 字段：.kicad_sch 源 / PNG / 组件列表 / JSON / YAML / name / desc
- 镜像方案（整包存 data/external/..., 不拆 per-project）
- .gitattributes 建议（data/external/**/*.{parquet,png} → LFS）
- plan.md §1.5: 阶段说明 + 待 Charles 批 6.4 GB 预算
- README.md 数据源表: 加一行
- log.md: 本次记录
下载未触发，等 Charles 拍板。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
154 lines
6.0 KiB
Markdown
154 lines
6.0 KiB
Markdown
# FacereDataset 爬取与建设计划
|
||
|
||
**维护**：Charles
|
||
**最近更新**：2026-04-23
|
||
**状态**：Phase 0 已完成（仓库骨架），Phase 1 待启动
|
||
|
||
---
|
||
|
||
## 总体策略
|
||
|
||
**先广度后深度，先合规后规模。**
|
||
|
||
1. 每个数据源先做一份 "可行性调研"（一页纸，放 `docs/sources/<site>.md`），明确：访问形式、速率限制、许可证分布、ToS 摘要、数据字段覆盖。
|
||
2. 每个站点实现一个最小 MVP 爬虫，**单项目跑通** → 然后才全量化。
|
||
3. 全量化之前先跟 Charles 对齐抽样结果与存储开销。
|
||
4. 所有站点输出统一到 `schemas/project.schema.json` 定义的结构，不要让下游消费者去适配 N 种 schema。
|
||
|
||
---
|
||
|
||
## Phase 0 — 仓库骨架 ✅
|
||
|
||
- [x] `README.md` / `CLAUDE.md` / `plan.md` / `log.md`
|
||
- [x] 目录骨架 `crawlers/ schemas/ scripts/ data/ docs/`
|
||
- [x] `.gitignore`（排除 derivative 目录）/ `.gitattributes`（LFS 规则）
|
||
- [x] 初始提交并推送
|
||
|
||
---
|
||
|
||
## Phase 1 — 立创开源平台（oshwhub.com）MVP ✅ 首批完成
|
||
|
||
**目标**：跑通 10 个项目的完整抓取，验证 schema。
|
||
**实际**：10/10 成功，52 附件，524 MB 入 LFS。
|
||
|
||
### 1.1 调研 ✅
|
||
|
||
- [x] 列表 API `/api/project?page=N&pageSize=M&sort=hot`（无鉴权）
|
||
- [x] 详情页 SSR HTML 嵌入 escaped JSON，含 attachments 数组与 license
|
||
- [x] 附件 CDN `image.lceda.cn/{src}` 直连
|
||
- [x] `docs/sources/oshwhub.md` 调研笔记
|
||
|
||
### 1.2 爬虫 MVP ✅
|
||
|
||
`crawlers/oshwhub/crawler.py`：
|
||
|
||
- [x] 列表分页 + 质量打分排序
|
||
- [x] HTML 解析：title / description / license / attachments
|
||
- [x] 每项目目录：metadata / description / cover / files / _urls
|
||
- [x] QPS ≤ 0.5，UA 真实声明
|
||
|
||
### 1.3 验收 ⏳
|
||
|
||
- [x] 10/10 成功，产出符合 `schemas/project.schema.json`
|
||
- [ ] **待 Charles**：随机抽查 2-3 条对照原站
|
||
- [ ] `scripts/validate.py` 自动 schema 校验（未写，后续补）
|
||
|
||
### 1.4 放量（待决策）
|
||
|
||
- [ ] Charles 定目标规模：50 / 500 / 5000 / 全量 12493
|
||
- [x] 实测规模分布（见 `docs/sources/oshwhub_corpus_estimate.md`）：
|
||
- median/proj 9 MB → 全量 **~110 GB**（合理预算）
|
||
- p90 上界 **660 GB**
|
||
- mp4+qt 视频占 54% → 加 `--skip-ext mp4,qt` 可省一半
|
||
- [ ] 未解决：
|
||
- `u.lceda.cn` EasyEDA 工程 JSON（需登录，v0.1 跳过）
|
||
- 增量更新：`updated_at` 变动检测 + LFS prune 策略
|
||
|
||
### 1.5 纳入第三方预处理数据集 `bshada/open-schematics`
|
||
|
||
**性质**：Hugging Face 已发布的 KiCad schematics 数据集（非待爬网站），镜像导入即可。
|
||
|
||
**目标**：补 KiCad 原生生态，与 oshwhub (EasyEDA) 互补。
|
||
|
||
- [x] 调研（见 `docs/sources/hf_bshada_open_schematics.md`）
|
||
- [ ] **待 Charles 拍板** 6.4 GB LFS 预算
|
||
- [ ] 目录：`data/external/huggingface/bshada--open-schematics/`
|
||
- 整包镜像，**不**拆成 per-project 目录（10K+ 条记录）
|
||
- 78 parquet shards + README + 封面 + 追加 `ATTRIBUTION.md`
|
||
- [ ] `.gitattributes`：`data/external/**/*.{parquet,png}` 走 LFS
|
||
- [ ] 下载：`huggingface-cli download bshada/open-schematics --repo-type dataset --local-dir data/external/huggingface/bshada--open-schematics`
|
||
- [ ] 单独维护 `datasets.md`（per-project 索引 `projects.md` 不适合整包数据集）
|
||
|
||
---
|
||
|
||
## Phase 2 — GitHub 开源硬件 repo
|
||
|
||
**目标**：抓 KiCad / EasyEDA / Eagle 格式的公开 repo。
|
||
|
||
- [ ] 用 GitHub Code Search API 查 `extension:kicad_pcb` / `extension:sch` / `filename:*.epro` 等
|
||
- [ ] 过滤 star ≥ N（降噪，可调）
|
||
- [ ] 抓 repo 元数据 + 文件树 + 关键文件，**不 clone 全仓**（省带宽）
|
||
- [ ] License 从 repo `LICENSE` 文件 + GitHub API `license` 字段双取
|
||
- [ ] MCP：优先 `mcp__github__*` 工具；大规模批量可切 `gh api` + `gitingest`
|
||
|
||
预计工期：3-5 天。
|
||
|
||
---
|
||
|
||
## Phase 3 — Hackaday.io
|
||
|
||
- [ ] 探测是否有公开 API（`/api/v1/` 曾经存在，需 key）
|
||
- [ ] 若无 API：解析 explore 列表 + project/log 页面
|
||
- [ ] 重点抓项目叙事（README / build log）——这是 LLM 语料的高价值部分
|
||
|
||
预计工期：3 天。
|
||
|
||
---
|
||
|
||
## Phase 4 — 长尾站点
|
||
|
||
并列小项目，每个 0.5-1 天：
|
||
|
||
- [ ] CERN OHR（`ohwr.org`）—— 高质量、CERN-OHL 许可清晰
|
||
- [ ] Wikifactory
|
||
- [ ] Open Hardware Park
|
||
- [ ] Tindie（仅商品元数据，文件多半不公开）
|
||
- [ ] Instructables 硬件类目（文本叙事为主）
|
||
|
||
---
|
||
|
||
## Phase 5 — 数据清洗与派生
|
||
|
||
- [ ] 去重：`sha256(files)` + `(title, author)` 模糊匹配
|
||
- [ ] 质量打分：字段完整度 + 文件大小合理性 + license 有效性
|
||
- [ ] 派生数据集：
|
||
- `components.jsonl`：从 BOM 汇总常见元件 → 成本曲线
|
||
- `subcircuits.jsonl`：常见子电路模板（电源、USB、MCU 最小系统）
|
||
- `narratives.jsonl`：项目叙事文本语料（给 LLM 预训练）
|
||
- [ ] 生成 README 级统计：项目总数、许可证分布、站点覆盖
|
||
|
||
---
|
||
|
||
## Phase 6 — 持续运营
|
||
|
||
- [ ] 增量爬取 cron：每站点每周扫一次新增/更新
|
||
- [ ] 数据发布：版本化 snapshot（v0.1, v0.2, ...），Release tag 到 Gitea
|
||
- [ ] 反馈回路：模型训练团队发现脏数据 → issue → 过滤规则下沉到 `scripts/`
|
||
|
||
---
|
||
|
||
## 风险与未决项
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|-----|-----|-----|
|
||
| oshwhub 反爬加强 | 卡住 Phase 1 | 切 lightpanda/真 Chrome；降速；部分内容弃 |
|
||
| 许可证字段缺失 / 模糊 | 下游训练合规风险 | 默认剔除 `license: unknown`；建 whitelist |
|
||
| 单个项目附件过大（>100MB） | 存储爆炸 | Phase 1 调研时统计分布；大文件走外部 OSS，记录 URL 不本地化 |
|
||
| GitHub API rate limit | Phase 2 慢 | 使用已登录 `gh` token；必要时换 fine-grained PAT |
|
||
| 站点改版 | 爬虫失效 | 爬虫带 schema 自检，HTML 结构变化时告警 |
|
||
|
||
**未决**（需要 Charles 定）：
|
||
- 数据存储方案：本地盘（够吗？）、Gitea LFS、或外挂对象存储？
|
||
- 是否要保留图片/Gerber/STEP 的二进制，还是只存 URL？
|
||
- 目标规模：第一版想要 1 万 / 10 万 / 全量？
|