WeKnora 本地大模型部署实操：五步跑通本地知识库 RAG 问答

WeKnora 本地大模型部署实操：五步跑通本地知识库 RAG 问答

【免费下载链接】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 提问是企业难以接受的，按 token 长期计费也不便宜。WeKnora 是一个开源 LLM 知识平台：部署在你自己的服务器上即可完成本地大模型部署与本地知识库搭建，文档解析、切分、嵌入、存储全部留在内网，并提供 RAG 问答、自主推理 Agent 和自维护 Wiki。

为什么选择私有环境部署 🛡️

• 数据只进自己的库：原文、分块文本、嵌入向量都落在自托管 PostgreSQL（ParadeDB 版，自带向量检索），全链路无外部 API 调用。
• 断网也能用：Ollama 加载模型后，问答与文档处理不依赖公网。
• 成本可控：没有按量计费，机器跑起来只有电费。
• 模型可替换：Ollama、OpenAI 兼容端点、Anthropic 等都支持，先用 7B 本地模型跑通，后续换更强的端点即可。

动手前的准备：硬件与软件清单 🧰

硬件最低配置（以本地跑 7B 级模型为基准）：

软件依赖：

• Docker 与 Docker Compose（v2 插件或独立版均可）
• Ollama：本地模型运行时，start-all脚本可代装，手动安装更稳
• 至少 1 个对话模型 + 1 个嵌入模型（嵌入模型把文本变成向量，供相似度检索使用）
• 只有源码构建才需要 Go / Node.js，镜像部署不用

自检清单：

1. docker info正常返回，且docker compose version可用
2. 端口 80（前端）、8080（后端）未被占用
3. 磁盘空闲 ≥ 20 GB（镜像 + 模型权重）
4. 服务器可访问外网（首次启动要拉镜像和模型）

五步完成本地部署 🚀

第 1 步：克隆仓库并创建环境文件

克隆代码并从模板生成.env：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env

成功长什么样：项目根目录出现.env，其中DB_DRIVER=postgres、STORAGE_TYPE=local为默认值，可直接使用。

第 2 步：修改.env关键项

数据库与 Redis 密码建议改掉，密钥两项生产环境必须换成自己的值（SYSTEM_AES_KEY须 32 字节）：

DB_PASSWORD=换一个强密码 REDIS_PASSWORD=换一个强密码 JWT_SECRET=换成随机字符串 SYSTEM_AES_KEY=换成32字节密钥 OLLAMA_BASE_URL=http://host.docker.internal:11434

成功长什么样：OLLAMA_BASE_URL保持host.docker.internal（容器通过它访问宿主机的 Ollama），其余占位值已替换。

第 3 步：安装 Ollama 并拉取本地模型

准备一个对话模型和一个嵌入模型（可按需替换）：

curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7b ollama pull bge-m3

成功长什么样：ollama list列出两个模型，curl http://localhost:11434/api/tags返回它们的 JSON。

第 4 步：一条命令启动全部服务

make start-all

成功长什么样：docker compose ps中 app、frontend、docreader、postgres 均为Up (healthy)，日志末尾提示可通过 http://localhost:80 访问。首次启动会拉取约 4 个镜像，耐心等几分钟。

验证与首次使用：从建库到第一次问答 ✅

验证核心端点（一条命令确认前后端与模型都活着）：

curl http://localhost:8080/health && curl http://localhost:11434/api/tags

注册并配置模型。打开 http://localhost 注册第一个账号，进入模型管理页，注册 Chat 模型（Ollama 端点，模型名填qwen2.5:7b）和 Embedding 模型（bge-m3），并把二者设为默认。

创建本地知识库并上传文档。在“知识库”页新建知识库，选择混合检索（向量相似度与关键词匹配的组合，兼顾语义和相关字面命中），上传一份 PDF 或 Word。解析完成后，文档列表显示“已处理”，并生成可预览的分块。

第一次问答。打开聊天页，选中刚建的知识库，提问“刚才上传的文档讲的是什么？”答案下方会带引用来源，点击可查看命中的原文分块。

如果引用分块和问题相关，说明本地模型 + 本地知识库的整条链路已经跑通。

调优与性能优化：模型与参数 ⚙️

• 按内存选模型：7B 约需 6-8 GB 内存，16 GB 机器建议 3B-4B 起步；32 GB 以上上 7B-14B，回答质量差别明显。
• 分块参数直接影响检索质量：config/config.yaml默认chunk_size: 512、chunk_overlap: 50；长句密集的文档可调到 768/50，改完对文档重新解析才生效。
• 压低生成随机性：conversation.summary.temperature默认 0.3，知识库问答场景保持低值，不建议高于 0.7。
• 批量导入时调并发：WEKNORA_ASYNQ_CORE_CONCURRENCY（默认 8）和WEKNORA_MODEL_MAX_CONCURRENCY（默认 32）控制后台任务与模型调用并发，文档量大时适当上调。
• 监控资源占用：curl http://localhost:11434/api/ps查看 Ollama 当前加载的模型与内存，docker stats看各容器 CPU/内存；内存紧张时用ollama stop <模型名>卸载空闲模型。

常见问题：现象到原因到解决 🔧

资源与社区 📚

• 中文文档与功能总览：README_CN.md、docs/
• API 参考（知识库、会话、模型、文档等接口）：docs/api/
• Go SDK 示例（创建知识库、发起对话）：client/example.go
• 部署配置说明：config/config.yaml
• 内置模型注册指南：docs/BUILTIN_MODELS.md
• 源码开发模式：docs/快速开发模式说明.md

跑通五步，你就有了一套完全在本地运转的 RAG 系统。下一步建议：导入三五份真实业务文档，问十个问题并记下答错的几个，再针对性地调分块参数和嵌入模型——动手调一天，比读十篇配置文档更有收获。

【免费下载链接】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