README
E
HubError
- ::newHubConfig::new
- ::with_cache_dirHubConfig::with_cache_dir
- ::with_endpointHubConfig::with_endpoint
- ::with_offlineHubConfig::with_offline
- ::with_revisionHubConfig::with_revision
- ::with_subfolderHubConfig::with_subfolder
- ::with_tokenHubConfig::with_token
T
RepoInfo
V
blob_dir
V
copy_stream
V
dataset_info
V
default_cache_dir
V
default_config
V
default_endpoint
V
default_offline
V
dirname
V
download_resumable
V
ensure_cache_tag
V
ensure_dir
V
fetch_revision_info
V
file_size
V
get_follow
V
get_stream_follow
V
hf_hub_download
V
load_default_token
V
matches_glob
V
model_info
V
partial_size
V
path_exists
V
read_refs_file
V
refs_path
V
remove_file
V
rename_checked
V
repo_cache_dir
V
resolve_sha
V
snapshot_dir
V
snapshot_download
V
symlink_checked
V
write_file_checked

modelhub

MoonBit × HuggingFace 生态栈：与 huggingface_hub 兼容的 Hub 客户端、张量推理内核、GPT-2 推理与通用 ONNX 图执行器。

huggingface

hub

llm

tensor

transformers

onnx

inference

download

cache

Download zip

Author

QUHONGYE-gif

Version

0.1.0

License

Apache-2.0

Repository

github.com/QUHONGYE-gif/moonkit-modelhub

Last updated

last month

Downloads

#moonkit：MoonBit × HuggingFace 生态栈

用纯 MoonBit 补齐 HuggingFace 生态的关键基础件，让 MoonBit 程序可以完整地「拉模型 → 分词 → 跑推理」。仓库包含四个子包，每一层都有与 Python 生态对照的自动化验证。

子包	定位	状态	验证方式
QUHONGYE-gif/modelhub	HuggingFace Hub 客户端（下载/缓存/认证/离线/镜像）	✅	与 huggingface_hub 1.31 缓存树逐文件 parity（本地 mock + 真实 hf-mirror，含 LFS）
moonkit/nn	张量与推理内核（GEMM/激活/归一化/注意力/KV cache）	✅	numpy golden 逐元素对照
moonkit/transformers	GPT-2 级模型推理（safetensors/前向/生成）	✅	numpy golden + 真实 tiny-random-gpt2 端到端生成
moonkit/onnx	通用 ONNX 图解释执行器（11 算子）	✅	numpy golden + 官方 ONNX backend test 子集

#快速开始

开发环境隔离在 conda 环境 moonbit 中（工具链 + Python 测试依赖）：

conda activate moonbit
moon test --target native      # 全部测试（31 个）
moon test                      # wasm 目标（21 个）

一键体验：

bash scripts/run_examples.sh   # 张量 / ONNX / Hub 三个示例（Hub 用本地 mock）
bash scripts/demo_gpt2.sh      # 端到端：拉模型 → 分词 → 生成 → 解码（需网络）
bash scripts/bench.sh          # 基准（matmul / attention / GPT-2 / ONNX）
python scripts/parity_test.py  # 与 Python huggingface_hub 的 parity 验证

#各子包用法

// 1) 拉模型（HF 兼容缓存）
///|
let config = @modelhub.HubConfig::new("https://hf-mirror.com", "/tmp/hf-cache")

///|
let path = @modelhub.hf_hub_download(
  "openai-community/gpt2", "config.json", config,
)

///|
let snapshot = @modelhub.snapshot_download(
  "sshleifer/tiny-gpt2",
  config,
  None,
  None,
)

// 2) 张量与算子

///|
let y = @nn.Tensor::randn([64, 64], 42UL).matmul(
  @nn.Tensor::randn([64, 64], 7UL),
)

///|
let probs = y.softmax()

// 3) GPT-2 推理（safetensors 权重 + KV cache 生成）

///|
let model = @transformers.Gpt2Model::load(
  cfg,
  @transformers.parse_safetensors(bytes),
)

///|
let text_ids = @transformers.Generator::new(model).generate(prompt_ids, 20, 0.0)

// 4) ONNX 图执行

///|
let graph = @onnx.parse_model(onnx_bytes)

///|
let outputs = @onnx.run_model(graph, inputs)

详见各子包文档：nn、 transformers、onnx、 modelhub 设计。

#验证哲学

这个项目把「可验证」当作第一原则，三层验证都可用脚本复现：

parity：modelhub 在同一个服务端下与 Python huggingface_hub 生成的缓存树逐文件一致（scripts/parity_test.py，支持本地 mock 与真实端点）；
golden：nn / transformers / onnx 的全部算子与语义以 numpy 参考实现生成期望值、逐元素对照（scripts/gen_*_fixture.py）；
官方一致性：ONNX 侧直接跑官方 backend test 用例（tests/fixtures/onnx-backend/）。

#文档索引

docs/plan.md — 生态路线图与阶段划分
docs/design.md — modelhub 与推理内核设计决策
docs/ARCHITECTURE.md — 分层、依赖与验证策略
docs/BENCHMARK.md — 基准数据与说明
docs/SUBMISSION.md — 参赛说明与验收对照
docs/APPLICATION.md — 项目申报书

#许可证

Apache-2.0

HubError

source

pub(all) suberror HubError {
  RevisionNotFound(String)
  EntryNotFound(String)
  GatedRepo(String)
  Offline(String)
  BadStatus(Int, String)
  Parse(String)
  Io(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

impl Show for HubError

HubConfig

source

pub struct HubConfig {
  endpoint : String
  cache_dir : String
  revision : String
  subfolder : String
  token : String?
  offline : Bool
}

HubConfig::new

source

fn HubConfig::new(endpoint : String, cache_dir : String) -> HubConfig

HubConfig::with_cache_dir

source

fn HubConfig::with_cache_dir(self : HubConfig, cache_dir : String) -> HubConfig

HubConfig::with_endpoint

source

fn HubConfig::with_endpoint(self : HubConfig, endpoint : String) -> HubConfig

HubConfig::with_offline

source

fn HubConfig::with_offline(self : HubConfig, offline : Bool) -> HubConfig

HubConfig::with_revision

source

fn HubConfig::with_revision(self : HubConfig, revision : String) -> HubConfig

HubConfig::with_subfolder

source

fn HubConfig::with_subfolder(self : HubConfig, subfolder : String) -> HubConfig

HubConfig::with_token

source

fn HubConfig::with_token(self : HubConfig, token : String) -> HubConfig

RepoInfo

source

pub struct RepoInfo {
  id : String
  sha : String?
  private : Bool
  downloads : Int
  likes : Int
  siblings : Array[String]
} derive(@moonbitlang/core/debug.Debug
Debug)

blob_dir

source

fn blob_dir(cache_root : String, repo_id : String) -> String

内容寻址存储目录：blobs/。

copy_stream

source

async fn copy_stream(client : @moonbitlang/async/http.Client
Client, path : String, offset : Int) -> Unit raise HubError

把 client 的剩余响应体写入 path；offset > 0 时以追加模式续写。中断时保留已写入的部分并抛 Io。

dataset_info

source

async fn dataset_info(repo_id : String, config : HubConfig) -> RepoInfo raise HubError

查询数据集仓库元信息。

default_cache_dir

source

fn default_cache_dir() -> String

默认缓存根目录：HF_HUB_CACHE，否则 ~/.cache/huggingface/hub。

default_config

source

async fn default_config() -> HubConfig

从环境变量组装默认配置。

default_endpoint

source

fn default_endpoint() -> String

默认端点：HF_ENDPOINT 环境变量，否则官方地址。

default_offline

source

fn default_offline() -> Bool

离线模式默认值：HF_HUB_OFFLINE ∈ {1,true,TRUE,yes}。

dirname

source

fn dirname(path : String) -> String

download_resumable

source

async fn download_resumable(url : String, token : String?, cache_root : String, repo_id : String) -> String raise HubError

下载 url 到 blobs 目录：探测 etag，流式写入 blobs/.incomplete，支持断点续传（Range），完成后重命名为 blobs/，返回 etag。

ensure_cache_tag

source

async fn ensure_cache_tag(cache_root : String) -> Unit raise HubError

写入缓存根目录标记文件（内容与 huggingface_hub 一致），幂等。

ensure_dir

source

async fn ensure_dir(path : String) -> Unit raise HubError

fetch_revision_info

source

async fn fetch_revision_info(endpoint : String, repo_id : String, revision : String, token : String?) -> (String, Array[String]) raise HubError

请求 revision 信息：commit sha 与文件列表（siblings）。

file_size

source

async fn file_size(path : String) -> Int raise HubError

get_follow

source

async fn get_follow(url : String, headers : Map[@moonbitlang/async/http.CaseInsensitiveString
CaseInsensitiveString, String], max_redirects : Int) -> (Int, Map[@moonbitlang/async/http.CaseInsensitiveString
CaseInsensitiveString, String], Bytes) raise HubError

发起 GET 并手动跟随重定向，返回最终状态码、响应头与响应体字节。

get_stream_follow

source

async fn get_stream_follow(url : String, headers : Map[@moonbitlang/async/http.CaseInsensitiveString
CaseInsensitiveString, String], max_redirects : Int) -> (Int, String?, @moonbitlang/async/http.Client
Client) raise HubError

与 get_follow 相同，但流式读取响应体：返回状态码、重定向链上首个 linked etag（优先 x-linked-etag，其次 etag）与客户端 reader。

hf_hub_download

source

async fn hf_hub_download(repo_id : String, filename : String, config : HubConfig) -> String raise HubError

下载 repo 中的单个文件到 HF 兼容缓存，返回快照目录中的本地文件路径。缓存命中时不做任何网络请求。

load_default_token

source

async fn load_default_token() -> String?

认证 token 默认值：HF_TOKEN → HUGGING_FACE_HUB_TOKEN → token 文件。

matches_glob

source

fn matches_glob(filename : String, pattern : String) -> Bool

glob 风格匹配（* / ?），整串匹配。

model_info

source

async fn model_info(repo_id : String, config : HubConfig) -> RepoInfo raise HubError

查询模型仓库元信息。

partial_size

source

async fn partial_size(path : String) -> Int raise HubError

path_exists

source

async fn path_exists(path : String) -> Bool raise HubError

read_refs_file

source

async fn read_refs_file(path : String) -> String? raise HubError

refs_path

source

fn refs_path(cache_root : String, repo_id : String, revision : String) -> String

revision -> commit 映射文件：refs/。

remove_file

source

async fn remove_file(path : String) -> Unit raise HubError

rename_checked

source

async fn rename_checked(old : String, new : String) -> Unit raise HubError

repo_cache_dir

source

fn repo_cache_dir(cache_root : String, repo_id : String) -> String

仓库在缓存中的目录名：models--，斜杠替换为双连字符。

resolve_sha

source

async fn resolve_sha(endpoint : String, repo_id : String, revision : String, cache_dir : String, token : String?, offline : Bool) -> String raise HubError

解析 revision 为 commit sha：优先读本地 refs 文件（零网络），否则请求远端 API 并写回 refs。

snapshot_dir

source

fn snapshot_dir(cache_root : String, repo_id : String, commit_sha : String) -> String

快照目录：snapshots/。

snapshot_download

source

async fn snapshot_download(repo_id : String, config : HubConfig, allow_patterns : Array[String]?, ignore_patterns : Array[String]?) -> String raise HubError

下载整个模型快照到 HF 兼容缓存，返回快照目录。离线模式下暂不支持（需要远端 siblings 列表）。

symlink_checked

source

async fn symlink_checked(target : String, link : String) -> Unit raise HubError

创建符号链接，底层 IO 错误统一映射为 HubError::Io。

write_file_checked

source

async fn write_file_checked(path : String, content : &@moonbitlang/async/io.Data
Data) -> Unit raise HubError

写文件，底层 IO 错误统一映射为 HubError::Io。

Source Files

Site source Report issue Packages Build queue Skills Statistics

modelhub

#moonkit：MoonBit × HuggingFace 生态栈

#快速开始

#各子包用法

#验证哲学

#文档索引

#许可证

#HubError

#HubConfig

#HubConfig::new

#HubConfig::with_cache_dir

#HubConfig::with_endpoint

#HubConfig::with_offline

#HubConfig::with_revision

#HubConfig::with_subfolder

#HubConfig::with_token

#RepoInfo

#blob_dir

#copy_stream

#dataset_info

#default_cache_dir

#default_config

#default_endpoint

#default_offline

#dirname

#download_resumable

#ensure_cache_tag

#ensure_dir

#fetch_revision_info

#file_size

#get_follow

#get_stream_follow

#hf_hub_download

#load_default_token

#matches_glob

#model_info

#partial_size

#path_exists

#read_refs_file

#refs_path

#remove_file

#rename_checked

#repo_cache_dir

#resolve_sha

#snapshot_dir

#snapshot_download

#symlink_checked

#write_file_checked

Source Files

HubError

HubConfig

HubConfig::new

HubConfig::with_cache_dir

HubConfig::with_endpoint

HubConfig::with_offline

HubConfig::with_revision

HubConfig::with_subfolder

HubConfig::with_token

RepoInfo

blob_dir

copy_stream

dataset_info

default_cache_dir

default_config

default_endpoint

default_offline

dirname

download_resumable

ensure_cache_tag

ensure_dir

fetch_revision_info

file_size

get_follow

get_stream_follow

hf_hub_download

load_default_token

matches_glob

model_info

partial_size

path_exists

read_refs_file

refs_path

remove_file

rename_checked

repo_cache_dir

resolve_sha

snapshot_dir

snapshot_download

symlink_checked

write_file_checked