WeKnora：本地 RAG 知识库从 0 到跑通的快速实操笔记

WeKnora本地 RAG 知识库从 0 到跑通的快速实操笔记【免费下载链接】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/WeKnoraWeKnora 是一个开源 RAG 知识库平台把 PDF、Word、网页等文档解析成可检索的知识库回答带出处引用。适合刚克隆仓库、想在本地跑通检索问答的开发者。本文覆盖环境自检、Docker 部署、检索参数调整和上线验证几个环节。先搞懂 WeKnora RAG 的知识链路文档上传后docreader 服务把它解析成文本分块向量化后写入向量库默认 ParadeDB/PostgreSQL。你提问时系统做混合检索关键词 向量可选图谱重排再让对话模型基于召回片段作答并附引用角标。适合查资料频次高、答案需要可追溯来源的团队或个人知识库。不适合需要实时业务数据它索引的是文档快照靠数据源同步更新或对首字延迟极敏感的在线场景。开工前的环境自检软件Docker Compose 插件。终端跑docker compose version能打印版本号即就绪。硬件至少 8GB 可用内存、20GB 以上磁盘前端、app、docreader、ParadeDB、Redis 都在容器里。df -h .看剩余空间。网络首次部署要能从 Docker Hub 拉 5 个镜像。docker pull redis:7.0-alpine秒过说明网络通畅。模型服务二选一本地 Ollama 跑curl localhost:11434或远程 OpenAI 兼容 API 跑curl 你的base_url/models返回模型列表即就绪。端口80前端和 8080app空闲。ss -lntp | grep -E :80|:8080无输出即可用。模型服务这一步最容易卡住容器里的 app 访问宿主机 Ollama 要用http://host.docker.internal:11434填localhost会连不上。WeKnora RAG 知识库从克隆到跑通的分步部署第 1 步克隆仓库并准备 .envgit clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env自带分组注释重点看数据库DB_USER、DB_PASSWORD、DB_NAME、RedisREDIS_ADDR、镜像版本WEKNORA_VERSION。数据库和 Redis 都在 compose 里用默认值就能跑。✅ 看到.env文件出现在仓库根目录即通过第 2 步拉取镜像并启动服务docker compose pull docker compose up -d docker compose psapp 有/health健康检查frontend 要等 app 健康后才启动。首次拉镜像较慢ps里容器陆续变绿属正常。✅ 看到 WeKnora-frontend 状态为 running 即通过第 3 步后端健康检查curl http://localhost:8080/health✅ 看到{status:ok}即通过第 4 步浏览器完成初始化打开http://localhost注册账号你会自动拥有一个工作空间并成为 Owner。新建知识库时向导会让你选对话模型和向量模型内置测试按钮可直接验证连通性。✅ 看到知识库列表页出现刚建的库即通过 不喜欢逐条命令的话./scripts/start_all.sh一条命令做前置检查含自动创建.env再拉起服务效果等价。WeKnora RAG 知识库检索质量调优3 个最值得动的参数默认值就能跑但回答质量不好时先动这 3 个。前两个在 配置样例 的conversation段第三个在knowledge_base段改完重启 app 容器生效。参数默认值调高的副作用调低的副作用推荐值vector_threshold0.2卡掉相关片段召回不全混入噪声片段靠重排兜底0.1–0.2embedding_top_k30重排和 LLM 调用量上升响应变慢目标片段没进候选集30–50chunk_size512单块语义被稀释表格易被切开上下文断裂块数和索引膨胀256–1024 按文档类型试向量模型建库后别换换了等于语义空间变了整个索引要重建。WeKnora RAG 检索验证四步确认知识库真的能用后端存活→curl http://localhost:8080/health返回{status:ok}→ 不对就docker compose logs -f app。前端可达→ 浏览器开http://localhost到注册/登录页 → 打不开先看 80 端口冲突。文档解析→ 上传一份 PDF状态走pending → processing → finalizing → completed完成后显示分块数 → 卡住就去 docreader 日志搜 ERROR。端到端问答→ 在对话页选这个知识库问一个只有文档里才有的事实性问题 → 答对的标准回答带引用角标点开能跳回原文对应片段泛泛而谈或拒答多半是向量模型没配好或阈值过高回去调vector_threshold。踩坑速查app 容器反复重启→.env里DB_*/REDIS_ADDR与容器内实际不符 → 对照 .env.example 的默认值改回docker compose up -d app重启。能启动但上传文档直接报错→ 向量模型或对话模型没配齐解析流水线起不来 → 回知识库向导补上模型并点测试。Ollama 连不上→ 容器里写了localhost:11434→ 模型地址改成http://host.docker.internal:11434。文档里的图片外部打不开→ 本地存储下图片走容器内网地址 → 设APP_EXTERNAL_URL让图片走/r/token代理转发。以上都没解决→docker compose logs -f app docreader postgres搜 ERROR再看 故障排查文档。跑通之后可以做什么数据源自动同步飞书、Notion、RSS 等接进来增量更新入口见 数据源文档 与internal/datasource/。MCP 集成PyPI 装tencent-weknora-mcp把检索问答挂给外部智能体示例在mcp-server/。终端管理weknoraCLI 支持weknora kb list、doc upload、chat源码在cli/。调用链追踪docker compose --profile langfuse up -d推理步骤和 token 消耗追到单次会话级别。下一步今天就可以做把一份真实业务文档传进去问一个只有它里面才有的问题确认引用角标能跳回原文然后设DISABLE_REGISTRATIONtrue关掉公开注册docker compose logs -f app盯一两天日志确认没有解析积压。【免费下载链接】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），仅供参考