入手一台 DGX Spark 的主要目的不是折腾硬件,而是把手上几个 AI 编码 Agent 从按 token 计费的订阅 API 挪回内网。两个动机:一是长上下文任务(一次上下文压缩就吞掉二十万 token)在云端成本压不住;二是历史会话和代码片段没必要出境。跑了八周,最花时间的部分并不是 vLLM 本身,而是让四个协议不同、思考档位语义不同、工具调用格式不同的 Agent 客户端在同一台推理机上同时正常工作。
下面按部署顺序记录,每个参数都给出取舍理由,未验证的地方单独标出来。
机器与环境
GB10 超级芯片,120GB 统一内存,aarch64 指令集,出厂预装 Ubuntu 24.04.5。
| 项目 | 实际值 |
|---|---|
| 系统 | Ubuntu 24.04.5 LTS / aarch64 |
| 驱动 | 580.178.04 |
| CPU | 20 核 Cortex-X925 |
| 内存 | 121 GiB 统一内存 |
| 待机功耗 / 温度 | 36 W / 60 ℃ |
有三条硬件特性影响了后面所有决策。
统一内存。 CPU 与 GPU 共享同一块物理内存,121 GiB 可以整体交给模型,这是这台机器敢开 256K 上下文的唯一原因。代价是模型常驻之后没有余量做别的,实测长期停在 111/121 GiB。
单卡。 无法同时驻留两份完整模型,热切换时可用内存约 12 GiB,一次加载几十秒。所以”多模型路由”在这台机器上只能靠外部网关兜住回退,不能靠本机起多实例。
aarch64。 所有镜像都要确认有 arm64 变体,只有 x86 的镜像在这一层直接失败,早期吃过一次。
散热方面,跑满时的降频做了核验:nvidia-smi -q -d PERFORMANCE 的 clocks_event_reasons 全程 0x0,没有主动降频事件。GB10 的功耗上限本身只有百瓦级,散热裕量比预期大。
网络用 netplan 配静态地址,有线接口的 autoconnect-priority 设为 100,无线作为备份接口。这个优先级不是可选项:早期无线没关自动连接,Wi-Fi 每次抖动都会抢走默认路由,导致推理服务”突然连不上”,发生了两次。
监控接进现成的 Zabbix,Agent2 7.4,加了 7 个自定义 Item 和 3 个触发器,覆盖显存占用、KV cache 使用率、请求排队和温度。其中”swap 常态换页”这一项被明确判定为 GB10 稳态而非故障,否则告警会天天响。
部署形态
最终是五个容器,而不是一条 docker run 拉起全部。
| 容器 | 职责 | 端口 |
|---|---|---|
| PostgreSQL | 网关的密钥、消耗记录、用户 | 内部 |
| vLLM | 模型引擎 | 内部 |
| LiteLLM | 协议网关与路由 | 4000 |
| API Gateway | 数据面边界代理 | 对外 |
| Management Gateway | 管理面 Web UI | 4001 |
拆开的理由是权限边界,不是微服务审美。
- master key 不进数据面。 API Gateway 只持有各 virtual key 的 SHA256 摘要,拿不到主密钥;管理面独立端口,不对公网暴露。
- 路由与引擎解耦。 引擎重启或换模型时,网关可以先把流量摘掉,客户端看到的是排队或回退,而不是连接拒绝。
- 边界代理承担兼容层。 八百行左右的薄代理,负责思考档位映射、system 消息重排、输出预算补齐和协议错误体转换。这些逻辑放在客户端要做四遍,放进 vLLM 要改引擎源码,放在这一层只做一遍。
LiteLLM 的模型注册用 YAML 声明式挂载,没用控制台的数据库注册。实测路由表在 LiteLLM_ProxyModelTable 里是 0 行,所有路由都来自挂载进容器的那份配置文件。这个区别在排查时很关键:控制台看不到模型、或者控制台改了不生效时,应该先看文件而不是怀疑数据库。配置骨架:
1 | model_list: |
模型别名与权重仓库名解耦是有意的:换一次量化版本不用去改四个客户端的配置。
vLLM 参数逐条
版本 0.1.dev20073+g8e685d198,NVFP4 量化权重。启动命令去掉路径与无关环境变量后是这样:
1 | vllm serve /models/candidate \ |
--max-model-len 262144。 256K 窗口。KV cache 占用与窗口长度线性相关,这一项决定了后面所有并发数字。
--gpu-memory-utilization 0.80。 vLLM 默认是 0.9。统一内存架构下 0.9 会挤压系统页缓存和宿主进程,早期出现过内存回收引起的请求毛刺,降到 0.80 之后没再复现。这不是玄学,是留 20 GiB 给引擎之外的进程。
--max-num-seqs 8。 调度上限,不是容量声明。后文会看到真实可用并发远低于它。
--enable-prefix-caching。 收益最大的一项。Agent 的多轮请求前缀高度重复(system + 工具定义 + 历史),前缀缓存命中与否,首 token 延迟差的是数量级。
--enable-chunked-prefill 与 --max-num-batched-tokens 8192。 256K 窗口的长 prompt 如果整块预填充,会把正在解码的请求全部堵住。分块之后 8192 token 一批,长请求插进来不会让在跑的流卡顿。批大小从 4096 试到 8192,再往上首 token 延迟开始回弹。
--kv-cache-dtype bfloat16。 量化权重配 BF16 的 KV cache。KV 用 fp8 在这里没有收益:瓶颈是内存带宽而不是容量,而精度损失会直接体现在长上下文的多跳检索上。
--mamba-ssm-cache-dtype float32。 混合架构的线性注意力状态必须保持 fp32,半精度会数值漂移,表现为长会话后半段答案质量下降。这是架构要求,不是调优选项。
--tool-call-parser qwen3_xml 与 --reasoning-parser qwen3。 工具调用走 XML 标记,思考内容独立成 reasoning 通道。两个 parser 配错的症状完全不同:前者是工具调用变成正文文本,后者是思考内容混进答案被客户端当成结果。
--speculative-config 的 MTP,num_speculative_tokens=2。 多 token 预测投机解码。2 是实测拐点:1 收益不够,3 之后接受率下降导致的回退抵消了收益。
--limit-mm-per-prompt。 多模态上限,见后文。
PIECEWISE cudagraph 与 splitting_ops。 混合架构下 FULL cudagraph 覆盖不到线性注意力的状态更新,必须分段捕获,代价是调度开销略高。这是部署这一代模型的必选项,不算性能优化项。
权重挂载有个坑值得单列:容器内 /models/candidate 映射到宿主模型目录,但实际生效的 config.json 来自另一份实验目录里的覆盖文件。也就是说在模型目录里改 config 不生效,改完重启发现参数没变,第一反应会误判成版本没生效。定位方式是 docker inspect 看挂载表,而不是看模型目录。
256K 其实是三个不同的数字
配置里写 262144,客户端显示 262144,真正能用的空间是另一回事。三层要分清:
- 引擎窗口——262144,由
--max-model-len决定的硬上限。 - 有效聊天空间——要减掉固定开销。实测固定前缀 28.5K token:system prompt 8.6K、工具定义 17.5K、skills 2.4K。
- 压缩触发点——网关侧阈值 130K,实际触发点约 123.5K。
第二层是踩坑踩出来的。最初压缩阈值设 100K,结果压缩频率约 23 次/小时:100K 阈值减掉 28.5K 固定开销,只剩 71.5K 真正留给对话,两三轮工具调用就触发一次。调到 130K 之后降到约 13 次/小时,安全校验是 123.5K 触发点加 65.5K 输出预留等于 189K,仍小于 262K。
即便如此,一个前缀本来就有 80-100K 的重会话仍然每 7-12 分钟压一次。这是结构问题,没调干净。
另有一条被推翻的假设值得记一笔:最初按”tokenizer 计数存在 25% 偏差”做过修正,后来判定这个修正本身不严谨——不同模型的 tokenizer 行为不同,正确做法是拿真实 token 数实测,而不是套一个比例系数。
并发:没验证的部分比验证了的更重要
从引擎调度日志采了 7983 条样本。
| 并发 | 吞吐 | 样本情况 |
|---|---|---|
| 1 路 | 28.3 token/s(单路中位) | 充足 |
| 2 路 | 40.9 token/s(合计) | 充足 |
| 3 路 | — | 仅 1 个瞬时样本,KV cache 86.2% |
持续 3 路并发可用这件事没有被证明。 所以我不会写”这台机器支持 3 路并发”。网关侧的并发门禁按 3 设置,是留了保守余量的。把 max-num-seqs=8 当 SLA 是这类部署最容易犯的错误,它只表示引擎最多愿意同时排 8 个序列,不表示 8 路都能有可用延迟。
超时问题的归因同样反直觉。有一段连续超时,怀疑是模型或引擎的问题,最后是三层客户端原因:
- 本地并发门禁:编排层
maxConcurrency=1 / queueLimit=2,超出直接返回 429,一天 104 条,请求根本没出门。 - 客户端主动取消:压缩请求 240 秒超时,取消掉 22 条。
- 公网链路 502:这一层根因目前仍未闭环。
24 小时账本是 570 success / 6 failure,p95 239.58 秒。p95 接近四分钟不是因为推理慢,而是里面包含了排队与压缩等待;分层统计之后,真正落在推理上的延迟分布是正常的。
四类 Agent 的接入差异
这是花时间最多的部分。四个客户端走三种协议,思考档位七档而引擎只有三档,工具调用格式各不相同。
| Agent | 协议 | 关键配置 |
|---|---|---|
| Codex | Responses | wire_api="responses" 加自定义头 X-Qwen-Profile |
| Claude Code | Anthropic Messages | 全部走环境变量 |
| WorkBuddy | Chat Completions | base_url 加模型名 |
| dsh | Chat Completions | 两个 compat 开关 |
Codex 走 Responses API。除 base_url、env_key 外必须显式声明三项窗口参数:model_context_window=262144、model_auto_compact_token_limit=131072、tool_output_token_limit=8192。第一项客户端会按模型名猜,猜错直接超窗;后两项不写的话一次工具输出就能把整个历史撑爆,实测有过 584098 字节的单次工具输出进历史。压缩走原生 POST /v1/responses/:compact,需要在边界代理的白名单里单独放行。
Claude Code 不需要配置文件,五个环境变量指向同一个模型即可:ANTHROPIC_BASE_URL、ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL,凭据走 ANTHROPIC_AUTH_TOKEN。网关侧要为 Anthropic 协议补两件事:CORS 显式放行 x-api-key, anthropic-version, anthropic-beta, anthropic-dangerous-direct-browser-access;错误体补 type: "error" 字段。缺后者时客户端不显示原因,只显示一句”请求失败”。
WorkBuddy 最省事,标准 OpenAI Chat Completions,给 base_url 和模型名就通。
dsh(DeepSeek Harness)需要两个 compat 开关:supportsDeveloperRole: false,发 developer 角色会被模板拒;maxTokensField: max_tokens,默认发的 max_completion_tokens vLLM 侧不认。还要显式声明 contextWindow: 262144 与 maxTokens: 32768,这两个数字不能都填 262144——输出上限等于上下文窗口时,客户端侧的压力校验直接抛错。
ZCode 也接过,同样要显式指定窗口(它按官方模型名做能力匹配,会把本地 262K 当云端 1M 处理),后来退出了验收范围。
边界说明:Claude Code 与 dsh 在这台机器上没有真机安装,只做到协议层与配置层验证。真机端到端跑通的是 Codex 与 WorkBuddy 两家。总验收的口径是:协议转换用例 57/57、parser 用例 57/57、真实客户端用例 32/32,250046 input token 下三处位置标记全部识别正确。
思考档位:七档塌缩成三档
引擎原生只有 low / medium / xhigh 三档,客户端暴露 high / xhigh / max / ultra。透传的结果是 400,所以必须在边界代理做映射:
1 | none / minimal / low → low |
映射的代价是”界面显示八档、实际三档”,这是等价性的真实损失,得承认。它比另一种做法好:白名单外一律 400,客户端直接不可用。
围绕档位还有三个坑。
extra_body 与顶层不等价。 LiteLLM 1.101 对两条载体的合并优先级不一致,表现为”显式关闭思考但仍在思考””low 变成了 xhigh”。修法是在代理层统一顶层与 extra_body 里的 reasoning/thinking 载体,并固定优先级:现代 effort 语义优先,显式关闭优先。
legacy budget_tokens 不能真限流。 旧的 Anthropic 思考预算被直传采样器,思考会被硬截断。处置是它只作强度提示,走 1024/2048/4096 的既有阈值映射,不进采样器。语义上这不完全等同于原预算上限,属于已知妥协。
null / default 必须显式拒绝。 客户端会发可选等级的空值,落到引擎是隐式行为。代理层直接返回 400 并列出可取值,比让它静默降级好排查。
max_tokens 缺失也要补。客户端省略时上游不会自动补,表现为随机截断。代理补 max_output_tokens = max(default_output, budget + 8192),并硬校验输出上限在 1 到 262144 之间,思考预算不小于输出上限,否则 400。
system 消息重排是另一处必改。Qwen 的 ChatML 只接受单条前导 system,而新客户端会发多条 system/developer。代理把它们合并置顶,非文本 content 一律拒 400 而不是静默字符串化——静默字符串化会把多模态内容变成一串看不出问题的 JSON 文本,问题会推迟到很后面才暴露。
压缩队列隔离
有一段时间每天出现 77 个最终 400。根因是”只接受摘要、拒绝 tools 的压缩服务”被放进了普通推理的回退链:普通请求打进去被拒,压缩请求带着 tools 打进去也被拒。
修复方式是把两个入口彻底分开:普通恢复与摘要各自独立 provider、独立并发槽,底层是同一个上游服务,靠 provider 维度做队列隔离。之后做了故障注入验证——两个压缩任务正在跑的时候,普通恢复请求 0.8 秒完成、零排队;分离之前同样的注入下是 75 到 134 秒。
这个数字的口径必须说清楚:它是故障注入结果,不是长期生产统计。它能证明隔离有效,不能证明日常延迟就是这个水平。同轮另一项证据更可靠:分离之后 133 次真实请求全部 200,路由未就绪 0 次。
配套还修了几处压缩阈值的查找问题:成员带固定后缀时,查找需要 provider 通配才能命中;分组级覆盖在新版本里被忽略(实际取成员最小值),所以不生效的 group/* 覆盖要删掉,按成员阈值落实并读回。
多模态:把识图关到专用路由
一开始的做法是让所有路由都能识图,结果是免费池的 502 拖垮了主链,视觉请求跨供应商回退还造成上下文污染。最终策略三条:
- 全局跨供应商识图关闭,只保留已验证具备原生视觉能力的成员。
- 识图集中在一个专用路由组,成员全部降档到最低思考强度。识图不需要深度思考,档位降下来吞吐差别明显。
- 图片 URL 抓取不跟跳转、不吃环境代理(
follow_redirects=False、trust_env=False),避免 SSRF 与环境代理污染。
换到专用组之后,此前某个上游累计 138 次的视觉 EOF/502 完全停止,识别请求由专用组接管,基本全部成功。
引擎侧的硬上限是单请求 64 张图,65 张直接 400。已验通过的组合:64 张 512px(三种协议)、64 张 1024px、4 轮历史各 16 张。被拒之后引擎本身健康,不是崩溃。代理层不做额外的图片裁剪或降采样,把上限交给引擎是更省事也更诚实的做法。
让 WAF 只放行推理路径
推理服务经雷池 SafeLine 暴露到公网。默认策略下推理接口会被语义引擎误拦:工具调用的参数里出现 git log --oneline -1、SELECT ... OR 1=1 这类内容,命中 SQLi 和命令注入规则太正常了。
社区版这里有条硬限制:站点级关闭内置增强规则会返回 license required,于是只剩语义 dry_run 加 ACL 精确放宽这一条路。做法是”POST 方法 + 五个推理 URI + JSON Content-Type”三条同时成立才放行,其余照旧拦截。
关键的是反向验证:用 GET 带一个 SQLi 探针打同一路径,仍然返回 403。这证明放行规则没有越权。只验通”能过”是不够的,还得证明”别的情况过不去”。
即便如此仍有 7 个边界样本被拦,原因未定位。另外要明确一点:401 只证明请求到达了鉴权边界,不代表推理成功。
其他几个坑
- CLI 的写副作用比预期大。 一条切换分组的命令会删掉客户端配置里的 provider 段和模型目录引用。每次操作后必须读回配置,不能假定”命令返回 0 就只改了该改的”。
- 直接改 JSON 配置会被覆盖。 编排层的配置有内存态,手工写入的字段会在下一次保存时被覆盖,规则变更必须走 CLI。
- shell 语法坑。
变量名:low在 zsh 里会被当变量修饰符吞掉,必须写${变量名}:low。这类错误的表现是规则静默失效,很难查。 - 设置命令的隐藏语义。 一处”设置分组”的操作会清空该分组的规则,所以每次设置后需要重新加规则。
- 嵌套分组带档位后缀是非法语法,导致路由被标记为未就绪,186 个探针里命中 11 次。
- 客户端进程会缓存旧模型目录,改完配置显示的还是旧窗口值。正确处置是读回网关实际版本,而不是中断活跃任务去重启客户端。
- 流式中断不做跨模型拼接。 半截响应跨模型续拼会产生脏内容,策略是流已经开始就不换上游,4xx 原样返回。
- 回滚脚本默认只读。 校验通过才允许
--apply,并且拒绝未知漂移。回滚脚本默认执行恢复是一件很危险的事。
仍然没解决的问题
- 持续 3 路并发未验证。 要做受控压测才能给出容量结论。
- 公网 502 根因未闭环。 影响面小,但没定位。
- 会话亲和导致重复命中同一个坏 key。 同会话锁定同 key 并触发退避时表现为反复 502。根因已识别,修复被别的事打断,没落地。
- 重会话压缩频率仍偏高。 前缀 80-100K 的会话每 7-12 分钟压一次,这是固定开销结构决定的,不是参数能解决的。
- 内存余量偏紧。 111/121 GiB 常驻,想加第二个模型必须先解决这件事。
- 单机单点。 所有 Agent 都指向它,它挂了就全部回退订阅 API,而这个回退目前是手动切换。
- 一个上游的端口写错(8000 应为 8080)。 已定位,修复清单在仓库里,决定暂不执行。
如果只抄三条
- 先测容量再写宣传。 从引擎自己的调度日志里统计真实并发吞吐,别把
max-num-seqs当 SLA。 - 超时报错先查客户端。 那一天 104 次”超时”里绝大部分是本地排队超时直接拒绝,请求根本没出门。
- 思考档位一定显式映射,并承认映射后的等价性损失。 透传换来的是 400,映射换来的是”界面显示八档、实际三档”——至少后者是可控的。
本文中的主机地址、模型权重来源与上游供应商名称已做脱敏处理,具体环境不具指代。