快速入门

从安装到可用的 RAG 栈

激活许可证就可以用了：安装脚本已经把 AI 模型登记给每个新用户，对话和知识库不需要任何模型配置。第 2、3 步是可选的——让模型统一走内置 API 网关，适合想集中管理渠道、令牌和用量的情况。

1步骤 1

激活许可证

Admin ▸ License
购买 → 付款
自动激活

2步骤 2

连接网关（可选）

Sovnex API ▸ 控制台
添加 Ollama Channel
创建 Token

3步骤 3

配置提供方（可选）

Settings ▸ Providers
添加 Sovnex API
用于 Chat / RAG

激活许可证

admin console · Web 门户

每个部署出厂时均未激活。你只需在 admin console 中激活一次。当你从 admin 端购买时，激活将自动完成 — 你无需手动复制任何激活码。

1.1

登录 admin console

打开 http://<your-host>/admin，用 admin@sovnex.io 和安装脚本结尾打印的密码登录（密码也写在 .env 的 DEFAULT_SUPERUSER_PASSWORD 里）。

已经没有出厂默认密码了——每次安装都会随机生成一个。首次登录后请换成你自己的密码。

1.2

打开 License — 显示为 "Not activated"

License 页面会显示部署状态和唯一的 Install ID。点击 "Purchase a plan"：它会将该 Install ID 带入结账流程，从而将许可证绑定到这个特定部署。

显示 Not activated 和 Install ID 的 License 页面

1.3

选择套餐

定价页面会在浏览器中打开。选择一个套餐 — 7 天免费试用、Monthly 或 Annual。你的 Install ID 会随链接一并传递。

1.4

注册并验证邮箱

创建门户账户并确认验证邮件。随后即可登录以完成购买。

1.5

使用银行卡付款

完成 Stripe 结账。想测试流程？Stripe 测试模式接受卡号 4242 4242 4242 4242，有效期填任意未来日期、CVC 填任意值即可。

结账已预先绑定到你的 Install ID — 正是这一绑定使激活自动完成，无需粘贴任何激活码。

1.6

订阅变为激活状态

你的门户账户此时会显示 Paid · active、席位数以及 Bound install（你的 Install ID）。

1.7

你的部署自动激活

回到 admin License 页面，状态会在约 30 秒内变为 Valid — 套餐、席位和到期时间都会显示出来。无需复制任何内容。

需要改用手动激活？在 "Activate online" 下粘贴激活码，或在 "Import offline license" 下上传 .lic 文件。

可选：将 API 网关连接到本地模型

网关控制台（在新标签页中打开）

对话并不需要这一步——安装脚本登记的模型已经对所有用户可用。Sovnex 还内置了一个 OpenAI-compatible 的 API 网关：只需将它指向本地 Ollama 一次，所有用户的请求都会经由它路由 — 无需为每个用户单独管理端点。

2.1

打开网关控制台

在 admin console 中，打开 Sovnex API。绿色的 "Connected" 状态表示网关运行正常。点击 "Open management console" — 它会在新标签页中自动为你登录。

显示 Connected 和 Open console 的 admin Sovnex API 页面

2.2

添加 Ollama Channel

在控制台中进入 Channel → New Channel，并设置 Type = Ollama。Base URL 在 Linux 上为 http://ollama:11434、在 macOS(Docker Desktop)上为 http://host.docker.internal:11434，Key 可为任意非空值（例如 ollama），Models 必须填写你真实的 Ollama 模型名称。

Base URL 没有 /v1 后缀 — 网关会自行追加该路径。添加 /v1 会导致其失效。

选择 Ollama 会预填一个模板模型列表。网关不会自动发现你的模型 — 请清空它并填入你自己的名称，取自 `ollama list`（例如安装脚本拉取的那两个：qwen2.5:7b、bge-m3:latest），标签需完全一致。

在 Docker Desktop 上，即使 Ollama 仅监听 127.0.0.1，host.docker.internal 也能访问到宿主机上的 Ollama。

GPU 机型上安装脚本启动的是 vLLM 而不是 Ollama。表单填法一样：Type 选 VLLM，Base URL 对话模型填 http://vllm-chat:8000、向量模型填 http://vllm-embed:8000，Models 填服务器启动时用的模型名（Qwen3.8-27B、bge-m3）。

2.3

保存并验证 channel

该 channel 会显示为 Enabled。使用 "Test Enabled Channels" 确认网关能够访问 Ollama 并运行模型。

显示已启用的 Local Ollama channel 的 Channel 列表

2.4

创建 API token

进入 Token 并添加一个 token。它的 key（以 sk- 开头）就是你的 sovnexAI 用户将在下一节中粘贴到模型提供方里的 API 密钥。

可选：在应用里使用网关的模型

sovnexAI 应用 · Settings

现在让 sovnexAI 用户通过网关来使用这些模型。"Sovnex API" 是一个内置提供方，因此 base URL 已为你预先填好 — 这里以该网关为例。

3.1

打开 Model providers

以用户身份登录应用，然后打开 Settings → Model providers。安装脚本登记的模型已经在 "Added models" 下，默认 LLM 和 Embedding 也已选好——除非想让它们走网关，否则无需任何操作。"Sovnex API" 位于提供方列表的顶部。

已含安装脚本登记模型、顶部为 Sovnex API 的 Model providers 设置页面

3.2

通过网关添加模型

点击 Sovnex API → Add。选择模型类型 Chat，填入与网关中完全一致的模型名称（qwen2.5:7b），并将网关 token（sk-…）粘贴为 API-Key。Max tokens 要填模型服务实际运行的上下文长度：安装脚本的 Ollama 模型是 8192，vLLM 对话模型是 32768。填小了，检索到的内容会被悄悄丢弃；填大了，提示词会被截断。

Base URL 已预填为 http://sovnex-api:3000/v1 — 即网关在 Docker 内部的地址。请使用服务名 sovnex-api:3000，而非 localhost:3001：后端是通过内部网络访问网关的。

包含模型名称、base URL 和 key 的 Sovnex API 提供方对话框

3.3

设为默认并开始使用

该模型现在会出现在 "Added models" 下。要让对话走网关，就把它选为默认 LLM，替换安装脚本直连登记的那个。Embedding 不用管：安装脚本已经登记好 bge-m3——只有也想让向量计算走网关时，才同样通过 Sovnex API 添加它。现在它已可在 Chat、Search 和 Agents 中使用。

重排模型不能走网关——网关对标的是 OpenAI 接口，而其中没有重排这一条，请求根本到不了路由。vLLM 安装下，安装脚本已经直连登记好重排模型（提供方 VLLM，Base-Url http://vllm-rerank:8000/v1），无需再添加。详见用户手册的《模型接入》。