DGX Spark 部署 vLLM:256K 上下文本机推理与四类 Agent 接入实录


入手一台 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
2
3
4
5
6
7
model_list:
- model_name: qwen3.8-flash-next # 对外别名,与权重仓库名解耦
litellm_params:
model: hosted_vllm/qwen3.8-flash-next
api_base: http://<vllm-host>:<port>/v1
api_key: os.environ/DGX_API_KEY
# 家庭自用,价格全部置 0,只用于消耗记账,不参与计费

模型别名与权重仓库名解耦是有意的:换一次量化版本不用去改四个客户端的配置。

vLLM 参数逐条

版本 0.1.dev20073+g8e685d198,NVFP4 量化权重。启动命令去掉路径与无关环境变量后是这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
vllm serve /models/candidate \
--served-model-name qwen3.8-flash-next \
--max-model-len 262144 \
--max-num-seqs 8 \
--gpu-memory-utilization 0.80 \
--enable-prefix-caching \
--enable-chunked-prefill \
--max-num-batched-tokens 8192 \
--kv-cache-dtype bfloat16 \
--mamba-ssm-cache-dtype float32 \
--limit-mm-per-prompt '{"image":64,"video":1}' \
--tool-call-parser qwen3_xml \
--reasoning-parser qwen3 \
--speculative-config '{"method":"mtp","num_speculative_tokens":2}' \
--compilation-config '{"cudagraph_mode":"PIECEWISE","splitting_ops":[...]}'

--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,真正能用的空间是另一回事。三层要分清:

  1. 引擎窗口——262144,由 --max-model-len 决定的硬上限。
  2. 有效聊天空间——要减掉固定开销。实测固定前缀 28.5K token:system prompt 8.6K、工具定义 17.5K、skills 2.4K。
  3. 压缩触发点——网关侧阈值 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
2
3
none / minimal / low       →  low
medium → medium
high / xhigh / max / ultra → xhigh

映射的代价是”界面显示八档、实际三档”,这是等价性的真实损失,得承认。它比另一种做法好:白名单外一律 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)。 已定位,修复清单在仓库里,决定暂不执行。

如果只抄三条

  1. 先测容量再写宣传。 从引擎自己的调度日志里统计真实并发吞吐,别把 max-num-seqs 当 SLA。
  2. 超时报错先查客户端。 那一天 104 次”超时”里绝大部分是本地排队超时直接拒绝,请求根本没出门。
  3. 思考档位一定显式映射,并承认映射后的等价性损失。 透传换来的是 400,映射换来的是”界面显示八档、实际三档”——至少后者是可控的。

本文中的主机地址、模型权重来源与上游供应商名称已做脱敏处理,具体环境不具指代。


文章作者: 李广明
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 李广明 !
评论
  目录