Surya 2 如何用 SURYA_GUIDED_LAYOUT 开启或关闭 JSON schema 约束解码【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90 languages项目地址: https://gitcode.com/GitHub_Trending/su/surya在 Surya 2 中跑 layout 分析时模型的原始输出是一段 JSON。SURYA_GUIDED_LAYOUT就是控制这段输出是否走 JSON schema 约束解码的开关开启后layout 的 decode 被限制在LAYOUT_JSON_SCHEMA的结构之内从结构上杜绝畸形 JSON关闭后模型自由解码再由客户端解析。本文覆盖该开关的默认值、开启/关闭的方法、它的取舍以及如何确认设置已生效。适用前提与 README 一致layout 依赖一个正在运行的推理后端NVIDIA GPU 用vllmCPU / Apple Silicon 用 llama.cpp 的llama-server后端由SuryaInferenceManager首次调用时自动拉起。本功能只对 layout 生效table_rec 有另一个独立开关见后文。SURYA_GUIDED_LAYOUT 的默认值与作用点定义在 surya/settings.py# Force layout/table_rec output through a JSON schema via guided decoding. # Eliminates malformed-JSON failures at small decode-throughput cost. SURYA_GUIDED_LAYOUT: bool True两点可以直接从源码读出默认开启True。README.md 的 Inference Backends 配置表中也确认SURYA_GUIDED_LAYOUT默认值为true说明为 JSON-schema-constrained layout decode。它只在layout环节生效。surya/layout/init.py 在每次调用时读取该设置决定是否把 schema 传给推理管理器guided LAYOUT_JSON_SCHEMA if settings.SURYA_GUIDED_LAYOUT else None如何开启或关闭用环境变量Surya 的设置基于 pydantic-settingsConfig中通过find_dotenv(local.env)加载.env文件见 surya/settings.py。README 也明确说明可以覆盖任意设置项例如# 默认即开启显式声明也可以 export SURYA_GUIDED_LAYOUT1 # 关闭约束解码 export SURYA_GUIDED_LAYOUT0也可以把这两行写进项目的local.env文件效果相同。在 Python 中切换如果你在脚本里调用LayoutPredictor可以直接修改settings对象from surya.layout import LayoutPredictor from surya.inference import SuryaInferenceManager from surya.settings import settings # 关闭约束解码默认是开启的 settings.SURYA_GUIDED_LAYOUT False layout_predictor LayoutPredictor(SuryaInferenceManager()) layout_predictions layout_predictor([image])注意设置是在每次调用时读取的所以同一进程内改settings.SURYA_GUIDED_LAYOUT对下一次调用立即生效。开启的代价与收益源文档对该开关的评价只有一句话settings.py 注释Eliminates malformed-JSON failures at small decode-throughput cost.即消除畸形 JSON 失败代价是少量解码吞吐。需要区分两层失败约束解码保证的是输出符合 schema 结构顶层是数组最多 200 项见 surya/inference/prompts.py每项必须是label枚举于LAYOUT_LABEL_SET、bboxx0 y0 x1 y1数字串、count0–10000 的整数三个字段。客户端仍然会解析原始输出。即使开启约束解码解析抛异常时 surya/layout/init.py 也会把该页标记为errorTrue并打一条Layout parse failed: ...的警告日志日志里附带原始输出前 300 字符便于排查。相邻开关SURYA_GUIDED_TABLE_REC 默认是关闭的table_rec 有对应的开关SURYA_GUIDED_TABLE_REC默认False。surya/settings.py 的注释给出了原因TABLE_REC_JSON_SCHEMA没有minItems约束解码器在temperature0时会在生成一个元素后就关闭数组而模型不带 schema 时能产出格式良好的 JSON。所以做 layout 时保持SURYA_GUIDED_LAYOUT默认开启即可不要把这个经验照搬到 table_rec。如何确认开关生效按上面的方式设置环境变量或修改settings后运行surya_layout DATA_PATH其中DATA_PATH可以是图片、PDF 或图片/PDF 文件夹--output_dir可指定结果输出目录。检查输出目录下的results.json。按 README.md 对 layout 输出的说明每页的error字段true表示该页的 layout 调用失败raw字段layout 模型输出的原始 JSON专门用于调试可以对照检查输出是否符合LAYOUT_JSON_SCHEMA的结构label/bbox/count三个字段bboxes按阅读序排列的布局框label已被归一化如Text、Table、SectionHeader并带有position阅读序、count、confidence。如果日志中出现Layout parse failed警告说明即使未开启约束解码解析环节仍出了问题可按日志中附带的 raw 前 300 字符定位原因。限制该开关只作用于 layout 的 JSON 输出OCR 全文HTML 输出和 table_rec 不走这个开关。开启约束解码有少量解码吞吐代价源文档的表述是 small decode-throughput cost未给出具体数值关闭则可能重新出现畸形 JSON 导致的解析失败。推理后端必须在场layout / OCR / table_rec 都需要 vllm 或 llama.cpp 服务在运行只有文本线检测可以脱离 VLM 单独工作。【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90 languages项目地址: https://gitcode.com/GitHub_Trending/su/surya创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考