| title | Remote Debug · 基础策略 | ||
|---|---|---|---|
| created | 2026-07-10 | ||
| updated | 2026-07-10 | ||
| type | guide | ||
| tags |
|
||
| sources |
远端任务先按下面的机制推进,再读具体事故细节:
- 侦察:确认 worktree/head、venv/import、cache root、模型/config 文件和当前 endpoint 支持的 CLI 参数。
- 本地化试错:调试阶段优先远端临时脚本 / one-liner,不用 commit-push-pull 当调试循环。
- 脚本化复杂命令:PowerShell -> SSH -> bash 的复杂命令必须落脚本;Bash 脚本完整执行下面的 fail-closed 投递门禁,其他解释器使用自己的语法检查。
- import gate:新 venv、重装依赖、换节点或 benchmark 前,先验证
torch/vllm/vllm_omni/transformers/flashinferimport 和版本。 - 状态汇报:远端 issue 复现只汇报 server/client 双日志和 server-side signature,不把“命令跑过”当复现成功。
Windows 或 PowerShell 产生的 Bash 脚本在远端执行前,必须同时过这四道门。Python、PowerShell 或其他解释器的脚本必须改用对应的语法/编译检查,不得套 bash -n。
test -s机器判定文件非空,wc -c只记大小,sed -n '1,40p'证明实际内容和目标一致。- 检查并去除 UTF-8 BOM 和 CRLF;
bash -n抓不住所有 shebang/BOM 问题,不能单独当编码证据。 bash -n <script>必须通过。如果合同是直接执行./script,还必须验证允许的 Bash shebang 和可执行权限;合同是bash script时不伪造 shebang 要求。- 脚本要么使用
set -euo pipefail,要么显式捕获并验证每个阶段的返回码。两者都没有时,后面的命令成功不能让整个 preflight 变成 PASS。
最小检查示例:
set -euo pipefail
script=/tmp/run_x.sh
test -s "$script"
wc -c "$script"
sed -n '1,40p' "$script"
first3=$(od -An -tx1 -N3 "$script" | tr -d ' \n')
if [ "$first3" = efbbbf ]; then
echo "UTF-8 BOM found in $script" >&2
exit 1
fi
if grep -n $'\r$' "$script"; then
echo "CRLF found in $script" >&2
exit 1
fi
bash -n "$script"
# 后续直接执行脚本路径时,显式设 DIRECT_EXECUTE=1。
if [ "${DIRECT_EXECUTE:-0}" = 1 ]; then
case "$(head -n 1 "$script")" in
'#!/bin/bash'|'#!/usr/bin/bash'|'#!/usr/bin/env bash') ;;
*) echo "unsupported Bash shebang in $script" >&2; exit 1 ;;
esac
test -x "$script"
fi任何验证或编码错误,以及直接执行合同下的 shebang/权限错误,都必须先修正再执行。使用 bash <script> 时 shebang 不参与解释器选择,但 BOM、CRLF、语法和错误处理门禁仍必须通过;脚本最后 exit 0 不能覆盖早先的门禁失败。
git commit-push-pull 是部署手段,不是调试手段。每轮"本地改 → push → 远端 stash → pull → run"5-10 分钟,6 轮就是 30-60 分钟。判据:你的 commit message 是 "fix attempt N" → 你在用部署流程做调试,立刻停下来换策略。
正确做法:
- 调试:远端直接写
/tmp/test_xxx.py或 Python one-liner,tmux 里跑,快速迭代 - 确认方案后:回本地写正式代码,一次 commit-push-pull 部署
反例(2026-04-21 tokenizer 6 轮失败链):
AutoTokenizer.from_pretrained→ 没auto_map(没看 tokenizer_config.json)PreTrainedTokenizerFast.from_pretrained→ transformers 版本 bug(没查远端版本)get_class_from_dynamic_module→HF_HUB_OFFLINE=1断网(忘了离线约束)snapshot_download→ symlink 解析失败(不了解 HF cache 结构)try_to_load_from_cache→ 依赖refs/main不存在(同上)- 手动遍历 HF cache 目录 → 成功(应该是第 1 步)
如果第 1 步花 5 分钟收集信息:
# 一次 SSH 全收集
cat $HF_HOME/hub/models--XXX/snapshots/*/tokenizer_config.json
ls $HF_HOME/hub/models--XXX/refs/ # refs/main 是否存在
ls $HF_HOME/hub/models--XXX/snapshots/*/tokenizer*
pip show transformers | grep Version
python -c "from transformers import AutoTokenizer; AutoTokenizer.from_pretrained('XXX')"就能一次性发现所有阻塞点,直接跳到最终方案。
- 路径:
$HF_HOME/hub/models--{org}--{name}/snapshots/{hash}/ refs/main可能不存在(手动下载或旧版 CLI 不创建)try_to_load_from_cache(revision=None)依赖refs/main→ 不可靠snapshot_download返回的路径可能有 symlink 问题- 最可靠 fallback:手动遍历 snapshots/ 目录找文件
- tmux 前台进程陷阱:
python ... | tee log占住 shell,send-keys发的命令进了进程 stdin。测试 API 必须从另一个 window 发请求 - docker exec 跨节点引号陷阱:
ssh nodeA "docker exec $(docker ps -q) ..."的$()在本地展开 → 必错。解法:写脚本到 Lustre,然后ssh nodeA bash /shared/path/script.sh - 远端发命令后必先短 sleep(≤5s)+ capture 确认脚本真启动了(看到 pytest
collected N items/ 程序日志 / 明确错误信息),再长 sleep 等结果。光看 shell 回显不算 - PowerShell→SSH→bash 脚本投递陷阱:
$VENV/$()可能被本地 PowerShell 展开,UTF-8 BOM 会污染首行,脚本甚至可能落成 0 字节。远端落盘后必须完整执行本页的 canonical fail-closed 投递门禁,不使用弱化三连代替。 - 路径猜测陷阱:HF snapshot 只代表权重/processor 资产,不代表 vLLM-Omni deploy yaml。写远端脚本前先
find <REMOTE_WORK_ROOT> ... -name "*hunyuan*yaml"和test -f "$MODEL_CFG",不要假设 snapshot 下有deploy.yaml。 - 旧 PR venv/ABI 陷阱:base commit 不一定兼容当前默认 venv。测旧 PR 先跑 base worktree 的 import/init smoke,确认 custom op / scheduler symbol / vLLM version 匹配;base 起不来时结论是 environment blocker,不是 PR 性能数据。
Plan 按当前任务拆,不要把未来工作混进来。当前任务是 X 就只 plan X——过大的 plan 导致认知负担重 + 每次读 plan 烧 context。
每次 SSH(ASKPASS + capture-pane)~500 token,6 轮调试 × 每轮 3-5 次 = 大量浪费在重复模板。
- 合并 SSH:一次发多条命令(
&&或脚本) - 减少 capture 频率:合理估算等待时间,不要频繁轮询
- 复杂操作写远端脚本一次执行
- 新终端接手远端任务时,先从当前会话/issue/PR 摘 5 行 runbook(head sha、worktree、venv、tmux、out_dir),不要把已知远端重新
find一遍。 - 已知有
<REMOTE_WORK_ROOT>/wt-...worktree 时,先git -C <dir> status/rev-parse HEAD验证事实;只有不一致才扩大搜索。 - PowerShell 管道可能因 CRLF/BOM 让路径检查变脏;看到“文档路径不存在”这类结论,先用无 BOM/LF 聚合脚本复查。
2026-06-05 PR4041 DiT 复测踩坑:用户要求在 <REMOTE_WORK_ROOT> 删除旧 venv 并重装。第一次按旧记忆装 vllm==0.21.0,结果 vllm-omni import gate 失败,报 vllm.model_executor.models.registry symbol mismatch。修正后用 vllm==0.22.0 才能进入正式 benchmark。
经验:
- 删 venv 前确认目标路径:
readlink -f <REMOTE_WORK_ROOT>/.venv,只删用户指定根下的 venv。 - 新 venv/cache 都落宿主工作根:
UV_CACHE_DIR、PIP_CACHE_DIR、XDG_CACHE_HOME、HF_HOME指向<REMOTE_WORK_ROOT>/...,不要写/root/.cache。 - benchmark 前必须 import gate:
python - <<'PY' import torch, vllm, vllm_omni, transformers, flashinfer print(torch.__version__, torch.cuda.is_available(), torch.cuda.device_count()) print(vllm.__version__, transformers.__version__, flashinfer.__version__) print(vllm_omni.__file__) PY
- 版本错配是 blocker,不是性能数据:import/init smoke 失败时先修环境,不进入长跑。
- 正式结果只看同口径 JSON:init time、warmup、measured elapsed/throughput 分开;baseline 和 candidate 要同物理 GPU、同模型、同 quantization、同 prompt/steps。
2026-06-08 讨论 HunyuanImage3 grouped DiT 时踩的表达坑:scheduler tick 里同时带出多个 request,不等于这些 request 一定在同一个 forward 里跑,更不等于并行跑。pipeline 还会按 step/layout/shape 拆成 step groups;拆出的多个 group 是在同一 worker 内 for-loop 串行执行多个 forward,不是 CUDA stream 并行,也不是多模型副本并行。
回答 diffusion batching / performance 问题时必须显式区分:
- 同一 scheduler tick:scheduler output 可以包含多个 request。
- 同一个 Hunyuan step group:shape、CFG、layout 兼容后才会合成一次 DiT forward。
- 多个 step group:同一 tick 内按 group 顺序串行 forward,属于 micro-batch 串行。
例子:512x512 请求和 768x768 请求即使出现在同一 scheduler tick,也会因为 latent shape / num_image_tokens 不同被拆成两个 group,然后先后跑两个 forward。不要说成“一起跑”;正确说法是“同一轮调度,但 pipeline 内部分组后串行执行”。不同 later step 在 same shape / compatible layout 下可以进同一个 forward;first step 和 later step 会拆组。
复现不是“命令跑过”,而是“打到同一路径并收集到同类证据”。本轮 #3743 里有几件事值得保留:
- 先把 blocker 串行化:
venv OK→vllm import OK→vllm-omni import OK→server /health OK→client request OK→server-side signature OK。前一步不 OK,不碰后一步。 - 用当前代码验证 issue 命令是否仍有效:先看
--help、endpoint mapping、request schema。脚本版本变了时,明确记录差异,不用“差不多”的 benchmark summary 冒充复现。 - server/client 双日志配对:client 记录每个请求的 status/latency/body length;server 用 grep 统计关键签名(如
KV transfer OK、Pool exhausted、Timeout waiting for KV cache)。最终结论只基于 server-side 签名。 - 失败类型先分类:低成功率可能来自 400/schema/chat-template,也可能来自 500/engine/KV timeout。先查 HTTP status 和 traceback,再决定是否继续压测。
- 手写最小客户端补齐 benchmark 缺口:当 benchmark CLI 不支持 issue 参数时,写最小 aiohttp/curl 客户端直接打目标 endpoint;请求字段显式列出,日志可复用。
- 环境 caveat 写在结论里:硬件、checkpoint、YAML、脚本版本、
max_inflight这类差异必须写出来。不能把 CUDA 上 Instruct 的结果包装成 Ascend 上 Distill 的严格复现。 - 释放资源只杀自己的 PID:记录 server/client pid;结束时只 kill 本次 venv /
repro*进程,不碰其他用户服务。释放后用 GPU memory 检查确认。
快速证据模板:
# client summary
tail -160 /tmp/repro_x_client.log
# server signature counts
grep -c 'KV transfer OK' /tmp/repro_x_server.log
grep -c 'Successfully received KV cache' /tmp/repro_x_server.log
grep -c 'Pool exhausted' /tmp/repro_x_server.log
grep -c 'Timeout waiting for KV cache' /tmp/repro_x_server.log
grep -c 'KV transfer FAILED' /tmp/repro_x_server.log
# config caveat
grep -n 'max_inflight\|memory_pool_size' vllm_omni/deploy/hunyuan_image3.yaml