OpenViking 知识蒸馏实战指南：用 ov compile 把多份知识库提炼为主题化、有出处的高阶结论

OpenViking 知识蒸馏实战指南：用 ov compile 把多份知识库提炼为主题化、有出处的高阶结论

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

导读

本文围绕 OpenViking 的Knowledge Distillation（知识蒸馏）Skill 展开，讲解如何把一份或多份知识库、文档集合，通过ov compile自动编译成按主题组织、有出处可查的高层次知识：跨来源的发现、趋势、变化、驱动因素、对比、影响和不确定性。读完本文，你将掌握该 Skill 的完整用法（从准备来源、添加 Skill、执行编译到检查产物），并理解其背后的证据分级模型、蒸馏质量标准与底层执行原理，能够把一叠财报、研究资料或任意领域文档蒸馏成可直接检索复用的结论树。

Skill 本体位于 examples/compile/ov-compile-skills/knowledge-distillation，官方配套示例文档见 docs/en/context-compilation/05-knowledge-distillation.md。

一、蒸馏是什么：从"资料堆"到"结论树"

知识蒸馏的目标，是把一大片知识收敛为一小组持久、高阶的结论。它不是给每份文档写摘要，也不是生成一个"资料目录"，而是完成这样的跃迁：

来源事实（source facts）→ 归一化证据（normalized evidence）→ 模式（patterns）→ 发现（findings）→ 影响（implications）

且每一步都可追溯。最终产物应当比来源集合更直接地回答用户的问题。

Skill 的 frontmatter 里对此有清晰定义（SKILL.md）：

--- name: knowledge-distillation description: Compile one or more OpenViking knowledge bases or document collections into topic-organized, evidence-grounded high-level knowledge, including cross-source findings, trends, changes, drivers, comparisons, implications, and uncertainties. Use with ov compile when the user asks to distill or synthesize a knowledge base, compare multiple collections, or derive higher-order insights such as changes across financial reports; do not use for document-by-document summaries. ---

它适用于三类典型诉求：

• 蒸馏一个知识库（把大库压成结论集）；
• 对比多个集合（跨知识库找差异）；
• 推导高阶洞察（例如"跨财报期的变化"）。

同时它也明确划定了不适用的场景：逐文档摘要（document-by-document summaries）。

蒸馏在 Context Compilation 生态中的位置

ov compile是 OpenViking 的上下文编译入口，负责把散落在文档、笔记、网页、转录、研究文件、代码仓库中的原材料，转成结构化、可检索、可复用的知识。一次编译需要提供三样东西（docs/en/context-compilation/01-overview.md）：

• --from：一个或多个来源目录/文件；
• --to：产物目标目录；
• --skill：规定输出形态的规格（spec）；
• 外加可选的--reason：本次运行的补充指令（范围、受众、语言、侧重点、日期区间）。

Skill 决定"编译成什么形状"，--reason告诉 Agent"这一次你想要什么"。OpenViking 自带的示例 Skill 各有不同的输出形态，蒸馏是其中之一：

底层执行原理

编译由VikingBot驱动（docs/en/concepts/15-vikingbot.md）：任务被接受后，VikingBot 加载你指定的 Skill，以你的身份读取来源，在专用的agent loop（Context → Model → Tools → Model）中自主工作——阅读、蒸馏、组织、写页面，就像雇人把一堆材料整理成干净的知识库再把成品交还给你。整个过程异步运行：你可以等待，也可以拿到task_id后先做别的事。

任务链路的代码入口（docs/en/api/23-agent-runtime.md）：

• openviking/server/routers/compile.py：Compile 任务创建（POST /api/v1/compile返回 202 Accepted）；
• openviking/server/routers/tasks.py：任务查询与取消；
• openviking/service/compile_service.py：Runtime 调用与任务状态收敛；
• crates/ov_cli/src/commands/compile.rs：ov compile命令的 CLI 实现。

二、输出模型：主题化工件树

蒸馏的产物是一棵按主题组织的浅层工件树：

<topic-a>/ <high-level-knowledge-a>.md <high-level-knowledge-b>.md <topic-b>/ <high-level-knowledge-c>.md

主题目录：语义领域，而非来源容器

• 每个主题目录是一个持久的语义领域，不是来源的容器；
• 主题边界由领域、任务问题和证据中反复出现的关系决定；
• 不要镜像来源知识库名、文档文件夹、作者、报告期或文件结构（除非它们本身就是分析对象）。

控制树的深度

• 默认只用一层主题目录；
• 只有当一个主题宽泛到无法连贯检索、且额外层级代表稳定的领域边界时，才引入子主题；
• 真正跨主题的结论放在最窄的共同主题下，或放在一个明确命名的 cross-cutting 主题下，不要复制进每个相关目录。

页面：一个独立有用的高阶知识单元

• 每个页面捕捉一个知识单元：趋势、机制、对比、变化、约束、权衡、风险、机会，或某个持久分析问题的答案；
• 不要一来源一页、一目录一页，也不要为主题建一个只有标签没有结论的页面；
• 不追求固定页数。

关于 index.md、.overview.md、.abstract.md 的约束

• 默认不创建index.md：蒸馏本身是一组结论，除非--reason明确要求导航页，或现有目标已有必须维护的 index 契约；
• 不要手动创建.overview.md或.abstract.md——这些派生目录摘要由 OpenViking 自己生成（它们是目录级的 L0/L1 语义 sidecar，见 docs/en/concepts/03-context-layers.md）。

命名规范

• 主题和页面名要稳定、路径安全；
• 拉丁字符路径优先用小写 kebab-case；非拉丁输出语言保留该语言的简洁规范名；
• 页面名按它检索的知识命名，而不是summary、report或来源标题；
• 复用已经拥有同一主题和结论的既有路径，不要仅为本地化而重命名既有路径。

一个形态示例

以一组财报为例（仅形态示范，真实主题由你给的领域决定）：

revenue-quality/ growth-shifted-from-volume-to-pricing.md overseas-growth-offset-domestic-slowdown.md profitability/ margin-recovered-but-cash-conversion-weakened.md risk/ customer-concentration-increased.md

注意页面名直接陈述结论本身（growth-shifted-from-volume-to-pricing），而不是来源标题（q2-report-summary）。

蒸馏页面的 OKF 格式

每个新建的蒸馏页面都是一个完整的 OKF Markdown 文件：

--- type: distillation title: Canonical analytical title description: One factual sentence stating the question, scope, and retrieval purpose. ---

frontmatter 之后接一个匹配的 H1 标题，以及直接给出答案的 2 到 4 句话。正文只使用分析真正需要的章节，例如 scope and evidence、key findings、changes and drivers、comparisons、implications、uncertainties。宁可要少数几个扎实的发现，也不要大量肤浅的观察。

OKF（OpenViking Format）是带 YAML frontmatter 的 Markdown。系统要求每个文件都有非空的type、title、description；未知元数据字段会被静默丢弃（docs/en/api/12-content.md）。

三、蒸馏标准：四层证据模型

构建结论必须经过显式的证据分级：

必须避免的推理谬误

• 把推断当作观察事实；
• 把重复出现的说法当作独立佐证（同一份会议纪要衍生的多页属于同一个证据家族，不是独立确认）；
• 把相关性当作因果；
• 把证据缺失当作"不存在的证据"。

判断一条声明是否可靠，文档数量不如其独立性、权威性、时效性和覆盖面重要。

可检验的推理链

对每个主要发现，推理过程要可检查：

1. 陈述结论；
2. 引用决定性事实；
3. 当联系不明显时解释连接；
4. 在相关时给出实际影响或不确定性。

避免伪精确的置信度分数。只有当well-supported、mixed evidence、tentative这类朴素的标签能帮助读者判断发现时，才使用它们。

四、完整工作流

1. Frame the question（框定问题）

定义：主体（subject）、时间范围（time range）、基线（baseline）、对比集（comparison set）、预期用途（intended use）、排除项（exclusions）。在深入阅读前把独立问题分开。当来源集合很宽时，先识别蒸馏应该支撑哪些决策或读者需求。

2. Survey before deep reading（先勘察，再精读）

• 先检查每个来源知识库的索引、目录或顶层结构（可用ov abstract/ov overview快速看 L0/L1）；
• 摸清它的覆盖面、时间线、权威性、术语、既有摘要和明显缺口；
• 再读每个候选发现所需的具体材料；
• 不要仅凭文件名或一次搜索命中就推断覆盖面；
• 追踪来源谱系：同一会议、报告、数据集或上游声明衍生的多页属于一个证据家族；集合中同时有原始材料和摘要时，优先原始证据。

3. Build topics bottom-up（自底向上建主题）

先抽取紧凑的声明卡片（claim cards），再决定输出树。对每条实质声明，记录：

• 主体（subject）、谓词（predicate）、范围（scope）、时间（time）；
• 证据（evidence）与状态：observation、source opinion 或 inference。

然后：归一化同义主体，去重共享同一上游来源的声明；按"共同回答的问题"或"共同解释的机制"聚类声明；主题名要在声明簇足够连贯之后才定；最后从簇内/簇间的共识、变化、对比、依赖和张力中导出候选高阶知识。这种自底向上的顺序，可以防止一个方便的文件夹分类法把证据硬塞进缺乏支持的结论。

主题名要在知识库增长时仍然有用，页面标题要陈述真实结论。例如用revenue-quality/growth-shifted-from-volume-to-pricing.md，而不是finance/q2-report-summary.md。

4. Normalize evidence（归一化证据）

在比较事实之前，先对齐：实体（entities）、别名（aliases）、定义（definitions）、版本（versions）、期间（periods）、单位（units）、货币（currencies）、范围（scopes）、度量方法（measurement methods）。保留有意义的差异，不要把不同质的东西硬塞进同一张表或同一条趋势。

变化分析要建立可比的基线与当前状态，并区分：

• 绝对变化（absolute change）；
• 相对变化（relative change）；
• 组合偏移（mix shift）；
• 定义变化（change in definition）。

例如，在声称某项财务指标改善之前，先对齐报告期、货币、合并范围、指标定义和任何重述（restatement）。去重重复事实；无法调和的分歧就保留为结果的一部分，并绑定其来源、日期、版本或视角。

5. Derive and select findings（推导并筛选发现）

寻找：有支持的变化、反复出现的机制、稳定关系、驱动因素、约束、权衡、异常、风险、机会、知识缺口。对每个候选结论，用**反证（counterevidence）**和合理的替代解释检验。

保留那些：对问题实质性、证据充分到有用、比直接复述来源更有信息量的发现。丢弃：装饰性主题、琐碎的共性、推理依赖缺失或不兼容证据的声明。

表格只用于真正可比的主体或期间。展示派生计算时要给出输入值、单位和公式；绝不虚构缺失的分母，也不要悄悄混用 reported 值和 calculated 值。

6. Write with provenance（带出处写作）

• 把准确的来源 URI、仓库相对路径或提供的链接放在它们支撑的观察附近；
• 给每个链接简洁可读的文本，保留提供的锚点；
• 绝不发明来源、锚点、引文、日期、指标、关系或因果解释；
• 声明专属证据内联保留；若页面还需要来源清单，用## Sources（或本地化等价标题）渲染一次，不要重复同一批链接；
• 说明来源覆盖面和重要遗漏，让读者明白蒸馏能证明什么、不能证明什么。

7. Integrate existing knowledge（整合既有知识）

• 更新前先勘察既有主题树，完整阅读相关蒸馏页；
• 保留准确、独有的上下文和用户创作的材料；
• 合并互补证据；
• 刷新同一个分析页，不要创建同义主题或重复结论；
• 每个可能变化的结论都要加时间边界：新证据改变旧结论时，解释转变及其证据，而不是静默追加一个不相容的发现；
• 不动无关的目标页和可选的 index，除非任务要求改动它们。

五、质量门（Quality gate）

完成前逐条核对（完整清单见 SKILL.md 的 Quality gate 一节），核心检查项包括：

• 开头直接回答清晰的分析问题，或定义了有用的领域概览；
• 结果是跨知识的综合，而不是逐来源摘要；
• 每个主要发现都有从被引用观察到结论的可追溯链条；
• observations、syntheses、inferences、hypotheses、source opinions 之间保持可区分；
• 所有被比较或计算的主体，其期间、实体、定义、版本、单位、货币、范围可比；
• 反证、矛盾、来源依赖、覆盖面缺口、不确定性都被保留；
• 因果声明和影响不超出证据；
• 主题目录反映分析领域而非来源布局，且保持浅层；
• 每个页面包含一个独立有用的高阶知识单元，而非来源或文件夹摘要；
• 没有创建根 index（除非任务或既有目标契约要求）；
• 每个文件都有非空type、title、description的合法 OKF frontmatter；
• 没有创建 OpenViking 生成的语义 sidecar、逐来源摘要页或重复操作日志。

六、实战：四步完成一次财报蒸馏

以下命令完整对应 docs/en/context-compilation/05-knowledge-distillation.md 的示例。

前置条件

• 运行中的 OpenViking 服务且开启 Bot（--with-bot），默认端点http://localhost:1933；远程使用需要 API Key（见 docs/en/guides/04-authentication.md）；
• ovCLI 已配置连接（~/.openviking/ovcli.conf或OPENVIKING_*环境变量）。

第一步：准备来源

ov add-resource ./finance-reports --to viking://resources/finance-reports --wait ov ls -r viking://resources/finance-reports

ov add-resource可导入本地文件、文件夹、URL、仓库乃至整个网站（sitemap/RSS），--wait表示等待导入处理完成（crates/ov_cli/src/help_ui.rs 中add-resource帮助说明）。

第二步：添加 Skill

ov add-skill examples/compile/ov-compile-skills/knowledge-distillation --wait ov skills list # → viking://agent/skills/knowledge-distillation （或 viking://user/<user_name>/skills/knowledge-distillation）

ov add-skill接受SKILL.md文件或包含SKILL.md的目录（辅助文件一并纳入），处理流程为：接收数据 → 检测格式（结构化数据 / SKILL.md / MCP Tool 自动转换）→ 解析定义 → 存储到当前用户的viking://user/{user_id}/skills/→ 若wait=true等待向量化完成（docs/en/api/04-skills.md）。核心入口包括openviking/server/routers/resources.py的add_skill路由和openviking/service/resource_service.py的ResourceService.add_skill。

第三步：执行编译

在--reason里说清分析问题、对比维度、基线和范围——它直接决定蒸馏的方向：

ov compile \ --from viking://resources/finance-reports \ --to viking://resources/finance-insights \ --skill viking://agent/skills/knowledge-distillation \ --reason "Compare the last three years of reports; obtain changes and drivers in revenue quality, profitability, and risk"

--from可传多个来源用于跨知识库对比：

ov compile \ --from viking://resources/finance-2024,viking://resources/finance-2025 \ --to viking://resources/finance-insights \ --skill viking://agent/skills/knowledge-distillation \ --reason "Compare the two yearly knowledge bases; surface changes and structural differences in key metrics"

命令立刻返回task_id（格式为cmp_...）：

ov task status cmp_01abc # 查看进度与最终结果 ov task cancel cmp_01abc # 协作式取消

参数细节与底层行为

ov compile的 CLI 实现在 crates/ov_cli/src/commands/compile.rs：

• --from支持逗号分隔多来源，且自动去重（normalize_sources会拆分逗号、去空项、去重，测试用例见同文件expands_comma_separated_and_repeated_sources_stably）；
• --args必须是合法 JSON 对象（如{"model_name":"your-model-endpoint-id"}），parse_args会严格校验，非对象或非法 JSON 直接报错；
• 请求发往POST /api/v1/compile（见 openviking/server/routers/compile.py），HTTP 层返回 202 Accepted。

Compile 任务字段（docs/en/api/23-agent-runtime.md）：

任务生命周期（ov task status/ov task cancel）：

取消是协作式的：任务先进入cancelling，在进程内工作和清理落定后变为cancelled；已完成写入不回滚；对已取消任务的重复取消是幂等的。

第四步：检查产物

先看主题树，再钻进具体结论页：

ov tree viking://resources/finance-insights ov read viking://resources/finance-insights/revenue-quality/growth-shifted-from-volume-to-pricing.md

ov tree展示 URI 下的分层视图（可用-L <depth>控制深度），ov read读取精确的 L2 文件内容（crates/ov_cli/src/help_ui.rs）。默认不创建index.md——蒸馏本身就是一组结论，除非--reason明确要求导航页。重复运行会刷新同一个分析页，并为可能变化的结论加上时间边界。

七、通过 HTTP API 与 SDK 触发蒸馏

Compile 不限于 CLI。作为创建任务的等价通道，POST /api/v1/compile接受 JSON：

curl -X POST http://localhost:1933/api/v1/compile \ -H "Content-Type: application/json" \ -H "X-API-Key: your-key" \ -d '{ "from": ["viking://resources/finance-2024", "viking://resources/finance-2025"], "to": "viking://resources/finance-insights", "skill": "viking://agent/skills/knowledge-distillation", "reason": "Compare the two yearly knowledge bases; surface changes and structural differences in key metrics.", "args": {"model_name": "your-model-endpoint-id"} }'

Python SDK 等价写法（sdk/python）：

task = client.compile( ["viking://resources/finance-2024", "viking://resources/finance-2025"], "viking://resources/finance-insights", "viking://agent/skills/knowledge-distillation", {"reason": "Compare the two yearly knowledge bases; surface changes and structural differences."}, )

创建后通过GET /api/v1/tasks/{task_id}查询、POST /api/v1/tasks/{task_id}/cancel取消。任务仅对创建它的主体可见：缺失任务和他人任务都返回404（docs/en/api/23-agent-runtime.md）。

八、进阶建议

• 把--reason当作分析契约：写清楚要回答的问题、对比维度、时间基线与范围。它决定蒸馏方向，写得越具体，产物越贴近需求；
• 先勘察再精读：利用 L0/L1 侧car 快速摸清来源结构，避免被文件名误导；
• 跨库对比时保持证据家族意识：多来源中源自同一上游材料的页面是同一证据家族，不算独立确认；
• 结论页命名即结论：让页面标题直接可检索（如growth-shifted-from-volume-to-pricing.md），方便未来复用与合并；
• 重跑即刷新：新增来源后重跑同一ov compile命令，系统会刷新同一分析页并保留时间边界，而不是堆叠重复结论。

相关文档

• 上下文编译概览
• 日报示例（Daily Report）
• Agent Runtime API（任务生命周期与 HTTP 接口）
• Skills API（Skill 管理与自定义）
• 上下文分层 L0/L1/L2 与 OKF 侧car 格式
• VikingBot 概念（编译背后的 Agent 运行时）

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking