Hologram Model Hub

Model Hub

热门开源模型目录，列出每个文件的内容地址，发布于 hologram-technologies.github.io/hologram-live/model-hub/。

每个模型页面都会按地址列出文件，并提供 Verify：浏览器从 Hugging Face 和 ModelScope 获取小文件，并将其哈希值与地址索引进行比对。整个过程不涉及我们的任何服务。将模型拉取到 hologram-live 节点的功能随 Model Hub .holo 应用一同提供（议题 #76，ADR 023 见 #75）。

将它与工具搭配使用：HF_ENDPOINT

export HF_ENDPOINT=https://gethologram.ai
hf download sentence-transformers/all-MiniLM-L6-v2

所有从 Hugging Face 下载内容的工具都会遵循此变量（hf、huggingface_hub、transformers、diffusers、 sentence-transformers、llama.cpp -hf），因此 hub 无需自带客户端。deploy/hub-resolve.mjs 会根据地址索引 以 Hugging Face 的方言响应，并将每个文件请求重定向到最近一次健康探测通过的来源：优先 Hugging Face（其 CDN 速度最快）， 然后是 ModelScope，最后是 IPFS。没有任何模型权重字节会经过 hub。main 是已编入索引的修订版本，因此明天构建时 获取的字节也相同。在路径前加上 /via/ipfs、 /via/modelscope 或 /via/huggingface，即可固定首选来源 （HF_ENDPOINT=https://gethologram.ai/via/ipfs）。每个模型都会生成 …/resolve/main/SHA256SUMS，因此可以使用普通的 sha256sum -c 检查下载内容；客户端自身不会进行验证。

此方言是从客户端记录得出的，而非猜测（web/qa/hf-dialect/recorder.mjs）：模型信息、树列表、 对 resolve 的 HEAD 和 GET 请求，以及 Xet 读取令牌路由。该路由会重定向到 Hugging Face，因为 huggingface_hub 1.32 会在 HEAD 请求中跟随我们的重定向，在那里获取 Hugging Face 的 Xet 标头，再向此端点 请求令牌。用户的 Hugging Face 令牌会发送到 HF_ENDPOINT 指定的任何地址：前置 Caddy 会在服务收到请求前移除 Authorization 和 Cookie，并拒绝受限模型，不会代理这些请求。索引之外的模型会返回一条说明及 404，并记录在 state/resolve/requested.txt 中。

2026-09-18，使用 web/qa/hf-dialect/matrix.sh 在 python:3.12-slim 中针对公共 URL 测得， 测试版本为 huggingface_hub 1.32.0 和 0.36.2：hf download 和 snapshot_download 下载整个模型（30 个文件中 有 30 个与 SHA256SUMS 匹配）、缓存复用、transformers AutoConfig 和 AutoTokenizer、普通 GET 和 Range 请求，以及客户端对未知模型和修订版本返回的自身类型化错误。同日测得的故障转移情况：在客户端容器中屏蔽 huggingface.co、hf.co 和 Hugging Face 的 CDN 主机，并在 hub 上将 Hugging Face 标记为不可用后，hf download 和 snapshot_download 下载整个模型，30 个文件全部匹配，transformers 成功加载；通过 ModelScope 和 IPFS 用时 110 秒。 同时停用 ModelScope 后，仅通过 IPFS 下载同一模型用时 126 秒（记录了 135 次重定向）。第一次尝试在 .gitattributes 处失败：IPFS 归档打包时漏掉了点文件（ipfs-car 会跳过隐藏路径）。 pin-model.sh 现在会将这些文件打包，所有 11 个模型也都重新固定了。请测试整个仓库，而不是单个文件。

Ollama，以及两者背后的设计

ollama pull gethologram.ai/bartowski/MiniCPM5-2B-GGUF:Q4_K_M

同一服务为索引中的每个 GGUF 仓库提供 Ollama 的注册表方言：manifest 的模型层使用索引中 GGUF 文件的 SHA-256，blob 请求会以 307 重定向到可用来源，Ollama 会自行验证摘要。聊天模板和参数取自 Hugging Face 自己的 manifest，只有当它指向的正是索引所标识的字节时才会接受，并且会保存下来，确保 Hugging Face 无法访问时拉取仍然有效（实测：Ollama 0.34.2 拉取、验证并运行了一个模型；屏蔽 Hugging Face 后，同一次拉取从 ModelScope 完成）。 OCI 客户端可通过相同路由获取相同模型，形式为 CNCF ModelPack 工件（oras pull gethologram.ai/hexgrad/kokoro-82m:latest，按 OCI 要求使用小写；实测：72 个文件全部匹配），Agent 则可通过 https://gethologram.ai/mcp 使用三个 MCP 工具。 GET /api/models?search=… 会以 Hugging Face 的格式列出并搜索模型（HfApi.list_models 可用），这也是 Agent 的低成本路径。关于这些方言、研究发现、路径映射以及后续计划，请参阅： docs/one-endpoint.md。

下载

下载会将整个模型保存为一个 .zip 文件，大小不限，可在任何现代浏览器中使用。一个小型 service worker （web/src/zip-sw.js，只处理 zip/…，从不处理页面）会在流式传输时组装压缩包，因此浏览器自带的下载管理器会以真实进度条保存文件，且不会将任何内容保存在内存中：zip 不压缩，因此会在传输第一个字节前声明其确切大小。每个文件经过时都会计算哈希，并与索引中的地址进行比对；字节不匹配会导致下载失败，且不会保留任何内容。每个文件都来自第一个响应的来源（Hugging Face、ModelScope、IPFS）；连接中断后会从已传输到的字节处继续，可使用相同来源或下一个来源；按钮旁的菜单可将 zip 限定为单个来源。每个 zip 都包含：SHA256SUMS（可离线永久使用 sha256sum -c SHA256SUMS 进行检查）和 HOLOGRAM.json（模型、修订版本、索引 manifest、每个文件的提供来源）。zip/<org>/<name>/auto.zip 是链接；它读取的文件列表位于 data/files/<org>/<name>.json。没有 service worker 时，页面会回退到文件选择器流式传输（Chrome、Edge），或使用最多 1.5 GB 内存的 zip。

2026-09-18 实测（web/qa/zip-proof，在 hub 主机上运行 Docker）：生成的 5.9 GB zip 保存时大小与声明完全一致，且文件有效；测试环境包括 Chromium 131（140 秒，浏览器内存从 377 MB 增至 471 MB）、WebKit 18.2（38 秒，从 383 MB 增至 419 MB）和原版 Firefox 156（以 60 MB/s 传输耗时 169 秒，容器内存低于 1 GB）。文件传输过程中切断连接后，下载成功续传并通过验证；故意设置错误地址后，三个浏览器中的下载均失败，磁盘上没有留下任何内容。Playwright 自带的 Firefox 构建版无法用于评估下载：普通的 6 GB 服务器下载也会耗尽其内存。node qa/zip-size.test.mjs 会同时校验声明大小与写入字节数（空文件、UTF-8 文件名、65,536 个条目，以及超过 4 GiB 的文件）。

档案

页眉中的 Index <day> 标签会打开目录采集过的每一天，就像 Wayback Machine 会打开网页的历史版本。选择某一天后，浏览、筛选、搜索和每个模型页面都会切换到当天的索引；标签会变为琥珀色，横幅会显示日期，点击 返回最新版本 即可返回。任何页面上的 ?at=YYYY-MM-DD 都会打开该日期当天或之前最近一次采集的版本，因此，指向某一天的链接会准确对应当天所显示的内容。

每日注册表推送后，deploy/archive.sh 会采集当天内容一次：当天的文件会打包成 CAR（IPFS 归档），其根 CID 在本地计算，再通过 Filebase 固定；只有 Filebase 报告的 CID 与本地计算结果一致时，才会接受该归档。当天记录会追加到账本 archive.json（hologram.model-hub.archive/v1）中；该账本由 gethologram.ai/archive.json 提供服务，也会被固定：

字段	含义
gateway、mirror、registry	每一天的读取位置：在 IPFS 上使用 <gateway><cid>/<path>，在中心注册表上使用 hologram pull <registry>:<date>；仅当天可在中心使用 <mirror><date>/<path>。镜像仅用于加快读取速度，绝不会被信任
days[].date、cid	日期以及该目录的根 CID（包含 index.json、models.json 和每个模型对应的一个 JSON 文件）
days[].index	当天 index.json 的 BLAKE3 哈希；该文件会记录其他所有文件的地址
days[].prev、prev_ledger	前一天的 CID 和前一个账本的 CID：构成哈希链，确保历史记录无法被悄悄改写
days[].models、addressed、files、bytes、source、archived	当天包含的内容及其采集时间

浏览器不会信任任何来源：它会读取 index.json，将其哈希与账本中的 index 对比，然后再将每个文件的哈希与索引记录的地址对比，验证通过后才会显示内容。验证失败的字节会被拒绝，并尝试下一个来源（实测中，损坏的镜像文件被拒绝，随后使用了网关副本）。验证通过的字节会按其内容地址保存在 Cache API 中，因此再次访问某天的内容时会即时加载，也能离线使用。验证和下载仍使用最新索引，因为它们会检查实时镜像。at/<date>.json 存根会为 Agent 提供某天的 CID、索引地址和读取位置。中心的镜像只保存当天内容；注册表会保留每天的标签（其存储也包含中心发布的对象，因此不会重建）；浏览器会从 IPFS 读取过去某天的内容，首次访问时，网关获取文件可能需要一分钟（实测冷启动时每个文件需要 25 到 55 s）。不可变的是采集内容和哈希链。唯一由操作人员负责的是每日写入程序（VPS cron）和单一的固定服务提供商。

构建

just model-hub-site   # catalog snapshot (if missing), token lint, static build → apps/model-hub/web/dist
just model-hub-data   # refresh the catalog snapshot

BASE=/path/ 可用于构建部署在路径下的网站。GitHub Pages 会通过 .github/workflows/release-docs.yml 与文档一同发布：在推送到 apps/model-hub 时、每日生成新快照时，以及手动运行时都会发布。文档本身始终使用最新的 docs-v* 标签构建。

目录由 Hugging Face 的热门列表与 humuhumu33.github.io/hologram-api 上的模型地址索引合并而成（HOLOGRAM_API 可覆盖此地址；HF_TOKEN 可避免速率限制）。

品牌套件

所有颜色、尺寸、间距、圆角和字体均来自 Hologram-Technologies/hologram-brand-kit，并由 web/scripts/vendor-kit.mjs 在 develop 分支的 bce3bdf59 修订版本（Desktop 使用的版本）中引入。三个间距令牌（--success、--success-foreground、--muted-foreground-subtle）来自该套件的开放 PR #1。web/scripts/lint-tokens.mjs 会在产品代码中发现任何字面颜色、尺寸、圆角、字体或内联样式时失败。

页眉

网站的每个页面都使用一个顶级菜单——Models、Registry、Docs，并将当前所在的版块标记为 aria-current，同时以强调色显示。菜单由 web/build.mjs 中的 topNav() 一次性构建，再由每个生成页面都会使用的 header() 渲染。Registry 页面以独立的完整文件形式存放在 web/public/registry/ 中，因此构建会在该文件的两个标记处（, ）插入相同的 header() 输出，而不是再创建一份副本。页面的共享部分——品牌别名、重置样式、外壳、控件、页眉、主题切换和登录——位于 web/src/chrome.css 和 web/src/chrome.js；web/src/styles.css 则包含依赖这些共享部分的页面样式。

npm run menu 会在两种主题和十二种宽度下遍历每种页面布局，并在菜单不一致、版块标记错误或标记的对比度低于 AA 时失败。

布局

路径	内容
web/build.mjs	静态生成器：着陆页、浏览页、每个模型对应的页面、每个 Registry 产物对应的页面，以及共享页眉
web/src/	渲染、客户端代码、样式、生成的品牌令牌；chrome.css + chrome.js 是共享页眉
web/scripts/	data.mjs（目录快照）、registry.mjs（从源 API 获取每条 Registry 记录的配置和徽标）、vendor-kit.mjs、lint-tokens.mjs
web/vendor/hologram-brand-kit/	引入的工具包 CSS、令牌、字体和徽标
web/public/wallpapers/	沉浸式主题壁纸
web/qa/	设计评审期间使用的布局、对比度和动画审查；menu.mjs 用于检查顶级菜单