docs: make Chinese README the default
Dashboard / frontend (push) Has been cancelled
Dashboard / api (push) Has been cancelled
Lint PowerShell / powershell-lint (ubuntu-latest) (push) Has been cancelled
Matrix Smoke / distro: rocky-9 (push) Has been cancelled
Validate .env Schema / tier-0-env-validation (push) Has been cancelled
Validate .env Schema / tier-1-env-validation (push) Has been cancelled
Validate .env Schema / tier-4-env-validation (push) Has been cancelled
Lint PowerShell / powershell-lint (windows-latest) (push) Has been cancelled
ShellCheck / Lint shell scripts (push) Has been cancelled
Python Lint / Lint Python with Ruff (push) Has been cancelled
Matrix Smoke / linux-smoke (push) Has been cancelled
Matrix Smoke / distro: archlinux (push) Has been cancelled
Matrix Smoke / distro: cachyos (push) Has been cancelled
Matrix Smoke / distro: debian-12 (push) Has been cancelled
Matrix Smoke / distro: fedora-41 (push) Has been cancelled
Matrix Smoke / distro: linux-mint-21.3 (push) Has been cancelled
Matrix Smoke / distro: manjaro (push) Has been cancelled
Matrix Smoke / distro: opensuse-tw (push) Has been cancelled
Matrix Smoke / distro: ubuntu-22.04 (push) Has been cancelled
Matrix Smoke / distro: ubuntu-24.04 (push) Has been cancelled
Matrix Smoke / macos-smoke (push) Has been cancelled
Secret Scan / Scan for secrets (push) Has been cancelled
Test Linux / integration-smoke (push) Has been cancelled
Validate .env Schema / tier-2-env-validation (push) Has been cancelled
Validate .env Schema / tier-3-env-validation (push) Has been cancelled

This commit is contained in:
wehub-resource-sync
2026-07-13 10:21:27 +00:00
parent c0116dc33a
commit 656bed4966
+201 -216
View File
@@ -1,13 +1,19 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理,属于社区翻译,非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/Light-Heart-Labs/DreamServer) · [上游 README](https://github.com/Light-Heart-Labs/DreamServer/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
<div align="center">
# ODS
**Osmantic Deployment System**
**Turn your PC, Mac, or Linux box into a private AI server.**
**将你的 PCMac Linux 机器变成私有 AI 服务器。**
AI server and homelab setup is rapidly becoming a solved problem.
It should feel that way for everyone.
AI 服务器与 homelab(家庭实验室)搭建正在迅速成为一项已解决的问题。
每个人都理应如此感受。
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/Light-Heart-Labs/ODS)](https://github.com/Light-Heart-Labs/ODS/stargazers)
@@ -19,141 +25,120 @@ It should feel that way for everyone.
---
ODS installs and wires together everything you need to run AI locally, so you do not have to assemble Ollama, Open WebUI, n8n, ComfyUI, and privacy tools by hand:
ODS 会安装并串联你在本地运行 AI 所需的一切,你无需再手动拼装 OllamaOpen WebUIn8nComfyUI 以及各类隐私工具:
- **Local model inference** — run open models on your own hardware
- **ChatGPT-style web UI** — talk to your models from any browser
- **Control dashboard** — manage models, services, setup, GPU status, and extensions from one place
- **Voice, agents, and workflows** — build automations that can listen, speak, call tools, and get work done
- **RAG and search** — connect local documents, private search, and retrieval workflows
- **Image generation** — run local image tools without sending prompts to a hosted API
- **Privacy and ops** — keep service auth, secrets, observability, and diagnostics in one local stack
- **本地模型推理(local model inference** — 在你自己的硬件上运行开源模型
- **ChatGPT 风格 Web UI** — 从任意浏览器与你的模型对话
- **控制面板(control dashboard** — 在一个地方管理模型、服务、配置、GPU 状态与扩展
- **语音、智能体与工作流** — 构建能听、能说、调用工具并完成任务的自动化
- **RAG 与搜索** — 连接本地文档、私有搜索与检索工作流
- **图像生成** — 运行本地图像工具,无需将提示词发送到托管 API
- **隐私与运维** — 将服务认证、密钥、可观测性与诊断集中在一套本地栈中
No cloud required. No subscriptions required. Your prompts and data stay on your machine unless you choose otherwise. Cloud and hybrid API modes are optional when you want them.
无需云端。无需订阅。你的提示词和数据留在本机,除非你主动选择其他方式。需要时,云端与混合 API 模式为可选项。
**Release validation:** Operational changes are checked with a release-grade
fleet and distro lab: zero-prereq bootstrap, fresh installs, product flows,
full-model capabilities, lifecycle recovery, and the final User Green gate. See
[Release Validation](ods/docs/RELEASE_VALIDATION.md) for what a green
run proves.
**发布验证:** 运维变更会通过发布级 fleet 与发行版实验室(distro lab)校验:零前置依赖引导、全新安装、产品流程、全模型能力、生命周期恢复,以及最终的 User Green(用户绿灯)关卡。请参阅 [Release Validation](ods/docs/RELEASE_VALIDATION.md) 了解一次 green run 所证明的内容。
**Repo layout:** the repository root holds the public README, installers,
security policy, GitHub workflows, and project coordination docs. The
`ods/` directory is the product runtime: services, installer phases,
compose overlays, dashboard, CLI, tests, and operator docs.
**仓库结构:** 仓库根目录存放公开 README、安装器、安全策略、GitHub workflows 与项目协作文档。`ods/` 目录是产品运行时:服务、安装阶段、compose overlays、dashboard、CLI、测试与运维文档。
**Stable consumption:** `v2.5.2` is the current stable release. `main` moves
quickly; use it for active development and validation candidates. For forks,
appliances, labs, or production-like installs, pin a tagged release or audited
commit and keep your own validation receipt. Stable patch fixes land on
`release/2.5.x` before being merged forward. See
[Release Channels](ods/docs/RELEASE_CHANNELS.md),
[Installer Trust](ods/docs/INSTALLER_TRUST.md), and
[Forkability](ods/docs/FORKABILITY.md).
**稳定版使用:** `v2.5.2` 是当前稳定发布版。`main` 迭代较快;用于活跃开发与验证候选。对于 fork、一体机、实验室或类生产安装,请固定(pin)带标签的发布版或经审计的 commit,并保留你自己的验证记录。稳定补丁修复会先落在 `release/2.5.x`,再向前合并。请参阅 [Release Channels](ods/docs/RELEASE_CHANNELS.md)、[Installer Trust](ods/docs/INSTALLER_TRUST.md) 与 [Forkability](ods/docs/FORKABILITY.md)。
## Get Started
## 快速开始
Linux and macOS:
Linux macOS
```bash
curl -fsSL https://raw.githubusercontent.com/Light-Heart-Labs/ODS/main/ods/get-ods.sh | bash
```
Prefer to inspect before running or pin a release tag? See
[Installer Trust](ods/docs/INSTALLER_TRUST.md).
想先检查再运行,或固定某个发布标签?请参阅 [Installer Trust](ods/docs/INSTALLER_TRUST.md)。
Windows users should use the PowerShell installer shown below or follow the [Windows Quickstart](ods/docs/WINDOWS-QUICKSTART.md).
Windows 用户应使用下方所示的 PowerShell 安装器,或参阅 [Windows Quickstart](ods/docs/WINDOWS-QUICKSTART.md)
After install, open **http://localhost:3000** and start chatting.
安装完成后,打开 **http://localhost:3000** 并开始聊天。
> **API endpoint:** Linux Docker installs expose llama-server on **http://localhost:11434** by default (`OLLAMA_PORT`) while containers use `llama-server:8080`. macOS native Metal and Windows native/Lemonade paths use **http://localhost:8080** unless overridden. Open WebUI stays on **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**.
> **No GPU?** ODS also runs in cloud mode — same full stack, powered by OpenAI/Anthropic/Together APIs instead of local inference:
> **没有 GPU** ODS 也可运行于云端模式 — 同一完整栈,由 OpenAI/Anthropic/Together API 驱动,而非本地推理:
> ```bash
> ./install.sh --cloud
> ```
> **Port conflicts?** Every port is configurable via environment variables. See [`.env.example`](ods/.env.example) for the full list, or override at install time:
> **端口冲突?** 每个端口均可通过环境变量配置。完整列表见 [`.env.example`](ods/.env.example),或在安装时覆盖:
> ```bash
> WEBUI_PORT=9090 ./install.sh
> ```
![ODS Dashboard](ods/docs/images/dashboard.png)
**New here?** Read the [Friendly Guide](ods/docs/HOW-ODS-SERVER-WORKS.md) or [listen to the audio version](https://open.spotify.com/episode/40MvqJ41bC8cEgvUyOyE3K) — a complete walkthrough of what ODS is, how it works, and how to make it your own. No technical background needed.
**初次接触?** 阅读 [Friendly Guide](ods/docs/HOW-ODS-SERVER-WORKS.md),或 [收听音频版](https://open.spotify.com/episode/40MvqJ41bC8cEgvUyOyE3K) — 完整讲解 ODS 是什么、如何工作,以及如何把它变成你自己的。无需技术背景。
---
## At A Glance
## 一览
| Question | Answer |
| 问题 | 答案 |
|----------|--------|
| **What is it?** | A local AI server stack for your own hardware, with a one-command Linux/macOS installer and a PowerShell installer for Windows. |
| **Who is it for?** | People who want private AI at home, in a lab, or on a workstation without hand-wiring a dozen services. |
| **What do I get?** | Local inference, Open WebUI chat, a control dashboard, voice, agents, workflows, RAG, search, image generation, privacy tools, observability, and developer tools. |
| **What does it run on?** | Linux, Windows with WSL2/Docker Desktop, and macOS Apple Silicon. |
| **Is cloud required?** | No. Local mode is the default; cloud and hybrid API modes are optional. |
| **它是什么?** | 面向自有硬件的本地 AI 服务器栈,提供 Linux/macOS 一键安装器与 Windows PowerShell 安装器。 |
| **适合谁?** | 希望在家、实验室或工作站上获得私有 AI,而无需手动串联十几个服务的人。 |
| **我能得到什么?** | 本地推理、Open WebUI 聊天、控制面板、语音、智能体、工作流、RAG、搜索、图像生成、隐私工具、可观测性与开发者工具。 |
| **运行在什么上?** | Linux、带 WSL2/Docker Desktop 的 Windows,以及 macOS Apple Silicon |
| **需要云端吗?** | 不需要。本地模式为默认;云端与混合 API 模式为可选。 |
| If you know... | ODS adds... |
| 如果你了解... | ODS 额外提供... |
|----------------|----------------------|
| **Ollama / llama.cpp** | The surrounding server stack: chat, dashboard, voice, RAG, workflows, agents, privacy, and service management. |
| **Open WebUI** | A full installer and control plane around Open WebUI, plus pre-wired local services. |
| **AnythingLLM** | Broader local AI appliance behavior beyond RAG: inference, chat, voice, workflows, image generation, and ops. |
| **n8n self-hosted AI starter kits** | Workflow automation as one part of a larger private AI server. |
| **Ollama / llama.cpp** | 围绕其外的服务器栈:聊天、面板、语音、RAG、工作流、智能体、隐私与服务管理。 |
| **Open WebUI** | 围绕 Open WebUI 的完整安装器与控制平面,以及预接线的本地服务。 |
| **AnythingLLM** | 超越 RAG 的更广本地 AI 一体机能力:推理、聊天、语音、工作流、图像生成与运维。 |
| **n8n 自托管 AI starter kits** | 作为更大私有 AI 服务器一部分的工作流自动化。 |
---
> **Current Platform Support**
> **当前平台支持**
>
> | Platform | Status |
> | 平台 | 状态 |
> |----------|--------|
> | **Linux** (NVIDIA + AMD + Intel Arc) | **Supported** — install and run today |
> | **Windows** (NVIDIA + AMD) | **Supported** — install and run today |
> | **macOS** (Apple Silicon) | **Supported** — install and run today |
> | **Linux**NVIDIA + AMD + Intel Arc | **已支持** — 今日即可安装运行 |
> | **Windows**NVIDIA + AMD | **已支持** — 今日即可安装运行 |
> | **macOS**Apple Silicon | **已支持** — 今日即可安装运行 |
>
> **Tested Linux distros:** Ubuntu 24.04/22.04, Debian 12, Linux Mint 21.3, Fedora 41+, Rocky Linux 9, Arch Linux, Manjaro, CachyOS, and openSUSE Tumbleweed. Other distros using apt, dnf, pacman, or zypper should also work — [open an issue](https://github.com/Light-Heart-Labs/ODS/issues) if yours doesn't.
> **已测试 Linux 发行版:** Ubuntu 24.04/22.04Debian 12Linux Mint 21.3Fedora 41+Rocky Linux 9Arch LinuxManjaroCachyOS openSUSE Tumbleweed。使用 aptdnfpacman zypper 的其他发行版通常也可用 — 若你的不行,请 [提交 issue](https://github.com/Light-Heart-Labs/ODS/issues)
>
> **Release validation:** Operational changes run through a release-grade gate
> that covers zero-prereq bootstrap, clean installs, product behavior,
> full-model capabilities, lifecycle recovery, and User Green. See
> [Release Validation](ods/docs/RELEASE_VALIDATION.md) and the
> [Validation Matrix](ods/docs/VALIDATION-MATRIX.md).
> **发布验证:** 运维变更会经过发布级关卡,覆盖零前置依赖引导、干净安装、产品行为、全模型能力、生命周期恢复与 User Green。请参阅 [Release Validation](ods/docs/RELEASE_VALIDATION.md) 与 [Validation Matrix](ods/docs/VALIDATION-MATRIX.md)。
>
> **Windows:** Requires Docker Desktop with WSL2 backend. NVIDIA GPUs use Docker GPU passthrough; AMD Strix Halo runs through the platform-specific accelerated path documented in the Windows installer and support matrix.
> **Windows** 需要带 WSL2 后端的 Docker DesktopNVIDIA GPU 使用 Docker GPU 直通;AMD Strix Halo 通过 Windows 安装器与支持矩阵中记录的平台专用加速路径运行。
>
> **macOS:** Requires Apple Silicon (M1+) and Docker Desktop. llama-server runs natively with Metal GPU acceleration; all other services run in Docker.
> **macOS** 需要 Apple SiliconM1+)与 Docker Desktopllama-server 以 Metal GPU 加速原生运行;其余服务在 Docker 中运行。
>
> See the [Support Matrix](ods/docs/SUPPORT-MATRIX.md) for supported
> platform claims and the [Validation Matrix](ods/docs/VALIDATION-MATRIX.md)
> for the layered test surface used to test those claims.
> 平台支持声明见 [Support Matrix](ods/docs/SUPPORT-MATRIX.md),用于验证这些声明的分层测试面见 [Validation Matrix](ods/docs/VALIDATION-MATRIX.md)。
---
## Why ODS?
## 为何选择 ODS
A handful of companies control the vast majority of global AI traffic — and with it, your data, your costs, and your uptime. Every query you send to a centralized provider is business intelligence you dont own, running on infrastructure you dont control, priced on terms you cant negotiate.
少数公司掌控着全球绝大多数 AI 流量 — 连同你的数据、成本与可用性。你发给中心化提供商的每一次查询,都是你不拥有的商业情报,运行在你无法掌控的基础设施上,按你无法谈判的条款定价。
If AI is becoming critical infrastructure, it shouldnt be rented. Self-hosting local AI should be a sovereign human right, not a career choice.
如果 AI 正在成为关键基础设施,它就不该被租用。自托管本地 AI 应是一项主权人权,而非职业选择。
Because running your own AI shouldn't require a CS degree and a weekend of debugging CUDA drivers. Right now, setting up local AI means stitching together a dozen projects, writing Docker configs from scratch, and praying everything talks to each other. Most people give up and go back to paying OpenAI.
因为运行自己的 AI 不应需要计算机学位,也不该花一个周末调试 CUDA 驱动。如今搭建本地 AI 意味着拼接十几个项目、从零编写 Docker 配置,并祈祷一切能互相通信。大多数人会放弃,回到付费使用 OpenAI
We built ODS so you don't have to.
我们打造 ODS,就是让你不必如此。
- **One command** — detects your GPU, picks the right model, generates credentials, launches everything
- **Chatting in under 2 minutes** — bootstrap mode gives you a working model instantly while your full model downloads in the background
- **Full service stack, pre-wired** — chat, agents, voice, workflows, search, RAG, image generation, privacy tools, observability, and developer tools. All talking to each other out of the box
- **Fully moddable** — every service is an extension. Drop in a folder, run `ods enable`, done
- **一条命令** — 检测 GPU、选择合适模型、生成凭据、启动一切
- **不到 2 分钟即可聊天** — 引导模式在完整模型后台下载时,立即给你一个可用模型
- **完整服务栈,预接线** — 聊天、智能体、语音、工作流、搜索、RAG、图像生成、隐私工具、可观测性与开发者工具,开箱即用、彼此互通
- **完全可改装** — 每个服务都是扩展。放入一个文件夹,运行 `ods enable`,完成
<div align="center">
![ODS Installer](ods/docs/images/installer-splash.gif)
*The ODSGATE installer handles everything — GPU detection, model selection, service orchestration.*
*ODSGATE 安装程序会处理一切——GPU 检测、模型选择与服务编排。*
</div>
<details>
<summary><b>Manual install (Linux)</b></summary>
<summary><b>手动安装(Linux</b></summary>
```bash
git clone https://github.com/Light-Heart-Labs/ODS.git
@@ -164,12 +149,12 @@ cd ODS/ods
</details>
<details>
<summary><b>Windows (PowerShell)</b></summary>
<summary><b>WindowsPowerShell</b></summary>
Requires [Docker Desktop](https://www.docker.com/products/docker-desktop/) with WSL2 backend enabled.
**Install Docker Desktop first and make sure it is running before you start.**
需要启用 WSL2 后端的 [Docker Desktop](https://www.docker.com/products/docker-desktop/) with WSL2 backend enabled.
**请先安装 Docker Desktop,并在开始前确保其正在运行。**
Open a normal **PowerShell** session and run:
打开一个普通的 **PowerShell** 会话并运行:
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
@@ -178,18 +163,18 @@ cd ODS
.\install.ps1
```
> The `Set-ExecutionPolicy` command allows the installer script to run in the current session. It does not change your system-wide policy.
> Running as Administrator is not recommended for the installer because user-level paths such as `.opencode`, `data/`, and `.env` can be created with admin-owned permissions.
> `Set-ExecutionPolicy` 命令允许安装脚本在当前会话中运行。它不会更改你的系统级策略。
> 不建议以管理员身份运行安装程序,因为 `.opencode``data/` `.env` 等用户级路径可能会以管理员拥有的权限创建。
The installer detects your GPU, picks the right model, generates credentials, starts all services, and creates a Desktop shortcut to the Dashboard. Manage with `.\ods\installers\windows\ods.ps1 status`.
安装程序会检测你的 GPU、选择合适模型、生成凭据、启动所有服务,并创建指向 Dashboard 的桌面快捷方式。使用 `.\ods\installers\windows\ods.ps1 status` 进行管理。
</details>
<details>
<summary><b>macOS (Apple Silicon)</b></summary>
<summary><b>macOSApple Silicon</b></summary>
Requires Apple Silicon (M1+) and [Docker Desktop](https://www.docker.com/products/docker-desktop/).
**Install Docker Desktop first and make sure it is running before you start.**
需要 Apple SiliconM1+)和 [Docker Desktop](https://www.docker.com/products/docker-desktop/).
**请先安装 Docker Desktop,并在开始前确保其正在运行。**
```bash
git clone https://github.com/Light-Heart-Labs/ODS.git
@@ -197,130 +182,130 @@ cd ODS/ods
./install.sh
```
The installer detects your chip, picks the right model for your unified memory, launches llama-server natively with Metal acceleration, and starts all other services in Docker. Manage with `./ods-macos.sh status`.
安装程序会检测你的芯片、根据统一内存选择合适模型,以 Metal 加速原生启动 llama-server,并在 Docker 中启动所有其他服务。使用 `./ods-macos.sh status` 进行管理。
See the [macOS Quickstart](ods/docs/MACOS-QUICKSTART.md) for details.
详见 [macOS 快速入门](ods/docs/MACOS-QUICKSTART.md)
</details>
---
## What's In The Box
## 开箱即用
### Chat & Inference
- **Open WebUI** — full-featured chat interface with conversation history, web search, document upload, and [30+ languages](https://docs.openwebui.com)
- **llama-server** — high-performance LLM inference with continuous batching, auto-selected for your GPU; Linux Docker host API defaults to `localhost:11434`, native macOS/Windows paths use `localhost:8080`, and container API runs on `8080`
- **LiteLLM** — API gateway supporting local/cloud/hybrid modes
- **TEI Embeddings** — text embedding service for RAG and search workflows
### 聊天与推理
- **Open WebUI** — 功能完整的聊天界面,支持对话历史、网页搜索、文档上传,以及 [30+ 种语言](https://docs.openwebui.com)
- **llama-server** — 高性能 LLM 推理,支持连续批处理(continuous batching),会根据你的 GPU 自动选择;Linux Docker 主机 API 默认为 `localhost:11434`macOS/Windows 原生路径使用 `localhost:8080`,容器 API 运行于 `8080`
- **LiteLLM** — 支持本地/云端/混合模式的 API 网关
- **TEI Embeddings** — 用于 RAG 与搜索工作流的文本嵌入服务
### Voice
- **Whisper** — speech-to-text
- **Kokoro** — text-to-speech
### 语音
- **Whisper** — 语音转文字(speech-to-text
- **Kokoro** — 文字转语音(text-to-speech
### Agents & Automation
- **Hermes Agent** — default local-first autonomous/browser agent with memory, skills, and a magic-link-gated proxy
- **OpenClaw** — deprecated legacy autonomous agent, still opt-in during the migration window
- **n8n** — workflow automation with 400+ integrations (Slack, email, databases, APIs)
- **APE** — Agent Policy Engine for auditing and governing autonomous tool calls
- **OpenCode** — browser-based AI coding assistant wired to the local stack
- **Memory Shepherd** — host/systemd helper for agent memory lifecycle management
### 智能体与自动化
- **Hermes Agent** — 默认的本地优先自主/浏览器智能体,具备记忆、技能,以及魔法链接(magic-link)门控代理
- **OpenClaw** — 已弃用的旧版自主智能体,在迁移窗口期内仍可自愿启用
- **n8n** — 工作流自动化,集成 400+ 种服务(Slack、邮件、数据库、API
- **APE** — 智能体策略引擎(Agent Policy Engine),用于审计与治理自主工具调用
- **OpenCode** — 基于浏览器的 AI 编程助手,已接入本地技术栈
- **Memory Shepherd** — 用于智能体记忆生命周期管理的宿主机/systemd 辅助工具
### Knowledge & Search
- **Qdrant** — vector database for retrieval-augmented generation (RAG)
- **SearXNG** — self-hosted web search (no tracking)
- **Perplexica** — deep research engine
- **Brave Search** — optional paid Brave Search API integration
### 知识与搜索
- **Qdrant** — 用于检索增强生成(RAG)的向量数据库
- **SearXNG** — 自托管网页搜索(无追踪)
- **Perplexica** — 深度研究引擎
- **Brave Search** — 可选的付费 Brave Search API 集成
### Creative
- **ComfyUI** — node-based image generation
### 创意
- **ComfyUI** — 基于节点的图像生成
### Privacy & Ops
- **Privacy Shield** — PII scrubbing proxy for API calls
- **Dashboard** — real-time GPU metrics, service health, model management
- **Dashboard API** — service health, setup, status, metrics, and management API behind the dashboard
- **Token Spy** — token usage monitor for local and proxied LLM traffic
- **Langfuse** — optional LLM observability and tracing
### 隐私与运维
- **Privacy Shield** — 用于 API 调用的 PII 脱敏代理
- **Dashboard** — 实时 GPU 指标、服务健康状态、模型管理
- **Dashboard API** — Dashboard 背后的服务健康、设置、状态、指标与管理 API
- **Token Spy** — 本地与代理 LLM 流量的 token 用量监控
- **Langfuse** — 可选的 LLM 可观测性与追踪
---
## Hardware Auto-Detection
## 硬件自动检测
The installer detects your GPU and first assigns a deterministic hardware tier. Linux and macOS then run the versioned catalog selector (`ods/scripts/select-model.py`), while Windows uses the PowerShell catalog selector in `ods/installers/windows/lib/tier-map.ps1`; both read `ods/config/model-library.json` to choose the best installable GGUF for the detected memory envelope. The final choice is written to `.env` as `LLM_MODEL`, `GGUF_FILE`, `MAX_CONTEXT`, and `MODEL_RECOMMENDATION_*`.
安装程序会检测你的 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` is the default non-Gemma catalog profile, so the effective pick can be Qwen, Phi, or DeepSeek depending on what fits best. `MODEL_PROFILE=gemma4` forces Gemma 4 where available, and `MODEL_PROFILE=auto` uses Gemma 4 on NVIDIA, Apple Silicon, and Intel Arc tiers. Override tier selection with `./install.sh --tier 3`; override the model family with `MODEL_PROFILE=gemma4 ./install.sh` or `MODEL_PROFILE=auto ./install.sh`.
`MODEL_PROFILE=qwen` 是默认的非 Gemma 目录配置,因此实际选择可能是 QwenPhi DeepSeek,取决于哪种最合适。`MODEL_PROFILE=gemma4` 会在可用时强制使用 Gemma 4`MODEL_PROFILE=auto` 会在 NVIDIAApple Silicon Intel Arc 层级上使用 Gemma 4。可使用 `./install.sh --tier 3` 覆盖层级选择;使用 `MODEL_PROFILE=gemma4 ./install.sh` `MODEL_PROFILE=auto ./install.sh` 覆盖模型系列。
When Hermes is enabled, which is the default agent path, installers keep the first-run bootstrap model at a 64K context floor and promote the full local model context to 128K where the selected model supports it. That avoids Hermes's hard 64K minimum while preserving the under-2-minute first chat experience. The examples below are current catalog-selector outputs for common hardware envelopes; exact installs can differ with detected VRAM/RAM, host architecture, existing downloads, or explicit profile overrides. Throughput still needs a local benchmark after first launch.
Hermes 启用时(这是默认的智能体路径),安装程序会将首次运行的引导模型保持在 64K 上下文下限,并在所选模型支持的情况下将完整本地模型上下文提升至 128K。这样既能满足 Hermes 硬性 64K 最低要求,又能保留首次聊天不到 2 分钟的体验。以下示例是当前目录选择器在常见硬件容量下的输出;实际安装可能因检测到的 VRAM/RAM、主机架构、已有下载或显式配置覆盖而有所不同。首次启动后,吞吐量仍需进行本地基准测试。
### NVIDIA
| Tier / envelope | Current default catalog pick | Context | Example hardware |
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 示例硬件 |
|------|--------------|---------|--------------|
| 0 / 8 GB CPU fallback | Qwen3.5 2B (Q4_K_M) | 8K | Low-RAM CPU-only |
| 1 / 8 GB discrete VRAM | Qwen3.5 9B (Q4_K_M) | 32K | RTX 4060, RTX 3060 12GB |
| 2 / 12 GB discrete VRAM | Phi-4 14B (Q4_K_M) | 16K | RTX 4070-class cards |
| 3 / 24 GB discrete VRAM | Qwen3.5 27B (Q4_K_M) | 32K | RTX 4090, A6000 |
| 4 / 48 GB discrete VRAM | DeepSeek R1 Distill Llama 70B (Q4_K_M) | 32K | A6000 Ada, L40S |
| NV_ULTRA / 90+ GB amd64 discrete VRAM | Qwen3 Coder Next (Q4_K_M) | 128K | Multi-GPU A100/H100 |
| NV_ULTRA / 90+ GB arm64 unified memory | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | DGX Spark / GB10-class hosts |
| 0 / 8 GB CPU 回退 | Qwen3.5 2B (Q4_K_M) | 8K | 低内存纯 CPU |
| 1 / 8 GB 独立 VRAM | Qwen3.5 9B (Q4_K_M) | 32K | RTX 4060RTX 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 4090A6000 |
| 4 / 48 GB 独立 VRAM | DeepSeek R1 Distill Llama 70B (Q4_K_M) | 32K | A6000 AdaL40S |
| 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 (Unified Memory)
### AMD Strix Halo(统一内存)
| Tier / envelope | Current default catalog pick | Context | Hardware |
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 硬件 |
|------|--------------|---------|----------|
| SH_COMPACT / 64 GB unified RAM | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | Ryzen AI MAX+ 395 (64GB) |
| SH_LARGE / 96 GB unified RAM | DeepSeek R1 Distill Llama 70B (Q4_K_M) | 32K | Ryzen AI MAX+ 395 (96GB) |
| SH_LARGE / 124 GB unified RAM | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | Ryzen AI MAX+ 395 (128GB class) |
| 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 级别) |
The selector routes unified-memory hosts away from Qwen3 Coder Next when that model would otherwise be selected, because current repo policy documents correctness issues on those backends.
当否则会选中 Qwen3 Coder Next 时,选择器会将统一内存主机路由到其他模型,因为当前仓库策略文档记录了这些后端上的正确性问题。
### Apple Silicon (Unified Memory, Metal)
### Apple Silicon(统一内存,Metal
| Tier / envelope | Current default catalog pick | Context | Example hardware |
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 示例硬件 |
|------|--------------|---------|-----------------|
| 0 / 8 GB unified RAM | Phi-4 Mini (Q4_K_M) | 128K | M1/M2 base (8GB) |
| 1 / 16 GB unified RAM | Qwen3.5 9B (Q4_K_M) | 32K | M4 Mac Mini (16GB) |
| 2 / 32 GB unified RAM | Phi-4 14B (Q4_K_M) | 16K | M4 Pro Mac Mini, M3 Max MacBook Pro |
| 3 / 48 GB unified RAM | Qwen3.5 27B (Q4_K_M) | 32K | M4 Pro (48GB), M2 Max (48GB) |
| 4 / 64+ GB unified RAM | Qwen3.6 35B-A3B (UD-Q4_K_M) | 128K | M2 Ultra Mac Studio, M4 Max (64GB+) |
| 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 MiniM3 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 StudioM4 Max (64GB+) |
### Intel Arc (Linux, SYCL)
### Intel ArcLinuxSYCL
| Tier / envelope | Current default catalog pick | Context | Example hardware |
| 层级 / 容量 | 当前默认目录选择 | 上下文 | 示例硬件 |
|------|--------------|---------|------------------|
| ARC_LITE / 6 GB discrete VRAM | Phi-4 Mini (Q4_K_M) | 128K | Arc A380 |
| ARC_LITE / 8 GB discrete VRAM | Qwen3.5 9B (Q4_K_M) | 32K | Arc A750 |
| ARC / 16 GB discrete VRAM | Phi-4 14B (Q4_K_M) | 16K | Arc A770 16GB, newer Arc GPUs |
| 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 profile tiers remain in the installer tier maps: E2B on entry hardware, E4B on midrange hardware, 26B-A4B on pro hardware, and 31B on large/ultra hardware.
Gemma 4 配置层级仍保留在安装程序的层级映射中:入门级硬件为 E2B,中端硬件为 E4B,专业级硬件为 26B-A4B,大型/旗舰级硬件为 31B。
---
## Bootstrap Mode
## 引导模式(Bootstrap Mode
No waiting for large downloads. ODS uses bootstrap mode by default:
无需等待大型下载。ODS 默认使用引导模式:
1. Downloads a tiny 1.5B model in under a minute
2. You start chatting immediately
3. The full model downloads in the background
4. Hot-swap to the full model when it's ready — zero downtime
1. 不到一分钟即可下载一个 1.5B 的小型模型
2. 可立即开始聊天
3. 完整模型在后台下载
4. 就绪后热切换到完整模型——零停机
<div align="center">
![Installer downloading modules](ods/docs/images/installer-download.png)
![安装程序正在下载模块](ods/docs/images/installer-download.png)
*The installer pulls all services in parallel. Downloads are resume-capable — interrupted downloads pick up where they left off.*
*安装程序会并行拉取所有服务。下载支持断点续传——中断后可从上次位置继续。*
</div>
The bootstrap model starts with a 64K context window so Hermes can work during the first session. After the background download finishes, ODS swaps to the full model and restores the Hermes/full-model context target.
引导模型(bootstrap model)初始提供 64K 上下文窗口,以便 Hermes 在首次会话期间可用。后台下载完成后,ODS 会切换到完整模型,并恢复 Hermes/完整模型的上下文目标。
Skip bootstrap: `./install.sh --no-bootstrap`
跳过引导:`./install.sh --no-bootstrap`
---
## Switching Models
## 切换模型
The installer picks a model for your hardware, but you can switch anytime:
安装程序会根据你的硬件选择模型,但你可随时切换:
```bash
ods model current # What's running now?
@@ -328,35 +313,35 @@ ods model list # Show all available tiers
ods model swap T3 # Switch to a different tier
```
If the new model isn't downloaded yet, pre-fetch it first:
若新模型尚未下载,请先预取:
```bash
./scripts/pre-download.sh --tier 3 # Download before switching
ods model swap T3 # Then swap (restarts llama-server)
```
Already have a GGUF you want to use? Drop the single `.gguf` file in
`data/models/`, then open Dashboard -> Models and load the local entry. For
older installs or headless maintenance, update `GGUF_FILE` and `LLM_MODEL` in
`.env`, then restart with the CLI:
已有想使用的 GGUF?将单个 `.gguf` 文件放入
`data/models/`,然后打开 Dashboard -> Models 并加载本地条目。对于
较旧安装或无头(headless)维护,在
`.env` 中更新 `GGUF_FILE``LLM_MODEL`,然后通过 CLI 重启:
```bash
ods restart llm
```
Or restart the container directly from the installed `ods` directory:
或直接从已安装的 `ods` 目录重启容器:
```bash
docker compose restart llama-server
```
Rollback is automatic — if a new model fails to load, ODS reverts to your previous model.
回滚是自动的——若新模型加载失败,ODS 会恢复到你之前的模型。
---
## Extensibility
## 可扩展性
ODS is designed to be modded. Every service is an extension — a folder with a `manifest.yaml` and a `compose.yaml`. The dashboard, CLI, health checks, and compose stack all discover extensions automatically.
ODS 专为可改装而设计。每个服务都是一个扩展——包含 `manifest.yaml` `compose.yaml` 的文件夹。DashboardCLI、健康检查以及 compose 栈都会自动发现扩展。
```
extensions/services/
@@ -371,15 +356,15 @@ ods disable my-service # Disable it
ods list # See everything
```
The installer itself is modular — 19 library modules, a shared service registry, and 13 ordered phases. Want to add a hardware tier, swap a default model, or skip a phase? Start with the installer architecture map so you update the Linux, macOS, Windows, upgrade, and host-agent writers together.
安装程序本身也是模块化的——19 个库模块、共享服务注册表,以及 13 个有序阶段。想新增硬件层级、更换默认模型或跳过某个阶段?先从安装程序架构图入手,以便同步更新 LinuxmacOSWindows、升级与 host-agent 编写器。
[Full extension guide](ods/docs/EXTENSIONS.md) | [Installer architecture](ods/docs/INSTALLER-ARCHITECTURE.md)
[完整扩展指南](ods/docs/EXTENSIONS.md) | [安装程序架构](ods/docs/INSTALLER-ARCHITECTURE.md)
---
## ods-cli
The `ods` CLI manages your entire stack:
`ods` CLI 管理你的整个栈:
```bash
ods status # Health checks + GPU status
@@ -403,71 +388,71 @@ ods preset load gaming # Restore it
---
## How It Compares
## 对比
Other tools get you part of the way. ODS gets you the whole way.
其他工具只能帮你走一部分路。ODS 能带你走完全程。
| | ODS | Ollama + Open WebUI | LocalAI |
|---|:---:|:---:|:---:|
| **Scope** | Full AI stack — inference to agents to workflows | LLM + chat | LLM only |
| One-command install | Everything, auto-configured | LLM + chat only | LLM only |
| Hardware auto-detect + model selection | NVIDIA + AMD Strix Halo + Apple Silicon + Intel Arc + CPU/cloud fallback | No | No |
| AMD APU unified memory support | Platform-specific accelerated backend, selected by installer | Partial (Vulkan) | No |
| Autonomous AI agents | Hermes Agent default; OpenClaw legacy opt-in | No | No |
| Workflow automation | n8n (400+ integrations) | No | No |
| Voice (STT + TTS) | Whisper + Kokoro | No | No |
| Image generation | ComfyUI | No | No |
| RAG pipeline | Qdrant + embeddings | No | No |
| Extension system | Manifest-based, hot-pluggable | No | No |
| Multi-GPU | Yes (NVIDIA) | Partial | Partial |
| **范围** | 完整 AI 栈——从推理到智能体再到工作流 | LLM + 聊天 | LLM |
| 一键安装 | 全部组件,自动配置 | 仅 LLM + 聊天 | 仅 LLM |
| 硬件自动检测 + 模型选择 | NVIDIA + AMD Strix Halo + Apple Silicon + Intel Arc + CPU/云回退 | | |
| AMD APU 统一内存支持 | 平台专用加速后端,由安装程序选择 | 部分(Vulkan | |
| 自主 AI 智能体 | 默认 Hermes AgentOpenClaw 遗留可选 | | |
| 工作流自动化 | n8n400+ 集成) | | |
| 语音(STT + TTS | Whisper + Kokoro | | |
| 图像生成 | ComfyUI | | |
| RAG 流水线 | Qdrant + embeddings | | |
| 扩展系统 | 基于 manifest,支持热插拔 | | |
| GPU | 是(NVIDIA | 部分 | 部分 |
---
## Documentation
## 文档
| | |
|---|---|
| [Quickstart](ods/QUICKSTART.md) | Step-by-step install guide with troubleshooting |
| [Docs Index](ods/docs/README.md) | Maintained map for operators, contributors, and reviewers |
| [Build On ODS](ods/docs/BUILD-ON-ODS-SERVER.md) | Forking, custom editions, extension templates, and downstream validation |
| [Forkability](ods/docs/FORKABILITY.md) | How to fork, audit, customize, and independently operate ODS |
| [Maintainer Runbook](ods/docs/MAINTAINER_RUNBOOK.md) | Release, rollback, validation, and operator continuity guidance for maintainers and forks |
| [High-Risk Change Map](ods/docs/HIGH_RISK_CHANGE_MAP.md) | Which changes require focused checks, fleet validation, or release-grade gates |
| [Headless Setup](ods/docs/HEADLESS-SETUP.md) | QR onboarding, first-boot setup, AP mode, mDNS, and local agent access |
| [Support Matrix](ods/docs/SUPPORT-MATRIX.md) | Current platform and GPU support status |
| [Release Validation](ods/docs/RELEASE_VALIDATION.md) | User Green gates and the release-grade fleet/distro validation policy |
| [Validation Matrix](ods/docs/VALIDATION-MATRIX.md) | Sanitized CI, distro lab, and real-hardware fleet release-readiness evidence |
| [Validation Reproducibility](ods/docs/VALIDATION_REPRODUCIBILITY.md) | How forks and operators can reproduce the validation story on their own hardware |
| [Offline And Mirroring](ods/docs/OFFLINE_AND_MIRRORING.md) | Pinning, mirroring, and preserving release artifacts for independent operation |
| [Installer Trust](ods/docs/INSTALLER_TRUST.md) | Inspect-first install paths, ref pinning, and current provenance limits |
| [Model Management](ods/docs/MODEL-MANAGEMENT.md) | Dashboard model downloads, switching, and manual GGUF workflows |
| [Hardware Guide](ods/docs/HARDWARE-GUIDE.md) | What to buy, tier recommendations |
| [FAQ](ods/FAQ.md) | Common questions and configuration |
| [Extensions](ods/docs/EXTENSIONS.md) | How to add custom services |
| [Installer Architecture](ods/docs/INSTALLER-ARCHITECTURE.md) | Modular installer deep dive |
| [Installer Phase Contracts](ods/docs/INSTALLER_PHASE_CONTRACTS.md) | Phase ownership, idempotency, failure modes, and validation expectations |
| [Compose Resolver Contracts](ods/docs/COMPOSE_RESOLVER_CONTRACTS.md) | Rules for compose layers, extensions, backends, ports, and mode overlays |
| [Changelog](ods/CHANGELOG.md) | Version history and release notes |
| [Contributing](CONTRIBUTING.md) | How to contribute |
| [快速入门](ods/QUICKSTART.md) | 分步安装指南,含故障排除 |
| [文档索引](ods/docs/README.md) | 面向运维人员、贡献者与审阅者的维护地图 |
| [基于 ODS 构建](ods/docs/BUILD-ON-ODS-SERVER.md) | Fork、定制版本、扩展模板与下游验证 |
| [可 Fork 性](ods/docs/FORKABILITY.md) | 如何 fork、审计、定制并独立运营 ODS |
| [维护者运行手册](ods/docs/MAINTAINER_RUNBOOK.md) | 面向维护者与 fork 的发布、回滚、验证及运维连续性指南 |
| [高风险变更地图](ods/docs/HIGH_RISK_CHANGE_MAP.md) | 哪些变更需要重点检查、机群验证或发布级门禁 |
| [无头设置](ods/docs/HEADLESS-SETUP.md) | QR 引导、首次启动设置、AP 模式、mDNS 及本地智能体访问 |
| [支持矩阵](ods/docs/SUPPORT-MATRIX.md) | 当前平台与 GPU 支持状态 |
| [发布验证](ods/docs/RELEASE_VALIDATION.md) | User Green 门禁及发布级机群/发行版验证策略 |
| [验证矩阵](ods/docs/VALIDATION-MATRIX.md) | 脱敏 CI、发行版实验室与真实硬件机群的发布就绪证据 |
| [验证可复现性](ods/docs/VALIDATION_REPRODUCIBILITY.md) | fork 与运维人员如何在自己的硬件上复现验证流程 |
| [离线与镜像](ods/docs/OFFLINE_AND_MIRRORING.md) | 固定版本、镜像并保留发布制品以支持独立运营 |
| [安装程序信任](ods/docs/INSTALLER_TRUST.md) | 先检查后安装路径、ref 固定及当前来源追溯限制 |
| [模型管理](ods/docs/MODEL-MANAGEMENT.md) | Dashboard 模型下载、切换及手动 GGUF 工作流 |
| [硬件指南](ods/docs/HARDWARE-GUIDE.md) | 选购建议与层级推荐 |
| [常见问题](ods/FAQ.md) | 常见问题与配置 |
| [扩展](ods/docs/EXTENSIONS.md) | 如何添加自定义服务 |
| [安装程序架构](ods/docs/INSTALLER-ARCHITECTURE.md) | 模块化安装程序深度解析 |
| [安装程序阶段契约](ods/docs/INSTALLER_PHASE_CONTRACTS.md) | 阶段归属、幂等性、失败模式与验证预期 |
| [Compose 解析器契约](ods/docs/COMPOSE_RESOLVER_CONTRACTS.md) | compose 层、扩展、后端、端口与模式叠加规则 |
| [变更日志](ods/CHANGELOG.md) | 版本历史与发布说明 |
| [贡献指南](CONTRIBUTING.md) | 如何参与贡献 |
---
## Contributors And Recognition
## 贡献者与认可
ODS is built by a growing group of contributors across installers, GPU support, dashboard, security, extensions, docs, and release validation. The README keeps the product overview focused; the long-form credits, upstream acknowledgements, and contributor history live in [CONTRIBUTORS.md](CONTRIBUTORS.md).
ODS 由不断壮大的贡献者团队在安装程序、GPU 支持、Dashboard、安全、扩展、文档与发布验证等领域共同构建。README 聚焦产品概览;详细致谢、上游鸣谢与贡献者历史见 [CONTRIBUTORS.md](CONTRIBUTORS.md)
ODS has been recognized by the local AI and developer community, including AMD Featured Developer recognition, selection as a May 2026 AMD Lemonade Developer Challenge winner, and a feature at [(Co)nnect: Philly's AI Ecosystem Summit](https://luma.com/xdwih64h) at Pennovation Works.
ODS 已获得本地 AI 与开发者社区认可,包括 AMD Featured Developer 认可、入选 2026 年 5 月 AMD Lemonade Developer Challenge 获奖者,并在 [(Co)nnect: Philly's AI Ecosystem Summit](https://luma.com/xdwih64h) at Pennovation Works 上亮相。
---
## License
## 许可证
Apache 2.0 — Use it, modify it, ship it. See [LICENSE](LICENSE).
Apache 2.0 — 随意使用、修改、发布。详见 [LICENSE](LICENSE)
---
<div align="center">
*Built by [Light Heart Labs](https://github.com/Light-Heart-Labs) and the growing resistance that refuses to rent what should be owned.*
* [Light Heart Labs](https://github.com/Light-Heart-Labs) 与不断壮大的、拒绝租用本应拥有之物的抵抗力量共同打造。*
</div>