把大模型搬进内网：WeKnora + Ollama 本地化部署实操指南-平芜编程栈

把大模型搬进内网：WeKnora + Ollama 本地化部署实操指南

【免费下载链接】WeKnoraOpen-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，哪些文档离开了公司。WeKnora 的本地化部署给出的答案很直接——模型侧接本地 Ollama，对话、向量、检索全部跑在内网，数据不出企业边界。

这篇按落地顺序写：先判断你的业务值不值得本地化，再拆数据在内网的流转链路，然后四步跑通本地推理，最后给出验证命令和一份避坑清单。

一、先想清楚：什么业务该本地化

本地化部署不是万能选项，模型和向量索引都要常驻内存，硬件成本摆在那里。先对照下表确认边界：

维度	适合本地化	不适合本地化
数据敏感度	涉密资料、客户隐私、研发核心文档	公开信息检索、对质量要求极高的通用问答
网络条件	内网隔离、弱网车间、离线办公点	强依赖公网 API 生态、需要持续调用最新旗舰模型
调用规模	调用量大、长期 API 账单高	偶发试用、PoC 验证
硬件门槛	宿主机能常驻加载模型权重 + 向量索引，内存余量以所选模型要求为准（以实际环境为准）	只有云主机轻量实例、无法扩容

两个硬性前提来自仓库文档：至少要备好一个对话模型 + 一个向量模型；向量模型建库后不要更换，换了要重建索引。

二、架构拆解：数据在内网怎么流转

先看整体架构，图中各组件都跑在同一内网里，没有任何一环需要出网：

按数据流顺序拆五个环节，每个环节对应一个源码模块：

文档接入：文件上传走 internal/handler/knowledge.go；飞书、Notion、RSS 等数据源自动同步由 internal/datasource/ 的连接器负责。
解析分块：gRPC 文档解析服务（OCR、版式、图片提取）在 docreader/；分块逻辑在 internal/infrastructure/chunker/，默认chunk_size: 512、chunk_overlap: 50，见 config.yaml。
混合检索：关键词 + 向量混合检索，向量索引基于 ParadeDB（迁移脚本见 migrations/paradedb/），检索工具函数在 internal/searchutil/。
本地推理：Ollama 连接管理与心跳检测在 internal/models/utils/ollama/ollama.go，对话与向量化分别在 internal/models/chat/ollama.go、internal/models/embedding/ollama.go。
输出生成：Agent 引擎在 internal/agent/，回答以 SSE 流式返回，接口层在 internal/handler/。

文档处理链路的完整流程如下图，从原始文件到可检索的分块全部在 docreader 内完成：

三、上手部署：四步跑通本地推理

第 1 步：环境检查

docker compose version && curl -fsS http://localhost:11434/api/version

确认 Docker 可用、宿主机 Ollama 已装并监听 11434 端口。

第 2 步：拉取本地模型

ollama pull qwen3:8b && ollama pull bge-m3 && ollama list

模型名以你的硬件为准；示例取自仓库快速上手文档。

第 3 步：部署 WeKnora 并配置关键项

git clone https://gitcode.com/GitHub_Trending/we/WeKnora && cd WeKnora && docker compose up -d

在.env中确认以下配置（对应 docker-compose.yml）：

配置项	推荐值	不这么配会怎样
`OLLAMA_BASE_URL`	容器化部署：`http://host.docker.internal:11434`；裸机：`http://localhost:11434`	容器内填`localhost`会指向容器自身，Ollama 永远连不上
`OLLAMA_OPTIONAL`	`false`	默认`true`时 Ollama 挂了服务照常启动，本地模型功能静默不可用
`DISABLE_REGISTRATION`	生产设`true`	公开注册不关闭，任何人都能注册建库
`DB_DRIVER`/`DB_HOST`	compose 默认`postgres`	数据库不通则健康检查失败

第 4 步：建库并绑定本地模型

登录后新建知识库，在初始化向导里把对话模型与向量模型的来源选为 Ollama（source: "local"），用向导内置的「测试」按钮确认连通后再保存。对应接口为POST /api/v1/initialization/initialize/:kbId，详见快速上手第 3 节。

四、验证与调优：怎么确认部署到位

按顺序执行，全部通过才算部署到位：

Ollama 侧模型就绪：curl -s http://localhost:11434/api/tags，返回的models里能列出你 pull 的模型；
WeKnora 后端存活：curl http://localhost:8080/health，预期返回{"status":"ok"}；
Ollama 集成自检：GET /api/v1/initialization/ollama/status返回可用，GET /api/v1/initialization/ollama/models能看到模型列表；
端到端问答：上传一份 PDF，等parse_status变为completed后提问，回答带可点击引用。

性能与资源口径，仓库文档没有给出固定数值，以实际环境为准，这里只给检查基准：

解析耗时：默认超时document_process_timeout: 2h，扫描件 PDF 会更慢，列表页会刷新进度；
分块参数：chunkSize合法范围 100–10000，默认 512/重叠 50，先按默认跑通再调；
内存占用：以「模型权重常驻 + 向量索引」为主，建议压测后记录基线，而非套用估算公式。

⚠️ 注意：调优前先固化一条基线（同一份文档、同一组问题、记录耗时与内存），改参数后对比，否则说不清改动带来的变化。

五、避坑清单：高频故障与排查

容器内连不上宿主机 Ollama（最高频）
- 现象：向导测试按钮报连接失败，日志出现ollama service unavailable；
- 排查：curl -fsS $OLLAMA_BASE_URL/api/version，确认OLLAMA_BASE_URL是host.docker.internal而非localhost；
- 处理：改.env后重启 app 服务；Linux 宿主不支持host.docker.internal时给 compose 加extra_hosts: ["host.docker.internal:host-gateway"]。
Ollama 重启后一切"正常"但模型不可用
- 现象：服务活着，但所有本地模型请求失败；
- 排查：env | grep OLLAMA_OPTIONAL，确认是不是true；
- 处理：私有化部署改为false，让启动期就暴露 Ollama 故障。
换了向量模型后检索结果异常
- 现象：回答引用错乱或召回明显变差；
- 排查：核对知识库初始化记录里的 embedding 模型是否被改过；
- 处理：向量模型建库后不再更换，确需更换就新建知识库重建索引。
模型迟迟不在模型列表里
- 现象：ollama list无目标模型；
- 排查：ollama ps看是否有下载卡住的任务；
- 处理：手动ollama pull <模型名>，或在 Web 初始化向导里用内置的模型下载功能异步拉取并轮询进度。
大文件解析长时间不完成
- 现象：状态停在processing；
- 排查：看文档状态链pending → processing → finalizing → completed卡在哪一段；
- 处理：确认 docreader 容器日志无异常，扫描件优先检查 OCR 环节。