OpenMed GGUF Grounding RuntimeQ4_K_M 本地检索向量的导出认证与隐私安全运行时实践【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed本文围绕 OpenMed 的 GGUF Grounding Runtime完整讲解如何把本地 encoder checkpoint 导出为经过认证的Q4_K_MGGUF 嵌入产物通过 G4 合成检索门禁recall gate认证后才发布并以不导入任何 llama.cpp Python 绑定的子进程桥接方式在本地运行。读完本文你将掌握export_gguf_int4/load_gguf_grounding_embedder的完整参数用法、证据文件manifest 与 benchmark 报告的含义以及该运行时如何保证患者文本永远不出现在命令行参数、临时文件与日志中。OpenMed 是一个 Local-first 的医疗 AI 仓库临床 NER 与 HIPAA PII 脱敏、全设备端运行、支持 Apple MLX 与 Python。在 OpenMed 的落地场景中grounding将模型输出或概念锚定到可信语料/术语经常需要本地化的语义检索向量。GGUF Grounding Runtime 提供了一条可认证、可审计、失败即拒绝fail-closed的路径先导出 F16/Q8_0再外部量化 Q4_K_M最后用合成数据验证量化前后的 top-k 检索一致性全部证据落盘、加载时校验。一、定位本地 grounding 检索为什么要一份认证过的 Q4_K_MOpenMed 的 grounding 能力是文档与知识锚定的核心参见 grounding.md、export-gguf.md。在设备端或机构内网部署时embedding 模型同样必须不出网既不能把患者文本发到云服务也不能在运行期偷偷下载模型权重或拉取远程模型。GGUF Grounding Runtime 解决的关键矛盾是体积与速度INT4 量化Q4_K_M显著缩小嵌入模型体积、降低推理内存与延迟可信度量化必然带来精度损失OpenMed 不允许盲目发布量化产物——必须用合成检索语料证明Q4_K_M的 top-k 排名与 F16 父模型基本一致且输出向量完全确定。二、导出流水线总览整条流水线由OM-195 exporter llama-quantize两级构成local encoder checkpoint │ ├─ OM-195 exporter ─ model-f16.gguf and model-q8_0.gguf └─ llama-quantize ─ model-q4_k_m.ggufOM-195 exporter即 openmed/gguf/convert.py 中的convert()负责把本地 Hugging Face embedding checkpoint 导出为model-f16.ggufF16与model-q8_0.ggufQ8_0两个变体llama-quantizeOpenMed 以外部子进程方式调用用户自行构建的 llama.cpp 量化器以Q4_K_M输出类型从 F16 文件生成model-q4_k_m.gguf。依赖边界OpenMed 不下载、不克隆、不捆绑文档明确强调checkpoint、converter、quantizer 与 embedding 可执行文件必须已经存在于本地存储。OpenMed 不会自动下载模型克隆 llama.cpp 仓库把 llama.cpp 的二进制打包进 OpenMed。从源码可以印证这一点convert()要求 checkpoint 目录存在且含config.jsonconverter 路径要么显式传入要么通过LLAMA_CPP_DIR环境变量或llama_cpp_dir参数指向本地的 llama.cpp checkout见 openmed/gguf/convert.py 与_resolve_converter_path量化器与嵌入可执行文件的解析同样只在本机查找openmed/onnx/gguf_int4_export.py 的_resolve_quantizer_path会在 checkout 根目录与build/bin下查找llama-quantize、quantize、llama_quantize。三、导出与认证export_gguf_int4 的完整用法文档给出的核心调用如下它一次性完成导出 → 量化 → 合成检索认证 → 发布from openmed.onnx import export_gguf_int4 result export_gguf_int4( models/synthetic-grounding-encoder, artifacts/grounding-gguf, llama_cpp_dir../llama.cpp, embedding_binary../llama.cpp/build/bin/llama-embedding, source_model_idlocal/synthetic-grounding-encoder, ) print(result.q4_k_m_path) print(result.recall_gate.passed)export_gguf_int4的完整签名与常用参数对应 openmed/onnx/gguf_int4_export.py参数默认值说明model_path必填本地 Hugging Face checkpoint 目录须含config.json及权重/词表文件output_dir必填产物输出目录最终包含 6 个文件见下文发布产物converter_path/llama_cpp_dir二选一llama.cpp 的convert_hf_to_gguf.py直接路径或包含该脚本的 checkout 目录也可通过环境变量LLAMA_CPP_DIR提供quantizer_path/llama_cpp_dir自动解析llama-quantize可执行文件路径或经llama_cpp_dir/LLAMA_CPP_DIR解析embedding_binary/embedding_command二选一本地llama-embedding可执行路径或自定义命令序列用于量化后构建 F16/Q4_K_M 两个子进程 runner 做认证source_model_idcheckpoint 目录名写入 manifest 的稳定来源标识用于溯源timeout_seconds3600.0每次导出/量化子进程的超时秒None表示禁用embedding_timeout_seconds120.0单次 embedding 子进程超时overwriteFalse是否覆盖已存在的 OpenMed GGUF 输出文件fp16_embedder/int4_embedder自动构建可注入的 embedder 适配器测试双打或自定义回调省略时必须提供embedding_binary或embedding_commandqueries/passages内置合成语料检索认证使用的合成 query/passage默认见下top_k3检索 top-krecall_delta_tolerance0.01G4 门禁的 recall delta 容忍上限embedding_context_size/embedding_batch_size512 / 32传给 llama.cpp 的--ctx-size/--batch-sizeembedding_extra_args()附加参数但受保护参数黑名单约束见运行时防护内部执行步骤源码视角冲突检查_check_output_conflicts先检查目标目录若已有产物且未传overwriteTrue则抛FileExistsErroropenmed/onnx/gguf_int4_export.py。OM-195 导出到 staging在目标目录内创建.openmed-gguf-int4-*临时目录调用convert_gguf依次产出model-f16.gguf、model-q8_0.gguf并复制config.json、写入openmed-gguf.json清单。转换器以python converter.py model --outfile out --outtype f16|q8_0子进程方式运行openmed/gguf/convert.py。外部量化_run_quantizer以llama-quantize f16 q4 Q4_K_M方式调用并校验输出文件存在、非空且文件头为GGUF魔数openmed/onnx/gguf_int4_export.py。合成检索认证对 F16 与 Q4_K_M 两个 runner 执行certify_gguf_grounding产出 G4 门禁证据与延迟/资源指标见下一节。通过后才更新 manifest 并发布只有gate.passed True时才会把 staging 中的文件原子移动到目标目录门禁失败则抛出GgufInt4Rejectedstaged 文件不会被发布openmed/onnx/gguf_int4_export.py。嵌入 backbone 的硬性限制convert()会校验 checkpoint 的task/pipeline_tag/architectures/auto_map明确拒绝 token-classificationNER 等headllama.cpp 能跑 BERT 家族的 encoder embedding但不提供 token 标签分类头因此导出仅限 embedding / feature-extraction backbone如BertModel/AutoModel否则抛UnsupportedGgufModelErroropenmed/gguf/convert.py。四、G4 合成检索认证量化不偷偷变差认证的核心是对比 Q4_K_M 与 F16 父模型的 top-k 检索一致性。对每条合成 query计算recall_delta 1 - mean(fp16_top_k ∩ q4_k_m_top_k / top_k)fp16_top_k ∩ q4_k_m_top_k是两个模型各自命中的 top-k passage 索引集合的交集大小对所有 query 取平均后recall_delta表示量化带来的排名漂移比例默认容忍度为共享的 INT4 G4 上限0.01源码定义于 openmed/eval/quant_delta.pyINT4_RECALL_DELTA_LIMIT 0.010并作为DEFAULT_GROUNDING_RECALL_DELTA_TOLERANCE注入openmed/onnx/gguf_int4_export.py。除召回一致性外认证还要求候选模型运行两次且输出完全相同的归一化向量deterministic检查。任何缺失、畸形、非确定或超容忍度的证据都会拒绝产物向量数量与输入不匹配、向量含非数值/非有限值/维度不一致 → 抛ValueErrorQ4_K_M 两次输出不一致 →deterministicFalse门禁失败拒绝原因为Q4_K_M embedding vectors are not deterministicrecall_delta tolerance 1e-12→ 门禁失败拒绝原因为recall delta exceeds G4 tolerance。相关逻辑见 openmed/onnx/gguf_int4_export.pycertify_gguf_grounding。门禁结果对象GgufGroundingRecallGate记录了top_k、query_count、passage_count、per_query_overlap、mean_top_k_overlap、recall_delta、tolerance、deterministic、passed与rejection_reason等字段。内置合成语料不触碰临床术语认证默认使用一组虚构概念openmed/onnx/gguf_int4_export.py例如aster pyrexia、beryl cough、corin skin flare等 5 条 query 与 8 条 passage。这样既完整地压测了检索能力又保证报告、日志与测试语料中不含任何临床术语、患者文本或真实输入提示。对自定义语料grounding_fixture_sha256会对有序 query/passage 计算稳定摘要供证据链绑定。五、发布产物与证据文件一次通过的导出会在artifacts/grounding-gguf/下生成 6 个文件artifacts/grounding-gguf/ ├── config.json ├── model-f16.gguf ├── model-q8_0.gguf ├── model-q4_k_m.gguf ├── openmed-gguf.json └── gguf-grounding-benchmark.jsonopenmed-gguf.json记录Q4_K_M方案、G4 判定certified、deterministic、gate、metric、recall_delta与容忍上限、benchmark 报告路径以及认证产物的size_bytes与sha256摘要。manifest 的quantization段还记录了source_artifact: model-f16.ggufopenmed/onnx/gguf_int4_export.py。gguf-grounding-benchmark.json绑定同一产物身份artifact 的 SHA-256 与字节数包含retrievalG4 门禁完整证据per_query_overlap、mean_top_k_overlap、recall_delta、tolerance、deterministiclatencyF16 与 Q4_K_M 的p50_ms/p95_ms/p99_ms延迟摘要resources模型体积bytes/MiB与 SHA-256metadataprofile 为openmed-gguf-int4-grounding、fixture 摘要、量化方案与来源openmed/onnx/gguf_int4_export.py。加载时的 fail-closed 校验load_gguf_grounding_embedder在启动任何可执行文件之前先调用validate_gguf_int4_artifactopenmed/onnx/gguf_int4_export.py。该校验会检查model-q4_k_m.gguf、openmed-gguf.json、gguf-grounding-benchmark.json三者都存在且不是符号链接重新计算产物 SHA-256并要求 manifest、report、certification、artifact metadata 中出现的所有摘要、size_bytes、recall_delta、tolerance相互一致差异须在1e-12内校验 GGUF 文件头魔数、fixture 摘要一致性与 G4 门禁字段为 passing。任何一项不满足都会抛GgufInt4Rejected。运行时无法绕过失败或缺失的证书——测试用例也专门验证了篡改报告或替换 Q4 产物后加载必然失败见 tests/unit/onnx/test_gguf_int4_grounding.py 中test_loader_fails_closed_when_report_is_tampered、test_loader_rejects_replaced_q4_artifact。发布与回滚发布前会再次检查输出冲突防止导出期间目录被写入。当overwriteTrue时_publish_staged_bundle先把已存在的 bundle 文件移动到 staging 下的.rollback目录直到所有 staged 文件全部就位一旦中途失败如磁盘错误会把已发布的文件移回 staging、把旧文件从 rollback 恢复保证失败的替换恢复先前的输出openmed/onnx/gguf_int4_export.py。对应测试test_bundle_publish_restores_previous_outputs_on_failure验证了回滚行为。六、运行本地运行时子进程桥接与隐私防护加载与编码from openmed.onnx import load_gguf_grounding_embedder embedder load_gguf_grounding_embedder( artifacts/grounding-gguf, executable../llama.cpp/build/bin/llama-embedding, ) vectors embedder.encode([synthetic mention, synthetic concept label])load_gguf_grounding_embedder的参数包括artifact_dir、executable或command、llama_cpp_dir、timeout_seconds默认 120、context_size默认 512、batch_size默认 32、extra_args。其返回的LlamaCppEmbeddingRuntimeopenmed/onnx/gguf_embed_runtime.py是一个很小的子进程桥接层从不导入 llama.cpp 的 Python 绑定llama.cpp 始终是用户自行构建的、进程外的依赖每个输入文本经匿名标准输入管道写入子进程并以/dev/stdin作为 llama.cpp 的 prompt 文件--file /dev/stdin因此原始文本不会出现在进程参数、临时文件、stderr 或 OpenMed 日志中。实际拼接的命令包含--pooling mean --embd-output-format raw --no-escape --log-disable --file /dev/stdin并附上--ctx-size、--batch-size与--model。请求边界与输出校验运行时对请求与输出做了硬性上限常量定义于 openmed/onnx/gguf_embed_runtime.py限制项上限单次encode文本条数256MAX_EMBEDDING_TEXTS单条文本字符数32,768MAX_EMBEDDING_TEXT_CHARS单批文本总字符数1 MiBMAX_EMBEDDING_TOTAL_CHARS单条文本字节数1 MiBMAX_PROMPT_BYTES向量维度65,536MAX_EMBEDDING_DIMENSION子进程输出解析上限4 MiBMAX_EMBEDDING_OUTPUT_CHARS畸形或超限的输出会被拒绝输出解析依次尝试完整 JSON、子串 JSON键embedding/embeddings/vector/data、方括号数字序列与行内数字序列最终结果必须是单个非空、全有限数值且维度一致的向量否则抛GgufEmbeddingRuntimeError。测试覆盖了embedding: [-0.25, 0.5, 1e-1]这类 llama 风格输出与维度不一致的拒绝场景。运行时防护禁止偷偷变成联网或持久化操作桥接层有两道防线清除继承的LLAMA_ARG_*覆盖_subprocess_environment构建子进程环境时丢弃所有LLAMA_ARG_前缀变量openmed/onnx/gguf_embed_runtime.py防止父进程环境中残留的 RPC、日志、模型下载等配置悄悄影响运行拒绝受保护参数_PROTECTED_EXTRA_OPTIONS黑名单openmed/onnx/gguf_embed_runtime.py明确拒绝--rpc、--prompt、--prompt-cache*、--log-file、--log-prompts-dir、--hf-repo、--hf-file、--model*、--model-url、--binary-file、--display-prompt等选项且不支持--分隔符绕过。任何extra_args或自定义command中的受保护选项都会抛ValueError。因此运行时配置无法静默地把本地 embedding 调用变成网络化或原始 prompt 持久化操作。对应测试见 tests/unit/onnx/test_gguf_int4_grounding.py 中test_runtime_rejects_args_that_can_bypass_model_or_prompt与test_runtime_removes_inherited_llama_argument_overrides。POSIX 前提/dev/stdin 管道传输直接桥接llama-embedding要求POSIX 兼容的/dev/stdin。_stdin_prompt_path在os.name posix且/dev/stdin存在时返回该路径否则抛GgufEmbeddingRuntimeError——在不支持该私有管道传输的平台上失败关闭而不是把患者文本放进命令行参数或临时文件openmed/onnx/gguf_embed_runtime.py。七、适用边界与安全声明本文所有示例均使用合成离线数据报告的fixture_count与grounding_fixture_sha256都基于虚构语料grounding 建议是辅助性的必须经过人工核验该运行时不做任何临床决策llama.cpp 始终是用户自行构建的进程外依赖OpenMed 仓库不包含其源码或二进制若需把模型真正用于医疗场景请同时参考 docs/grounding.md、docs/export-gguf.md、docs/model-loader.md 与 docs/model-manifest.md 中的模型加载与清单约束。参考链接运行时文档docs/runtimes/gguf-grounding.mdGGUF 导出实现openmed/gguf/convert.pyQ4_K_M 导出与认证实现openmed/onnx/gguf_int4_export.py子进程桥接运行时openmed/onnx/gguf_embed_runtime.py量化 recall delta 阈值openmed/eval/quant_delta.py公开 API 导出清单openmed/onnx/init.py单元测试tests/unit/onnx/test_gguf_int4_grounding.py【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考