5条命令跑通WeKnora本地知识问答：私有RAG知识库快速搭建-开发者社区

5条命令跑通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

你手上有一堆产品手册、内部制度，同事提问时一条条翻文档回答很累。把它们丢进开源项目 WeKnora，它会自动解析、向量化，并能带引用地回答提问，全程跑在你自己的机器上，数据不出内网。下面带你完成一次从本地部署、接入 Ollama 到文档导入、首次提问的完整流程。

🚀 5条命令启动：先看到知识库界面

这节能帮你在10分钟内把 WeKnora 跑起来，得到一个能直接打开的网页界面。

前置条件只有一个：宿主机装好 Docker 和 Docker Compose。然后克隆代码并启动：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env docker compose pull docker compose up -d

启动后浏览器打开http://localhost，会落在注册页。WeKnora 没有内置账号，首次注册会自动建一个工作空间，你直接是这个空间的 Owner。用curl http://localhost:8080/health能返回{"status":"ok"}说明后端就绪。

想接本地 Ollama 模型的话，先把模型拉下来（1个对话模型 + 1个向量模型）：

ollama pull qwen3:8b ollama pull bge-m3

硬件怎么估？参考下面这张表，官方建议标准 Docker 部署 4核CPU / 8GB内存起步（docreader 解析容器较吃内存）：

部署形态	建议配置	适合场景
Docker Compose 标准部署	4核 / 8GB 内存起步	团队自托管，默认推荐
Lite 单二进制	更低配置的机器	个人、离线、低资源环境

🧩 一张图看懂 WeKnora 的工作方式

这节用大白话讲清你上传文档后数据去了哪里，之后排查问题时就不会迷路。

默认部署是4个容器分工：frontend（Nginx，端口80）管页面，并把/api/请求反代给后端；app（端口8080）是主后端，负责问答编排和索引管理；docreader 走 gRPC 专门解析文档，PDF、Word 的版式识别都发生在它里面，代码在 docreader 解析服务；数据层是 ParadeDB（带向量能力的 PostgreSQL）加 Redis，前者存分块和向量，后者跑异步任务队列。

提问时的路径是：你的问题先走混合检索（向量召回 + BM25 关键词召回），两路结果融合后交给大模型组织答案，回答里会带可点击的引用。模型层既接本地 Ollama，也接任意 OpenAI 兼容的远程服务，Ollama 客户端实现在 internal/models/chat/ollama.go。

📚 建库到提问：完整走一遍

这节按操作顺序演示一次真实闭环：建库、配模型、导入文档、提问看引用，每步都能在网页界面完成。

第1步，在「知识库」页点新建，填名称，类型选document（普通文档库）或faq（问答对库）。

第2步，在初始化向导里为这个库选模型：对话模型负责生成回答，向量模型负责把文档转成向量。注意向量模型建库后不要换，换了要重建索引。选 Ollama 时点「测试」确认连通再保存。

第3步，进入知识库上传文档。支持 PDF、Word、Excel、PPT、Markdown、HTML、EPUB、图片等格式。上传后解析异步进行，状态依次是pending → processing → finalizing → completed，列表页实时刷进度，等它变completed再提问。

第4步，进对话页，选中刚才的知识库直接提问。默认的「快速问答」Agent 会先检索相关片段再作答，引用点一下能跳回原文；想处理多步推理的问题，可以切到「智能推理」Agent。

如果习惯命令行，每一步都有对应接口（统一前缀/api/v1，前端 Nginx 会代理）。下面这段走通核心链路，可直接复制：

BASE=http://localhost/api/v1 TOKEN=$(curl -s -X POST $BASE/auth/login -H "Content-Type: application/json" \ -d '{"email":"admin@example.com","password":"pass123456"}' | jq -r '.token') AUTH="Authorization: Bearer $TOKEN" KB_ID=$(curl -s -X POST $BASE/knowledge-bases -H "$AUTH" -H "Content-Type: application/json" \ -d '{"name":"公司文档","type":"document"}' | jq -r '.data.id') curl -s -X POST $BASE/initialization/initialize/$KB_ID -H "$AUTH" -H "Content-Type: application/json" \ -d '{"llm":{"source":"local","modelName":"qwen3:8b"},"embedding":{"source":"local","modelName":"bge-m3","dimension":1024},"rerank":{"enabled":false},"multimodal":{"enabled":false},"documentSplitting":{"chunkSize":512,"chunkOverlap":50},"nodeExtract":{"enabled":false},"questionGeneration":{"enabled":false}}' curl -s -X POST $BASE/knowledge-bases/$KB_ID/knowledge/file -H "$AUTH" -F "file=@./manual.pdf" SESSION_ID=$(curl -s -X POST $BASE/sessions -H "$AUTH" -H "Content-Type: application/json" \ -d '{"title":"第一次对话"}' | jq -r '.data.id') curl -N -X POST $BASE/knowledge-chat/$SESSION_ID -H "$AUTH" -H "Content-Type: application/json" \ -d '{"query":"总结这份文档的要点","knowledge_base_ids":["'$KB_ID'"]}'

🛠 新手期最容易踩的5个坑

这节把新手阶段出现频率最高的5类报错讲清楚，每个按「现象→原因→解决」三句话交代完。

坑1：Ollama 检测不到模型。现象是初始化向导里本地模型一直连不上、列表为空。原因是 WeKnora 后端跑在容器里，容器内的localhost不是你的宿主机。解决：地址填http://host.docker.internal:11434（.env里OLLAMA_BASE_URL的默认值就是这个），Linux 上确认host.docker.internal能解析即可。

坑2：文档一直卡在 processing。现象是上传半小时状态仍不变成 completed。原因是解析在独立的 docreader 容器里进行，扫描件和大文件天然慢，且受MAX_FILE_SIZE_MB（默认50MB）限制。解决：docker logs WeKnora-docreader看它卡在哪一步，超大文件先拆分再传。

坑3：回答没引用或答非所问。现象是提问后引用区为空、内容泛泛。原因通常是解析还没 completed 就去提问，或向量模型和建库时不一致导致检索对不上。解决：确认所有文档解析完成，且不要在已有文档的库里换 embedding 模型。

坑4：http://localhost打不开。现象是启动成功但浏览器拒绝连接。原因是宿主机80或8080端口已被其他服务占用。解决：在.env里改FRONTEND_PORT或APP_PORT，再执行docker compose up -d。

坑5：compose 启动直接报错。现象是docker compose up -d提示 env_file 相关错误。原因是 app 服务声明了读取.env，文件不存在时编排解析直接失败。解决：先执行cp .env.example .env再启动，这也是上面5条命令里第3条的作用。