add_resource 函数在处理目录时是否会刻意将嵌套结构展平？

[JuLian1130]

我们在 0.24 版上，用内部有目录层级结构的路径测试add_resource，发现保存后的文件把嵌套结构展平了。
不知道这是预期行为还是 bug？
我看到 #83
有‘目录间的组织关系（papers/、notes/、src/）与原始目录一致，单个文档（如 transformer.pdf）被 Parser 展开为子目录。’的设计。
把嵌套结构展平似乎在维护文档摘要时有更高的效率。但是有时用户的输入文档本来就是严格分类的。展平后丢失了目录层级结构本身的语义信息。
如果是预期结果，但我又想保留层级，推荐的做法是什么？

[r266-tech]

Great question! This is intentional design behavior, not a bug.

Why flattening happens

When add_resource processes a directory, OpenViking's parser expands each document into a content node, and the storage layer normalizes all nodes into a flat namespace. This is a deliberate tradeoff: flat structures are faster for retrieval (no need to traverse hierarchy during search), and the semantic meaning OpenViking cares about is document content + metadata, not folder organization.

How to preserve hierarchical semantics

If your directory structure carries meaningful categorization, you have a few options:

Option 1: Encode hierarchy in metadata
Inject the directory path as metadata when calling add_resource, so the hierarchy becomes queryable:

viking.add_resource("papers/nlp/", metadata={"category": "nlp", "path_prefix": "papers/nlp"})

Then filter by metadata at retrieval time.

Option 2: Use separate namespaced resources
Call add_resource separately per subdirectory with a descriptive name prefix, so the hierarchy is reflected in the resource names themselves.

Option 3: Preprocess documents
Before ingestion, inject the file path into each document's front matter or content header — OpenViking preserves this metadata through indexing, keeping the hierarchical semantics accessible during search.

The core insight: OpenViking's flat node model trades structural fidelity for retrieval efficiency. If hierarchy is semantically important for your use case, encoding it explicitly in metadata is the recommended approach rather than relying on folder structure implicitly.

Hope this helps! Feel free to follow up if you have more questions.

[JuLian1130]

感谢回答，但是我有几个问题。
Option 1: 即使传入metadata参数，似乎在向量库也无法被用到。所以这个字段真的有用吗？
Option 2: 回答的意思是多级目录拼成一个目录名吗？但是系统怎么理解到这是多级目录呢？而且，如果是 a/b/c/d 这样的目录结构，这样操作也无法对 a、b、c 这些级别生成摘要。
Option 3: 这个只能做向量召回时根据目录名产生微弱的语义信号，还是要大量召回后在过滤。这样系统的目录递归检索的特性意义就不是太大了。

[r266-tech]

你指出的三点都是有效的批评，我来诚实回答。

---

Option 1：metadata 字段

你是对的。LanceDB 支持存储 metadata 作为附加列，也支持 WHERE 过滤——但 OpenViking 当前的 find() 和 search() API 并未向调用者暴露 metadata 过滤参数。所以在现有实现下，metadata 存进去了但检索时用不上，几乎没有实际用途。

这是一个值得提 Issue 的点：retrieval API 应该支持按 metadata 字段过滤。

Option 2：多级目录路径编码

你的分析是正确的。把 a/b/c/d 编码成 a_b_c_d 对系统来说只是一个普通字符串，embedding 模型最多从中感知到一点路径语义，但：

• 无法做 a/b/* 的前缀范围查询
• a、a/b、a/b/c 中间层没有摘要
• 随着层级加深，方案完全不可扩展

我之前的回答在这一点上给了一个误导性的"解决方案"，实际上只是很弱的 workaround。

Option 3：大量召回后过滤

你的理解是正确的。当前目录级检索只能靠语义信号（目录名在 embedding 中的权重）做模糊相关性，或者大量召回后在应用层过滤。

---

诚实的结论

OpenViking 当前的 add_resource 设计是为扁平语义检索优化的，不支持真正的层级命名空间。 如果使用场景需要按目录树精确范围查询、中间层节点摘要或递归子树检索，现有设计确实无法满足——这是一个真实的设计缺口。

目前最实际的路径：

1. 使用 OpenViking 的 URI 组织（viking://resources/section_a/）作为不同召回空间——这是当前有效的命名空间隔离
2. 如果层级检索是核心需求，建议向 OpenViking 提 Issue/PR，在 resource schema 中加入显式的 parent_uri 字段和递归查询 API

感谢你的追问，这些问题确实暴露了我之前回答的局限性。