企业官网建设流程全解析

知识库问答系统这两年从"玩具"变成了"刚需"，但真正落到本地部署这一步，很多人卡在的不是模型，而是文档解析、向量检索、权限管理这一整条链路怎么串起来。WeKnora 是腾讯微信团队开源的一套 AI 知识库框架，定位很明确：把 RAG 的完整流程——文档解析、分块、向量化、检索、生成——打包成一套可以自己部署的服务，而不是让你从零拼 LangChain。我前后在几台机器上折腾过它的部署，踩过依赖冲突、模型下载、向量库连接这些坑，这篇就把整套流程和背后的取舍讲清楚，适合想搭私有知识库、又不想被云服务绑死的开发者参考。

1. 先搞清楚 WeKnora 到底解决了什么问题

1.1 它不是"又一个 ChatGPT 套壳"

很多人第一次听到"AI 知识库"，脑子里浮现的是把文档丢进去、然后套个大模型 API 就完事。这种方案在 demo 阶段没问题，一旦文档上到几百份、格式五花八门，问题立刻暴露：PDF 里的表格解析成乱码、扫描件根本读不出文字、检索出来的片段答非所问。

WeKnora 的价值在于它把 RAG 里最脏最累的活做成了工程化的模块。文档进来先走解析层，PDF、Word、Markdown、网页各有对应的处理逻辑；解析完做分块，分块策略直接决定检索质量；然后向量化入库，检索时做相似度召回，最后交给大模型生成答案。这一整条链路它都给了默认实现，你要做的是配置和调优，而不是从零写。

从关键词里能看到"腾讯云 vectordb""mineru 本地部署"这些词，说明大家关心的正是解析和向量存储这两个环节。WeKnora 在这两块都留了可替换的接口，这是它比很多"一体化黑盒"产品更实用的地方。

1.2 本地部署的真正动机

为什么非要本地部署？我总结下来无非三类需求。第一类是数据不能出内网，企业内部的合同、技术文档、客户资料，走公有云 API 意味着数据要离开自己的服务器，合规上过不去。第二类是成本，文档量大、查询频繁的场景，按 token 计费的云服务账单会很难看，本地跑一次投入长期摊薄。第三类是可控性，模型版本、检索参数、分块规则都能自己调，出问题能定位到具体环节。

WeKnora 的架构天然适配这三种诉求。它支持本地大模型（比如通过 Ollama 或 vLLM 部署的模型），也支持接云端 API；向量库可以选本地文件型，也可以接独立的向量数据库服务。这种"可插拔"设计意味着你可以先用最简配置跑通，再逐步替换成生产级组件。

1.3 部署前必须想清楚的三个问题

动手之前先回答自己三个问题，能省掉后面大量返工。

第一个是硬件。本地跑大模型对显存有硬要求，7B 参数的模型量化后大概需要 6-8GB 显存，13B 需要 12GB 以上。如果只是做检索、生成交给云端 API，那对硬件的要求会低很多，一台 8 核 16G 的普通服务器就够。你得先确定自己是"全本地"还是"混合"。

第二个是文档规模。几十份文档和几万份文档，对向量库的选型完全不同。小规模用内置的轻量向量存储就够，大规模必须上专业的向量数据库，否则检索延迟会随数据量线性上升。

第三个是并发量。内部几个人用和全公司几百人用，架构差别很大。前者单机单进程足够，后者要考虑服务拆分、负载均衡、缓存。

提示：不要一上来就追求"生产级架构"。先用最小配置跑通全流程，验证效果，再根据实际瓶颈做优化，这是最省时间的路径。

2. 环境准备：那些文档里不会写的依赖细节

2.1 基础环境的选择与版本锁定

WeKnora 是 Python 技术栈为主的项目，对 Python 版本有要求。我实测下来 3.10 和 3.11 最稳，3.12 在某些依赖上会有编译问题，3.9 则可能缺少一些新语法支持。用 conda 或 pyenv 把版本锁死，别用系统自带的 Python，否则后面依赖冲突会让你怀疑人生。

操作系统方面，Linux（Ubuntu 22.04 或 Debian 12）是最省心的选择，macOS 也能跑但部分依赖的编译需要额外装 Xcode 命令行工具，Windows 建议直接用 WSL2，原生 Windows 下有些包会装不上。

# 用 conda 创建独立环境，避免污染系统 Python conda create -n weknora python=3.11 -y conda activate weknora # 验证版本 python --version

这里有个细节：创建环境后先升级 pip 和 setuptools，老版本的 pip 在解析复杂依赖树时经常给出错误的版本组合。

pip install --upgrade pip setuptools wheel

2.2 依赖安装的坑与绕行方案

直接pip install -r requirements.txt大概率会遇到两类问题。一类是编译型依赖，比如某些向量计算库需要本地有 C++ 编译器和对应的开发头文件；另一类是版本冲突，两个包对同一个底层库要求不同版本。

编译型依赖的通用解法是先装系统级开发包：

# Ubuntu/Debian 下安装常见编译依赖 sudo apt-get update sudo apt-get install -y build-essential python3-dev libssl-dev libffi-dev

版本冲突则要靠虚拟环境隔离加手动干预。我的经验是，遇到冲突先看报错里是哪两个包打架，然后去查它们各自支持的版本区间，取交集。实在解不开，就单独建一个环境装那个"刺头"包，用子进程方式调用。

注意：不要盲目用--force-reinstall或忽略版本约束，短期能装上，运行时报的错会更难查。

2.3 模型文件的获取与存放

如果走本地模型路线，模型文件是绕不开的。以常见的开源中文模型为例，权重文件动辄几个 GB，下载慢、容易断。建议用支持断点续传的工具，并且提前规划好存放路径。

模型存放有个原则：统一目录管理，别散落在各处。我一般建一个/data/models目录，每个模型一个子目录，配置里用绝对路径引用。这样迁移和备份都方便。

# 目录结构示例 /data/models/ ├── embedding-model/ # 向量化模型 ├── rerank-model/ # 重排序模型（可选） └── llm-model/ # 生成模型

向量化模型和生成模型是两回事，别搞混。向量化模型负责把文本转成向量，通常比较小（几百 MB）；生成模型负责根据检索结果组织答案，才是吃显存的大头。有些部署方案只本地跑向量化、生成走 API，就是基于这个成本考量。

3. 核心组件拆解：解析、向量化、检索各自的门道

3.1 文档解析层为什么最容易出问题

文档解析是整条链路的第一道关，也是最容易被低估的一环。PDF 看着简单，实际上分三种：原生电子版（文字可选）、扫描版（本质是图片）、混合版。原生电子版直接抽文字就行，扫描版必须先做 OCR，混合版要逐页判断。

WeKnora 的解析层对常见格式都有处理，但 OCR 能力取决于你接的引擎。关键词里出现的"mineru 本地部署"就是一个专门做文档解析的开源工具，对复杂版面的 PDF（多栏、表格、公式）处理得比通用库好。如果你的文档里有大量学术论文或技术手册，值得单独接一个解析引擎。

表格是另一个重灾区。很多解析库会把表格拍平成一行文字，行列关系全丢。检索时用户问"某参数是多少"，召回的片段里数字和参数名对不上，答案自然错。处理办法是解析时保留表格结构，转成 Markdown 表格或结构化 JSON 再入库。

# 解析结果的结构化处理思路（伪代码示意） def parse_document(file_path): raw = extract_text(file_path) # 表格单独处理，保留行列结构 tables = extract_tables(file_path) structured_tables = [table_to_markdown(t) for t in tables] return { "text": raw, "tables": structured_tables, "metadata": get_file_metadata(file_path) }

3.2 分块策略直接决定检索质量

分块（chunking）是 RAG 里最玄学的环节。块太大，检索出来的内容包含大量无关信息，干扰生成；块太小，上下文不完整，答案缺胳膊少腿。

常见的分块方式有三种。固定长度分块最简单，按字符数或 token 数切，但会切断句子和段落。按语义分块用模型判断句子边界，效果好但慢。按结构分块利用文档本身的标题层级，最适合有清晰结构的文档。

我的实践是混合策略：优先按标题层级切，同一标题下的内容如果超过阈值再按段落切，段落还超就按句子切。这样既保留了结构信息，又控制了单块大小。

块大小一般控制在 300-800 字符之间，具体要看文档密度。技术文档信息密度高，块可以小一点；叙述性文档可以大一点。这个参数没有标准答案，必须拿自己的文档实测。

3.3 向量化与检索的匹配逻辑

向量化的核心是选对 embedding 模型。中文场景下，专门针对中文优化的模型效果明显好于通用多语言模型。选模型看两个指标：检索准确率和向量维度。维度越高表达能力强，但存储和计算成本也高，常见的是 768 维和 1024 维。

检索环节有个容易被忽略的点：单纯向量检索（稠密检索）对精确匹配的关键词不敏感。比如用户问某个具体的错误码，向量检索可能召回一堆语义相近但错误码不同的内容。解决办法是混合检索——向量检索加关键词检索（BM25），两路结果融合排序。

# 混合检索的融合思路（伪代码） def hybrid_search(query, top_k=10): vector_results = vector_search(query, top_k=top_k*2) keyword_results = bm25_search(query, top_k=top_k*2) # 用 RRF（倒数排名融合）合并两路结果 merged = reciprocal_rank_fusion(vector_results, keyword_results) return merged[:top_k]

如果对精度要求更高，还可以加一层重排序（rerank）。先召回较多候选（比如 20 个），再用重排序模型精排取前几个。这一步能显著提升最终答案质量，代价是多一次模型推理。

4. 从零跑通：完整部署流程与配置要点

4.1 服务启动的先后顺序

WeKnora 这类系统通常由几个部分组成：后端服务、前端界面、向量库、模型服务。启动顺序有讲究，依赖方要先起来。

正确的顺序是：向量库 → 模型服务 → 后端 → 前端。向量库没起来后端连不上会报错退出；模型服务没起来，后端启动时做健康检查会失败。如果用了容器编排，用depends_on加健康检查来控制顺序。

# docker-compose 片段示意，控制启动依赖 services: vectordb: image: vectordb-image healthcheck: test: ["CMD", "curl", "-f", "http://localhost:port/health"] interval: 10s retries: 5 backend: depends_on: vectordb: condition: service_healthy

4.2 配置文件里最该关注的几项

配置文件通常很长，但真正影响运行的就那么几项。我按重要性排个序。

第一是模型路径和类型。本地模型填本地路径，API 模型填接口地址和密钥。这里最容易错的是模型类型标识，填错了会加载失败。

第二是向量库连接信息。地址、端口、库名、认证信息，任何一项不对都连不上。建议先用命令行工具单独测通向量库连接，再配到系统里。

第三是分块参数。块大小、重叠长度、分块策略，这几个直接决定检索效果，值得反复调。

第四是检索参数。召回数量、相似度阈值、是否启用混合检索和重排序。

# 配置项示意 embedding: model_path: /data/models/embedding-model dimension: 768 vectordb: host: localhost port: 19530 collection: weknora_docs chunking: strategy: structure chunk_size: 500 overlap: 50 retrieval: top_k: 5 hybrid: true rerank: true

4.3 首次导入文档的验证方法

服务起来后别急着灌大量文档，先拿几份有代表性的测试。选文档的原则是覆盖你实际会遇到的格式：一份纯文本、一份带表格的 PDF、一份扫描件。

导入后做三件事验证。第一，看解析结果，确认文字没乱码、表格结构还在。第二，做检索测试，用几个你已知答案的问题查，看召回的片段是否包含答案。第三，看生成结果，确认大模型是基于召回内容回答而不是瞎编。

提示：如果检索召回的内容对，但生成答案错，问题在生成模型或提示词；如果召回就不对，问题在解析、分块或向量化。定位清楚再调，别乱改。

4.4 一个完整的导入与查询脚本示例

把流程串起来看更直观。下面是一个简化的导入加查询流程，帮你理解各环节怎么衔接。

from weknora import KnowledgeBase # 初始化知识库，加载配置 kb = KnowledgeBase.from_config("config.yaml") # 导入文档 kb.add_documents([ "docs/manual.pdf", "docs/spec.docx", "docs/faq.md" ]) # 执行查询 result = kb.query("系统支持哪些文档格式？", top_k=5) # 查看召回片段 for i, chunk in enumerate(result.retrieved_chunks): print(f"片段{i+1}: {chunk.text[:100]}...") print(f"相似度: {chunk.score}") # 查看生成的答案 print("答案:", result.answer)

这段代码的价值在于它把"导入"和"查询"两个阶段分开了。实际调试时，先确认导入阶段解析和分块没问题，再调查询阶段的检索和生成，问题定位会清晰很多。

5. 实测中踩过的坑与排查链路

5.1 检索结果为空或答非所问

这是最常见的问题，排查要按链路顺序来，别跳步。

第一步查解析。把入库的文档内容导出来看，如果解析出来就是空的或乱码，后面全白搭。扫描件没做 OCR、PDF 加密、编码不对，都会导致解析失败。

第二步查分块。如果解析正常但检索不到，可能是分块把关键信息切碎了。比如答案跨了两个块，单独一个块都不完整。这时候调大块大小或增加重叠长度。

第三步查向量化。确认文档和查询用的是同一个 embedding 模型。用不同模型向量化，向量空间不一致，相似度计算完全没意义。这个错误很隐蔽，因为系统不会报错，只是检索结果很差。

第四步查相似度阈值。阈值设太高，稍微不匹配的就被过滤掉，召回为空。先把阈值调低甚至关掉，看能不能召回，再逐步调高。

5.2 服务启动报依赖或端口错误

启动失败看日志，日志里通常写得很清楚。依赖错误一般是版本不匹配，按报错里的包名和版本要求调整。端口错误要么是端口被占用，要么是配置里的地址写错。

# 查端口占用 lsof -i :8000 # 或 netstat -tlnp | grep 8000

端口被占用就换一个，或者把占用进程停掉。地址写错的情况，注意localhost和127.0.0.1在容器环境里含义不同——容器内的 localhost 指的是容器自己，要连宿主机得用宿主机的实际 IP 或专门的网络配置。

5.3 大模型响应慢或显存溢出

响应慢先看是模型推理慢还是检索慢。在日志里加时间戳，分别记录检索耗时和生成耗时。检索慢通常是向量库数据量大或索引没建好；生成慢是模型本身或硬件问题。

显存溢出（OOM）是本地部署的经典问题。几个缓解方向：换更小的量化模型、减小单次请求的上下文长度、限制并发数。上下文长度对显存影响很大，检索召回太多片段塞进提示词，很容易撑爆。

5.4 中文文档的特殊处理

中文和英文在 RAG 里有几个不同点。中文没有天然的空格分词，关键词检索（BM25）需要先做分词，分词质量直接影响关键词召回。选分词工具时优先用针对中文优化的。

中文的字符密度高，同样字符数包含的信息比英文多，所以分块大小可以比英文场景小一些。另外中文的标点符号和英文不同，按句子切分时要处理全角标点。

还有一个细节是编码。中文文档如果编码识别错误，会解析成乱码。入库前统一转成 UTF-8，能避免大部分编码问题。

6. 让系统更好用的几个进阶方向

6.1 接入重排序提升答案精度

前面提过重排序，这里展开说。重排序模型（rerank）的作用是对初步召回的候选做精细打分。向量检索用的是双塔结构，查询和文档分别编码再算相似度，快但精度有限；重排序用的是交叉编码，查询和文档一起输入模型，精度高但慢。

实践中的组合是：向量检索召回 20-50 个候选，重排序精排取前 3-5 个给生成模型。这样既保证了速度，又提升了精度。重排序模型通常比生成模型小很多，本地部署压力不大。

6.2 多轮对话与上下文管理

单轮问答跑通后，用户自然会想要多轮对话。多轮的核心问题是上下文怎么管理。直接把历史对话全塞进去，很快会超出上下文长度限制。

常见做法是只保留最近几轮对话，或者对历史做摘要压缩。更精细的做法是判断当前问题是否依赖历史——如果是个独立问题，就不带历史；如果指代了前文（比如"它""这个"），才带上相关历史。

# 上下文管理的简化逻辑 def build_prompt(query, history, retrieved_chunks): # 判断是否需要历史上下文 if needs_history(query): recent_history = history[-3:] # 只取最近3轮 else: recent_history = [] context = "\n".join([c.text for c in retrieved_chunks]) return format_prompt(query, recent_history, context)

6.3 权限与多知识库隔离

企业场景下，不同部门的知识库要隔离，不同用户能访问的文档不同。这需要在检索层加过滤条件，只召回用户有权限的文档。

实现方式是在文档入库时打上权限标签（部门、密级等），检索时把用户的权限作为过滤条件传进去。向量库一般支持带过滤的检索，在查询时附加元数据过滤条件即可。

注意：权限过滤必须在检索层做，不能只在展示层做。否则无权限的内容虽然不显示，但可能影响生成结果，造成信息泄露。

6.4 监控与效果评估

系统上线后要能知道它好不好用。几个关键指标：检索命中率（召回内容是否包含答案）、答案准确率（生成答案是否正确）、响应延迟、用户反馈。

评估检索效果可以建一个测试集，准备一批问题和对应的标准答案文档，定期跑一遍看召回情况。这个测试集不用很大，几十条有代表性的就够，关键是覆盖真实使用场景。

我在实际使用中的体会是，RAG 系统的调优是个持续过程，没有一劳永逸的配置。文档在变、用户在变、问题在变，定期回顾检索日志、分析失败案例，比一次性把参数调到极致更有价值。另外别迷信大模型，很多时候答案不准的根因在检索环节，把解析和分块做扎实，比换个更大的模型见效更快。