Xinference 4.2 部署实测:默认单请求只有 5120 token

Xinference 4.2 能在一台 16GB 内存的 M4 上把 Qwen3-8B 跑起来,解码 18.7 tok/s,和 Ollama 的 19.5 tok/s 几乎打平。但它默认每个请求只给 5120 token,装完直接 curl 还会全是 401。按下面五步走完,从零到出第一句回答大约 10 分钟,冷启动下载 4.7GB 另算。

测试环境:Mac mini M4 / 16GB 统一内存 / macOS / Python 3.12.12 / uv 0.10.7 / xinference 4.2.0。本文所有数字都在这台机器上现跑,命令可直接复制。

先看版本:4.2 和你收藏的中文教程不是一回事

装完第 24 个依赖之后,你会看到一个 1.1GB 的虚拟环境和一堆没见过的命令:xinference-local、xinference-service、xinference-router、xinference-supervisor、xinference-worker。这套东西已经不是单纯的模型服务,而是一个带用户、API key、限流、黑名单的小型网关。

网上能搜到的中文教程大多停在 1.x,那个版本的 curl http://127.0.0.1:9997/v1/models 会直接吐出模型列表。在 4.2 上同样的命令返回这个:

{"detail":"Could not validate credentials"}

所以第一个坑不是安装,是鉴权。4.2 的数据库鉴权默认开启,常量文件里写得很直白:XINFERENCE_AUTH_ADVANCED 默认 true,要完全关掉才需要显式设成 0。

第一步不是装,是把管理员账号建出来

启动命令很朴素,两个参数就够:

uv venv -p 3.12 .venv
uv pip install --python .venv/bin/python xinference
.venv/bin/xinference-local -H 127.0.0.1 -p 19997

第一次启动会在日志里打一段方块字,把 setup token 直接印出来,这是唯一一次显示机会:

FIRST-RUN SETUP REQUIRED
Setup token: cpzTDjtGNQ0PgwawRrk7Y9b2oT771sB9iJAgUMoQ1RA
Create the initial admin account at POST /v1/admin/setup

拿这个 token 建号,密码最少 8 位,返回 201 表示成功:

curl -X POST http://127.0.0.1:19997/v1/admin/setup \
  -H "Content-Type: application/json" \
  -d '{"setup_token":"<上面那串>","username":"yc","password":"xinf-test-123"}'

返回体只有两个字段:{"id":1,"username":"yc"}。要确认状态可以查一个不需要鉴权的接口:

curl http://127.0.0.1:19997/v1/admin/setup/status
{"needs_setup":false,"initialized":true,"password_min_length":8}

如果你的场景就是本机一人用,不想碰这套账号体系,可以整个跳过:启动前加 XINFERENCE_AUTH_ADVANCED=0。实测这样起的实例,/v1/models 直接 200,而 /v1/admin/keys 变成 404,管理路由根本不存在。

登录要 JSON,API key 只够推理用

账号建好之后先用它换 JWT。这里有一个容易卡住的细节:标准 OAuth2 的密码流是表单提交,Xinference 4.2 认的是 JSON。发表单会得到一句很短的拒绝。

curl -X POST http://127.0.0.1:19997/token -d 'username=yc&password=...'
{"detail":"Request body must be a JSON object"}

curl -X POST http://127.0.0.1:19997/token \
  -H "Content-Type: application/json" \
  -d '{"username":"yc","password":"xinf-test-123"}'

换成 JSON 后返回 access_token 和 refresh_token,注意返回体里没有 expires_in 字段,看起来像永久的。实际 JWT 有效期 30 分钟,由 XINFERENCE_ACCESS_TOKEN_EXPIRE_MINUTES 控制。我本轮就是被这条坑了一次:写完半篇文章回来发请求,全部 401,还以为是 token 泄漏被封。

长期跑脚本不要用 JWT,用 API key。创建方式如下,返回的 key 只显示一次:

curl -X POST http://127.0.0.1:19997/v1/admin/keys \
  -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" \
  -d '{"name":"local-test"}'
{"id":1,"key":"xf-IBJX...","prefix":"xf-IBJX","name":"local-test"}

但 API key 的权限被刻意收窄了。用它调推理接口没问题,用它启动模型会被直接拒绝,报错原文是 API keys can only access model query and inference endpoints。这也是命令行工具为什么要先 xinference login:不登录,xinference launch 连模型都起不来。

三个参数写错就报 Model not found

启动模型的接口是 POST /v1/models,四个字段一个都不能省,而且写法跟直觉不一样。下表是本轮逐个试错试出来的。

字段 正确写法 写错的报错原文
model_engine 必须显式传 llama.cpp / MLX / Transformers Invalid input. Please specify the `model_engine` field.
model_size_in_billions “0_6″(下划线) Model not found, name: qwen3, format: ggufv2, size: 0.6, quantization: Q4_K_M
model_format ggufv2 Model not found(同一句式,不提示格式无效)
quantization Q4_K_M、Q8_0、4bit 等,须与引擎匹配 Model not found(同一句式)

四条错误里前三条都长一个样,都是 Model not found,唯一的线索是报错里回显的 size 值。0.6 会被原样回显成 0.6,说明它没被识别成合法尺寸;写成 0_6 立刻通过。这个下划线来自注册表里的 0_6b 命名,跟小数点在语义上是一回事,但在代码里是两个字符串。

选引擎之前先查一下这台机器到底支持哪些组合。查询命令需要服务在跑:

xinference engine -e http://127.0.0.1:19997 -n qwen3 -s 8

Qwen3-8B 在 4.2 里挂的引擎有 Transformers、vLLM、SGLang、llama.cpp、MLX 五家,其中 llama.cpp 一家就列了 37 个量化档(从 UD-IQ1_S 到 BF16),MLX 只有 3bit 和 4bit 两档。macOS 上 vLLM 和 SGLang 装不上,实际能用的只有另外三个。

默认每个请求只有 5120 token

这是本轮最值得写进正文的一条。启动 8B 之后看日志,会连着出现三行关键信息:

n_ctx: 40960, n_batch: 2048, n_parallel: 8
load_model: initializing, n_slots = 8, n_ctx_slot = 5120

也就是说 40960 的上下文被平均切给了 8 个并发槽,每个请求实际能用 5120。这个 8 不是可调参数,源码里写死成 min(8, cpu_count),M4 是 10 核,所以恒定拿到 8 槽。

实测边界很清楚:5028 token 的输入正常返回,耗时 8.8 秒,prefill 速度 178 tok/s;把同一段材料扩到 8719 汉字(约 6300 token)后,请求在 0.1 秒内就返回 500,报错正文只有一句 Compute error.,没有任何上下文超限的提示。

想提高单请求上限,要传 context_length。但这个参数是每槽的值,框架会自己乘 8 作为 llama.cpp 的 n_ctx。我传 16384,日志里的 n_ctx 变成 131072,每槽确实是 16384,代价也立刻显现:

ggml_metal_synchronize: error: command buffer 0 failed with status 5
ggml_metal_graph_compute: backend is in error state from a previous
command buffer failure - recreate the backend to recover

Metal 后端进入错误态之后,这个实例对任何请求都返回 500,连一句「你好」也不行。llama.cpp 自己给出的解法就是重建后端,落到 Xinference 上等于 xinference terminate 换一个新的 model_uid 重载。下表是三个档位的实测。

context_length n_ctx 每槽可用 实测结果
不传(默认 5120) 40960 5120 5028 token 通过,常驻 4.3GB,稳定
16384 131072 16384 加载后 4.55GB,长请求触发 Metal 报错,实例报废
32768(估算) 262144 32768 16GB 机器放不下 KV,不建议尝试

16GB 机器上要给单请求 16K 上下文,等于要求 KV cache 按 13 万 token 预留,Qwen3-8B 每 1K 约 144MB,这笔账本身就不成立。所以这台机器上 Xinference 的实际可用上下文就是 5120,要长文处理得换 4bit 量化加更小的模型,或者干脆走 Ollama 那条路,Ollama 的 num_ctx 是单槽语义,没有这个乘法。关于 num_ctx 的坑,早前那篇 Ollama 上下文实测 里有更细的账。

三引擎实测:0.6B 差 7 倍,8B 打平 Ollama

同一台机器、同一个模型(Qwen3-0.6B)、同一句提示词、temperature 0,只换引擎。客户端墙钟计时,每次跑 150 token。

引擎 / 量化 下载体积 首次启动 解码速度 备注
MLX / 4bit 336MB 67.5 秒 213 tok/s 两次 208 与 219,最快
llama.cpp / Q4_K_M 385MB 41 秒 154 tok/s 两次 135 与 173,波动大
Transformers / fp16 1.4GB 82.6 秒 30 tok/s 首次含预热只有 21

0.6B 这一档 MLX 比 Transformers 快 7 倍,差距主要来自 fp16 与 4bit 的计算量,以及 Metal 后端是否真的被用上。这和之前那篇 MLX 跑 8B 的横向实测 结论方向一致:短输入下 MLX 有优势。

到了 8B,差距被抹平。Xinference 的 llama.cpp 引擎三次跑出 17.4、18.2、18.7 tok/s,Ollama 同一句提示词稳定在 19.5 tok/s,差 4%。内存这一侧 Xinference 占优,模型进程 RSS 实测 4.3GB,Ollama 的 /api/ps 报 5.08GB。两边用的都是 Q4_K_M 权重,差的这 0.8GB 主要是默认上下文预分配的 KV 不同。

顺带一个测速口径问题:只有 llama.cpp 引擎会在响应体里带 timings 字段,给出 prefill 与 decode 的 tok/s。MLX 和 Transformers 的响应体里没有这个字段,只能客户端计时。拿同一段测速脚本套三家,后两家会被算成 0。

三个真实失败点与判断方法

第一个是 Compute error. 的两种来源。第一种是单请求 token 超过 5120,特征是 0.1 秒内立刻失败,失败之后发一句「你好」仍然正常。第二种是同机内存被别的进程占着,特征是短请求也一起失败,且日志里有 Metal 的 command buffer 报错。判据就是拿一句「你好」试一下:能回就是超限,不能回就是显存。我本轮在 Ollama 还驻留 5GB 时踩过第二种,两个 8B 同时在一台 16GB 机器上,Xinference 这边直接连着 500。

第二个是思考链把输出吃到空。Qwen3 是混合推理模型,Xinference 默认让思考链跑起来,而它在两种返回方式下的落点不一样:非流式的 content 里直接混着思考过程,看不出边界;流式的 content 恒为 null,内容全在 delta.reasoning_content 里。只读 content 的客户端会拿到一片空,还以为是服务坏了。关掉的办法实测两个都有效:在提示词末尾加 /no_think,或者传 chat_template_kwargs 里 enable_thinking 为 false,同一个问题从 254 字思考降到 49 字直接回答。

第三个是返回体里的 model 字段。它不是你以为的 model_uid,而是本地 GGUF 文件的绝对路径,长这样:/Users/yc/.../qwen3-ggufv2-8b-Q4_K_M/Qwen3-8B-Q4_K_M.gguf。任何按 resp["model"] == "qwen3" 做判断的代码都会失败。同理,日志里出现的 uid 带 -rep0 后缀,接口里没有这个后缀,两边对不上属于正常。

还有两条跟磁盘有关的细节。模型默认不落在 Hugging Face 缓存,日志会打印 Auto-detected download hub: modelscope,判断依据是本机请求 huggingface.co 会走环境代理,于是直接跳到魔搭,探测超时默认 3 秒。落盘位置在 XINFERENCE_HOME/modelscope/models/<作者>--<仓库>/snapshots/master/,而 cache/v2 下面只是一层软链,所以 4.7GB 的模型只占一份空间。要复制整个 XINFERENCE_HOME 到别的机器,记得走 rsync -L 或 cp -L,否则搬过去全是断链。

它和 Ollama 该选谁

单机单人、就想跑一个模型聊聊天,Ollama 更省事,装完不用建账号不用发 token。Xinference 值得用的是另外三种场景:要给多个人发不同的 key 并按 key 限流;要在同一端口上切换 llama.cpp 与 MLX 两种后端做对比;或者要把推理服务和用户体系一起交出去。

如果只是想在浏览器里用一个本地模型,中间加一层网关也行。之前那篇 LiteLLM 代理 Ollama 的配置记录 走的是轻量路线,几百 MB 就能起来;Open WebUI 免 Docker 安装 那份记录则是把前端一起解决掉。三个方案解决的是不同层的问题,别指望一个工具全包。

常见问题

装完 curl 全 401,是不是装坏了? 没坏,4.2 默认开数据库鉴权。去启动日志里找 setup token,调一次 /v1/admin/setup 建管理员,再决定是用 JWT 还是建 API key。实在不想管,启动时加 XINFERENCE_AUTH_ADVANCED=0 直接关掉。

16GB 内存能跑多大的模型? 8B 的 Q4_K_M 权重 4.7GB,加默认 40960 的 n_ctx,实测能跑,解码 18.7 tok/s。再往上 14B 会开始和系统抢内存,建议直接上 4bit 量化并且把 context_length 压到 2048 以下,代价是单请求只能聊很短的内容。

Xinference 和 Ollama 能同时装吗? 端口不冲突,Xinference 用 9997,Ollama 用 11434。真正的冲突在内存:两边各驻留一个 8B 就会互挤,Xinference 那边的表现是一律 500 加日志里的 Metal 报错。要对比测速就一个一个来,别同时开着。

全部文章归档与模型专题