模型文件声明¶

使用 inspect_model_artifact（CLI：inspect-model-artifact）检查本地 GGUF v2/v3 或 safetensors 文件。检测基于内容（包括 GGUF 字节序），而非扩展名。REA 不加载模型、不解释权重、不运行推理、不导入 Python、不打开外部数据引用，也不使用网络。

不支持的 GGUF 版本仍会被拒绝。其诊断信息保留四个版本字节以及两种 UINT32 解释，并注明字节序未知，而不是从未识别的小端值推断大端。小端 v2/v3 和大端 v3 仍然支持；大端 v2 仍被拒绝。

rea inspect-model-artifact /absolute/path/model.gguf --json
rea inspect-model-artifact /absolute/path/model.safetensors --hash full --json

CLI 默认生成完整的 Evidence。如需紧凑交付并可移植地访问所有保留的观测结果：

rea inspect-model-artifact /absolute/path/model.gguf \
  --detail summary --evidence_output /absolute/path/model-evidence.json --json

身份与读取¶

默认的 hash: "header" 只读取元数据和张量目录。结果记录精确选定的路径、文件大小、头部长度、头部 SHA-256、已读取字节数和读取范围。GGUF 对齐填充不在此前缀内。artifact.sha256 和 Evidence 主体为 null：头部摘要并非对权重的承诺。不同的文件可能具有相同的头部和大小。报告的 GGUF 张量数据偏移量在存在填充时跟随对齐后的张量目录。对于在目录处结束的零张量纯元数据文件，该偏移量即目录结束位置；并不暗示存在张量载荷。部分对齐间隙会被拒绝。header_length 仍以目录结束，在任何填充之前。

hash: "full" 额外将剩余文件字节流式传入 SHA-256。它返回完整文件摘要和 Evidence 主体，同时保留相同的头部摘要。它使用有界缓冲区，不解释张量数据，但确实会读取整个文件。因此成本随文件大小增长。两种模式在完成前都会检查描述符与所选路径的身份及元数据；这能检测观测到的替换或修改，但无法检测绕过文件系统元数据检查的对抗性修改。

如果完整文件哈希在任一格式的头部已被验证后失败或被取消，部分 Evidence 会保留已解析的元数据和张量目录。头部覆盖完整；摘要和最终文件身份仍然未知。Safetensors 头部解析是原子的，因此在验证之前中断不会暴露未验证的 JSON 行。

事实与选定查询¶

GGUF 报告版本、字节序、对齐方式、类型化元数据，以及每个张量的名称、原始类型 ID、维度、相对数据偏移量、文件偏移量和推导出的字节长度。对齐方式接受所有为正的、八的倍数的 UINT32 值，包括非二的幂。验证通过后，部分 Evidence 会保留显式对齐；默认对齐在元数据完成后变为已知。取消操作会保留已完成的声明，但其摘要未知且最终文件身份未经验证。元数据键保留其拼写，并使用由点、下划线或连字符分隔的小写 ASCII 字母数字组件；标准数字组件如 general.base_model.0.name 会被保留。连字符组件因兼容已发布的 llama.cpp v0.7.0 写入器而保留，该写入器会生成诸如 gpt-oss.context_length 和 wavtokenizer-dec.context_length 的键；当前 GGUF 规范 将 general.architecture 值限制为字母和数字。这记录了与书面限制相冲突的生成器输出，而非声称规范允许连字符。参见固定的 WAVTOKENIZER_DEC 和 GPT_OSS 架构名称、上下文长度键模板 以及 写入器方法。标量元数据完整。数组具有声明的元素类型、数量以及每个数组最多八个预览元素，并带有显式的 preview_complete 标志。这包括分词器词汇表：省略的值不会静默表示为完整数组。字符串为 UTF-8；64 位整数元数据和所有形状维度使用十进制字符串，不进行舍入。非有限浮点元数据使用 NaN、+Infinity 或 -Infinity，并带有其声明的浮点类型；负零为 "-0"。未知张量类型保留其数字 ID 和 null 字节长度；受影响的每类型和总体字节总计仍然未知。

Q8_1（类型 ID 9）有两种已发布的布局：llama.cpp b1500 中每 32 个元素 40 字节，以及固定的 现代 ggml 布局 中每 32 个元素 36 字节。两者均使用 GGUF v3 和量化版本 2，因此这些声明不会选择存储布局。REA 保留已知类型、形状、参数数量和起始偏移量，并带有 byte_length: null、storage_validation: "unknown"、部分存储/范围覆盖，以及对非空 Q8_1 张量的显式限制。受影响处的每类型和总体字节总计仍然未知。填充、下一个张量的偏移量和文件大小无法确定布局；保留的查询保持同样的不确定性。空的 Q8_1 张量仍然具有推导出的零字节长度，并且已知的 32 元素行块约束仍然强制执行。

K-quantization ID 10–15 也具有不兼容的已发布布局。b1500 构建选项 LLAMA_QKK_64 选择 GGML_QKK_64；同一发布的默认版本和 b3001 使用 256 元素块。b1500 结构 给出了这些源自源代码的大小：

两个构建版本都写入 GGUF v3 和量化版本 2。量化器 直接从所选的 llama_ftype 写入 general.file_type，而不对 K64 构建选项进行编码。GGML_QNT_VERSION_FACTOR 在头文件中定义，但此 GGUF 序列化路径并不使用它。全局文件类型也无法标识单个张量类型：量化器会保留未选中的张量。写入器将每个负载填充 到默认的 32 字节对齐；最后一列说明了为什么即使是相同的文件范围也无需区分这些布局。

REA 保留每个 K 类型的名称，并强制使用通用的 64 元素行倍数，但这并未建立存储块大小。非空的 K 张量长度及受影响的总数现在未知，包括常见的现代文件。空的 K 张量仍然具有推导出的零字节存储。

整数 ID 也在每次添加 IQ 类型时发生了移位。以下已发布的 ggml.h 快照均声明为 GGUF v3 和量化版本 2：

上游 PR 6050 后来明确固定了整数值。现代 ID 16–23 分别表示 IQ2_XXS、IQ2_XS、IQ3_XXS、IQ1_S、IQ4_NL、IQ3_S、IQ2_S 和 IQ4_XS。因此每个 ID 16–25 都有多种已发布的含义。REA 保留其数字 type_id，对 type 使用 AMBIGUOUS_<id>，并在限制中记录已发布的候选名称。非空字节长度未知。空的声明仍然推导出零字节存储，但其文本标识仍然模糊。类型过滤器与报告的 AMBIGUOUS_<id> 标签匹配。ID 26 在这些快照中保持为 I32；后来的稳定条目保留其现有解释。本次审计并未确立与每个生产者分支或未来修订版的兼容性。

清单不会从模型名称、全局文件类型、填充或猜测的生产者来源中选择历史布局。源代码修订版连同其构建配置可以确立外部布局事实；这些头文件不携带该标识，且 REA 当前没有布局选择输入。编写的回归测试夹具使用上述来自源代码推导的大小；未运行历史可执行文件。

Safetensors 报告头部范围、精确的字符串 __metadata__ 值、dtype、形状和声明的数据范围。空的 __metadata__ 被视为已省略；在读取器的 32 层 JSON 嵌套限制内，张量条目上的未知字段会被忽略，同时必需的 dtype、形状和数据偏移量仍会被验证。JSON 重复键、无效的 UTF-8、文件外范围、重叠、间隙、尾部未索引数据以及已知的 dtype/形状字节长度矛盾，都会以类型化的 file_format_rejected 约束被拒绝（公共代码 target_unavailable，类别 unsupported_target）。缺失、非常规或无法使用的所选路径同样是 target_unavailable；对有效选择的主机 I/O 或资源故障（如 EMFILE 或 EIO）则属于 execution_failure，并在 details.diagnostics 中记录路径和原因。支持空张量和标量形状。读取器将形状维度保留为精确的无符号 64 位值，包括当零范围使存储为空时超过 JavaScript 安全整数范围的值。形状乘积按声明顺序检查，与64 位上游读取器一致；后面的零不会消除先前的乘积溢出。实际文件和数据的偏移量仍必须符合精确的主机偏移精度。打包的亚字节类型需要完整的字节存储。未知的 dtype 保留声明的范围和显式限制，即形状到存储的验证不可用。每个张量记录 storage_validation: "consistent" | "unknown"；当无法检查该一致性时，coverage.storage_sizes 仍保持部分状态。张量过滤器接受这些 storage_validation 状态，与 dtype 或名称无关。

参数计数和按类型统计的总数是从声明中派生的，而非对有效参数或推理行为的度量。共享或重复的权重不会被去重。GGUF 维度保留其原始的 fastest-first 顺序；safetensors 形状保留 JSON 顺序。Safetensors 张量行使用名称顺序；GGUF 行使用目录顺序。索引标识的是其集合和头部摘要中的声明，而非张量内容或跨版本匹配。GGUF 支持零范围和标量形状，最多四个维度；已知的量化类型仍要求第一维度包含完整块。

MCP 默认返回紧凑摘要：包含计数、选定的简短标题元数据、聊天模板存在性（默认或具名模板内容）以及派生总计。仅有名称的 tokenizer.chat_templates 清单不能确立模板内容。完整的类型直方图和所有行仍保留在完整的 Evidence 中。标题元数据使用短键/类型和标量值；长值或复合值仍可通过显式元数据查询获取。使用返回的 parent_evidence_id：

{
  "source": {
    "kind": "retained-evidence",
    "evidence_id": "<parent_evidence_id>"
  },
  "view": {
    "kind": "model-artifact",
    "collection": "tensors",
    "names": ["token_embd.weight", "output.weight"],
    "fields": ["name", "type", "shape", "file_offset", "byte_length"],
    "offset": 0,
    "limit": 32
  }
}

若要在初始检查中回答已知问题，请将不带 kind 的相同选择作为 inspect_model_artifact 的可选 view 传入，例如 {"path":"/absolute/path/model.gguf","view":{"collection":"tensors","names":["token_embd.weight"],"fields":["type","shape","file_offset"]}}。这将返回一个包含紧凑模型上下文的所选页面，并保留完整的源 Evidence，从而避免再次调用工具。view 要求交付摘要；完整详情与选择会被视为冲突选项而拒绝。CLI 使用 --view '{"collection":"tensors","names":["token_embd.weight"]}' 搭配 --detail summary --evidence_output FILE。

如需更多页面，请使用上述历史查询对象调用 inspect_analysis_view。collection: "metadata" 接受精确的 keys、索引、字段和分页；可用于 tokenizer.chat_template 或分词器数组预览。collection: "types" 对派生的存储和参数总计进行分页，并接受精确的 types。张量页面同样接受 types。过滤器取交集；省略过滤器表示所有已记录行，空数组表示无匹配。每一行都保留其源范围内的索引。名称、键和类型标签遵循字段选择；fields: [] 仅返回索引。省略字段则返回所有已记录列。紧凑警告使用共享的有界视图预算，并在消息被省略时链接到完整的父级 Evidence。页面偏移量计算过滤后的匹配项，而行索引保留其原始范围。每个页面都携带源标识、头部覆盖范围、数组省略、未知项及父级 Evidence 链接。

页面读取的是历史保留事实，无需重新打开模型。完整 Evidence 也可以通过 source: {"kind": "evidence-file", "path": "/absolute/path/model-record.json"} 以内联方式或作为单条经过认证的 Evidence JSON 记录提供。CLI Evidence 捆绑包包含 records 数组；在使用保留查询之前，请使用 import_evidence_bundle 导入捆绑包，或将一条完整记录保存为独立的 Evidence 文件。捆绑包不是单条 Evidence 记录。会话持有已验证的索引，直到该 Evidence 被释放；不存在实时文件结果缓存或自动新鲜度声明。导入的报告必须保留位置索引以及唯一的名称、键和类型标识；格式错误的报告会在索引之前返回类型化输入错误。

边界与不支持的输入¶

读取器每个提供者仅允许一次活动检查。它强制执行 100,000,000 字节的头部上限（safetensors 将其声明的 JSON 字节与固定的八字节长度前缀分开计数；GGUF 计数完整头部），并在保留行或展开字符串之前设置独立的 32 MiB 保留表示预算。数值乘积使用精确整数运算。GGUF 遵循其四维张量布局，并将元数据数组嵌套限制为 32 层。资源拒绝是类型化的，而非作为完整的空清单返回。取消会加入描述符终结流程；失败的清理仍由持有者保留以供重试。

不支持 PyTorch pickle 和 ZIP 模型反序列化；请使用可信的外部工作流进行转换，并提供 GGUF 或 safetensors。ONNX、TFLite、Core ML、模型执行和转换不在本操作范围内。

格式参考：GGUF specification、 ggml tensor layouts、 safetensors format。