llmfit Hardware Profile 硬件档案完全指南用一条 --profile 在任意机器上预估模型可运行性与吞吐【免费下载链接】llmfitHundreds of models providers. One command to find what runs on your hardware.项目地址: https://gitcode.com/GitHub_Trending/ll/llmfitllmfit 的 Hardware Profile硬件档案是一个命名且带版本号的 JSON 机器描述文件它刻画一台机器的总内存、内存是否为统一内存unified memory以及吞吐估算器需要的带宽与算力参数。通过--profile传入它所有分析命令就会针对这台目标机器而非你当前所坐的宿主机打分——这正是回答某个模型在这台不存在的机器上跑多快这类问题的官方方案。读完本文你将掌握内置档案的即拿即用、为未发布硬件手写档案的完整流程以及档案字段背后的源码级作用机制。Hardware Profile 面向的应用场景非常具体--memory/--ram/--cpu-cores只能修改容量类字段而 tok/s 吞吐估算依赖的是内存带宽与 fp16 矩阵算力见 llmfit-core/src/fit.rs 中CalcConfig的实现这些都不是容量。当你需要评估在别人的机器或还没上市的硬件上模型表现如何时单个字段覆盖无法给出可信答案一份描述整台机器的档案才是可复现、可评审的方案。数据文件与完整字段契约位于 llmfit-core/data/hardware/面向用户的完整操作教程见 docs/cli.md → Hardware profiles。快速上手三条命令体验硬件档案最直接的体验方式就是调用内置档案。llmfit hardware子命令组负责档案的查看与管理--profile让所有分析命令改用指定机器打分llmfit hardware list llmfit hardware show ryzen-ai-max-plus-395 llmfit --profile ryzen-ai-max-plus-395 fit -n 10 llmfit --profile ryzen-ai-max-plus-395 plan openai/gpt-oss-120b llmfit --profile nvidia-rtx-4090 recommend --json llmfit --profile apple-m3-max-128gb info Qwen/Qwen3-4B-MLX-4bit上面四行llmfit --profile ...分别展示了fit给出一批模型的匹配度排名、plan为单个模型制定运行计划、recommend --json以 JSON 输出推荐与info四种典型用法。--profile同时支持两种传参形式直接写档案名如ryzen-ai-max-plus-395或写一个文件路径如./my-workstation.json后者无需安装任何东西即可临时评测。注意约束--profile会整体替换--memory/--ram/--cpu-cores三个参数并与三者互斥profile 描述的是整台机器而这三个参数只覆盖单个字段无法解析的 profile 属于硬错误而不是被静默忽略。目录布局schema 与 profile 文件的存放约定llmfit-core/data/hardware/ schema.json JSON Schemadraft-07每个 profile 必须满足 name.json 一个 profilename 必须等于文件名去掉 .json 后缀本目录下每个.json文件即一份 profile其name字段必须与文件主干名完全一致——llmfit-core/src/hwprofile.rs中的check_name_matches_stem见 hwprofile.rs会强制这一约束因为一个列在列表里的名字却无法被选中是典型事故源。一个关键设计是这些档案的分发机制目录下所有 profile 由 llmfit-core/build.rs 在编译期聚合embed_hardware_profiles()读取data/hardware下全部 JSON 并拼接成单个数组经include_str!嵌入二进制见 hwprofile.rs。因此一份合并进仓库的档案会随下一个 release直接内置分发按名字使用、无需任何下载用户不需要重新编译只需把档案文件放进llmfit hardware path打印出的目录即可加载。llmfit hardware path # 例如 Linux 下 ~/.local/share/llmfit/hardware # 可用环境变量覆盖LLMFIT_HARDWARE_PROFILES/tmp/my-hw优先级规则清晰可测用户目录中name与内置档案同名的用户档案优先shadow 机制见下文源码解析LLMFIT_HARDWARE_PROFILES环境变量则用于整体改指向用户档案目录其实现位于 hwprofile.rs 的user_profile_dir()——读取该变量为空时才回退到 llmfit 的更新缓存目录下的hardware子目录。字段说明schema_version 1 的全部字段与作用对象llmfit-core/data/hardware/schema.json 是每个档案必须满足的权威契约且additionalProperties: false即验证阶段拒绝一切未声明键。各字段含义如下字段是否必填作用对象schema_version是必须为1name是必须等于文件主干名符合[a-z0-9][a-z0-9._-]*match.gpu_name_contains否仅作溯源用 —— llmfit 永远不会自动选择 profilehardware.total_ram_gb是SystemSpecs容量统一内存时同时充当 VRAMhardware.unified_memory是SystemSpecs::unified_memoryhardware.gpu_memory_bandwidth_gbps否CalcConfig::gpu_bandwidth_gbps_overridehardware.ddr_bandwidth_gbps否CalcConfig::ddr_bandwidth_gbpshardware.gpu_compute_tflops_fp16否CalcConfig::gpu_compute_tflops_fp16prefill/TTFT 阶段estimation.efficiency否CalcConfig::efficiencyestimation.run_mode_factors.*否CalcConfig::run_mode_factors按模式生效未设的键保持默认值calibration[]否在schema_version1 中仅被解析并校验尚未参与计算几点值得展开match字段是纯溯源性质这份档案描述哪张 GPU代码注释明确说明profile 永远不会被自动选中因此错误的猜测不会悄悄替换掉正确的本机检测见 hwprofile.rs。用户必须显式--profile才会生效。calibration用于记录带来源的实测锚点哪个模型、什么量化、什么运行模式、实测多少 tok/s、来源链接让它们现在可以被评审、未来可被更高 schema 版本消费。它今天不改变任何估算——实测锚点一旦应用会改变该机器上的每一项估算所以先以可评审的数据形式随档案发布。离散 GPU 档案不携带 VRAM 数值因此 VRAM 保持宿主机检测值不变统一内存档案则是完整描述VRAM 跟随total_ram_gb两者本就是一个池子。范围约束在源码validate()中统一用check_range执行见 hwprofile.rstotal_ram_gb上限 16384 GB、带宽与 TFLOPS 上限 100000、efficiency上限 1、run_mode_factors各键上限 10且所有数值必须是大于 0 的有限数。注释特别指出边界故意放宽——目的是拒绝会让估算失去意义的取值0 带宽会把 roofline 除以到零、NaN 会污染每个分数而不是去审查硬件是否合理。标准格式一份完整的示例档案每个文件都要符合 schema.json。下面是涵盖全部可选区块的完整示例对应仓库文档中的示例并保留原样语义{ schema_version: 1, name: example-unified-256, match: { gpu_name_contains: Radeon 8060S }, hardware: { total_ram_gb: 128.0, unified_memory: true, gpu_memory_bandwidth_gbps: 256.0, ddr_bandwidth_gbps: 256.0, gpu_compute_tflops_fp16: 29.7 }, estimation: { efficiency: 0.6, run_mode_factors: { cpu_only: 0.25 } }, calibration: [ { model: openai/gpt-oss-120b, quant: MXFP4, run_mode: gpu, measured_tps: 50.0, source: issue #969 } ] }各区块要点hardware.gpu_compute_tflops_fp16决定 prefill / TTFT 估算缺省时 prefill/TTFT 如实报告null而非猜测见 apple-m3-max-128gb.json 的做法。estimation.run_mode_factors的每个键都可选未设置的运行模式沿用RunModeFactors默认值而不会被清零——apply_to_config的测试断言了这一点见 hwprofile.rs。calibration[].run_mode只接受五个枚举值gpu、tensor_parallel、moe_offload、cpu_offload、cpu_only与crate::fit::RunMode的 snake_case 一致非法值会在校验时被拒绝。容错加载与严格校验如何保证拼写错误不会静默失效这是 llmfit 档案机制最具设计巧思的一点加载与校验采用两套标准。加载时容忍未知键parsevalidate一份为更新版本 llmfit 编写的档案在旧版本上依然能加载使用向前兼容。HardwareProfile通过#[serde(flatten)]把不认识的键收进unknown映射而不是报错见 hwprofile.rsloader_tolerates_unknown_keys_but_strict_validation_rejects_them测试验证了future_top_level、hardware.npu_tops这类未来键可以被解析并逐层记录路径见 hwprofile.rs。hardware validate走严格校验validate_strict在validate()之上追加拒绝一切未识别键把 typo 变成可见错误而不是一个悄悄什么都不做的字段llmfit hardware validate ./my-workstation.json # FAIL ./my-workstation.json: unknown key(s): hardware.gpu_bandwith_gbps上面的报错正是拼错bandwidth这一典型场景的反馈。选择器解析规则也值得留意resolve()先判断选择器是否像路径以.json结尾、含路径分隔符、或磁盘上确有此文件三者任一成立即视为路径否则按档案名查找未知名字的报错会列出当前全部可用档案见 hwprofile.rs 及对应测试 resolve_rejects_an_unknown_name_and_lists_alternatives。内置档案一览三个种子档案及其设计含义仓库当前内置三个档案覆盖了三种典型拓扑是学习手写档案的最佳范本名称内存带宽说明ryzen-ai-max-plus-395128 GB 统一内存256 GB/sStrix Halo APU256-bit LPDDR5X-8000。Radeon 8060S40 个 RDNA 3.5 CU ~2.9 GHz → 约 29.7 TFLOP/spacked fp16。apple-m3-max-128gb128 GB 统一内存400 GB/s40 核 GPU 的 M3 Max。fp16 matmul 吞吐刻意留空因此 prefill/TTFT 报告null而不是猜测值。nvidia-rtx-409064 GB 系统内存1008 GB/s离散 Ada 卡165.2 TFLOP/stensor、fp32 累加的 dense fp16。ddr_bandwidth_gbps为双通道 DDR5-5600。它们的 JSON 文件在 llmfit-core/data/hardware/ 下与 README、schema 平级ryzen-ai-max-plus-395.jsonunified_memory: truegpu_compute_tflops_fp16: 29.7并携带一条gpt-oss-120bMXFP4 的实测校准记录measured_tps: 50.0apple-m3-max-128gb.jsontotal_ram_gb: 128.0、带宽 400 GB/s没有gpu_compute_tflops_fp16键——这是缺省即如实报 null的官方示例nvidia-rtx-4090.jsonunified_memory: false、GPU 带宽 1008 GB/s、ddr_bandwidth_gbps: 89.6、算力 165.2 TFLOP/s且不带 VRAM 字段VRAM 保持宿主机检测值。从三种档案可以看出字段与机器拓扑的对应关系统一内存机器APU / Apple Silicon由total_ram_gb同时决定容量与显存池离散 GPU 机器则分离系统内存与 GPU估算 decode 走 GPU 带宽、CPU/offload 路径走ddr_bandwidth_gbps。运行时如何应用档案SystemSpecs 与 CalcConfig 的双轨联动档案在运行时的应用不是一次性赋值而是规格 估算配置双轨同步保证描述整台机器的档案在内部自洽。核心逻辑在HardwareProfile::apply()见 hwprofile.rspub fn apply(self, specs: SystemSpecs, config: mut CalcConfig) - SystemSpecs { self.apply_to_config(config); self.apply_to_specs(specs) }两条轨道的职责分别是apply_to_specs容量侧调用SystemSpecs::with_profile_capacity见 hardware.rs。实现细节里有一个严谨的自洽处理先设置unified_memory再做 RAM 覆盖保证统一内存档案让 VRAM 严格跟随total_ram_gb若统一内存档案作用于一台没检测到 GPU 的主机还会像--memory一样合成一块 GPU否则所有模型都会掉进 CPU-only 路径档案永远无法复现它所命名的机器非统一档案则不携带 VRAM 值保持检测值不动。apply_to_config速度侧逐项把gpu_memory_bandwidth_gbps→CalcConfig::gpu_bandwidth_gbps_override、ddr_bandwidth_gbps→CalcConfig::ddr_bandwidth_gbps、gpu_compute_tflops_fp16→CalcConfig::gpu_compute_tflops_fp16、efficiency与run_mode_factors各自映射到位。未设置的字段保持原样让不完整的档案继续使用计算出的默认值见 hwprofile.rs测试 partial_profile_leaves_estimator_defaults_alone 断言最小档案不会改动任何估算默认值。档案目录的扫描逻辑catalog_in同样值得了解见 hwprofile.rs先装载全部内置档案再扫描用户目录下的.json用户档案会retain掉同名内置档案后插入即同名用户档案替换内置档案而不是并列两份加载失败的文件不会静默跳过而是进入errors列表随目录一起上报——用户写的档案选不中是需要看到的 bug。实战为未发布硬件写一份自己的档案你不必真的拥有那台机器。写一份档案、校验、然后对模型打分即可。以文档中的 M5 Ultra 场景为例第 1 步查看用户档案目录llmfit hardware path # 例如 ~/.local/share/llmfit/hardware # 覆盖方式LLMFIT_HARDWARE_PROFILES/tmp/my-hw第 2 步写档案文件主干名必须等于namemkdir -p $(llmfit hardware path) cat $(llmfit hardware path)/m5ultra512.json EOF { schema_version: 1, name: m5ultra512, match: { gpu_name_contains: M5 Ultra }, hardware: { total_ram_gb: 512.0, unified_memory: true, gpu_memory_bandwidth_gbps: 1200.0, ddr_bandwidth_gbps: 1200.0 } } EOF或者保留一份一次性文件、直接传路径无需任何安装llmfit --profile ./m5ultra512.json fit --json第 3 步校验、列出、检视llmfit hardware validate $(llmfit hardware path)/m5ultra512.json llmfit hardware list llmfit hardware show m5ultra512第 4 步像拥有那台机器一样打分llmfit --profile m5ultra512 fit -n 20 llmfit --profile m5ultra512 plan --quant Q4_K_M openai/gpt-oss-120b llmfit --profile m5ultra512 recommend --json对应字段的影响总结与本文字段表一一对应字段效果total_ram_gb容量unified_memory为 true 时同时充当 VRAMunified_memory统一内存池Apple / APUvs 离散 GPUgpu_memory_bandwidth_gbpsdecode / 估算 tok/sddr_bandwidth_gbpsCPU / offload 路径gpu_compute_tflops_fp16prefill / TTFT缺省 → 如实报null档案管理命令与已知限制档案相关的全部管理命令llmfit hardware list # 内置 用户档案 llmfit hardware list --json llmfit hardware show NAME # 显示字段 在本机应用后会改变什么 llmfit hardware validate file llmfit hardware path已知限制当前实现明确声明calibration[]目前仅存储供评审不参与估算schema v1--profile暂时不能与--force-runtime组合使用doctor命令拒绝--profile它诊断的是当前宿主机这种情况请改用hardware show查看档案应用效果。质量保障CI 级校验如何拦截损坏档案内置档案在编译期被嵌入而加载时无效文件会被直接丢弃——若无测试把关一份格式错误的贡献就会以永远选不中的档案形式发布且构建不报错。仓库为此设置了双重防线集成测试 llmfit-core/tests/hardware_profiles.rs 用 jsonschema 校验器把data/hardware/下每个.json排除 schema 自身逐一对照 schema.json 验证并检查name与文件主干一致cargo test -p llmfit-core会运行这些校验同时在 hwprofile.rs 单元测试层断言embedded()中的内置档案全部通过validate_strict()见 embedded_profiles_are_present_and_valid且覆盖了wrong_schema_version_is_rejected、invalid_names_are_rejected、non_finite_and_out_of_range_numbers_are_rejected、calibration_is_validated_even_though_it_is_not_applied、unified_profile_makes_vram_track_ram_and_synthesizes_a_gpu、discrete_profile_sets_ram_and_leaves_detected_vram等关键行为。因此一份格式错误的档案贡献会在 CI 失败而不是进入发布——社区提交硬件档案的完整闭环为修改data/hardware/→cargo test -p llmfit-core通过 → 合并后经 build.rs 随下一 release 内置分发给所有用户。若想进一步把档案用于完整实操如结合plan与recommend子命令、JSON 输出、TUI 中的估算配置继续阅读 docs/cli.md 中从--memory/--ram/--cpu-cores单字段覆盖到硬件档案的完整链路即可。【免费下载链接】llmfitHundreds of models providers. One command to find what runs on your hardware.项目地址: https://gitcode.com/GitHub_Trending/ll/llmfit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考