企业官网建设流程全解析

去年年初我们团队接了一个内部知识库的项目，要求把几十万份产品文档、故障工单和技术规范变成可检索、可问答的资产。一开始我们天真地以为“接个大模型API就完事了”，结果两个月下来，最耗精力的根本不是模型本身，而是围绕知识接入、解析、检索、权限、更新这一整条链路。后来换成了腾讯开源的WeKnora做底座，才算是真正把“LLM知识平台”这几个字落到了地上。

这篇内容不是官方文档的复述，而是我们团队从选型评估到本地部署、再到生产环境排障的完整记录。如果你是公司里负责LLM应用落地的人，或者正在纠结“知识库到底该自己拼还是用一个成熟平台”，这篇文章应该能帮你少踩不少坑。

1. 为什么企业知识库不能靠“模型 + 向量库”硬拼

先聊聊选型逻辑。很多人一听到知识库问答，第一反应就是“用LangChain把文档切了塞进向量数据库，再回调大模型”。这套路在Demo里确实跑得通，demo里那二三十个PDF都是干净整洁的。但企业里的真实文档完全是另一个物种：扫描件、表格、复杂排版、专业术语、多级目录、甚至是发黄的老工单截图。

先说解析这块。开源社区里用的比较多的方案是 unstructured / PyMuPDF / Tika，单独看都能用，但放到企业环境里你要自己解决的事情非常多——OCR引擎要不要接？表格要不要转成结构化数据？PDF里嵌的图片怎么处理？老文档的编码混乱谁来清洗？这些问题一个接一个冒出来的时候，你实际上已经不是在搭知识库了，你是在做一套文档解析中间件，工程量立马失控。

再说检索。向量检索听起来简单，但“切多长的chunk”这一件事就能让效果天差地别。我们最初直接用固定512token切，结果大量产品型号被切在了两个chunk里，混合检索和重排就更不用说了——BM25要不要做？rerank模型选哪个？每个环节都得自己调，每个环节都是坑。

WeKnora之所以能吸引我们，是因为它把这些事做成了平台能力，而不是留给调用方一堆散装的Python脚本。它天然包含了我说的这些组件：文档解析、知识管理、检索、重排、LLM编排，还带一套知识管理系统和可视化后台。我们要做的，是把公司内部的知识源接进去，而不是从零开始写一套 RAG 管道。

用一句话总结就是：如果你只需要做十几个文档的问答 Demo，那自己拼完全没问题；但如果你要支撑的是几千人同时查询的生产系统，你需要的是一个能扛住版本迭代、权限隔离和解析长尾问题的平台底座。WeKnora 在这条路上给了一个相当完整的参考实现。

2. WeKnora的核心架构拆解：从知识注入到问题回答的完整链路

WeKnora 的架构如果只看官方那个大图会觉得有点晕，实际上它拆开了就五层：接入层、解析层、知识管理层、检索增强层、LLM编排层。我按数据流向一个个说。

2.1 接入层与文档解析：先解决“知识进得来”的问题

知识进得来的前提是文档解析。WeKnora 的解析模块不是简单调用一两个Python库，它把解析做成了独立服务，能适配 PDF、Word、Markdown、HTML 等主流格式，并且支持 OCR 识别扫描件。尤其在处理带复杂表格的PDF时，它能尝试还原表格结构，而不是把表格压成一坨乱序文本。

我们在接入中发现，解析质量直接决定后续检索的天花板。解析阶段丢的信息，后面任何 fancy 的LLM技巧都找不回来。所以第一步先把源文档按类型分好：技术手册走版面解析，扫描工单走OCR链路，纯文本走轻量解析。这个分类听起来简单，但它避免了所有文档涌进同一个解析模型导致的通用性下降。

2.2 知识管理层：数据不是塞进向量库就完事了

很多自研RAG系统会忽略这一层，文档切完直接embedding入库，知识就变成了黑盒子。WeKnora 的做法更接近企业知识管理系统的思路——它给每个知识对象建立了目录、标签、元数据和版本管理的维度，并且有知识集合（Knowledge Base）的概念。

你可能觉得这些是“管理员的洁癖”，但在生产环境里，元数据的作用非常实际。比如我们接入产品文档时给每个文档打上“产品线”“适用版本”“更新时间”标签，用户提问时就能按产品线过滤范围，既提升了检索精度，又能在后续做权限控制时按目录维度直接隔离数据。没有元数据，你就只能面向一锅粥做检索。

2.3 检索与重排：双路召回加精排，效果比单路向量好一个量级

WeKnora 的检索采用了混合检索思路，向量召回和 BM25 关键词召回并行，然后过一个 Rerank 模型做精排。这个设计跟 LangChain 文档里推荐的 RAG 模式是吻合的，真正实现的时候差别在于细节。

我们的实测数据是：在内部故障工单场景下，单路向量检索的 Top5 准确率大概在 60% 左右，加上 BM25 混合之后能到 75%，再加 Rerank 精排能到 85% 以上。如果你现在用的方案里没有 Rerank，我建议下一步就补上，它是性价比最高的一层优化。

Rerank 模型的选型也提一句：不要盲目追求排行榜上分数最高的模型，要看它的推理延迟。知识库问答是交互场景，检索阶段如果多花 1 秒做精排，用户体感就会变差。我们后来在速度和效果之间做了平衡，选了一个中型模型，单次精排 200 毫秒级别，整体链路才舒服。

2.4 LLM编排层：为什么还需要一个 Harness 概念

这是 WeKnora 里跟 LangChain 类框架最像的一层，也是最容易被低估的一层。我们看热搜词里出现了“harness架构(langchain+langgraph)智能体开发案例”，其实在 WeKnora 里 Harness 的含义更克制——它不是一个通用 Agent 框架，而是把 LLM 调用过程编排好：提示词模板管理、上下文组装、外部工具调用、输出结构化解析、多轮对话状态维护。

我见过不少人问“WeKnora 和 LangChain 有什么区别”。我的理解是：LangChain 是工具箱，什么都能拼；WeKnora 是已经替你拼好了一整套 RAG 知识问答系统，它内部也用到了类似 LangChain 的编排思想，但不需要你自己去串联各个环节。你把 API 或者 SDK 接进来，拿到的是可用的知识问答能力，而不是一堆组件接口。

这样做的好处是出问题时能收敛。LangChain 方案的报错经常是“链子断在哪一环得自己查”，而 WeKnora 的日志会把解析、检索、重排、生成拆得比较清楚，哪个环节慢、哪个环节报错，一目了然。省下来的排查时间，在生产环境里真的非常值钱。

3. 本地部署实录：Windows 11 和 Linux 环境下的安装与初始配置

WeKnora 的部署是前后端分离的架构，包含后端 API、任务队列 Worker、前端页面和知识管理服务几个部分。很多人卡在第一步就是没搞清楚哪些服务要一起起来。

3.1 Linux 服务器部署的基本流程

我们生产环境用 Docker Compose 部署，这里列一下核心步骤（基于常见实践补充）：

# 1. 克隆代码仓库 git clone https://github.com/Tencent/WeKnora.git cd WeKnora # 2. 创建并激活 Python 虚拟环境（要求 Python 3.10+） python3.10 -m venv venv source venv/bin/activate # 3. 安装后端与 Worker 依赖 pip install -r requirements.txt # 4. 启动核心中间件（向量库、缓存、任务队列） docker compose up -d # 5. 初始化数据库并创建管理员账号 python manage.py migrate python manage.py createsuperuser # 6. 启动后端服务、任务队列 Worker 与前端 python manage.py runserver 0.0.0.0:8080 celery -A core worker -l info &

第一次部署最需要注意的坑是版本匹配。WeKnora 对 Python 版本比较敏感，我们用 Python 3.8 尝试时直接跑不起来，换 3.10 之后就顺利很多。另外 Vector 数据库的版本也要跟 compose 文件里锁定的版本保持一致，否则会出现连接被拒或者索引崩溃的问题。

3.2 Windows 11 本地开发环境的特别说明

看到热搜里有“weknora windows11 下安装”，我自己也在 Windows 11 上试过一次。结论是：能跑，但你不应该直接在 Windows 里跑生产环境。

WeKnora 的依赖里有不少 Linux 生态的库（比如某些解析器和二进制工具），Windows 上缺编译环境会报一些莫名奇妙的错。我们测试机上的做法是装 WSL2，然后在 Ubuntu 里按 Linux 流程走。如果只是个人学习，直接用 Windows 安装也可以试试，但记得提前装好 Microsoft C++ Build Tools，很多 Python 包在 Windows 上安装失败就是缺这个。

如果你不想碰冷门依赖，最简单的办法还是搞一台 Linux 虚拟机，或者直接 Windows 上用 WSL2。本地跑通之后，再把整套配置搬到服务器，路径最顺。

3.3 模型接入：Ollama 本地模型与 API Key 两种方式

WeKnora 支持配置多种 LLM 服务来源，包括 OpenAI 风格接口和兼容本地推理的接入方式。两种方式我们都试过：

• API模式：在系统设置里填 API Base 和 Key，适合公司已有模型网关的情况，配置最简单。这里的 Key 建议用项目级密钥，而不是个人密钥——后面的安全章节我会细说。
• 本地模型模式：通过 Ollama 拉取 Qwen 等开源模型，配置在本地地址。优势是数据不出内网，但推理速度和效果上限受限于你的显卡。我们内部跑过 7B 和 14B 模型，7B 做简单查证够用，做多跳推理和长文档总结就比较吃力。

另外提一个常被问到的问题：“deepseek 属于哪个？”DeepSeek 本身就是一个大语言模型，跟 Qwen、Llama 是同一类东西。WeKnora 只要能配置 OpenAI 兼容接口，就能把 DeepSeek 这类国产模型接进来用，不冲突。对那些对数据合规敏感的企业，这反而是个好消息：你完全可以用国产模型 + 本地化部署来满足监管要求。

4. 生产环境必须面对的硬话题：鉴权安全、文档解析失败与版本升级

部署只是个开始，真正让人头大的是上线之后那些“预期之外”的事。把我们在生产环境遇到的高频问题按优先级排一下，大概是密钥安全、解析失败、版本升级这三类。

4.1 使用LLM时如何防止密钥与鉴权信息泄露

为什么这个问题要单独拎出来说？因为知库这类应用天然会接触敏感数据：员工问的是内部信息，系统配置里可能存着第三方模型的 API Key，如果处理不当，密钥很容易泄露。

我们团队立了几条规矩，现在每次接入新系统都会过一遍：

• API Key 一律放服务端环境变量或密钥管理系统，绝不进代码仓库。前端配置项里要用的敏感信息，也要通过后端代理注入，而不是直接写死在前端构建产物里。
• 按项目维度区分密钥，做到最小权限。如果一个 Key 只用于某个知识库的向量化任务，就不要给它其他模型服务的权限。出了问题也只影响一个面。
• 建立模型网关层做统一的鉴权和审计。这样一来，WeKnora 面对的是网关，网关统一控制哪些用户能调用哪个模型、额度多少、有没有异常调用。日志里出现可疑的批量请求时能及时发现。

在自研 RAG 项目里，密钥管理常常被当成“最后再说的事”，但真实世界里它往往是最早出事的事。企业级 LLM 平台如果没有一层安全边界，上了生产你晚上是睡不踏实的。

4.2 文档解析失败：根因定位与解决路径

“weknora解析失败的原因是什么”能进热搜，说明这不是我们一家遇到的问题。我们排查后归纳出四类主要根因：

• 文件格式识别异常。比如某些扫描工具的 PDF 实际上没嵌入文本层，WeKnora 会走 OCR 流程，如果部署环境没装好 OCR 依赖，就会出现解析失败。解决办法是确认 OCR 相关组件安装完整。
• 文档编码混乱。老导出工具生成的文件偶尔会有奇怪的编码，导致文本提取出来是乱码。多数情况需要先用工具批量清洗后再喂给平台。
• 依赖模型或资源缺失。有些解析模块依赖特定模型文件，如果下载不完整，解析会超时或直接报错。这一步在日志里定位很快，缺哪个补哪个。
• 超大文件超时。我们有一批几百 MB 的技术手册，默认任务超时时间不够，解析任务直接被杀掉。解决方式是调整 Worker 的超时时间和内存限制，并把大文件拆分后再投喂。

建议排查路径：先看任务队列的日志返回的是“解析器报错”“资源不足”还是“任务超时”，这三类问题的解决路径完全不同。盲目重新解析只会浪费算力。

4.3 腾讯云上的WeKnora如何更新版本

我们有一套环境跑在云主机上，升级流程也踩过几次坑。WeKnora 的版本更新一般走三步：

1. 拉取最新代码：git pull，注意先看 release notes 有没有破坏性变更。
2. 更新依赖并执行迁移：pip install -r requirements.txt，然后python manage.py migrate，数据库结构变了的话这里会一起处理。
3. 重启服务并观察任务队列：如果新增了解析器或检索模型，建议先小范围测试，再全量重建索引，避免新旧索引格式混用导致查询异常。

一个小教训：升级后文档索引最好重建，尤其是向量化模型版本有变化的时候。老向量和新向量如果在不同维度空间里，混在一起检索的效果会很奇怪，表现为“能查到文档但相似度得分整体偏低”，这种问题靠调参是解决不了的，只能重建索引。

5. 从“跑通”到“好用”：知识库效果调优与长期运维的隐性工作

如果只是想让知识库“能回答”,部署完就够用了。但如果你希望它真正变成一个能天天被员工信任的工具，那还有一截里路程要走。

5.1 分块参数、Embedding模型和重排策略的配合

这三点是决定检索效果最直接的三组参数。WeKnora 里可以把它们分开配，但真正调优时必须合在一起看。

我们测试下来的经验是：

如果出现“明明库里有答案但大模型答不上来”的情况，先别急着换大模型，先检查 Top-K 和重排配置——大概率是答案没有进到最终上下文里。

5.2 从单点问答走向智能体编排

知识库跑通之后，很多人会想在它外面再套一层 Agent 能力，让AI不只是回答问题，还能执行操作：比如根据故障排查手册定位问题、联动监控系统查状态、调用工具生成工单。WeKnora 里已经有 Harness 机制可以承载这种编排逻辑，LangGraph 那套状态机思路也能用它来实现。

我们的做法是：先用知识库解决“查文档”这个单一动作，把它做成一个工具；再在 Agent 编排层把这个工具跟其他系统接口串起来。这样知识库作为数据底座，Agent 作为交互前端。每一步都只做自己擅长的事，排查问题的时候也不会互相甩锅。

5.3 长期运维中最容易被忽略的几件事

最后说几个我们靠“被坑之后才记住”的运维要点：

• 全链路监控。一定记录好解析消耗、向量入库耗时、检索耗时、重排耗时、LLM 首字延迟。每多一组数据，排查问题时就多一分底气。
• 知识更新机制。企业知识不会静止，文档一变，老向量和新文档会产生语义冲突。我们后续的规划是把文档变更做成事件，触发增量重建，而不是每个月手动全量刷一次。
• 建立内测用户群。知识库好不好用，不是算法说了算，而是使用者说了算。我们每两周收集一次“答非所问”的案例，分类后反哺到分块策略和元数据规范里，效果比闷头调参好得多。

我可以很直接地说，WeKnora 不是装上就万事大吉的“一键知识库”，它更像一个骨架。但它帮我们省掉了从零搭建 RAG 平台最脏最累的那部分活——解析、混合检索、重排、知识管理、权限体系、版本升级路径。搭好之后，你真正要投入精力的是内容质量的维护和业务场景的适配。

如果你正准备在企业内部搭一个 LLM 知识平台，我建议你直接拿 WeKnora 当底座，先跑起来，再根据自己公司的数据形态做调优。比起在 LangChain 的海洋里反复横跳，这套工程化的东西能让你三个月后回头看时，发现自己确实在解决知识库问题，而不是在研究框架本身的 bug。