企业官网建设流程全解析

想在 MacBook 或普通 Linux 服务器上本地跑大模型，又不想折腾云 API 和一堆环境依赖？本文带你用 LARQL 推理引擎完成 Metal/CPU 双后端配置。LARQL 是一个开源的模型执行与查询系统（Rust 编写），支持在 macOS 上用 Apple GPU（Metal）加速推理，或在任意平台用纯 CPU 内核运行，一条命令即可切换后端，是本地大模型推理的完整落地方案。

为什么选择 LARQL 做本地推理

很多本地推理方案（如各家 CLI 工具）要么绑定特定硬件，要么后端写死。LARQL 的做法是把"数值后端"抽成独立 crate：

• larql-compute：CPU 内核，负责矩阵乘法、量化 MatVec 等基础运算，Linux/Windows 用 OpenBLAS 或纯 ndarray 路径
• larql-compute-metal：Metal 后端（macOS 专属），GPU 加速推理
• larql-inference：会话与生成逻辑，消费上层的 logits
• larql-cli：命令行入口，把以上能力封装成日常可用的run/bench/serve命令

这样同一份模型容器文件，在 macOS 上默认走 Metal，在 Linux/Windows 上自动降级 CPU，无需改任何模型文件。架构细节见 docs/compute-substrate.md 与 docs/architecture-stack.md。

快速开始：克隆并构建双后端版本

一键安装步骤

先准备 Rust 工具链（仓库通过 rust-toolchain.toml 锁定了版本），然后克隆代码：

git clone https://gitcode.com/gh_mirrors/la/larql cd larql

macOS（默认 Metal 后端 + CPU 兜底）：

cargo build --release -p vindex-cli -p larql-cli

Linux / Windows（纯 CPU 后端）：

cargo build --release -p vindex-cli -p larql-cli --no-default-features

💡 关键点：crates/larql-cli/Cargo.toml 中默认特性为default = ["gpu", "research"]。在 macOS 上默认就带上了 Metal 的gpu特性；Linux/Windows 必须加--no-default-features关闭它，否则构建会报错。若想在 macOS 上编译纯 CPU 版本，也用同样的开关。

构建完成后，二进制在target/release/目录，加入 PATH 或直接调用即可。

三条命令跑通第一次推理

LARQL 的 CLI 提供 Ollama 风格的日常动词（完整命令表见 docs/cli.md）：

# 1. 从 HuggingFace 拉取一个现成的 vindex 模型 larql pull chrishayuk/gemma-3-4b-it-vindex # 2. 一次性推理（给 prompt） larql run gemma-3-4b-it-vindex "The capital of France is" # 3. 不带 prompt 则进入交互式聊天 larql chat gemma-3-4b-it-vindex

模型支持三种引用方式：缓存简写名（gemma-3-4b-it-vindex）、owner/name、hf://owner/name，也可以用本地目录路径直接指向 vindex 文件。

如果你手里是 Hugging Face 原始 checkpoint（safetensors/GGUF/MLX），用larql extract <model-id>构建成.vindex即可查询和推理。

Metal/CPU 双后端如何切换

这是本文的核心配置项，全部围绕larql run的参数：

典型用法：

# 明确指定 Metal 后端 larql run qwen3-0.6b.vindex3 --metal "The capital of France is" # 显式限定 KV 缓存策略，长文本更省内存 larql run gemma-3-4b-it-vindex --kv-cache markov-bounded --context-window 2048 "..."

切换逻辑很简单：同一命令，加不加--metal决定数值后端，权重只加载一次。对 VINDEX3 容器而言，不带--metal时自动用 larql-compute 的 CPU 内核执行。

用 bench 命令实测两种后端的速度

配置完别急着信文档，用内置基准测试自己验证（参数说明见 docs/cli.md）：

# 同时测量 Metal 与 CPU 两个后端，50 步 decode larql bench gemma3-4b-it-vindex --backends metal,cpu # 还可以顺带和本地 Ollama 服务对比 larql bench gemma3-4b-it-vindex --ollama gemma3:4b

输出会给出每种后端的 tok/s（均值、p50、p99）。注意：数字只描述你当前这台机器的表现，换硬件要重新测。项目自己的历史基准记录在 bench/baselines/ 目录，可作参考起点。

进阶：VINDEX3 容器与 serve 服务化

LARQL 新一代的工作流是把模型编码成 VINDEX3 容器（一个可执行的"模型程序"），完整文档见 docs/vindex3/execution.md：

# 准入检查 → 编码 → 校验 vindex plan /path/to/checkpoint --json vindex encode /path/to/checkpoint --output model.vindex3 vindex verify model.vindex3 # 在后端上执行并记录真实 decode（--backend production 即 CPU 内核） larql vindex3 exec model.vindex3 --backend production --tokens 1,2,3 --generate 8 larql vindex3 observe model.vindex3 --backend production \ --prompt "The capital of France is" --record run.jsonl

需要给多客户端提供推理服务时，用larql serve model.vindex3 --port 8080起 HTTP + gRPC 服务；docs/vindex3-runtime.md 详述了 API 行为。

常见配置问题排查

• Linux 构建报 Metal 相关错误：忘记加--no-default-features，默认gpu特性只支持 macOS
• 想编译纯 CPU 版但仍用 release 形态：cargo build -p larql-cli --no-default-features；要 Metal 则--no-default-features --features gpu
• run报研究命令不可用（如larql walk）：该二进制未带research特性，重建时加上即可，详见 docs/cli.md
• 后端跑错了：用larql diag <vindex>打印当前实际命中的内核路径，加--probe可跑一次真实前向验证

总结

LARQL 把 Metal/CPU 双后端做成了构建特性 + 运行时开关的组合，模型文件与后端解耦。从git clone到第一条推理输出，通常只需要一条cargo build和一条larql run——本地跑大模型，真的不求人。