首次运行配置
按照快速部署把容器拉起来之后,系统里还没有任何用户、渠道和模型。本页按顺序走完从「空系统」到「发出第一条消息」的全部配置:创建管理员、添加上游渠道、创建模型、设置默认模型与任务模型、配置嵌入模型,最后是几个可选增强项。
第 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 暴露站点时的配置要点
- 用户与配额:开放注册前先定好每日消息与图像限额
- 对话功能指南:把使用手册发给你的用户
- 管理后台概览:其余后台能力速览