Skip to content
ict-agent
asc-data
Public

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

Ascend C Pretraining Corpus Builder

用于收集和整理 Ascend C / CANN 相关仓库语料的工具集，目标是把多平台代码仓库转换为适合大模型预训练的结构化 JSONL 语料。

详细运行说明见：

  • docs/5-minute-onboarding.md
  • docs/runbook.md
  • docs/schema-gap-analysis.md
  • docs/codebase-interpretation.md

概览

当前实现覆盖：

  • GitCode、Gitee、GitHub 的仓库发现与 API 采集
  • 本地 git clone / fetch 后的源码、文档、commit history 抽取
  • code / doc / issue / pull_request / commit / branch 六类语料输出
  • 官方文档页与 toolkit 下载页的手工来源补充
  • 增量写出的 manifest.json、index/repos.json、index/shards.json
  • 逐仓阶段状态、断点续做与实时状态看板
  • 基础统计与详细分析脚本

当前重要约定：

  • 现在的正式输出结构是 data/raw + data/normalized
  • 默认不做训练前内容去重
  • 默认分支会优先处理，但不会丢掉其他分支

当前目录结构

asc-data/
  config.yaml
  repos/
    <platform>/
      <org_name>/<repo>/
      _misc/<owner>--<repo>/
  data/
    raw/
      <snapshot>/
        api/
        docs/
        toolkit/
        discovery/
        status/
    normalized/
      <snapshot>/
        repos/
        index/
        manifest.json
  docs/
    runbook.md
    schema-gap-analysis.md
  scripts/
    build_corpus.py
    stats.py
    analyze_corpus.py
  sources/
    ascend_language_sources.yaml
  src/

目录说明：

  • repos/: 跨 snapshot 复用的 Git 缓存，正式布局为 repos/<platform>/<bucket>/<repo_key>/
  • 如果旧版本运行留下了本应属于核心 org 的 _misc/<owner>--<repo>/，优先运行 scripts/reorganize_repo_cache.py 重组缓存，而不是直接删除全部产物
  • data/raw/<snapshot>/: 当前 snapshot 的原始抓取结果
  • data/raw/<snapshot>/status/: 当前 snapshot 的任务状态与实时看板
  • data/normalized/<snapshot>/: 当前 snapshot 的结构化语料与索引
  • docs/runbook.md: 最详细的运行手册
  • docs/5-minute-onboarding.md: 新同学 5 分钟上手说明
  • docs/schema-gap-analysis.md: 当前 schema 与 The Stack v2 的差异分析
  • docs/codebase-interpretation.md: 当前代码仓库结构与数据流解读

最短上手

1. 准备环境

推荐环境：

  • Python 3.11
  • Conda 环境：dev-py311

安装依赖：

conda create -n dev-py311 python=3.11 -y
conda run -n dev-py311 pip install -r requirements.txt

新环境建议先做一轮 CLI 自检：

conda run -n dev-py311 python scripts/build_corpus.py --help
conda run -n dev-py311 python scripts/show_run_status.py --help
conda run -n dev-py311 python scripts/stats.py --help
conda run -n dev-py311 python scripts/analyze_corpus.py --help

2. 准备 Token

建议配置：

  • GITCODE_TOKEN
  • GITEE_TOKEN
  • GITHUB_TOKEN

可以二选一：

方式 1：直接在 shell 里导出

export GITCODE_TOKEN="your_gitcode_token"
export GITEE_TOKEN="your_gitee_token"
export GITHUB_TOKEN="your_github_token"

方式 2：在项目根目录创建 .env

cp .env.example .env

然后编辑 .env：

GITCODE_TOKEN=your_gitcode_token
GITEE_TOKEN=your_gitee_token
GITHUB_TOKEN=your_github_token

当前加载规则：

  • config.yaml 中的 ${...} 同时支持 shell 环境变量和项目根目录 .env
  • 如果 shell 环境变量和 .env 同时存在，优先使用 .env

3. 先做发现

conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --discover-only

发现结果会写到：

  • data/raw/<snapshot>/discovery/discovered_repos.json

4. 做一轮小规模验证

conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --repo-limit 10

补充说明：

  • seed_repos 现在会严格按 config.yaml 中的书写顺序优先处理
  • 在默认配置下，--repo-limit 1 会先处理 seed_repos.gitcode 里的第一个核心仓，也就是 cann/ops-nn
  • 如果你想做“只跑一个指定仓”的隔离测试，最稳妥的方式仍然是临时复制一份配置，只保留该仓并清空 seed_orgs 与 search_keywords

5. 全量抽取

conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml

如果你只想跑部分任务，可以用阶段筛选：

conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --only-stages clone,code,commits
conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --skip-stages pulls,branches

可选阶段：

  • manual
  • clone
  • code
  • commits
  • issues
  • pulls
  • branches

说明：

  • code 和 commits 依赖本地仓缓存，选中它们时会自动补做 clone
  • issues、pulls、branches 可以独立运行，适合把 API 类阶段单独补齐
  • manual 是手工文档/工具包源，建议在共享 snapshot 中只初始化一次

如果你想多人分工跑同一个 snapshot，可以按仓库切片：

conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --output-version <snapshot> --repo-slice 1/3 --only-stages clone,code,commits,issues,pulls,branches
conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --output-version <snapshot> --repo-slice 2/3 --only-stages clone,code,commits,issues,pulls,branches
conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --output-version <snapshot> --repo-slice 3/3 --only-stages clone,code,commits,issues,pulls,branches

协作建议：

  • 先用同一个 --output-version <snapshot> 做一次 --discover-only
  • 再由一个 worker 单独执行一次 --only-stages manual
  • 之后各 worker 使用不同的 --repo-slice N/M 跑互不重叠的仓库分片
  • 不要让多个 worker 处理同一个 repo-slice

如果你是多台服务器各自运行、最后再汇聚，更推荐冻结发现结果并使用 job YAML：

conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --discover-only --output-version <snapshot>

conda run -n dev-py311 python scripts/build_corpus.py --job-file docs/corpus-jobs.example.yaml --job import-discovery
conda run -n dev-py311 python scripts/build_corpus.py --job-file docs/corpus-jobs.example.yaml --job manual-init
conda run -n dev-py311 python scripts/build_corpus.py --job-file docs/corpus-jobs.example.yaml --job worker-1

推荐分工方式：

  • 协调者先产出一份冻结的 discovered_repos.json
  • 各服务器拿同一份 discovered_repos.json 和同一份 job YAML
  • 每台服务器只执行自己的 job
  • 最后把各服务器的 data/raw/<snapshot>/status/repos/、data/raw/<snapshot>/api/、data/raw/<snapshot>/docs/、data/raw/<snapshot>/toolkit/、data/normalized/<snapshot>/repos/ 汇聚到同一个目录
  • 汇聚后执行 conda run -n dev-py311 python scripts/rebuild_snapshot_metadata.py --config config.yaml --output-version <snapshot> --discovered-repos-file <frozen-discovery-file> 重建 summary.json、live.md、manifest.json 和索引

如果需要关闭当前终端/IDE，可以改用脱离会话的后台方式：

mkdir -p logs
nohup bash -lc 'source ~/.bashrc && exec conda run -n dev-py311 python scripts/build_corpus.py --config config.yaml --output-version <snapshot>' > logs/corpus-<snapshot>.log 2>&1 < /dev/null &

补充说明：

  • logs/ 仅用于本地后台运行时保存标准输出/错误输出，不属于语料数据产物，默认应忽略版本控制
  • 真正的运行进度与恢复状态以 data/raw/<snapshot>/status/live.md 和 data/raw/<snapshot>/status/summary.json 为准

6. 统计与分析

conda run -n dev-py311 python scripts/stats.py data/normalized/<snapshot>
conda run -n dev-py311 python scripts/analyze_corpus.py data/normalized/<snapshot>

当前输出说明

发现结果：

  • data/raw/<snapshot>/discovery/discovered_repos.json

原始 API：

  • data/raw/<snapshot>/api/...

结构化语料：

  • data/normalized/<snapshot>/repos/<platform>/<owner>/<repo>/<type>/part-00000.jsonl

增量索引：

  • data/normalized/<snapshot>/manifest.json
  • data/normalized/<snapshot>/index/repos.json
  • data/normalized/<snapshot>/index/shards.json

分析结果：

  • data/normalized/<snapshot>/index/analysis.json
  • data/normalized/<snapshot>/index/analysis.md

当前主要数据来源

主发现来源包括：

  • GitCode 组织：cann、Ascend、mindspore
  • Gitee 组织：ascend
  • GitHub 组织：Ascend、Huawei-Ascend、Ascend-Huawei

当前默认策略是：

  • 对 cann、Ascend、mindspore 三个 GitCode org 做整 org 枚举
  • GitCode 作为主来源
  • GitHub 主要补 GitCode 未收录的仓
  • Gitee 主要补 GitCode 和 GitHub 都未收录的仓
  • 同时保留 seed_repos 作为强优先级核心仓名单

当前核心种子中包含：

  • cann/ops-nn
  • cann/ops-math
  • cann/ops-cv
  • cann/ops-transformer
  • cann/runtime
  • cann/pyasc
  • cann/pto-isa
  • cann/hccl
  • cann/hcomm
  • mindspore/mindspore
  • mindspore/akg
  • Ascend/pytorch
  • Ascend/docs
  • mindspore-ai/graphengine
  • nndeploy/nndeploy
  • vllm-project/vllm-ascend

更完整的路线与来源说明见：

  • sources/ascend_language_sources.yaml

配置入口

主配置文件是 config.yaml。

最重要的配置段：

  • tokens: 三个平台的 token
  • seed_orgs: 初始组织枚举
  • seed_repos: 必须纳入发现流程的核心仓，并且严格按配置顺序优先处理
  • search_keywords: GitHub 搜索补仓关键词
  • discovery: 平台优先级与跨平台镜像折叠规则
  • repo_cache_dir: 顶层本地 clone 缓存目录
  • raw: data/raw 输出结构
  • output: data/normalized 输出结构
  • filters: 文件过滤规则
  • clone: Git 抓取策略
  • runtime: 并发、超时、重试

关键脚本

  • scripts/build_corpus.py

    • 主入口
    • 支持 --discover-only
    • 支持 --repo-limit
    • 支持 --output-version

  • scripts/stats.py

    • 生成基础统计

  • scripts/analyze_corpus.py

    • 生成详细分析与逐仓说明

  • scripts/show_run_status.py

    • 输出当前 snapshot 的实时任务状态摘要

  • scripts/reorganize_repo_cache.py

    • 把历史 clone 目录迁移到正式的 repos/<platform>/<bucket>/<repo_key>/ 布局

运行时你最常检查的文件

看发现阶段：

  • data/raw/<snapshot>/discovery/discovered_repos.json

看写盘进度：

  • data/normalized/<snapshot>/manifest.json

看实时任务状态：

  • data/raw/<snapshot>/status/live.md
  • data/raw/<snapshot>/status/summary.json

看哪些仓已经真正写出：

  • data/normalized/<snapshot>/index/repos.json

看 shard 分片：

  • data/normalized/<snapshot>/index/shards.json

当前边界

  • GitHub 的搜索补仓能力目前强于 GitCode / Gitee
  • pull_request 现在会保留讨论、元数据和完整 patch；但 fork PR 的 patch 仍可能受平台可见性影响
  • commit 现在会保留 message、统计摘要和完整 patch，体积会明显增大
  • 当前默认不做训练前去重
  • 当前未做许可证白名单裁剪

建议阅读顺序

如果你第一次接手这个项目，建议按下面顺序看：

  1. 本 README.md
  2. docs/runbook.md
  3. config.yaml
  4. sources/ascend_language_sources.yaml
  5. docs/schema-gap-analysis.md

备注

如果你要看“具体在 shell 里一条一条怎么执行、每步预期输出是什么、失败时怎么排查”，请直接看：

  • docs/runbook.md

那里已经是终端逐步实操手册，不再在 README.md 重复展开。 其中命令示例默认按 bash 写，同时关键流程也给了可直接复制的 zsh 版本。

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages