10分钟跑通WeKnora：从Docker部署到自建知识库问答的完整路径

10分钟跑通WeKnora：从Docker部署到自建知识库问答的完整路径

【免费下载链接】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（维娜拉）是一个开源的大模型知识平台：你把 PDF、Word、网页这类原始文档丢进去，它帮你做成可提问的 RAG 知识库、能自己调工具推理的 Agent，以及一套自动维护的 Wiki，MIT 协议，适合想在私有环境里搭文档问答系统的团队和个人。你需要的环境只有 Docker、Docker Compose 和 Git 三件套。

🚀 先跑起来：4条命令起服务

先克隆仓库，把环境变量模板复制成.env按需改，然后拉镜像、起容器：

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

启动成功的验证信号有两个：浏览器访问http://localhost能看到 Web 界面；后端健康检查curl http://localhost:8080/health返回正常（健康检查端点在 internal/router/router.go 里注册）。docker-compose.yml里 frontend 映射 80 端口、app 映射 8080 端口，都是.env里可改的。

首次访问时如果还没配过模型，会先进入初始化配置页，把 LLM、Embedding、向量数据库这几项填完才能正常用：

核心配置分两处：运行行为看 config/config.yaml（分块默认chunk_size: 512、chunk_overlap: 50，检索阈值vector_threshold: 0.2、rerank_threshold: 0.3）；模型地址和密钥在.env（变量注释非常详细，比如INIT_LLM_MODEL_NAME、INIT_EMBEDDING_MODEL_NAME、INIT_EMBEDDING_MODEL_DIMENSION）。

按需开启可选组件（compose profile，可叠加）：

停止服务用docker compose down；也提供了一键脚本./scripts/start_all.sh（支持--stop、--check自检），见 scripts/start_all.sh。

想用本地 Ollama 的话，先ollama serve > /dev/null 2>&1 &，再把.env里的模型地址指过去。

三个核心功能走一遍

文档进去到回答出来的链路是：解析 → 切块向量化 → 混合检索（向量 + BM25 关键词）→ 大模型生成。

建知识库：上传文档到能回答

能干什么：创建知识库，上传文件（PDF / Word / Excel / 图片 / XMind 等十余种格式）、粘贴 URL、导入文件夹或 FAQ；解析完成后按你配置的参数切块并建索引。

怎么操作：Web UI 里新建知识库 → 上传文档 → 等解析任务跑完，文档列表里能看到分块；上传时的批次级process_config可以临时覆盖解析引擎、分块和多模态设置。

入口在哪：界面在 frontend/src/views/；接口文档在 docs/api/knowledge-base.md；API 认证统一用X-API-Key请求头（注册或建空间后会拿到sk-开头的 key）。用 curl 建库最小示例：

curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: your_api_key' \ --data '{"name": "示例知识库", "description": "用于演示"}'

解析卡住或分块效果不对，先看文档级解析追踪时间线（Langfuse 风格的逐阶段 Span 树），再查docker compose logs -f app docreader。

对话：快速问答和 Agent 推理两个档位

能干什么：同一个知识库支持两种回答方式。快速问答走 RAG：检索命中后直接生成，带引用浮层，适合日常查证；智能推理是 ReAct 模式：模型自主决定何时查知识库、何时调 MCP 工具、何时执行沙箱里的技能，适合"先查 A 再算 B 最后汇总"这类多步任务。

怎么操作：新建会话时切换对话模式即可；会话里还能@Skill/@MCP限定当前轮可用的工具和技能。

入口在哪：检索与生成的阈值、改写与重排开关都在 config/config.yaml 的conversation段（enable_rewrite、enable_rerank、rerank_top_k等）；Agent 循环实现看 internal/agent/engine.go。

回答不准时先查三处：Embedding 模型维度是否和向量库匹配（.env的INIT_EMBEDDING_MODEL_DIMENSION）、检索阈值（vector_threshold/rerank_threshold）、Rerank 模型有没有配（INIT_RERANK_MODEL_*）。

Wiki 模式：让 Agent 自己写文档

能干什么：Agent 从原始文档自动提炼出相互链接的 Markdown Wiki 页面和可视化知识图谱，支持在浏览器里人工编辑、看行级 diff、一键回滚到历史版本。

怎么操作：对已有文档知识库启用 Wiki 任务，然后在 Wiki 浏览器里按目录翻页面、点图谱节点跳引用。

入口在哪：前端在 frontend/src/views/ 的 Wiki 浏览器页面，处理器看 internal/handler/wiki_page.go。

进阶方向：三条扩展线

只给思路，细节看对应文件。

知识图谱增强检索：默认检索是向量 + BM25 混合召回；开启图谱后会把段落间语义关联建进 Neo4j，拓宽召回面。配置见 docs/开启知识图谱功能.md，实体/关系抽取提示词在 config/config.yaml 的extract段。

多模态与数据源：图片类文档可配 VLM 做 OCR 与描述生成，解析器在 docreader/parser/；飞书知识库 / GitLab / Notion / 语雀 / RSS 等外部数据源可定时增量同步，连接器代码在 internal/datasource/connector/，开发文档 docs/数据源导入开发文档.md。

程序化集成与二次开发：对外有三条路——REST API（完整端点文档 docs/api/README.md）、Go SDK（跑通示例 client/example.go）、官方 MCP Server（mcp-server/，PyPI 包tencent-weknora-mcp，stdio / SSE / HTTP 三种传输）。要改源码的话用快速开发模式免打镜像：make dev-start起基础设施，另开终端make dev-app（Air 热重载）和make dev-frontend，详细说明在 docs/开发指南.md。

🔧 卡住时先查这五处

1. 容器起不来 / 8080 不通：docker compose logs -f app docreader postgres找 ERROR；镜像版本对不上时，把.env的WEKNORA_VERSION设成目标 tag（如v0.7.0），重新docker compose pull && docker compose up -d——只执行up -d会复用旧缓存镜像。
2. 文档上传后解析失败：绝大多数是模型没配对。核对.env里INIT_LLM_MODEL_NAME、INIT_EMBEDDING_MODEL_NAME、INIT_EMBEDDING_MODEL_DIMENSION，远端模型还要*_BASE_URL和*_API_KEY，排查步骤见 docs/QA.md。
3. 图片显示为无效链接：多半是 MinIO 没起或 bucket 权限不对——docker compose --profile minio up -d，再用.env里的MINIO_ACCESS_KEY_ID登录http://localhost:9001控制台看策略；跨机器访问图片要把MINIO_PUBLIC_ENDPOINT从localhost改成实际 IP。
4. OCR 报错或 PaddleOCR 起不来：在docreader服务把OCR_BACKEND换成vlm（配OCR_API_BASE_URL/OCR_API_KEY/OCR_MODEL）或no_ocr，再重启 docreader。
5. 页面保存的配置几秒后又消失：基本不是后端问题，先关浏览器代理和改写类插件、把localhost加进直连名单，再用无痕窗口重试；仍不行docker compose restart app。

更多场景（日志查看、清空数据库、平台兼容性）都在 docs/QA.md。

📚 三档学习路线

第一档（半天）：按上文部署 → 建库上传 → 两种对话模式各问几个问题 → 用X-API-Key打两个接口（建库、混合搜索POST /knowledge-bases/:id/hybrid-search，见 docs/api/knowledge-search.md）。

第二档（一两周）：跑通快速开发模式改一处代码 → 换一家模型厂商验证配置灵活性 → 调分块参数与 Rerank 观察召回变化 → 给知识库接一个数据源同步。参考 config/builtin_models.yaml.example 做声明式内置模型，API 全量文档在 website-docs/。

第三档（长期）：读 Agent 循环 internal/agent/engine.go 和技能沙箱 internal/sandbox/ → 给 MCP Server 加一个自己的工具（examples/mcp-demo/）→ 研究 Wiki 自治生成与版本回滚实现（internal/handler/wiki_page.go），或把 Langfuse 追踪（docs/Langfuse集成.md）接到你自己的可观测体系里。

版本演进和路线图看 CHANGELOG.md 与 docs/ROADMAP.md；生产部署安全基线（内网隔离、登录鉴权）在 SECURITY.md。

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