AI如何“理解”你的房间?Open Reality场景报告的证据引用与Q&A grounding机制全解
AI如何“理解”你的房间?Open Reality场景报告的证据引用与Q&A grounding机制全解
Open Reality(openreality)是一个把手机视频变成“可被 AI 查询的 3D 场景”的开源项目。它最有意思的一点是:当你在页面上问“电视柜旁边有什么?”时,AI 的回答不是凭空想象,而是基于扫描得到的场景报告(Scene Report)与证据引用(EvidenceRef),经过一套 Q&A grounding(答案接地)机制校验后才输出。本文带你从零看懂这套机制:结构化的 3D 事实、关键帧证据链、对象相关性排序,以及 LLM 如何被约束得“不会编造”。
从视频到“可问答”的场景:Open Reality 的分工
先建立全局观。Open Reality 的扫描链路可以拆成三步:
- 重建:手机视频经过 VGGT-SLAM 重建出点云场景(子图 submap + 关键帧 keyframe);
- 提炼:
SceneFeatureExtractor把重建结果压缩成一份结构化“事实清单”(SceneFacts)——房间包围盒、物体清单(带世界坐标系位置)、物体两两之间的距离关系; - 表达与问答:LLM 基于这份清单 + 若干关键帧图片撰写场景报告;之后你再提问时,Q&A grounding 核心会把答案约束在这份“事实清单 + 证据帧”之内。
前两步发生在 GPU worker 上;第三步的问答甚至可以不需要 GPU——在常开的 CPU broker 上直接回答已保存场景的问题。
什么是“场景报告”:把模糊感知变成带证据的事实
从点云到结构化的 SceneFacts
场景报告的原料是 features.py 中的 SceneFeatureExtractor.extract()。它读取每个子图的世界坐标系点云与相机位姿,算出:
- 房间指标(
SceneMetrics):AABB 尺寸、轨迹长度、子图数、关键帧数; - 物体清单(
ObjectInstance):每个检测到的物体有世界坐标中心、尺寸、置信度,以及一组evidence证据引用; - 空间关系(
SpatialRelation):哪两个物体 near / medium / far,距离多少。
这些全部定义在 schemas.py 的 Pydantic 模型里,是整个系统“可审计”的基础——因为每个字段都有明确的类型与出处。
每条论断都挂着证据:EvidenceRef
这是整个设计的灵魂。EvidenceRef 只有两个核心字段:submap_id(哪个子图)和 frame_idx(第几帧)。它本质上是一个指回某张真实拍摄帧的指针:
- 报告里写“靠窗有一台笔记本电脑” → 挂上该笔记本在某个关键帧中的引用;
- Q&A 回答“电视柜旁边有绿植” → 附上能证明这一点的帧。
LLM 的文字可以被质疑,但 (submap_id, frame_idx) 可以逐帧核对。报告构建器 report.py 的 system prompt 明确要求:“Ground every claim in the provided facts or visible keyframe content; never invent objects or measurements”(每条论断必须锚定在给定事实或可见关键帧上,绝不编造)。
三层证据引用机制:关键帧、物体、空间关系
证据引用实际上分了三层,层层递进:
| 层级 | 内容 | 作用 |
|---|---|---|
| 关键帧证据 | (submap_id, frame_idx) + 图片字节 |
证明“这个物体真的出现在这里” |
| 物体证据 | 物体的世界坐标中心 + 尺寸 + 置信度 | 支撑“它在房间的什么位置” |
| 空间关系证据 | 两物体间距离 + near/medium/far 关系 | 支撑“A 旁边是 B”这类布局断言 |
关键帧不是随便挑的。keyframes.py 的 choose_frame_refs 有一套优先级:先放最新子图(扫描中“进度报告”用),再按置信度从每个物体的证据里各取一帧,最后把剩余预算均匀铺满整条拍摄时间线——而不是只从每个子图取一帧。这样报告的视觉证据覆盖整个空间,而不是只盯着进门那一段。
Q&A grounding:四道闸门拦住 AI 幻觉
当你问“沙发上放着什么?”,真正的处理核心是 app.py 中的 _grounded_scene_answer()。它用四道闸门保证答案可信:
1️⃣ 对象相关性排序:不找“精确词”,找“语义上的对”
系统不会拿问题里的词去做精确匹配。它有一个轻量词干化函数(couches→couch)+ 方向性子串匹配(whiteboard~board、tabletop~table),再叠加上下文加权:每个物体的“名字”权重最高,其次是它与别的物体的空间关系词和报告正文中提及它的句子。所以问“白板上面有什么”能命中 whiteboard,问“电视附近有什么”能命中电视的邻居。平局时回退到置信度排序(或可选的 embedding 相似度)。
2️⃣ 证据图片由模型“点单”,再经服务端核验
一个有趣的进化:早期版本总是展示“置信度 Top 3”的图片,问什么都配同样的三张图。现在的做法是 _candidate_keyframes() 从相关物体的证据里挑出一个带标签的候选菜单(每张注明 shows 了哪个物体),交给模型自己引用;_select_evidence() 只保留模型真实引用且服务端确实有字节的帧,按模型顺序展示。问的问题不同,配的证据图也不同——而且模型引用不存在的帧会被直接丢弃。
3️⃣ focus 与证据引用:白名单校验,绝不信任模型坐标
模型回答时可以给出一个 focus(让 3D 视图飞过去的目标物体)。服务端 _validate_focus() 会把它对照真实物体清单:名字必须精确存在,坐标只取库里存的世界坐标,模型自己报的任何数字一律不信。找不到 → focus=None,而不是瞎飞。
4️⃣ 单位诚实:没有 metric anchor,就不许说“米”
SLAM 重建的尺度是 up-to-scale 的。_qa_metric_grounding() 会给模型写一段“诚实条款”:未校准时,所有长度都是 relative units,禁止报出米数;只有场景做过 metric anchor 校准后,才允许换算成米。同样的规则也被 PersistedSceneAgent 用正则硬性拦截——LLM 文字里带单位的数字会被直接丢弃(见 persisted_agent.py 的 strip_metric_claims),所有可度量数字必须由代码计算后填入。
两个问答入口:扫描中实时聊,保存后无 GPU 再问
同一个 grounding 核心被两个界面共用,保证行为永远一致:
- 扫描中实时问答:
POST /api/assistant/chat基于 worker 缓存的最新报告(终版或进度版)作答,纯文本接地; - 保存后回访问答:
POST /api/scenes/<scan_id>/qa由 app.py 路由,在常开的 CPU broker 上跑——读回持久化的 facts、报告与关键帧 JPEG 作答,完全不启动 GPU。这也是“证据引用”能落地的前提:持久化层 store.py 会把报告引用的关键帧连同cloud.npz全量点云一起存下。
两个入口都返回统一的 {answer, model, degraded, focus, evidence} 结构——degraded 为 true 时说明 LLM 不可用、答案退化为纯事实版,前端能如实告知用户。
相关文件索引
| 模块 | 路径 | 说明 |
|---|---|---|
| 证据与事实模型 | schemas.py | EvidenceRef / SceneFacts / SceneReport |
| 事实提取 | features.py | 点云 → 结构化 3D facts |
| 报告构建 | report.py | 终版 / 进度版 LLM 报告 |
| 关键帧选择 | keyframes.py | 预算内去重的证据帧挑选 |
| Q&A 核心 | app.py | _grounded_scene_answer 全链路 |
| 官方文档 | server/docs/scene-report.md | 系统设计与配置项全解 |
| 测试 | test_scene_qa.py | grounding 排序与证据选择测试 |
总结
Open Reality 场景报告的本质,是把 LLM 从“看图说话”升级为“基于结构化 3D 事实作答,并随时接受举证”:
- 每条论断都挂可核对的关键帧引用(
EvidenceRef); - 问答时先做语义相关性排序,再让模型从带标签候选里自选证据图,服务端逐一核验;
- 坐标、单位、度量数字全部由代码计算,LLM 的文字带数字会被正则拦截;
- 未校准的尺度只敢说 relative units——“诚实”被写进了 system prompt 和执行层。
这套机制不只服务于网页问答:MCP 工具(npm 包 openreality-mcp)让 Claude / Codex / Cursor 也能查询同一份带证据的 3D 场景,而 core/docs/overview.md 则介绍了底层 VGGT-SLAM 重建库,供想深入 3D 视觉的同学继续探索。

