把大模型搬进内网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_OPTIONALfalse默认true时 Ollama 挂了服务照常启动本地模型功能静默不可用DISABLE_REGISTRATION生产设true公开注册不关闭任何人都能注册建库DB_DRIVER/DB_HOSTcompose 默认postgres数据库不通则健康检查失败第 4 步建库并绑定本地模型登录后新建知识库在初始化向导里把对话模型与向量模型的来源选为 Ollamasource: 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 环节。 小贴士先在内网挑一个非核心业务如内部制度问答跑两周把上面四条验证命令固化成脚本再推广到客户资料、研发文档等关键业务风险最小。落地入口文档与命令细节参考仓库内文档快速上手、安装部署、配置说明。遇到问题直接通过项目 issue 系统提交附上本文四条验证命令的输出能显著加快定位。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
把大模型搬进内网：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_OPTIONALfalse默认true时 Ollama 挂了服务照常启动本地模型功能静默不可用DISABLE_REGISTRATION生产设true公开注册不关闭任何人都能注册建库DB_DRIVER/DB_HOSTcompose 默认postgres数据库不通则健康检查失败第 4 步建库并绑定本地模型登录后新建知识库在初始化向导里把对话模型与向量模型的来源选为 Ollamasource: 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 环节。 小贴士先在内网挑一个非核心业务如内部制度问答跑两周把上面四条验证命令固化成脚本再推广到客户资料、研发文档等关键业务风险最小。落地入口文档与命令细节参考仓库内文档快速上手、安装部署、配置说明。遇到问题直接通过项目 issue 系统提交附上本文四条验证命令的输出能显著加快定位。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
