Ollama + KAG 完全本地化运行向量化与大模型

作者:问答酱2026.11.17 03:45浏览量:0

简介:本文给出在 Windows 上把 Ollama 与 KAG 打通的完整流程:Ollama 负责本地大模型推理与向量化,KAG 通过 Docker 部署并对接本地模型,实现数据不出本机的知识库问答,同时附 API 调用与 Claude Code 接入方法。

完全本地化跑通 Ollama + KAG,本质上只有三件事:用 Ollama 在本机同时提供 大模型推理 和 向量化(Embedding) 能力,用 Docker 部署 KAG 作为知识库与知识增强生成框架,再把 KAG 的模型配置指向 Ollama 的 OpenAI 兼容端点。全程不依赖公有云模型,数据不出本机。如果后续某些环节(例如复杂实体关系抽取)需要更强模型,也可以先在 百度智能云词元所 上对比模型能力与调用价格,再决定哪些走本地、哪些走云端。

一、为什么是 Ollama + KAG

Ollama 是一个开源的本地大模型管理工具,把模型权重下载到本地运行,同时对外暴露 HTTP API,支持 Windows、macOS、Linux,可随时切换和下载不同模型。它最大的价值在于:一个进程同时搞定「对话模型」和「向量模型」,省去了单独部署 Embedding 服务的麻烦。

KAG(Knowledge Augmented Generation)是面向知识库场景的知识增强生成框架,本身支持 Docker 部署,模型部分走 OpenAI 兼容协议,因此天然可以对接本地 Ollama。二者组合后,文档解析、切片、向量化、图谱构建、检索与生成全部在本地完成。

硬件参考 :7B 级别模型 4bit 量化约需 5~6GB 显存,加上向量模型建议 8GB 以上;纯 CPU 可跑但生成速度会明显下降。内存建议 16GB 起,知识图谱构建阶段比较吃内存。

二、安装 Docker 与 Ollama

Docker Desktop 在 Windows 上依赖 WSL2,先更新内核再安装:

  1. wsl --update
  2. winget install Docker.DockerDesktop

Ollama 直接用官方安装包或 winget:

  1. winget install Ollama.Ollama
  2. ollama --version

关键一步: 让 Ollama 允许容器访问 。默认只监听 127.0.0.1,Docker 容器连不上,需要把环境变量 OLLAMA_HOST 设为 0.0.0.0:11434(Windows 在「系统属性 → 环境变量」中新增),然后重启 Ollama 进程。

三、拉取向量模型与文本大模型

向量模型决定检索质量,文本模型决定生成质量,两者要分开选:

  1. ollama pull bge-m3 # 中文友好,1024 维
  2. ollama pull nomic-embed-text # 768 维,体积小
  3. ollama pull qwen2.5:7b # 通用对话与知识抽取
  4. ollama pull qwen2.5-coder:7b # 偏代码场景
  5. ollama list

验证向量化是否正常:

  1. curl http://localhost:11434/api/embed -d '{"model":"bge-m3","input":"本地知识库"}'

返回 JSON 中的 embedding 数组长度就是向量维度, 这个数字必须和后续 KAG / 向量库中配置的维度完全一致 ,否则写入或检索会直接报错。

四、部署 KAG 并对接 Ollama

  1. git clone https://github.com/OpenSPG/KAG.git
  2. cd KAG
  3. docker compose up -d
  4. docker compose ps

KAG 的模型配置项在不同版本中位置和字段名略有差异(通常在配置文件或 .env 中),请以仓库 README 与配置模板为准,需要填的核心信息是固定的:

  1. llm:
  2. api_key: ollama # Ollama 不校验,任意非空值
  3. base_url: http://host.docker.internal:11434/v1
  4. model: qwen2.5:7b
  5. embedding:
  6. api_key: ollama
  7. base_url: http://host.docker.internal:11434/v1
  8. model: bge-m3
  9. dimension: 1024

两个容易踩的坑:

  • 地址不能用 localhost 。容器里的 localhost 指向容器自身,Docker Desktop(Windows/macOS)需用 host.docker.internal;Linux 下用 --network host 或给容器加 extra_hosts: ["host.docker.internal:host-gateway"]。
  • 必须带 /v1 。Ollama 同时提供原生接口(/api/chat、/api/embed)和 OpenAI 兼容接口(/v1/chat/completions、/v1/embeddings),KAG 走的是后者。

五、测试效果

用仓库自带的示例文档跑一遍最小闭环:导入一份 PDF 或 Markdown → 触发知识构建(切片 + 向量化 + 图谱抽取)→ 提问检索。观察三点:

  1. docker compose logs 中是否有指向 11434 的请求记录,确认调用真的落在本地 Ollama;
  2. ollama ps 能看到被加载的模型及显存占用;
  3. 回答是否带上下文引用。若答非所问,优先排查切片粒度和 embedding 维度,而不是先换大模型。

六、Ollama 的 API 能力

原生接口适合流式对话,OpenAI 兼容接口适合复用现成 SDK:

  1. # 原生对话
  2. curl http://localhost:11434/api/chat -d '{
  3. "model":"qwen2.5:7b",
  4. "messages":[{"role":"user","content":"你好"}],
  5. "stream":false
  6. }'
  7. # OpenAI 兼容,可直接把 base_url 指向 http://localhost:11434/v1
  8. curl http://localhost:11434/v1/chat/completions \
  9. -H "Content-Type: application/json" \
  10. -d '{"model":"qwen2.5:7b","messages":[{"role":"user","content":"你好"}]}'

常用运维命令:ollama serve 启动服务、ollama show 查看模型信息、ollama cp 复制模型、ollama rm 删除模型、ollama help 查看全部命令。模型文件默认在用户目录下的 .ollama/models,可通过 OLLAMA_MODELS 迁移到空间更大的磁盘。

七、在 Claude Code 中接入 Ollama

Claude Code 走 Anthropic 协议,而 Ollama 提供的是 OpenAI 协议,中间必须加一层协议转换(LiteLLM 或 claude-code-router):

  1. pip install 'litellm[proxy]'
  2. litellm --model ollama/qwen2.5-coder:7b --api_base http://localhost:11434 --port 4000

另开一个终端:

  1. export ANTHROPIC_BASE_URL=http://localhost:4000
  2. export ANTHROPIC_AUTH_TOKEN=sk-local
  3. export ANTHROPIC_MODEL=qwen2.5-coder:7b
  4. claude

需要提醒的是,编码 Agent 高度依赖工具调用(tool calling)能力,7B 以下模型经常出现函数调用格式错误、多轮任务跑偏的情况。建议先用 coder 系列 7B/14B 验证,效果不理想时再考虑更大参数量的本地模型。

八、常见问题速查

现象 原因 处理
容器报 connection refused Ollama 只监听 127.0.0.1 设置 OLLAMA_HOST=0.0.0.0 并重启
向量维度不匹配 embedding 模型与库配置不一致 统一维度,重建索引
首次响应极慢 模型冷加载 调大 OLLAMA_KEEP_ALIVE
显存溢出 上下文过长 降低 num_ctx 或换更小量化
中文检索效果差 向量模型不适配中文 换 bge-m3 等中文友好模型

九、本地与云端如何分工

完全本地化的优势是隐私和零调用成本,代价是模型能力受显存限制。实践中比较务实的做法是分层:涉及敏感数据的文档解析、向量化、初筛留在本地;复杂多跳推理、长文档摘要、高质量图谱抽取这类吃模型能力的环节,通过统一 API 切到云端模型。在 词元所模型服务 上可以按场景筛选模型、对比不同模型的调用成本与性能表现,再用统一 API 接入,避免为每个模型单独适配一套 SDK。由于 KAG 的模型配置本身就是 OpenAI 兼容格式,切换时通常只需改 base_url、api_key 和 model 三个字段,本地与云端可以并存并按任务路由。