Unlimited-OCR 部署运行（11/13）：环境变量块超限导致 spawn 子进程崩溃

Unlimited-OCR 部署运行（11/13）：环境变量块超限导致 spawn 子进程崩溃

第 09 篇 给了"最稳的启动命令"，其中第一条就是unset ACC_PRODUCT_CONFIG_V3。本篇讲清楚为什么必须这样做——一个只在 Windows 上出现、且极具迷惑性的故障：服务日志停在server_args后完全无输出、GPU 显存不涨、worker 卡在 ~866MB CPU 内存，看似"模型加载慢"，实则子进程已经崩了。

一、现象：日志停在 server_args，然后"静默挂起"

• 日志打印完server_args=...后再无任何输出（没有 “Loading weights”、没有 JIT 进度）。
• GPU 显存始终 ~532 MiB（模型权重没传到 GPU）。
• worker 进程停在 ~866 MB CPU 内存、~11.5 CPU 秒、~49–52 线程，长时间无变化→ 硬挂起，不是慢加载。
• /health持续 DOWN；run_server.py最终超时。

第一直觉是"模型加载慢 / JIT 编译卡住"。但监控（见 第 09 篇 第四节）显示 GPU 显存根本没动——这说明问题在模型加载之前。

二、根因：Windows 环境变量块 ≤ 32,767 字符

SGLang 用multiprocessing+spawn拉起 tokenizer / worker 子进程。Windows 的CreateProcess把整个父进程环境块传给子进程，而 Win32 对环境块大小有硬上限32,767 字符。

实测本机父进程（在某壳层 / IDE 下）继承了超大环境变量块：372,009 字符，远超上限。其中元凶是单个变量ACC_PRODUCT_CONFIG_V3≈354 KB（由本机某壳层 / IDE 注入）。

超限后，spawn 出来的子进程在import torch阶段直接访问冲突崩溃（0xC0000005），父进程收不到任何子进程输出 → 表现为"日志停在 server_args 后无输出、GPU 显存不增长、worker 卡死"。

关键认知：父进程自己能跑、能打印server_args，不代表子进程能起来。spawn 子进程是一个全新的CreateProcess，它要复制整个 env 块——父进程 env 块过大，子进程在最早阶段就崩了，连报错都传不回父进程。

三、为什么"之前能跑通"

同一份代码，之前曾生成 3554+ token 成功跑通。原因是：那时父进程环境块恰巧较小（没被注入那个 354KB 变量）。后来环境被注入超大变量后，必然崩溃。这解释了"明明什么都没改，怎么突然起不来了"——你没改代码，但环境变了。

四、修复 A：代码层兜底（_shrink_env_for_windows_spawn）

在sglang/srt/entrypoints/engine.py新增_shrink_env_for_windows_spawn()，在_set_envs_and_config()中调用（仅sys.platform == "win32"生效）：

def_shrink_env_for_windows_spawn():ifsys.platform!="win32":returnsize=_win_env_block_size()# 所有 k+v+2 的字符总和ifsize<=_WIN_ENV_BLOCK_BUDGET:# 30000，留余量低于 32767return# 按"变量占用字符数"从大到小排序big=sorted(os.environ.items(),key=lambdakv:len(kv[0])+len(kv[1]),reverse=True)fork,vinbig:if_WIN_ENV_BLOCK_BUDGET-(len(k)+len(v)+2)<512:break# 单变量成本 < 512 就停手，避免误删小变量ifkin_WIN_ENV_KEEP_EXACTorany(k.startswith(p)forpin_WIN_ENV_KEEP_PREFIXES):continue# 白名单保护delos.environ[k]# 若仍 > 32767，打印 ERROR 提示手动 unset

• 白名单保护：_WIN_ENV_KEEP_PREFIXES（CUDA/NCCL/TORCH/TRITON/HF_/TRANSFORMERS/PYTHON/SGLANG/FLASHINFER/OMP_/MKL_等）与_WIN_ENV_KEEP_EXACT（PATH/TEMP/SYSTEMROOT/USERPROFILE等）绝不删除——CUDA / torch / triton 相关变量被保留，子进程才能正确初始化。
• 启动时会打印：Windows environment block was 372483 chars (limit 32767). Removed ACC_PRODUCT_CONFIG_V3 (354881 chars) to keep spawned subprocesses loadable.

五、修复 B（推荐）：启动前先unset大变量

代码兜底能救场，但最稳的启动仍是在父进程侧先unset那个超大变量，让父进程 env 块本身就 < 32K：

cdK:\PythonProjects5\Unlimited-OCRunsetACC_PRODUCT_CONFIG_V3 .venv\Scripts\python.exe-u-msglang.launch_server--modelC:/models/Unlimited-OCR...

这样父进程 env 块干净，spawn 子进程从一开始就不会撞上限，连兜底逻辑都不需要触发。

六、监控与判定（不依赖日志）

再次强调：Windows 下子进程 stdout 经管道/重定向会严重缓冲，日志常为空。用客观信号判断：

# GPU 显存是否增长（模型传到 GPU 的标志）——本故障下它不涨nvidia-smi --query-gpu=memory.used,memory.free--format=csv,noheader# worker 是否推进（卡在 ~866MB 即疑似本故障）powershell-Command"Get-Process python | Sort-Object CPU -Descending | Select-Object -First 5 Id,@{N='MemMB';E={[math]::Round($_.WorkingSet64/1MB)}},@{N='CPU';E={[math]::Round($_.CPU,1)}} | Format-Table -AutoSize"

修复 env 块超限后，模型从 C: SSD 冷启动~50–60s 内完成加载并fired up——印证根因就是它。

七、给你的避坑清单

1. "启动即崩 / 日志停在 server_args"的第一反应：查父进程环境块大小

   python-c"import os;print(sum(len(k)+len(v)+2 for k,v in os.environ.items()))"

   若接近或超 32767，多半又是某个超大变量被注入——先unset它，或依赖engine.py的自动收缩兜底。
2. 不要只盯日志文件：Windows 子进程日志缓冲会骗你"卡住了"，用 nvidia-smi / 进程内存判断进度。
3. 该修复是 第 09 篇 启动命令里unset ACC_PRODUCT_CONFIG_V3的依据；它与 第 10 篇 的 15 个 Windows 补丁共同构成"运行时与官方仅差有意的 Windows 适配"的结论。

八、小结与下一篇

本篇的故障只在 Windows 上存在，且根因不在 Python 代码、不在 CUDA，而在Win32CreateProcess的环境块 32KB 上限+ 某个 IDE / 壳层注入的 354KB 变量。修法是双保险：代码层_shrink_env_for_windows_spawn()自动收缩（带白名单保护）+ 启动前unset大变量。

第 12 篇转入性能调优：RTX 3090 上 SGLang 启动会打印Using default MoE kernel config. Performance might be sub-optimal!警告——讲清为什么不能盲拷 A100 的 autotune 配置（会运行时崩溃），以及如何为 3090 生成一份安全且有效的 MoE triton autotune config。

系列导航（全 14 篇）（同第 09 / 10 篇，略）
部署运行篇：09 正确启动 · 10 排障①乱码 · 11 排障②环境变量崩溃（本篇） · 12 MoE 性能调优 · 13 长文档验证与使用指南

参考资料与延伸阅读

以下为本文涉及的官方仓库、文档与规格站，建议发布前点一遍确认可达：

• Unlimited-OCR 官方仓库（模型与项目源码）
• SGLang 官方仓库
• SGLang 官方文档（启动参数 / OpenAI 兼容 API）
• flashinfer-windows（Windows 兼容 fork，编译前置）
• vllm-windows（同作者，可对照的 Windows 移植思路）
• PyTorch Windows CUDA 预编译索引（cu130）
• NVIDIA CUDA Toolkit 下载
• uv 官方文档（Python 环境治理）
• MSVC /Zc:preprocessor 标准预处理器
• MSVC 致命错误 C1001（编译器内部错误）
• nvcc -Xcompiler 转发 host 编译器选项
• CMake 生成器（Visual Studio / Ninja）
• RTX 3090 规格（GA102 / sm_86，共享内存 100KB）
• CUDA 共享内存上限与 dynamic_shared_memory 限制
• Windows 子进程环境变量块限制（CreateProcess / ~32KB）
• OpenAI 兼容 API 参考（推理调用）