kunpengtalk/OmniStudio · 上手攻略

  • 仓库：kunpengtalk/OmniStudio
  • 链接：https://github.com/kunpengtalk/OmniStudio
  • 分类：AI 桌面工作台 / 本地推理运行时 / 一体化
  • 作者：spark
  • 更新：2026-09-16

是什么

OmniStudio 是一个本地优先的大模型一体化桌面工作台，由「鲲鹏Talk」开发并以 MIT 协议开源。它把"模型从哪里来、用什么引擎跑、怎么用起来"三件事收进一个 Electron-like 桌面应用（基于 Electrobun + Bun），把"模型市集下载、推理引擎管理、对话、语音、图片、视频、OCR、翻译、本地 RAG、共享记忆、MCP、Skills 管理、编码工具集成"这十几条原本零散的工具链粘成一套统一体验。

仓库当前 Star ~108、周增 +114，处于 trending 状态（数据来自工作队列入榜快照）。它不是一个"再写一个 ChatGPT 客户端"，而是把"本地 + 云端"两套大模型能力在同一份数据（SQLite + Drizzle ORM）里打通：本地用 llama.cpp / vLLM / SGLang / MLX 跑权重，云端用 OpenAI 兼容端点直连，统一抽象成"模型名 + 引擎类型"这一层，对外只暴露一套 Chat Completions / Responses / Anthropic Messages 协议 + 一个 MCP 服务端。

解决什么问题

如果只跑一个本地模型，llama.cpp / Ollama / LM Studio 任意一个就够；OmniStudio 想覆盖的是更宽的边界：

  1. 多引擎混用：同一个对话场景可能想要 llama.cpp 跑量化小模型（省显存）、SGLang/vLLM 跑长上下文、需要时切到云端 MiniMax/DeepSeek/通义/GLM — OmniStudio 用统一网关按模型名路由，热切换不重启。
  2. 多模态一站到底：TTS（audio.cpp / Edge-TTS / OpenAI 兼容）、ASR（whisper.cpp / audio.cpp / 兼容 API）、实时语音（云端实时端点）、生图（云端 API / ComfyUI / Apple Silicon MLX）、生视频（云端 H3 / 火山方舟 Seedance / ComfyUI）、OCR（Tesseract / PaddleOCR / VLM）每条都是独立工具链，OmniStudio 把它们收成一个工作台"应用"。
  3. 本地 RAG + 共享记忆：不依赖外部向量库 / FTS，纯 JS 实现 BM25 + 向量 RRF 混合检索 + 可选 /v1/rerank；全 Agent 共享一份 SQLite 记忆，3 条通路（内置工具 / 网关 REST /v1/memories / MCP 工具 / omi memory CLI）。
  4. 编码工具不重复造轮子：Claude Code / Codex / OpenCode / Hermes / Pi / Copilot CLI / OpenClaw 一键启动并绑定默认模型，自动接入共享记忆。
  5. Skills 中央库：默认 ~/.agents/skills，53 个内置工具适配器，symlink / copy 两种同步模式，Git 远端备份 + 快照。

快速安装

⚠️ 平台限制：README 当前明确写"macOS（Apple Silicon）"，Linux / Windows 在 Roadmap 中尚未交付。下面的命令仅适用于 macOS Apple Silicon。

环境要求：

  • Bun 1.3+
  • macOS Apple Silicon（M 系列芯片；Intel Mac 引导页能识别但 Apple 统一内存预算不适用）

安装与开发（来自 README）：

git clone https://github.com/kunpengtalk/OmniStudio.git
cd OmniStudio
bun install

# 开发模式（HMR，推荐调试用）
cd apps/studio && bun run dev:hmr

# 生产构建
cd apps/studio && bun run build:dev

# 安装全局 omi CLI（与应用共享同一份 SQLite 库）
cd apps/studio && bun link

预编译安装包：Releases — 下载 dmg/pkg 双击安装即可。⚠️ 本攻略写作时点未在 releases 页明示具体最新版本号（截取到的内容是 changelog 体例），请以 releases 列表顶部为准；不建议直接用 git HEAD 当稳定版。

核心用法

1. 首次启动：按机器选模型

引导页有「这台机器」卡片，自动探测芯片 / 核数 / 内存 / 独显显存，并按预算给推荐：

  • Apple Silicon → 装 mlx-lm → 推 MLX 引擎
  • NVIDIA 独显 ≥ 48GB 显存且装了 vLLM → 推 vLLM（vLLM 只有 bf16，无量化档，显存不够大反而会把可跑模型砍小一档）
  • 其他 → llama.cpp

模型按"权重 + KV 缓存 + 运行期开销"估算，分四档：流畅 / 可用 / 内存偏紧 / 超出内存；量化下拉里装不下的档位直接标红。预置 Qwen3.5 4B / 9B / 35B-A3B 与 Qwen3.6 27B 一键下载部署。

2. 三引擎统一运行时

切换引擎不重启：模型选择页选引擎 → 应用主进程拉起对应二进制 → 写回网关槽位。

# CLI 端查询与切换
omi models                    # 本地 + 云端清单
omi model-info <name>         # 看详情
omi model --select            # 终端里选活动模型（不加选项就打开应用模型列表）
omi serve --port 8090         # 无界面常驻跑推理服务器（前台长驻）

云端预设 20 家厂商（OmniLabs、DeepSeek、通义千问、智谱 GLM、Kimi、豆包、文心一言、腾讯混元、MiniMax、讯飞星火、零一万物、阶跃星辰、硅基流动、OpenRouter、OpenAI、Anthropic、Gemini 等），「设置 → 云端模型」里给各用途指定默认模型。

3. 统一网关（最值钱的部分）

应用启动后，本地一个端点按模型名路由：

  • POST /v1/chat/completions / /v1/responses / /v1/messages（Anthropic 协议，含双向工具调用）
  • GET /v1、/health、/metrics（设置页一键复制）
  • POST /mcp（Streamable HTTP，无状态）— 把知识库 kb_search / kb_list 与记忆 memory_search / memory_save / memory_list 开放给 Claude Code / Cursor 等任意 MCP 客户端；浏览器打开 GET /mcp 有内置调试工作台
  • GET /v1/memories — 共享记忆 REST

可选 API Key 鉴权，内置交互式 OpenAPI 文档。

4. 本地 RAG 知识库

# 导入：文本直读，PDF / 图片走 VLM OCR
# 切片：Markdown 感知（标题分节 + 段落贪心打包 + 超长硬切带重叠）
# 检索：BM25 × 向量 RRF 混合 + 可选 /v1/rerank 重排
# 召回测试 / 文档 / 访问 / 设置 四个标签页

不依赖外部向量库或 FTS 扩展，纯 JS + SQLite。

5. Pi Agent 三模式

  • Agent：完整工具集（文件 / Shell / 检索 / 记忆 / 已启用 MCP）
  • Plan：只读工具，先出方案再动手；自动排除有副作用的工具
  • Goal：长程目标驱动

工具以 mcp_* 命名注入；MCP 客户端支持 stdio / Streamable HTTP / 旧版 SSE 三种传输，连接失败自动跳过。

6. 共享记忆

omi memory add "偏好用 pnpm"          # 写入（Agent 与 CLI 共用一份库）
omi memory search 构建工具             # 检索
omi memory mcp                         # stdio MCP，给编码工具读写

omi launch codex --model qwen3-4b-q4_k_m 拉起 Codex 并自动挂载 omni-memory MCP 服务器，CLAUDE.md / AGENTS.md 托管记忆区块自动刷新。

7. 编码工具一键集成

设置页 → 「编码工具」组：Claude Code（Opus / Sonnet / Haiku 三档映射）、Codex、OpenCode、OpenClaw、Hermes、Pi、Copilot CLI 一键生成启动命令并绑定默认模型。

8. 实时仪表盘 + 基准测试

  • 仪表盘：吞吐 / tok/s / 请求数 / 活跃模型 / 内存 CPU 负载 / 模型磁盘占用，每 2 秒轮询
  • 基准测试：上下文长度扫描 1K–200K，记录 TTFT / TPOT / TPS，支持本地或远程服务

典型适用场景

  1. 个人 / 小团队本地 AI 工作台：不想装 Ollama + LM Studio + ComfyUI + Open WebUI + 一堆 MCP 调试工具的人，一个 dmg 解决 80% 日常（对话 / 翻译 / 语音 / OCR / 知识库）。
  2. MCP 服务端：/mcp 把本地知识库 + 记忆暴露给 Claude Code / Cursor / Cline，省得每个 IDE 都各搞一份。
  3. 多模型 A/B：同一份 prompt 在 llama.cpp 4B 量化 / SGLang 27B / 云端 Claude 之间热切，看效果差异。
  4. 教学 / Demo：引导页+一键模型+统一网关，最少命令行就能让新人跑起一套完整本地 AI。
  5. AI 视频原型：云端 H3 / Seedance 任务轮询统一接口 + 历史库，少写一层状态机。

坑与注意

  • ⚠️ 仅 macOS Apple Silicon：README 明确写"Linux / Windows 支持规划中"，别在非 Mac 上尝试。
  • ⚠️ Releases 版本号：本攻略写作时点从仓库抓到的最新更新日志是 changelog 体例，没在 GitHub releases 页拿到显式最新版本号；生产使用前请以 Releases 顶部 tag 为准。
  • ⚠️ vLLM 显存门槛：vLLM 引擎只跑 bf16 权重，没有量化档，≥ 48GB 显存的 NVIDIA 卡才推荐；显存不够时引导页会自动降到 llama.cpp，不要手动硬上 vLLM。
  • ⚠️ MCP stdio 与应用生命周期：omi memory mcp 走 stdio 给外部 IDE 用，IDE 关闭进程会跟着退出；长驻场景改用网关 REST /v1/memories 或 MCP HTTP。
  • ⚠️ 多引擎 GPU 抢占：Apple Silicon 上 llama.cpp / MLX / whisper.cpp 同时跑会争统一内存；仪表盘盯紧内存，必要时关掉不用的引擎。
  • ⚠️ Rerank 第三方依赖：BM25 + 向量是内置的，但 /v1/rerank 需自备 Jina / SiliconFlow / Cohere 兼容端点，不配就只有 RRF 不加重排。

与同类对比

  • Ollama / LM Studio：只覆盖"本地跑模型 + 对话"，OmniStudio 在它之上叠加了模型市集、语音 / 图片 / 视频 / OCR / 翻译、知识库、共享记忆、MCP 服务端、编码工具集成；体量大一个数量级。
  • Open WebUI：纯 Web 前端，要靠 Ollama / vLLM / OpenAI API 当后端；OmniStudio 内置三引擎运行时 + 桌面壳 + 命令行（omi），安装即用。
  • ComfyUI + 各自脚本：OmniStudio 把 ComfyUI、MiniMax H3、Seedance 三套视频后端统一成"提交任务 + 轮询 + 历史库"一条路径，但不是 ComfyUI 替代品 —— 复杂工作流仍要在 ComfyUI 里搭，OmniStudio 只是调用方。
  • AnythingLLM / RAGFlow：偏 RAG 文档管理；OmniStudio 的 RAG 是工作台"应用"之一（"召回测试 / 文档 / 访问 / 设置"四页），没有 AnythingLLM 那么深的文档协作，但多模态 + MCP 服务端 + 编码工具集成是 AnythingLLM 没有的。
  • Cherry Studio / NextChat：纯前端客户端，云端为主；OmniStudio 是 macOS 原生桌面应用 + 引擎运行时 + 工具链中央库。

一句话推荐结论

如果你只在 Mac Apple Silicon 上、想"一个应用搞定本地 + 云端、对话 + 多模态、知识库 + 记忆 + MCP"，OmniStudio 是当前体量最大、整合最深的开源一体化选择；如果你只要"本地跑模型 + 对话"，Ollama / LM Studio 更轻，先用它们等不够用了再迁过来。