1. 为什么企业需要一个“会说话”的知识库1.1 从“文档坟场”到“智能问答”的转变很多公司都面临一个尴尬的现实内部文档越积越多从产品手册、技术规范到客服话术、运维记录散落在各个网盘、Wiki、甚至个人电脑里。员工想找一份半年前的项目复盘得在群里问一圈最后发现只有离职的那位同事电脑里有。这就是典型的“文档坟场”——存了很多但用不起来。WeKnora 要解决的就是这个问题。它本质上是一套基于RAG检索增强生成架构的企业知识库系统由腾讯开源。你可以把它理解成一个“会说话”的文档中心你把公司内部的 PDF、Word、Markdown、网页链接等资料喂给它它自动完成解析、切块、向量化然后当员工用自然语言提问时它能从这些资料里找到最相关的片段再交给大语言模型组织成一段通顺、有依据的回答。和传统关键词搜索最大的区别在于关键词搜索要求你猜文档里用了什么词而 RAG 知识库允许你像问同事一样提问。比如“去年双十一大促期间订单服务的限流阈值调整到多少了”——这种问题在传统搜索里几乎无解但在 WeKnora 里只要相关复盘文档在库中它就能定位到具体段落并给出答案。1.2 WeKnora 适合哪些场景和人群从实际落地经验看WeKnora 最适用的场景有这么几类技术团队内部知识管理API 文档、架构决策记录、故障复盘、部署手册统一入库新成员入职时直接问系统减少老员工重复答疑。客服与售后支持把产品说明书、常见问题、历史工单处理记录导入客服人员可以快速检索标准话术和处理方案。销售与售前支持产品报价、竞品对比、成功案例、合同模板等资料集中管理销售在客户现场也能快速调取准确信息。个人知识库如果你有大量技术笔记、论文、电子书也可以本地部署一套当作自己的“第二大脑”。适合阅读这篇内容的人包括运维工程师、后端开发、技术负责人、IT 支持人员以及任何想在自己环境里跑通一套 RAG 知识库的爱好者。不需要你是 AI 专家但需要你熟悉基本的 Linux 命令和 Docker 操作。1.3 整体架构速览WeKnora 由哪些部分组成WeKnora 的架构设计比较清晰核心组件包括前端界面提供知识库管理、文档上传、对话问答的 Web 界面。后端服务基于 FastAPI 构建负责文档解析、切块、向量化、检索和对话编排。向量数据库默认使用 PostgreSQL pgvector 扩展存储文档切块的向量表示。大语言模型接入层支持对接多种大模型 API也支持本地部署的模型。文档解析模块处理 PDF、Word、Markdown、HTML 等格式提取纯文本。整个数据流是这样的文档上传 → 解析提取文本 → 按策略切块 → 调用嵌入模型生成向量 → 存入 pgvector → 用户提问 → 问题向量化 → 向量检索 Top-K 相关块 → 拼接上下文交给大模型 → 生成回答返回前端。理解这个流程很重要因为后面排查问题时你需要知道是解析阶段丢了内容、切块阶段切碎了语义、还是检索阶段没召回正确片段。2. 部署前的环境准备与关键决策2.1 硬件与操作系统选择WeKnora 对硬件的要求取决于你选择哪种大模型接入方式。如果使用云端大模型 API如腾讯混元、DeepSeek 等那么本地机器只需要承担文档解析、向量化和向量检索的工作配置要求不高CPU4 核以上内存8GB 以上如果文档量大建议 16GB磁盘至少 20GB 可用空间主要用于存放 Docker 镜像、PostgreSQL 数据和上传的文档操作系统Ubuntu 20.04/22.04 LTS 最稳妥CentOS 7.9 也可以但需要额外处理一些依赖如果你想完全本地化连大模型也在本地跑那硬件要求就高多了。以 7B 参数量的模型为例量化后大约需要 6-8GB 显存加上向量化和检索的开销建议至少 16GB 显存的 GPU。如果只是体验可以用 CPU 推理但速度会慢到影响使用体验。我个人的建议是初次搭建先用云端 API 跑通全流程确认业务价值后再考虑本地化部署。这样能快速验证效果避免在环境问题上消耗过多精力。2.2 Docker 与 Docker Compose 安装WeKnora 官方推荐用 Docker Compose 部署这是最省心的方式。安装 Docker 的步骤这里不展开网上资料很多。重点提醒几个容易出问题的地方第一Docker 版本不要太老。建议 Docker 20.10 以上Docker Compose v2 以上。用docker compose version检查如果显示的是docker-compose带横杠说明是 v1建议升级。第二配置国内镜像加速。拉取镜像时如果速度慢可以在/etc/docker/daemon.json里加上镜像加速地址。具体地址这里不列举你可以根据自己所在网络环境搜索可用的加速服务。第三确保当前用户有 Docker 执行权限。要么用sudo要么把用户加入docker组sudo usermod -aG docker $USER然后重新登录生效。安装完成后用docker run hello-world验证一下能正常输出就说明基础环境没问题。2.3 大模型 API 的选择与配置思路WeKnora 支持多种大模型接入方式这是它比较灵活的地方。你需要准备两类模型的接入信息对话模型负责根据检索到的上下文生成回答。可选的有腾讯混元、DeepSeek、通义千问等。选择时主要考虑三点一是 API 是否稳定二是价格是否可接受三是中文理解能力是否够强。从实际使用看混元和 DeepSeek 在中文企业场景下表现都不错。嵌入模型负责把文本转换成向量。这个模型的选择直接影响检索效果。WeKnora 默认可能使用某个开源嵌入模型你也可以配置成 API 方式。嵌入模型不需要太强的生成能力但要求语义表征准确、维度适中通常 768 或 1024 维。配置方式一般是在.env文件或config.yaml里填写 API Key、Base URL 和模型名称。这里有个经验先把 API Key 在 curl 里测试通过再填到配置文件里。我见过不少人因为 Key 复制时多了空格、或者 Base URL 路径不对导致服务启动后一直报鉴权失败。注意API Key 属于敏感信息不要提交到 Git 仓库。建议用.env文件管理并把.env加入.gitignore。2.4 数据库与向量存储的初始化WeKnora 用 PostgreSQL pgvector 作为向量存储。Docker Compose 文件里通常已经定义好了数据库服务你只需要确保数据库端口不冲突默认 5432如果本机已有 PostgreSQL 在跑需要改成其他端口数据卷挂载正确否则容器重启后数据丢失pgvector 扩展已启用首次启动时后端服务会自动执行数据库迁移创建必要的表和索引。你可以在日志里看到类似Running migrations...的输出。如果卡在这里多半是数据库连接配置不对检查DATABASE_URL环境变量。3. 从零搭建 WeKnora 的完整实操3.1 获取源码与目录结构说明从官方仓库克隆代码git clone https://github.com/Tencent/WeKnora.git cd WeKnora克隆完成后先别急着启动花两分钟看一下目录结构。通常会有这几个关键目录docker/或根目录下的docker-compose.yml编排文件backend/后端服务代码frontend/前端代码config/或.env.example配置模板data/文档存储目录可能需要手动创建我的习惯是先把.env.example复制成.env然后逐项填写。不要直接改.env.example否则后续更新代码时容易冲突。3.2 配置文件逐项解读打开.env文件你会看到一堆配置项。挑几个最关键的说明数据库相关POSTGRES_USERweknora POSTGRES_PASSWORDyour_password POSTGRES_DBweknora DATABASE_URLpostgresql://weknora:your_passworddb:5432/weknora注意DATABASE_URL里的主机名是db这是 Docker Compose 里的服务名。如果你改成localhost容器内部是连不上的。大模型相关LLM_API_KEYsk-xxxxxxxx LLM_BASE_URLhttps://api.example.com/v1 LLM_MODEL_NAMEhunyuan-lite EMBEDDING_API_KEYsk-xxxxxxxx EMBEDDING_BASE_URLhttps://api.example.com/v1 EMBEDDING_MODEL_NAMEtext-embedding-3-small这里有个细节有些平台的对话模型和嵌入模型用的是同一个 API Key有些是分开的。根据你选的服务商填写。应用相关APP_PORT8080 SECRET_KEYrandom_string_hereSECRET_KEY用于会话加密随便生成一串随机字符即可但不要用默认值。3.3 启动服务与验证配置完成后执行docker compose up -d-d表示后台运行。然后查看日志docker compose logs -f重点关注后端服务的日志。正常启动会看到数据库连接成功、迁移完成、服务监听在某个端口。如果看到Connection refused或Authentication failed回去检查数据库配置。启动完成后浏览器访问http://你的服务器IP:8080应该能看到登录或注册页面。首次使用需要创建管理员账号。提示如果页面打不开先用docker compose ps确认所有容器都是Up状态再用curl http://localhost:8080在服务器本地测试。如果本地能通但外部访问不了检查防火墙和安全组规则。3.4 上传第一份文档并测试问答登录后创建一个知识库然后上传一份文档。建议先用一份结构清晰的 Markdown 或 Word 文档测试不要一上来就传几百页的扫描版 PDF。上传后系统会自动解析和向量化。你可以在文档列表里看到处理状态。处理完成后进入对话界面问一个文档里明确有答案的问题。比如文档里写了“本系统默认端口为 8080”你就问“系统默认端口是多少”。如果回答正确说明全流程通了。如果回答不对先检查文档是否解析成功——有些 PDF 是图片扫描版需要 OCR 才能提取文字而 WeKnora 默认可能不带 OCR 能力。4. 文档处理与检索效果调优4.1 文档解析的常见坑与处理策略文档解析是 RAG 系统里最容易被忽视但影响最大的环节。我踩过的坑包括PDF 里的表格丢失结构很多 PDF 解析库会把表格拆成一行行文字丢失行列关系。如果文档里大量关键信息在表格中检索效果会很差。处理办法是尽量上传原始 Word 或 Markdown 版本或者在解析后人工检查关键文档的提取结果。扫描版 PDF 无法提取文字纯图片 PDF 需要 OCR。WeKnora 是否内置 OCR 取决于版本和配置。如果没有你需要先用其他工具把 PDF 转成可搜索的 PDF或者手动整理成文本再上传。页眉页脚干扰有些 PDF 每页都有公司名称、页码等重复内容这些会被切进文本块影响检索相关性。如果问题严重可以在解析前用工具去掉页眉页脚。编码问题中文文档如果编码识别错误会出现乱码。上传后务必抽查几段文本确认没有乱码。4.2 切块策略粒度决定检索质量切块Chunking是把长文档切成小段的过程每段会单独生成向量。切块大小直接影响检索效果切得太碎每个块只有一两句话语义不完整检索时可能召回很多无关片段。切得太大一个块包含多个主题向量表征被稀释检索精度下降。WeKnora 通常有默认的切块大小和重叠长度。以我的经验中文文档的切块大小在 300-500 字比较合适重叠 50-100 字。重叠是为了避免一个完整的句子被切断。如果你发现检索结果总是差一点可以尝试调整切块参数后重新处理文档。但注意重新处理会重新生成向量耗时较长建议先用小批量文档测试。4.3 检索参数调整Top-K 与相似度阈值检索阶段有两个关键参数Top-K每次检索返回多少个最相关的块。K 太小可能漏掉关键信息K 太大则上下文过长可能超出大模型的上下文窗口也会引入噪声。一般从 3-5 开始调。相似度阈值低于这个阈值的块会被过滤掉。如果阈值太高可能什么都召不回太低则引入无关内容。这个值需要根据你的嵌入模型和实际数据分布来调。我的做法是先用默认参数跑一批测试问题观察召回结果。如果发现正确答案所在的块经常排在 Top-5 之外说明切块或嵌入模型有问题如果召回的块很多但都不相关说明阈值太低或切块太碎。4.4 嵌入模型的选择与替换嵌入模型是 RAG 的“搜索引擎核心”。不同嵌入模型在中文语义理解上差异明显。选择时考虑维度维度越高表达能力越强但存储和计算成本也越高。768 维是常见折中。中文支持有些开源嵌入模型主要在英文语料上训练中文效果一般。优先选明确支持中文的模型。API 稳定性如果用 API 方式要确保服务商稳定否则批量处理文档时容易中断。替换嵌入模型后所有文档都需要重新向量化因为不同模型的向量空间不兼容。这是个大工程所以初期选型要慎重。5. 常见问题排查与运维经验5.1 服务启动失败排查清单现象可能原因排查方法容器不断重启配置文件错误docker compose logs 服务名看报错数据库连接失败密码错误或主机名不对检查.env里DATABASE_URL端口被占用本机已有服务占用端口netstat -tlnp查看端口前端白屏后端 API 地址配置错误浏览器 F12 看网络请求上传文档无响应文件过大或格式不支持看后端日志换小文件测试5.2 问答效果差的排查思路问答效果差通常表现为答非所问、回答“我不知道”、或者胡编乱造。排查顺序第一步确认文档是否解析成功。在知识库详情里看文档的文本提取结果如果提取出来是空的或乱码后面全白搭。第二步手动测试检索。有些版本提供检索测试接口你可以直接输入问题看召回了哪些块。如果召回块里根本没有正确答案说明是检索问题如果召回了但模型没用好说明是提示词或模型问题。第三步检查提示词模板。WeKnora 的提示词决定了如何把检索结果和问题拼给大模型。如果提示词写得太模糊模型可能忽略上下文。可以尝试调整提示词明确要求“仅根据以下资料回答”。第四步换一个更强的大模型测试。有时候确实是模型能力不够尤其是需要多步推理的问题。5.3 数据备份与迁移注意事项WeKnora 的数据主要包括PostgreSQL 数据库存向量和元数据、上传的原始文档、配置文件。备份时这三样都要覆盖。PostgreSQL 备份用pg_dumpdocker compose exec db pg_dump -U weknora weknora backup.sql恢复时先建空库再导入。注意 pgvector 扩展要先启用。迁移到新服务器时除了数据还要确保新环境的 Docker 版本、配置文件和原环境一致。特别是.env里的SECRET_KEY如果变了已登录用户的会话会失效。5.4 性能优化与资源控制当文档量增大、并发用户增多时可能会遇到性能瓶颈。几个优化方向向量索引pgvector 支持 IVFFlat 和 HNSW 索引。数据量超过几万条时建索引能显著提升检索速度。但建索引需要额外时间和内存。限制上传文件大小在 Nginx 或应用层限制单文件大小避免超大文件拖垮解析服务。异步处理文档解析和向量化是耗时操作确保是异步队列处理不阻塞 Web 请求。缓存对常见问题可以加一层缓存相同问题直接返回上次结果减少大模型调用。6. 进阶玩法与扩展思路6.1 对接企业现有系统WeKnora 提供 API可以和企业现有的 OA、IM、工单系统对接。比如在内部 IM 里加一个机器人员工直接对话提问后台调用 WeKnora 的问答接口。这样不用改变员工使用习惯推广阻力小很多。对接时注意鉴权。WeKnora 的 API 通常需要 Token不要直接把 Token 写在前端代码里应该由后端代理请求。6.2 多知识库与权限隔离企业里不同部门的知识库可能需要隔离。WeKnora 支持创建多个知识库你可以按部门或业务线划分。权限控制方面需要确认版本是否支持细粒度权限。如果不支持可以通过部署多套实例来实现物理隔离但运维成本会高一些。6.3 结合工作流实现自动化一个实用的扩展是当有新文档上传时自动触发向量化并通知相关人员。这可以用 Webhook 或定时任务实现。另外可以定期用一批测试问题评估知识库的问答准确率形成质量监控。我在实际使用中的体会是RAG 知识库的效果上限取决于文档质量下限取决于切块和检索参数。花时间整理文档、调好切块策略比换更贵的大模型更有效。另外不要指望一次配置就完美先跑通再根据真实问题迭代这才是最务实的做法。 腾讯开源WeKnora：基于RAG的企业级知识库部署与调优实战
1. 为什么企业需要一个“会说话”的知识库1.1 从“文档坟场”到“智能问答”的转变很多公司都面临一个尴尬的现实内部文档越积越多从产品手册、技术规范到客服话术、运维记录散落在各个网盘、Wiki、甚至个人电脑里。员工想找一份半年前的项目复盘得在群里问一圈最后发现只有离职的那位同事电脑里有。这就是典型的“文档坟场”——存了很多但用不起来。WeKnora 要解决的就是这个问题。它本质上是一套基于RAG检索增强生成架构的企业知识库系统由腾讯开源。你可以把它理解成一个“会说话”的文档中心你把公司内部的 PDF、Word、Markdown、网页链接等资料喂给它它自动完成解析、切块、向量化然后当员工用自然语言提问时它能从这些资料里找到最相关的片段再交给大语言模型组织成一段通顺、有依据的回答。和传统关键词搜索最大的区别在于关键词搜索要求你猜文档里用了什么词而 RAG 知识库允许你像问同事一样提问。比如“去年双十一大促期间订单服务的限流阈值调整到多少了”——这种问题在传统搜索里几乎无解但在 WeKnora 里只要相关复盘文档在库中它就能定位到具体段落并给出答案。1.2 WeKnora 适合哪些场景和人群从实际落地经验看WeKnora 最适用的场景有这么几类技术团队内部知识管理API 文档、架构决策记录、故障复盘、部署手册统一入库新成员入职时直接问系统减少老员工重复答疑。客服与售后支持把产品说明书、常见问题、历史工单处理记录导入客服人员可以快速检索标准话术和处理方案。销售与售前支持产品报价、竞品对比、成功案例、合同模板等资料集中管理销售在客户现场也能快速调取准确信息。个人知识库如果你有大量技术笔记、论文、电子书也可以本地部署一套当作自己的“第二大脑”。适合阅读这篇内容的人包括运维工程师、后端开发、技术负责人、IT 支持人员以及任何想在自己环境里跑通一套 RAG 知识库的爱好者。不需要你是 AI 专家但需要你熟悉基本的 Linux 命令和 Docker 操作。1.3 整体架构速览WeKnora 由哪些部分组成WeKnora 的架构设计比较清晰核心组件包括前端界面提供知识库管理、文档上传、对话问答的 Web 界面。后端服务基于 FastAPI 构建负责文档解析、切块、向量化、检索和对话编排。向量数据库默认使用 PostgreSQL pgvector 扩展存储文档切块的向量表示。大语言模型接入层支持对接多种大模型 API也支持本地部署的模型。文档解析模块处理 PDF、Word、Markdown、HTML 等格式提取纯文本。整个数据流是这样的文档上传 → 解析提取文本 → 按策略切块 → 调用嵌入模型生成向量 → 存入 pgvector → 用户提问 → 问题向量化 → 向量检索 Top-K 相关块 → 拼接上下文交给大模型 → 生成回答返回前端。理解这个流程很重要因为后面排查问题时你需要知道是解析阶段丢了内容、切块阶段切碎了语义、还是检索阶段没召回正确片段。2. 部署前的环境准备与关键决策2.1 硬件与操作系统选择WeKnora 对硬件的要求取决于你选择哪种大模型接入方式。如果使用云端大模型 API如腾讯混元、DeepSeek 等那么本地机器只需要承担文档解析、向量化和向量检索的工作配置要求不高CPU4 核以上内存8GB 以上如果文档量大建议 16GB磁盘至少 20GB 可用空间主要用于存放 Docker 镜像、PostgreSQL 数据和上传的文档操作系统Ubuntu 20.04/22.04 LTS 最稳妥CentOS 7.9 也可以但需要额外处理一些依赖如果你想完全本地化连大模型也在本地跑那硬件要求就高多了。以 7B 参数量的模型为例量化后大约需要 6-8GB 显存加上向量化和检索的开销建议至少 16GB 显存的 GPU。如果只是体验可以用 CPU 推理但速度会慢到影响使用体验。我个人的建议是初次搭建先用云端 API 跑通全流程确认业务价值后再考虑本地化部署。这样能快速验证效果避免在环境问题上消耗过多精力。2.2 Docker 与 Docker Compose 安装WeKnora 官方推荐用 Docker Compose 部署这是最省心的方式。安装 Docker 的步骤这里不展开网上资料很多。重点提醒几个容易出问题的地方第一Docker 版本不要太老。建议 Docker 20.10 以上Docker Compose v2 以上。用docker compose version检查如果显示的是docker-compose带横杠说明是 v1建议升级。第二配置国内镜像加速。拉取镜像时如果速度慢可以在/etc/docker/daemon.json里加上镜像加速地址。具体地址这里不列举你可以根据自己所在网络环境搜索可用的加速服务。第三确保当前用户有 Docker 执行权限。要么用sudo要么把用户加入docker组sudo usermod -aG docker $USER然后重新登录生效。安装完成后用docker run hello-world验证一下能正常输出就说明基础环境没问题。2.3 大模型 API 的选择与配置思路WeKnora 支持多种大模型接入方式这是它比较灵活的地方。你需要准备两类模型的接入信息对话模型负责根据检索到的上下文生成回答。可选的有腾讯混元、DeepSeek、通义千问等。选择时主要考虑三点一是 API 是否稳定二是价格是否可接受三是中文理解能力是否够强。从实际使用看混元和 DeepSeek 在中文企业场景下表现都不错。嵌入模型负责把文本转换成向量。这个模型的选择直接影响检索效果。WeKnora 默认可能使用某个开源嵌入模型你也可以配置成 API 方式。嵌入模型不需要太强的生成能力但要求语义表征准确、维度适中通常 768 或 1024 维。配置方式一般是在.env文件或config.yaml里填写 API Key、Base URL 和模型名称。这里有个经验先把 API Key 在 curl 里测试通过再填到配置文件里。我见过不少人因为 Key 复制时多了空格、或者 Base URL 路径不对导致服务启动后一直报鉴权失败。注意API Key 属于敏感信息不要提交到 Git 仓库。建议用.env文件管理并把.env加入.gitignore。2.4 数据库与向量存储的初始化WeKnora 用 PostgreSQL pgvector 作为向量存储。Docker Compose 文件里通常已经定义好了数据库服务你只需要确保数据库端口不冲突默认 5432如果本机已有 PostgreSQL 在跑需要改成其他端口数据卷挂载正确否则容器重启后数据丢失pgvector 扩展已启用首次启动时后端服务会自动执行数据库迁移创建必要的表和索引。你可以在日志里看到类似Running migrations...的输出。如果卡在这里多半是数据库连接配置不对检查DATABASE_URL环境变量。3. 从零搭建 WeKnora 的完整实操3.1 获取源码与目录结构说明从官方仓库克隆代码git clone https://github.com/Tencent/WeKnora.git cd WeKnora克隆完成后先别急着启动花两分钟看一下目录结构。通常会有这几个关键目录docker/或根目录下的docker-compose.yml编排文件backend/后端服务代码frontend/前端代码config/或.env.example配置模板data/文档存储目录可能需要手动创建我的习惯是先把.env.example复制成.env然后逐项填写。不要直接改.env.example否则后续更新代码时容易冲突。3.2 配置文件逐项解读打开.env文件你会看到一堆配置项。挑几个最关键的说明数据库相关POSTGRES_USERweknora POSTGRES_PASSWORDyour_password POSTGRES_DBweknora DATABASE_URLpostgresql://weknora:your_passworddb:5432/weknora注意DATABASE_URL里的主机名是db这是 Docker Compose 里的服务名。如果你改成localhost容器内部是连不上的。大模型相关LLM_API_KEYsk-xxxxxxxx LLM_BASE_URLhttps://api.example.com/v1 LLM_MODEL_NAMEhunyuan-lite EMBEDDING_API_KEYsk-xxxxxxxx EMBEDDING_BASE_URLhttps://api.example.com/v1 EMBEDDING_MODEL_NAMEtext-embedding-3-small这里有个细节有些平台的对话模型和嵌入模型用的是同一个 API Key有些是分开的。根据你选的服务商填写。应用相关APP_PORT8080 SECRET_KEYrandom_string_hereSECRET_KEY用于会话加密随便生成一串随机字符即可但不要用默认值。3.3 启动服务与验证配置完成后执行docker compose up -d-d表示后台运行。然后查看日志docker compose logs -f重点关注后端服务的日志。正常启动会看到数据库连接成功、迁移完成、服务监听在某个端口。如果看到Connection refused或Authentication failed回去检查数据库配置。启动完成后浏览器访问http://你的服务器IP:8080应该能看到登录或注册页面。首次使用需要创建管理员账号。提示如果页面打不开先用docker compose ps确认所有容器都是Up状态再用curl http://localhost:8080在服务器本地测试。如果本地能通但外部访问不了检查防火墙和安全组规则。3.4 上传第一份文档并测试问答登录后创建一个知识库然后上传一份文档。建议先用一份结构清晰的 Markdown 或 Word 文档测试不要一上来就传几百页的扫描版 PDF。上传后系统会自动解析和向量化。你可以在文档列表里看到处理状态。处理完成后进入对话界面问一个文档里明确有答案的问题。比如文档里写了“本系统默认端口为 8080”你就问“系统默认端口是多少”。如果回答正确说明全流程通了。如果回答不对先检查文档是否解析成功——有些 PDF 是图片扫描版需要 OCR 才能提取文字而 WeKnora 默认可能不带 OCR 能力。4. 文档处理与检索效果调优4.1 文档解析的常见坑与处理策略文档解析是 RAG 系统里最容易被忽视但影响最大的环节。我踩过的坑包括PDF 里的表格丢失结构很多 PDF 解析库会把表格拆成一行行文字丢失行列关系。如果文档里大量关键信息在表格中检索效果会很差。处理办法是尽量上传原始 Word 或 Markdown 版本或者在解析后人工检查关键文档的提取结果。扫描版 PDF 无法提取文字纯图片 PDF 需要 OCR。WeKnora 是否内置 OCR 取决于版本和配置。如果没有你需要先用其他工具把 PDF 转成可搜索的 PDF或者手动整理成文本再上传。页眉页脚干扰有些 PDF 每页都有公司名称、页码等重复内容这些会被切进文本块影响检索相关性。如果问题严重可以在解析前用工具去掉页眉页脚。编码问题中文文档如果编码识别错误会出现乱码。上传后务必抽查几段文本确认没有乱码。4.2 切块策略粒度决定检索质量切块Chunking是把长文档切成小段的过程每段会单独生成向量。切块大小直接影响检索效果切得太碎每个块只有一两句话语义不完整检索时可能召回很多无关片段。切得太大一个块包含多个主题向量表征被稀释检索精度下降。WeKnora 通常有默认的切块大小和重叠长度。以我的经验中文文档的切块大小在 300-500 字比较合适重叠 50-100 字。重叠是为了避免一个完整的句子被切断。如果你发现检索结果总是差一点可以尝试调整切块参数后重新处理文档。但注意重新处理会重新生成向量耗时较长建议先用小批量文档测试。4.3 检索参数调整Top-K 与相似度阈值检索阶段有两个关键参数Top-K每次检索返回多少个最相关的块。K 太小可能漏掉关键信息K 太大则上下文过长可能超出大模型的上下文窗口也会引入噪声。一般从 3-5 开始调。相似度阈值低于这个阈值的块会被过滤掉。如果阈值太高可能什么都召不回太低则引入无关内容。这个值需要根据你的嵌入模型和实际数据分布来调。我的做法是先用默认参数跑一批测试问题观察召回结果。如果发现正确答案所在的块经常排在 Top-5 之外说明切块或嵌入模型有问题如果召回的块很多但都不相关说明阈值太低或切块太碎。4.4 嵌入模型的选择与替换嵌入模型是 RAG 的“搜索引擎核心”。不同嵌入模型在中文语义理解上差异明显。选择时考虑维度维度越高表达能力越强但存储和计算成本也越高。768 维是常见折中。中文支持有些开源嵌入模型主要在英文语料上训练中文效果一般。优先选明确支持中文的模型。API 稳定性如果用 API 方式要确保服务商稳定否则批量处理文档时容易中断。替换嵌入模型后所有文档都需要重新向量化因为不同模型的向量空间不兼容。这是个大工程所以初期选型要慎重。5. 常见问题排查与运维经验5.1 服务启动失败排查清单现象可能原因排查方法容器不断重启配置文件错误docker compose logs 服务名看报错数据库连接失败密码错误或主机名不对检查.env里DATABASE_URL端口被占用本机已有服务占用端口netstat -tlnp查看端口前端白屏后端 API 地址配置错误浏览器 F12 看网络请求上传文档无响应文件过大或格式不支持看后端日志换小文件测试5.2 问答效果差的排查思路问答效果差通常表现为答非所问、回答“我不知道”、或者胡编乱造。排查顺序第一步确认文档是否解析成功。在知识库详情里看文档的文本提取结果如果提取出来是空的或乱码后面全白搭。第二步手动测试检索。有些版本提供检索测试接口你可以直接输入问题看召回了哪些块。如果召回块里根本没有正确答案说明是检索问题如果召回了但模型没用好说明是提示词或模型问题。第三步检查提示词模板。WeKnora 的提示词决定了如何把检索结果和问题拼给大模型。如果提示词写得太模糊模型可能忽略上下文。可以尝试调整提示词明确要求“仅根据以下资料回答”。第四步换一个更强的大模型测试。有时候确实是模型能力不够尤其是需要多步推理的问题。5.3 数据备份与迁移注意事项WeKnora 的数据主要包括PostgreSQL 数据库存向量和元数据、上传的原始文档、配置文件。备份时这三样都要覆盖。PostgreSQL 备份用pg_dumpdocker compose exec db pg_dump -U weknora weknora backup.sql恢复时先建空库再导入。注意 pgvector 扩展要先启用。迁移到新服务器时除了数据还要确保新环境的 Docker 版本、配置文件和原环境一致。特别是.env里的SECRET_KEY如果变了已登录用户的会话会失效。5.4 性能优化与资源控制当文档量增大、并发用户增多时可能会遇到性能瓶颈。几个优化方向向量索引pgvector 支持 IVFFlat 和 HNSW 索引。数据量超过几万条时建索引能显著提升检索速度。但建索引需要额外时间和内存。限制上传文件大小在 Nginx 或应用层限制单文件大小避免超大文件拖垮解析服务。异步处理文档解析和向量化是耗时操作确保是异步队列处理不阻塞 Web 请求。缓存对常见问题可以加一层缓存相同问题直接返回上次结果减少大模型调用。6. 进阶玩法与扩展思路6.1 对接企业现有系统WeKnora 提供 API可以和企业现有的 OA、IM、工单系统对接。比如在内部 IM 里加一个机器人员工直接对话提问后台调用 WeKnora 的问答接口。这样不用改变员工使用习惯推广阻力小很多。对接时注意鉴权。WeKnora 的 API 通常需要 Token不要直接把 Token 写在前端代码里应该由后端代理请求。6.2 多知识库与权限隔离企业里不同部门的知识库可能需要隔离。WeKnora 支持创建多个知识库你可以按部门或业务线划分。权限控制方面需要确认版本是否支持细粒度权限。如果不支持可以通过部署多套实例来实现物理隔离但运维成本会高一些。6.3 结合工作流实现自动化一个实用的扩展是当有新文档上传时自动触发向量化并通知相关人员。这可以用 Webhook 或定时任务实现。另外可以定期用一批测试问题评估知识库的问答准确率形成质量监控。我在实际使用中的体会是RAG 知识库的效果上限取决于文档质量下限取决于切块和检索参数。花时间整理文档、调好切块策略比换更贵的大模型更有效。另外不要指望一次配置就完美先跑通再根据真实问题迭代这才是最务实的做法。