WeKnora 与 Ollama 集成：5 分钟在本地跑通大模型部署

【免费下载链接】WeKnora Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki. 项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora

文档不想出公司，API Key 不想交给外部服务——这是自建知识库问答时很常见的顾虑。WeKnora 是一个开源的 LLM 知识平台，把文档变成可检索的 RAG 问答系统；而 Ollama 是本地大模型运行时，负责在你自己的机器上跑推理。两者集成后，本地大模型部署的整条链路就完整了：文档解析、向量化、检索、生成回答全部发生在本地，网络只在第一次下载模型时用一次。

🏃 先让 Ollama 和 WeKnora 跑起来

整条链路只有两个前置服务。先装 Ollama（官网有一键安装脚本，Linux/macOS 都支持），然后拉两个模型：一个对话模型负责生成回答，一个向量模型负责把文本变成数字（embedding，把文本转成向量以便做相似度比较）：

ollama pull qwen3:8b   # 对话模型
ollama pull bge-m3     # 向量模型
ollama serve           # 启动本地服务，默认端口 11434

模型名可以按机器配置替换，8B 级别大约需要 10GB 内存。再启动 WeKnora：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora
cd WeKnora && cp .env.example .env
make start-all

.env 里有两个与 Ollama 相关的变量值得看一眼：OLLAMA_BASE_URL 指定 Ollama 地址，默认 http://host.docker.internal:11434（容器内访问宿主机的写法）；OLLAMA_OPTIONAL=true 表示 Ollama 掉线只告警、不阻断启动，适合模型服务不稳定的开发环境。

启动完用两条命令确认两边都活着：

curl http://localhost:11434/api/version   # Ollama 心跳
curl http://localhost:8080/health          # WeKnora 后端

🧭 第一次本地问答：网页里完成四步

接下来全程在浏览器里操作，地址是 http://localhost：

1. 注册账号：首次访问落到注册页，注册完自动获得一个属于你自己的工作空间；
2. 建知识库并选模型：新建知识库时弹出初始化向导，模型来源选 Ollama，对话模型填 qwen3:8b，向量模型填 bge-m3，点向导里的"测试"按钮确认连通后再保存。注意模型配置是按知识库走的，不是全局一次性配置；
3. 上传文档：把 PDF、Word、Markdown 拖进上传区，状态会从 pending 走到 completed，大部分时间花在解析上；
4. 提问：进对话页选中这个知识库直接问，回答会带引用角标，点角标能跳回原文。

到这一步，一个完全离线的知识问答系统就跑通了。

🔍 一个问题问出去之后发生了什么

前端看到的是"打字机"式的流式回答，背后的链路不长，拆开看有四段：

• 问题先到 WeKnora 后端，检索引擎（默认 ParadeDB，即带向量能力的 PostgreSQL）从知识库中捞出与问题最相关的文档片段；
• 片段和提问拼进提示词，通过 Ollama 的聊天接口发出。响应逐块流回，流式处理、工具调用、图片解析都收在 internal/models/chat/ollama.go 这一个适配层里；
• 每次调用前，Ollama 服务管理 会先发心跳确认进程在线，再检查模型名是否已安装（没带 tag 的名字会自动补上 :latest）；
• 回答落屏的同时带上引用来源，保证答案可溯源。

模型本身也不用离开网页去管：初始化处理器 提供了一组接口，列出已安装模型、检查指定模型是否存在、异步下载缺失模型并返回下载进度，界面里的模型管理就是调它们。

🕳️ 三个几乎必踩的坑

容器连不上 localhost。 后端跑在容器里，http://localhost:11434 指向的是容器自身，永远连不到宿主机的 Ollama。改成 http://host.docker.internal:11434（macOS/Windows 原生 Docker 均可用），这是集成 Ollama 时最高频的失败原因。

Ollama 没起，但页面看起来一切正常。 因为 OLLAMA_OPTIONAL=true 的默认行为是"Ollama 不可用只告警"，服务照常启动，真正发请求时才报错。排查顺序固定：先看 11434 端口心跳，再看 ollama list 里有没有你填的模型名。

内存不够时别硬扛。 推理中途进程被系统杀掉，多半是 8B 模型加默认上下文窗口吃掉了太多内存。换 4B 级别模型，或者调小 num_ctx（上下文窗口大小，决定模型一次能"看见"多少 token）都比加机器更快见效。

🎛️ 跑通之后值得调的三个旋钮

• 对话模型可以换，向量模型别轻易换：对话模型随时可换成更强或更小的版本，成本只是重建会话上下文；向量模型换了维度就变，等于全部文档重新向量化、索引重建。
• temperature 和 top_p：控制回答的随机性，文档问答建议取 0.3~0.5 的保守值，答案更贴合原文。
• num_ctx：调大能处理更长的片段拼接，但显存/内存占用同步上升，8GB 内存机器不建议超过 4096。

参数入口就在知识库初始化向导的模型配置里，改完用"测试"按钮验证连通性即可。

现在可以上传一份你自己的文档，问一个只有你答得上来的问题——如果回答里出现可点击的引用角标，说明这次本地大模型部署已经不只是"跑起来了"，而是真的在干活。

【免费下载链接】WeKnora Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki. 项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora