Skip to main content

首次运行配置

按照快速部署把容器拉起来之后,系统里还没有任何用户、渠道和模型。本页按顺序走完从「空系统」到「发出第一条消息」的全部配置:创建管理员、添加上游渠道、创建模型、设置默认模型与任务模型、配置嵌入模型,最后是几个可选增强项。

第 1 步:创建管理员账号​

浏览器打开你的站点。全新部署(用户数为 0)时会自动进入首启设置页 /setup,填写三个字段:

字段要求
邮箱作为登录账号
名字显示名
密码至少 8 个字符

提交后,这个账号立即成为管理员并自动登录,不需要邮箱验证。

/setup 只有一次机会

系统中一旦存在任何账号,/setup 就永久失效(再访问返回 409)。所以部署完成后请尽快完成这一步,不要把一个「零用户」的实例长时间暴露在公网上,否则任何先访问到的人都能把自己注册成管理员。

后续的用户管理(邀请、封禁、配额)在管理后台进行,见用户与配额。

第 2 步:进入管理后台​

管理后台入口有两个,效果相同:

  • 侧栏底部的账号菜单里的管理入口;
  • 直接访问 /admin。

后台各页面的总览见管理后台概览。首次配置主要用到「渠道 Channels」和「模型 Models」两页。

第 3 步:添加渠道(Channel)​

渠道是一条到上游模型服务商的连接。所有服务商 API Key 都保存在数据库的渠道表里,不写在 .env 中。进入管理后台的「渠道 Channels」页,新建渠道时选择类型并填写连接信息:

渠道类型适用上游需要填写
AnthropicAnthropic 官方或兼容其协议的服务Base URL + API Key
OpenAIOpenAI 官方或兼容其协议的服务Base URL + API Key
GeminiGoogle GeminiBase URL + API Key
OpenAI 兼容任何暴露 OpenAI 格式接口的中转、聚合或本地推理服务Base URL + API Key

字段说明:

  • 类型:决定 Aivory 以哪种协议格式调用上游。用官方 API 就选对应官方类型;用中转或自建推理服务通常选「OpenAI 兼容」。
  • Base URL:上游服务地址。
  • API Key:上游签发的密钥,保存在数据库中。

一个部署可以同时添加多个渠道(例如一个 Anthropic 官方渠道加一个 OpenAI 兼容中转),渠道本身对普通用户不可见,用户只会看到下一步创建的「模型」。渠道管理的完整说明见渠道与模型。

没有 API Key 也想先验证?

在 .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(该模型不使用工具)
研究开关该模型是否可用于深度研究,见深度研究

模型启用后立即出现在所有用户的模型选择器中。建议起步至少创建:

  1. 一个主力 chat 模型(开启 stream,按上游能力设置 vision 和 tool_mode);
  2. 一个便宜快速的小模型,下一步可指定为任务模型;
  3. 如需知识库,再建一个 embedding 模型(见第 6 步)。
上游模型 ID 写错是最常见的翻车点

名称是给用户看的,可以随便起;「上游模型 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 的模型(走某条渠道),并把它设为嵌入模型。

无论哪种方式,都要注意维度一致性:

EMBEDDING_DIM 必须与模型输出维度一致

Qdrant 按嵌入宽度使用独立 collection。如果维度配置与模型实际输出不一致,系统会退回内置的 256 维本地 embedder,它的 collection 与 1536 维模型向量互不兼容,检索质量也只适合开发测试,不适合生产。例如 text-embedding-3-small 对应 EMBEDDING_DIM=1536。

完全不配置嵌入模型时,知识库仍可创建,向量检索关闭时 RAG 会回退为把范围内的完整文档文本注入上下文。知识库的日常使用见知识库指南。

第 7 步:发送第一条消息验证​

回到聊天界面:

  1. 在模型选择器中选中你刚创建的 chat 模型;
  2. 发送一条消息,确认能收到流式回复;
  3. 如果模型开启了 vision,可以再发一张图片验证多模态;
  4. 如果 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。完整流程见备份与迁移。

下一步​