Skip to content

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

28.4 KB
Raw Blame
{"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": "OpenViking 的内置记忆类型如何划分?在实际应用中如何自动提取?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/openviking/session/compressor_v2.py"], "answer": "OpenViking 的记忆类型由 MemoryType Schema 定义,并可通过自定义模板扩展或覆盖。当前内置类型按用途可理解为三组:\n\n**用户与环境理解**:\n- **profile**:用户基本信息,存储在 `user/memories/profile.md`\n- **preferences**:用户偏好,存储在 `user/memories/preferences/`\n- **entities**:人物、项目、组织等实体知识,存储在 `user/memories/entities/`\n- **events**:决策、里程碑等事件记录,存储在 `user/memories/events/`\n\n**助手身份与连续性**:\n- **identity**:助手身份与自我介绍,存储在 `user/memories/identity.md`\n- **soul**:助手原则、边界、风格和连续性,存储在 `user/memories/soul.md`\n\n**任务执行与学习**:\n- **cases**:可训练、可评估的任务案例\n- **trajectories**:可复用的任务执行轨迹\n- **experiences**:从执行结果提炼的可复用经验\n- **tools**:工具使用经验与最佳实践\n- **skills**:技能执行经验与工作流策略\n\n这些类型默认存储在 `user/memories/` 的对应文件或子目录中;短路径会按当前身份解析到 `viking://user/{user_id}/...`,支持的类型也可按记忆策略写入相关 Peer 空间。\n\n**自动提取机制**:\n1. 提交 Session 后格式化会话消息\n2. 根据当前记忆策略选择已启用的 MemoryType Schema\n3. 调用 LLM 生成结构化 memory operations\n4. 按各 Schema 的目录、文件名和合并规则写入并建立索引"}
{"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://~/memories/` - 用户级记忆\n   - `viking://user/{user_id}/peers/{peer_id}/memories/` - Peer 级记忆\n   - `viking://resources/` - 共享资源\n   - `viking://~/skills/` - User 技能\n\n2. **作用域划分**:\n   - **User Scope**:用户相关的 profile、preferences、entities、events\n   - **Peer/Execution Scope**:Agent 学习到的 trajectories、experiences\n   - **Resources Scope**:共享的知识库\n\n**记忆共享机制**:\n1. **资源层共享**:所有 Agent 可以访问 `viking://resources/` 下的共享知识库。\n2. **用户记忆共享**:同一用户的不同 Agent 可以共享 `viking://~/memories/` 下的用户偏好和实体记忆。\n3. **关系管理**:\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)` - 添加消息\n3. **提交**:`session.commit()` - 归档并提取记忆\n\n**commit 后的持久化流程**:\n1. **归档流程**:\n   - 增加 compression_index\n   - 复制当前消息到归档目录\n   - 生成结构化摘要(LLM)\n   - 清空当前消息列表\n\n2. **记忆提取**:\n   - SessionCompressorV2 从消息中提取和更新记忆\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  \"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://~/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- 自动会话管理:实现记忆迭代"}
{"question": "如何评估 OpenViking 的检索质量?是否有内置的评测机制或指标?", "files": ["OpenViking/openviking/eval/__init__.py:1-25", "OpenViking/examples/eval/rag_eval.py"], "answer": "OpenViking 提供了 eval 评估模块,支持 RAGAS 等主流评测工具集成。\n\n**内置评测机制**:\n\n1. **eval 模块组成**:\n   - `EvalSample`:评估样本数据结构\n   - `EvalDataset`:评估数据集\n   - `RagasEvaluator`:RAGAS 评测适配器\n   - `RAGQueryPipeline`:RAG 查询流水线\n\n2. **支持的评测指标**(通过 RAGAS):\n   - **faithfulness**:答案忠实度\n   - **answer_relevance**:答案相关性\n   - **context_precision**:上下文精确度\n   - **context_recall**:上下文召回率\n\n3. **评测流程**:\n```python\n# 准备评估样本\nsamples = [EvalSample(\n    query=\"问题\",\n    context=[\"检索到的上下文\"],\n    response=\"生成的答案\",\n    ground_truth=\"标准答案\"\n)]\n\n# 运行评测\nevaluator = RagasEvaluator()\nsummary = await evaluator.evaluate_dataset(dataset)\n```\n\n4. **CLI 评测工具**:\n```bash\nuv run rag_eval.py \\\n  --docs_dir ./docs \\\n  --question_file ./questions.json \\\n  --output ./results.json\n```\n\n**评测报告输出**:\n- 平均分数(mean_scores)\n- 每个样本的详细分数\n- JSON 格式结果保存"}
{"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│    URI Mapping · Hierarchical Access     │\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://~/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    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` 的全局检索流程是怎样的?THINKING 和 QUICK 如何影响召回数量与 Rerank?", "files": ["OpenViking/openviking/retrieve/hierarchical_retriever.py"], "answer": "HierarchicalRetriever 每条查询只执行一次全局向量检索,目标目录、上下文类型、权限、元数据和 level 共同限定搜索范围。QUICK 直接召回 limit 条,不执行 Rerank。THINKING 配置了可用的 Rerank 时召回 2 × limit 条候选,对候选统一精排一次,应用分数阈值后返回最多 limit 条;没有可用的 Rerank 时只召回 limit 条。未显式指定模式时,有可用 Rerank 选择 THINKING,否则选择 QUICK。图像查询跳过文本 Rerank。Rerank 失败或返回无效结果时沿用向量分数。检索不再逐层遍历目录,也没有父子分数传播或多轮收敛判断。"}
{"question": "语义处理队列的工作机制是什么?如何监控和调试异步处理状态?", "files": ["OpenViking/docs/en/concepts/01-architecture.md", "OpenViking/openviking/service/resource_service.py:1-80"], "answer": "语义处理队列通过 SemanticQueue 异步生成 L0/L1 内容。\n\n**工作机制**:\n\n1. **处理流水线**:\n```\nInput → Parser → TreeBuilder → AGFS → SemanticQueue → Vector Index\n```\n\n2. **队列处理**:\n   - TreeBuilder 将文件移动到 AGFS 后入队\n   - SemanticQueue 异步处理队列项\n   - 自底向上生成 L0/L1\n\n3. **异步处理优势**:\n   - 不阻塞资源添加操作\n   - 支持大规模文档处理\n   - LLM 调用并行化\n\n**监控和调试**:\n\n1. **等待处理完成**:\n```python\nresult = client.add_resource(\"./docs\", wait=False)\nclient.wait_processed()  # 等待队列处理完成\n```\n\n2. **超时控制**:\n```python\nresult = client.add_resource(\n    \"./docs\",\n    wait=True,\n    timeout=300  # 超时时间(秒)\n)\n```\n\n3. **DebugService**:\n   - 提供 ObserverService 用于调试\n   - 可视化检索轨迹\n\n4. **日志监控**:\n   - 通过 logger 获取处理状态\n   - 监控队列长度和处理延迟\n\n**Service 层支持**:\n- ResourceService 管理 add_resource 操作\n- wait_processed() 方法等待语义处理完成"}
{"question": "如何通过代码动态创建和管理 Session?Session 与 Memory 的关系是什么?", "files": ["OpenViking/docs/en/concepts/08-session.md", "OpenViking/openviking/session/compressor_v2.py"], "answer": "Session 通过 client API 动态创建,commit 后自动提取 Memory。\n\n**Session 创建和管理**:\n\n1. **创建 Session**:\n```python\n# 创建新会话\nsession = client.session(session_id=\"chat_001\")\n\n# 或使用 create_session\nresult = client.create_session()\n```\n\n2. **添加消息**:\n```python\nsession.add_message(\n    \"user\",\n    [TextPart(\"How to configure embedding?\")]\n)\n\nsession.add_message(\n    \"assistant\",\n    [\n        TextPart(\"Here's how...\"),\n        ContextPart(uri=\"viking://~/memories/profile.md\"),\n    ]\n)\n```\n\n3. **提交会话**:\n```python\nresult = session.commit()\n# {\"status\": \"committed\", \"memories_extracted\": 5}\n```\n\n**Session 与 Memory 的关系**:\n\n1. **Memory 来源**:\n   - Memory 从 Session 消息中提取\n   - SessionCompressorV2 在 commit 时触发\n\n2. **提取流程**:\n   - 格式化会话消息\n   - 根据当前记忆策略调用 LLM 提取已启用的记忆类型\n   - 写入当前用户或相关 Peer 的记忆目录并索引\n\n3. **内置记忆类型与默认位置**:\n   - profile → `user/memories/profile.md`\n   - preferences → `user/memories/preferences/`\n   - entities → `user/memories/entities/`\n   - events → `user/memories/events/`\n   - identity → `user/memories/identity.md`\n   - soul → `user/memories/soul.md`\n   - cases → `user/memories/cases/`\n   - trajectories → `user/memories/trajectories/`\n   - experiences → `user/memories/experiences/`\n   - tools → `user/memories/tools/`\n   - skills → `user/memories/skills/`\n\n这些 `user/...` 短路径会按当前身份解析为 `viking://user/{user_id}/...`,应用也可以通过自定义模板扩展或调整记忆类型。"}
{"question": "OpenViking Server 模式与本地模式的区别是什么?如何选择部署方式?", "files": ["OpenViking/openviking/server/bootstrap.py:1-61", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "Server 模式提供 HTTP API,本地模式直接嵌入应用。\n\n**模式对比**:\n\n| 维度 | 本地模式 | Server 模式 |\n|------|----------|-------------|\n| 访问方式 | Python SDK | HTTP API |\n| 部署复杂度 | 简单 | 需启动服务 |\n| 多客户端 | 不支持 | 支持 |\n| 资源共享 | 单进程 | 多进程共享 |\n| 适用场景 | 单机应用 | 生产环境 |\n\n**Server 模式启动**:\n\n1. **命令行启动**:\n```bash\nopenviking-server --host 0.0.0.0 --port 1933 --config ./ov.conf\n```\n\n2. **参数说明**:\n- `--host`:绑定地址\n- `--port`:端口号\n- `--config`:配置文件路径\n\n3. **HTTP API 示例**:\n```bash\ncurl -X POST http://localhost:1933/api/v1/resources \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-key\" \\\n  -d '{\"path\": \"./documents/guide.md\"}'\n```\n\n**部署方式选择**:\n\n1. **选择本地模式**:\n   - 单机应用开发\n   - 快速原型验证\n   - 无需多客户端访问\n\n2. **选择 Server 模式**:\n   - 生产环境部署\n   - 多客户端/多服务访问\n   - 需要集中式上下文管理\n   - 微服务架构集成\n\n**Service 层复用**:\n两种模式共享 Service 层逻辑,支持 HTTP Server 和 CLI 复用。"}
{"question": "eval 模块的 RAGAS 集成是如何实现的?如何自定义评测指标?", "files": ["OpenViking/openviking/eval/ragas.py", "OpenViking/openviking/eval/base.py:1-60"], "answer": "eval 模块通过 RagasEvaluator 适配器集成 RAGAS,支持自定义评测指标。\n\n**RAGAS 集成实现**:\n\n1. **RagasEvaluator 类**:\n```python\nclass RagasEvaluator(BaseEvaluator):\n    def __init__(self, metrics=None, llm=None, embeddings=None):\n        from ragas.metrics import (\n            answer_relevance,\n            context_precision,\n            context_recall,\n            faithfulness,\n        )\n        self.metrics = metrics or [\n            faithfulness,\n            answer_relevance,\n            context_precision,\n            context_recall,\n        ]\n```\n\n2. **评测流程**:\n```python\nasync def evaluate_dataset(self, dataset: EvalDataset) -> SummaryResult:\n    # 转换为 RAGAS 数据集格式\n    data = {\n        \"question\": [s.query for s in dataset.samples],\n        \"contexts\": [s.context for s in dataset.samples],\n        \"answer\": [s.response for s in dataset.samples],\n        \"ground_truth\": [s.ground_truth for s in dataset.samples],\n    }\n    \n    # 调用 RAGAS evaluate\n    result = evaluate(data, metrics=self.metrics)\n```\n\n**自定义评测指标**:\n\n1. **继承 BaseEvaluator**:\n```python\nclass MyEvaluator(BaseEvaluator):\n    async def evaluate_sample(self, sample: EvalSample) -> EvalResult:\n        # 实现自定义评测逻辑\n        scores = {\"my_metric\": 0.85}\n        return EvalResult(sample=sample, scores=scores)\n```\n\n2. **自定义 RAGAS 指标**:\n```python\nfrom ragas import evaluate\nfrom ragas.metrics import Metric\n\nclass MyMetric(Metric):\n    name = \"my_metric\"\n    # 实现指标计算\n\nevaluator = RagasEvaluator(metrics=[MyMetric()])\n```\n\n3. **评测结果结构**:\n```python\nclass SummaryResult(BaseModel):\n    dataset_name: str\n    sample_count: int\n    mean_scores: Dict[str, float]  # 平均分数\n    results: List[EvalResult]       # 每个样本结果\n```"}