Khoj 知识库配置怎么让本地文档可被检索问答

Khoj 知识库配置的本质，是让 Khoj 能读取你指定的文档或笔记，并把这些内容切分、向量化后存入索引，之后才能在对话或搜索中被检索到。
本文以本地 Docker 部署为例，说明从启动服务到验证检索效果的完整流程；
如果你使用云端托管版，界面入口类似，但不需要自己维护容器和模型服务。

先确认运行环境和可用的模型来源

Khoj 需要一个大语言模型来生成回答，也需要嵌入模型来处理文档向量。
本地部署时，这两者可以指向 OpenAI 兼容接口，也可以使用 Ollama 等本地模型服务。
开始前先确认：

• 服务器已安装 Docker 和 Docker Compose，并且当前用户有权限执行 docker 命令。
• 准备一个可用的模型 API Key，或者在本机或内网运行了 Ollama 并拉取了对话模型和嵌入模型。
• 规划好数据目录，例如 /opt/khoj/data，避免容器重建后索引丢失。
• 确认要导入的文档格式，Khoj 常见支持 Markdown、纯文本、PDF 和 Org 文件，扫描版 PDF 需要先做 OCR 才有文字可索引。

如果模型服务在另一台机器上，先保证 Khoj 容器能访问该地址，例如 http://192.168.1.10:11434，不要填 localhost，否则容器内会指向自己。

启动 Khoj 服务并完成基础设置

在服务器上创建目录并进入：

mkdir -p /opt/khoj && cd /opt/khoj

新建 docker-compose.yml，下面是一个最小可运行示例，模型地址和密钥按实际替换：

services:
  khoj:
    image: ghcr.io/khoj-ai/khoj:latest
    ports:
      - "42110:42110"
    volumes:
      - ./data:/data
    environment:
      - KHOJ_DJANGO_SECRET_KEY=替换为随机长字符串
      - OPENAI_API_KEY=替换为你的密钥
      - KHOJ_OPENAI_API_BASE_URL=https://api.openai.com/v1
    restart: unless-stopped

如果使用 Ollama，把 OPENAI_API_KEY 保留为任意占位值，并将 KHOJ_OPENAI_API_BASE_URL 改为 http://你的Ollama地址:11434/v1。
启动容器：

docker compose up -d
docker compose logs -f khoj

日志出现监听 42110 端口且没有持续报错后，浏览器访问 http://服务器IP:42110。
首次进入需要创建管理员账号，这个账号只保存在本地数据库中。

配置内容来源并触发索引

登录后进入设置页面，找到内容或知识库相关入口，按来源类型添加：

• 本地文件：填写容器内可访问的目录路径，例如 /data/docs。需要先把文档放进宿主机 /opt/khoj/data/docs，容器内对应 /data/docs。
• GitHub 仓库：填写仓库地址和分支，私有仓库需要提供访问令牌。
• Notion 或 Obsidian：按页面提示授权或填写导出目录，注意只选择需要检索的页面，避免把无关内容全部索引。

添加后点击重新索引或同步按钮。
索引过程会在后台运行，可以在日志中观察进度：

docker compose logs -f khoj | grep -i index

索引完成后，在对话界面输入一个只有你的文档里才有的问题，例如文档中某个内部项目名称，观察回答是否引用了对应内容。
如果回答为空或明显没有用到文档，先检查索引是否完成，再检查文件路径是否在容器内真实存在：

docker compose exec khoj ls /data/docs

容易踩坑的几个配置点

路径写成了宿主机路径。 容器内只能看到挂载进去的目录，填写 /opt/khoj/data/docs 在容器内通常不存在，应填 /data/docs。

修改配置后没有重新索引。 新增文件或修改内容来源后，需要手动触发同步，否则索引仍是旧数据。

嵌入模型和对话模型混用。 嵌入模型负责把文档转成向量，对话模型负责生成回答，两者可以不同，但嵌入模型一旦更换，旧索引可能需要重建。

端口或防火墙未放行。 本机访问正常但远程打不开时，检查云服务器安全组和系统防火墙是否放行 42110。

密钥泄露风险。 KHOJ_DJANGO_SECRET_KEY 和模型 API Key 不要提交到公开仓库，建议用 .env 文件管理并限制文件权限。

验证知识库是否真正生效

完成上述步骤后，用三个动作确认配置结果：

1. 在搜索框输入文档中的专有名词，看是否能返回相关片段，而不是通用回答。
2. 在对话中要求“根据我的文档回答”，观察回答是否附带来源或引用内容。
3. 新增一个测试文件后重新索引，确认新内容能被检索到。

如果三项都通过，说明 Khoj 知识库配置基本完成。
后续维护重点是定期同步内容来源、关注索引日志中的失败记录，以及在更换模型时评估是否需要重建索引。

常见疑问

Khoj 支持直接上传单个文件吗？ 部分版本在界面上提供文件上传入口，但更稳妥的方式是把文件放进挂载目录并按目录索引，这样容器重建后内容不会丢。

索引很慢或卡住怎么办？ 先看日志是否在调用嵌入模型，再确认模型服务地址和密钥是否正确。
大文档可以拆分成较小文件后分批索引。

必须用 OpenAI 吗？ 不是。
只要模型服务兼容 OpenAI 接口，就可以把地址指向本地或内网服务，具体支持范围以你使用的 Khoj 版本实际表现为准。