wehub-resource-sync
656bed4966
24 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
ODS
Osmantic Deployment System
将你的 PC、Mac 或 Linux 机器变成私有 AI 服务器。
AI 服务器与 homelab（家庭实验室）搭建正在迅速成为一项已解决的问题。 每个人都理应如此感受。
ODS 会安装并串联你在本地运行 AI 所需的一切，你无需再手动拼装 Ollama、Open WebUI、n8n、ComfyUI 以及各类隐私工具：
- 本地模型推理（local model inference） — 在你自己的硬件上运行开源模型
- ChatGPT 风格 Web UI — 从任意浏览器与你的模型对话
- 控制面板（control dashboard） — 在一个地方管理模型、服务、配置、GPU 状态与扩展
- 语音、智能体与工作流 — 构建能听、能说、调用工具并完成任务的自动化
- RAG 与搜索 — 连接本地文档、私有搜索与检索工作流
- 图像生成 — 运行本地图像工具，无需将提示词发送到托管 API
- 隐私与运维 — 将服务认证、密钥、可观测性与诊断集中在一套本地栈中
无需云端。无需订阅。你的提示词和数据留在本机，除非你主动选择其他方式。需要时，云端与混合 API 模式为可选项。
发布验证： 运维变更会通过发布级 fleet 与发行版实验室（distro lab）校验：零前置依赖引导、全新安装、产品流程、全模型能力、生命周期恢复，以及最终的 User Green（用户绿灯）关卡。请参阅 Release Validation 了解一次 green run 所证明的内容。
仓库结构： 仓库根目录存放公开 README、安装器、安全策略、GitHub workflows 与项目协作文档。ods/ 目录是产品运行时：服务、安装阶段、compose overlays、dashboard、CLI、测试与运维文档。
稳定版使用： v2.5.2 是当前稳定发布版。main 迭代较快；用于活跃开发与验证候选。对于 fork、一体机、实验室或类生产安装，请固定（pin）带标签的发布版或经审计的 commit，并保留你自己的验证记录。稳定补丁修复会先落在 release/2.5.x，再向前合并。请参阅 Release Channels、Installer Trust 与 Forkability。
快速开始
Linux 与 macOS：
curl -fsSL https://raw.githubusercontent.com/Light-Heart-Labs/ODS/main/ods/get-ods.sh | bash
想先检查再运行，或固定某个发布标签？请参阅 Installer Trust。
Windows 用户应使用下方所示的 PowerShell 安装器，或参阅 Windows Quickstart。
安装完成后，打开 http://localhost:3000 并开始聊天。
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
初次接触？ 阅读 Friendly Guide，或 收听音频版 — 完整讲解 ODS 是什么、如何工作，以及如何把它变成你自己的。无需技术背景。
一览
| 问题 | 答案 |
|---|---|
| 它是什么？ | 面向自有硬件的本地 AI 服务器栈，提供 Linux/macOS 一键安装器与 Windows PowerShell 安装器。 |
| 适合谁？ | 希望在家、实验室或工作站上获得私有 AI，而无需手动串联十几个服务的人。 |
| 我能得到什么？ | 本地推理、Open WebUI 聊天、控制面板、语音、智能体、工作流、RAG、搜索、图像生成、隐私工具、可观测性与开发者工具。 |
| 运行在什么上？ | Linux、带 WSL2/Docker Desktop 的 Windows，以及 macOS Apple Silicon。 |
| 需要云端吗？ | 不需要。本地模式为默认；云端与混合 API 模式为可选。 |
| 如果你了解... | ODS 额外提供... |
|---|---|
| Ollama / llama.cpp | 围绕其外的服务器栈：聊天、面板、语音、RAG、工作流、智能体、隐私与服务管理。 |
| Open WebUI | 围绕 Open WebUI 的完整安装器与控制平面，以及预接线的本地服务。 |
| AnythingLLM | 超越 RAG 的更广本地 AI 一体机能力：推理、聊天、语音、工作流、图像生成与运维。 |
| 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 分钟即可聊天 — 引导模式在完整模型后台下载时，立即给你一个可用模型
- 完整服务栈，预接线 — 聊天、智能体、语音、工作流、搜索、RAG、图像生成、隐私工具、可观测性与开发者工具，开箱即用、彼此互通
- 完全可改装 — 每个服务都是扩展。放入一个文件夹，运行
ods enable，完成
ODSGATE 安装程序会处理一切——GPU 检测、模型选择与服务编排。
手动安装（Linux）
git clone https://github.com/Light-Heart-Labs/ODS.git
cd ODS/ods
./install.sh
Windows（PowerShell）
需要启用 WSL2 后端的 Docker Desktop with WSL2 backend enabled. 请先安装 Docker Desktop，并在开始前确保其正在运行。
打开一个普通的 PowerShell 会话并运行：
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
git clone https://github.com/Light-Heart-Labs/ODS.git
cd ODS
.\install.ps1
Set-ExecutionPolicy命令允许安装脚本在当前会话中运行。它不会更改你的系统级策略。 不建议以管理员身份运行安装程序，因为.opencode、data/和.env等用户级路径可能会以管理员拥有的权限创建。
安装程序会检测你的 GPU、选择合适模型、生成凭据、启动所有服务，并创建指向 Dashboard 的桌面快捷方式。使用 .\ods\installers\windows\ods.ps1 status 进行管理。
macOS（Apple Silicon）
需要 Apple Silicon（M1+）和 Docker Desktop. 请先安装 Docker Desktop，并在开始前确保其正在运行。
git clone https://github.com/Light-Heart-Labs/ODS.git
cd ODS/ods
./install.sh
安装程序会检测你的芯片、根据统一内存选择合适模型，以 Metal 加速原生启动 llama-server，并在 Docker 中启动所有其他服务。使用 ./ods-macos.sh status 进行管理。
详见 macOS 快速入门。
开箱即用
聊天与推理
- 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 与搜索工作流的文本嵌入服务
语音
- Whisper — 语音转文字（speech-to-text）
- Kokoro — 文字转语音（text-to-speech）
智能体与自动化
- Hermes Agent — 默认的本地优先自主/浏览器智能体，具备记忆、技能，以及魔法链接（magic-link）门控代理
- OpenClaw — 已弃用的旧版自主智能体，在迁移窗口期内仍可自愿启用
- n8n — 工作流自动化，集成 400+ 种服务（Slack、邮件、数据库、API）
- APE — 智能体策略引擎（Agent Policy Engine），用于审计与治理自主工具调用
- OpenCode — 基于浏览器的 AI 编程助手，已接入本地技术栈
- Memory Shepherd — 用于智能体记忆生命周期管理的宿主机/systemd 辅助工具
知识与搜索
- Qdrant — 用于检索增强生成（RAG）的向量数据库
- SearXNG — 自托管网页搜索（无追踪）
- Perplexica — 深度研究引擎
- Brave Search — 可选的付费 Brave Search API 集成
创意
- ComfyUI — 基于节点的图像生成
隐私与运维
- Privacy Shield — 用于 API 调用的 PII 脱敏代理
- Dashboard — 实时 GPU 指标、服务健康状态、模型管理
- Dashboard API — Dashboard 背后的服务健康、设置、状态、指标与管理 API
- Token Spy — 本地与代理 LLM 流量的 token 用量监控
- Langfuse — 可选的 LLM 可观测性与追踪
硬件自动检测
安装程序会检测你的 GPU，并首先分配一个确定性的硬件层级（tier）。Linux 与 macOS 随后运行带版本号的目录选择器（ods/scripts/select-model.py），而 Windows 使用 ods/installers/windows/lib/tier-map.ps1 中的 PowerShell 目录选择器；两者都会读取 ods/config/model-library.json，以根据检测到的内存容量选择最佳可安装 GGUF。最终选择会写入 .env，对应 LLM_MODEL、GGUF_FILE、MAX_CONTEXT 和 MODEL_RECOMMENDATION_*。
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 启用时（这是默认的智能体路径），安装程序会将首次运行的引导模型保持在 64K 上下文下限，并在所选模型支持的情况下将完整本地模型上下文提升至 128K。这样既能满足 Hermes 硬性 64K 最低要求，又能保留首次聊天不到 2 分钟的体验。以下示例是当前目录选择器在常见硬件容量下的输出；实际安装可能因检测到的 VRAM/RAM、主机架构、已有下载或显式配置覆盖而有所不同。首次启动后，吞吐量仍需进行本地基准测试。
NVIDIA
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 示例硬件 |
|---|---|---|---|
| 0 / 8 GB CPU 回退 | Qwen3.5 2B (Q4_K_M) | 8K | 低内存纯 CPU |
| 1 / 8 GB 独立 VRAM | Qwen3.5 9B (Q4_K_M) | 32K | RTX 4060、RTX 3060 12GB |
| 2 / 12 GB 独立 VRAM | Phi-4 14B (Q4_K_M) | 16K | RTX 4070 级别显卡 |
| 3 / 24 GB 独立 VRAM | Qwen3.5 27B (Q4_K_M) | 32K | RTX 4090、A6000 |
| 4 / 48 GB 独立 VRAM | DeepSeek R1 Distill Llama 70B (Q4_K_M) | 32K | A6000 Ada、L40S |
| NV_ULTRA / 90+ GB amd64 独立 VRAM | 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 统一 RAM | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | Ryzen AI MAX+ 395 (64GB) |
| SH_LARGE / 96 GB 统一 RAM | DeepSeek R1 Distill Llama 70B (Q4_K_M) | 32K | Ryzen AI MAX+ 395 (96GB) |
| SH_LARGE / 124 GB 统一 RAM | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | Ryzen AI MAX+ 395 (128GB 级别) |
当否则会选中 Qwen3 Coder Next 时，选择器会将统一内存主机路由到其他模型，因为当前仓库策略文档记录了这些后端上的正确性问题。
Apple Silicon（统一内存，Metal）
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 示例硬件 |
|---|---|---|---|
| 0 / 8 GB 统一 RAM | Phi-4 Mini (Q4_K_M) | 128K | M1/M2 基础款 (8GB) |
| 1 / 16 GB 统一 RAM | Qwen3.5 9B (Q4_K_M) | 32K | M4 Mac Mini (16GB) |
| 2 / 32 GB 统一 RAM | Phi-4 14B (Q4_K_M) | 16K | M4 Pro Mac Mini、M3 Max MacBook Pro |
| 3 / 48 GB 统一 RAM | Qwen3.5 27B (Q4_K_M) | 32K | M4 Pro (48GB)、M2 Max (48GB) |
| 4 / 64+ GB 统一 RAM | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | M2 Ultra Mac Studio、M4 Max (64GB+) |
Intel Arc（Linux，SYCL）
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 示例硬件 |
|---|---|---|---|
| ARC_LITE / 6 GB 独立 VRAM | Phi-4 Mini (Q4_K_M) | 128K | Arc A380 |
| ARC_LITE / 8 GB 独立 VRAM | Qwen3.5 9B (Q4_K_M) | 32K | Arc A750 |
| ARC / 16 GB 独立 VRAM | Phi-4 14B (Q4_K_M) | 16K | Arc A770 16GB、较新 Arc GPU |
Gemma 4 配置层级仍保留在安装程序的层级映射中：入门级硬件为 E2B，中端硬件为 E4B，专业级硬件为 26B-A4B，大型/旗舰级硬件为 31B。
引导模式（Bootstrap Mode）
无需等待大型下载。ODS 默认使用引导模式：
- 不到一分钟即可下载一个 1.5B 的小型模型
- 可立即开始聊天
- 完整模型在后台下载
- 就绪后热切换到完整模型——零停机
安装程序会并行拉取所有服务。下载支持断点续传——中断后可从上次位置继续。
引导模型（bootstrap model）初始提供 64K 上下文窗口，以便 Hermes 在首次会话期间可用。后台下载完成后，ODS 会切换到完整模型，并恢复 Hermes/完整模型的上下文目标。
跳过引导：./install.sh --no-bootstrap
切换模型
安装程序会根据你的硬件选择模型，但你可随时切换：
ods model current # What's running now?
ods model list # Show all available tiers
ods model swap T3 # Switch to a different tier
若新模型尚未下载，请先预取：
./scripts/pre-download.sh --tier 3 # Download before switching
ods model swap T3 # Then swap (restarts llama-server)
已有想使用的 GGUF？将单个 .gguf 文件放入
data/models/，然后打开 Dashboard -> Models 并加载本地条目。对于
较旧安装或无头（headless）维护，在
.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 # Metadata: name, port, health endpoint, GPU backends
compose.yaml # Docker Compose fragment (auto-merged into the stack)
ods enable my-service # Enable it
ods disable my-service # Disable it
ods list # See everything
安装程序本身也是模块化的——19 个库模块、共享服务注册表，以及 13 个有序阶段。想新增硬件层级、更换默认模型或跳过某个阶段？先从安装程序架构图入手，以便同步更新 Linux、macOS、Windows、升级与 host-agent 编写器。
ods-cli
ods CLI 管理你的整个栈：
ods status # Health checks + GPU status
ods list # All services and their state
ods logs llm # Tail logs (aliases: llm, stt, tts)
ods restart [service] # Restart one or all services
ods start / stop # Start or stop the stack
ods mode cloud # Switch to cloud APIs via LiteLLM
ods mode local # Switch back to local inference
ods mode hybrid # Local primary, cloud fallback
ods model swap T3 # Switch to a different hardware tier
ods enable n8n # Enable an extension
ods disable whisper # Disable one
ods config show # View .env (secrets masked)
ods preset save gaming # Snapshot current config
ods preset load gaming # Restore it
对比
其他工具只能帮你走一部分路。ODS 能带你走完全程。
| ODS | Ollama + Open WebUI | LocalAI | |
|---|---|---|---|
| 范围 | 完整 AI 栈——从推理到智能体再到工作流 | LLM + 聊天 | 仅 LLM |
| 一键安装 | 全部组件，自动配置 | 仅 LLM + 聊天 | 仅 LLM |
| 硬件自动检测 + 模型选择 | NVIDIA + AMD Strix Halo + Apple Silicon + Intel Arc + CPU/云回退 | 否 | 否 |
| AMD APU 统一内存支持 | 平台专用加速后端，由安装程序选择 | 部分（Vulkan） | 否 |
| 自主 AI 智能体 | 默认 Hermes Agent；OpenClaw 遗留可选 | 否 | 否 |
| 工作流自动化 | n8n（400+ 集成） | 否 | 否 |
| 语音（STT + TTS） | Whisper + Kokoro | 否 | 否 |
| 图像生成 | ComfyUI | 否 | 否 |
| RAG 流水线 | Qdrant + embeddings | 否 | 否 |
| 扩展系统 | 基于 manifest，支持热插拔 | 否 | 否 |
| 多 GPU | 是（NVIDIA） | 部分 | 部分 |
文档
| 快速入门 | 分步安装指南，含故障排除 |
| 文档索引 | 面向运维人员、贡献者与审阅者的维护地图 |
| 基于 ODS 构建 | Fork、定制版本、扩展模板与下游验证 |
| 可 Fork 性 | 如何 fork、审计、定制并独立运营 ODS |
| 维护者运行手册 | 面向维护者与 fork 的发布、回滚、验证及运维连续性指南 |
| 高风险变更地图 | 哪些变更需要重点检查、机群验证或发布级门禁 |
| 无头设置 | QR 引导、首次启动设置、AP 模式、mDNS 及本地智能体访问 |
| 支持矩阵 | 当前平台与 GPU 支持状态 |
| 发布验证 | User Green 门禁及发布级机群/发行版验证策略 |
| 验证矩阵 | 脱敏 CI、发行版实验室与真实硬件机群的发布就绪证据 |
| 验证可复现性 | fork 与运维人员如何在自己的硬件上复现验证流程 |
| 离线与镜像 | 固定版本、镜像并保留发布制品以支持独立运营 |
| 安装程序信任 | 先检查后安装路径、ref 固定及当前来源追溯限制 |
| 模型管理 | Dashboard 模型下载、切换及手动 GGUF 工作流 |
| 硬件指南 | 选购建议与层级推荐 |
| 常见问题 | 常见问题与配置 |
| 扩展 | 如何添加自定义服务 |
| 安装程序架构 | 模块化安装程序深度解析 |
| 安装程序阶段契约 | 阶段归属、幂等性、失败模式与验证预期 |
| Compose 解析器契约 | compose 层、扩展、后端、端口与模式叠加规则 |
| 变更日志 | 版本历史与发布说明 |
| 贡献指南 | 如何参与贡献 |
贡献者与认可
ODS 由不断壮大的贡献者团队在安装程序、GPU 支持、Dashboard、安全、扩展、文档与发布验证等领域共同构建。README 聚焦产品概览；详细致谢、上游鸣谢与贡献者历史见 CONTRIBUTORS.md。
ODS 已获得本地 AI 与开发者社区认可，包括 AMD Featured Developer 认可、入选 2026 年 5 月 AMD Lemonade Developer Challenge 获奖者，并在 (Co)nnect: Philly's AI Ecosystem Summit at Pennovation Works 上亮相。
许可证
Apache 2.0 — 随意使用、修改、发布。详见 LICENSE。
由 Light Heart Labs 与不断壮大的、拒绝租用本应拥有之物的抵抗力量共同打造。