尧图网页设计 
1. 三台 DGX Spark 跑 DeepSeek V4 Flash NVFP4 到底难在哪如果你手里正好有三台 DGX Spark想把 DeepSeek V4 Flash 的 NVFP4 量化权重跑成一个对外可用的 OpenAI-compatible API那这篇就是按我实际踩过的路径写的。核心检索词先摆出来三台 DGX Spark 部署 DeepSeek V4 Flash NVFP4本质是把一个 43 层的 MoE 模型按 Pipeline Parallel 切成 14/14/15 三段分别放到三台 GB10 机器上通过 ConnectX-7 组成的 RoCE Ring 做 NCCL 通信最后只在 rank 0 暴露一个 8000 端口的推理服务。它适合第一次接触多机大模型、Docker、RoCE 或 NCCL 的管理员也适合已经单机跑过 SGLang、想往多机扩展的人。难点不在模型本身而在三件事第一三台机器必须被当成一个整体任意一台退出整个实例都不完整启停必须协调第二NVFP4 在 SM121 上有特定的 kernel 路径参数写错会出现 HTTP 200 但返回空内容第三NCCL 的 bootstrap 走管理网、模型数据走 RoCE这两条网络职责不能混。我见过太多人把 dist-init 地址写成 RoCE 地址结果 TCPStore 直接 No route to host。先把最终拓扑说清楚后面所有配置都围绕它展开客户端 / Agent │ HTTP :8000 OpenAI-compatible API ▼ spark-6 / 192.168.1.128 / rank 0 / PP stage 0 / 14 层 │ ConnectX-7 RoCE RingNCCL 模型通信 ▼ spark-7 / 192.168.1.228 / rank 1 / PP stage 1 / 14 层 ▼ spark-8 / 192.168.1.168 / rank 2 / PP stage 2 / 15 层控制面、SSH、TCPStore、Gloo、NCCL bootstrap 全部走管理网enP7s7 / 192.168.1.0/24模型数据面走三条 ConnectX-7 200 Gb/s 直连组成的 RoCE Ring。节点映射固定不要交换 rank节点管理 IPRankPipeline stage层数对外职责spark-6192.168.1.1280014rendezvous、API :8000spark-7192.168.1.2281114workerspark-8192.168.1.1682215worker、输出层这是一个 TP1、PP3、nnodes3 的分布式实例。模型 43 层分成 14、14、15任意一台退出整个实例都不完整。新手最容易犯的错是只重启一个 rank看起来容器健康实际整个 PP 集群已经不可用。术语表也顺手给一下不然后面看参数会懵术语含义本方案取值Rank分布式任务中节点唯一编号spark-6/7/8 分别为 0/1/2TPTensor Parallel同层拆到多 GPU1不跨节点拆层PPPipeline Parallel不同层放不同节点3每台一个 stageNCCLNVIDIA GPU 集合通信库负责三节点模型通信RoCE以太网上承载 RDMA走 ConnectX-7 RingGloo/TCPStore进程发现与控制面通信走管理网 enP7s7NVFP4NVIDIA 4-bit 浮点量化格式MoE 专家权重主要格式SM121DGX Spark GB10 的 compute capability(12, 1)已验证的安全运行边界是这样的生产配置不是模型理论上限而是这组三机实测后的安全边界TP1 PP3 PP_LAYER_PARTITION14,14,15 CONTEXT_LENGTH12288 # Server 硬窗口 # 生产输入 cap8192必须由客户端或网关执行 MEM_FRACTION_STATIC0.57 MAX_TOTAL_TOKENS1579520 MAX_RUNNING_REQUESTS8 CUDA_GRAPH_MAX_BS_DECODE4 CHUNKED_PREFILL_SIZE4096 MAX_PREFILL_TOKENS409612288 不是推荐输入长度它还要容纳输出、Chat template、reasoning 和 tool schema。生产输入最多 8192 tokens长请求建议并发 1。12K 重复冷请求和 16K 请求已经触发过系统内存压力门槛所以不要对外宣传或开放 12K、16K、32K 这些输入能力。2. TaoToken 统一 Key 接入为什么多机部署也需要它三台 DGX Spark 把模型跑起来之后下一个问题马上来了你的 Agent、Codex、OpenClaw、各种客户端怎么统一调用如果每个客户端都直接写http://192.168.1.128:8000/v1加一个本地 key短期能用但一旦你要同时接多个模型、多个环境、多个团队成员key 管理就会变成灾难。这时候用 TaoToken 做统一 Key/API 通道就非常合适。TaoToken 在这里扮演的角色是统一入口和凭据管理层。你的三台 DGX Spark 集群对外只暴露一个受保护的 API而所有客户端通过 TaoToken 的统一 Key 去访问不用在每台客户端上散落不同的服务凭据。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先说清楚它解决什么问题。多机部署的痛点不只是推理本身还有第一凭据分散。三台机器共用同一个SGLANG_API_KEY这个 key 是服务凭据不是多租户权限系统。如果你把它直接发给每个客户端等于把后端完全暴露。TaoToken 的统一 Key 让你在网关层做一次收敛客户端拿到的是 TaoToken 的 key而不是后端服务凭据。第二模型切换。今天跑 DeepSeek V4 Flash明天可能想对比别的模型。如果每个客户端都硬编码 base_url 和 model切换成本很高。通过 TaoToken 的统一通道客户端配置只需要改 model 字段。第三连通性自检。多机集群最容易出的问题是看起来起来了但实际不通。TaoToken 的模型对话入口可以帮你快速验证通道是否打通而不用每次都写 curl。具体操作上你需要先拿到 TaoToken 的 API Key。进入控制台创建 key然后就可以在客户端里配置。对于长期编码和 Agent 场景建议用 Coding Plan它更适合持续性的编码任务如果只是验证模型连通性用模型对话入口就够了。这里要强调一个安全边界TaoToken 是统一接入层不是让你把后端 8000 端口直接暴露到公网。正确的做法是后端 API 仍然只在可信管理网内TaoToken 作为受控的统一入口。多用户或跨网访问时在 API 前增加独立 TLS 反向代理或网关并实现每客户端身份认证、最大输入 8192 token、默认并发 4、后端总在途不超过 8、长上下文请求并发 1、请求速率和排队上限、超时取消和审计日志脱敏。如果你要把 Codex 接进来Codex 需要 Responses API所以必须用带兼容补丁的派生镜像。配置上关键项是model deepseek-v4-flash model_provider spark_sglang model_context_window 12288 model_auto_compact_token_limit 8192 [model_providers.spark_sglang] base_url http://192.168.1.128:8000/v1 env_key SGLANG_API_KEY wire_api responses先在启动 Codex 的受控 shell 或 credential manager 中提供SGLANG_API_KEY不要把值写进 TOML。如果你通过 TaoToken 统一通道接入base_url 就换成 TaoToken 的 API 地址key 换成 TaoToken 的 keymodel 仍然是deepseek-v4-flash。这样客户端侧就不需要知道后端三台机器的具体 IP。对于 OpenClaw当前经过验证的 provider 配置是api: openai-completions contextWindow: 12288 maxTokens: 4096 apiKey: ${SGLANG_API_KEY}同样如果你走 TaoToken 统一通道把 apiKey 换成 TaoToken 的 keybase_url 指向 TaoToken API 即可。复制模板不会也不应该自动启动 OpenClaw当前三台 OpenClaw service 都保持 disabled/inactive只有明确要求在指定主机运行时才另行启用。这里有个硬规则必须记住实际序列化后的 prompt tokens max_output_tokens 12288其中 prompt 已包含 chat template、system、tool schema、工具结果和历史消息。网关应该使用服务 tokenizer 计数后再准入并额外保留模板/协议余量。如果输入接近 8192就必须相应降低最大输出。TaoToken 的接入文档里有完整的参数说明和示例建议对照着配置。如果你在配置过程中遇到 401 或连接问题先检查 key 是否正确、base_url 是否指向了正确的端点。排障时优先看 API Keys 页面确认 key 状态再看接入文档核对参数格式。3. 可复制的 Docker 与 NCCL 配置从镜像到 .env这一节是全文最核心的可复制部分。先说镜像固定本方案冻结 NVIDIA SGLang 26.07 的整套兼容栈SGLang 0.5.14、FlashInfer 0.6.14、Torch 2.13/CUDA 13.3、NCCL 2.30.7。不要把更新误当成优化单独升级其中一个组件会失去已经验证的 ABI 和 kernel 组合。对象固定标识官方基础镜像 RepoDigestnvcr.io/nvidia/sglangsha256:4e2c6f610dca57dd26af9c3045d1935a11d185903cec060d11cec061de2b62f0官方基础镜像 config IDsha256:4f5f4cade001a28b44f3e6289f49eb6e2e3e941e284fa95ee67a53c3d17745a1三机当前派生镜像 config IDsha256:43e76a532b12365232231d0bff2f63b79744f0042a016f04b8d5f7c27bf20386平台linux/arm64兼容补丁 SHA-256ceb5ac6536e25e4ce786dd99bbe09d4c2890cf645b74794425c952a1b976c3dc派生镜像只给 SGLang Responses 完成事件补充cache_write_tokens: 0以满足镜像中 openai-python 2.48.0 的 schema。它不升级或替换任何 CUDA/Python 依赖。Codex 使用 Responses API所以生产接入 Codex 时必须用这个派生镜像。SM121 必须保留的设置这几项写错会直接导致空输出--moe-runner-backend flashinfer_cutlass --fp4-gemm-backend flashinfer_cutlass --disable-flashinfer-autotune SGLANG_OPT_FLASHMLA_SPARSE_PREFILL0 SGLANG_SM120_TRITON_FLASHMLA1 SGLANG_FP8_IGNORED_LAYERSlm_headlm_head在 checkpoint 中是 BF16 且没有 FP8 scale。如果强行套用 FP8API 可能返回 HTTP 200 却生成空内容或 BOS。CUTLASS 两项则防止 GB10/SM121 误入不适用的 TRT-LLM routed kernel。Docker 最小权限的 Compose 关键片段services: sglang: image: sha256:43e76a532b12365232231d0bff2f63b79744f0042a016f04b8d5f7c27bf20386 network_mode: host ipc: host gpus: all devices: - /dev/infiniband ulimits: memlock: -1 stack: 67108864 volumes: - /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4:/model:ro - /home/nvidia/workspaces/cache/deepseek-v4/${HOSTNAME}:/cache:rw restart: no logging: driver: json-file options: max-size: 100m max-file: 3明确不使用--privileged、seccompunconfined、Docker socket 挂载、模型目录读写挂载、宿主 CUDA/NCCL 注入、Ray、SGLang Gateway、Docker overlay network。restart: no是有意设计单个 rank 自动重启会制造一个容器看似健康、整个 PP 集群不可用的假象。每台的.env文件公共参数必须一致COMPOSE_PROJECT_NAMEdeepseek-v4-pp3 MGMT_IFNAMEenP7s7 SERVER_PORT8000 DIST_INIT_ADDR192.168.1.128:25001 SGLANG_IMAGEsha256:43e76a532b12365232231d0bff2f63b79744f0042a016f04b8d5f7c27bf20386 SGLANG_API_KEYREPLACE_WITH_A_SECRET_VALUE SERVED_MODEL_NAMEdeepseek-v4-flash MODEL_DIR/home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 PP_LAYER_PARTITION14,14,15 MEM_FRACTION_STATIC0.57 MAX_TOTAL_TOKENS1579520 CONTEXT_LENGTH12288 CHUNKED_PREFILL_SIZE4096 MAX_PREFILL_TOKENS4096 MAX_RUNNING_REQUESTS8 CUDA_GRAPH_MAX_BS_DECODE4 WATCHDOG_TIMEOUT1800 NCCL_DEBUGINFO REQUIRE_SYNC_CLUSTER1 MIN_MEM_AVAILABLE_GIB100节点专属字段节点EXPECTED_HOSTNAMENODE_RANKMGMT_IP / SERVER_HOSTCACHE_DIRspark-6spark-60192.168.1.128.../cache/deepseek-v4/spark-6spark-7spark-71192.168.1.228.../cache/deepseek-v4/spark-7spark-8spark-82192.168.1.168.../cache/deepseek-v4/spark-8创建.env时权限必须是 0600owner 必须是可信的 root 或 nvidiacd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy umask 077 node_envnodes/$(hostname).env test ! -e ${node_env} || { echo REFUSE: ${node_env} already exists; exit 1; } install -m 600 ${node_env}.example ${node_env} mkdir -p /home/nvidia/workspaces/cache/deepseek-v4/$(hostname)API key 至少 32 字符建议用openssl rand -hex 32生成一次并存入密码管理器。不要把真实 key 写在 Shell 历史、聊天、Git 或文档中。NCCL 环境变量清单首轮不要自行设置NCCL_IB_HCA、NCCL_IB_GID_INDEX、NCCL_CROSS_NIC、NCCL_IB_TC、NCCL_IB_SL或 GDR 参数。DGX Spark 不支持 GPUDirect RDMA跨节点 RoCE 使用 host staging 是平台预期行为。Ring helper 会使用NCCL_IB_SUBNET_AWARE_ROUTING1 NCCL_NET_PLUGINnone拉取固定基础镜像并验证docker pull nvcr.io/nvidia/sglangsha256:4e2c6f610dca57dd26af9c3045d1935a11d185903cec060d11cec061de2b62f0 docker image inspect \ nvcr.io/nvidia/sglangsha256:4e2c6f610dca57dd26af9c3045d1935a11d185903cec060d11cec061de2b62f0 \ --format id{{.Id}} platform{{.Os}}/{{.Architecture}}期望基础 config ID 是sha256:4f5f4cade...45a1平台为linux/arm64。不要只使用会漂移的26.07-py3tag。4. 验证请求与成功结果从 NCCL 到 API 逐条确认配置写完不代表能用这一节给你逐条验证命令。顺序是先主机 NCCL再容器 NCCL最后 API 语义。主机 NCCL helper 只用于网络验收不挂入 SGLang 容器。为保证复现固定到审阅过的 playbook commitset -Eeuo pipefail mkdir -p /home/nvidia/workspaces/nccl-validation cd /home/nvidia/workspaces/nccl-validation PLAYBOOK_COMMIT1fb66f059ee427c5a3678b3117ef73aab042b458 curl -fsSL https://raw.githubusercontent.com/NVIDIA/dgx-spark-playbooks/${PLAYBOOK_COMMIT}/nvidia/nccl/assets/setup.sh -o setup.sh curl -fsSL https://raw.githubusercontent.com/NVIDIA/dgx-spark-playbooks/${PLAYBOOK_COMMIT}/nvidia/nccl/assets/launch.sh -o launch.sh printf %s %s\n \ 32665e12b12c9a3eb3f9ac043993f442df9215e47b42d0b93f511e113c1b5cc7 setup.sh \ a6c2e69b234f3455283f354b9f21b13cd2665d69a563e69aa2f51f49a31c00f3 launch.sh \ | sha256sum -c - eval $(ssh-agent -s) trap ssh-agent -k /dev/null 21 || true EXIT ssh-add /home/nvidia/.ssh/id_ed25519_shared bash setup.sh 192.168.1.228 192.168.1.168 bash launch.sh --topology ring \ 192.168.1.128 \ 192.168.1.228 \ 192.168.1.168 ssh-agent -k trap - EXIT通过条件三 rank 完成、不 hang、数值正确日志没有unknown event type (18)、mlx5 fatal/reset、AER、link reset。模型完整性检查三台分别执行cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 du -sh . find . -maxdepth 1 -type f -name model-*.safetensors | wc -l test -r model.safetensors.index.json再让 index 自己检查被引用的分片import json from pathlib import Path root Path(.) with (root / model.safetensors.index.json).open(encodingutf-8) as f: index json.load(f) files sorted(set(index[weight_map].values())) missing [name for name in files if not (root / name).is_file()] empty [name for name in files if (root / name).is_file() and (root / name).stat().st_size 0] print(fshards{len(files)} missing{len(missing)} empty{len(empty)}) raise SystemExit(1 if len(files) ! 46 or missing or empty else 0)正确结果为 46 个 shard、无 missing、无空文件当前总字节为 168281985176。三层预检三台分别执行cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy ./scripts/preflight.sh nodes/$(hostname).env ./scripts/container-smoke.sh nodes/$(hostname).env三机一致性门禁只在 spark-6 执行./scripts/cluster-preflight.sh期望最后输出PASS: ranks are unique and all common image, secret-hash, runtime, and model-index fields match最终容器 NCCL Gate模型启动前从 spark-6 执行./scripts/cluster-down.sh nvidia-smi --query-compute-appspid,process_name,used_memory --formatcsv ./scripts/cluster-nccl-smoke.sh通过条件CLUSTER_NCCL_SMOKE PASS ranks0,1,2 transportIB ...每个日志必须包含 NET/IB HCA 选择不能出现 Socket 数据面、unknown event type、NCCL ERROR、Traceback 或数据错误。NCCL 2.30.7 在本平台每个 HCA 可能有一条固定的ibv_query_port_speed ... errno 93能力查询 warning验收器只允许这一条精确 warning。启动三节点模型cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 sudo deploy/systemd/install.sh --now以后开机由deepseek-v4-pp3.service等待三台节点和 RoCE 就绪后整组启动。手工维护时才执行bash deploy/scripts/cluster-up.sh等待真正就绪首次加载约 168 GB 权重需要数分钟cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy ./scripts/wait-ready.sh nodes/spark-6.env成功会输出Rank 0 API is ready: http://192.168.1.128:8000一键 API 验收./scripts/verify-api.sh nodes/spark-6.env它会检查/health和执行真实 forward 的/health_generate、/v1/models中的deepseek-v4-flash、确定性数值语义、Chat Completions SSE 流式结束标记、DeepSeek V4 reasoning_content、function tool-call 解析。最后必须看到PASS: all DeepSeek V4 API verification gatesAgent 协议验收cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 source deploy/scripts/lib.sh load_env nodes/spark-6.env python3 deploy/integrations/verify_agent_endpoints.py期望PASS chat-completions PASS responses-sse-completed PASS anthropic-messages PASS all-agent-endpoints如果你通过 TaoToken 统一通道接入验证方式更简单用模型对话入口发一条测试请求确认能正常返回内容。这一步能快速判断是后端问题还是客户端配置问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。多机部署最容易卡在几个固定位置我把现象、原因、处理列成表你对照着查。现象最可能原因正确处理preflight 报多个 169.254/16旧重叠 IPv4LL 路由仍在回到 Cluster Assistant/Netplan Ring不用手写 HCA 绕过TCPStore No route to host管理网、端口或 dist-init 错误确认 enP7s7 和 192.168.1.128:25001NCCL 只有 SocketRoCE 没有被最终容器发现停止部署查 Sync 计划、HCA、/dev/infiniband 和日志unknown event type (18)旧 NCCL/旧镜像或 RDMA 异常核对派生 image ID、NCCL 2.30.7、mlx5 日志no kernel image / SM121 unsupported镜像依赖被覆盖核对固定镜像移除 pip overlaytrtllm_batched_gemm_runner.cu:305SM121 误入 TRT-LLM routed backend恢复两个 flashinfer_cutlass 参数并三机协调重启API 200 但内容为空/BOSBF16 lm_head 被错误量化恢复 SGLANG_FP8_IGNORED_LAYERSlm_head重跑语义 Gate提高 CUDA Graph BS 后启动失败新 batch graph/kernel 路径未通过验收回滚 CUDA_GRAPH_MAX_BS_DECODE4启动时 OOM、持续 swap 或 PSIcontext/mem/并发过高停三 rank恢复最终参数rank 0 /health 不就绪某 worker 卡住或退出同时查看三机 status 和脱敏日志工具调用未解析parser、客户端 schema 或模型配置错误保持 deepseekv4 tool parser运行 verify-api.shCodex 收不到 response.completed使用了未打补丁的基础镜像核对派生 image ID运行 Agent 协议探针AER、Xid、HCA reset、link flap供电、线缆、固件或硬件风险立即停止压测保留诊断检查电源/线缆现在说几个和 TaoToken 接入相关的报错。401 Unauthorized这是最常见的。如果你通过 TaoToken 统一通道访问先检查 TaoToken 的 key 是否正确、是否过期。如果直连后端检查SGLANG_API_KEY是否在三台.env中一致。注意.env里SGLANG_API_KEYREPLACE_WITH_A_SECRET_VALUE这个占位符必须替换成真实值很多人忘了改。另外key 不要带引号dotenv 每行采用KEYvalue单行格式。local proxy failed这个通常出现在客户端配置了代理但代理不可达时。检查你的客户端是否设置了HTTP_PROXY或HTTPS_PROXY环境变量如果后端在管理网内应该把192.168.1.0/24加入NO_PROXY。如果你通过 TaoToken 访问确认网络能正常到达 TaoToken 的 API 端点。reading choices 相关报错这通常是响应格式解析问题。如果你用的是派生镜像之前的版本Responses API 的完成事件缺少cache_write_tokens: 0openai-python 2.48.0 会解析失败。核对派生 image ID 是否为sha256:43e76a...20386运行 Agent 协议探针确认PASS responses-sse-completed。OAuth 相关报错如果你在 Codex 里看到 OAuth 错误通常是因为 Codex 尝试用 OAuth 流程但你的后端是本地 API key 模式。确认 Codex 配置里env_key SGLANG_API_KEY并且启动 Codex 的 shell 里已经 export 了这个变量。不要把 key 写进 TOML 文件。遇到问题先保存诊断cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy ./scripts/node-status.sh nodes/$(hostname).env ./scripts/node-logs.sh nodes/$(hostname).env --no-follow ./scripts/collect-diagnostics.sh nodes/$(hostname).env不要以增大 timeout、关闭错误检查、强制 Socket、禁用 RDMA 或提高 swap 的方式把故障隐藏为成功。还有一个容易忽略的点如果你在配置 TaoToken 时遇到连通性问题先确认后端 API 本身是通的。用curl直接打后端curl -s http://192.168.1.128:8000/health curl -s http://192.168.1.128:8000/v1/models \ -H Authorization: Bearer ${SGLANG_API_KEY}如果后端通但 TaoToken 不通问题在网关层如果后端本身不通先回到第 4 节排查。6. 把三台 DGX Spark 接进 TaoToken 统一通道最后这一节说清楚接入路径。你的三台 DGX Spark 集群跑起来之后对外只暴露 rank 0 的 8000 端口。这个端口只应该在可信管理网内。TaoToken 作为统一接入层帮你把凭据管理和模型切换收敛到一个地方。具体操作步骤第一步确认后端 API 可用。在 spark-6 上执行./scripts/verify-api.sh nodes/spark-6.env看到PASS: all DeepSeek V4 API verification gates才算后端就绪。第二步拿到 TaoToken 的 API Key。进入控制台创建建议为不同用途创建不同的 key方便后续审计和轮换。第三步配置客户端。以 Codex 为例把 base_url 指向 TaoToken 的 API 端点key 用 TaoToken 的 keymodel 保持deepseek-v4-flash。这样客户端不需要知道后端三台机器的具体 IP也不需要持有后端服务凭据。第四步验证连通性。用模型对话入口发一条测试请求确认返回正常。如果失败先检查 key 和 base_url再检查后端是否可达。对于长期编码和 Agent 场景建议用 Coding Plan它更适合持续性的编码任务有更稳定的配额和更长的会话支持。如果你只是偶尔验证模型用模型对话就够了。接入文档里有完整的参数说明、错误码解释和示例代码建议对照着配置。API Keys 页面可以管理你的 key包括创建、查看状态和轮换。这里再强调一次安全边界TaoToken 是统一接入层不是让你把后端 8000 端口直接暴露到公网。正确的架构是后端 API 在可信管理网内TaoToken 作为受控的统一入口。多用户或跨网访问时在 API 前增加独立 TLS 反向代理或网关并实现每客户端身份认证、最大输入 8192 token、默认并发 4、后端总在途不超过 8、长上下文请求并发 1、请求速率和排队上限、超时取消和审计日志脱敏。生产限额必须保持输入 cap 8192 tokens交互默认并发 4后端最大在途 8长上下文并发 1。256→128 合成形状建议稳态到达率 0.10 req/s同一形状 0.20 req/s 仅允许短暂排队0.30 req/s 是 SLA WARN 不作为交互默认。其他真实工作负载必须重新压测 arrival 曲线。如果你要把这套部署交给团队使用最短验收清单是这样的三机 hostname、管理 IP、rank 一一对应key-based SSH 无交互通过三机模型路径相同index 引用 46 个 shard六子网 Ring 无重叠 IPv4LL四个逻辑 HCA/node Up物理链路 200 Gb/s三机拥有相同派生 image ID三份.env权限 0600公共运行参数和秘密匹配单机 preflight、container smoke、cluster preflight 全部通过cluster-nccl-smoke.sh 三 rank 为 NET/IB 且数据正确cluster-up.sh 成功wait-ready.sh 返回 Readyverify-api.sh 和 verify_agent_endpoints.py 全部 PASSGateway/客户端限制生产输入 8192、默认并发 4、最大在途 8。完成本教程不代表可以跳过变更管理。任何 OTA、网络、镜像、模型、context、内存比例、并发或 CUDA Graph 变更都会使相关历史 PASS 失效必须按对应 Gate 重新验证。 三台 DGX Spark 部署 DeepSeek V4 Flash NVFP4：从零到可用教程（TaoToken 统一 Key 接入篇）
1. 三台 DGX Spark 跑 DeepSeek V4 Flash NVFP4 到底难在哪如果你手里正好有三台 DGX Spark想把 DeepSeek V4 Flash 的 NVFP4 量化权重跑成一个对外可用的 OpenAI-compatible API那这篇就是按我实际踩过的路径写的。核心检索词先摆出来三台 DGX Spark 部署 DeepSeek V4 Flash NVFP4本质是把一个 43 层的 MoE 模型按 Pipeline Parallel 切成 14/14/15 三段分别放到三台 GB10 机器上通过 ConnectX-7 组成的 RoCE Ring 做 NCCL 通信最后只在 rank 0 暴露一个 8000 端口的推理服务。它适合第一次接触多机大模型、Docker、RoCE 或 NCCL 的管理员也适合已经单机跑过 SGLang、想往多机扩展的人。难点不在模型本身而在三件事第一三台机器必须被当成一个整体任意一台退出整个实例都不完整启停必须协调第二NVFP4 在 SM121 上有特定的 kernel 路径参数写错会出现 HTTP 200 但返回空内容第三NCCL 的 bootstrap 走管理网、模型数据走 RoCE这两条网络职责不能混。我见过太多人把 dist-init 地址写成 RoCE 地址结果 TCPStore 直接 No route to host。先把最终拓扑说清楚后面所有配置都围绕它展开客户端 / Agent │ HTTP :8000 OpenAI-compatible API ▼ spark-6 / 192.168.1.128 / rank 0 / PP stage 0 / 14 层 │ ConnectX-7 RoCE RingNCCL 模型通信 ▼ spark-7 / 192.168.1.228 / rank 1 / PP stage 1 / 14 层 ▼ spark-8 / 192.168.1.168 / rank 2 / PP stage 2 / 15 层控制面、SSH、TCPStore、Gloo、NCCL bootstrap 全部走管理网enP7s7 / 192.168.1.0/24模型数据面走三条 ConnectX-7 200 Gb/s 直连组成的 RoCE Ring。节点映射固定不要交换 rank节点管理 IPRankPipeline stage层数对外职责spark-6192.168.1.1280014rendezvous、API :8000spark-7192.168.1.2281114workerspark-8192.168.1.1682215worker、输出层这是一个 TP1、PP3、nnodes3 的分布式实例。模型 43 层分成 14、14、15任意一台退出整个实例都不完整。新手最容易犯的错是只重启一个 rank看起来容器健康实际整个 PP 集群已经不可用。术语表也顺手给一下不然后面看参数会懵术语含义本方案取值Rank分布式任务中节点唯一编号spark-6/7/8 分别为 0/1/2TPTensor Parallel同层拆到多 GPU1不跨节点拆层PPPipeline Parallel不同层放不同节点3每台一个 stageNCCLNVIDIA GPU 集合通信库负责三节点模型通信RoCE以太网上承载 RDMA走 ConnectX-7 RingGloo/TCPStore进程发现与控制面通信走管理网 enP7s7NVFP4NVIDIA 4-bit 浮点量化格式MoE 专家权重主要格式SM121DGX Spark GB10 的 compute capability(12, 1)已验证的安全运行边界是这样的生产配置不是模型理论上限而是这组三机实测后的安全边界TP1 PP3 PP_LAYER_PARTITION14,14,15 CONTEXT_LENGTH12288 # Server 硬窗口 # 生产输入 cap8192必须由客户端或网关执行 MEM_FRACTION_STATIC0.57 MAX_TOTAL_TOKENS1579520 MAX_RUNNING_REQUESTS8 CUDA_GRAPH_MAX_BS_DECODE4 CHUNKED_PREFILL_SIZE4096 MAX_PREFILL_TOKENS409612288 不是推荐输入长度它还要容纳输出、Chat template、reasoning 和 tool schema。生产输入最多 8192 tokens长请求建议并发 1。12K 重复冷请求和 16K 请求已经触发过系统内存压力门槛所以不要对外宣传或开放 12K、16K、32K 这些输入能力。2. TaoToken 统一 Key 接入为什么多机部署也需要它三台 DGX Spark 把模型跑起来之后下一个问题马上来了你的 Agent、Codex、OpenClaw、各种客户端怎么统一调用如果每个客户端都直接写http://192.168.1.128:8000/v1加一个本地 key短期能用但一旦你要同时接多个模型、多个环境、多个团队成员key 管理就会变成灾难。这时候用 TaoToken 做统一 Key/API 通道就非常合适。TaoToken 在这里扮演的角色是统一入口和凭据管理层。你的三台 DGX Spark 集群对外只暴露一个受保护的 API而所有客户端通过 TaoToken 的统一 Key 去访问不用在每台客户端上散落不同的服务凭据。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先说清楚它解决什么问题。多机部署的痛点不只是推理本身还有第一凭据分散。三台机器共用同一个SGLANG_API_KEY这个 key 是服务凭据不是多租户权限系统。如果你把它直接发给每个客户端等于把后端完全暴露。TaoToken 的统一 Key 让你在网关层做一次收敛客户端拿到的是 TaoToken 的 key而不是后端服务凭据。第二模型切换。今天跑 DeepSeek V4 Flash明天可能想对比别的模型。如果每个客户端都硬编码 base_url 和 model切换成本很高。通过 TaoToken 的统一通道客户端配置只需要改 model 字段。第三连通性自检。多机集群最容易出的问题是看起来起来了但实际不通。TaoToken 的模型对话入口可以帮你快速验证通道是否打通而不用每次都写 curl。具体操作上你需要先拿到 TaoToken 的 API Key。进入控制台创建 key然后就可以在客户端里配置。对于长期编码和 Agent 场景建议用 Coding Plan它更适合持续性的编码任务如果只是验证模型连通性用模型对话入口就够了。这里要强调一个安全边界TaoToken 是统一接入层不是让你把后端 8000 端口直接暴露到公网。正确的做法是后端 API 仍然只在可信管理网内TaoToken 作为受控的统一入口。多用户或跨网访问时在 API 前增加独立 TLS 反向代理或网关并实现每客户端身份认证、最大输入 8192 token、默认并发 4、后端总在途不超过 8、长上下文请求并发 1、请求速率和排队上限、超时取消和审计日志脱敏。如果你要把 Codex 接进来Codex 需要 Responses API所以必须用带兼容补丁的派生镜像。配置上关键项是model deepseek-v4-flash model_provider spark_sglang model_context_window 12288 model_auto_compact_token_limit 8192 [model_providers.spark_sglang] base_url http://192.168.1.128:8000/v1 env_key SGLANG_API_KEY wire_api responses先在启动 Codex 的受控 shell 或 credential manager 中提供SGLANG_API_KEY不要把值写进 TOML。如果你通过 TaoToken 统一通道接入base_url 就换成 TaoToken 的 API 地址key 换成 TaoToken 的 keymodel 仍然是deepseek-v4-flash。这样客户端侧就不需要知道后端三台机器的具体 IP。对于 OpenClaw当前经过验证的 provider 配置是api: openai-completions contextWindow: 12288 maxTokens: 4096 apiKey: ${SGLANG_API_KEY}同样如果你走 TaoToken 统一通道把 apiKey 换成 TaoToken 的 keybase_url 指向 TaoToken API 即可。复制模板不会也不应该自动启动 OpenClaw当前三台 OpenClaw service 都保持 disabled/inactive只有明确要求在指定主机运行时才另行启用。这里有个硬规则必须记住实际序列化后的 prompt tokens max_output_tokens 12288其中 prompt 已包含 chat template、system、tool schema、工具结果和历史消息。网关应该使用服务 tokenizer 计数后再准入并额外保留模板/协议余量。如果输入接近 8192就必须相应降低最大输出。TaoToken 的接入文档里有完整的参数说明和示例建议对照着配置。如果你在配置过程中遇到 401 或连接问题先检查 key 是否正确、base_url 是否指向了正确的端点。排障时优先看 API Keys 页面确认 key 状态再看接入文档核对参数格式。3. 可复制的 Docker 与 NCCL 配置从镜像到 .env这一节是全文最核心的可复制部分。先说镜像固定本方案冻结 NVIDIA SGLang 26.07 的整套兼容栈SGLang 0.5.14、FlashInfer 0.6.14、Torch 2.13/CUDA 13.3、NCCL 2.30.7。不要把更新误当成优化单独升级其中一个组件会失去已经验证的 ABI 和 kernel 组合。对象固定标识官方基础镜像 RepoDigestnvcr.io/nvidia/sglangsha256:4e2c6f610dca57dd26af9c3045d1935a11d185903cec060d11cec061de2b62f0官方基础镜像 config IDsha256:4f5f4cade001a28b44f3e6289f49eb6e2e3e941e284fa95ee67a53c3d17745a1三机当前派生镜像 config IDsha256:43e76a532b12365232231d0bff2f63b79744f0042a016f04b8d5f7c27bf20386平台linux/arm64兼容补丁 SHA-256ceb5ac6536e25e4ce786dd99bbe09d4c2890cf645b74794425c952a1b976c3dc派生镜像只给 SGLang Responses 完成事件补充cache_write_tokens: 0以满足镜像中 openai-python 2.48.0 的 schema。它不升级或替换任何 CUDA/Python 依赖。Codex 使用 Responses API所以生产接入 Codex 时必须用这个派生镜像。SM121 必须保留的设置这几项写错会直接导致空输出--moe-runner-backend flashinfer_cutlass --fp4-gemm-backend flashinfer_cutlass --disable-flashinfer-autotune SGLANG_OPT_FLASHMLA_SPARSE_PREFILL0 SGLANG_SM120_TRITON_FLASHMLA1 SGLANG_FP8_IGNORED_LAYERSlm_headlm_head在 checkpoint 中是 BF16 且没有 FP8 scale。如果强行套用 FP8API 可能返回 HTTP 200 却生成空内容或 BOS。CUTLASS 两项则防止 GB10/SM121 误入不适用的 TRT-LLM routed kernel。Docker 最小权限的 Compose 关键片段services: sglang: image: sha256:43e76a532b12365232231d0bff2f63b79744f0042a016f04b8d5f7c27bf20386 network_mode: host ipc: host gpus: all devices: - /dev/infiniband ulimits: memlock: -1 stack: 67108864 volumes: - /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4:/model:ro - /home/nvidia/workspaces/cache/deepseek-v4/${HOSTNAME}:/cache:rw restart: no logging: driver: json-file options: max-size: 100m max-file: 3明确不使用--privileged、seccompunconfined、Docker socket 挂载、模型目录读写挂载、宿主 CUDA/NCCL 注入、Ray、SGLang Gateway、Docker overlay network。restart: no是有意设计单个 rank 自动重启会制造一个容器看似健康、整个 PP 集群不可用的假象。每台的.env文件公共参数必须一致COMPOSE_PROJECT_NAMEdeepseek-v4-pp3 MGMT_IFNAMEenP7s7 SERVER_PORT8000 DIST_INIT_ADDR192.168.1.128:25001 SGLANG_IMAGEsha256:43e76a532b12365232231d0bff2f63b79744f0042a016f04b8d5f7c27bf20386 SGLANG_API_KEYREPLACE_WITH_A_SECRET_VALUE SERVED_MODEL_NAMEdeepseek-v4-flash MODEL_DIR/home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 PP_LAYER_PARTITION14,14,15 MEM_FRACTION_STATIC0.57 MAX_TOTAL_TOKENS1579520 CONTEXT_LENGTH12288 CHUNKED_PREFILL_SIZE4096 MAX_PREFILL_TOKENS4096 MAX_RUNNING_REQUESTS8 CUDA_GRAPH_MAX_BS_DECODE4 WATCHDOG_TIMEOUT1800 NCCL_DEBUGINFO REQUIRE_SYNC_CLUSTER1 MIN_MEM_AVAILABLE_GIB100节点专属字段节点EXPECTED_HOSTNAMENODE_RANKMGMT_IP / SERVER_HOSTCACHE_DIRspark-6spark-60192.168.1.128.../cache/deepseek-v4/spark-6spark-7spark-71192.168.1.228.../cache/deepseek-v4/spark-7spark-8spark-82192.168.1.168.../cache/deepseek-v4/spark-8创建.env时权限必须是 0600owner 必须是可信的 root 或 nvidiacd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy umask 077 node_envnodes/$(hostname).env test ! -e ${node_env} || { echo REFUSE: ${node_env} already exists; exit 1; } install -m 600 ${node_env}.example ${node_env} mkdir -p /home/nvidia/workspaces/cache/deepseek-v4/$(hostname)API key 至少 32 字符建议用openssl rand -hex 32生成一次并存入密码管理器。不要把真实 key 写在 Shell 历史、聊天、Git 或文档中。NCCL 环境变量清单首轮不要自行设置NCCL_IB_HCA、NCCL_IB_GID_INDEX、NCCL_CROSS_NIC、NCCL_IB_TC、NCCL_IB_SL或 GDR 参数。DGX Spark 不支持 GPUDirect RDMA跨节点 RoCE 使用 host staging 是平台预期行为。Ring helper 会使用NCCL_IB_SUBNET_AWARE_ROUTING1 NCCL_NET_PLUGINnone拉取固定基础镜像并验证docker pull nvcr.io/nvidia/sglangsha256:4e2c6f610dca57dd26af9c3045d1935a11d185903cec060d11cec061de2b62f0 docker image inspect \ nvcr.io/nvidia/sglangsha256:4e2c6f610dca57dd26af9c3045d1935a11d185903cec060d11cec061de2b62f0 \ --format id{{.Id}} platform{{.Os}}/{{.Architecture}}期望基础 config ID 是sha256:4f5f4cade...45a1平台为linux/arm64。不要只使用会漂移的26.07-py3tag。4. 验证请求与成功结果从 NCCL 到 API 逐条确认配置写完不代表能用这一节给你逐条验证命令。顺序是先主机 NCCL再容器 NCCL最后 API 语义。主机 NCCL helper 只用于网络验收不挂入 SGLang 容器。为保证复现固定到审阅过的 playbook commitset -Eeuo pipefail mkdir -p /home/nvidia/workspaces/nccl-validation cd /home/nvidia/workspaces/nccl-validation PLAYBOOK_COMMIT1fb66f059ee427c5a3678b3117ef73aab042b458 curl -fsSL https://raw.githubusercontent.com/NVIDIA/dgx-spark-playbooks/${PLAYBOOK_COMMIT}/nvidia/nccl/assets/setup.sh -o setup.sh curl -fsSL https://raw.githubusercontent.com/NVIDIA/dgx-spark-playbooks/${PLAYBOOK_COMMIT}/nvidia/nccl/assets/launch.sh -o launch.sh printf %s %s\n \ 32665e12b12c9a3eb3f9ac043993f442df9215e47b42d0b93f511e113c1b5cc7 setup.sh \ a6c2e69b234f3455283f354b9f21b13cd2665d69a563e69aa2f51f49a31c00f3 launch.sh \ | sha256sum -c - eval $(ssh-agent -s) trap ssh-agent -k /dev/null 21 || true EXIT ssh-add /home/nvidia/.ssh/id_ed25519_shared bash setup.sh 192.168.1.228 192.168.1.168 bash launch.sh --topology ring \ 192.168.1.128 \ 192.168.1.228 \ 192.168.1.168 ssh-agent -k trap - EXIT通过条件三 rank 完成、不 hang、数值正确日志没有unknown event type (18)、mlx5 fatal/reset、AER、link reset。模型完整性检查三台分别执行cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 du -sh . find . -maxdepth 1 -type f -name model-*.safetensors | wc -l test -r model.safetensors.index.json再让 index 自己检查被引用的分片import json from pathlib import Path root Path(.) with (root / model.safetensors.index.json).open(encodingutf-8) as f: index json.load(f) files sorted(set(index[weight_map].values())) missing [name for name in files if not (root / name).is_file()] empty [name for name in files if (root / name).is_file() and (root / name).stat().st_size 0] print(fshards{len(files)} missing{len(missing)} empty{len(empty)}) raise SystemExit(1 if len(files) ! 46 or missing or empty else 0)正确结果为 46 个 shard、无 missing、无空文件当前总字节为 168281985176。三层预检三台分别执行cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy ./scripts/preflight.sh nodes/$(hostname).env ./scripts/container-smoke.sh nodes/$(hostname).env三机一致性门禁只在 spark-6 执行./scripts/cluster-preflight.sh期望最后输出PASS: ranks are unique and all common image, secret-hash, runtime, and model-index fields match最终容器 NCCL Gate模型启动前从 spark-6 执行./scripts/cluster-down.sh nvidia-smi --query-compute-appspid,process_name,used_memory --formatcsv ./scripts/cluster-nccl-smoke.sh通过条件CLUSTER_NCCL_SMOKE PASS ranks0,1,2 transportIB ...每个日志必须包含 NET/IB HCA 选择不能出现 Socket 数据面、unknown event type、NCCL ERROR、Traceback 或数据错误。NCCL 2.30.7 在本平台每个 HCA 可能有一条固定的ibv_query_port_speed ... errno 93能力查询 warning验收器只允许这一条精确 warning。启动三节点模型cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 sudo deploy/systemd/install.sh --now以后开机由deepseek-v4-pp3.service等待三台节点和 RoCE 就绪后整组启动。手工维护时才执行bash deploy/scripts/cluster-up.sh等待真正就绪首次加载约 168 GB 权重需要数分钟cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy ./scripts/wait-ready.sh nodes/spark-6.env成功会输出Rank 0 API is ready: http://192.168.1.128:8000一键 API 验收./scripts/verify-api.sh nodes/spark-6.env它会检查/health和执行真实 forward 的/health_generate、/v1/models中的deepseek-v4-flash、确定性数值语义、Chat Completions SSE 流式结束标记、DeepSeek V4 reasoning_content、function tool-call 解析。最后必须看到PASS: all DeepSeek V4 API verification gatesAgent 协议验收cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4 source deploy/scripts/lib.sh load_env nodes/spark-6.env python3 deploy/integrations/verify_agent_endpoints.py期望PASS chat-completions PASS responses-sse-completed PASS anthropic-messages PASS all-agent-endpoints如果你通过 TaoToken 统一通道接入验证方式更简单用模型对话入口发一条测试请求确认能正常返回内容。这一步能快速判断是后端问题还是客户端配置问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。多机部署最容易卡在几个固定位置我把现象、原因、处理列成表你对照着查。现象最可能原因正确处理preflight 报多个 169.254/16旧重叠 IPv4LL 路由仍在回到 Cluster Assistant/Netplan Ring不用手写 HCA 绕过TCPStore No route to host管理网、端口或 dist-init 错误确认 enP7s7 和 192.168.1.128:25001NCCL 只有 SocketRoCE 没有被最终容器发现停止部署查 Sync 计划、HCA、/dev/infiniband 和日志unknown event type (18)旧 NCCL/旧镜像或 RDMA 异常核对派生 image ID、NCCL 2.30.7、mlx5 日志no kernel image / SM121 unsupported镜像依赖被覆盖核对固定镜像移除 pip overlaytrtllm_batched_gemm_runner.cu:305SM121 误入 TRT-LLM routed backend恢复两个 flashinfer_cutlass 参数并三机协调重启API 200 但内容为空/BOSBF16 lm_head 被错误量化恢复 SGLANG_FP8_IGNORED_LAYERSlm_head重跑语义 Gate提高 CUDA Graph BS 后启动失败新 batch graph/kernel 路径未通过验收回滚 CUDA_GRAPH_MAX_BS_DECODE4启动时 OOM、持续 swap 或 PSIcontext/mem/并发过高停三 rank恢复最终参数rank 0 /health 不就绪某 worker 卡住或退出同时查看三机 status 和脱敏日志工具调用未解析parser、客户端 schema 或模型配置错误保持 deepseekv4 tool parser运行 verify-api.shCodex 收不到 response.completed使用了未打补丁的基础镜像核对派生 image ID运行 Agent 协议探针AER、Xid、HCA reset、link flap供电、线缆、固件或硬件风险立即停止压测保留诊断检查电源/线缆现在说几个和 TaoToken 接入相关的报错。401 Unauthorized这是最常见的。如果你通过 TaoToken 统一通道访问先检查 TaoToken 的 key 是否正确、是否过期。如果直连后端检查SGLANG_API_KEY是否在三台.env中一致。注意.env里SGLANG_API_KEYREPLACE_WITH_A_SECRET_VALUE这个占位符必须替换成真实值很多人忘了改。另外key 不要带引号dotenv 每行采用KEYvalue单行格式。local proxy failed这个通常出现在客户端配置了代理但代理不可达时。检查你的客户端是否设置了HTTP_PROXY或HTTPS_PROXY环境变量如果后端在管理网内应该把192.168.1.0/24加入NO_PROXY。如果你通过 TaoToken 访问确认网络能正常到达 TaoToken 的 API 端点。reading choices 相关报错这通常是响应格式解析问题。如果你用的是派生镜像之前的版本Responses API 的完成事件缺少cache_write_tokens: 0openai-python 2.48.0 会解析失败。核对派生 image ID 是否为sha256:43e76a...20386运行 Agent 协议探针确认PASS responses-sse-completed。OAuth 相关报错如果你在 Codex 里看到 OAuth 错误通常是因为 Codex 尝试用 OAuth 流程但你的后端是本地 API key 模式。确认 Codex 配置里env_key SGLANG_API_KEY并且启动 Codex 的 shell 里已经 export 了这个变量。不要把 key 写进 TOML 文件。遇到问题先保存诊断cd /home/nvidia/workspaces/models/DeepSeek-V4-Flash-NVFP4/deploy ./scripts/node-status.sh nodes/$(hostname).env ./scripts/node-logs.sh nodes/$(hostname).env --no-follow ./scripts/collect-diagnostics.sh nodes/$(hostname).env不要以增大 timeout、关闭错误检查、强制 Socket、禁用 RDMA 或提高 swap 的方式把故障隐藏为成功。还有一个容易忽略的点如果你在配置 TaoToken 时遇到连通性问题先确认后端 API 本身是通的。用curl直接打后端curl -s http://192.168.1.128:8000/health curl -s http://192.168.1.128:8000/v1/models \ -H Authorization: Bearer ${SGLANG_API_KEY}如果后端通但 TaoToken 不通问题在网关层如果后端本身不通先回到第 4 节排查。6. 把三台 DGX Spark 接进 TaoToken 统一通道最后这一节说清楚接入路径。你的三台 DGX Spark 集群跑起来之后对外只暴露 rank 0 的 8000 端口。这个端口只应该在可信管理网内。TaoToken 作为统一接入层帮你把凭据管理和模型切换收敛到一个地方。具体操作步骤第一步确认后端 API 可用。在 spark-6 上执行./scripts/verify-api.sh nodes/spark-6.env看到PASS: all DeepSeek V4 API verification gates才算后端就绪。第二步拿到 TaoToken 的 API Key。进入控制台创建建议为不同用途创建不同的 key方便后续审计和轮换。第三步配置客户端。以 Codex 为例把 base_url 指向 TaoToken 的 API 端点key 用 TaoToken 的 keymodel 保持deepseek-v4-flash。这样客户端不需要知道后端三台机器的具体 IP也不需要持有后端服务凭据。第四步验证连通性。用模型对话入口发一条测试请求确认返回正常。如果失败先检查 key 和 base_url再检查后端是否可达。对于长期编码和 Agent 场景建议用 Coding Plan它更适合持续性的编码任务有更稳定的配额和更长的会话支持。如果你只是偶尔验证模型用模型对话就够了。接入文档里有完整的参数说明、错误码解释和示例代码建议对照着配置。API Keys 页面可以管理你的 key包括创建、查看状态和轮换。这里再强调一次安全边界TaoToken 是统一接入层不是让你把后端 8000 端口直接暴露到公网。正确的架构是后端 API 在可信管理网内TaoToken 作为受控的统一入口。多用户或跨网访问时在 API 前增加独立 TLS 反向代理或网关并实现每客户端身份认证、最大输入 8192 token、默认并发 4、后端总在途不超过 8、长上下文请求并发 1、请求速率和排队上限、超时取消和审计日志脱敏。生产限额必须保持输入 cap 8192 tokens交互默认并发 4后端最大在途 8长上下文并发 1。256→128 合成形状建议稳态到达率 0.10 req/s同一形状 0.20 req/s 仅允许短暂排队0.30 req/s 是 SLA WARN 不作为交互默认。其他真实工作负载必须重新压测 arrival 曲线。如果你要把这套部署交给团队使用最短验收清单是这样的三机 hostname、管理 IP、rank 一一对应key-based SSH 无交互通过三机模型路径相同index 引用 46 个 shard六子网 Ring 无重叠 IPv4LL四个逻辑 HCA/node Up物理链路 200 Gb/s三机拥有相同派生 image ID三份.env权限 0600公共运行参数和秘密匹配单机 preflight、container smoke、cluster preflight 全部通过cluster-nccl-smoke.sh 三 rank 为 NET/IB 且数据正确cluster-up.sh 成功wait-ready.sh 返回 Readyverify-api.sh 和 verify_agent_endpoints.py 全部 PASSGateway/客户端限制生产输入 8192、默认并发 4、最大在途 8。完成本教程不代表可以跳过变更管理。任何 OTA、网络、镜像、模型、context、内存比例、并发或 CUDA Graph 变更都会使相关历史 PASS 失效必须按对应 Gate 重新验证。