Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: clarify resource API field names (#2107)

Qin Haojie578148a85597
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index e980e319f..7934d4500 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -108,7 +108,7 @@ Resource incremental updates are implemented via the **Watch Task** mechanism:
### add_resource
-Add a resource to the knowledge base. Supports local files/directories, URLs, and other sources.
+Add a resource to the knowledge base. The SDK supports local files/directories, URLs, and other sources. Raw HTTP calls accept remote URLs through `path` or uploaded local files through `temp_file_id`.
#### 1. API Implementation Overview
@@ -136,8 +136,8 @@ This endpoint is the core entry point for resource management, supporting adding
|-----------|------|----------|---------|-------------|
| path | string | No | - | Remote resource URL (HTTP/HTTPS/Git). Mutually exclusive with `temp_file_id` |
| temp_file_id | string | No | - | Temporary upload file ID. Mutually exclusive with `path` |
-| to | string | No | - | Target Viking URI (exact location). Mutually exclusive with `parent` and `parent_auto_create` |
-| parent | string | No | - | Parent Viking URI (resource placed under this directory). Mutually exclusive with `to` and `parent_auto_create` |
+| to | string | No | - | Target Viking URI (exact location). Mutually exclusive with `parent` |
+| parent | string | No | - | Parent Viking URI (resource placed under this directory). Mutually exclusive with `to` |
| create_parent | bool | No | False | Automatically create parent directory if it does not exist (server-side flag) |
| reason | string | No | "" | Reason for adding the resource (for documentation and relevance improvement, experimental feature) |
| instruction | string | No | "" | Processing instructions for semantic extraction (experimental feature) |
@@ -153,12 +153,13 @@ This endpoint is the core entry point for resource management, supporting adding
| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
**Additional Notes**:
-- `to`, `parent`, and `parent_auto_create` cannot be specified together
+- `to` and `parent` cannot be specified together. Use `create_parent=true` with `parent` when the parent directory should be created automatically.
- `path` and `temp_file_id` cannot be specified together
- Raw HTTP calls for local files require first uploading via [temp_upload](#temp_upload) to obtain `temp_file_id`
- When `to` is specified and the target already exists, triggers incremental update
- `watch_interval` only takes effect when `to` is provided
- For local directory inputs, scanning respects `.gitignore` files (root and nested) with standard Git semantics; `ignore_dirs`, `include`, and `exclude` further refine what is ingested.
+- To create or update plain text directly, use [content/write](03-filesystem.md#write) instead of `add_resource`. Semantic processing and embeddings are refreshed automatically after resource ingestion and content writes.
#### 3. Usage Examples
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index d7f3ddbdc..233a5f6ed 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -21,6 +21,7 @@ Behavior notes:
- Creating a new file through WebDAV triggers OpenViking semantic generation for that file path.
- Replacing an existing file through WebDAV refreshes related semantics and vectors, same as `write()`.
+- `PUT` does not create parent collections automatically. Create missing directories with `MKCOL` first.
- User-created dot-directories and dot-files remain visible unless they match one of the reserved internal filenames above.
## API Reference
@@ -179,7 +180,7 @@ Update an existing file, or create a new one when `mode="create"`, and automatic
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
-| uri | str | Yes | - | Existing file URI |
+| uri | str | Yes | - | File URI to write. For `mode="create"`, the file must not already exist |
| content | str | Yes | - | New content to write |
| mode | str | No | `replace` | `replace`, `append`, or `create` |
| wait | bool | No | `false` | Wait for background semantic/vector refresh |
diff --git a/docs/en/concepts/04-viking-uri.md b/docs/en/concepts/04-viking-uri.md
index aaf628730..50d1477ed 100644
--- a/docs/en/concepts/04-viking-uri.md
+++ b/docs/en/concepts/04-viking-uri.md
@@ -323,7 +323,7 @@ Each directory may contain special files:
```python
# Add resources only to resources scope
-await client.add_resource(url, target="viking://resources/project/")
+await client.add_resource(url, to="viking://resources/project/")
# Skills go to agent scope
await client.add_skill(skill) # Automatically to viking://agent/skills/
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 3fa747bf0..15c6a17e3 100644
--- a/docs/en/faq/faq.md
+++ b/docs/en/faq/faq.md
@@ -166,7 +166,7 @@ The SDK constructor only accepts `url`, `api_key`, and `path` parameters. Other
await client.add_resource(
"./document.pdf",
reason="Project technical documentation", # Describe resource purpose to improve retrieval quality
- target="viking://resources/docs/" # Specify storage location
+ to="viking://resources/docs/" # Specify storage location
)
# Add web page
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index b0348daaf..2745cede7 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -107,7 +107,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
#### 1. API 实现介绍
-此接口是资源管理的核心入口,支持多种来源的资源添加,并可选择等待语义处理完成。
+此接口是资源管理的核心入口,支持多种来源的资源添加,并可选择等待语义处理完成。SDK 可直接处理本地文件/目录、URL 等来源;直接 HTTP 调用只通过 `path` 接受远程 URL,或通过 `temp_file_id` 引用先上传的本地文件。
**处理流程**:
1. 识别资源来源(URL 或上传的临时文件)
@@ -131,8 +131,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
|------|------|------|--------|------|
| path | string | 否 | - | 远程资源 URL(HTTP/HTTPS/Git)。与 `temp_file_id` 二选一 |
| temp_file_id | string | 否 | - | 临时上传文件 ID。与 `path` 二选一 |
-| to | string | 否 | - | 目标 Viking URI(精确位置)。与 `parent` 和 `parent_auto_create` 互斥 |
-| parent | string | 否 | - | 父级 Viking URI(资源放入此目录下)。与 `to` 和 `parent_auto_create` 互斥 |
+| to | string | 否 | - | 目标 Viking URI(精确位置)。与 `parent` 互斥 |
+| parent | string | 否 | - | 父级 Viking URI(资源放入此目录下)。与 `to` 互斥 |
| create_parent | bool | 否 | False | 如果父目录不存在,自动创建父目录(服务端标志) |
| reason | string | 否 | "" | 添加资源的原因(用于文档化和相关性提升,实验特性) |
| instruction | string | 否 | "" | 语义提取的处理指令(实验特性) |
@@ -148,10 +148,11 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
**补充说明**:
-- `to`、`parent` 和 `parent_auto_create` 都可用于指定目标路径,但不能同时使用;指定 `to` 且目标已存在时,触发增量更新。
+- `to` 和 `parent` 不能同时使用;如果使用 `parent` 且希望父目录不存在时自动创建,请传 `create_parent=true`。指定 `to` 且目标已存在时,触发增量更新。
- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp_upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
- `watch_interval` 仅在指定 `to` 时生效
- 本地目录输入会遵循 `.gitignore`(根目录和子目录,标准 Git 语义);`ignore_dirs`、`include`、`exclude` 会在此基础上进一步过滤。
+- 如果要直接创建或更新纯文本内容,请使用 [content/write](03-filesystem.md#write),不要使用 `add_resource`。资源导入和内容写入后都会自动刷新语义与 embedding。
#### 3. 使用示例
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index 8d27c2a67..682518ad3 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -21,6 +21,7 @@ Phase 1 有意把范围控制得比较小:
- 通过 WebDAV 新建文件时,会对该文件路径触发 OpenViking 的语义生成。
- 通过 WebDAV 覆盖已有文件时,会像 `write()` 一样刷新相关语义和向量。
+- `PUT` 不会自动创建父目录。缺失的目录需要先用 `MKCOL` 创建。
- 用户自己创建的点目录或点文件仍然可见,只有上面列出的保留内部文件名会被隐藏。
## API 参考
@@ -179,7 +180,7 @@ openviking read viking://resources/docs/api.md
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
-| uri | str | 是 | - | 已存在文件的 URI |
+| uri | str | 是 | - | 要写入的文件 URI。`mode="create"` 时目标文件必须不存在 |
| content | str | 是 | - | 要写入的新内容 |
| mode | str | 否 | `replace` | `replace`、`append` 或 `create` |
| wait | bool | 否 | `false` | 是否等待后台语义/向量刷新完成 |
diff --git a/docs/zh/concepts/04-viking-uri.md b/docs/zh/concepts/04-viking-uri.md
index 852d4b512..090992f3c 100644
--- a/docs/zh/concepts/04-viking-uri.md
+++ b/docs/zh/concepts/04-viking-uri.md
@@ -319,7 +319,7 @@ overview = await client.overview("viking://resources/docs/")
```python
# 资源只添加到 resources 作用域
-await client.add_resource(url, target="viking://resources/project/")
+await client.add_resource(url, to="viking://resources/project/")
# 技能添加到 agent 作用域
await client.add_skill(skill) # 自动到 viking://agent/skills/
diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.md
index dc11eeebb..a1cf0d346 100644
--- a/docs/zh/faq/faq.md
+++ b/docs/zh/faq/faq.md
@@ -165,7 +165,7 @@ SDK 构造函数仅接受 `url`、`api_key`、`path` 参数。其他配置(emb
await client.add_resource(
"./document.pdf",
reason="项目技术文档", # 描述资源用途,提升检索质量
- target="viking://resources/docs/" # 指定存储位置
+ to="viking://resources/docs/" # 指定存储位置
)
# 添加网页
diff --git a/openviking/eval/datasets/local_doc_example_glm5.jsonl b/openviking/eval/datasets/local_doc_example_glm5.jsonl
index 9d731f54e..0c7363d11 100644
--- a/openviking/eval/datasets/local_doc_example_glm5.jsonl
+++ b/openviking/eval/datasets/local_doc_example_glm5.jsonl
@@ -1,7 +1,7 @@
{"question": "OpenViking 的核心定位是什么?与传统向量数据库(如 Milvus、Pinecone)有何本质区别?", "files": ["OpenViking/README.md", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "OpenViking 是一个专门为 AI Agent 设计的开源上下文数据库(Context Database)。与传统向量数据库的本质区别在于:\n\n1. **设计范式不同**:OpenViking 采用\"文件系统范式\"统一管理记忆、资源和技能,而传统向量数据库仅提供扁平的向量存储。\n\n2. **解决的问题不同**:OpenViking 解决 Agent 开发中的五大挑战:上下文碎片化、上下文需求激增、检索效果差、上下文不可观察、记忆迭代受限。传统向量数据库主要解决向量检索问题。\n\n3. **功能特性不同**:\n - 分层上下文加载(L0/L1/L2三层结构)显著降低 Token 消耗\n - 目录递归检索结合目录定位与语义搜索\n - 可视化检索轨迹,支持调试\n - 自动会话管理,实现上下文自我迭代\n\n4. **架构层次**:OpenViking 包含 Client、Service、Retrieve、Session、Parse、Compressor、Storage 等多层架构,而传统向量数据库主要是存储和检索层。"}
{"question": "分层记忆设计(L0 抽象层、L1 概述层、L2 内容层)的设计初衷是什么?三层之间如何保持语义一致性?", "files": ["OpenViking/docs/en/concepts/03-context-layers.md"], "answer": "分层记忆设计的初衷是平衡检索效率与内容完整性。\n\n**三层结构说明**:\n- **L0(Abstract)**:最简洁的内容表示,约100 tokens,用于向量检索和快速过滤,存储在 `.abstract.md` 文件中。\n- **L1(Overview)**:约2k tokens的综合摘要,包含导航指引,用于重排序和理解访问方式,存储在 `.overview.md` 文件中。\n- **L2(Detail)**:完整原始内容,无 token 限制,仅在确认需要时加载。\n\n**语义一致性保证**:\n1. **生成机制**:SemanticProcessor 采用自底向上的方式遍历目录,为每个节点生成 L0/L1,确保层级间的语义关联。\n2. **统一来源**:所有层级都源自同一份原始内容,L0 是 L1 的精炼,L1 是 L2 的结构化摘要。\n3. **渐进式加载**:检索时先通过 L0 定位,再通过 L1 确认相关性,最后按需加载 L2,保证语义传递。\n\n**API 支持**:\n```python\nabstract = client.abstract(\"viking://resources/docs/auth\") # L0\noverview = client.overview(\"viking://resources/docs/auth\") # L1\ncontent = client.read(\"viking://resources/docs/auth/oauth.md\") # L2\n```"}
{"question": "六种记忆类别(profile、preferences、entities、events、cases、patterns)的划分依据是什么?在实际应用中如何自动分类?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/openviking/session/memory_extractor.py"], "answer": "六种记忆类别基于人类认知模式的简化和工程考量进行划分。\n\n**划分依据**:\n\n**用户记忆**:\n- **profile**:用户基本信息,存储在 `user/memories/.overview.md`\n- **preferences**:用户偏好,按主题聚合,存储在 `user/memories/preferences/`\n- **entities**:实体记忆(人、项目、概念),存储在 `user/memories/entities/`\n- **events**:事件记录(决策、里程碑),存储在 `user/memories/events/`\n\n**Agent 记忆**:\n- **cases**:学习到的案例,存储在 `agent/memories/cases/`\n- **patterns**:学习到的模式,存储在 `agent/memories/patterns/`\n\n**自动分类机制**:\nMemoryExtractor 通过 LLM 自动提取和分类记忆。流程如下:\n1. 格式化会话消息\n2. 调用 `compression.memory_extraction` 提示词模板\n3. LLM 返回结构化的记忆候选,包含 category、abstract、overview、content\n4. 根据 category 写入对应目录\n\n**更新策略**:\n- profile、preferences、entities:可追加更新\n- events、cases、patterns:不更新,作为历史记录"}
-{"question": "OpenViking 如何支持多 Agent 协作场景?不同 Agent 之间的记忆如何隔离与共享?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "OpenViking 通过 URI 命名空间和作用域设计支持多 Agent 协作。\n\n**记忆隔离机制**:\n1. **URI 命名空间**:\n - `viking://user/memories/` - 用户级记忆\n - `viking://agent/memories/` - Agent 级记忆\n - `viking://resources/` - 共享资源\n - `viking://agent/skills/` - Agent 技能\n\n2. **作用域划分**:\n - **User Scope**:用户相关的 profile、preferences、entities、events\n - **Agent Scope**:Agent 学习到的 cases、patterns\n - **Resources Scope**:共享的知识库\n\n**记忆共享机制**:\n1. **资源层共享**:所有 Agent 可以访问 `viking://resources/` 下的共享知识库。\n2. **用户记忆共享**:同一用户的不同 Agent 可以共享 `viking://user/memories/` 下的用户偏好和实体记忆。\n3. **关系管理**:通过 `.relations.json` 建立资源间的关联关系,支持跨 Agent 的上下文关联。\n\n**实际应用**:\n```python\n# Agent A 添加资源\nclient.add_resource(\"./docs/api.pdf\", target=\"viking://resources/api\")\n\n# Agent B 可以检索到\nresults = client.find(\"API usage\", target_uri=\"viking://resources/\")\n```"}
+{"question": "OpenViking 如何支持多 Agent 协作场景?不同 Agent 之间的记忆如何隔离与共享?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "OpenViking 通过 URI 命名空间和作用域设计支持多 Agent 协作。\n\n**记忆隔离机制**:\n1. **URI 命名空间**:\n - `viking://user/memories/` - 用户级记忆\n - `viking://agent/memories/` - Agent 级记忆\n - `viking://resources/` - 共享资源\n - `viking://agent/skills/` - Agent 技能\n\n2. **作用域划分**:\n - **User Scope**:用户相关的 profile、preferences、entities、events\n - **Agent Scope**:Agent 学习到的 cases、patterns\n - **Resources Scope**:共享的知识库\n\n**记忆共享机制**:\n1. **资源层共享**:所有 Agent 可以访问 `viking://resources/` 下的共享知识库。\n2. **用户记忆共享**:同一用户的不同 Agent 可以共享 `viking://user/memories/` 下的用户偏好和实体记忆。\n3. **关系管理**:通过 `.relations.json` 建立资源间的关联关系,支持跨 Agent 的上下文关联。\n\n**实际应用**:\n```python\n# Agent A 添加资源\nclient.add_resource(\"./docs/api.pdf\", to=\"viking://resources/api\")\n\n# Agent B 可以检索到\nresults = client.find(\"API usage\", target_uri=\"viking://resources/\")\n```"}
{"question": "会话的生命周期是如何管理的?commit_session 后记忆如何被持久化和索引?", "files": ["OpenViking/docs/en/concepts/08-session.md"], "answer": "会话生命周期遵循:创建 → 交互 → 提交 的模式。\n\n**生命周期管理**:\n1. **创建**:`session = client.session(session_id=\"chat_001\")`\n2. **交互**:\n - `session.add_message(role, parts)` - 添加消息\n - `session.used(contexts, skill)` - 记录使用的上下文/技能\n3. **提交**:`session.commit()` - 归档并提取记忆\n\n**commit 后的持久化流程**:\n1. **归档流程**:\n - 增加 compression_index\n - 复制当前消息到归档目录\n - 生成结构化摘要(LLM)\n - 清空当前消息列表\n\n2. **记忆提取**:\n - MemoryExtractor 从消息中提取 6 类记忆\n - 生成 L0(abstract)和 L1(overview)\n - 写入对应的 VikingFS 目录\n\n3. **索引构建**:\n - 对新生成的记忆内容进行向量化\n - 写入 Vector Index 支持语义检索\n\n**消息结构**:\n- Message:id、role、parts、created_at\n- Part 类型:TextPart、ContextPart、ToolPart\n\n**返回结果**:\n```python\n{\n \"status\": \"committed\",\n \"memories_extracted\": 5,\n \"active_count_updated\": 2,\n \"archived\": True\n}\n```"}
{"question": "技能系统的设计理念是什么?与传统的 Function Calling 或 Tool Use 有何不同?", "files": ["OpenViking/docs/en/api/04-skills.md", "OpenViking/docs/en/concepts/02-context-types.md"], "answer": "技能系统的设计理念是将 Agent 可调用的能力统一管理,与 Function Calling 的区别在于存储和检索方式。\n\n**设计理念**:\n1. **统一存储**:技能作为上下文的一种类型,与记忆、资源采用相同的存储范式。\n2. **分层描述**:技能同样有 L0(简短描述)、L1(详细概述)、L2(完整定义)三层结构。\n3. **语义检索**:支持通过自然语言描述检索相关技能。\n\n**与传统 Function Calling 的区别**:\n| 维度 | OpenViking Skills | Function Calling |\n|------|-------------------|-----------------|\n| 存储方式 | 文件系统 + 向量索引 | 代码定义 |\n| 检索方式 | 语义检索 + 目录定位 | 精确匹配 |\n| 描述层次 | L0/L1/L2 三层 | 单层描述 |\n| 上下文关联 | 支持关系管理 | 无 |\n\n**存储位置**:\n```\nviking://agent/skills/{skill-name}/\n├── .abstract.md # L0: 简短描述\n├── SKILL.md # L1: 详细概述\n└── scripts # L2: 完整定义\n```\n\n**支持的数据格式**:\n1. Dict(Skill 格式)\n2. Dict(MCP Tool 格式)- 自动检测并转换\n3. String(SKILL.md 内容)\n4. Path(文件或目录)"}
{"question": "OpenViking 适合哪些具体的应用场景?例如:长期记忆助手、知识库问答、代码助手等场景的适配性如何?", "files": ["OpenViking/README.md", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "OpenViking 专为 AI Agent 设计,适合需要长期上下文管理的场景。\n\n**核心应用场景**:\n\n1. **长期记忆助手**:\n - 自动从会话中提取用户偏好、实体记忆\n - 支持跨会话的记忆累积和检索\n - 适配性:★★★★★(核心场景)\n\n2. **知识库问答**:\n - 支持 PDF、Markdown、HTML 等多种文档格式\n - 分层检索提高效率和准确性\n - 适配性:★★★★★(核心场景)\n\n3. **代码助手**:\n - 支持代码仓库解析(Git/Zip)\n - 自动过滤非代码目录(.git、node_modules)\n - 语义检索代码片段\n - 适配性:★★★★☆(支持代码解析)\n\n4. **多模态助手**:\n - 支持图片、视频、音频处理\n - VLM 描述和向量化\n - 适配性:★★★★☆(需要 VLM 支持)\n\n5. **企业知识管理**:\n - 统一管理文档、代码、技能\n - 支持关系管理和关联检索\n - 适配性:★★★★★(核心场景)\n\n**场景适配关键能力**:\n- 分层上下文加载:降低 Token 成本\n- 目录递归检索:提高检索精度\n- 可视化检索轨迹:便于调试优化\n- 自动会话管理:实现记忆迭代"}
@@ -9,7 +9,7 @@
{"question": "OpenViking 与主流 RAG 框架(LlamaIndex、LangChain)的集成方式是什么?是否可以无缝替换其向量存储组件?", "files": ["OpenViking/docs/en/concepts/05-storage.md", "OpenViking/docs/en/api/06-retrieval.md"], "answer": "OpenViking 采用独立的存储架构,通过 API 接口与 RAG 框架集成。\n\n**存储架构**:\nOpenViking 使用双层存储架构,分离内容存储与索引存储:\n- **AGFS**:内容存储层,存储 L0/L1/L2 全部内容、多媒体文件、关系\n- **Vector Index**:索引存储层,存储 URI、向量、元数据(不含文件内容)\n\n**与 RAG 框架的集成方式**:\n\n1. **API 层集成**:\n - 提供 `find()` 和 `search()` API\n - `find()`:基础向量相似度搜索\n - `search()`:复杂检索(意图分析、会话上下文、查询扩展)\n\n2. **检索结果结构**:\n```python\nclass FindResult:\n memories: List[MatchedContext] # 记忆上下文\n resources: List[MatchedContext] # 资源上下文\n skills: List[MatchedContext] # 技能上下文\n```\n\n3. **替换向量存储的可行性**:\n - 可以通过 HTTP API 与 LlamaIndex/LangChain 集成\n - 但 OpenViking 提供的是完整的上下文管理方案,不仅仅是向量存储\n - 建议作为独立的上下文管理层使用\n\n**HTTP API 支持**:\n```bash\nPOST /api/v1/search/find\n{\n \"query\": \"how to authenticate users\",\n \"limit\": 10\n}\n```"}
{"question": "在生产环境中,OpenViking 的性能瓶颈可能出现在哪些环节?如何进行容量规划和性能调优?", "files": ["OpenViking/docs/en/concepts/05-storage.md", "OpenViking/openviking/storage/viking_vector_index_backend.py"], "answer": "OpenViking 的性能瓶颈主要出现在语义处理、向量检索和存储层。\n\n**潜在性能瓶颈**:\n\n1. **语义处理队列**:\n - L0/L1 生成依赖 LLM 调用\n - 大量资源添加时队列积压\n - 调优:增加并发处理数、使用更快的 VLM\n\n2. **向量检索**:\n - 大规模数据集的相似度计算\n - 调优:使用 VikingDB 后端、调整索引参数\n\n3. **存储层**:\n - AGFS 后端选择(local/s3/memory)\n - 向量索引存储(本地持久化/HTTP 服务/Volcengine VikingDB)\n\n**容量规划建议**:\n\n1. **存储后端选择**:\n - 本地开发:`backend: \"local\"`\n - 生产环境:`backend: \"s3\"` 或 `backend: \"volcengine\"`\n\n2. **向量索引配置**:\n```json\n{\n \"storage\": {\n \"vectordb\": {\n \"backend\": \"volcengine\",\n \"dimension\": 1024\n }\n }\n}\n```\n\n3. **性能调优参数**:\n - `batch_size`:嵌入请求批量大小\n - `limit`:检索结果数量限制\n - `score_threshold`:相关性分数阈值\n\n4. **监控指标**:\n - 语义处理队列长度\n - 向量检索延迟\n - 存储层 I/O 性能"}
{"question": "VikingFS 与 AGFS 的关系是什么?为什么需要两层文件系统抽象?", "files": ["OpenViking/docs/en/concepts/05-storage.md"], "answer": "VikingFS 是 AGFS 之上的 URI 抽象层,两者构成双层存储架构。\n\n**关系说明**:\n\n```\n┌─────────────────────────────────────────┐\n│ VikingFS (URI Abstraction) │\n│ URI Mapping · Hierarchical Access │\n│ · Relation Management │\n└────────────────┬────────────────────────┘\n ┌────────┴────────┐\n │ │\n┌───────▼────────┐ ┌─────▼───────────┐\n│ Vector Index │ │ AGFS │\n│ (Semantic │ │ (Content │\n│ Search) │ │ Storage) │\n└────────────────┘ └─────────────────┘\n```\n\n**职责划分**:\n\n| 层级 | 职责 | 内容 |\n|------|------|------|\n| **VikingFS** | URI 抽象层 | URI 映射、层级访问、关系管理 |\n| **AGFS** | 内容存储层 | L0/L1/L2 全部内容、多媒体文件 |\n| **Vector Index** | 索引存储层 | URI、向量、元数据 |\n\n**为什么需要两层抽象**:\n\n1. **职责分离**:\n - VikingFS 处理 URI 到物理路径的映射\n - AGFS 处理实际的文件读写操作\n\n2. **后端灵活性**:\n - AGFS 支持多种后端:localfs、s3fs、memory\n - VikingFS 屏蔽底层存储差异\n\n3. **URI 映射示例**:\n```\nviking://resources/docs/auth → /local/resources/docs/auth\nviking://user/memories → /local/user/memories\n```\n\n4. **设计优势**:\n - 清晰职责:向量索引负责检索,AGFS 负责存储\n - 内存优化:向量索引不存储文件内容\n - 独立扩展:向量索引和 AGFS 可独立扩展"}
-{"question": "`client.add_resource` 支持哪些输入格式?如何处理本地目录的递归添加和子目录过滤?", "files": ["OpenViking/docs/en/api/02-resources.md", "OpenViking/openviking/parse/directory_scan.py:1-80"], "answer": "`add_resource` 支持多种输入格式,目录处理通过 directory_scan 模块实现。\n\n**支持的输入格式**:\n\n| 格式 | 扩展名 | 处理方式 |\n|------|--------|----------|\n| PDF | `.pdf` | 文本和图片提取 |\n| Markdown | `.md` | 原生支持 |\n| HTML | `.html`, `.htm` | 清理文本提取 |\n| 纯文本 | `.txt` | 直接导入 |\n| JSON/YAML | `.json`, `.yaml` | 结构化解析 |\n| 代码 | `.py`, `.js`, `.go` 等 | 语法感知解析 |\n| 图片 | `.png`, `.jpg` 等 | VLM 描述 |\n| 视频/音频 | `.mp4`, `.mp3` 等 | 转录 |\n\n**目录递归添加流程**:\n\n1. **DirectoryScan 预扫描**:\n - 遍历目录树\n - 分类文件为 processable / unsupported\n - 跳过:点文件、符号链接、空文件\n\n2. **目录过滤机制**:\n```python\ndef _should_skip_directory(dir_path, root, ignore_dirs):\n # 跳过:点目录、符号链接、IGNORE_DIRS\n```\n\n3. **内置忽略目录**:\n - `.git`、`node_modules`、`__pycache__` 等\n - 通过 `IGNORE_DIRS` 常量定义\n\n4. **API 参数**:\n```python\nclient.add_resource(\n \"./documents\", # 本地目录路径\n target=\"viking://resources/docs\", # 目标 URI\n reason=\"文档说明\", # 添加原因\n wait=True, # 等待处理完成\n timeout=300 # 超时时间\n)\n```\n\n**处理流水线**:\nInput → Parser → TreeBuilder → AGFS → SemanticQueue → Vector Index"}
+{"question": "`client.add_resource` 支持哪些输入格式?如何处理本地目录的递归添加和子目录过滤?", "files": ["OpenViking/docs/en/api/02-resources.md", "OpenViking/openviking/parse/directory_scan.py:1-80"], "answer": "`add_resource` 支持多种输入格式,目录处理通过 directory_scan 模块实现。\n\n**支持的输入格式**:\n\n| 格式 | 扩展名 | 处理方式 |\n|------|--------|----------|\n| PDF | `.pdf` | 文本和图片提取 |\n| Markdown | `.md` | 原生支持 |\n| HTML | `.html`, `.htm` | 清理文本提取 |\n| 纯文本 | `.txt` | 直接导入 |\n| JSON/YAML | `.json`, `.yaml` | 结构化解析 |\n| 代码 | `.py`, `.js`, `.go` 等 | 语法感知解析 |\n| 图片 | `.png`, `.jpg` 等 | VLM 描述 |\n| 视频/音频 | `.mp4`, `.mp3` 等 | 转录 |\n\n**目录递归添加流程**:\n\n1. **DirectoryScan 预扫描**:\n - 遍历目录树\n - 分类文件为 processable / unsupported\n - 跳过:点文件、符号链接、空文件\n\n2. **目录过滤机制**:\n```python\ndef _should_skip_directory(dir_path, root, ignore_dirs):\n # 跳过:点目录、符号链接、IGNORE_DIRS\n```\n\n3. **内置忽略目录**:\n - `.git`、`node_modules`、`__pycache__` 等\n - 通过 `IGNORE_DIRS` 常量定义\n\n4. **API 参数**:\n```python\nclient.add_resource(\n \"./documents\", # 本地目录路径\n to=\"viking://resources/docs\", # 目标 URI\n reason=\"文档说明\", # 添加原因\n wait=True, # 等待处理完成\n timeout=300 # 超时时间\n)\n```\n\n**处理流水线**:\nInput → Parser → TreeBuilder → AGFS → SemanticQueue → Vector Index"}
{"question": "向量索引是如何构建和维护的?增量更新时如何避免全量重建?", "files": ["OpenViking/openviking/storage/viking_vector_index_backend.py", "OpenViking/docs/en/concepts/05-storage.md"], "answer": "向量索引通过 VikingVectorIndexBackend 实现,支持增量更新。\n\n**索引构建流程**:\n\n1. **初始化配置**:\n```python\nconfig = VectorDBBackendConfig(\n backend=\"local\", # local/http/volcengine\n path=\"./data/vectordb\",\n dimension=1024,\n distance_metric=\"cosine\"\n)\nbackend = VikingVectorIndexBackend(config=config)\n```\n\n2. **支持的后端模式**:\n - **local**:本地持久化存储\n - **http**:远程 HTTP 服务\n - **volcengine**:火山引擎 VikingDB\n\n3. **索引特性**:\n - 使用 BruteForce 索引进行向量相似度搜索\n - 支持标量过滤和多操作符\n - 每个集合自动管理索引\n\n**增量更新机制**:\n\n1. **URI 级别操作**:\n - VikingFS 的 `rm()`、`mv()` 操作同步更新向量索引\n - 新增内容自动触发向量化并写入索引\n\n2. **避免全量重建**:\n - 通过 URI 唯一标识每个向量条目\n - 更新时只删除旧向量、插入新向量\n - 不影响其他条目的索引\n\n3. **双层存储优势**:\n - 向量索引只存储 URI 引用和元数据\n - 内容变更不影响索引结构\n - 独立扩展存储和索引层\n\n**核心 API**:\n- `upsert()`:插入或更新向量\n- `delete()`:删除向量\n- `search()`:向量相似度搜索"}
{"question": "配置文件 `ov.conf` 的必填项有哪些?如何配置不同的 VLM 后端(OpenAI、Volcengine 等)?", "files": ["OpenViking/docs/en/guides/01-configuration.md:1-150"], "answer": "配置文件 `ov.conf` 包含 embedding、vlm、rerank、storage 等配置项。\n\n**必填配置项**:\n\n```json\n{\n \"embedding\": {\n \"dense\": {\n \"provider\": \"volcengine\", // 必填:volcengine/openai/vikingdb\n \"api_key\": \"your-api-key\", // 必填\n \"model\": \"doubao-embedding-vision-251215\",\n \"dimension\": 1024\n }\n },\n \"vlm\": {\n \"provider\": \"volcengine\", // 必填\n \"api_key\": \"your-api-key\", // 必填\n \"model\": \"doubao-seed-2-0-pro-260215\"\n }\n}\n```\n\n**VLM 后端配置**:\n\n1. **Volcengine(豆包模型)**:\n```json\n{\n \"vlm\": {\n \"api_base\": \"https://ark.cn-beijing.volces.com/api/v3\",\n \"api_key\": \"your-volcengine-api-key\",\n \"provider\": \"volcengine\",\n \"model\": \"doubao-seed-2-0-pro-260215\"\n }\n}\n```\n\n2. **OpenAI**:\n```json\n{\n \"vlm\": {\n \"api_base\": \"https://api.openai.com/v1\",\n \"api_key\": \"your-openai-api-key\",\n \"provider\": \"openai\",\n \"model\": \"gpt-4-vision-preview\"\n }\n}\n```\n\n**Embedding 配置**:\n\n| 参数 | 说明 |\n|------|------|\n| `provider` | volcengine/openai/vikingdb |\n| `api_key` | API 密钥 |\n| `model` | 模型名称 |\n| `dimension` | 向量维度 |\n| `input` | 输入类型:text/multimodal |\n\n**可选配置**:\n- `rerank`:重排序模型配置\n- `storage`:存储后端配置"}
{"question": "`HierarchicalRetriever` 的检索流程是怎样的?如何实现从 L0 到 L2 的层级穿透检索?", "files": ["OpenViking/openviking/retrieve/hierarchical_retriever.py"], "answer": "HierarchicalRetriever 实现目录递归检索和层级穿透。\n\n**检索流程**:\n\n1. **初始化**:\n```python\nclass HierarchicalRetriever:\n MAX_CONVERGENCE_ROUNDS = 3 # 收敛轮次\n MAX_RELATIONS = 5 # 最大关联数\n SCORE_PROPAGATION_ALPHA = 0.5 # 分数传播系数\n DIRECTORY_DOMINANCE_RATIO = 1.2 # 目录分数阈值\n GLOBAL_SEARCH_TOPK = 3 # 全局检索数量\n```\n\n2. **检索模式**:\n - **THINKING**:深度思考模式\n - **QUICK**:快速检索模式\n\n3. **核心方法**:\n```python\nasync def retrieve(\n self,\n query: TypedQuery,\n limit: int = 5,\n mode: RetrieverMode = RetrieverMode.THINKING,\n score_threshold: Optional[float] = None,\n metadata_filter: Optional[Dict[str, Any]] = None,\n) -> QueryResult:\n```\n\n**层级穿透机制**:\n\n1. **L0 检索**:\n - 向量相似度搜索 `.abstract.md` 内容\n - 快速过滤不相关内容\n\n2. **L1 确认**:\n - 读取 `.overview.md` 进行重排序\n - 确认内容相关性\n\n3. **L2 加载**:\n - 按需读取完整内容\n - 仅在确认需要时加载\n\n**关键特性**:\n- 分数传播:目录分数向子节点传播\n- 目录优势:目录分数需超过最大子节点分数\n- 关联检索:自动检索关联上下文"}
diff --git a/openviking/parse/parsers/code/README.md b/openviking/parse/parsers/code/README.md
index dde00ebe5..49dac5080 100644
--- a/openviking/parse/parsers/code/README.md
+++ b/openviking/parse/parsers/code/README.md
@@ -31,7 +31,7 @@ OpenViking 通过 **Code Parser** 模块实现对代码仓库的整体解析与
```python
client.add_resource(
"https://github.com/volcengine/OpenViking",
- target="viking://resources/github/volcengine/OpenViking"
+ to="viking://resources/github/volcengine/OpenViking"
)
```
@@ -115,7 +115,7 @@ viking://resources/github/volcengine/OpenViking/
# 导入代码仓库
client.add_resource(
"https://github.com/volcengine/OpenViking",
- target="viking://resources/github/volcengine/OpenViking",
+ to="viking://resources/github/volcengine/OpenViking",
reason="引入 OpenViking 源码作为参考"
)