技术速递｜oBeaver —— 一只可以在你本地机器上运行大语言模型的海狸 [特殊字符]

作者卢建晖 - 微软高级云技术布道师排版Alan Wang大家好我是 oBeaver 的创建者。这个项目起源于一个非常简单的想法我想在自己的电脑上运行大语言模型。不把数据发送到云端不需要 API Key也没有按调用计费。我猜你可能也有过类似的想法。市面上已经有一些很优秀的工具——其中最知名的就是 Ollama。但在我的日常工作中我花了很多时间在 ONNX 生态中——比如 ONNX Runtime 的跨平台能力、原生 NPU 支持以及 Microsoft Foundry Local 的开箱即用体验。这让我一直在想ONNX 生态其实值得拥有一个更完整的本地推理工具链。于是oBeaver 就这样诞生了。如果你想直接上手这里是相关链接GitHubhttps://github.com/microsoft/obeaver/?wt.mc_id3reg_webpage_reactor文档https://microsoft.github.io/obeaver/?wt.mc_id3reg_webpage_reactor三分钟快速上手使用 oBeaver 上手非常简单。你只需要 Python 3.12然后执行克隆、安装、开始对话这几步git clone https://github.com/microsoft/obeaver.gitcd obeaverpip install -e . # 初始化模型目录会自动创建 ort/、foundrylocal/、cache_dir/ 子目录obeaver init # 检查一切是否正常obeaver check如果你使用的是 macOS 或 Windows安装 Microsoft Foundry Local 后只需一条命令就可以开始与模型对话obeaver run phi-4-mini第一次运行会自动下载模型——稍等一分钟即可。之后再次运行就会是即时响应。在 Linux 上或者如果你想使用来自 Hugging Face 的模型ORT 引擎可以满足你的需求# 将 Hugging Face 上的 Qwen3-0.6B 转换为 ONNX 格式obeaver convert Qwen/Qwen3-0.6B # 使用 ORT 引擎运行obeaver run --engine ort ./models/ort/Qwen3-0.6B_ONNX_INT4_CPU想把你的模型变成一个 HTTP 服务一行命令即可obeaver serve Phi-4-mini然后将任何兼容 OpenAI 的客户端指向它——只需要修改一个 base_url你现有的代码就可以直接运行from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:18000/v1, api_keyunused) response client.chat.completions.create( modelPhi-4-mini, messages[{role: user, content: What is the capital of France?}], streamTrue,)for chunk in response: print(chunk.choices[0].delta.content or, end, flushTrue)LangChain、LlamaIndex、Microsoft Agent Framework、CrewAI ——任何使用 OpenAI 协议的工具都可以直接接入。这是从一开始就不可妥协的设计原则本地推理不应该是一个孤岛而应该能够无缝融入你现有的开发工作流。“为什么不直接用 Ollama”我经常被问到这个问题而且值得一个直接的回答。Ollama 是一个非常出色的项目。它开创了“用一条命令运行模型”的体验让本地 LLM 推理对所有人都变得触手可及。如果你只是需要一种快速在本地与模型对话的方式Ollama 依然是一个非常棒的选择。oBeaver 本身也从它身上获得了大量灵感。但 Ollama 和 oBeaver 走的是不同的技术路径。Ollama 基于llama.cpp构建使用GGUF模型格式。oBeaver 基于ONNX Runtime构建使用 ONNX 模型格式。这两种格式背后是两种截然不同的理念。GGUF拿来即用GGUF 的优势在于极致的可移植性。一个文件就打包了所有内容——权重、分词器、元数据。Hugging Face 上有大量已经量化好的 GGUF 模型可以直接下载运行。量化选项非常丰富从 Q2_K 到 Q8_0社区也非常活跃。对于个人开发者来说这种“拿来即用”的体验几乎无可替代。ONNX一次转换到处加速ONNX 的优势体现在另一个维度。作为跨平台的工业标准ONNX Runtime 提供了一个叫做Execution Providers的机制——同一个 ONNX 模型无需任何修改就可以运行在 CPU、GPU甚至NPU上。这一点的重要性可能比表面看起来更大。随着像 Intel Core Ultra、Qualcomm Snapdragon X 以及 Apple Neural Engine 这样的芯片逐渐普及NPU 正在快速成为 AI PC 的标准硬件。ONNX Runtime 已经原生支持 NPU 加速而 GGUF 生态目前还不具备这一能力。这意味着ONNX 可以自然适配更广泛的设备——从服务器到笔记本从桌面到边缘设备甚至手机和 IoT 终端。你今天在 CPU 上运行的 ONNX 模型明天可以在带有 NPU 的设备上直接加速运行——无需重新转换模型也无需修改代码只需切换 Execution Provider。当然ONNX 的上手门槛更高——模型需要先进行转换。但 oBeaver 内置的obeaver convert命令基于微软的 Olive 工具链已经将这个过程简化为一行命令。另一个值得一提的项目是oMLX它同样在 ONNX 生态中探索本地推理但主要专注于 Apple 芯片。而 oBeaver 的目标更全面——覆盖 macOS、Windows 和 Linux并支持文本对话、向量嵌入以及视觉语言等多种场景。三者对比一览_OllamaoMLXoBeaver模型格式GGUFONNXONNX推理后端llama.cppONNX RuntimeFoundry Local ORT GenAI平台支持macOS / Linux / WindowsmacOSmacOS / Windows / LinuxNPU 加速❌❌✅嵌入模型✅✅✅VL 模型✅✅✅函数调用✅✅✅Docker 部署✅✅✅我并不是说 oBeaver 比 Ollama 更好。它们服务于不同的需求。但如果你的工作涉及 ONNX 生态、NPU 加速或者需要结合嵌入功能与多模态能力oBeaver 提供了一条目前 Ollama 尚未覆盖的路径。为什么采用“双引擎”这是 oBeaver 最具特色的设计决策也是我花时间最多思考的一点。oBeaver 在底层集成了两个推理引擎Microsoft Foundry Local和ONNX Runtime GenAIORT。为什么不只选一个因为现实远比理想更复杂。Microsoft Foundry Local是微软的本地推理运行时使用体验非常好——只需要传入一个模型别名例如 Phi-4-mini它就会自动下载、加载并运行模型同时还能进行智能硬件调度NPU GPU CPU。但它也有两个明显的限制第一模型目录还比较小主要集中在微软的 Phi 系列第二它只支持 macOS 和 WindowsLinux 用户无法使用。ONNX Runtime GenAI刚好弥补了这些不足。它支持 macOS、Windows 和 Linux 三大平台。通过obeaver convert你可以将 Hugging Face 上几乎任何模型转换为 ONNX 格式从而获得更广泛的模型选择。目前oBeaver 已经可以通过 ORT 引擎运行来自Phi、Qwen、Gemma、GLM等 SLM 系列的模型。除此之外ORT 引擎还支持一些 Foundry Local 无法实现的能力嵌入模型ORT 引擎内置了专用的嵌入引擎支持 Qwen3-Embedding 和 EmbeddingGemma非常适合本地 RAG 流水线# 启动嵌入服务obeaver serve-embed ./models/Qwen3-Embedding-0.6Bfrom openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:18001/v1, api_keyunused) response client.embeddings.create( modelQwen3-Embedding-0.6B, input[Hello, world!, Embeddings are useful.],)for item in response.data: print(findex{item.index} dim{len(item.embedding)})视觉语言模型VL当 ORT 引擎检测到模型目录中存在vision.onnx时会自动切换到 VL 模式。当前支持Qwen-2.5-VL-3B 和 Qwen-3-VL-2B。你可以同时发送图像和文本实现多模态理解obeaver serve ./models/Qwen3-VL-2B-Instruct_VL_ONNX_INT4_CPU将 VL 模型转换为 ONNX 也只需要一条命令obeaver convert Qwen/Qwen2.5-VL-3B-Instruct --type vl因此“双引擎”并不是冗余设计而是基于现实做出的最优选择Foundry Local 只覆盖 macOS / Windows而 ORT GenAI 覆盖所有平台Foundry Local 模型较少但零门槛ORT GenAI 模型更多且更灵活。oBeaver 会根据你的平台和任务自动选择最合适的引擎在 macOS / Windows 上默认使用 Foundry Local在 Linux 上使用 ORT在 embedding 或视觉语言任务中会自动切换到 ORT。当然你始终可以通过--engine ort进行覆盖。一句话总结Foundry Local 负责“开箱即用”ORT 负责“能力扩展”。两者结合让 oBeaver 能够覆盖几乎所有平台和使用场景。云原生当然可以oBeaver 不只是一个本地玩具。从一开始部署能力就被设计进了系统架构中。整体架构是清晰分层的CLITyper → FastAPI 服务器 → 可插拔推理引擎。我们提供了一个 Docker 镜像同时支持 linux/amd64 和 linux/arm64包括 Apple 芯片# 构建镜像docker buildx build --platformlinux/amd64 \ -f docker/Dockerfile.cpu -t obeaver-cpu . # 启动 API 服务器docker run -d --rm -p 18000:18000 \ -v /path/to/models:/models \ obeaver-cpu serve -m /models -E ort --host 0.0.0.0 --port 18000无论是本地开发、CI/CD 流水线、无界面服务器还是 Kubernetes 集群都可以正常运行。结合 OpenAI 兼容 API你可以在本地针对 oBeaver 进行开发然后在生产环境中只需修改一个 URL 就切换到云端服务。你的应用代码甚至不需要做任何改动。不只是 CLI —— 还有 Dashboard到目前为止我展示的都是终端命令但有时候你只是想要一个可视化界面——尤其是在评估模型、对比性能或者做演示的时候。oBeaver 内置了一个 Web Dashboard只需一条命令即可启动obeaver dashboard # Foundry Local 引擎macOS/Windowsobeaver dashboard -e ort # ORT 引擎扫描本地 ONNX 模型打开 http://127.0.0.1:1573/你会看到类似这样的界面它是一个“实时监控 聊天”的一体化界面主要功能包括模型选择器可以在已缓存的模型之间快速切换。如果某个模型支持 NPU 加速会用 ⚡ 标识出来。使用 Foundry Local 时你会看到本地目录中的模型列表而在 ORT 引擎下它会扫描你的模型目录列出所有可用的 ONNX 模型聊天 实时基准测试你可以直接发送消息并获取流式响应同时界面会实时显示性能数据例如TTFT首 token 时间tokens/s生成速度总 token 数这让你可以非常方便地对不同模型进行横向性能对比系统监控实时展示 CPU、GPU、NPU 以及进程内存占用情况。顶部信息栏还会显示当前模型、引擎类型、平台以及健康状态一目了然。推理参数调节可以直接在界面中调整temperaturetop-ptop-kmax tokens所有参数都有预设值无需重启服务。VL 模式当你在 ORT Dashboard 中加载 Vision-Language 模型时界面会自动切换到专用 VL 模式你可以同时输入图片 URL 和文本提示其他功能还包括对话历史保存与加载系统提示词配置实时服务器日志每个请求的请求方式、路径、状态码及耗时导出为 JSON 或 Markdown这个 Dashboard 不是一个独立产品它只是obeaver dashboard。所有功能都在本地运行不会上传任何数据。它特别适合在将模型接入应用之前快速评估它在你本机上的真实表现。说实话目前仅支持 CPUoBeaver 目前仍处于技术预览阶段这里我想坦诚说明一点——目前只支持 CPU 推理。这是一个有意的分阶段决策。我们希望先把整个工具链打磨扎实模型转换、推理、API 服务、Docker 部署——全部在 CPU 上做到稳定可靠。几乎每一台机器都有 CPU它是验证完整工作流最稳妥的基础。但GPU 和 NPU 支持很快就会到来而且已经在路线图的最优先级位置。ONNX Runtime 本身已经提供了成熟的 CUDAGPU以及 QNN / OpenVINONPU执行后端。Foundry Local 也已经内置了 NPU GPU CPU 的自动调度能力。oBeaver 需要做的是把这些能力整合进自身的引擎选择逻辑和模型转换流程中——这部分工作正在积极推进。从长远来看oBeaver 选择 ONNX 路线的一个核心原因就是面向 NPU 的未来。AI PC 时代正在到来当 NPU 成为标准硬件时ONNX 将成为适配该硬件最为成熟的生态系统。致谢oBeaver 的设计灵感来源并借鉴了以下优秀项目项目说明Ollamahttps://github.com/ollama/ollama/?wt.mc_id3reg_webpage_reactor通过简单 CLI 在本地运行大语言模型OMLXhttps://github.com/jundot/omlx/?wt.mc_id3reg_webpage_reactor基于 ONNX在 Apple 芯片上运行大模型vLLMhttps://github.com/vllm-project/vllm/?wt.mc_id3reg_webpage_reactor高吞吐、内存高效的 LLM 推理引擎Foundry Localhttps://github.com/microsoft/foundry-local/?wt.mc_id3reg_webpage_reactor微软的本地模型运行时支持 NPU/GPU/CPU 加速ONNX Runtime GenAIhttps://github.com/microsoft/onnxruntime-genai/?wt.mc_id3reg_webpage_reactorONNX Runtime 的生成式 AI 扩展Olivehttps://github.com/microsoft/Olive/?wt.mc_id3reg_webpage_reactor微软的 ONNX Runtime 模型优化工具链我需要你的反馈以上就是这次介绍的全部内容。但 oBeaver 仍处于发展初期还有大量可以改进的空间。作为这个项目的创建者我最担心的不是批评而是沉默。所以真诚希望大家能试用并告诉我你的想法你最希望运行哪些模型对你的使用场景来说GPU / NPU 加速有多重要你如何看待“双引擎”设计它是提升体验还是增加复杂度在真实项目中本地推理最大的痛点是什么Docker 方案还缺什么Helm Chart还是 Compose 文件无论是 GitHub Issue、PR还是社交媒体上的反馈都非常欢迎。oBeaver 这个名字来源于“海狸”——自然界最出色的工程师之一。海狸会一根一根地搭建水坝创造出适合自己生存的环境。我希望 oBeaver 也能帮助你做到同样的事情在自己的硬件设备上一步步搭建起属于你的本地 AI 基础设施。在本地构建筑起属于你的“云坝”。GitHubhttps://github.com/microsoft/obeaver/?wt.mc_id3reg_webpage_reactor文档https://microsoft.github.io/obeaver/?wt.mc_id3reg_webpage_reactor如果你觉得 oBeaver 有用在 GitHub ⭐ 对我们意义重大