企业官网建设流程全解析

LocalScore 本地大模型性能基准测试指南：从单文件基准到公测排行榜

【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile

LocalScore 是 llamafile 项目（localscore/ 目录）内置的开源 LLM 基准测试工具，用于量化大语言模型在你具体硬件上的推理速度，并支持把结果匿名提交到公共基准数据库 localscore.ai 供横向对比。阅读本文后，你将掌握 LocalScore 的三项核心指标与评分公式、四种运行方式、全部命令行参数及输出格式，并理解其背后基于 llama.cpp 的计时与采样实现原理。

LocalScore 是什么

LocalScore 是一个开源的本地基准测试工具，由 Mozilla Builders 支持开发，它基于 llama.cpp 与 Llamafile 构建。它的核心目标有两个：

1. 测量：量化 LLM 在你的 CPU、NVIDIA GPU、AMD GPU 或 Apple Silicon 上的实际运行速度；
2. 比较：通过可选的匿名结果提交，构建公开的硬件性能数据库，帮助社区在决定“是否在本地跑 AI 模型”以及“用什么硬件跑”时做出更明智的选择。

你可以通过 localscore.ai 查看由社区提交结果汇聚成的排行榜。

从源码结构看，LocalScore 是一个独立的 CLI 程序（入口为 localscore/main.cpp 中的main，实际逻辑在 localscore/localscore.cpp 的localscore_cli），通过 localscore/BUILD.mk 构建为o/$(MODE)/localscore/localscore可执行文件，同时其核心测速逻辑也被整合进 llamafile 主程序（通过--bench入口）。

LocalScore 测量什么：三大核心指标

LocalScore 对每个模型评估三个关键性能指标：

评分公式：三项指标的几何平均

这三个指标被组合成一个单一的LocalScore数值，使用几何平均（geometric mean）：

$$\text{score} = 10 \cdot \sqrt[3]{\text{avg_prompt_tps} \cdot \text{avg_gen_tps} \cdot \frac{1000}{\text{avg_ttft_ms}}}$$

该公式的实现可以在 localscore/localscore.cpp 的getResultsSummary中看到：它对所有基准测试结果求prompt_tps、gen_tps、ttft_ms的算术平均，再按上式求出performance_score。

分数参考区间

作为通用参考（非绝对标准）：

• 1000+ 分：表现优秀
• 250 分：对大多数用户而言可接受至良好
• 100 分：相对较差

基准测试的模拟场景

为了让测试贴近真实使用，LocalScore 内置了一组基线测试场景（见 localscore/localscore.cpp 的get_baseline_test_configs），每个场景由(n_prompt, n_gen)即“提示词 token 数 : 生成 token 数”组成，覆盖从标题生成到长文本推理的多种负载：

{1024, 16}, // 64:1 title generation {4096, 256}, // 16:1 content summarization {2048, 256}, // 8:1 lots of code to fix {2048, 768}, // 3:1 standard code chat {1024, 1024}, // 1:1 code back and forth {1280, 3072}, // 1:3 reasoning over code {384, 1152}, // 1:3 code gen with back and forth {64, 1024}, // 1:16 code gen/ideation {16, 1536} // 1:96 QA, Storytelling, Reasoning

测试会依次运行这 9 个负载场景（每个场景按--reps指定的次数重复），并分别统计提示词处理速度（pp t/s）、生成速度（tg t/s）与首个令牌延迟（ttft）。测试输入并非真实文本，而是由随机 token 填充的模拟 prompt，目的是测量硬件与推理后端的原始吞吐能力。

运行 LocalScore 的四种方式

LocalScore 提供四种运行途径，前两种的安装包可以从 localscore.ai/download 页面获取：

也可以始终选择从源码构建，构建方式遵循主仓库的 Llamafile 构建说明（参见 README.md 与 docs/source_installation.md）。

方式 1：下载并运行 LocalScore Bundle

Bundle 将 LocalScore 二进制与一个模型打包在一起，访问 localscore.ai/download 获取当前可用的 bundle 即可直接运行。

方式 2：直接下载 LocalScore Release

从 Latest Release Download Page 下载适合你操作系统的二进制：

macOS / Linux：

chmod +x localscore ./localscore -m path/to/model.gguf

Windows（PowerShell）：

localscore.exe -m path\to\model.gguf

模型需要是 GGUF 格式（llama.cpp 的标准模型格式）。

方式 3：下载 llamafile Bundle 后运行--bench

从 llamafile v0.9.2 起，每一个新发布的 llamafile 都内置了 LocalScore 基准测试命令（--bench），无需单独下载基准工具。

macOS / Linux：

# 从 Hugging Face 下载一个 llamafile curl -O https://huggingface.co/Mozilla/Llama-3.2-1B-Instruct-llamafile/resolve/main/Llama-3.2-1B-Instruct.Q4_K_M.llamafile # 运行 LocalScore 基准测试 chmod +x Llama-3.2-1B-Instruct.Q4_K_M.llamafile ./Llama-3.2-1B-Instruct.Q4_K_M.llamafile --bench

Windows：

从 Hugging Face 下载任意小于 4GB 的 llamafile 并运行：

Llama-3.2-1B-Instruct.Q4_K_M.llamafile.exe --bench

注意（Windows 限制）：受 Windows 自身限制，大于 4GB 的 llamafile 无法直接运行。Windows 用户应使用独立版 LocalScore，并传入 GGUF 格式模型（详见后文“限制”一节）。

方式 4：通过已安装的 Llamafile 运行

如果你已经安装了 Llamafile，可以直接调用它来运行基准测试：

macOS / Linux：

llamafile --bench -m path/to/model.gguf

Windows：

llamafile.exe --bench -m path\to\model.gguf

命令行选项详解

LocalScore 的完整用法如下（实际输出与源码 localscore/cmd.cpp 的print_usage一致）：

usage: localscore [options] options: -h, --help Show this help message -m, --model <filename> Model to benchmark (default: path/to/default) -c, --cpu Disable GPU acceleration (alias for --gpu=disabled) -g, --gpu <auto|amd|apple|nvidia|disabled> GPU backend to use (default: "auto") -i, --gpu-index <i> Select GPU by index (default: 0) --list-gpus List available GPUs and exit -o, --output <csv|json|md> Output format (default: md) -v, --verbose Enable verbose output -y, --send-results Send results without confirmation -n, --no-send-results Disable sending results -e, --extended Run 4 repetitions (shortcut for --reps=4) --long Run 16 repetitions (shortcut for --reps=16) --reps <N> Set custom number of repetitions

常用组合示例

纯 CPU 运行（禁用 GPU 加速，等价于--gpu=disabled，同时将n_gpu_layers置 0）：

./localscore -m path/to/model.gguf --cpu

自动提交结果（跳过确认提示，直接匿名上传）：

./localscore -m path/to/model.gguf -y

每个测试重复 4 次（-e是--reps=4的快捷方式，结果更稳定）：

./localscore -m path/to/model.gguf -e

参数背后的实现细节

从 localscore/cmd.cpp 的parse_cmd_params可以看到几个值得注意的实现细节：

• -c/--cpu与-g/--gpu disabled都会把FLAG_gpu置为LLAMAFILE_GPU_DISABLE并将n_gpu_layers设为 0；而指定某个 GPU 后端时n_gpu_layers为 9999（全部层卸载到 GPU）。
• -y（--send-results）与-n（--no-send-results）是互斥的，源码中会校验二者不能同时使用。
• --reps的下限被钳制为 1（std::max(1, ...)），避免 0 次重复的无意义运行。
• 除-m/--model外，也支持把模型路径作为位置参数直接传入。
• 若未指定模型文件，程序会报错退出：missing model file。
• 实际的默认值可在 localscore/cmd.cpp 的cmd_params_defaults中查看，例如n_batch=2048、n_ubatch=512、KV cache 类型（type_k/type_v）在支持 AVX512-BF16 的 CPU 上默认BF16，否则为F16、线程数取cpu_get_num_math()、n_gpu_layers=9999（优先 GPU）、reps=1、默认输出为控制台格式。

输出格式

• 默认（-o未指定）为控制台 Markdown 风格表格，表头包含test（测试场景名，形如pp1024+tg16）、run number、avg time、tokens processed、pp t/s、tg t/s、ttft等列，由 localscore/printer.cpp 的console_printer::print_header生成；
• -o csv输出 CSV 表格，字段与 JSON 输出一致；
• -o json输出结构化 JSON，包含runtime_info（llamafile 版本与 llama.cpp commit）、system_info（CPU 型号、架构、内存、内核信息）、accelerator_info（GPU 名称、厂商、显存）与results数组，数组中每项含prompt_tps、gen_tps、ttft_ms、power_watts、samples_ns（原始采样间隔）等字段，见 localscore/printer.cpp。

说明：README 帮助文本中的-o <csv|json|md>与源码实际支持值略有出入——源码实现（localscore/cmd.cpp）接受的取值是csv、json、console。以源码为准：用-o console可获得默认表格输出。

结果提交与数据收集

提交机制

基准测试完成后，LocalScore 会询问是否将结果匿名提交到公共数据库：

Do you want to submit your results to https://localscore.ai? The results will be public (y/n):

源码 localscore/localscore.cpp 的submitBenchmarkResults展示了提交流程：

• 提交目标为https://www.localscore.ai/api/results（POST+ JSON）；
• 默认（SEND_ASK）会等待用户确认；-y跳过确认直接提交；-n禁止提交；
• 网络失败时采用指数退避重试（第 n 次重试前等待 2^n 秒，最多 3 次）；
• 成功后打印结果链接：Result Link: https://www.localscore.ai/result/<id>。

收集的数据类型

提交到 localscore.ai 的数据不含任何个人可识别信息，仅包括：

• CPU 型号与配置
• GPU 型号与配置
• 操作系统及版本
• 内存（RAM）大小
• 基准性能指标（上述三项速度指标及派生分数）

这些数据用于构建 LLM 推理硬件性能数据库，帮助用户对比不同配置并做出知情决策。硬件与系统信息的具体采集逻辑在 localscore/system.cpp 中实现。

基准测试的底层原理

LocalScore 的测速核心复用 llama.cpp 的推理引擎。从 localscore/localscore.cpp 的主流程localscore_cli看，一次完整基准测试的调用链为：

1. 环境初始化：LoadZipArgs解压嵌入参数 →parse_cmd_params解析命令行 →acceleratorSelector处理多 GPU 选择（多块 NVIDIA GPU 时交互式询问主 GPU，见 localscore/localscore.cpp）→ 采集运行时/系统/加速器信息；
2. 初始化 llama 后端：llama_backend_init()+llama_numa_init()，非 verbose 模式下静默日志；
3. 加载模型：llama_load_model_from_file，并读取模型的general.name、量化类型、大小、参数量等元信息（见 localscore/benchmark.cpp 的test构造函数）；
4. 预热（warmup）：perform_warmup→warmup_run先用 1024 个 prompt token 和 16 个生成 token 各跑一遍，排除冷启动/缓存初始化对结果的影响（见 localscore/localscore.cpp）；
5. 逐个运行基线场景：对 9 个(n_prompt, n_gen)场景，通过llama_new_context_with_model创建独立上下文，运行test.run()，并用一个独立的pthread线程在控制台实时刷新生成速度列（见 localscore/localscore.cpp）；
6. 统计与汇总：test类（localscore/benchmark.h）记录每次重复的prompt_intervals、gen_intervals、time_to_first_token等时间采样，用avg_ns/stdev_ns/avg_ts计算平均值、标准差与 tokens/s，ttft()返回首个 token 延迟平均值；
7. 提交与展示：汇总三项指标的平均值计算 LocalScore 分数，用彩色终端输出分数、生成速度、提示词处理速度与 TTFT（见displayResults），随后进入提交确认流程。

测速过程中，测试使用随机 token 而非真实文本：prompt 阶段首 token 使用 BOS 标记、其余为std::rand() % n_vocab随机 token，分批（每批n_batch=2048）通过llama_decode喂给模型；生成阶段则单 token 逐次解码并同步（llama_synchronize），以排除异步流水线对计时的影响（见 localscore/benchmark.cpp）。

此外，LocalScore 还通过 localscore/powersampler.h 提供的功率采样器记录功耗（power_watts），进而给出每瓦特吞吐量（prompt_tps_watt、gen_tps_watt，见get_tps_watt），可用于衡量能效。

限制与已知问题

• Windows 文件大小限制：由于 Windows 限制，大于 4GB 的 llamafile 无法直接运行。Windows 用户应把 LocalScore 作为独立工具使用，并传入 GGUF 格式模型。
• 单 GPU 聚焦：目前 LocalScore 仅支持单 GPU 配置，这也是大多数本地运行 LLM 用户最实际的场景（多 GPU 场景下仅交互式选择主 GPU，不做多卡并行）。
• 早期开发阶段：LocalScore 仍处于相对早期开发阶段，可能会遇到偶发问题，遇到问题请到 Issue Tracker 反馈。

故障排查

LocalScore 的常见问题与 Llamafile 高度类似，完整排查指南见 localscore/doc/troubleshooting.md，要点如下：

• Windows：超过 4GB 的 bundle 无法运行，请改用独立工具 + GGUF 模型；在 WSL2 中需要注册 cosmopolitian APE binfmt 服务（将cosmo-binfmt.service写入/etc/systemd/system/，并把 APE 加载器安装到/usr/bin/ape后systemctl enable --now cosmo-binfmt），必要时通过echo -1 > /proc/sys/fs/binfmt_misc/WSLInterop（Windows 11 为WSLInterop-late）或在/etc/wsl.conf中设置[interop] enabled=false禁用 WIN32 互操作；另外 Windows 上 LocalScore 性能暂时慢于 Linux，属预期现象。
• Linux：若出现run-detectors或 WINE 相关报错，是binfmt_misc注册冲突，可为 APE 格式补充注册:APE:与:APE-jart:两条规则。
• macOS：Apple Silicon 上需安装 Xcode Command Line Tools 以便 llamafile 自举；zsh（5.9 之前版本）及部分 shell/Pythonsubprocess环境下可用sh -c ./llamafile规避；若出现“无法验证开发者”提示，可在系统设置的“隐私与安全性”中允许，或用sudo spctl --master-disable临时关闭校验后恢复。

许可证

LocalScore 以 MIT License 发布，其构建依赖的 llama.cpp 与 Llamafile 亦遵循各自的许可条款。它是 Mozilla Builders 支持的项目，构建于 llama.cpp 与 Llamafile 的杰出工作之上。

【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile