# 明格拉科研开发工具

Python 3.10+。Windows 可用 py 替代 python；Mac/Linux 使用自己的 Python 环境。CLI/Notebook 仅使用标准库。节点执行器需要 psutil，训练项目需要匹配设备的 PyTorch 和 NumPy。解压后直接运行，不需要发布到 PyPI。

## 首次运行

在解压目录：

    python mingora.py login --identifier 你的明格拉用户名
    python mingora.py init my-project --template summary
    python mingora.py submit my-project --key 自己保留的唯一提交编号
    python -m pip install psutil
    python mingora_worker.py --root ./mingora-work --allow-own-code

提交返回 job_ 任务编号。另一个终端：

    python mingora.py status 任务编号
    python mingora.py logs 任务编号
    python mingora.py wait 任务编号
    python mingora.py download 任务编号 --output ./outputs

登录要求密码，仅用于现有账户登录，随后换取 24 小时授权。配置文件 ~/.mingora-research.json 保存限定权限短期 token，Unix 权限 600；请勿上传该文件。网页“本地开发工具”可以撤回授权。账户通过明格拉登录页创建。平台只接受 HTTPS，localhost 测试允许 HTTP。

## 代码、模型、数据

项目包含相对路径文件清单、参数数组命令和 job.json。默认排除 .git、.local、.env*、虚拟环境、凭据/密钥、results 与临时文件；可添加 .mingoraignore。拒绝符号链接。CLI 不上传 job.json 本身，按清单上传各输入。模型权重可作为项目文件，model 字段说明固定版本、格式与许可，不由平台猜测版本。

客户端流式 SHA256、按后端分片上传、续传、去重。执行器和下载工具重算完整 SHA256；平台核对分片摘要。不能改变已有分片；任务编号冻结输入对象。网络中断后用相同 --key 重提原任务，不能更换该编号内容。

普通私有预览沿用 SQLite，单文件 8 MiB，账户总量 64 MiB。本轮 R2 仅供服务端明确指定的内部合成验收账户试验，普通客户不会自动切入试验桶。内部对象记录固定试验标记，使用 8 MiB 分片、单文件 128 MiB；累计最多 1 GB、1,000 次 Class A、10,000 次 Class B。超过上限拒绝该内部试验操作，不阻止普通客户原有任务、成果保存或读取已有无试验标记的 R2 文件。客户端不能声明试验身份或修改对象标记。删除不返还本轮预算，此计数不是全账户账单。面向普通客户的大模型文件上传仍需完成正式存储容量、成本和接线验收。上传和梯度通道目前经过 Worker；高吞吐大模型数据面还需要私有对象存储/就近节点或直接对象存储策略。

## 协作训练

    python mingora.py init training-project --template gradient_sharded

启动两个本人执行器，可在两台机器分别运行，使用相同账户各自短期授权：

    python mingora_worker.py --root ./node-work --allow-own-code --name 我的节点

节点一次执行一个 rank；先预留全部 rank，校验输入一致、全部就绪才执行。租约、尝试编号、轮次和样本权重防止旧回执混入。缺节点等待，掉线使全组失败；可取消，心跳终止进程组。执行器用 psutil 监测内存和 CPU 时间，native 模式使用当前用户权限，CPU 核数属于预算声明，不能视为严格 OS 限制。原生执行器只接受同一账户自己的代码，不运行公共市场陌生人代码。

gradient_sharded 使用真实 autograd float32 梯度，执行节点按样本数加权聚合，SGD momentum 0.9 状态按分片归属。所有 rank 保留参数，平台不计算张量。未参与本轮的参数、混合精度或复杂优化器需使用自己的 DDP/FSDP 配方。模型 buffer 按 rank 保存，不自动同步 BatchNorm。每轮参数摘要必须一致。检查点保存参数、buffer、所属优化器、Python/NumPy/Torch/可用加速器随机状态。

恢复：相同项目 job.json 增加 resumeFrom 原编号，增加 training.steps 后提交。输入、算法、seed、learningRate、分片和节点布局须相同。只允许完整组检查点。产出 results/training.json、检查点、真实日志；各 rank 本地 loss 可因样本划分不同而不同。

## 高速网络：DDP、FSDP、模型流水线

    python mingora.py init cluster-project --template data_parallel
    python mingora.py init fsdp-project --template fsdp
    python mingora.py init pipeline-project --template pipeline
    python mingora.py init pipeline-training --template pipeline_train

修改 resources.networkGroup 和 rendezvous.host 为实际互通地址。127.0.0.1 仅同机双进程可用，两台机器不可使用 loopback 作为相互地址。

    python mingora_worker.py --root ./work --allow-own-code --network-group 你的网络组 --allow-cluster-network

CPU 使用 Gloo，CUDA 使用 NCCL。FSDP FULL_SHARD 使用真正 PyTorch 参数/梯度/优化器分片，要求 CUDA；无 CUDA 不降级标成功。同名网络组仅准入声明，不证明带宽、延迟或防火墙合格。FSDP 无真实双 CUDA 设备保持待实测。

mingora_torch.wrap、checkpoint、restore_from_job 提供 DDP/FSDP 接入和 PyTorch DCP 文件检查点；随机状态逐 rank 保存。pipeline_forward 为层分片推理，pipeline_train_step 为显式形状同步前向、反向、逐层优化器更新，当前串行同步，尚非微批次吞吐优化。pipeline_checkpoint / restore_pipeline 保存并恢复各层模型、优化器、随机状态；恢复后从完整组步数继续。张量只在互通节点传送，不由 Cloudflare 计算。

多 GPU 机器可以为各执行器指定 --gpu-index 0、--gpu-index 1。平台按机器与 GPU 标识核算资源，避免重复启动占用同一 GPU；这是客户端报告的保护，不是独立硬件认证。job.json 的 environment 可固定镜像摘要或环境指纹，不匹配的节点不会获得该任务。

## 容器环境

已安装 Docker 可用 --docker-image repository@sha256:固定摘要，JobSpec runtime=docker。只读容器根、独立项目、默认无网络、丢弃权限、CPU/内存限制。集群联网需 --allow-cluster-network，部署者须审核镜像和实际 Docker GPU 支持。对象梯度运行时未向容器注入平台凭据，该组合拒绝。原生项目代码仍可使用当前用户权限，只有本人私有任务开放。

## Notebook / Python

    from mingora import Client
    import json
    client = Client()
    job = client.submit("./my-project", json.load(open("my-project/job.json")))
    result = client.wait(job["id"])
    client.results(job["id"], "./results-download")

## REST

同源 /api/research/v1，Authorization: Bearer 现有账户签发的短期授权，权限 research:read / research:write / research:work。网页登录也可操作本人资源。按租户和账户检查，客户端不能指定其他 tenant。

GET /policy、/objects、/jobs、/nodes；POST /objects 建上传，PUT /objects/:id/parts/:index 附 X-Content-SHA256，POST /objects/:id/complete；POST /jobs 附稳定 Idempotency-Key；GET /jobs/:id、/jobs/:id/events?after=序号；POST /jobs/:id/cancel；POST /nodes 登记、/nodes/:id/claim、ready、heartbeat、report、round、checkpoint、pause。round 包含 gradients/reduced/applied 与 committed 全组屏障；leaseId、attempt 需匹配。

## 服务端与成本

现有 Cloudflare 平台鉴权，独立 ResearchCoordinator SQLite Durable Object 处理每租户科研作业、调度和轮次；文件不写入账户/余额账本。BlobStore 支持独立 SQLite 小文件和 R2 multipart。CPU/GPU/模型、梯度聚合、优化器、进程通信发生在节点。平台模型费 ¥0，用量由节点报告，未独立核验、不形成真实人民币结算。

此版提供私有项目提交与协作运行链路。跨账户任意代码租赁、独立硬件认证、跨公网高速张量网络、真实大模型质量和商业结算尚未验收，不能宣称数亿设备训练或 GPT 等价。生产、实际多设备和 CUDA/FSDP 验证分别记录。


当前私有预览每账户最多 1000 个文件/任务、200 个执行器登记；梯度和检查点也占文件配额。长训练须先接通容量及清理策略，不能把小文件预览作为无限规模服务。

项目支持空的 __init__.py 和空成果文件。梯度训练示例可把自己的 PyTorch state_dict 保存为 weights.pt 随项目上传；执行器以 weights_only 模式读取该权重再训练。

开发期遵守平台流控：网页每30秒刷新且隐藏时停止；节点空闲15秒领取、活跃心跳15秒。SDK 每10秒查询任务、每5秒查询梯度屏障，对带明确 Retry-After 的短期限频429退避并保持提交编号，超过60秒的日预算拒绝直接报告；网络写入结果未知时不自动重复。公共梯度通道适合小规模验证，DDP/FSDP的高频张量应在同一高速网络组直接通信。