WeKnora 上手实战：5分钟让一份PDF答出答案

WeKnora 上手实战：5分钟让一份PDF答出答案

【免费下载链接】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 是开源 RAG（让大模型先翻资料再回答）知识框架，把 PDF、Word 变成能直接问答的知识库。适合两类人：要部署内部知识问答服务的，和想进源码改一改的。

🚀 四条命令启动 WeKnora

环境只需 Docker 和 Docker Compose，没有别的依赖：

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

打开http://localhost，首次访问会跳到初始化页面，把 LLM 模型和 Embedding（把文本转成向量供检索的模型）填进去就能用。后端 API 在http://localhost:8080。所有变量集中在.env，按 A 到 J 分组注释得很清楚，参考 .env.example。

📄 上传一份 PDF 然后提问

在界面建一个知识库，把 PDF 拖进去。文档状态从解析中变成就绪，大约需要十几秒。这十几秒里发生了三件事：文档解析服务 把 PDF 读成文本和图，分块逻辑 按标题层级和标点把文本切成带重叠的小段，Embedding 模型把每段转成向量写进 pgvector。

提问时走反方向的时序：你的问题先被改写成更适合检索的形式，再去向量库里捞出最相关的若干段，经 Rerank（重排序）模型排一遍序，最后才交给大模型拿着这些段落组织答案。所以答案下面挂的引用，就是真正被"翻到"的那几段。

⚙️ 换 Embedding 模型只改 .env 里的变量

模型配置不走界面，走.env。对话模型用INIT_LLM_MODEL_NAME，向量模型用INIT_EMBEDDING_MODEL_NAME，再配上INIT_EMBEDDING_MODEL_DIMENSION写清维度；接远程 API 就再加对应的INIT_LLM_MODEL_BASE_URL、INIT_LLM_MODEL_API_KEY等变量。

两个容易踩的点：

• 维度必须和实际模型一致，写错会导致向量入库失败。
• 换了 Embedding 模型后，旧文档的向量是新模型算不出来的，需要重新上传或触发重新解析，否则检索会"对不上话"。

改完docker compose up -d重启 app 容器即可，不用重建镜像。

🔍 把检索精度提上去

答案不准，九成是检索环节在漏。配置文件 的conversation段就是调检索的旋钮：vector_threshold: 0.2是向量相似度门槛，rerank_threshold: 0.3是重排后的保留线，embedding_top_k和rerank_top_k控制各捞多少段。

经验值：结果噪音多，就把vector_threshold调高一点；明明库里写了却答不上来，就把top_k调大再配合 Rerank 收紧。改完直接看效果——每个知识库都有分块编辑页，能逐块检查切出来的质量，块太长或把一句话拦腰切断都会拉低精度。

混合检索（BM25 关键词召回 + 向量召回）的组合逻辑在 检索引擎源码 里，想动策略从这里进。

🛠️ 动手改一改：从分块参数开始

最小二次开发切点是config/config.yaml的默认分块参数：

knowledge_base: chunk_size: 512 # 每块目标字数，长文档可上调 chunk_overlap: 50 # 相邻块重叠字数，防断句

改完对新建知识库生效，到分块编辑页立刻能看到差别。如果要改解析、切片或检索的代码本身，从 开发指南 的快速开发模式入手：make dev-start起基础设施，后端用 Air 热重载，改 Go 代码 5 秒内重启，不用重建 Docker 镜像。

踩坑速查

• 现象：服务起来了但上传文档失败 →原因：LLM 或 Embedding 变量没配全 →解决：补齐.env的INIT_*模型变量，看docker compose logs -f app里的 ERROR。
• 现象：图片显示无效链接 →原因：多模态用了 MinIO 但 bucket 不公开 →解决：控制台把 bucket 设为公开读，或填一个不存在的 bucket 名让系统自动创建。
• 现象：PaddleOCR 启动失败 →原因：OCR_BACKEND=paddle平台兼容性差 →解决：改OCR_BACKEND=vlm走外部视觉模型，或去掉该配置关闭 OCR。
• 现象：界面版本和下载的 release 不一致 →原因：docker compose up -d复用了缓存镜像 →解决：先docker compose pull再 up。
• 现象：其他机器访问不到文档里的图片 →原因：MINIO_PUBLIC_ENDPOINT默认是 localhost →解决：改成宿主机真实 IP。

条目出处都在 常见问题排查，可按图索骥。

继续往哪走

• 程序化接入：读 API 文档 了解 360 个端点，照着 client/example.go 跑通"建库 → 传文件 → 提问"的最小闭环；想让外部 Agent 调你的知识库，仓库里的 mcp-server/ 提供 29 个现成工具。
• 给自己定一个下一步问题："我有一批真实业务问答对，怎么在 WeKnora 里量化评估检索召回和答案质量？"带着它去翻 端到端评估接口 和 dataset/samples/ 里的 parquet 样例，比泛泛看源码收获大得多。

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