> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Odysseus
> 如何部署 Odysseus 智能 Agent，並透過自訂端點接入 Mixroute 驅動強大的自託管 AI 工作空間。
Odysseus 是一個自託管的 AI 工作空間，旨在提供類似於 ChatGPT 和 Claude 的私有化 Web 體驗。它不僅支援本地模型，還能無縫對接雲端 API（如 Mixroute），具備強大的 Agent 智能體路由、深度研究（Deep Research）、文件協作編輯、持久化記憶（ChromaDB）和技能進化系統。
* 官方 GitHub：[pewdiepie-archdaemon/odysseus](https://github.com/pewdiepie-archdaemon/odysseus)
## 核心特性
內置基於工具調用、網路搜尋、檔案讀寫和 Shell 執行的自主 Agent，支援 MCP 服務擴充。
多步驟、自主化的學術與事實搜尋、綜合提取，最終輸出結構完整的高品質視覺化報告。
配備富文本 Markdown 編輯器，AI 可以根據上下文協同編輯文件，完美適配行動裝置。
## 部署前準備
在開始部署前，請確保您的系統滿足以下要求：
**Smart Routing** 是一項智能模型路由能力，能夠根據輸入任務的複雜程度，自動將請求分配至最合適的模型，通過智能分配起到降本增效的作用。
1. 獲取 Mixroute API 端點地址，通常為：`https://api.mixroute.ai/v1`
2. 在 Mixroute [Smart Routing](https://console.mixroute.ai/smart-route) 頁面生成您的智能路由節點 Key。
3. 為不同級別的任務選擇模型，指南和約束見 [Smart Routing 指南](/zh-hant/smart-routing)
配置項示意如下：
```text theme={null}
API Key :
API Host : https://api.mixroute.ai/v1
Models: auto
```
1. 獲取 Mixroute API 端點地址，通常為：`https://api.mixroute.ai/v1`
2. 在 Mixroute 控制台生成您的 API Key。
3. 確定需要使用的模型名稱，如 `claude-sonnet-5`（需在 Mixroute 控制台已啟用該模型）。
配置項示意如下：
```text theme={null}
API Key :
API Host : https://api.mixroute.ai/v1
Models: claude-sonnet-5
```
* **Docker 部署**：需要安裝 Docker 和 Docker Compose。
* **原生 Linux 部署**：需要 Python 3.11 或更高版本，並確保系統已安裝 `git`。
## 部署 Odysseus
您可根據系統情況，選擇推薦的 Docker 容器化部署或原生的 Linux 部署方式。
透過 Docker Compose 一鍵啟動 Odysseus 及其配套服務（ChromaDB、SearXNG 等），全部數據保存在本地 `data/` 目錄中。
```bash theme={null}
# 克隆倉庫並進入工作目錄
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
# 建立並配置文件（可選，用於修改埠或綁定地址）
cp .env.example .env
# 啟動服務
docker compose up -d --build
```
如果您希望獲得可選的 PDF 渲染、Office 提取支援（需 AGPL PyMuPDF 協議包支援），請在 `up` 前加入建置參數進行手動 Build：
```bash theme={null}
docker compose build --build-arg INSTALL_OPTIONAL=true
docker compose up -d
```
如果您傾向於直接在宿主機（實體機/虛擬機）上部署，請參考以下指南：
```bash theme={null}
# 克隆並進入目錄
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
# 建立並啟用 Python 虛擬環境 (Python 3.11+)
python3 -m venv venv
source venv/bin/activate
# 安裝依賴
pip install -r requirements.txt
# 執行初始化腳本
python setup.py
# 啟動應用（綁定 127.0.0.1 埠 7000）
python -m uvicorn app:app --host 127.0.0.1 --port 7000
```
原生部署需要確保系統中已安裝必要的依賴（如 `sqlite3`）。如果需要利用 Odysseus 的 Cookbook 功能下載或管理背景服務，建議額外安裝 `tmux`。
## 首次登入與密碼獲取
預設情況下，Odysseus 在首次啟動時會自動建立管理員帳號 `admin`，並將其生成的隨機初始密碼輸出到啟動日誌中。
在終端中執行以下命令查看輸出：
* **Docker 部署**：
```bash theme={null}
docker compose logs odysseus | grep -C3 'password'
```
* **原生 Linux 部署**： 查看 `uvicorn` 或啟動終端中輸出的臨時初始密碼。
使用使用者名稱為 `admin` 和剛剛獲取到的密碼登入。
* 本地環境存取：`http://127.0.0.1:7000`
* 遠端雲端伺服器存取：`http://:7000`
預設設定下容器僅監聽 127.0.0.1，需要配置雲端虛機請參考，下方網路報錯或容器監聽問題。
## 接入 MaxRoute 配置
成功登入後，請按照以下步驟配置 Mixroute 的自訂端點，以驅動您的 Odysseus 智能助理。
在左下角點擊 **Settings** 進入全域系統設定。
在 **Settings** 中的 Providers/Endpoints 頁面新增自訂端點：
* **Base URL**: `https://api.mixroute.ai/v1`
* **API Key**: 填入您的 Mixroute API Key （例如 `sk-xxxxxxxx`）
新增端點後，Odysseus 會自動探測（Probe）並載入該端點下返回的可用模型。 您可以在列表中將常用的模型設定為啟用狀態，或將其指派為全域預設角色（如預設聊天、深度研究、Task 調度、視覺等角色）。
經過測試，GPT系列在odysseus中表現良好，建議配合GPT的模型使用。
返回 Chat 主頁面，即可順利使用 Mixroute 的底層模型來完成對話和啟動強大的智能 Agent。
## 常見問題與進階
如果需要在自託管容器中調用或透過 Cookbook 管理本地 GPU，建議：
1. 執行內置的診斷和配置腳本：
```bash theme={null}
scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
```
2. 此腳本會自動在 `.env` 中新增：`COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml` 啟用 NVIDIA 容器工具包映射。
預設設定下容器僅監聽 `127.0.0.1`。
* 如果需要直接從區域網路或公網透過 IP 存取，請修改 `.env` 中的 `APP_BIND=0.0.0.0`，然後重啟容器。
* 在生產環境下，強烈建議保持 `127.0.0.1` 監聽，並使用 Nginx, Caddy 或 Cloudflare Tunnel 進行反向代理並加持 SSL 憑證。
If 遇到 ChromaDB 無法載入或用戶端不相容問題：
```bash theme={null}
# 推薦手動解除安裝可能衝突的輕量用戶端，重新強行安裝完整版本
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
```
配置完成後，Odysseus 所有的後續功能（深度研究、檔案檢索、日曆/待辦及郵件 Triage）都將基於您在設定中綁定和配置的 Mixroute 端點進行驅動，享受到強大且極具性價比的雲端大模型服務。