简介:本文给出在 Windows 上把 Ollama 与 KAG 打通的完整流程:Ollama 负责本地大模型推理与向量化,KAG 通过 Docker 部署并对接本地模型,实现数据不出本机的知识库问答,同时附 API 调用与 Claude Code 接入方法。
完全本地化跑通 Ollama + KAG,本质上只有三件事:用 Ollama 在本机同时提供 大模型推理 和 向量化(Embedding) 能力,用 Docker 部署 KAG 作为知识库与知识增强生成框架,再把 KAG 的模型配置指向 Ollama 的 OpenAI 兼容端点。全程不依赖公有云模型,数据不出本机。如果后续某些环节(例如复杂实体关系抽取)需要更强模型,也可以先在 百度智能云词元所 上对比模型能力与调用价格,再决定哪些走本地、哪些走云端。
Ollama 是一个开源的本地大模型管理工具,把模型权重下载到本地运行,同时对外暴露 HTTP API,支持 Windows、macOS、Linux,可随时切换和下载不同模型。它最大的价值在于:一个进程同时搞定「对话模型」和「向量模型」,省去了单独部署 Embedding 服务的麻烦。
KAG(Knowledge Augmented Generation)是面向知识库场景的知识增强生成框架,本身支持 Docker 部署,模型部分走 OpenAI 兼容协议,因此天然可以对接本地 Ollama。二者组合后,文档解析、切片、向量化、图谱构建、检索与生成全部在本地完成。
硬件参考 :7B 级别模型 4bit 量化约需 5~6GB 显存,加上向量模型建议 8GB 以上;纯 CPU 可跑但生成速度会明显下降。内存建议 16GB 起,知识图谱构建阶段比较吃内存。
Docker Desktop 在 Windows 上依赖 WSL2,先更新内核再安装:
wsl --updatewinget install Docker.DockerDesktop
Ollama 直接用官方安装包或 winget:
winget install Ollama.Ollamaollama --version
关键一步: 让 Ollama 允许容器访问 。默认只监听 127.0.0.1,Docker 容器连不上,需要把环境变量 OLLAMA_HOST 设为 0.0.0.0:11434(Windows 在「系统属性 → 环境变量」中新增),然后重启 Ollama 进程。
向量模型决定检索质量,文本模型决定生成质量,两者要分开选:
ollama pull bge-m3 # 中文友好,1024 维ollama pull nomic-embed-text # 768 维,体积小ollama pull qwen2.5:7b # 通用对话与知识抽取ollama pull qwen2.5-coder:7b # 偏代码场景ollama list
验证向量化是否正常:
curl http://localhost:11434/api/embed -d '{"model":"bge-m3","input":"本地知识库"}'
返回 JSON 中的 embedding 数组长度就是向量维度, 这个数字必须和后续 KAG / 向量库中配置的维度完全一致 ,否则写入或检索会直接报错。
git clone https://github.com/OpenSPG/KAG.gitcd KAGdocker compose up -ddocker compose ps
KAG 的模型配置项在不同版本中位置和字段名略有差异(通常在配置文件或 .env 中),请以仓库 README 与配置模板为准,需要填的核心信息是固定的:
llm:api_key: ollama # Ollama 不校验,任意非空值base_url: http://host.docker.internal:11434/v1model: qwen2.5:7bembedding:api_key: ollamabase_url: http://host.docker.internal:11434/v1model: bge-m3dimension: 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 → 触发知识构建(切片 + 向量化 + 图谱抽取)→ 提问检索。观察三点:
docker compose logs 中是否有指向 11434 的请求记录,确认调用真的落在本地 Ollama;ollama ps 能看到被加载的模型及显存占用;原生接口适合流式对话,OpenAI 兼容接口适合复用现成 SDK:
# 原生对话curl http://localhost:11434/api/chat -d '{"model":"qwen2.5:7b","messages":[{"role":"user","content":"你好"}],"stream":false}'# OpenAI 兼容,可直接把 base_url 指向 http://localhost:11434/v1curl http://localhost:11434/v1/chat/completions \-H "Content-Type: application/json" \-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 走 Anthropic 协议,而 Ollama 提供的是 OpenAI 协议,中间必须加一层协议转换(LiteLLM 或 claude-code-router):
pip install 'litellm[proxy]'litellm --model ollama/qwen2.5-coder:7b --api_base http://localhost:11434 --port 4000
另开一个终端:
export ANTHROPIC_BASE_URL=http://localhost:4000export ANTHROPIC_AUTH_TOKEN=sk-localexport ANTHROPIC_MODEL=qwen2.5-coder:7bclaude
需要提醒的是,编码 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 三个字段,本地与云端可以并存并按任务路由。