Facere/FacereDataset
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
main
FacereDataset/plan.md
Zhang Jiahao b0ddcf3f14 Allow login content; plan cloud infra, storage tiers, EDA→KiCad conversion 
Why:
- 策略调整：登录后才能访问的内容从"禁止"改为"纳入本项目范围"，
  同时明确凭据管理红线（合法账号、不入 git、云服务器隔离）。
  解锁 u.lceda.cn 工程源 JSON，这是训练数据质量的关键升级。
- 计划中"存储"和"运行环境"一直模糊，现在按 Charles 提供的广州云服务器
  + 存储分级演进（Gitea LFS → 对象存储）给出清晰路径。
- 打通 oshwhub (EasyEDA) 与 bshada/open-schematics (KiCad) 两个生态，
  需要一个 EDA→KiCad 批转换脚本。先把它纳入 plan，等拿到工程源再实现。

What:
- CLAUDE.md: 登录态条款从"不抓"改为"合法账号可抓"，凭据管理写死在
  ~/.secrets/，事件记 docs/secrets.md；合规红线同步更新
- plan.md §0.5: 新增 基础设施段（机器初始化 / 调度 / 登录态获取）
- plan.md §1.4: 存储分级演进（< 50 GB 云盘，50-200 GB 评估，> 200 GB 迁对象存储）
- plan.md §1.6: 登录态抓 u.lceda.cn 工程源
- plan.md §1.7: scripts/convert_to_kicad.py 批处理，候选 easyeda2kicad.py
- plan.md 风险表: 加账号封禁 / 转换失败 / 云服务器单点故障三条
- docs/sources/oshwhub.md: u.lceda.cn 从"未开放"移到"需登录，已纳入范围"
- README.md 数据源表: 加"登录态"列 + 运行环境说明
- log.md: 本次策略变更记录

未改：未新增 docs/infra.md（等机器到位 + 真实细节后再写），scripts/convert_to_kicad.py
尚未实现（等拿到工程源样本再实现）。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 20:57:30 +08:00

10 KiB
Raw Permalink Blame History

FacereDataset 爬取与建设计划

维护：Charles 最近更新：2026-04-23 状态：Phase 0 已完成（仓库骨架），Phase 1 待启动

总体策略

先广度后深度，先合规后规模。

  1. 每个数据源先做一份 "可行性调研"（一页纸，放 docs/sources/<site>.md），明确：访问形式、速率限制、许可证分布、ToS 摘要、数据字段覆盖。
  2. 每个站点实现一个最小 MVP 爬虫，单项目跑通 → 然后才全量化。
  3. 全量化之前先对齐抽样结果与存储开销。
  4. 所有站点输出统一到 schemas/project.schema.json 定义的结构，不要让下游消费者去适配 N 种 schema。

Phase 0 — 仓库骨架 ✅

  • README.md / CLAUDE.md / plan.md / log.md
  • 目录骨架 crawlers/ schemas/ scripts/ data/ docs/
  • .gitignore（排除 derivative 目录）/ .gitattributes（LFS 规则）
  • 初始提交并推送

Phase 0.5 — 基础设施 / 运行环境

目标：把爬取从本地 dev 机迁到专用云服务器（广州，已规划），集中管理登录凭据、磁盘和长跑任务。

0.5.1 云服务器初始化（待机器到位）

  • 机器规格确认（CPU / 内存 / 磁盘初始容量；广州可用区）
  • 基础环境：
    • 系统升级 + 防火墙
    • 安装：git, git-lfs, uv, python 3.11+, jq, curl
    • 创建非 root 用户 + SSH key（不允许密码登录）
  • 克隆仓库：git clone https://git.deepknow.site/Facere/FacereDataset.git ~/repo/FacereDataset
  • git lfs install + 配置 Gitea 带 token 的 remote
  • uv sync 安装依赖
  • 凭据目录：~/.secrets/ (mode 700)，放 Gitea token、oshwhub cookie、其它登录态
  • 写 docs/infra.md 记录主机 ID、用户、路径、端口开放情况（不含凭据值）

0.5.2 调度

  • 单次长跑：tmux / nohup + 输出落 ~/logs/<site>-<date>.log
  • 定期增量：systemd timer（优先）或 cron，每周扫新增 / 更新
  • 磁盘监控： df -h | cron 告警阈值 80%

0.5.3 登录态获取（按站点）

  • oshwhub / u.lceda.cn：用浏览器登录后导出 cookie → 转 ~/.secrets/oshwhub-cookies.txt，httpx 通过 cookies= 注入
  • 换号 / 重登事件记到 docs/secrets.md（只写事件，不写值）

Phase 1 — 立创开源平台（oshwhub.com）MVP ✅ 首批完成

目标：跑通 10 个项目的完整抓取，验证 schema。 实际：10/10 成功，52 附件，524 MB 入 LFS。

1.1 调研 ✅

  • 列表 API /api/project?page=N&pageSize=M&sort=hot（无鉴权）
  • 详情页 SSR HTML 嵌入 escaped JSON，含 attachments 数组与 license
  • 附件 CDN image.lceda.cn/{src} 直连
  • docs/sources/oshwhub.md 调研笔记

1.2 爬虫 MVP ✅

crawlers/oshwhub/crawler.py：

  • 列表分页 + 质量打分排序
  • HTML 解析：title / description / license / attachments
  • 每项目目录：metadata / description / cover / files / _urls
  • QPS ≤ 0.5，UA 真实声明

1.3 验收 ⏳

  • 10/10 成功，产出符合 schemas/project.schema.json
  • 待人工：随机抽查 2-3 条对照原站
  • scripts/validate.py 自动 schema 校验（未写，后续补）

1.4 放量（待决策）

  • 定目标规模：50 / 500 / 5000 / 全量 12493
  • 实测规模分布（见 docs/sources/oshwhub.md §5）：
    • median/proj 9 MB → 全量 ~110 GB（合理预算）
    • p90 上界 660 GB
    • mp4+qt 视频占 54% → 加 --skip-ext mp4,qt 可省一半
  • 存储分级（按规模演进）：
    • Phase 1.x 前期（< 50 GB）：直接落云服务器磁盘，git-lfs push 到 Gitea
    • 放量中期（50 – 200 GB）：Gitea LFS 容量压力评估；可选方案 (a) 服务器挂载大盘扩容，(b) 分批 push 分仓（按月 / 按 grade 档位切仓库）
    • 放量后期（> 200 GB）：迁移到网盘 / 对象存储（候选：阿里云 OSS、腾讯 COS、MinIO 自建），Gitea 只存 metadata + 指针
    • 选型决策点：达到 50 GB 时评估，不过早迁移
  • 增量更新：updated_at 变动检测 + LFS prune 策略（未实现）
  • 登录态工程源（u.lceda.cn EasyEDA JSON）现在纳入范围，见 §1.6

1.6 登录态工程源抓取（u.lceda.cn）

目标：拿到立创 EDA 的真正工程源 JSON（含原理图、PCB、组件数据），而不只是用户附件。是训练数据质量的关键升级。

  • 在广州云服务器上用合法账号登录 oshwhub / EasyEDA，导出 cookie
  • 探明 u.lceda.cn/api/... 的项目源下载端点：
    • /api/projects 返回 401（需 session）——登录后试
    • 可能的端点：/api/project/<uuid>、/api/document/<uuid>/source
  • 扩展 crawlers/oshwhub/crawler.py：
    • --with-source 开关触发登录态抓取
    • 把工程源 JSON 存到 data/raw/oshwhub/<uuid>/source.json（LFS）
    • schema 加 source_format: "easyeda" 字段
  • 账号速率更保守：登录态 QPS ≤ 0.2，避免被封号

1.7 立创 EDA → KiCad 格式转换

目标：把 source.json（立创 EDA / EasyEDA 格式）批量转成 KiCad 原生格式（.kicad_sch + .kicad_pcb + 可选 .pretty 库），打通 oshwhub（EasyEDA 生态）与 bshada/open-schematics（KiCad 生态）的统一训练语料。

预选工具：easyeda2kicad（pypi 包，活跃维护）

  • 支持 EasyEDA → KiCad 6/7/8 symbol / footprint / 3D model 转换

  • 可能需要扩展以支持整个 project JSON → .kicad_pro + 关联文件

  • 调研 easyeda2kicad.py 的整工程转换能力；若只支持单符号 / 封装，评估是否需要自写 orchestrator

  • 写 scripts/convert_to_kicad.py：

    • 输入：data/raw/oshwhub/<uuid>/source.json
    • 输出：data/processed/oshwhub/<uuid>/kicad/ 下的 .kicad_sch、.kicad_pcb 等
    • 支持批处理：--input data/raw/oshwhub/ --output data/processed/oshwhub/ 扫全目录
    • 失败样本落 data/state/convert_failed.jsonl（记 uuid + 原因）
    • 转换后跑 KiCad CLI kicad-cli sch erc / pcb drc 做语法校验

  • 产出统计：转换成功率、常见失败模式，反馈到工具选型

  • 运行：云服务器定期批处理（每次爬完新项目后跑）

1.5 纳入第三方预处理数据集 bshada/open-schematics

性质：Hugging Face 已发布的 KiCad schematics 数据集（非待爬网站），镜像导入即可。

目标：补 KiCad 原生生态，与 oshwhub (EasyEDA) 互补。

  • 调研（见 docs/sources/hf_bshada_open_schematics.md）
  • 待拍板 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） 存储爆炸 实测 p90=54MB 可接受；大于阈值走外部 OSS、只存 URL
GitHub API rate limit Phase 2 慢 使用已登录 gh token；必要时换 fine-grained PAT
站点改版 爬虫失效 爬虫带 schema 自检，HTML 结构变化时告警
登录态账号被封 §1.6 登录态工程源卡住 账号 QPS ≤ 0.2；多账号轮询；凭据泄露应急计划（见 docs/infra.md）
EDA→KiCad 转换缺失字段 §1.7 产物不可用 每轮记录失败样本；扩展工具 or 保留原始 JSON 作 fallback
云服务器单点故障 长跑任务中断 数据及时 push 到 Gitea；定时快照云盘；抓取进度存 data/state/

未决：

  • 数据规模目标：第一版想要 1 万 / 10 万 / 全量？
  • 存储分级切换阈值：什么时机从 Gitea LFS 迁到对象存储？（当前提议 200 GB）
  • 对象存储选型：阿里云 OSS / 腾讯 COS / MinIO 自建？
  • 是否保留视频（mp4/qt 占 54% 存储）：加 --skip-ext 还是全保？
Reference in New Issue View Git Blame Copy Permalink