SemIf 实战指南用开放模型在本地 GPU 上实现语义化 if——直接从类型化选项读取概率的运行时决策方案【免费下载链接】SemIfSemantic ifs from open models, on a 3090 at home. Independent; not affiliated with Jev or TypeSafe.项目地址: https://gitcode.com/gh_mirrors/op/SemIf导读SemIf前身 OpenJev是一个面向运行时定义的语义化 if 决策runtime-defined semantic decisions的独立研究项目给定一段非结构化状态、一个运行时判据和一组类型化选项它不生成任何回答文本而是通过单次前向传播直接读取声明选项的原生概率把大模型当作一个if 语句评估器使用目标是在家用的单张 RTX 3090 上运行冻结的 4B 开放模型。本文将带你完整掌握 SemIf 的输入输出契约、四种执行模式direct / serial / shared / reranker、三种后端Torch / MLX / llama.cpp的选型与命令行用法并深入其源码实现、性能实测与校准方法论使你能够在自己机器上复现并部署这套决策流水线。为什么需要语义化 if从文本生成到概率直读大多数 Agent 决策其实都很小路由这条请求、要不要重试、证据是否支持结论 X。对话模型当然能回答这些问题但代价是它花大量时间生成一段文本而软件随后又要把这段文本解析回一个if语句——生成、解析、修复 JSON整条链路既慢又脆。Jev 是 TypeSafe 的闭源服务用于运行时定义的语义化决策。SemIf复现的是这一接口模式interface pattern而非 Jev 未公开的模型或训练过程用开放模型、在家用硬件上提供同类的给状态 判据 选项返回每个选项的概率能力。从源码结构看其核心主张可以概括为四点见 README.md运行时定义判据criterion与选项描述随请求一起到达而非预编译进提示词决策原生decision-native一次前向传播读取声明选项的 logits不采样任何回答 token共享状态感知一段长状态可以只 prefill 一次然后分叉到多个判据上并行评估可审计自有测试集、精确的评测脚本、逐行输出、模型 revision、提示词哈希与已知失败都被提交到仓库。一句话概括项目定位Semantic ifs from open models, on a 3090 at home.在家用 3090 上、用开放模型做语义化 if。核心原理一次前向传播读出类型化选项概率输入行契约SemIf 的输入是逐行的 JSONL每行必须包含id、state、question、options四个字段其中state是被评估的非结构化证据question是判据options是类型化候选列表{ id: route-1, state: Customer cannot access an account after a password reset., question: Which queue should handle this request?, options: [ {id: access, description: Account access support.}, {id: billing, description: Billing support.} ] }仓库自带三个可直接运行的示例examples/decisions.jsonl覆盖了部署成功判定yes/no/insufficient、客服工单路由account_access/billing/sales与变更审批策略required/not_required/insufficient三类典型场景。输入校验逻辑位于 src/semif_phase1/core.py 的validate_row约束如下id与question必须是非空字符串state必须是非空的字符串、JSON 对象或数组且必须是有限的 JSON 兼容数据json.dumps(..., allow_nanFalse)校验options必须是列表数量在 2 到 16 之间与字母表LETTERS ABCDEFGHIJKLMNOP一一对应每个 option 必须有字符串id与description字段且id全局唯一。提示词构造与单 token 槽位验证direct_messagescore.py把输入行序列化为固定的 system/user 两轮消息system 指令固定为Apply the supplied criterion to the supplied evidence. Choose exactly one listed option. Respond with only its uppercase letter, with no explanation or reasoning.应用判据、只输出大写字母user 内容是把evidence、criterion、带字母编号的options组成的 JSON 载荷ensure_asciiFalse保证中文等文本不被转义破坏。关键设计在 src/semif_phase1/direct.py 的encode_prompt每个选项字母必须编码为恰好一个往返 tokenencode 后 decode 回原字母且与相邻 token 的拼接边界不改变切分否则直接抛错——这是从原生 logits 读取能成立的前提。提示词通过apply_chat_template(..., enable_thinkingFalse)构造并计算prompt_sha256作为提示词指纹。一次前向传播与条件概率输出scoredirect.py的流程极简编码 → 单次前向 → 取出最后一个位置的完整词表 logits → 按选项槽位 token id 取值 → softmaxwith torch.inference_mode(): vocabulary _forward(model, inputs)[0].float() # 只有最后一个位置的 logits selected vocabulary[slots].cpu().tolist() return { id: row[id], option_ids: [...], probabilities: softmax(selected), option_logits: selected, input_tokens: len(ids), forward_seconds: ..., total_seconds: ..., prompt_sha256: prompt_hash, prompt_version: direct-options-v1, model: metadata, ... }_forward会检测模型是否支持logits_to_keep参数从而只保留最后位置的 logits省去整个词表的计算开销。返回的概率以给定选项为条件conditional on the supplied options输出中明确标注probability_status为条件选项得分未校准为决策置信度——这是理解 SemIf 所有结果的先决条件。安装与快速开始环境要求与安装SemIf 面向 Python 3.10、CUDA 与能容纳 4B BF16 模型的 GPUREADME 实测环境为单张 RTX 3090。推荐流程python -m venv .venv . .venv/bin/activate export HF_HOME/path/to/large-drive/huggingface pip install -e .[test]各可选依赖组见 pyproject.tomltest组pytest、mlx组仅 darwin/arm64 的 mlx 与 mlx-lm 固定版本、llamacpp组llama-cpp-python 0.3.35。命令入口semif-score由 [project.scripts] 注册到semif_phase1.cli:main。命令行全参数说明CLI 实现在 src/semif_phase1/cli.py参数如下参数取值说明--modedirect/serial/shared/reranker必选四种执行模式--backendtorch默认/mlx/llamacpp推理后端--model模型名或本地目录必选--revision40 位 commit 哈希必选远端模型必须钉死 commit本地模型则作为 manifest/revision 标签--input/--output路径必选输出必须是新文件已存在即报错防覆盖证据--max-tokens正整数默认 4096输入 token 上限超限直接报错、绝不截断--deviceauto/cuda/mps默认autoTorch 后端auto 优先 CUDA 再 MPS--dtypebfloat16默认/float16/float32精度改变它可能改变选项得分--mlx-bits4 / 8仅 MLX内存内仿射量化需未量化源检查点--mlx-cache-limit-mib非负整数默认 256仅 MLX限制闲置分配缓存MiB0 关闭--gguf路径仅 llamacpp本地 GGUF 检查点--llama-threads正整数仅 llamacppCPU 线程数默认全部可见核心CLI 还会做一组前置一致性校验cli.py例如--mlx-bits必须配--backend mlx、--gguf必须配 llamacpp、MLX/llama.cpp 后端不支持reranker模式reranker 强制走 Torch/CUDA--device mps会被拒绝。这些规则都有对应的测试用例见 tests/test_cli.py。第一个基准命令CUDA_VISIBLE_DEVICES0 semif-score \ --mode direct \ --model Qwen/Qwen3.5-4B \ --revision 851bf6e806efd8d0a36b00ddf55e13ccb7b8cd0a \ --input examples/decisions.jsonl \ --output results.jsonl每条结果包含类型化选项得分probabilities option_logits、计时、精确模型 revision含 torch/transformers 版本与prompt_sha256。CUDA_VISIBLE_DEVICES只暴露一块 GPU——Torch 加载器core.py强制单 GPU 可见且检查检查点加载完整性missing/mismatched keys 任一存在即抛错远端模型必须提供 40 位 revision。四种执行模式从逐行打分到共享状态并行direct逐行独立打分最朴素的模式逐行完整编码、一次前向、读取概率。适用于状态各不相同、无法复用的场景也是其余模式的基准。serial状态前缀缓存当同一段状态需要连续回答多个判据时src/semif_phase1/serial.py 的SerialPrefixScorer先把状态部分 prefill 一次并把原生 KV 缓存保存下来后续每行若state相同则命中缓存深拷贝一份缓存分支再只解码后缀部分。这依赖模型支持选择性末位 logitslogits_to_keep否则直接报错。输出额外带有cache_hit、prefix_tokens、prefix_sha256、allowed_token_mass选项 logits 质量占全词表的质量比与full_vocab_argmax_id。shared共享状态并行评估如果每一行都共享完全相同的 state就用--mode shared状态只 prefill 一次然后通过cache.reorder_cache复制分支CUDA 上批处理全部后缀或逐行复制MPS 上更快一次性返回所有行的概率与聚合计时prefill / replicate / suffix 分段计时。约束所有行的state必须完全一致、行id必须唯一要求模型的原生缓存支持reorder_cachesrc/semif_phase1/shared.py。共享模式的结果行会附上shared_timing汇总字段。注意串行/共享这类快速复用路径属于实验性能力——README 实测在 777 个决策上BF16 执行相对逐行新鲜打分改变了 5–6 个 argmax 结果因此对精度敏感的场景应对比两种路径的输出。reranker官方风格 Qwen3 重排器读法src/semif_phase1/reranker.py 把每个选项单独构造成证据-候选答案配对读取yes/no两个单 token 的 logits取 log-odds 作为该选项的兼容度最后对 log-odds 做 softmax 归一化用于相对比较。它对检索类场景code-rag、company-brain使用检索指令对普通决策使用决策指令probability_status明确标注为相对选项兼容度未校准为类别概率。从源码结构看reranker 在检索排序上更强而 direct 是更通用的决策基线。三种后端Torch / MLX / llama.cppTorchCUDA 与 Apple MPS默认后端经 core.py 的设备解析逻辑选择 cuda:0 或 MPSQwen3.5 系列走原生Qwen3_5ForCausalLM并要求安装的 transformers 自带该类缺失即报错。加载时禁用trust_remote_code。MLXApple Silicon 原生macOS arm64 上可安装pip install -e .[test,mlx]并在命令中加--backend mlx详见 docs/MLX.md。src/semif_phase1/mlx_backend.py 提供 direct、serial、shared 三种模式不支持 reranker。实现要点强制 Apple SiliconDarwin arm64与 Metal GPU 可用仅支持原生 Qwen3.5 文本模型model_type qwen3_5禁止自定义模型代码支持--mlx-bits 4/8的内存内仿射量化group_size64但要求源检查点未量化用mx.set_cache_limit限制闲置分配缓存默认 256 MiB--mlx-cache-limit-mib可调避免变量长度提示词挤占系统内存对源检查点逐文件计算 SHA-256 存入 metadatasource_artifact_sha256本地 revision 标签之外再增加一层来源证据。llama.cpp纯 CPU GGUF无 CUDA 设备时可用pip install -e .[test,llamacpp]获取一个 GGUF 检查点例如 Qwen3.5-4B 的 Q4_K_M 量化版命令中加--backend llamacpp --gguf /path/to/model.gguf--llama-threads限制 CPU 线程。实现细节src/semif_phase1/llamacpp_backend.py值得注意提示词构造始终使用钉死的参考 transformers tokenizer因此prompt_sha256与 Torch 后端逐行一致llama.cpp 只负责前向执行每次打分前用 GGUF 词表重新 tokenize 并与参考编码比对不一致即报错加载时还有独立的词表探针校验_verify_vocabulary输出携带 GGUF 文件校验和分数以量化权重为条件direct 与前缀缓存路径可能因 llama.cpp 不同评估路径存在小幅数值差异比较决策或概率时应带容差而非逐位对比 logitsQwen3.5 的混合线性注意力不支持序列拷贝分支复用走 llama.cpp 自身的整序列状态保存/恢复save_state/restore_state一个已加载后端只拥有一个有状态打分上下文。跨后端的一致性设计无论哪个后端输入验证、提示词模板、槽位校验、softmax 与输出字段都由 core.py 与 direct.py 统一提供后端仅替换加载 前向两层这保证了prompt_sha256跨后端可对齐、结果可对比。性能实测直读概率 vs 生成式基线决策 vs 紧凑生成数组同一冻结 Qwen3.5-4B、同一自有状态、同一 21 条二元判据、单张 RTX 3090输出路径时间中位数3 次输出 token结果直接读取类型化 logits1.023 s021 组概率对自回归生成紧凑 JSON 数组5.332 s111合法有序 21 值数组生成基线的中位首个 token 时间只有 0.489 s但完成整个数组耗时是直接读取的5.21 倍。三次数组的输出全部合法且一致与直接 argmax 在 21 条判据中 18 条一致——因此这是系统级对比而非声称两种读法语义等价。精确提示词、输出、token 时间线与全部运行记录已提交至 results/raw/decision-vs-compact-array.json。一段状态复用于 21 个决策在自有的 37 状态 × 21 判据工作负载777 个决策上执行路径决策/秒777 个决策耗时逐行新鲜 direct 打分2.33333.1 s串行前缀复用10.7572.3 s并行后缀20.0338.8 s原生 reranker1.86417.3 s对应证据文件自有 37×21 测试集、direct/复用评测脚本、reranker 评测脚本、原始计时 与逐行预测。注意快速复用路径是实验性的前述 BF16 下 5–6/777 的 argmax 变化。质量评估与校准浏览器模型阶梯Browser model ladder系统浏览器产物下载体积Authored 平衡准确率Perturbation 平衡准确率TypeSafe 子集一致率Qwen3-0.6BQ8_0639 MB0.4400.5280.407MiniCPM5-2BQ4_K_M1.56 GB0.6860.6930.637Qwen3.5-4BQ4_K_M3.01 GB0.8130.7660.845已发布的 Jev闭源托管服务———0.883原生 BF16 得分浏览器构建使用量化 GGUF。Jev 数字为 TypeSafe 在相同 102 行子集上的公开结果。通用决策基线冻结工作负载行数direct logits4B BF16EXL3 direct27B, 5 bpw原生 reranker4B已发布 JevAuthored 决策平衡准确率1440.8130.9580.625—WANLI平衡准确率2560.637—0.522—TypeSafe 选定子集模态一致率10220 例0.845—0.5600.883Every 判断网格准确率360.806—0.694—Every 操作防火墙组合准确率10 动作0.700—0.700—Every 代码检索Recall16 查询1.000—1.000—Every 公司知识Recall17 查询0.929—0.929—两点边界必须明确其一Jev 数字读取自 TypeSafe 公开记录项目并未运行真实 Jev 端点且对比覆盖的是能从公开产物对齐的 102 行而非 TypeSafe 报告的 711 行聚合其二Qwen3.8-27B EXL3 桥接见 exl3-bridge/README.md使用与 4B 基线相同的 144 行 authored 数据、匹配的提示词哈希、选项、直接 logits 读法与指标属于系统级质量对比而非受控的模型规模/量化消融模型家族、规模、量化、运行时全部不同且在 777 决策共享状态测试集上与钉死 4B 模型的抉择一致率为 84.43%尚未在其他质量工作负载上运行。概率校准温度缩放选项概率只有在置信度与观测准确率匹配时才有实用价值。SemIf 内置按工作负载拟合的温度缩放per-workload temperature scaling详见 docs/CALIBRATION.md工作负载原始 ECE折外校准 ECE温度Authored 决策0.0680.0381.23WANLI0.2080.0692.50Every judgments0.0500.0471.71校准不改变所选的选项WANLI 上改善显著authored 与 Every 工作负载上区间有重叠。结论务必在将要实际做决策的工作负载上做校准与验证而不是跨负载复用温度。可审计性与证据边界SemIf 把可复现落实到提交物层面自有测试集、精确评测脚本、逐行输出、模型 revision、提示词哈希、已知失败与校验和全部入库。README 强调模型权重与第三方源记录不随仓库分发上游模型保留各自许可证项目代码以 MIT 许可证 发布第三方来源清单见 THIRD_PARTY.md。文档导航docs/RESULTS.md — 质量、速度、扰动测试与声明边界docs/METHOD.md — 冻结提示词、指标与计时范围docs/REPRODUCE.md — 精确环境、钉死命令、扰动与验证docs/APPLE_SILICON.md — MPS 与可选 MLX 后端docs/CALIBRATION.md — 拟合温度、折外证据与应用exl3-bridge/README.md — 量化 27B 运行器与已提交证据demo/index.html — 交互式重放可复现的速度对比演示webgpu-demo/index.html — 纯浏览器 WebGPU 演示无需等待名单results/phase1-summary.json — 机器可读汇总benchmarks/README.md — 测试集、运行器、选择 ID 与复现命令results/raw/ — 原始结果与校验和manifests/models.json — 模型清单结语SemIf 提供了一条与生成文本再解析完全不同的决策路径把大模型的下一步 token 分布当作分类器直接消费用单次前向传播换取数量级的延迟与输出 token 节省同时以钉死的 revision、提示词哈希与逐行证据保证可复现性。它既是一个可直接运行的 CLI 工具semif-score也是一套可拆解的方法论——从输入契约、槽位校验到共享状态前缀缓存再到按工作负载校准每一层都有源码与测试支撑适合作为自建语义化 if服务的最小可信基线。【免费下载链接】SemIfSemantic ifs from open models, on a 3090 at home. Independent; not affiliated with Jev or TypeSafe.项目地址: https://gitcode.com/gh_mirrors/op/SemIf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
