# LLM Wiki Agent：Karpathy Wiki模式的开源实现，支持离线运行

> 基于Andrej Karpathy提出的LLM Wiki模式构建的知识管理Agent，采用奖章架构分层存储，支持本地Ollama推理与云端Gemini混合部署，完全离线可用。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-21T16:14:28.000Z
- 最近活动: 2026-04-21T16:29:31.305Z
- 热度: 157.8
- 关键词: 知识管理, Wiki, Ollama, 本地推理, 知识图谱, Obsidian, Karpathy
- 页面链接: https://www.zingnex.cn/forum/thread/llm-wiki-agent-karpathy-wiki
- Canonical: https://www.zingnex.cn/forum/thread/llm-wiki-agent-karpathy-wiki
- Markdown 来源: ingested_event

---

## 起源：Karpathy的Wiki模式

LLM Wiki Agent直接源于Andrej Karpathy分享的一个设计模式。这个模式的核心思想是：将知识库组织为Wiki风格的单概念页面，通过`[[wiki链接]]`建立概念间的关联，并利用图遍历作为导航机制。

与传统的文档管理系统不同，Wiki模式强调**概念的离散化和关联化**。每个页面只承载一个核心概念，通过链接与其他概念形成知识网络。这种结构天然适合大语言模型的理解和推理。

## 核心架构：奖章分层存储

项目实现了 medallion architecture（奖章架构），将知识分为三个层级：

### 黄金层（canon/）

只读的核心知识源，包含经过验证的权威信息。Agent可以读取但永远不会覆盖这一层的内容。在搜索排序中，黄金层结果具有最高优先级。

### 白银层（knowledge/wiki/）

Agent可写的知识存储层，用于保存Agent整理、归纳和生成的知识。这是Agent进行知识工作的主要场所，搜索结果中优先级次于黄金层。

### 青铜层（knowledge/raw/）

原始数据源，包括导入的文档、网页抓取内容等未经处理的信息。作为知识加工的原材料，搜索优先级最低。

这种分层设计确保了知识的质量控制和溯源能力，避免了原始噪声污染核心知识库。

## 混合推理：本地与云端自由切换

项目的一大亮点是灵活的推理模式选择，用户可以根据隐私和性能需求自由组合：

| 使用场景 | 对话推理 | 嵌入向量 | 网络需求 |
|---------|---------|---------|---------|
| 完全本地 | Ollama（本地） | Ollama（本地） | 无 |
| 混合模式 | Ollama（本地或云端） | Gemini（云端） | 仅嵌入 |
| 完全云端 | Ollama Cloud | Gemini（云端） | 需要网络 |

这种设计打破了本地必慢、云端必泄露的二元对立，让用户能够根据具体任务选择最合适的推理模式。敏感内容使用本地模型处理，复杂推理任务可以调用云端能力。

## 知识图谱：六种边类型

项目构建了丰富的知识图谱，支持六种边类型来描述概念间的关系：

- **SIMILAR**：概念相似性
- **INTER_FILE**：文件间关联
- **CROSS_DOMAIN**：跨领域联系
- **PARENT_CHILD**：层级从属关系
- **REFERENCES**：引用关系
- **RELATES_TO**：一般关联

每条边都携带来源信息（link_text、link_kind、evidence），确保图谱的可解释性和可追溯性。

## 工具执行：诚实的完成状态

项目引入了一个重要的UX设计原则：诚实的工具执行反馈。每个工具调用都会明确标注执行状态：COMPLETE（完成）、TRUNCATED（截断）或NOT_EXECUTED（未执行）。跳过的调用和重复调用永远不会被标记为完成，UI会清晰展示这些差异。这种设计避免了用户被虚假的成功状态误导，提升了系统的可信度。

## 自适应预算管理

为了在大规模知识库中高效工作，项目实现了智能的上下文预算管理：

- **单次加载限制**：每轮对话最多加载15个章节
- **Token安全阈值**：始终保持至少8K tokens的余量
- **分类上限控制**：按内容类型设置不同的加载上限
- **流量管控**：工具调用占用约50%的上下文容量上限

这些机制确保了Agent在处理大型文档时不会超出模型上下文限制，同时优先加载最相关的内容。

## 流式工具循环

项目采用异步流式架构处理工具调用：

- 使用Ollama原生的tool_calls接口
- 通过asyncio.to_thread在后台执行工具
- 自动去重相同名称和参数的重复调用
- SSE（Server-Sent Events）生命周期事件实时推送

这种设计让UI可以实时展示工具执行进度，而不是等待所有操作完成后才一次性返回结果。

## Obsidian兼容：无缝集成现有工作流

项目充分考虑了与现有工具的兼容性：

- **Frontmatter元数据**：支持YAML格式的页面属性
- **Wiki链接语法**：[[page-name]]格式与Obsidian完全一致
- **标题树结构**：保留H1-H5层级，便于导航
- **Token成本标注**：在标题旁显示预估token消耗

这意味着用户可以将现有的Obsidian笔记库直接作为知识库使用，无需任何格式转换。

## 快速开始

部署LLM Wiki Agent非常简单，只需几步：

```bash
git clone https://github.com/thefilesareinthecomputer/llm-wiki-agent.git
cd llm-wiki-agent

echo "GOOGLE_GEMINI_API_KEY=你的API密钥" > .env
echo "EMBEDDING_PROVIDER=gemini" >> .env

docker compose up --build -d
```

然后访问http://localhost:8080即可开始使用。

## 应用场景

### 个人知识管理

将多年的学习笔记、阅读摘录整理为结构化的知识库，通过AI助手快速检索和关联相关信息。

### 团队知识沉淀

在团队中建立共享的知识库，新成员可以通过对话快速了解项目背景和技术细节，减少重复答疑。

### 研究资料整理

学术研究中的论文、实验记录、想法片段可以离散化为Wiki页面，利用知识图谱发现潜在的研究关联。

### 离线敏感工作

对于涉及机密信息的场景，可以完全离线部署，所有数据保存在本地，AI推理也在本地完成。

## 总结：Wiki模式的工程实现

LLM Wiki Agent不仅是一个可用的软件产品，更是对Karpathy Wiki模式的一次完整工程实现。它证明了这种以概念为中心、以链接为纽带的知识组织方式，确实能够与大语言模型形成良好的协同。

项目的奖章架构、混合推理、诚实反馈等设计决策，都体现了对实际使用场景的深入思考。对于希望构建个人或团队知识管理系统的用户来说，这是一个值得认真考虑的开源方案。