Osmantic ODS 快速入门：把 PC / Mac / Linux 变成私有 AI 服务器

这是什么？适合谁？

Osmantic ODS（Osmantic Deployment System）是一个自托管的本地 AI 服务器整合栈。它做的事不是「再写一个模型运行时」，而是把你原本要手工拼起来的十几个服务装好、接好线、放进一个仪表盘：本地推理（llama-server）、ChatGPT 式的网页对话（Open WebUI）、服务与 GPU 健康仪表盘、语音（Whisper 语音转文字、Kokoro 文字转语音）、Agent（Portal 对话助理、Hermes Agent、APE 策略引擎）、工作流（n8n，官方称 400+ 集成）、RAG 与搜索（Qdrant 向量库、SearXNG 自建搜索、Perplexica 深度检索）、图像生成（ComfyUI），以及隐私与运维件（Privacy Shield 的 PII 清洗代理、Token Spy、可选的 Langfuse 观测）。

官方定位一句话：Turn your PC, Mac, or Linux box into a private AI server。它的价值在于「整合 + 生命周期管理」，而不是模型本身——模型仍然是 Qwen、Gemma、Nemotron 这些开源权重。

适合谁：有独立显卡或统一内存机器、想把对话与文档留在本机的开发者和小团队；要给内网搭一套可审计 AI 环境的运维；不想每月付订阅费但愿意付电费的人。

不适合谁：只有一台 8GB 内存办公本、且不愿意装 Docker 的人；需要开箱即用的托管 API 的纯业务用户；对「安装脚本从 main 分支拉取」这件事零容忍的合规环境（见下文风险）。

核验日期：2026-11-12。本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

前置条件与安全边界

• Linux 或 macOS：必须先装好并运行 Docker；macOS 仅支持 Apple Silicon（M1 及以上），并使用 Docker Desktop。
• Windows：不需要预装任何东西，官方 PowerShell 安装块会引导启用 WSL2、安装 Ubuntu 24.04 与 Docker Desktop，但需要一次重启和管理员授权；安装器会检查 40 GB 可用磁盘与硬件虚拟化是否开启。
• NVIDIA 显卡的 Windows 机器，官方要求先把驱动更新到 570 或更新版本；AMD Strix Halo 走平台专用加速路径。
• 平台支持面：Linux（NVIDIA、AMD Strix Halo）与 Windows（NVIDIA、AMD）、macOS Apple Silicon 为 Supported；Linux + Intel Arc（SYCL）仍是 Experimental / Tier C，需要自己指定 --tier ARC_LITE 或 --tier ARC。
• 磁盘预算：模型权重要单独占空间，官方安装器按 40 GB 起检查；实际占用取决于你选的模型档位。
• 安全边界要说清：当前是 V3 pre-release，安装器装的是 main 分支而不是签名发布；v3.0.0 是「latest published source release」，但官方明确「no release has qualified for the verified channel yet」。也就是说你执行的是持续变动的代码，不是经过端到端验证的签名包。
• 别在生产机上第一发就上。先用一台可以整机重装的机器试，确认 ./ods-uninstall.sh --force 能干净回滚再考虑迁移。
• 密钥纪律：ods config show 会脱敏显示 .env，但 .env 仍是明文文件；不要把 ~/ods 整个目录提交进任何仓库。

安装与启用

三条路径按平台选一条，命令都能直接复制。

Linux / macOS 一条命令：

curl -fsSL https://install.osmantic.com/ods.sh | bash

执行前建议先读脚本再执行（官方在 Installer Trust 文档里给了审查路径与 ODS_REF 指定 commit 的做法）；装完的运行时默认在 ~/ods。

Windows 用 PowerShell 安装块（不是管理员窗口，也不要在 PowerShell 里跑上面那条 curl）：

& {
    $ErrorActionPreference = 'Stop'
    $ProgressPreference = 'SilentlyContinue'
    $odsSrc = Join-Path $env:TEMP ('ods-install-' + [guid]::NewGuid().ToString('N'))
    $odsZip = Join-Path $odsSrc 'ods-main.zip'
    New-Item -ItemType Directory -Path $odsSrc | Out-Null
    Invoke-WebRequest -UseBasicParsing 'https://github.com/Osmantic/ODS/archive/refs/heads/main.zip' -OutFile $odsZip
    Expand-Archive -LiteralPath $odsZip -DestinationPath $odsSrc
    $odsEntry = Join-Path $odsSrc 'ODS-main\install.ps1'
    if (-not (Test-Path -LiteralPath $odsEntry -PathType Leaf)) { throw 'The downloaded archive does not contain the ODS installer.' }
    Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
    & $odsEntry
}

macOS 手动路径（先启动 Docker Desktop，再把源码 clone 到与默认运行时 ~/ods 不同名的目录）：

git clone https://github.com/Osmantic/ODS.git ~/src/ODS
cd ~/src/ODS/ods
./install.sh

要避开的不是「用户目录」本身，而是默认运行时那个名字：macOS 磁盘大小写不敏感，~/ODS 与 ~/ods 是同一个文件夹，克隆到 ~/ODS 会和安装目录打架——官方专门提示了这一点。~/src/ODS 仍在你的用户目录下，但完整路径与 ~/ods 不同，因此不冲突。

Linux 手动路径：

git clone https://github.com/Osmantic/ODS.git
cd ODS/ods
./install.sh

安装完成后三个入口要分清，很多人在这里以为是装坏了：

• Portal（新仪表盘 + 对话）：http://localhost:3001/pixel
• Open WebUI（传统对话界面）：http://localhost:3000
• 推理 API：Linux Docker 默认 http://localhost:11434，macOS 原生 Metal 与 Windows AMD 走 8080；Windows 服务端需要 API key

端口冲突可用环境变量覆盖，完整列表在 ods/.env.example 的「Ports — all overridable」一段。变量与服务一一对应，写错变量不会生效：

• WEBUI_PORT（默认 3000）只改 Open WebUI；
• DASHBOARD_PORT（默认 3001）改 Portal 仪表盘的本机入口，DASHBOARD_REMOTE_PORT（默认 3011）是给其他机器访问的入口；
• OLLAMA_PORT（默认 11434）是 Linux Docker 下的推理 API 端口。

只把 Open WebUI 挪开（Portal 仍留在 3001）：

WEBUI_PORT=9090 ./install.sh

只把 Portal 的 3001 挪开：

DASHBOARD_PORT=4001 ./install.sh

不想用本地算力时可以直接上云模式（同一套栈，后端换成托管 API）：

./install.sh --cloud

第一个任务与成功判定

首任务不要挑复杂的，就跑「确认整条链路真的通了」：

1. 浏览器打开 http://localhost:3001/pixel，等仪表盘出现。
2. 在对话框里发一句 用三句话解释什么是 RAG，并指出它和微调的区别。
3. 拿到模型回复后，再发第二条追问 把刚才的答案压缩成一张三行的对比表。

成功判定（缺一条都算没跑通）：

• 第一条消息返回的是模型生成的自然语言，不是报错页、不是空白、不是「模型未加载」。
• 第二条能引用第一条的上下文，说明会话没断、模型没有在切换过程中掉线。
• 仪表盘的 Services 里推理服务状态是运行中，不是仅「页面能打开」。

容易踩的假成功：仪表盘能打开、服务列表全绿，但对话压根没响应——这通常说明全量模型还在后台下载，你现在连的是 bootstrap 的小模型或还没完成切换。官方明确写了「a loaded dashboard alone does not prove Pixel is ready」，所以判定必须落在一次真实的对话往返上。

用命令行核对状态：

ods status                # 健康检查 + GPU 状态
ods model current         # 当前到底加载了哪个模型
ods logs llm              # 推理服务日志

初级用法

• 先接受 bootstrap 模式：安装器会先下 Qwen3.5 2B（约 1.3 GB）让你马上能聊，全量模型在后台继续下；下完会重启推理服务换成全量模型。这几秒里的请求需要重发，不是故障。
• 用仪表盘切模型，而不是手改 .env：Dashboard → Models 会列出适配你显存的模型、带校验和下载、加载失败自动回滚到上一个。手改 .env 里 GGUF_FILE / LLM_MODEL 没有自动回滚。
• 用 ods 管生命周期，别去 docker compose 里翻：ods start / stop / restart [service] / list / logs llm 覆盖启停、查看与单服务重启；扩展开关走 ods enable / disable。
• 私有文档问答：在 Open WebUI 里上传文档就走它自带的 RAG 流程。ODS 的 docker-compose.base.yml 把嵌入计算指向本栈的 TEI 服务（RAG_EMBEDDING_ENGINE=openai、RAG_OPENAI_API_BASE_URL=http://embeddings:80/v1、默认模型 BAAI/bge-base-en-v1.5），但没有设置 VECTOR_DB，所以向量库用的是 Open WebUI 自己的默认后端，不是 Qdrant——Qdrant 在这套栈里是独立服务，谁在用它取决于你启用了哪些扩展。「数据不出网」也不是装好就成立：还要看 ENABLE_WEB_SEARCH 是否为 true（默认 false，开启后走自建 SearXNG），以及模型是否走 cloud / hybrid 模式。上线前用 ods config show 把这三项核一遍。
• 语音与图像按需开：Whisper + Kokoro 做听写与朗读，ComfyUI 做本地出图；不用就在 Extensions 里关掉，省显存。

高级玩法

• 混合路由省钱：ods mode hybrid 让本地模型当主力、云端 API 当兜底，ods mode cloud / ods mode local 随时切。适合「日常问答走本地、难任务偶尔上云」的团队。
• 自己写扩展：ODS 把每个服务都当扩展，目录里放 manifest.yaml（名称、端口、健康检查端点、GPU 后端）和 compose.yaml（会被自动合并进栈），然后 ods enable my-service。加一个内部服务不需要改主 compose。
• 用 APE（Agent Policy Engine）管自治调用：Agent 要碰真实系统时，工具边界、本地上下文与策略都在这一层审计，适合把「能自动执行」和「能自动改生产」分开。
• 配置快照与回滚：ods preset save gaming / ods preset load gaming 把当前 .env 配置存成命名档位，换模型或换模式前先存一份，出问题一条命令退回去。
• Headless / 无显示器部署：官方有 QR 引导首启、AP 模式、mDNS 与本地 Agent 接入的文档（ods/docs/HEADLESS-SETUP.md），适合塞在机柜里的机器。
• 按硬件档位挑模型：ods model swap T3 直接切硬件档；也可以用 MODEL_PROFILE=gemma4 ./install.sh 强制走 Gemma 4 系列。

小技巧

• 首次安装把「重启」当成流程的一部分，Windows 路径会要求重启后继续，别以为卡住了就 Ctrl+C。
• 装之前先 docker info 确认 Docker 真的在跑；Linux/macOS 上「Docker 装了但没启动」是最常见的失败原因。
• 记录你安装时的 commit 或 ODS_REF。因为是 main 分支，出问题时「我装的是哪天的代码」决定了你能不能复现。
• 换模型前 ods preset save before-swap，失败时 ods preset load before-swap，比回忆自己改了什么快。
• 自己已经有 GGUF 的话，把单个 .gguf 丢进 data/models/，再从 Dashboard → Models 加载本地条目，比重新下一遍省带宽。
• 在混合模式下先开 Privacy Shield，再填云端 API key，让 PII 清洗发生在出网之前。
• 定期看 GitHub 的 security advisories；官方明说在 pin v3.0.0 之前应该先读它。

踩坑

踩坑 1： 症状——仪表盘能打开，发消息一直转圈或直接报错。原因——全量模型还在后台下载，或刚完成 bootstrap 到全量模型的切换，推理服务正在重启。排查——ods model current 看当前模型是不是那个 2B 引导模型，ods logs llm 看有没有下载/加载日志。解决——等下载完成；切换瞬间的请求重发一次即可。想跳过 bootstrap 用 ./install.sh --no-bootstrap。来源：README Bootstrap Mode。

踩坑 2： 症状——Windows 上照文档跑 curl -fsSL ... | bash 报一堆语法错。原因——PowerShell 不认 bash 语法，官方明确写了不要从 PowerShell 跑这条。解决——改用上文那段 PowerShell 安装块，它下载源码 ZIP 后交给 Ubuntu/WSL2 里的安装器。来源：README Get Started。

踩坑 3： 症状——Windows 装完，在 PowerShell 里敲 ods status 说不认识这个命令。原因——运行时其实在 WSL 的 Ubuntu 里（通常是 ~/ods），原生 Windows 的 ods.ps1 不管理这个 Linux 运行时。解决——打开 Ubuntu 终端，cd ~/ods 后执行 ods status 或 ./ods-cli status。来源：README Windows。

踩坑 4： 症状——macOS 上 clone 完，安装器行为诡异或文件互相覆盖。原因——macOS 文件系统大小写不敏感，~/ODS 和默认安装目录 ~/ods 是同一个地方。解决——克隆到 ~/src/ODS 这类完整路径与 ~/ods 不同名的位置（不必离开用户目录），再 cd 进去安装。来源：README macOS。

踩坑 5： 症状——ods update 跑完了，但某个 bug 还在。原因——ods update 只刷新容器镜像，不更新安装器与宿主机代码；官方安全文档明确代码修复要重跑安装器。解决——重新执行对应平台的安装命令（已有安装会保留数据），再 ods restart。来源：README Status 段。

踩坑 6： 症状——3000 打不开，或和本机别的服务冲突。原因——WEBUI_PORT 默认 3000，被占时 Open WebUI 起不来。解决——安装时用同名的 WEBUI_PORT 覆盖：WEBUI_PORT=9090 ./install.sh，装完 ods restart。注意这个变量只改 Open WebUI：Portal 仪表盘是另一个变量 DASHBOARD_PORT（默认 3001），改 WEBUI_PORT 不会解决 3001 的冲突，那种情况要写 DASHBOARD_PORT=4001 ./install.sh。来源：README Port conflicts、.env.example Ports 段。

踩坑 7： 症状——Intel Arc 机器上安装器识别不出显卡，选了 CPU 档。原因——Arc 目前是 Tier C 实验支持，硬件探测还认不出 Arc。解决——手动指定档位：6–8 GB 卡用 ./install.sh --tier ARC_LITE，16 GB 卡用 --tier ARC。来源：README Intel Arc。

踩坑 8： 症状——手改 .env 换了模型，服务起不来且没有自动恢复。原因——手工改 .env 没有回滚机制，只有仪表盘换模型才有。解决——把 GGUF_FILE、LLM_MODEL 改回旧值后 ods restart llm；以后统一走 Dashboard → Models。来源：README Switching Models。

常见问题 FAQ

Q1: ODS 到底免费吗，会不会有隐藏收费？

A: 代码是 Apache-2.0，官方明说不需要订阅、不需要云。钱花在自有硬件、电费和你自己选的模型上。唯一要留意的例外是内置的 Pixel 源码：它有单独的「仅限 ODS 使用与分发」授权，不等于 Apache-2.0，二次分发或改造前要读 ods/LICENSING.md。

Q2: 最低什么硬件能跑？

A: 官方给了分档：NVIDIA 8–16 GB 显存对应 Qwen3.5 9B（64K 上下文），24–32 GB 对应 27B；Apple Silicon 8 GB 起（Nemotron3 Nano 4B）；纯 CPU 8–12 GB 内存也能跑 2B。低于这些不是不能装，是体验会很差。

Q3: 断网能用吗？

A: 能用。默认只在三件事上联网：下载模型与容器镜像、检查 GitHub 上的 ODS 新版本、Portal agent 替你做的网页搜索。官方 FAQ 写了每一项怎么关。装完之后跑本地推理本身不需要外网。

Q4: Windows 必须装 WSL2 吗？

A: 走官方 PowerShell 安装器就是必须的，它会把 WSL2、Ubuntu 24.04、Docker Desktop 一起准备好；原生 Windows 安装属于另一条历史路径，官方另有迁移说明。已经有 WSL 发行版可以用 -Distro <name> 指定。

Q5: 怎么更新？会不会丢数据？

A: 分两层。ods update 只刷新容器镜像；安装器与宿主代码的修复要重跑安装命令。数据在 ~/ods/data 下，重跑安装器是保留数据的升级路径，但升级前先备份这个目录更稳妥。

Q6: 和 Ollama、Open WebUI、AnythingLLM 是什么关系？

A: 不是替代关系，是「装好并接好」。官方自己的对比表写得很直白：Ollama / llama.cpp / LM Studio 给的是本地模型服务，ODS 加的是硬件感知选型、外围服务与仪表盘；Open WebUI 给的是对话界面，ODS 负责把它和推理、语音、搜索、图像装在一起并管住登录与端口暴露。

Q7: 能商用吗？

A: 主体代码 Apache-2.0 允许商用。但内置 Pixel 有 ODS 专用的使用与分发授权，商用前必须逐条读 ods/LICENSING.md 与 Pixel 的许可证文件，不要默认「Apache-2.0 就是随便用」。

进阶学习：把 ODS 当平台而不是一次性安装

装通之后，值得按六个方向继续往下读；每一项都对应仓库里的一份文档，能直接照着做：

1. 模型管理层（ods/docs/MODEL-MANAGEMENT.md）：Dashboard → Models 是一条六步链——在目录里发现模型、下载、加载、在所有已启用的 LLM 应用里使用、临时切换后恢复原模型。它支持在 ODS 内检索 Hugging Face 上的兼容 GGUF 仓库，也能导入你手工放进模型库的单文件 GGUF。先拿一个已有 .gguf 试导入，用 ods model current 确认读到了，再批量迁移。
2. 切换的请求安全（.env.example 里的 ODS_MODEL_SWITCHBOARD 与 ODS_MODEL_PROFILES）：开关处于 enabled 时，受支持的应用走 ods/current 稳定别名并做请求安全切换，出问题可退回 observe 或 legacy；模型档案默认是 observe，只测量不启用，改成 enabled 后模型首跑会量测回答、工具调用、思考、图像与速度并显示在 Models 页——想先看数据再放行，就先用 observe 跑一周。
3. 扩展开发（ods/docs/EXTENSIONS.md 与 ods/extensions/library/）：每个服务一个目录，manifest.yaml 声明名称、端口、健康检查端点与 GPU 后端，compose.yaml 会被并入主栈，然后 ods enable <name>。起步最快的办法是复制库内一个同类扩展再改，改完用 ods/docs/COMPOSE_RESOLVER_CONTRACTS.md 核对端口与覆盖规则。
4. 安装器与升级面（ods/docs/INSTALLER-ARCHITECTURE.md、ods/docs/INSTALLER_PHASE_CONTRACTS.md）：安装器是 41 个库模块加一个服务注册表、14 个有序 phase。要加硬件档位或换默认模型，得同时改 Linux、macOS、Windows、升级与 host-agent 五个写入点——这正是「手改 .env 会和下次安装打架」的根源。
5. 网络与无头部署（ods/docs/HEADLESS-SETUP.md、ods/docs/MDNS.md、ods/docs/NETWORK.md）：塞在机柜里的机器走 QR 首启、AP 模式与 mDNS；BIND_ADDRESS 决定端口只听 loopback 还是暴露到 LAN，ODS_PROXY_PORT（默认 80）给 <device>.local 提供服务入口。改成非 loopback 之前先读 SECURITY.md。
6. 发布可预期性（ods/docs/VALIDATION-MATRIX.md、ods/docs/KNOWN-GOOD-VERSIONS.md、ods/docs/SUPPORT-MATRIX.md）：把这次安装对应的 commit、模型文件与镜像 tag 记成一份自己的已知良好版本清单，回滚时按清单对齐，而不是凭记忆猜「上次是哪个版本」。

参考链接

• Osmantic 官网
• GitHub 仓库 Osmantic/ODS
• README（安装、平台支持、模型档位）
• 许可说明 ods/LICENSING.md
• 安装器信任与审查 Installer Trust
• 安全策略与升级方式 SECURITY.md
• V3 发布说明 RELEASE_NOTES_3.0.0.md
• 扩展开发指南 EXTENSIONS.md
• Headless 部署 HEADLESS-SETUP.md
• 数据与隐私 FAQ