为 Android 本地 AI 制定 JSON-LD 上下文加载策略

直接回答

有效 JSON 不会自动成为 JSON-LD，有效的 JSON-LD 语法也不代表文档对应用安全或有意义。JSON parser 检查 JSON 结构；JSON-LD processor 还会解释 `@context`、扩展术语、解析引用，并可能通过 document loader 加载远程上下文。如果用户导入文件或模型生成内容包含上下文 URL，processor 可能访问该地址，也可能沿着 `@import` 继续加载。对本地或离线任务而言，这会改变可复现性和数据流边界。首先确认功能是否真的需要 JSON-LD 语义；如果只处理固定 JSON 对象，使用有界 JSON parser 和应用 schema 通常更简单。 W3C JSON-LD 1.1 语法与处理 API 定义了远程上下文、导入上下文、base URL 处理和 processor 错误。API 通过 document-loader callback 让实现控制如何读取被引用文档；它并未定义 Android 库，也未要求使用某种网络栈。上下文文档本身可能再包含远程上下文，相对 URL 按包含它的上下文文档 URL 解析。JSON-LD 1.1 的 `@import` 会先处理被导入上下文，再应用包装上下文；被导入上下文本身若再含 `@import`，就是 invalid context entry，而不是任意串联的 import 链。因此，只查看顶层的 `@context` 字符串并不能描述完整加载图。 如果任务必须严格离线，应先固定应用实际打包的 JSON-LD processor 及解析版本，再通过其支持的扩展提供显式本地 allowlist。每个允许的绝对 URL 都映射到经审核的上下文文件、版本标识和对实际字节计算的摘要。处理时拒绝映射外 URL，不回退到 HTTP、默认 loader、DNS 或浏览器缓存。如果库无法替换或控制默认 document loader，就不要声称这条路径离线。摘要只能确认提供的字节与所选记录一致；它不证明上下文语义正确、对任何输入都安全，也不代表词汇所有者背书。 把加载图当作输入数据，而不是可信声明。按实际 processor 规则解析 URL，包括相对引用；记录请求 URL、适用时的最终文档 URL、content type、摘要和 loader 决策。严格离线策略可以拒绝重定向，只服务 allowlist 中的固定字节。processor 在处理远程上下文时会忽略其中的 `@base`；loader 仍须保留正确 document URL/base 元数据，否则相对引用的解析结果会改变。上下文文件应保持小，并分别限制总字节、loader 调用总数、不同文档数量、处理深度、耗时和扩展节点数。JSON-LD API 对 remote-context 跟踪数组条目数使用 processor 定义的上限，并报告 `context overflow`，但它没有替产品选定字节或时间预算。应配置并测试真实实现，不能假设每个 processor 默认限制相同。 不要把每次远程上下文重访都称为循环错误。JSON-LD 1.1 因 scoped context 可能合法地再次加载上下文，将早期 recursive-context-inclusion error 改为 `context overflow`。处理算法跟踪 remote-context 条目，并在 processor 定义的上限处停止；该数组不保证只计算唯一 URL。另一个 `cyclic IRI mapping` 错误描述术语映射依赖循环。产品可实行更严格的封闭图策略，但应标明这是应用策略而不是 W3C 规则。通过本地字节服务上下文时，loader 必须保留原文档 URL/base 元数据以维持相对引用语义。分别限制 loader 总调用数、唯一文档数、响应字节、处理深度、耗时和扩展结果大小；URL 条目上限不能约束大响应或转换工作。固定内容摘要变化时，应视为新上下文版本并重跑夹具。 处理结果仍需受限。扩展或压缩后的内容要按应用真正使用的字段校验；上下文有效不等于它可以授权命令、文件路径、网络目标或模型操作。诊断记录可保留原始来源标识和加载轨迹，但默认不要记录私有载荷。如果上下文缺失、摘要不符、请求未知 URL、超过配置上限或内容格式错误，就明确拒绝导入且不要网络重试。只有当完整所需加载图都存在，并且所选 processor 确实配置为使用缓存时，缓存上下文才可能支持离线任务。 本文给出验证契约，不是 Cove 功能声明。现有资料不能证明 Cove 使用哪一种 JSON-LD 库、document-loader callback、上下文集合或远程获取行为。W3C 对处理语义的定义，也不能证明某个 Android 包暴露了合适的控制接口。应记录依赖坐标、解析版本，检查确切 API，并在网络阻断且加载器可观测的打包构建上测试。缺少这些证据时，行为应标为未知，不应用作产品离线宣传。

本地导入包含未知上下文 URL

用户选择的 JSON-LD 文档引用了应用外托管的上下文。之前联网测试能够完成，但在关闭无线电的旅行环境中，应用校验扩展字段前就失败。团队尚未确认实际 Android processor 是否支持可注入 loader，还是会保留默认网络 loader。

决策

确认确切 processor 版本并枚举上下文加载图；通过有版本记录的本地 allowlist 提供文档，否则不访问网络并拒绝导入。

预期结果

导入结果绑定到明确的上下文字节，或显示上下文不受支持；两种结果都不代表 Cove 已经实现该导入流程。

需要收集的证据

只有将以下证据与同一模型文件和测试运行关联起来，结论才可复核：

• JSONLD-REMOTE-CONTEXT-2026-10：远程 @context、@import、递归处理和处理器定义的上下文数量限制需要纳入加载器策略。
• RAG-01：输入解析、数据处理和后续检索或推理是不同阶段。
• ANDROID-PRIVACY-01：端侧处理不自动证明所有数据访问和网络路径均私密。

隐私声明需要数据清单和流量证据；“本地模型”标签本身不是证明。

实施流程

1. 判断是否需要 JSON-LD 语义. 写明输入用途和应用字段。如果流程只读取固定 JSON 结构，就用大小受限的 JSON parser 和应用 schema，不额外加入词汇扩展和远程上下文行为。
2. 固定实际 processor 与 loader API. 记录依赖坐标、解析版本、Android API 范围和确切 document-loader hook，并确认它能替换默认获取路径。若没有可控 loader，就把离线行为记为未知并拒绝该声明。
3. 建立封闭且有版本的上下文映射. 每个允许的绝对 URL 都保存经审核的上下文字节、版本号和摘要。按 processor 规则解析相对引用，拒绝未登记 URL 与重定向，不在后台静默下载替代内容。
4. 限制完整的递归加载图. 设置并测试总字节数、loader 调用数、不同上下文数、处理深度、扩展节点、耗时和取消上限。覆盖嵌套远程上下文、scoped-context 重载、processor overflow、cyclic IRI mapping、被导入上下文内出现 `@import` 的无效情况、重复 URL、超大响应与错误 JSON。
5. 校验结果并证明离线路径. 按应用 schema 和授权策略检查扩展结果。用网络阻断并开启 loader 追踪的实际打包构建运行；所有请求都必须从固定映射解析，否则明确失败。

让每个阶段的状态都可观察。失败信息应指出阶段、模型、运行时和恢复动作，同时避免记录用户私密内容。

验收标准

• 记录已解析 processor 及可控 loader API；默认 loader 不明时不会声称离线。
• 每个允许 URL 都对应版本化字节和已核对摘要，重定向与未知 URL 策略经过测试。
• 嵌套引用、`@import`、循环、processor overflow、字节上限、取消和错误上下文都有明确测试结果。
• JSON 语法、JSON-LD 扩展、应用校验、授权与模型行为仍作为不同主张处理。

决策对照表

需要避免的失败模式

• 不要把 JSON 能解析等同于 JSON-LD 已完成扩展或离线处理。
• 不要只盘点顶层 @context 而漏掉相对 URL、嵌套上下文和 @import。
• 不要只钉住 URL；必须记录实际提供的字节、版本、摘要和重定向策略。
• 不要假设 W3C 的文档加载接口就是某个 Android 包已提供的 API。

还要避免静默回退、版本未固定、缺少取消处理，以及把不同配置的结果混在一起下结论。失败运行也应与成功记录一并保存。

最小复现记录

发布检查表

• ☐ 主要搜索问题已回答，且没有未经支持的数字。
• ☐ 所有模型文件和运行时版本均已固定。
• ☐ 代表性任务和失败处理策略均有说明。
• ☐ 生命周期、取消、清理和回退均已测试。
• ☐ 用户内容与网络边界均有说明。
• ☐ 结论只适用于被记录的配置。
• ☐ 新增测试结果时链接到原始方法或证据。

来源与相关证据

• Android privacy and security
• W3C — JSON-LD 1.1 语法
• W3C — JSON-LD 1.1 处理算法与 API
• IETF — RFC 8259，JSON 数据交换格式

中文部署与排错专题见。奇连 AI 端侧专题。

常见问题