Unlimited-OCR 部署运行9/13正确启动 SGLang 模型参数逐项理由前 8 篇编译移植篇我们把sglang-kernel从源码编出了win_amd64wheel并让 sglang 高性能后端在原生 Windows 上装得上、导得进、依赖闭合。但装好不等于跑通——本篇部署运行篇第 1 篇讲最务实的一步怎么把这个编好的后端真正启动起来加载 Unlimited-OCR 模型对外提供 OCR 服务。这一步藏着不少 Windows 特有的坑环境变量块超限、模型放在网络盘导致超时、若干 Windows 专用启动参数任何一处没对齐表现都是服务起不来或起来但输出不对。本篇把已验证可用的完整启动方式一次给全。一、前置你已经具备什么启动之前请确认编译移植篇的产物已经就位详见 第 02 篇 的三铁证 第 07 篇 的安装验证python -c import sgl_kernel; print(Kernel OK) # 编出的 C/CUDA 扩展能加载 python -c import sglang; print(sglang, sglang.__version__) # sglang 主包就位 pip show sglang sglang-kernel # Required-by 链闭合模型权重建议放在本地 SSD本机实测 K: 盘是网络/外置盘读 6.4GB 模型约 1.5 MB/s必然触发启动超时拷到 C: 盘约 70s:: 模型放到本地 SSD例如 C:\models\Unlimited-OCR 含 config.json / *.safetensors / tokenizer 等模型路径后续会作为--model参数传入。本文所有示例均假设模型在C:\models\Unlimited-OCR。二、关键启动参数逐项解释下面是已验证可用、针对 Windows RTX 3090 Unlimited-OCR 调过的完整参数集。不要照抄别的平台的启动命令——其中好几项是为 Windows 专门加的。cdK:\PythonProjects5\Unlimited-OCRunsetACC_PRODUCT_CONFIG_V3 .venv\Scripts\python.exe-u-msglang.launch_server ^--modelC:/models/Unlimited-OCR ^ --served-model-name Unlimited-OCR ^ --attention-backend triton ^ --page-size1^ --mem-fraction-static0.7^ --context-length32768^ --trust-remote-code ^ --enable-custom-logit-processor ^ --disable-overlap-schedule ^ --skip-server-warmup ^ --disable-cuda-graph ^ --disable-hybrid-swa-memory ^--host0.0.0.0--port10000每一项为什么这么设参数取值为什么Windows / 本机特定--attention-backendtritonWindows 上fa3不可用FA3 是 Hopper 专属见 第 06 篇 裁剪用triton后端最稳。--page-size1Unlimited-OCR 的 KV cache 页大小固定 1。--mem-fraction-static0.7关键。默认 0.3 时剩余内存为负KV cache 无法分配本机 24GB 卡、模型 ~6.4GB、其他应用还占几 GB0.7 是实测能正常分配 KV cache 的值。显存更干净可上调。--context-length32768长文档 OCR 需要较大的上下文见 第 13 篇。--trust-remote-code开Unlimited-OCR 用trust_remote_code加载自定义模型类。--enable-custom-logit-processor开OCR 输出需要自定义 logit 处理。--disable-overlap-schedule开Windows 上重叠调度有兼容问题关掉更稳。--skip-server-warmup开跳过预热避免冷启动卡在预热阶段。--disable-cuda-graph开Windows 下 CUDA Graph 兼容性差关掉。--disable-hybrid-swa-memory开关键。模型 config 有sliding_window128混合 SWA 内存池计算异常关掉后内存记账正常。SGLANG_ENABLE_STRICT_MEM_CHECK_DURING_IDLE0环境变量SWA 内存记账误报swa_leaked为负降级为警告避免被误杀。PYTHONUNBUFFERED1环境变量实时输出日志避免 Windows 下日志缓冲导致看起来卡住。--mem-fraction-static和--disable-hybrid-swa-memory这两项是 Windows 上能起来和起来就崩/内存算错的分水岭务必带上。三、最稳的启动方式直接拉起launch_server项目里有run_server.py作为父进程 子进程的包装器。但实测在后台任务框架里父进程被回收会连累子服务一起死。更稳的做法是直接把sglang.launch_server作为后台任务本身让后台任务就是服务进程树cdK:\PythonProjects5\Unlimited-OCRunsetACC_PRODUCT_CONFIG_V3nohup.venv\Scripts\python.exe-u-msglang.launch_server ^--modelC:/models/Unlimited-OCR --served-model-name Unlimited-OCR ^ --attention-backend triton --page-size1--mem-fraction-static0.7^ --context-length32768--trust-remote-code --enable-custom-logit-processor ^ --disable-overlap-schedule --skip-server-warmup --disable-cuda-graph ^ --disable-hybrid-swa-memory--host0.0.0.0--port10000^log/srv.log21echolaunched, PID$!engine.py里的_shrink_env_for_windows_spawn()见 第 11 篇仍作为兜底但你最好同时在父进程侧先unset那个超大变量让父进程 env 块本身就 32K。四、怎么确认服务真的就绪Windows 下 SGLang 子进程 stdout 经管道/重定向会严重缓冲日志文件常为空或停更。不要只盯着日志文件用下面三种方式判断进度# 1) GPU 显存是否增长模型传到 GPU 的标志nvidia-smi --query-gpumemory.used,memory.free--formatcsv,noheader# 2) 服务是否就绪curl-s--connect-timeout3http://127.0.0.1:10000/healthecho UP||echoDOWN# 3) worker 是否在推进CPU 秒 / 内存是否增长powershell-CommandGet-Process python | Sort-Object CPU -Descending | Select-Object -First 5 Id,{NMemMB;E{[math]::Round($_.WorkingSet64/1MB)}},{NCPU;E{[math]::Round($_.CPU,1)}} | Format-Table -AutoSize正常表现模型从 C: 盘冷启动~50–60s 内完成加载/health返回 200GPU 显存涨到数 GB。首次请求会非常慢服务冷启动时triton 会对所有 kernelvision 编码器 7 个 MoE 唯一 config 注意力做 JIT 编译首请求可能 300s。客户端超时要放宽建议 600s服务其实在正常编译 生成不是卡死。热身后的请求回到 ~50–60s 级详见 第 13 篇。五、最小推理验证服务就绪后对一张测试图发请求参考test_inference.py/infer.py.venv\Scripts\python.exe test_inference.py assets/baidu.pngdocument parsing.预期Status 200、输出含Baidu 百度、流式在亚秒内结束。如果输出是乱码/无意义中日韩字符混杂请直接跳到 第 10 篇 按wheel RECORD sha256 审计法排查——这通常是 sglang 源码里某几个模型文件被改坏不是启动参数的问题。六、小结与下一篇本篇给全了 Windows 上启动 SGLang Unlimited-OCR 的已验证启动命令、每一项 Windows 专用参数的理由、最稳的直接启动方式以及不依赖日志的就绪判断方法。记住三个分水岭unset ACC_PRODUCT_CONFIG_V3否则 spawn 子进程崩溃见 第 11 篇--mem-fraction-static 0.7--disable-hybrid-swa-memory否则内存算错/起不来模型放本地 SSD否则 K: 网络盘读取超时。第 10 篇进入第一个排障实战服务能起、但输出是乱码——根因不是启动参数而是 3 个 sglang 源码文件被手工改坏我们用 wheel RECORD sha256 审计法定位并还原。系列导航全 14 篇编译移植篇怎么把 sglang 从源码编出来00 · 系列总览01 · EPGF 环境地基与岔路口02 · 结论与可行性三铁证 --no-deps03 · 编译篇·前置FlashInfer Windows 源码编译04 · 编译篇·环境关05 · 移植篇(上)GCC 方言06 · 移植篇(下)语义严格与崩溃07 · 编译篇·收尾架构裁剪与 LNK201908 · 方法论部署运行篇怎么跑起来并排障09 · 正确启动 SGLang Unlimited-OCR本篇10 · 排障①推理输出乱码/数值错误根因定位11 · 排障②环境变量块超限导致 spawn 子进程崩溃12 · 性能调优RTX 3090 MoE triton autotune config13 · 长文档验证 代理/端口冲突坑 使用指南参考资料与延伸阅读以下为本文涉及的官方仓库、文档与规格站建议发布前点一遍确认可达Unlimited-OCR 官方仓库模型与项目源码SGLang 官方仓库SGLang 官方文档启动参数 / OpenAI 兼容 APIflashinfer-windowsWindows 兼容 fork编译前置vllm-windows同作者可对照的 Windows 移植思路PyTorch Windows CUDA 预编译索引cu130NVIDIA CUDA Toolkit 下载uv 官方文档Python 环境治理MSVC /Zc:preprocessor 标准预处理器MSVC 致命错误 C1001编译器内部错误nvcc -Xcompiler 转发 host 编译器选项CMake 生成器Visual Studio / NinjaRTX 3090 规格GA102 / sm_86共享内存 100KBCUDA 共享内存上限与 dynamic_shared_memory 限制Windows 子进程环境变量块限制CreateProcess / ~32KBOpenAI 兼容 API 参考推理调用
