ODS (Osmantic Deployment System) 私有 AI 服务器详细部署教程

ODS 是一套能让你在 PC、Mac 或 Linux 电脑上，通过一条命令就把整个本地 AI 服务器跑起来的系统。它集成了本地模型推理、ChatGPT 风格的 Web 界面、语音、智能体、工作流、RAG 和图像生成等功能，开箱即用。本教程将指导你完成部署。

📋 目录

ODS 是什么
硬件要求与准备
一键安装（推荐）
手动安装（源码）
首次启动与配置
核心功能与使用
模型管理
扩展与自定义
更新与卸载
常见问题排查

ODS 是什么

ODS 不是一个单一软件，而是一个本地 AI 应用栈。它把多个优秀的开源 AI 工具整合在一起，并处理好了它们之间的配置和通信。

你得到的是一整套：

聊天界面：功能完整的 Open WebUI。
模型推理：通过 llama-server 运行 GGUF 格式模型，支持 NVIDIA、AMD、Apple Silicon 和 Intel Arc GPU。
语音能力：Whisper（语音转文字）和 Kokoro（文字转语音）。
智能体：Hermes Agent (默认) 用于自主任务，n8n 用于工作流自动化。
RAG 与搜索：Qdrant 向量数据库、SearXNG 元搜索引擎。
图像生成：ComfyUI。
控制面板：用于监控 GPU、管理模型和服务的 Web 仪表板。
隐私与运维：PII 过滤、Token 监控、Langfuse 追踪等。

核心原则：本地优先，数据归你。所有处理默认在本地完成。可选云端 API 模式。

硬件要求与准备

基本要求

操作系统：Linux（Ubuntu 24.04/22.04、Debian 12、Fedora 41+ 等）、Windows（需 Docker Desktop + WSL2）、macOS（Apple Silicon M1+）。
Docker：必需，且必须正在运行。
- Windows：安装 Docker Desktop，并启用 WSL2 后端。在普通的 PowerShell（非管理员）中运行。
- macOS：安装 Docker Desktop。
网络：需要互联网连接以下载安装脚本和模型文件。

硬件建议

内存：至少 8GB（16GB+ 更佳，用于运行较大模型）。
GPU（可选但强烈推荐）：NVIDIA、AMD、Apple Silicon 或 Intel Arc 显卡可大幅提升推理速度。无 GPU 也可运行（纯 CPU 模式或云端模式）。
存储：至少 20GB 可用空间（模型文件通常数 GB）。

一键安装（推荐）

这是最快的方式，脚本会自动检测硬件、下载模型、配置并启动所有服务。

Linux 或 macOS

打开终端，执行以下命令：

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

脚本运行过程中，会检测你的 GPU 并自动下载适配的模型。

Windows (PowerShell)

确保 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

安装完成后，桌面上会创建一个 Dashboard 快捷方式。

手动安装（源码）

如果一键安装不适合，或你想使用特定分支，可以手动克隆并运行。

Linux / macOS:

1
2
3

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

Windows (PowerShell):

1
2
3

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

首次启动与配置

安装成功后，脚本会自动启动所有服务。

访问 Web UI：打开浏览器，访问 http://localhost:3000。你会看到 Open WebUI 的登录界面。
注册账户：首次访问需要创建管理员账户。按照页面提示设置用户名和密码。
开始聊天：登录后，你已可以直接在 Web 界面与默认加载的模型进行对话了。

可选：切换到云端模式
如果你想用 OpenAI、Anthropic 等云端模型，可以在安装时添加 --cloud 参数，或在安装后使用 CLI 切换：

1
2
3

ods mode cloud   # 切换到云端模式
ods mode local   # 切回本地模式
ods mode hybrid  # 本地为主，云端备用

核心功能与使用

使用 `ods` CLI 管理服务

安装后，ods 命令会添加到 PATH。你可以在终端中管理整个 stack：

ods status           # 查看所有服务状态和 GPU 信息
ods list             # 列出所有服务及其状态
ods logs llm         # 查看模型服务日志
ods restart          # 重启所有服务
ods stop / start     # 停止/启动整个 stack
ods config show      # 查看当前配置（敏感信息已隐藏）

访问各个服务

聊天界面：http://localhost:3000 (Open WebUI)
控制面板：通过 Open WebUI 界面左下角的设置进入，或访问 http://localhost:3000/admin
ComfyUI (图像生成)：默认端口未直接映射，可通过仪表板或 ods enable comfyui 启用并访问对应端口。
n8n (工作流)：http://localhost:5678 (若已启用)

模型管理

ODS 会自动为你的硬件选择并下载合适的模型。

查看和切换模型

1
2
3

ods model current     # 查看当前运行的模型
ods model list        # 列出所有可用模型和硬件层级
ods model swap T3     # 切换到层级 3 的模型（会热切换）

手动下载模型

如果想提前下载另一个层级的模型：

1	./scripts/pre-download.sh --tier 3

使用自己的 GGUF 文件

将你的 .gguf 文件放入 ods/data/models/ 目录，然后打开 Dashboard (Web UI 的设置) -> Models -> 加载本地模型，或手动更新 .env 文件中的 GGUF_FILE 变量。

扩展与自定义

ODS 设计为高度可扩展。每个服务都是一个扩展，位于 ods/extensions/services/ 目录下。

启用/禁用扩展：

1
2
3

ods enable n8n       # 启用 n8n 工作流服务
ods disable whisper  # 禁用 Whisper 语音服务
ods list             # 查看所有已启用和可用的扩展

创建自己的扩展：只需在 extensions/services/ 下创建一个包含 manifest.yaml 和 compose.yaml 的文件夹即可。manifest.yaml 描述元数据，compose.yaml 定义 Docker 服务。

更新与卸载

更新 ODS

进入 ODS 安装目录（默认是用户目录下的 ods 或 ~/ods）：cd ~/ods
拉取最新代码：git pull (若通过源码安装)
运行更新脚本：./install.sh (会自动检测并升级)
重启服务：ods restart

卸载 ODS