OpenJarvis Pearl 工具链解析：从 Hugging Face safetensors 到 Pearl 量化检查点的本地转换

【免费下载链接】OpenJarvisPersonal AI, On Personal Devices项目地址https://gitcode.com/gh_mirrors/op/OpenJarvis点击查看免费下载Pearl Toolingscripts/pearl/README.md是 OpenJarvis 中一组独立于运行时、面向模型 enablement 与验证的 Pearl 生态工具其核心是model_converter.py——一个把原始 Hugging Face safetensors 权重转换为 Pearl vLLM 插件可消费的量化暂存检查点的实验性脚本。本文围绕该目录的定位、转换脚本的量化策略、配置文件与命令行用法展开并结合仓库源码与测试用例说明如何在本地把原始模型加工成 Pearl 兼容的 staging artifact以及它与src/openjarvis/mining/运行时提供方之间的边界。Pearl Tooling 目录的定位与设计边界在 OpenJarvis 仓库中scripts/pearl/被明确界定为独立于 OpenJarvis 运行时的 Pearl 生态工具。这份定位意味着该目录内的脚本满足两个约束服务于模型 enablement 或验证阶段而不是作为守护进程、挖矿循环等运行时组件被自动加载由开发者手动显式运行是操作性工具operational tools不是面向最终用户的功能入口。该目录在架构上承担的是开发期工具角色与之相对的运行时代码路径在文档中被明确划界面向用户的挖矿命令user-facing mining commands位于 src/openjarvis/cli/挖矿运行时提供方runtime provider code位于 src/openjarvis/mining/scripts/pearl/只保留需要开发者手工触发的转换、验证类脚本。也就是说一个完整的 Pearl 挖矿能力由三层拼成CLI 命令层jarvis mine、jarvis pearl、运行时提供方层VllmPearlProvider等见 src/openjarvis/mining/vllm_pearl.py以及本目录提供的模型加工工具层。model_converter.py属于第三层它的产出是实验性 Pearl 兼容暂存检查点而非已通过的验证模型。model_converter.py脚本能做什么不能做什么model_converter.pyscripts/pearl/model_converter.py是一个约 360 行的独立 Python 工具其文档字符串docstring对该工具的职责与边界做了严格声明它做什么把原始 Hugging Face safetensors 检查点转换为 Pearl vLLM 插件所需的量化形态对挖矿层mining layers输出 int7 通道级channel-wise权重对非挖矿层non-mining layers输出 int8 通道级权重写入动态的、按 token 粒度对称的激活量化元数据dynamic token-wise symmetric activation metadata。它不做什么intentionally conservative不向 Hugging Face 上传任何产物不把任何模型标记为已验证validated目标收敛于 Gemma4/Qwen3.5 的 enablement 工作因此行为刻意保守。这个边界与 docs/development/pearl-model-enablement.md 中的模型 enablement 流程一致转换器产出的 staging artifact 必须继续经过jarvis mine inspect-model与jarvis mine validate-model在 H100/H200 硬件上验证通过后才能被提升为validated状态。为了方便从scripts/mining/一侧引用仓库还提供了一个兼容包装器 scripts/mining/pearl_model_converter.py它通过runpy.run_path直接执行scripts/pearl/model_converter.py实现逻辑单一来源、不复制代码。权重分类哪些层被量化、哪些层被跳过转换的核心逻辑是classify_weight(name, tensor)scripts/pearl/model_converter.py它把 safetensors 里的每个张量分为三类copied原样复制、miningint7 量化、non_miningint8 量化。分类规则由三个正则表达式决定正则匹配目标分类结果NON_MINING_REself_attn.(q_proj\|k_proj\|v_proj\|qkv_proj).weight、mlp.down_proj.weightnon_mining→ int8IGNORED_TEXT_REembed_tokens、embed_tokens_per_layer、lm_head、各类norm/layernorm的.weightcopied→ 原样保留IGNORED_MULTIMODAL_REmodel.vision/model.audio/embed_vision、vision_tower、vision_model、visual、audio等copied→ 原样保留此外任何不以.weight结尾或不是 2 维ndim ! 2的张量也一律归为copied。这保证了 embedding、LayerNorm、lm_head 以及多模态子模型不进入量化路径保留原始精度——因为 Pearl 的挖矿量化只面向文本侧线性层。分类依据在 tests/pearl/test_model_converter.py 中有明确断言在构造的TinyForCausalLM检查点中q_proj被记为non_mining、o_proj被记为mining而embed_tokens、embed_tokens_per_layer、input_layernorm保持 bfloat16 原样且不生成对应的weight_scale。量化内核对称 per-output-channel int 量化真正执行量化的是quantize_channelwise(weight, *, max_val, device, chunk_rows)scripts/pearl/model_converter.py。它是一个对称的、按输出通道行进行的 int 量化实现要点如下按chunk_rows默认 4096分块处理控制内存峰值每块先转 float32 计算行方向绝对值的最大值scale chunk.abs().amax(dim1, keepdimTrue) / max_val零行全零通道的 scale 被置为 1避免除零量化公式为torch.round(chunk / scale).clamp(-max_val, max_val)输出 int8 张量int7 也以 int8 存储只是值域被 clamp 到 ±63scale 以 bfloat16 保存最终与量化权重一同写入命名为{权重名去掉 .weight}.weight_scale。两个量化档位的max_val由分类决定mining 层为63即 int7 的 ±2⁶−1non-mining 层为127int8 的 ±2⁷−1。测试断言了量化后权重 dtype 为torch.int8且weight_scale形状为(rows, 1)——这正是 Pearl/vLLM 插件按通道反量化的输入格式。quantization_configmixed-precision 的 Pearl 元数据转换完成后脚本会通过patch_config()在输出目录的config.json中注入quantization_config声明量化方式为quant_method: pearl版本0.13.0状态compressed。这份配置scripts/pearl/model_converter.py是 vLLM 插件识别该检查点的关键核心结构如下config_groups.group_0format int-quantized权重为 int8 通道级量化strategy: channel、symmetric: true、observer: minmax输入激活为 int8 动态按 token 量化dynamic: true、strategy: tokentargets用正则锁定self_attn的 q/k/v/qkv_proj 与down_proj——对应非挖矿层config_groups.group_1format int-quantized权重为 int7 通道级量化num_bits: 7输入激活为 int7 动态按 token 量化targets为[Linear]——兜底覆盖其余文本线性层即挖矿层ignore列表以正则排除lm_head、embed_tokens、embed_tokens_per_layer、vision*、visual*、vision_tower、image*、audio*、embed_vision、multi_modal_projector等与classify_weight中的IGNORED_TEXT_RE/IGNORED_MULTIMODAL_RE一一对应kv_cache_scheme: None、sparsity_config: {}、transform_config: {}、global_compression_ratio: None表示仅做 weightactivation 量化不做 KV cache 量化和稀疏化。测试同样验证了这份配置的关键字段quant_method pearl、group_1.weights.num_bits 7以及 ignore 列表包含re:.*visual.*与re:.*embed_tokens_per_layer$。元数据与多模态兼容Gemma4 的 preprocessor 处理除权重转换外脚本还处理两件容易被忽略的元数据工作copy_metadata_files()把源目录下所有非.safetensors文件*.json、*.jinja、*.txt、*.model、.gitattributes等原样复制到输出目录保证 tokenizer、processor、generation 配置等随检查点一起分发patch_processor_metadata()针对 Gemma4 架构architectures中含Gemma4的模型做 vLLM profiler 兼容处理——如果输出目录存在processor_config.json但缺少preprocessor_config.json则复制一份同名文件。原因在 docs/development/pearl-model-enablement.md 中有说明vLLM 的 Gemma4 多模态 profiler 需要这部分处理器元数据。该行为有独立测试用例覆盖tests/pearl/test_model_converter.py。转换完成后脚本还会写出model.safetensors.index.json含total_size与排序后的weight_map这是多分片 safetensors 模型被 vLLM 正确加载所必需的索引文件。命令行用法与完整转换流程脚本入口是标准的argparseCLI核心参数如下参数说明默认值source位置参数本地模型目录或 Hugging Face 模型 id必填output_dir位置参数输出检查点目录必填--hf-token-env读取 Hugging Face token 的环境变量名HF_TOKEN--device量化计算设备cpu可指定cuda--chunk-rows通道量化分块行数控制内存峰值4096--dry-run只做分类统计、不写任何检查点falsesource解析逻辑resolve_source()很实用如果参数是已存在的本地路径则直接使用否则走huggingface_hub.snapshot_download下载快照且只拉取*.json、*.jinja、*.txt、*.model、*.safetensors、.gitattributes这几类文件token 通过--hf-token-env指定的环境变量提供默认HF_TOKEN因此可以转换 gated 模型。一个典型的转换命令同样出现在 docs/development/pearl-model-enablement.md 的 enablement 清单中python scripts/pearl/model_converter.py \ meta-llama/Llama-3.1-8B-Instruct \ /tmp/pearl-ai-Llama-3.1-8B-Instruct-pearl \ --device cuda在正式执行前建议先跑一遍--dry-run做分类审计确认 mining/non-mining 层的划分符合预期、不会产生误伤python scripts/pearl/model_converter.py \ meta-llama/Llama-3.1-8B-Instruct \ /tmp/pearl-ai-Llama-3.1-8B-Instruct-pearl \ --device cuda --dry-run--dry-run下每个.safetensors文件都会打印copied... mining... non_mining...三类计数最后汇总total: copied... mining... non_mining...并提示dry run only; no checkpoint was written。转换器对每个 safetensors 分片都输出进度统计整个流程的产出物包括量化后的.safetensors分片 每个量化权重对应的*_weight_scale张量注入quantization_config的config.json完整复制过来的 tokenizer/processor 等元数据文件Gemma4 额外生成preprocessor_config.jsonmodel.safetensors.index.json索引文件。从 staging artifact 到可挖矿模型必须强调的是转换器的输出只是staging artifact不是可对外宣称的验证模型。OpenJarvis 只支持pearl-aiHugging Face 组织发布的 Pearl 模型作为面向用户的挖矿模型见 docs/development/pearl-model-enablement.md 的 Supported Models 列表本地转换产物的完整路径是用jarvis mine inspect-model --model /tmp/pearl-ai-...-pearl检查本地 staging 检查点用jarvis mine init --provider vllm-pearl --model pearl-ai 模型 id --local-model-path 本地检查点目录 --vllm-arg--language-model-only --vllm-arg--skip-mm-profiling配置 Docker 挖矿jarvis mine start启动并经过 vLLM 加载、NoisyGEMM 提交候选证明、gateway 指标等验收标准见 docs/development/pearl-model-enablement.md 的 Acceptance Criteria后模型才可能在注册表src/openjarvis/mining/_models.py中从planned提升为validated。也就是说model_converter.py解决的是怎么把原始权重变成 Pearl 插件认识的形态而这个模型能不能正式开放挖矿由 docs/development/pearl-model-enablement.md 定义的多阶段验证流程说了算。这也正是scripts/pearl/作为enablement 或验证阶段工具的存在意义它把最繁琐的量化与元数据加工自动化让模型启用工作聚焦在真正需要硬件验证的环节上。小结scripts/pearl/目录是 OpenJarvis Pearl 挖矿能力链上的加工车间model_converter.py以明确的保守策略把原始 Hugging Face safetensors 检查点转换为 int7/int8 混合精度、带动态 token 级激活量化的 Pearl 兼容 staging artifact并同步处理好 config、元数据、索引与 Gemma4 兼容文件。配合 tests/pearl/test_model_converter.py 的单元测试与 docs/development/pearl-model-enablement.md 的 enablement 流程开发者可以完整复现原始模型 → 本地转换 → 本地 inspect → Docker 挖矿验证的模型启用工作流而不会误把 staging 产物当作已验证的正式发布模型。赞分享【免费下载链接】OpenJarvisPersonal AI, On Personal Devices项目地址https://gitcode.com/gh_mirrors/op/OpenJarvis点击查看免费下载相关推荐OpenJarvis Pearl 模型启用指南从 Hugging Face 原模型到 vLLM 可挖矿 Pearl 模型的完整流程OpenJarvis Pearl 模型启用指南从 Hugging Face 原模型到 vLLM 可挖矿 Pearl 模型的完整流程 导读 本指南基于 docsOpenJarvis 在 Apple Silicon 上挖掘 Pearl 链cpu-pearl 与 apple-mps-pearl 实战指南OpenJarvis 在 Apple Silicon 上挖掘 Pearl 链cpu pearl 与 apple mps pearl 实战指南 OpenJarvOpenJarvis Pearl CLI 集成指南jarvis pearl 原生节点、钱包与 RPC 工具透传实战OpenJarvis Pearl CLI 集成指南 jarvis pearl 原生节点、钱包与 RPC 工具透传实战 jarvis pearl 是 OpenJ上一篇数据库顶会追踪终极指南ccf-deadlines覆盖SIGMOD/VLDB/KDD最新动态下一篇TypeGraphQL订阅消息认证刷新策略无缝续期创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考