ODS

ODS

Osmantic Deployment System

把你的 PC、Mac 或 Linux 机器变成一台私有 AI 服务器。

AI 服务器和 homelab 的搭建正在迅速成为一个已解决的问题。 它应该让每个人都感受到这一点。

ODS 负责安装并把你在本地运行 AI 所需的一切组件拼接起来，这样你就不必手动组装 Ollama、Open WebUI、n8n、ComfyUI 和各类隐私工具：

• 本地模型推理（inference） — 在你自己的硬件上运行开源模型
• ChatGPT 风格 Web UI — 从任何浏览器与你的模型对话
• 控制面板（Dashboard） — 在一个地方管理模型、服务、设置、GPU 状态和扩展
• 语音、Agent 与工作流 — 构建能够聆听、说话、调用工具并完成工作的自动化
• RAG 与搜索 — 连接本地文档、私有搜索和检索工作流
• 图像生成 — 在本地运行图像工具，无需将提示词发送到托管 API
• 隐私与运维 — 将服务认证、密钥、可观测性和诊断集中在一个本地技术栈中

无需云服务，无需订阅。除非你自己选择，否则你的提示词和数据都留在你的机器上。当你需要时，云和混合 API 模式是可选功能。

发布验证： 运维变更会通过一套发布级（release-grade）的集群和发行版实验室进行验证：零前置条件引导、全新安装、产品流程、完整模型能力、生命周期恢复，以及最终的 User Green 门禁。关于一次绿色运行（green run）证明了什么，请参阅 Release Validation。

仓库结构： 仓库根目录包含公开 README、安装器、安全策略、GitHub workflows 和项目协调文档。ods/ 目录是产品运行时：服务、安装器阶段、compose overlays、仪表盘、CLI、测试和运维文档。

稳定版本消费： v2.6.0 是当前稳定版本。main 分支迭代很快；请将其用于活跃开发和验证候选。对于 fork、appliance、实验室或类似生产环境的安装，请固定到已打标签的发布版本或经过审计的 commit，并保留你自己的验证凭证。稳定版补丁会先落到 release/2.6.x，然后再向前合并。请参阅 Release Channels、Installer Trust 和 Forkability。

快速开始

选择你的系统，复制对应的命令块，在普通终端中运行。ODS 会安装整个技术栈、根据你的硬件挑选模型、启动服务，并给你本地 Web UI 的访问地址。

Linux 或 macOS

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

Windows PowerShell

$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 "https://github.com/Osmantic/ODS/archive/refs/heads/main.zip" -OutFile $odsZip
Expand-Archive -LiteralPath $odsZip -DestinationPath $odsSrc -Force
cd (Get-ChildItem -LiteralPath $odsSrc -Directory | Select-Object -First 1).FullName
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

前置条件：必须已安装并运行 Docker。在 Windows 上，请使用启用了 WSL2 后端的 Docker Desktop，并在普通（非管理员）PowerShell 窗口中运行上述命令块。

托管的 Linux/macOS 端点代理仓库 main 分支的当前引导脚本。经过审查的合并会在边缘缓存刷新后自动到达该端点。ODS_REF 可以选择一个兼容的仓库 checkout。请参阅 Installer Trust 来检查脚本内容，或手动安装稳定发布版本或经过审计的 commit。

Windows 用户不应在 PowerShell 中运行 curl ... | bash 命令。上面的 PowerShell 命令块会下载源码 ZIP 并运行与 clone 工作流相同的 Windows 安装器。更多细节请参阅 Windows Quickstart。

安装完成后，打开 http://localhost:3000 即可开始聊天。

之后使用对应平台的命令卸载：

cd ~/ods
./ods-uninstall.sh --force

$installDir = "$env:USERPROFILE\ods"
cd $installDir
.\ods.ps1 uninstall --force

Windows 恢复说明：如果运行时目录不完整且缺少 .\ods.ps1，请从源码 checkout 中运行同样的命令：.\ods\installers\windows\ods.ps1 uninstall --force。它会先移除标记为 ODS compose 项目的 Docker 资源，然后删除运行时目录。

API 端点： Linux Docker 安装默认在 http://localhost:11434 暴露 llama-server（OLLAMA_PORT），而容器内部使用 llama-server:8080。macOS 原生 Metal 和 Windows 原生/Lemonade 路径默认使用 http://localhost:8080，除非被覆盖。Open WebUI 始终位于 http://localhost:3000。

没有 GPU？ ODS 也可以运行在云模式下 — 同样的完整技术栈，由 OpenAI/Anthropic/Together API 驱动，而非本地推理：

./install.sh --cloud

端口冲突？ 每个端口都可以通过环境变量配置。完整列表请参阅 .env.example，也可以在安装时覆盖：

WEBUI_PORT=9090 ./install.sh

刚接触 ODS？ 请阅读 Friendly Guide 或 收听音频版本 — 全面了解 ODS 是什么、它如何工作，以及如何让它为你所用。无需任何技术背景。

---

概览

问题	回答
它是什么？	一个运行在你自己硬件上的本地 AI 服务器技术栈，附带 Linux/macOS 的一键安装器和 Windows 的 PowerShell 安装器。
为谁设计？	希望在家、实验室或工作站上拥有私有 AI，而又不想手动串联十几个服务的人。
我能得到什么？	本地推理、Open WebUI 聊天、控制面板、语音、Agent、工作流、RAG、搜索、图像生成、隐私工具、可观测性和开发者工具。
它运行在什么平台上？	Linux、带 WSL2/Docker Desktop 的 Windows，以及 Apple Silicon 的 macOS。
必须使用云吗？	不是。本地模式是默认选项；云和混合 API 模式是可选的。

如果你熟悉...	ODS 在此基础上增加...
Ollama / llama.cpp	完整的服务器技术栈：聊天、仪表盘、语音、RAG、工作流、Agent、隐私和服务管理。
Open WebUI	围绕 Open WebUI 的完整安装器与控制平面，以及预先接好的本地服务。
AnythingLLM	超越 RAG 的更广泛本地 AI appliance 行为：推理、聊天、语音、工作流、图像生成和运维。
n8n 自托管 AI starter kits	工作流自动化成为更大私有 AI 服务器中的一部分。

---

当前平台支持

平台	状态
Linux (NVIDIA + AMD + Intel Arc)	支持 — 今天即可安装运行
Windows (NVIDIA + AMD)	支持 — 今天即可安装运行
macOS (Apple Silicon)	支持 — 今天即可安装运行

经过测试的 Linux 发行版： Ubuntu 24.04/22.04、Debian 12、Linux Mint 21.3、Fedora 41+、Rocky Linux 9、Arch Linux、Manjaro、CachyOS 和 openSUSE Tumbleweed。其他使用 apt、dnf、pacman 或 zypper 的发行版应该也能正常工作 — 如果你的发行版不行，请提交 issue。

发布验证： 运维变更会经过一套发布级门禁，覆盖零前置条件引导、全新安装、产品行为、完整模型能力、生命周期恢复和 User Green。请参阅 Release Validation 和 Validation Matrix。

Windows： 需要带 WSL2 后端的 Docker Desktop。NVIDIA GPU 使用 Docker GPU 透传；AMD Strix Halo 通过平台特定的加速路径运行，详见 Windows 安装器和支持矩阵。

macOS： 需要 Apple Silicon (M1+) 和 Docker Desktop。llama-server 以 Metal GPU 加速原生运行；所有其他服务在 Docker 中运行。

有关受支持平台的声明，请参阅 Support Matrix；有关用于验证这些声明的分层测试面，请参阅 Validation Matrix。

---

为什么选择 ODS？

少数几家公司控制着全球绝大部分 AI 流量 — 随之而来的还有你的数据、你的成本和你的可用性。你发送给集中式提供商的每一次查询，都是你不拥有的商业情报，运行在你无法控制的基础设施上，定价条款你无法协商。

如果 AI 正在成为关键基础设施，它就不应该被租用。自托管本地 AI 应该是一项主权人权，而不是一个职业选择。

因为运行自己的 AI 不应该需要计算机学位再搭上一个周末去调试 CUDA 驱动。目前，搭建本地 AI 意味着把十几个项目拼接在一起、从零编写 Docker 配置，然后祈祷一切能够互相通信。大多数人最终放弃，回去继续向 OpenAI 付费。

我们构建 ODS 就是为了让你不必如此。

• 一条命令 — 检测你的 GPU、挑选合适的模型、生成凭据、启动一切
• 2 分钟内开始聊天 — 引导模式（bootstrap mode）让你立即获得一个可用的模型，同时完整模型在后台下载
• 预接线好的完整服务栈 — 聊天、Agent、语音、工作流、搜索、RAG、图像生成、隐私工具、可观测性和开发者工具。开箱即用，彼此互联
• 完全可定制 — 每个服务都是一个扩展。放入一个文件夹，运行 ods enable，完成

手动安装（Linux）

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

Windows（PowerShell）

需要启用 WSL2 后端的 Docker Desktop。 先安装 Docker Desktop，并确保它在开始之前已经运行。

打开一个普通 PowerShell 会话并运行：

$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 "https://github.com/Osmantic/ODS/archive/refs/heads/main.zip" -OutFile $odsZip
Expand-Archive -LiteralPath $odsZip -DestinationPath $odsSrc -Force
cd (Get-ChildItem -LiteralPath $odsSrc -Directory | Select-Object -First 1).FullName
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

Set-ExecutionPolicy 命令允许安装脚本在当前会话中运行。它不会更改你的系统级策略。 不建议以管理员身份运行安装器，因为 .opencode、data/ 和 .env 等用户级路径可能会以管理员拥有的权限创建。

安装器会检测你的 GPU、挑选合适的模型、生成凭据、启动所有服务，并在桌面创建 Dashboard 快捷方式。使用 .\ods.ps1 status 从运行时目录进行管理；使用 .\ods.ps1 uninstall --force 卸载。

macOS（Apple Silicon）

需要 Apple Silicon (M1+) 和 Docker Desktop。 先安装 Docker Desktop，并确保它在开始之前已经运行。

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

安装器会检测你的芯片、为你的统一内存挑选合适的模型、以 Metal 加速原生启动 llama-server，并在 Docker 中启动所有其他服务。使用 ./ods-macos.sh status 进行管理。

详情请参阅 macOS Quickstart。

---

包含什么

聊天与推理

• Open WebUI — 功能完整的聊天界面，支持对话历史、网络搜索、文档上传和 30+ 种语言
• llama-server — 高性能 LLM 推理服务，支持连续批处理（continuous batching），会根据你的 GPU 自动选择；Linux Docker 主机 API 默认在 localhost:11434，原生 macOS/Windows 路径使用 localhost:8080，容器 API 运行在 8080
• LiteLLM — 支持本地/云/混合模式的 API 网关
• TEI Embeddings — 用于 RAG 和搜索工作流的文本 embedding 服务

语音

• Whisper — 语音转文字（speech-to-text）
• Kokoro — 文字转语音（text-to-speech）

Agent 与自动化

• Hermes Agent — 默认的本地优先自治/浏览器 Agent，具备记忆、技能和 magic-link 门控代理
• OpenClaw — 已弃用的遗留自治 Agent，在迁移窗口期内仍可选择性启用
• n8n — 工作流自动化，支持 400+ 集成（Slack、邮件、数据库、API）
• APE — Agent Policy Engine，用于审计和管理自治工具调用
• OpenCode — 基于浏览器的 AI 编程助手，已接入本地技术栈
• Memory Shepherd — host/systemd 辅助工具，用于 Agent 记忆生命周期管理

知识与搜索

• Qdrant — 用于检索增强生成（RAG）的向量数据库
• SearXNG — 自托管网络搜索（无追踪）
• Perplexica — 深度研究引擎
• Brave Search — 可选的付费 Brave Search API 集成

创意

• ComfyUI — 基于节点的图像生成

隐私与运维

• Privacy Shield — 用于 API 调用的 PII 擦除代理
• Dashboard — 实时 GPU 指标、服务健康状态、模型管理
• Dashboard API — 仪表盘背后的服务健康、设置、状态、指标和管理 API
• Token Spy — 本地和代理 LLM 流量的 token 用量监控器
• Langfuse — 可选的 LLM 可观测性和追踪

---

硬件自动检测

安装器会检测你的 GPU，并首先分配一个确定性的硬件层级（hardware tier）。然后 Linux 和 macOS 运行带版本号的目录选择器（ods/scripts/select-model.py），而 Windows 使用 ods/installers/windows/lib/tier-map.ps1 中的 PowerShell 目录选择器；两者都会读取 ods/config/model-library.json，为检测到的内存范围选择最佳可安装 GGUF。最终选择会以 LLM_MODEL、GGUF_FILE、MAX_CONTEXT 和 MODEL_RECOMMENDATION_* 的形式写入 .env。

MODEL_PROFILE=qwen 是默认的非 Gemma 目录配置，因此实际选择可能是 Qwen、Phi 或 DeepSeek，取决于哪个最合适。MODEL_PROFILE=gemma4 在可用时强制使用 Gemma 4，MODEL_PROFILE=auto 在 NVIDIA、Apple Silicon 和 Intel Arc 层级上使用 Gemma 4。使用 ./install.sh --tier 3 覆盖层级选择；使用 MODEL_PROFILE=gemma4 ./install.sh 或 MODEL_PROFILE=auto ./install.sh 覆盖模型家族。

当 Hermes 启用时（这是默认的 Agent 路径），安装器会将首次运行的引导模型保持在 64K 上下文下限，并在所选模型支持的情况下将完整本地模型的上下文提升到 128K。这样既避免了 Hermes 的硬性 64K 最低要求，又保留了 2 分钟内首次聊天的体验。下面的示例是当前目录选择器对常见硬件配置的输出；实际安装可能因检测到的 VRAM/RAM、主机架构、已有下载或显式配置覆盖而有所不同。吞吐量仍需要在首次启动后通过本地基准测试确认。

NVIDIA

层级 / 内存范围	当前默认目录选择	上下文	示例硬件
0 / 8 GB CPU 回退	Qwen3.5 2B (Q4_K_M)	8K	低内存纯 CPU
1 / 8 GB 独立显存	Qwen3.5 9B (Q4_K_M)	32K	RTX 4060, RTX 3060 12GB
2 / 12 GB 独立显存	Phi-4 14B (Q4_K_M)	16K	RTX 4070 级别显卡
3 / 24 GB 独立显存	Qwen3.5 27B (Q4_K_M)	32K	RTX 4090, A6000
4 / 48 GB 独立显存	DeepSeek R1 Distill Llama 70B (Q4_K_M)	32K	A6000 Ada, L40S
NV_ULTRA / 90+ GB amd64 独立显存	Qwen3 Coder Next (Q4_K_M)	128K	多 GPU A100/H100
NV_ULTRA / 90+ GB arm64 统一内存	Qwen3.6 35B-A3B (UD-Q4_K_M)	128K	DGX Spark / GB10 级别主机

AMD Strix Halo（统一内存）

层级 / 内存范围	当前默认目录选择	上下文	硬件
SH_COMPACT / 64 GB 统一内存	Qwen3.6 35B-A3B (UD-Q4_K_M)	128K	Ryzen AI MAX+ 395 (64GB)
SH_LARGE / 96 GB 统一内存	DeepSeek R1 Distill Llama 70B (Q4_K_M)	32K	Ryzen AI MAX+ 395 (96GB)
SH_LARGE / 124 GB 统一内存	Qwen3.6 35B-A3B (UD-Q4_K_M)	128K	Ryzen AI MAX+ 395 (128GB 级别)

选择器会将统一内存主机从 Qwen3 Coder Next 上路由开（如果该模型本来会被选中），因为当前仓库政策记录了这些后端上的正确性问题。

Apple Silicon（统一内存，Metal）

层级 / 内存范围	当前默认目录选择	上下文	示例硬件
0 / 8 GB 统一内存	Phi-4 Mini (Q4_K_M)	128K	M1/M2 基础款 (8GB)
1 / 16 GB 统一内存	Qwen3.5 9B (Q4_K_M)	32K	M4 Mac Mini (16GB)
2 / 32 GB 统一内存	Phi-4 14B (Q4_K_M)	16K	M4 Pro Mac Mini, M3 Max MacBook Pro
3 / 48 GB 统一内存	Qwen3.5 27B (Q4_K_M)	32K	M4 Pro (48GB), M2 Max (48GB)
4 / 64+ GB 统一内存	Qwen3.6 35B-A3B (UD-Q4_K_M)	128K	M2 Ultra Mac Studio, M4 Max (64GB+)

Intel Arc（Linux，SYCL）

层级 / 内存范围	当前默认目录选择	上下文	示例硬件
ARC_LITE / 6 GB 独立显存	Phi-4 Mini (Q4_K_M)	128K	Arc A380
ARC_LITE / 8 GB 独立显存	Qwen3.5 9B (Q4_K_M)	32K	Arc A750
ARC / 16 GB 独立显存	Phi-4 14B (Q4_K_M)	16K	Arc A770 16GB, 较新的 Arc GPU

Gemma 4 配置层级仍保留在安装器层级映射中：入门硬件使用 E2B，中端硬件使用 E4B，专业硬件使用 26B-A4B，大型/超大型硬件使用 31B。

---

引导模式（Bootstrap Mode）

无需等待大文件下载。ODS 默认使用引导模式：

1. 不到一分钟下载一个微小的 1.5B 模型
2. 你立即开始聊天
3. 完整模型在后台下载
4. 准备就绪后热切换到完整模型 — 零停机

引导模型以 64K 上下文窗口启动，以便 Hermes 在首个会话期间正常工作。后台下载完成后，ODS 会切换到完整模型并恢复 Hermes/完整模型的上下文目标。

跳过引导模式：./install.sh --no-bootstrap

---

切换模型

安装器会为你的硬件挑选一个模型，但你随时可以切换：

ods model current              # 当前运行的是什么？
ods model list                 # 显示所有可用层级
ods model swap T3              # 切换到不同层级

如果新模型尚未下载，请先预取：

./scripts/pre-download.sh --tier 3    # 切换前先下载
ods model swap T3                    # 然后切换（会重启 llama-server）

已经有一个想用的 GGUF？将单个 .gguf 文件放入 data/models/，然后打开 Dashboard -> Models 并加载本地条目。对于旧安装或无头维护，请更新 .env 中的 GGUF_FILE 和 LLM_MODEL，然后使用 CLI 重启：

ods restart llm

或者直接从已安装的 ods 目录重启容器：

docker compose restart llama-server

回滚是自动的 — 如果新模型加载失败，ODS 会恢复到之前的模型。

---

可扩展性

ODS 的设计目标就是可以被改造。每个服务都是一个扩展 — 一个包含 manifest.yaml 和 compose.yaml 的文件夹。Dashboard、CLI、健康检查和 compose 技术栈都会自动发现扩展。

extensions/services/
  my-service/
    manifest.yaml      # 元数据：名称、端口、健康端点、GPU 后端
    compose.yaml       # Docker Compose 片段（自动合并到技术栈中）

ods enable my-service     # 启用
ods disable my-service    # 禁用
ods list                  # 查看所有内容

安装器本身也是模块化的 — 19 个库模块、一个共享服务注册表和 13 个有序阶段。想添加一个硬件层级、替换默认模型，或跳过某个阶段？先从安装器架构图开始，这样你可以同时更新 Linux、macOS、Windows、升级和 host-agent 的编写逻辑。

完整扩展指南 | 安装器架构

---

ods-cli

ods CLI 管理你的整个技术栈：

ods status                # 健康检查 + GPU 状态
ods list                  # 所有服务及其状态
ods logs llm              # 跟踪日志（别名：llm, stt, tts）
ods restart [service]     # 重启一个或所有服务
ods start / stop          # 启动或停止技术栈

ods mode cloud            # 通过 LiteLLM 切换到云 API
ods mode local            # 切换回本地推理
ods mode hybrid           # 本地优先，云作为回退

ods model swap T3         # 切换到不同硬件层级
ods enable n8n            # 启用一个扩展
ods disable whisper       # 禁用一个扩展

ods config show           # 查看 .env（密钥已遮蔽）
ods preset save gaming    # 快照当前配置
ods preset load gaming    # 恢复配置

---

对比

其他工具只能让你走一部分路。ODS 让你走完全程。

	ODS	Ollama + Open WebUI	LocalAI
范围	完整 AI 技术栈 — 从推理到 Agent 到工作流	LLM + 聊天	仅 LLM
一键安装	全部，自动配置	仅 LLM + 聊天	仅 LLM
硬件自动检测 + 模型选择	NVIDIA + AMD Strix Halo + Apple Silicon + Intel Arc + CPU/云回退	无	无
AMD APU 统一内存支持	平台特定加速后端，由安装器选择	部分（Vulkan）	无
自治 AI Agent	Hermes Agent 默认；OpenClaw 遗留可选	无	无
工作流自动化	n8n（400+ 集成）	无	无
语音（STT + TTS）	Whisper + Kokoro	无	无
图像生成	ComfyUI	无	无
RAG 流水线	Qdrant + embeddings	无	无
扩展系统	基于 manifest，可热插拔	无	无
多 GPU	是（NVIDIA）	部分	部分

---

文档

Quickstart	带故障排除的分步安装指南
Docs Index	面向运维者、贡献者和审查者的维护文档地图
Build On ODS	Fork、自定义版本、扩展模板和下游验证
Forkability	如何 fork、审计、定制并独立运行 ODS
Maintainer Runbook	面向维护者和 fork 的发布、回滚、验证和运维连续性指南
High-Risk Change Map	哪些变更需要专项检查、集群验证或发布级门禁
Headless Setup	QR 引导、首次启动设置、AP 模式、mDNS 和本地 Agent 访问
Support Matrix	当前平台和 GPU 支持状态
Release Validation	User Green 门禁和发布级集群/发行版验证策略
2.6.0 Release Notes	当前稳定版发布说明、验证凭证和已知验证边界
Validation Matrix	脱敏后的 CI、发行版实验室和真实硬件集群的发布就绪证据
Validation Reproducibility	fork 和运维者如何在自己的硬件上复现验证流程
Offline And Mirroring	固定版本、镜像和保存发布产物以实现独立运行
Installer Trust	先检查再安装的路径、引用固定和当前溯源限制
Model Management	精选和 Hugging Face GGUF 发现、验证导入、切换和恢复
Hardware Guide	买什么硬件、层级推荐
FAQ	常见问题和配置
Extensions	如何添加自定义服务
Installer Architecture	模块化安装器深度解析
Installer Phase Contracts	阶段所有权、幂等性、失败模式和验证预期
Compose Resolver Contracts	compose 层、扩展、后端、端口和模式覆盖的规则
Changelog	版本历史和发布说明
Contributing	如何贡献

---

贡献者与致谢

ODS 由一个不断壮大的贡献者群体共同构建，涵盖安装器、GPU 支持、Dashboard、安全、扩展、文档和发布验证。README 保持产品概览的聚焦；完整的致谢、上游鸣谢和贡献者历史记录在 CONTRIBUTORS.md 中。

ODS 已获得本地 AI 和开发者社区的认可，包括 AMD Featured Developer 认可、入选 2026 年 5 月 AMD Lemonade Developer Challenge 获奖者，以及在 Pennovation Works 举办的 (Co)nnect: Philly's AI Ecosystem Summit 上的专题展示。

---

许可证

Apache 2.0 — 自由使用、修改和分发。请参阅 LICENSE。

---

由 Osmantic 以及不断壮大的、拒绝租用本该拥有的东西的抵抗力量共同构建。