首次執行配置
按照快速部署把容器拉起來之後,系統裡還沒有任何使用者、渠道和模型。本頁按順序走完從「空系統」到「發出第一條訊息」的全部配置:建立管理員、新增上游渠道、建立模型、設定預設模型與任務模型、配置嵌入模型,最後是幾個可選增強項。
第 1 步:建立管理員賬號
瀏覽器開啟你的站點。全新部署(使用者數為 0)時會自動進入首啟設定頁 /setup,填寫三個欄位:
| 欄位 | 要求 |
|---|---|
| 郵箱 | 作為登入賬號 |
| 名字 | 顯示名 |
| 密碼 | 至少 8 個字元 |
提交後,這個賬號立即成為管理員並自動登入,不需要郵箱驗證。
系統中一旦存在任何賬號,/setup 就永久失效(再訪問返回 409)。所以部署完成後請儘快完成這一步,不要把一個「零使用者」的例項長時間暴露在公網上,否則任何先訪問到的人都能把自己註冊成管理員。
後續的使用者管理(邀請、封禁、配額)在管理後臺進行,見使用者與配額。
第 2 步:進入管理後臺
管理後臺入口有兩個,效果相同:
- 側欄底部的賬號選單裡的管理入口;
- 直接訪問
/admin。
後臺各頁面的總覽見管理後臺概覽。首次配置主要用到「渠道 Channels」和「模型 Models」兩頁。
第 3 步:新增渠道(Channel)
渠道是一條到上游模型服務商的連線。所有服務商 API Key 都儲存在資料庫的渠道表裡,不寫在 .env 中。進入管理後臺的「渠道 Channels」頁,新建渠道時選擇型別並填寫連線資訊:
| 渠道型別 | 適用上游 | 需要填寫 |
|---|---|---|
| Anthropic | Anthropic 官方或相容其協議的服務 | Base URL + API Key |
| OpenAI | OpenAI 官方或相容其協議的服務 | Base URL + API Key |
| Gemini | Google Gemini | Base URL + API Key |
| OpenAI 相容 | 任何暴露 OpenAI 格式介面的中轉、聚合或本地推理服務 | Base URL + API Key |
欄位說明:
- 型別:決定 Aivory 以哪種協議格式呼叫上游。用官方 API 就選對應官方型別;用中轉或自建推理服務通常選「OpenAI 相容」。
- Base URL:上游服務地址。
- API Key:上游簽發的金鑰,儲存在資料庫中。
一個部署可以同時新增多個渠道(例如一個 Anthropic 官方渠道加一個 OpenAI 相容中轉),渠道本身對普通使用者不可見,使用者只會看到下一步建立的「模型」。渠道管理的完整說明見渠道與模型。
在 .env 中設定 ENABLE_MOCK_PROVIDER=true 並重啟,會注入一個內建演示渠道和演示模型,可以端到端跑通整個對話鏈路。驗證完、新增真實渠道後記得改回 false。
第 4 步:建立模型(Model)
渠道建好後,到「模型 Models」頁建立對使用者可見的模型條目。每個模型的欄位:
| 欄位 | 說明 |
|---|---|
| 名稱 | 展示給使用者的模型名,出現在模型選擇器裡 |
| 圖示 | 模型在選擇器和訊息流中的圖示 |
| kind | 模型種類:chat(對話)/ image(影像生成)/ embedding(向量嵌入) |
| 渠道 | 該模型走哪條渠道呼叫上游 |
| 上游模型 ID | 傳給上游 API 的真實模型標識,必須與服務商的模型名完全一致 |
| 定價 | 該模型的 token 單價,用於平臺內的用量核算 |
| vision | 是否接受圖片輸入。開啟後用戶才能在該模型的對話中傳送圖片 |
| stream | 是否以流式方式返回輸出 |
| tool_mode | 工具呼叫方式:native(上游原生工具呼叫)/ prompt(通過提示詞模擬工具呼叫,適合不支援原生 function calling 的上游)/ none(該模型不使用工具) |
| 研究開關 | 該模型是否可用於深度研究,見深度研究 |
模型啟用後立即出現在所有使用者的模型選擇器中。建議起步至少建立:
- 一個主力
chat模型(開啟 stream,按上游能力設定 vision 和 tool_mode); - 一個便宜快速的小模型,下一步可指定為任務模型;
- 如需知識庫,再建一個
embedding模型(見第 6 步)。
名稱是給使用者看的,可以隨便起;「上游模型 ID」是真正發給服務商的,拼寫錯誤會導致對話直接報錯。建立後先自己發一條訊息驗證再放給使用者。
第 5 步:設定預設模型與任務模型
模型建好後,在管理後臺指定三類全域性角色:
| 角色 | 用途 | 建議 |
|---|---|---|
| 預設模型 | 使用者新建對話時的預設選擇 | 選主力 chat 模型 |
| 任務模型 | 系統內部的小任務呼叫,不直接面向用戶 | 選便宜、快、穩定的小模型 |
| 嵌入模型 | 知識庫向量化,知識庫功能的必要條件 | 見第 6 步 |
第 6 步:配置嵌入模型,啟用知識庫
知識庫(RAG)需要一個嵌入模型才能工作。兩種配置途徑,任選其一:
途徑 A,環境變數(啟動期兜底):在 deploy/.env 中配置 EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL / EMBEDDING_DIM,指向任意 OpenAI 格式的 /v1/embeddings 端點,然後重啟。
途徑 B,管理後臺:建立一個 kind = embedding 的模型(走某條渠道),並把它設為嵌入模型。
無論哪種方式,都要注意維度一致性:
Qdrant 按嵌入寬度使用獨立 collection。如果維度配置與模型實際輸出不一致,系統會退回內建的 256 維本地 embedder,它的 collection 與 1536 維模型向量互不相容,檢索質量也只適合開發測試,不適合生產。例如 text-embedding-3-small 對應 EMBEDDING_DIM=1536。
完全不配置嵌入模型時,知識庫仍可建立,向量檢索關閉時 RAG 會回退為把範圍內的完整文件文本注入上下文。知識庫的日常使用見知識庫指南。
第 7 步:傳送第一條訊息驗證
回到聊天介面:
- 在模型選擇器中選中你剛建立的 chat 模型;
- 傳送一條訊息,確認能收到流式回覆;
- 如果模型開啟了 vision,可以再發一張圖片驗證多模態;
- 如果 tool_mode 不是
none,可以讓模型做一次聯網搜尋或程式碼執行,驗證工具鏈路(需要先完成下面的可選配置)。
報錯時的排查順序:上游模型 ID 是否拼寫正確,渠道 Base URL / API Key 是否有效,docker compose logs app 裡的具體報錯。常見問題見 FAQ。
可選配置
以下三項都不影響基礎對話,按需開啟。
聯網搜尋
給模型提供 web 搜尋工具。兩種配置方式:管理後臺線上配置,或 .env 啟動期兜底(SEARCH_PROVIDER / SEARCH_API_KEY / SEARCH_BASE_URL):
serper/brave:填 API Key;searxng:填自建例項的 Base URL,不需要 key。
聯網搜尋也是深度研究功能的基礎,見深度研究。
程式碼沙箱
Docker Compose 完整棧已內建沙箱服務,app 與沙箱共享內建預設金鑰,無需任何配置即可執行 Python 程式碼。唯一要求:保持管理後臺設定裡的 sandbox_base_url 與 sandbox_api_key 欄位為空,內建沙箱才會被使用。這兩個欄位僅在對接外部自建沙箱時填寫。
沙箱的資源限額、網路隔離與持久化見程式碼沙箱部署,使用者側用法見 Python 沙箱指南。
MinerU 文件解析
掃描版、圖片型 PDF 需要 OCR 才能進知識庫檢索。在 .env 配置 MINERU_API_URL(預設 https://mineru.net)與 MINERU_API_KEY,或在管理後臺的站點設定裡線上配置,見站點設定。不配置時這類文件上傳後只有一行佔位文本。
從舊例項遷移
如果你是從另一套 Aivory 例項搬家,不需要手工重建以上配置:在舊例項的管理後臺「備份與遷移」頁生成全量遷移包(含資料庫邏輯備份、可選的上傳檔案與產物、Qdrant 向量資料),再到新例項同一頁面匯入即可。匯入大小上限由 MAX_BACKUP_BYTES 控制,預設 20 GiB。完整流程見備份與遷移。
下一步
- 反向代理與 HTTPS:
app容器提供的是明文 HTTP,公網部署務必加 TLS 終止層 - Cloudflare 接入:經由 Cloudflare 暴露站點時的配置要點
- 使用者與配額:開放註冊前先定好每日訊息與影像限額
- 對話功能指南:把使用手冊發給你的使用者
- 管理後臺概覽:其餘後臺能力速覽