迁移到 Xinference 3.0#

Xinference 3.0 对身份验证、Web UI 和容器部署进行了现代化改造。大多数工作负载无需修改即可继续使用，但少数行为和参数被移除或重命名。本页列出了所有不兼容变更及相应的应对方法。

身份验证默认启用#

从 v3.0 开始，基于数据库的身份验证系统 默认启用。在全新部署中，每次 API 调用都需要登录或提供 API Key。

  • 首次启动时，请打开 Web UI（或调用 POST /v1/admin/setup）创建初始管理员账号。完整流程参见 身份验证系统（基于数据库）。

  • 若要恢复之前的无身份验证行为，请设置：

    export XINFERENCE_AUTH_ADVANCED=false

  • 与启用身份验证的服务器通信的现有客户端和脚本，现在必须先登录（xinference login / client.login()）或传入 API Key（--api-key / api_key= / Authorization: Bearer <key>）。

旧版 --auth-config 系统已移除#

通过 xinference-local 和 xinference-supervisor 的 --auth-config 参数配置的内存态 JSON 身份验证系统已被移除，其静态 auth_config.json 格式也一并移除。该参数已不复存在。

若要将旧的用户和 API Key 迁移到新的基于数据库的系统，请使用迁移命令：

xinference-migrate-auth \
  --auth-config /path/to/old/auth_config.json \
  --db-path ~/.xinference/auth/auth.db \
  --encryption-key <your-encryption-key> \
  --dry-run   # preview first, then run again without --dry-run

传给 --encryption-key 的值必须与升级后服务运行时使用的密钥**完全相同**，即 XINFERENCE_AUTH_ENCRYPTION_KEY 的值或持久化在 <XINFERENCE_HOME>/auth/encryption_key 中的值。它不是一次性的迁移密钥。如果使用了不同的密钥，迁移后的 API Key 哈希仍可用于鉴权，但 Xinference 无法解密或显示已保存的 Key 明文。

如果管理员密码丢失，拥有 shell 访问权限的运维人员可以使用 xinference-reset-auth-password 离线重置——参见 身份验证系统（基于数据库）。

权限范围重命名#

若干细粒度的权限范围被合并并重命名：

旧权限范围

新权限范围

models:start

models:write

models:stop

models:write

models:add

models:register

admin （用于日志相关接口）

logs:list

admin （旧版 API Key 明文查看接口所需）

keys:manage （查看任意用户的 Key 列表，以及更新、删除、查看明文和管理每个 Key 的模型权限）

API Key 创建权限保持独立：创建 Key 需要 keys:create；为其他用户创建时还需要 keys:manage。

携带旧权限范围名称的令牌和 API Key 仍然可用：服务器会透明地将旧名称映射到新名称。该兼容映射已被弃用，并将在未来版本中移除，因此请更新所有授予权限的自动化脚本，改用新名称。

新的默认 Web UI（Next.js）#

Web UI 已使用 Next.js 重写并成为默认界面；旧版 React UI 已被移除。UI 在构建时静态导出，并由 Xinference 服务器本身提供服务——无需单独的前端进程。

  • XINFERENCE_FRONTEND_ENDPOINT 环境变量已被 移除。若要提供自定义的前端构建产物，请改用 XINFERENCE_FRONTEND_DIST_DIR 指向其所在目录。

  • 旧的 /ui/ 路径会重定向到 /。打开 / 即进入模型启动页面。

内置 Gradio 演示页面已移除#

针对每个模型的 Gradio 演示 UI（之前挂载在 /{model_uid}）及其背后的 /v1/ui/* 接口已被移除， gradio 依赖也一并移除。若要与运行中的模型交互，请改用 Web UI、OpenAI 兼容 API 或 Python 客户端。

官方 GPU 镜像要求 CUDA 13，并按需安装推理引擎#

官方 3.0 GPU 镜像现在是基于 nvidia/cuda:13.0.2-devel-ubuntu22.04 的精简镜像，要求 NVIDIA 驱动版本为 580 或更高。镜像仍包含 Python 3.12、共享的 CUDA PyTorch 栈和 Transformers 引擎，但不再预装 vLLM、SGLang、llama.cpp 或其他可选推理引擎。

模型需要这些引擎时，Xinference 会在首次启动时将其安装到该模型专属的虚拟环境中。因此首次启动耗时更长，并且需要访问 PyPI 或兼容的私有软件包镜像；后续启动会复用该环境。

对于离线或隔离网络的 Compose 部署，请拉取或传输匹配的 xprobe/xinference-pypiserver 镜像，并将其固定为与 xprobe/xinference 相同的发行标签。也可以通过 docker-compose.byo-wheels.yml 覆盖文件提供自己的 wheel 目录。完整要求请参见 Docker 镜像 和 Docker Compose 部署。

严格的 Qwen3 系列系统消息顺序#

对于聊天模板要求系统消息位于首位的模型系列（包括 Ornith-1.0-35B、qwen3.5、qwen3.6 和 Nex-N2），Xinference 现在会在分发请求前验证消息顺序。若 system 消息不在 messages[0]，将返回 HTTP 400。升级前，请将所有系统指令合并到一条位于首位的系统消息中。

Docker Compose 版本要求#

随附的 Compose 文件移除了已弃用的 version: 字段，并使用了较新的 Compose 特性，因此使用它们部署需要 Docker Compose v2.24.4 或更高版本。参见 Docker Compose 部署。