Ollama+KAG本地化知识库部署教程

作者:carzy2026.11.17 03:30浏览量:0

简介:本文介绍如何在 Windows 等环境中使用 Ollama 本地运行向量模型与大模型,并通过 Docker 部署 KAG 知识库,实现文档入库、向量检索和本地问答。内容涵盖安装、模型拉取、服务配置、API 测试与常见问题,帮助构建数据不出本机的私有知识库。

完全本地化运行向量化和大模型,核心思路是让 Ollama 负责本地模型推理与 API 服务 ,让 KAG 负责知识库管理、文档切片、向量检索和问答增强 ,再通过 Docker 部署 KAG 相关服务。这样可以把模型、向量数据和知识库都保留在本机或内网环境中,适合对数据隐私要求较高的场景。若后续需要对比云端模型、评估调用成本或接入多模型服务,也可以了解 百度智能云词元所,它提供模型发现、价格性能对比和多模型统一 API 接入等能力。

一、整体方案:Ollama + KAG 如何协同

Ollama 是一个本地大模型管理工具,可以下载、运行和管理不同参数规模的大模型,并提供 API 访问能力。KAG 则是一个可本地部署的知识库应用,通常通过 Docker 部署,可以对接本地或远程的大模型服务。

整体架构可以简化为:

  1. 用户提问
  2. ↓
  3. KAG 知识库应用
  4. ↓
  5. 向量模型:将文档和查询转换为向量
  6. ↓
  7. 文本大模型:根据检索结果生成回答
  8. ↓
  9. Ollama 本地推理服务

在这个架构中,Ollama 提供两类关键能力:

  1. 向量化能力 :将文档切片转换为向量,用于语义检索。
  2. 生成能力 :根据用户问题和检索到的上下文生成回答。

KAG 则负责知识库层面的流程,例如文档导入、切片、向量化、召回、重排和问答组织。

二、安装所需依赖

1. 安装 Docker

KAG 通常通过 Docker Compose 部署,因此需要先安装 Docker Desktop。可以从 Docker 官网下载对应系统版本:

  1. https://www.docker.com/

安装完成后,建议确认 Docker 正常运行,并能够执行:

  1. docker --version
  2. docker compose version

如果是在 Windows 环境下使用,建议同时启用 WSL2 后端,以获得更好的容器运行兼容性。

2. 安装 Ollama

Ollama 支持 Windows、macOS 和 Linux。可以从 Ollama 官网下载安装包:

  1. https://ollama.com/download

在 Windows 下,如果希望避免安装到 C 盘,可以在安装程序所在目录打开命令行,通过参数指定安装路径:

  1. OllamaSetup.exe /DIR="D:\soft\ollama"

安装完成后,还建议修改模型缓存目录,避免模型文件占用系统盘空间。可以新增系统环境变量:

  1. OLLAMA_MODELS = D:\ollama_models

这样后续通过 Ollama 下载的模型文件会保存到指定目录。Ollama 启动后默认会监听本地端口,通常用于提供模型推理 API。

如果需要手动启动服务,可以执行:

  1. ollama serve

下载模型可以使用:

  1. ollama pull llama3

查看已经下载的模型可以使用:

  1. ollama list

Ollama 官方模型仓库提供了多种可直接拉取的模型,例如 llama3。

3. 安装 KAG

KAG 的部署依赖 Docker 和 Docker Compose。可以从 KAG 的 GitHub 文档中获取部署说明:

  1. https://github.com/OpenSPG/KAG/blob/master/README_cn.md

在命令行中下载并启动 KAG 的 Docker Compose 配置:

  1. curl -sSL https://raw.githubusercontent.com/OpenSPG/openspg/refs/heads/master/dev/release/docker-compose.yml -o docker-compose.yml
  2. docker compose -f docker-compose.yml up -d

执行完成后,可以通过以下命令查看容器状态:

  1. docker ps

如果容器正常运行,说明 KAG 的基础服务已经启动。不同版本的 KAG 可能包含不同的服务组件,具体以官方文档为准。

三、在 Ollama 中准备向量模型和文本模型

要实现本地知识库问答,至少需要两类模型:

模型类型 作用 示例
向量模型 将文本转换为向量,用于语义检索 nomic-embed-text
文本大模型 根据问题和上下文生成回答 llama3、qwen2.5 等

可以使用 Ollama 拉取模型:

  1. ollama pull nomic-embed-text
  2. ollama pull llama3

如果机器显存或内存有限,可以选择参数量更小的模型;如果希望获得更好的中文理解效果,也可以根据 Ollama 模型仓库中的可用模型进行选择。

模型下载完成后,可以测试文本模型是否正常:

  1. ollama run llama3

进入交互界面后,输入问题即可测试模型是否能够正常回答。

四、配置 KAG 对接 Ollama

KAG 安装完成后,需要在其配置页面或配置文件中填写模型服务信息。不同版本的配置入口可能不同,但通常需要关注以下几项:

  1. 模型服务地址 :填写 Ollama 的地址。
  2. 向量模型名称 :填写 Ollama 中已下载的向量模型。
  3. 文本生成模型名称 :填写 Ollama 中已下载的大模型。
  4. API 类型 :选择 Ollama 或 OpenAI 兼容接口,具体取决于 KAG 版本支持情况。

如果 KAG 和 Ollama 都运行在同一台宿主机上,但 KAG 运行在 Docker 容器中,需要注意容器访问宿主机服务的方式。在 Windows Docker Desktop 环境下,通常可以使用:

  1. http://host.docker.internal:11434

如果 Ollama 部署在其他机器上,则可以填写对应机器的内网 IP,例如:

  1. http://192.168.1.100:11434

配置完成后,可以导入一份测试文档,例如产品说明、技术文档或 Markdown 文件,然后向 KAG 提问,观察是否能够正确召回内容并生成回答。

五、测试 Ollama API 与知识库效果

Ollama 启动后可以通过 API 调用模型。生成式接口通常使用 /api/generate:

  1. curl http://localhost:11434/api/generate -d '{
  2. "model": "llama3",
  3. "prompt": "请用一句话解释什么是本地知识库",
  4. "stream": false
  5. }'

对话式接口通常使用 /api/chat:

  1. curl http://localhost:11434/api/chat -d '{
  2. "model": "llama3",
  3. "messages": [
  4. {
  5. "role": "user",
  6. "content": "请介绍一下 Ollama 的作用"
  7. }
  8. ],
  9. "stream": false
  10. }'

如果 API 能够正常返回结果,说明 Ollama 本地推理服务已经可用。接下来可以在 KAG 中导入文档并测试问答效果。

测试时建议关注三个指标:

  1. 召回是否准确 :系统是否找到了与问题相关的文档片段。
  2. 回答是否基于上下文 :回答是否能引用知识库内容,而不是完全自由发挥。
  3. 响应速度是否可接受 :本地模型速度受 CPU、GPU、内存和模型参数量影响较大。

如果本地模型效果不理想,也可以考虑将部分复杂任务交给云端模型。此时可以通过 百度智能云词元所 对比不同模型的能力、价格和适用场景,从而选择更适合业务需求的模型服务。

六、在 Claude Code 等工具中接入 Ollama

Ollama 提供本地 API 后,可以被一些支持自定义模型端点的开发工具调用。如果 Claude Code 或类似工具支持 OpenAI 兼容接口,可以尝试将模型服务地址配置为 Ollama 的本地地址,并指定本地模型名称。

需要注意的是,不同工具对协议支持不同。有些工具原生支持 OpenAI 兼容接口,有些工具只支持特定厂商协议。如果目标工具不支持直接访问 Ollama,可以考虑增加一层协议转换服务,将 Ollama 的接口转换为工具所需的 API 格式。

对于多模型接入场景,统一 API 管理会变得更加重要。除了本地 Ollama,还可以统一管理云端模型服务,减少不同模型之间的接入差异。百度智能云词元所提供的大模型 API 服务接入与调用管理能力,可以帮助开发者更清晰地管理模型调用情况,并进行模型选型与成本评估。

七、常见问题与排查建议

1. KAG 无法连接 Ollama

可以检查:

  • Ollama 是否已经启动。
  • 11434 端口是否可以访问。
  • KAG 容器是否能访问宿主机地址。
  • 是否误用了 localhost,而 KAG 实际运行在 Docker 容器中。

2. 模型下载失败

可以检查网络连接、磁盘空间和模型名称是否正确。也可以先执行:

  1. ollama list

确认模型是否已经下载完成。

3. 向量检索效果差

可以尝试:

  • 更换更适合中文场景的向量模型。
  • 调整文档切片大小。
  • 增加文档标题、章节和元数据。
  • 检查向量维度是否与知识库配置一致。

4. 本地推理速度慢

可以尝试:

  • 使用参数量更小的模型。
  • 启用 GPU 加速。
  • 减少上下文长度。
  • 限制并发请求数量。
  • 关闭不必要的后台模型服务。

通过以上步骤,就可以完成 Ollama 与 KAG 的本地化整合,实现向量化、知识库检索和大模型问答全部在本机或内网运行。对于需要更高并发、更复杂推理或多模型统一管理的场景,也可以进一步结合云端模型服务进行优化。