Unlimited-OCR 部署运行（10/13）：推理输出乱码根因——wheel RECORD sha256 审计

Unlimited-OCR 部署运行（10/13）：推理输出乱码根因------wheel RECORD sha256 审计

服务能启动、/health 返回 200，但端到端推理输出是乱码 ------重复 token、无意义的中日韩字符混杂。这不是启动参数问题（第 09 篇 已排除），而是更隐蔽的模型装配层被破坏。本篇记录一次完整的根因定位：用"内核单测 + wheel RECORD sha256 审计"两板斧，锁定 3 个被手工改坏的 sglang 源码文件，并从官方 wheel 还原。这套审计法，建议你也存一份------它能在任何"输出又变乱码"的时刻立刻复现。

---

一、现象：服务活着，但输出是垃圾

服务正常起来，但 OCR 一张正常图片，得到的是：

orb.Mvc活用胡说胡说...   （重复 token 18452，无意义中日韩字符混杂）

带 logprob 探针显示 input_token_logprobs 全在 -16 ~ -32 （正常应为 -2 ~ -8）------说明模型在位置 0 就"自信地输出垃圾"。bug 不在 rope / attention（位置 1 时二者平凡），而在 embedding / RMSNorm / MoE / lm_head 装配链路。

---

二、两板斧定位法

第一斧：内核数值单测 ------ 证明底层算子没问题

先排除"是不是我们编的 CUDA 算子数值错了"。写 test_kernels.py 对关键算子做数值比对：

# 伪代码：把 sglang 的 CUDA 算子结果和纯 PyTorch 参考实现比对
sgl_kernel.rmsnorm(x, w)            vs  ref_rmsnorm(x, w)
sgl_kernel.fused_add_rmsnorm(...)   vs  ref
sgl_kernel.silu_and_mul(...)        vs  ref
sgl_kernel.rotary_embedding(...)    vs  ref
triton fused_experts(MoE)           vs  ref_moe

结果：全部相对误差 ≤ 0.006 → 底层算子数值正确。bug 在模型装配层，不是 kernel。

这一步非常关键：它把排查范围从"整个 sglang"收窄到"模型类 / 权重映射 / config 匹配"这一小块，避免你在 CUDA 代码里白绕。

第二斧：wheel RECORD sha256 审计 ------ 揪出被改坏的文件

sglang 安装后，每个文件在 wheel 的 RECORD 里都有官方 sha256。用 Python 读 site-packages/sglang-*.dist-info/RECORD，对每个 .py 重新算 sha256，和官方值比对，差异文件就是"被改过"的。

import hashlib, csv, os,zipfile

def sha256(p):
    h = hashlib.sha256()
    with open(p, "rb") as f:
        for b in iter(lambda: f.read(1 << 20), b""):
            h.update(b)
    return h.hexdigest()

# RECORD 在 sglang-*.dist-info/RECORD，每行: 相对路径,sha256,大小
rec = "Lib/site-packages/sglang-0.0.0.dev11416+g92e8bb79e.dist-info/RECORD"
root = "Lib/site-packages"
with open(rec) as f:
    for row in csv.reader(f):
        if len(row) < 2: continue
        rel, exp = row[0], row[1]
        fp = os.path.join(root, rel)
        if rel.endswith(".py") and os.path.isfile(fp):
            if sha256(fp) != exp:
                print("CHANGED:", rel)

对 .venv/Lib/site-packages/sglang/srt/ 下 1047 个 .py 逐一比对，发现 3 个文件被改：

文件	改动
models/unlimited_ocr.py	被替换成 5210 字节的 hand-written transformers fallback 包装器 （原版 18451 字节）
configs/unlimited_ocr.py	第 586 行 model_type = "unlimited-ocr" 被改成 "unlimited-ocr-sglang"
models/transformers.py	hf_to_sglang_mapper 中 4 行映射被删

---

三、3 个文件到底怎么坏的（错误链）

文件 1：models/unlimited_ocr.py 被换成 fallback 包装器

被替换的版本是：

class UnlimitedOCRForCausalLM(MultiModalMixin, CausalMixin, TransformersBase):
    def forward(self, ...):
        ...
        with torch.no_grad():
            out = self.model.model.forward(  # 直接调 HF 基座，use_cache=False
                input_ids=..., past_key_values=None, use_cache=False, ...)

它绕过了 sglang 的 KV cache 与注意力后端，直接用 HF 基座 forward------这正是"位置 0 就输出垃圾"的元凶：sglang 的调度/缓存假设完全没被满足。

原版官方实现基于 DeepseekForCausalLM + deepseek_ocr（SAM ViT-B + CLIP-L + MlpProjector），18451 字节。

文件 2：configs/unlimited_ocr.py 的 model_type 被改

模型 config.json 写的是 "unlimited-ocr"。这一改使 sglang 原生 UnlimitedVLConfig 匹配失败 ，强制回落 trust_remote_code HF 通路，进而加载上面那个被替换的 fallback 模型类。整条错误链由这处隐蔽改动触发。

文件 3：models/transformers.py 的权重映射被删

hf_to_sglang_mapper 里 4 行映射被删：

model.layers.        → model.language_model.layers.
model.embed_tokens.  → model.language_model.embed_tokens.
model.norm.          → model.language_model.norm.
model.rotary_emb.    → model.language_model.rotary_emb.

删掉后，权重加载时这些层对不上，模型装配直接错位。

三个文件互为因果：文件 2 触发回落 → 加载文件 1 的 fallback 类 → 文件 3 的 mapper 缺失让权重错位。任一单独存在都不致乱码，三个叠加才表现出"服务正常、输出全错"。

---

四、修复：从官方 wheel 还原 + sha256 校验

从项目内原始发行 wheel wheel/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whl 取出这 3 个文件的官方版本，覆盖回去，并重新跑 sha256 确认与官方一致（改完即验证，见 第 08 篇 铁律）：

# 从 wheel 里取官方文件
import zipfile
whl = zipfile.ZipFile("wheel/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whl")
for name in ["sglang/srt/models/unlimited_ocr.py",
             "sglang/srt/configs/unlimited_ocr.py",
             "sglang/srt/models/transformers.py"]:
    data = whl.read(name)
    out = os.path.join("Lib/site-packages", name)
    # 先备份被改坏的版本，再覆盖
    open(out, "wb").write(data)

还原后三个文件 sha256 全部与 wheel RECORD 一致：

• models/unlimited_ocr.py ← 18451B（备份 unlimited_ocr.py.transformers-fallback.bak）
• configs/unlimited_ocr.py ← model_type 改回 "unlimited-ocr"（备份 unlimited_ocr.py.port.bak）
• models/transformers.py ← 还原 4 行 mapper（备份 transformers.py.port.bak）

---

五、验证

• 文本探针 /generate：The capital of France is → 输出连贯英文；output_token_logprobs 全部健康（-0.03 ~ -0.95）。
• 非流式 OCR /v1/chat/completions：baidu.png → title [14, 0, 999, 999]Baidu 百度（识别正确）。
• 流式 OCR test_inference.py baidu.png：Status 200，TTFT 0.20s，TPS 38.39，输出 <|det|>title [14, 0, 999, 999]<|/det|>Baidu 百度。此前 10 分钟流式 ReadTimeoutError 也消失了------该超时同样是 broken fallback 路径的症候。

---

六、给你的避坑清单

1. "输出又变乱码"的第一反应 ：立刻重跑上面的 wheel RECORD sha256 审计，优先检查 models/unlimited_ocr.py / configs/unlimited_ocr.py / models/transformers.py 是否被再次改坏（多个 AI 工具 / 手工改动都可能在你不知情时改这些文件）。
2. 任何"改好"都要 sha256 坐实：脚本报告还原成功 ≠ 真的和官方一致，必须重算 sha256 比对。
3. 全量审计结论 ：除本篇修复的 3 个文件外，运行时 sglang 与官方发行版仅差 15 个有意为之的 Windows 兼容补丁（见 第 11 篇 的审计表），无任何其它非预期改动。

---

七、小结与下一篇

本篇的两板斧------内核单测收窄范围 + wheel RECORD sha256 审计精准定位 ------把"输出乱码"这种最让人无从下手的故障，变成了可复现、可验证的确定性排查。核心结论：底层算子没错，是 3 个模型装配文件被人改坏；从官方 wheel 还原 + sha256 校验即修复。

第 11 篇 讲另一个"服务起不来"的经典故障：日志停在 server_args 后无输出、GPU 显存不涨------根因是 Windows 环境变量块超过 32KB 上限，导致 spawn 子进程在 import torch 时崩溃（0xC0000005）。

---

系列导航（全 14 篇）（同第 09 篇，略）

编译移植篇 00--08 见 第 09 篇导航；部署运行篇：

• 09 · 正确启动
• 10 · 排障①：乱码根因定位（本篇）
• 11 · 排障②：环境变量块超限 spawn 崩溃
• 12 · 性能调优：RTX 3090 MoE autotune config
• 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 参考（推理调用）