larql

Rust 写的模型运行时，能跑能查还能改模型内部

开源 🏷️定价信息待确认 ⏳ 访问状态待核验基础设施 🍴 复刻 211 🐛 待处理 29 👀 关注 25

访问官网 ↗ GitHub ↗

GitHub 星标 ★ 1175

维护状态活跃

是否开源开源

定价模式 🏷️定价信息待确认

项目预览

项目数据

分类基础设施

开发团队chrishayuk

官网地址https://vindex3.org

GitHubhttps://github.com/chrishayuk/larql

定价模式🏷️定价信息待确认

价格说明定价信息待确认

访问状态⏳ 访问状态待核验

是否开源是

开源协议Apache-2.0

主要语言Rust

技术栈/模型huggingface,inference,llm,mechanistic-interpretability,metal,model-editing,model-interpretability,openai-api,rust,vindex3

GitHub 星标★ 1175

上线时间2026-03-27 00:00:00

代码更新2026-11-11

仓库体积81.2 MB

本站数据更新2026-11-12

维护状态活跃

收录时间2026-11-12

浏览次数0

项目介绍

larql 是一个用 Rust 编写的 AI 模型运行时，目标是让模型不仅能跑起来，还能被直接查看和修改。它建立在自定义的 VINDEX3 模型格式之上，这种格式把模型做成可执行、可检查的结构，而不是传统的不透明权重文件。项目解决的核心问题是：常规推理框架只负责加载和运行模型，开发者很难在推理过程中观察内部状态或对模型做细粒度编辑。larql 提供运行、服务、查询、编辑四类能力，支持接入 Hugging Face 模型生态，对外暴露 OpenAI 兼容 API，方便现有客户端直接调用。它面向机械可解释性研究和模型编辑场景，允许在统一格式下检查模型结构、定位特定组件并施加修改，同时兼顾 Metal 等本地加速后端。整体定位偏向研究型基础设施，适合需要深入模型内部而非只做黑盒推理的开发者。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-11-12 · 当前星标 ★ 1175

技术标签

huggingface inference llm metal openai-api

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

macOS（Apple Silicon）、Linux（x86_64）或 Windows（x86_64）系统
无需 Rust 工具链，直接使用官方预编译二进制
首次运行需从 Hugging Face 下载模型并转换为 VINDEX3，Qwen3-0.6B 约占 1.5 GB 磁盘空间
需要能正常访问 Hugging Face 以完成首次模型下载

安装与启动步骤

1下载预编译二进制

按系统选择对应压缩包，解压后得到 larql 与 larql-server 两个可执行文件
```
curl -L https://github.com/chrishayuk/larql/releases/latest/download/larql-aarch64-apple-darwin.tar.gz | tar xz
```
2安装到系统路径

把解压出的 larql 系列文件移动到 /usr/local/bin，之后可在任意目录调用
```
sudo mv larql-aarch64-apple-darwin/larql* /usr/local/bin/
```

3Linux 用户替换为对应包

Linux x86_64 使用 linux-gnu 压缩包，解压目录名不同，移动命令也随之调整

curl -L https://github.com/chrishayuk/larql/releases/latest/download/larql-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv larql-x86_64-unknown-linux-gnu/larql* /usr/local/bin/

4Windows 手动下载

从 latest release 页面下载 larql-x86_64-pc-windows-msvc.zip 并解压，将目录加入 PATH
5检查安装环境

运行 doctor 自检，确认硬件、后端、缓存目录与 Hugging Face 访问是否正常
```
larql doctor
```
6运行第一个模型

首次运行会把 Hugging Face 检查点转换为 VINDEX3 并缓存，之后启动很快
```
larql run hf://Qwen/Qwen3-0.6B "What is the capital of France? Answer in one word. /no_think"
```
7启动兼容 API 服务

用 serve 在指定端口暴露 OpenAI 兼容接口，供现有客户端直接调用
```
larql serve Qwen3-0.6B --port 8080
```

8调用接口验证

向本地 chat/completions 端点发一条消息，返回内容即表示服务正常

curl http://localhost:8080/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"Qwen3-0.6B","messages":[{"role":"user","content":"Write a haiku about Rust."}]}'

关键配置

配置项	必填	说明	示例
`--port`	否	serve 子命令监听端口，默认示例为 8080	`8080`
`hf://`	否	run 时用于指向 Hugging Face 模型仓库地址	`hf://Qwen/Qwen3-0.6B`
`--raw`	否	跳过聊天模板，按纯文本补全方式处理提示词	`--raw`
`--backend`	否	observe 子命令指定推理后端	`production`
`--record`	否	把每层贡献记录写入指定的 jsonl 文件	`run.jsonl`

如何确认成功

larql doctor 无报错，且 curl 请求 /v1/chat/completions 能返回模型生成的文本内容。

常见问题

Q：第一次运行很慢是正常的吗？

A：正常。首次运行会从 Hugging Face 下载模型并转换为 VINDEX3 格式，Qwen3-0.6B 约 1.5 GB；转换完成后按短名缓存，后续启动很快。

Q：第二次运行还需要联网吗？

A：不需要。模型已缓存为 VINDEX3，后续按短名（如 Qwen3-0.6B）直接加载，可离线启动。

Q：larql serve 启动失败怎么办？

A：serve 依赖同目录下的 larql-server 可执行文件，请确认压缩包中的 larql 与 larql-server 都已移动到 /usr/local/bin。

Q：怎么直接使用现成的 VINDEX3 模型？

A：用 larql pull 拉取预转换模型，例如 granite-4.1-3b，随后即可用 larql run 加载并按短名调用。

Q：模型回答里出现 think 标签是什么原因？

A：提示词会按模型自带聊天模板处理；把 /no_think 追加到提示词末尾可切换为非思考模式，或用 --raw 走纯文本补全。

注意事项

每个发行归档同时包含 larql 与 larql-server，后者被 larql serve 使用，不要只复制其中一个。
安装完成后先跑 larql doctor，确认硬件、后端、缓存与 Hugging Face 访问状态，再下载模型。
模型首次转换只做一次，缓存按模型短名存放，后续命令可直接写短名。
windows 用户需手动下载 zip 并自行配置 PATH，没有对应的 curl 一键命令。

核心亮点

自定义 VINDEX3 格式让模型可执行且可检查，支持在推理链路中观察和编辑模型内部结构
单一 Rust 二进制提供运行、服务、查询、编辑四类能力，部署链路简单
暴露 OpenAI 兼容 API，现有客户端和工具可直接接入，迁移成本低

不足之处

VINDEX3 为项目自定义格式，与主流 GGUF、safetensors 等格式的互操作和转换工具尚不明确
项目处于早期成长阶段，模型编辑与可解释性相关文档和社区案例积累有限

适用场景

机械可解释性研究：检查模型内部组件并做定向编辑实验
本地模型服务：用 Rust 单二进制部署 OpenAI 兼容推理接口
模型调试与改造：在统一格式下定位并修改模型特定部分

替代项目

llama.cpp、Ollama、vLLM

上一篇：dotLLM

下一篇：ollama-fundamentals