自托管AI知识库Khoj部署指南：打造离线可用的个人第二大脑

1. 项目概述：你的个人AI知识副驾驶

如果你和我一样，电脑里散落着成千上万的笔记、文档、PDF、网页书签，每次想找点东西都得靠记忆和搜索碰运气，那你一定懂那种“知识就在那里，但我就是找不到”的无力感。我尝试过各种笔记软件、文档管理工具，但它们大多只是把文件堆在一起，并没有真正理解里面的内容。直到我遇到了 Khoj。

Khoj 不是一个简单的搜索工具，它是一个开源的、可自托管的个人 AI 助手，核心目标是把你的所有个人知识库——无论是 Obsidian 笔记、Markdown 文件、PDF 文档、图片，还是网页内容——变成一个你可以随时用自然语言对话的“第二大脑”。你可以问它：“我上周读的那篇关于 Rust 内存管理的文章里，作者提到的零成本抽象具体是怎么实现的？”或者“帮我找出所有关于‘项目复盘’的笔记，并总结一下我常用的几个框架。”它不仅能精准定位，还能理解上下文，给出整合后的答案。

这个项目最吸引我的地方在于它的“离线优先”和“隐私至上”理念。你的所有数据都在你自己的设备上处理，AI 模型也可以本地运行，这意味着你的私人想法、工作笔记、学习资料完全不会离开你的电脑。对于注重数据安全和隐私的开发者、研究者、写作者来说，这几乎是刚需。接下来，我会详细拆解我是如何部署、配置 Khoj，并让它深度融入我的日常工作流的，希望能给你提供一个完整的参考。

2. 核心架构与工作原理解析

要玩转 Khoj，首先得理解它到底是怎么工作的。它不是一个魔法黑盒，其核心架构清晰且模块化，理解了原理，后续的配置和问题排查都会事半功倍。

2.1 核心组件：检索器、模型与接口

Khoj 的架构可以简单理解为三个核心层：数据处理与检索层、AI 模型层和用户交互层。

首先，数据处理与检索层是地基。当你把一堆杂乱的文档丢给 Khoj 时，它做的第一件事是“消化”。这个过程叫做“索引”（Indexing）。Khoj 会读取你的文档（支持 Markdown, Org-mode, PDF, 图像，甚至 Notion、Github 导出的内容），使用嵌入模型（Embedding Model）将文本转换成高维向量（Vector）。你可以把向量理解为一串能代表文本语义的数字指纹。比如，“狗”和“犬”的向量在空间中的距离会很近，而“狗”和“汽车”的向量距离则很远。所有这些向量会被存储在一个本地的向量数据库（默认是 ChromaDB）里。当你提问时，你的问题也会被转换成向量，系统会快速在向量数据库中找出与之最“相似”（即向量距离最近）的几段文本，这就是“语义搜索”，它理解意图，而非单纯的关键词匹配。

其次，AI 模型层是大脑。Khoj 支持两种模式：在线 API 和离线本地模型。在线模式下，你可以配置 OpenAI 的 GPT 系列或 Anthropic 的 Claude 等模型的 API。本地模式下，则依赖 Ollama 或 LM Studio 来运行诸如 Llama 3、Mistral、Qwen 等开源大语言模型。检索层找到的相关文本片段，会作为“上下文”和你的问题一起，提交给这个大语言模型。模型的任务是基于这些上下文，生成一个连贯、准确、有针对性的回答。这就是为什么 Khoj 的回答感觉像是“读过你的笔记”一样，因为它确实“看”了检索到的相关内容。

最后，用户交互层是面孔。Khoj 提供了多种交互方式：一个简洁的 Web 界面、一个桌面应用程序（Electron）、以及最强大的——与 Obsidian、Emacs、Visual Studio Code 等工具的深度插件集成。我大部分时间都在 Obsidian 里直接和 Khoj 对话，这让我感觉它就是我笔记系统的一个自然延伸。

2.2 为什么选择自托管与本地模型？

这里涉及几个关键的技术选型考量，也是很多人在初次接触时的疑惑点。

第一，数据隐私与安全。将个人全部知识库上传到第三方云服务，始终存在隐私泄露的风险，无论服务商承诺得多好。自托管意味着所有数据，从原始文档、索引向量到聊天记录，都物理存储在你自己的硬盘上。本地模型推理则确保了你的问题和你笔记的敏感内容永远不会通过互联网发送出去。这对于处理商业计划、未公开的创作草稿、个人日记等内容至关重要。

第二，成本可控与离线可用。使用 GPT-4 等在线 API 虽然效果强大，但长期频繁使用成本不菲，且严重依赖网络。本地模型一次部署，后续推理几乎零成本（电费除外），并且完全离线工作。在飞机上、网络信号差的地区，你依然可以畅快地查询自己的知识库。

第三，定制化与可控性。开源模型社区异常活跃，你可以选择最适合你领域和需求的模型。比如，如果你主要处理中文资料，可以选择 Qwen 系列；如果更注重推理能力，可以选 Llama 3。你还可以对模型进行微调（虽然 Khoj 本身不直接提供此功能，但你可以准备微调好的模型给它用），让它更懂你的行文风格和专业术语。

当然，这需要权衡。本地模型对硬件（尤其是 GPU 内存）有要求，且响应速度可能不如顶级云 API 快。但以目前消费级硬件（如配备 M 系列芯片的 Mac、或拥有 16GB 以上内存和较好显卡的 PC）的能力，运行 7B（70亿）参数级别的量化模型，已经能提供非常流畅可用的体验了。Khoj 的聪明之处在于它支持“混合模式”，你可以为不同的功能配置不同的模型后端，比如用快速的本地小模型处理简单检索和总结，在需要深度创作时手动切换到云 API。

3. 从零开始的部署与配置实战

理论说再多，不如动手做一遍。我将在 macOS/Linux 环境下，以最常用的 Docker 部署方式为例，带你走通全流程。Windows 用户使用 Docker Desktop 过程类似。

3.1 基础环境部署：Docker 一键启动

Docker 是部署 Khoj 最推荐的方式，它封装了所有依赖，避免了环境冲突。首先，确保你的系统已经安装了 Docker 和 Docker Compose。

第一步，获取配置文件。Khoj 团队提供了一个标准的docker-compose.yml文件，我们以此为基础进行定制。

# 创建一个专门的工作目录 mkdir khoj && cd khoj # 下载官方docker-compose配置文件 curl -o docker-compose.yml https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml

第二步，在启动前，我们必须修改这个配置文件，这是最关键的一步。用你喜欢的文本编辑器（如 VSCode, Vim）打开docker-compose.yml。你会看到里面定义了两个服务：khoj和ollama。我们需要关注以下几点：

1. 数据持久化卷（Volumes）：这是你的知识库索引和聊天记录的存储位置。默认配置已经将容器内的/usr/src/app/data目录挂载到宿主机的./data目录。我强烈建议你将其修改为一个明确的绝对路径，比如~/khoj-data:/usr/src/app/data，这样即使你删除或移动了khoj项目文件夹，你的数据也不会丢失。
2. 模型配置：ollama服务默认会拉取llama3.2:1b这个很小的模型用于快速启动测试。但对于实际使用，这个模型能力太弱。我建议在ollama服务的command部分后面，添加run llama3.2:3b或run qwen2.5:3b等指令，让容器启动时自动拉取一个更实用的模型。你也可以后续通过 Ollama 的命令行来拉取。
3. 端口映射：Khoj 的 Web 界面默认运行在容器内的42110端口，并映射到宿主机的42110。确保这个端口没有被占用。

一个修改后的ollama服务配置片段示例如下：

ollama: image: ollama/ollama:latest container_name: ollama ports: - "11434:11434" volumes: - ~/.ollama:/root/.ollama # 将模型数据持久化到本地 command: serve # 容器启动后，我们另外拉取模型，不在这里阻塞启动。

修改并保存好docker-compose.yml后，就可以启动了。

# 在后台启动服务 docker-compose up -d

首次启动会拉取镜像，需要一些时间。使用docker-compose logs -f khoj可以查看实时日志，确认服务是否正常启动。

3.2 核心配置：连接你的知识库

服务启动后，打开浏览器访问http://localhost:42110，你会看到 Khoj 的配置界面。首次使用，我们需要完成两个核心配置：内容源和AI 模型。

配置内容源：在左侧导航栏点击 “Configure” -> “Content”。这里就是告诉 Khoj 你的知识藏在哪。点击 “Add Source”。

• 类型选择：最常用的是 “Files”（本地文件目录）和 “Github Repository”。我以 “Files” 为例。
• 路径设置：输入你本地知识库的绝对路径，例如/Users/YourName/Documents/MyNotes。注意：由于 Docker 容器的隔离性，容器内的进程无法直接访问宿主机的/Users/...路径。这就是为什么之前要在docker-compose.yml中为khoj服务也添加一个卷挂载，将宿主机的笔记目录映射到容器内。 你需要在docker-compose.yml的khoj服务下添加类似配置：

  volumes: - ~/khoj-data:/usr/src/app/data # 应用数据 - ~/Documents/MyNotes:/my-notes # 将你的笔记目录挂载到容器内的 /my-notes

  然后，在 Khoj 的配置界面，内容源路径就应该填写容器内的路径/my-notes。
• 文件类型：可以全选，Khoj 会自动识别。支持.md,.org,.pdf,.html, 图片文件等。
• 索引频率：可以选择 “实时监控”（Watch for changes），这样当你新增或修改笔记后，Khoj 会自动更新索引，非常方便。

点击 “Save”，Khoj 就会开始索引你的文档。首次索引大量文件可能需要几分钟到几十分钟，取决于文件数量和你的硬件性能。你可以在 “Configure” -> “Processor” 页面查看索引进度。

配置 AI 模型：点击 “Configure” -> “Processor”。在 “Conversation Processor” 部分，选择 “Configure”。

• 模型类型：选择 “Ollama”（如果你按上述方式部署了）。
• API 端点：因为ollama和khoj在同一个 Docker 网络下，你可以直接使用服务名作为主机名，填写http://ollama:11434。
• 模型名称：填写你在 Ollama 中拉取的模型名，例如llama3.2:3b。

关键提示：在配置模型前，你需要先通过 Ollama 拉取模型。由于我们的 Ollama 也在容器中，需要进入容器执行命令：

docker exec -it ollama ollama pull llama3.2:3b

这会下载约 2GB 的模型文件。你也可以选择其他模型，如mistral:7b,qwen2.5:3b等，模型越大，能力越强，所需内存也越多。

保存模型配置后，回到主聊天界面，你就可以开始和你的知识库对话了。

3.3 高级配置与优化技巧

基础功能跑通后，一些优化配置能极大提升体验。

1. 使用更强大的本地模型：llama3.2:3b是入门之选。要获得更好的推理和写作能力，可以升级到 7B 甚至更大模型。你需要确保宿主机有足够的内存（运行 7B 量化模型建议 16GB 以上系统内存）。拉取命令类似：docker exec -it ollama ollama pull llama3.1:7b。然后在 Khoj 配置中修改模型名即可。注意，首次切换模型时，Khoj 可能需要一点时间加载。

2. 配置混合模式（在线+离线）：你可以在 Khoj 的 “Conversation Processor” 配置中，添加多个模型配置。例如，配置一个本地的llama3.2:3b作为默认快速响应模型，再配置一个 OpenAI GPT-3.5 Turbo 的 API 作为备选。在聊天界面，你可以通过下拉菜单或命令快速切换。这样，在需要生成高质量文案、复杂代码时，可以临时切换到更强大的云模型。

3. 优化索引性能：如果你的知识库非常大（数万个文件），索引可能会很慢或占用过高内存。你可以：

• 在 “Content Source” 配置中，通过 “Filters” 排除一些不必要的目录，比如node_modules,.git, 缓存文件夹等。
• 调整索引的 “Chunk Size”（文本块大小）和 “Chunk Overlap”（重叠量）。较小的块（如 256 tokens）检索更精准，但会生成更多向量；较大的块（如 512 tokens）能提供更多上下文，但可能包含无关信息。通常 384-512 是一个平衡点。重叠量设为块大小的 10%-20% 有助于避免在块边界丢失重要信息。
• 索引是一个后台任务，首次全量索引后，后续的增量更新（Watch模式）开销很小，不用担心。

4. 深度集成：将 Khoj 嵌入你的工作流

仅仅通过 Web 界面使用 Khoj 有些割裂。它的威力在于与现有工具的深度集成。这里我重点介绍与 Obsidian 和 VS Code 的集成。

4.1 与 Obsidian 的无缝融合

对于 Obsidian 用户来说，Khoj 插件是“神器”级别的存在。它让你在笔记软件内部直接拥有一个 AI 助手。

安装与配置：在 Obsidian 中，进入 “设置” -> “社区插件” -> “浏览”，搜索 “Khoj” 并安装。启用插件后，你会在左侧边栏看到一个 Khoj 的图标。 配置非常简单，主要就是填写 Khoj 服务器的地址。如果你在本机用 Docker 运行，地址就是http://localhost:42110。插件会自动测试连接。

核心使用场景：

1. 对话式搜索：点击插件图标，打开聊天面板。你可以直接问：“我去年写的关于‘用户增长’的思路有哪些？” Khoj 会检索所有相关笔记，并用模型总结出答案，并附上引用来源。点击引用可以直接跳转到原文，这对于追溯信息源头至关重要。
2. 笔记生成与续写：在编辑笔记时，你可以选中一段文字，右键选择 “Khoj: Chat with selected text”。这样，你的选文就成为了对话的上下文。你可以让它总结、扩写、翻译或基于此提问。比如，选中一段项目需求，让它“生成一份对应的测试用例清单”。
3. 每日摘要：Khoj 插件可以配置为每天自动检索你过去 24 小时新建或修改的笔记，并生成一个摘要，帮助你回顾工作。这个功能对于每日复盘极其有用。
4. 语义搜索替换全局搜索：你甚至可以尝试用 Khoj 的语义搜索来替代 Obsidian 自带的全文搜索，因为它更能理解你的意图。比如搜索“如何解决内存泄漏”，它不仅能找到包含这个词组的笔记，还能找到讨论“垃圾回收”、“引用计数”等相关概念的笔记。

4.2 在 VS Code 中召唤 AI 助手

对于开发者，在 IDE 里直接查询知识库或获取代码建议是高频需求。Khoj 也提供了 VS Code 插件。

安装与配置：在 VS Code 扩展商店搜索 “Khoj” 安装。安装后，你需要配置服务器地址（同样是http://localhost:42110）。配置好后，你可以通过命令面板（Ctrl+Shift+P）输入 “Khoj” 来找到相关命令，或者会在侧边栏看到一个活动栏图标。

开发者专属用法：

1. 代码库知识问答：如果你将项目代码库（尤其是文档、注释丰富的代码）索引到 Khoj，你可以直接问：“我们这个项目里处理用户认证的模块是怎么设计的？”或者“utils.py里的format_date函数接受什么参数？”它可以从代码注释和文档字符串中找出答案。
2. 基于上下文的代码生成：在编辑器里选中一段代码或错误信息，通过右键菜单或命令调用 Khoj，可以询问：“如何优化这段循环？”或“这个错误通常是什么原因引起的？”由于 Khoj 的上下文包含了你的知识库，它的建议可能比通用 Copilot 更贴合你的项目规范和过往经验。
3. 技术文档速查：如果你把常看的技术文档（如 React 官方文档、Python 标准库文档的离线版）也做了索引，那就相当于在 VS Code 里集成了一个超强的技术文档助手，比切屏到浏览器搜索快得多。

实操心得：不要试图一次性索引所有东西。先从一个小而精的目录开始，比如你当前最活跃的项目笔记文件夹。体验顺畅后，再逐步扩大范围。同时，定期检查 Khoj 的 “Configure” -> “Processor” 页面，看看索引是否成功，有没有报错（比如不支持的文件格式、权限问题）。一个健康运行的 Khoj，其索引进程应该是安静且持续的。

5. 常见问题排查与性能调优实录

在实际使用中，你肯定会遇到一些坑。以下是我和社区其他用户遇到过的一些典型问题及解决方案。

5.1 部署与连接问题

问题1：Docker 容器启动失败，端口冲突。

• 现象：运行docker-compose up -d后，使用docker-compose ps发现 khoj 或 ollama 状态是Exit。
• 排查：运行docker-compose logs khoj查看具体错误。常见错误是port is already allocated。
• 解决：修改docker-compose.yml中的端口映射，比如将42110:42110改为42111:42110（宿主机端口改为 42111）。或者用lsof -i :42110命令找出占用端口的进程并停止它。

问题2：Khoj Web 界面能打开，但无法连接 Ollama 模型。

• 现象：在 Khoj 的 “Processor” 配置中测试 Ollama 连接，显示失败。
• 排查：
  1. 确认 Ollama 容器正在运行：docker-compose ps | grep ollama。
  2. 进入 Khoj 容器内部测试连接：docker exec -it khoj-khoj-1 curl http://ollama:11434/api/tags。如果返回 Ollama 的模型列表 JSON，说明网络是通的。
  3. 如果上一步失败，检查docker-compose.yml中是否使用了自定义网络，或者khoj服务中links或depends_on配置是否正确。最简单的办法是确保两个服务在同一个默认的 Docker Compose 网络下（默认就会创建）。
• 解决：确保 Khoj 配置中的 API 端点填写正确。在 Docker Compose 环境下，应使用服务名http://ollama:11434，而不是localhost。

问题3：内容源索引失败，提示“Permission denied”或找不到文件。

• 现象：添加文件内容源后，处理器状态一直显示错误，日志显示权限或路径问题。
• 排查：这是 Docker 挂载卷权限的经典问题。容器内的进程（通常以非 root 用户运行）可能没有权限读取你挂载的宿主机目录。
• 解决：
  1. （Linux/Mac 推荐）在宿主机上，将你的笔记目录权限设置为755：chmod -R 755 ~/Documents/MyNotes。
  2. （快速但不够安全）修改docker-compose.yml，让 khoj 容器以 root 用户运行。在khoj服务下添加user: root。但这会降低安全性，仅作临时测试。
  3. 检查挂载的源路径在容器内是否存在。可以通过docker exec -it khoj-khoj-1 ls -la /my-notes来验证。

5.2 性能与使用优化

问题4：模型响应速度非常慢。

• 现象：每次问答都需要等待 10 秒以上。
• 排查与解决：
  1. 模型大小：首先检查你使用的模型。7B 模型比 3B 模型慢，非量化模型比量化模型（如-q4_0）慢得多。对于大多数知识问答场景，一个 3B 或 7B 的 4-bit 量化模型在 CPU 上也能在几秒内响应。使用docker exec -it ollama ollama list查看已拉取模型的详细信息，确保你用的是量化版。
  2. 硬件资源：运行docker stats查看容器 CPU 和内存占用。如果内存不足，系统会使用交换分区，导致急剧变慢。考虑关闭其他占用内存大的程序，或换用更小的模型。
  3. 上下文长度：Khoj 检索到的上下文文本会连同你的问题一起发送给模型。如果索引的文本块（Chunk）设置得太大，或者一次检索了太多片段（默认是4个），会导致提示词非常长，拉慢推理速度。可以在 Khoj 配置的 “Search Processor” 中调小 “Number of results to use”（检索结果数量），比如从 4 调到 2。

问题5：回答质量不高，感觉“没读懂”我的笔记。

• 现象：Khoj 的回答泛泛而谈，没有精准结合我笔记中的具体内容。
• 排查与解决：
  1. 索引质量：这是最常见的原因。语义搜索的效果极度依赖于文本嵌入（向量化）的质量。确保你的笔记是结构化的纯文本。对于 PDF 文件，Khoj 会尝试提取文字，但如果 PDF 是扫描版图片，则需要 OCR 功能（目前 Khoj 通过 Tesseract 支持，但需要额外配置）。可以尝试在 Khoj 的搜索界面（非聊天）直接用关键词搜索，看能否找到正确的文档片段。如果搜索都不准，聊天就更难了。
  2. 检索相关性：调整 “Search Processor” 中的 “Similarity threshold”（相似度阈值）。调高这个值（如从 0.2 到 0.3）会让检索更“严格”，只返回相关性非常高的片段，避免无关信息干扰模型。
  3. 提示词工程：Khoj 发送给模型的提示词是预设的。虽然用户不能直接修改，但你可以通过提问方式来引导。比如，在问题中明确指定来源：“根据我笔记中关于‘敏捷开发会议’的部分，总结一下站会的主要议程。” 这比单纯问“站会议程是什么？”效果更好。
  4. 模型能力：如果索引和检索都正常，那可能是模型本身的理解和归纳能力有限。尝试切换到能力更强的模型（如从 3B 到 7B，或启用在线 GPT API）进行对比测试。

问题6：如何备份和迁移我的 Khoj 数据？

• 操作：Khoj 的所有数据都保存在你挂载的data目录下（我们之前配置的~/khoj-data）。这个目录下通常有chroma.db（向量数据库）、khoj.db（应用数据库）、models（缓存的嵌入模型）等子目录。
• 备份：直接复制整个~/khoj-data目录即可。
• 迁移：在新机器上部署好 Docker 和docker-compose.yml文件后，将备份的khoj-data目录放到对应位置，并确保docker-compose.yml中的卷挂载路径指向它。启动服务后，你的所有索引和聊天历史就都恢复了。注意：如果宿主机操作系统或架构发生变化（如从 Intel Mac 换到 ARM Mac），本地缓存的某些模型文件可能需要重新下载，但向量数据库通常是兼容的。

6. 安全考量与进阶玩法

将个人全部知识库交给一个自托管应用，安全是重中之重。Khoj 在这方面做得相当不错，但仍有几点需要你注意。

网络访问控制：默认情况下，Khoj 的 Web 服务（端口 42110）绑定在0.0.0.0，意味着同一局域网内的其他设备也能访问。如果你在办公室或公共网络，这存在风险。

• 解决方案：修改docker-compose.yml中 khoj 服务的端口映射，将42110:42110改为127.0.0.1:42110:42110。这样服务就只监听本机（localhost），杜绝了外部访问。如果你需要在局域网内其他设备访问，可以考虑搭配一个安全的反向代理（如 Nginx 配置 HTTPS 和密码认证），或者使用 SSH 隧道进行端口转发。

模型安全：即使是本地运行的开源模型，也并非绝对安全。模型可能在其训练数据中带有偏见，或在某些提示下产生不受欢迎的内容。选择来自可信赖机构（如 Meta, Mistral AI, 01.ai）的知名模型，并关注其许可协议。

数据加密：Khoj 的索引数据以明文形式存储在硬盘上。虽然别人需要直接访问你的硬盘才能获取，但对于有全盘加密需求的用户，确保~/khoj-data目录所在的分区启用了系统级的加密（如 macOS 的 FileVault，Windows 的 BitLocker，Linux 的 LUKS）。

进阶玩法：打造专属智能体Khoj 的潜力不止于问答。通过其 API（运行后可在http://localhost:42110/api/docs查看），你可以将其集成到自动化工作流中。

• 自动化日报生成：写一个脚本，定时（如每天下午6点）调用 Khoj 的搜索 API，检索你当天修改过的笔记，然后调用对话 API，让其“总结我今天的工作进展和明日计划”，最后将结果通过邮件或消息应用发送给你。
• 项目知识门户：如果你管理一个团队，可以将团队共享的文档库（如 Confluence 导出、项目文档）索引到 Khoj，并部署在一个内部服务器上。团队成员就可以通过一个简单的界面，用自然语言查询项目历史、设计决策、技术规范等，比传统 Wiki 搜索高效得多。
• 结合自动化工具：通过 Zapier 或 n8n 等工具，监听你的笔记软件（如 Obsidian）的文件更新事件，触发 Khoj 重新索引该文件，实现真正的实时知识同步。

经过一段时间的深度使用，Khoj 已经从我的一个“实验性玩具”变成了不可或缺的生产力基石。它解决的不是“搜索”问题，而是“知识激活”问题。那些沉寂在文件夹深处的笔记，重新变得鲜活可用。最大的体会是，与其追求一个功能大而全的 AI 产品，不如像 Khoj 这样，聚焦于一个核心场景（个人知识管理），并将其与你的现有工具生态（Obsidian, VS Code）深度打通，这种“小而美”的集成带来的效率提升是颠覆性的。如果你也受困于信息碎片化和知识检索难，不妨花上一个下午，按照上面的步骤部署属于你自己的 Khoj，开始构建真正为你所用的“第二大脑”。