企业级知识库问答系统混合架构部署实践

一、部署概述

在企业知识库问答（RAG，检索增强生成）的落地过程中，常见开源方案大致分为两类：一类偏重应用编排，提供可视化工作流、智能体（Agent）构建、多模型接入与外部工具调用能力，易用性高、上手快、便于二次开发；另一类偏重文档处理，擅长解析 PDF、扫描件、图文表格等复杂非结构化文档，在解析质量与检索召回上更有优势。许多团队会在两者之间纠结“二选一”，但更务实的做法是混合部署：以编排平台作为主框架，通过标准 API 调用文档解析检索引擎的知识库组件，把前者的流程编排能力与后者的深度解析能力组合起来。

本文的目标是帮助读者完成这套混合架构从零到上线的完整部署。部署完成后应达到如下效果：

• 用户通过编排平台提供的统一入口提问；
• 编排平台完成意图理解、流程编排与模型调度，并调用检索引擎获取相关知识片段；
• 检索引擎负责文档解析、切分、向量化与检索召回；
• 整条“提问—检索—生成”链路可验证、可监控、可回滚。

适合读者：需要在企业内落地知识库问答系统的开发者、运维工程师、架构师与技术负责人。阅读前建议对容器化部署、端口映射、REST API 调用以及大模型推理服务的基本概念有初步了解。

二、部署场景与选型逻辑

选型逻辑可以概括为一句话：文档复杂度与检索质量优先时，重心放在检索引擎；多模型协作与复杂业务流程优先时，重心放在编排平台；两者都重要时，采用本文的混合架构。

两类平台的典型能力差异（以业界通用认知归纳）：

维度	编排平台	检索引擎
上手成本	低，无需大量阅读文档即可快速搭建原型，通常半小时级可跑通	中等，需要理解切分模板与解析策略
文档处理	通用解析，复杂文档表现一般	深度解析组件，对 PDF、扫描件、表格表现突出，内置 OCR 与多种切分模板
流程能力	工作流编排、Agent、多模型协作、外部工具扩展	以知识库管理为主
知识库能力	支持跨知识库检索与自动路由选择	单库检索能力扎实，检索质量稳定
负载表现	依赖后端模型服务	对延迟敏感的应用表现稳定，可应对较繁重的检索负载

混合架构的典型适用场景：

1. 企业文档以 PDF 报告、扫描合同、图文表格等复杂结构为主；
2. 问答需要嵌入审批、工单等业务流程，需要工作流分支与外部系统调用；
3. 需要跨多个知识库检索并自动路由；
4. 对响应延迟与并发负载有一定要求；
5. 后续计划扩展更多检索框架或数据源，希望架构保持可插拔——除本文的两件套组合外，也可结合业务需要引入其他类型的检索增强框架作为补充。

三、总体架构与组件拆解

混合架构自上而下分为四层：

• 接入层：域名、证书、负载均衡与访问控制，是企业用户触达系统的唯一入口；
• 应用编排层：编排平台，包含工作流引擎、Agent 模块、模型网关与应用管理控制台，负责“怎么答”；
• 知识检索层：检索引擎，包含深度文档解析组件、OCR 模块、切分模板库、向量化模块、检索服务与知识库管理控制台，负责“答的依据从哪来”；
• 基础依赖层：向量数据库、关系数据库、缓存、对象存储，以及模型推理服务（可使用云上模型推理 API，也可自建推理集群）。

集成链路说明：编排平台将检索引擎的“知识库检索”注册为外部知识源或工具节点，运行时通过 HTTP API 传入查询语句，取回召回片段后注入提示词，交给模型生成最终答案。这种 API 集成方式保证了松耦合：任何一侧升级、替换或扩容，都不影响另一侧，这正是混合架构在灵活性与可扩展性上的核心价值。

四、前置准备

4.1 资源规划

• 测试环境：单台 8 核 16GB 的云服务器即可完成全链路验证（例如在百度智能云开通通用型云服务器并挂载独立数据盘），系统盘 100GB 起步；
• 生产环境：建议编排平台与检索引擎分开部署在两台及以上服务器，各自 8 核 16GB 以上；
• 资源画像：文档解析与 OCR 是 CPU 密集型任务；向量检索消耗内存；原始文档与索引占用磁盘，需按文档总量预留 2～3 倍存储空间；
• 模型服务：确认推理 API 的并发配额与限流策略，避免上线后模型侧成为瓶颈；文档量大会触发批量向量化，同样占用模型调用额度；
• 网络：两套服务之间必须内网互通，公网只暴露编排平台入口。

4.2 环境准备

• 两类平台官方均推荐以容器化方式部署，需在目标服务器上安装容器运行时与容器编排工具，并确认版本兼容；
• 从各自官方渠道获取部署包与镜像，规划统一的应用目录、数据目录、日志目录，数据目录必须做持久化挂载，避免容器重建导致知识库与索引丢失；
• 开发、测试、生产环境保持依赖版本与配置一致，配置差异通过环境变量而非改动部署包来体现，这是环境一致性的基本要求。

4.3 端口规划（部署成败的关键环节）

在容器编排的端口映射配置中，格式通常写作 A:B：A 代表宿主机端口，B 代表容器内部端口。例如 80:80 表示宿主机 80 端口映射到容器 80 端口，443:443 表示宿主机 443 映射到容器 443。通常容器内的 80 端口处理 HTTP 请求，443 端口处理 HTTPS 请求。

问题在于：编排平台与检索引擎默认的宿主机端口往往都包含 80 与 443，同机部署必然冲突。标准解法是保留容器端口不变，只修改宿主机端口——例如把检索引擎的 80:80 改为 8080:80、443:443 改为 8443:443，编排平台保持默认。这样做侵入性最小：容器内部配置完全不动，只影响外部访问入口。

服务	容器端口	默认宿主机端口	调整后宿主机端口	用途
检索引擎	80	80	8080	管理控制台与检索 API
检索引擎	443	443	8443	HTTPS 访问
编排平台	80	80	80（保持不变）	应用构建与对外服务入口
编排平台	443	443	443（保持不变）	HTTPS

两点注意：调整后需在云服务器安全组与主机防火墙中同步放行 8080/8443；后续 API 集成时，检索引擎地址必须携带新端口。

4.4 密钥与账号

准备模型推理 API Key、检索引擎 API Key（供编排平台调用鉴权）、两个平台各自的管理员账号。密钥统一通过环境变量注入，不写入代码仓库与配置库，生产与测试密钥严格隔离。

4.5 数据准备

梳理首批入库文档的来源、格式、数量与更新频率；剔除无效页与重复文档；明确文档的部门权限边界——敏感文档建议单独建库并收紧调用范围，这直接影响后续安全策略设计。

五、部署流程

建议顺序：先知识层（检索引擎）、后应用层（编排平台）、最后做集成。这样编排平台部署完成后可立即对接已就绪的知识库，减少反复切换。

Step 1：初始化环境。 安装容器运行时与编排工具，创建应用/数据/日志目录，配置日志轮转策略，避免日志撑满磁盘。

Step 2：部署检索引擎。 获取部署包并解压至规划目录；打开容器编排配置文件，定位端口映射段，将 80:80 修改为 8080:80、443:443 修改为 8443:443，容器侧端口不动；执行启动命令并等待全部容器进入运行状态；浏览器访问 http://<服务器IP>:8080 完成管理员初始化；在控制台配置模型推理服务的 API 地址与密钥。

# 通用容器编排配置示意（节选）
service_search:
  ports:
    - "8080:80"    # 宿主机 8080 → 容器 80（HTTP）
    - "8443:443"   # 宿主机 8443 → 容器 443（HTTPS）

Step 3：部署编排平台。 获取部署包，按默认端口或规划端口启动；访问 http://<服务器IP> 初始化管理员；配置模型接入地址与密钥并测试连通。

Step 4：验证网络连通。 从编排平台所在容器或宿主机，对 http://<检索引擎内网地址>:8080 发起访问测试。若不通，优先排查安全组、防火墙与容器网络配置。

Step 5：配置 API 集成。 在编排平台中将检索引擎注册为外部知识源：

# 环境变量配置示意
SEARCH_API_BASE = http://<检索引擎内网IP>:8080
SEARCH_API_KEY  = <检索引擎生成的密钥>
MODEL_API_KEY   = <模型服务密钥>

务必走内网地址，避免绕行公网带来延迟与安全风险；填入密钥后先做一次测试调用，确认能返回召回片段。

Step 6：构建知识库。 在检索引擎中创建知识库，按文档类型选择切分模板；分批上传文档触发解析与向量化；抽查解析结果——段落切分是否合理、表格结构是否还原、OCR 是否准确，不合格的文档更换模板后重建索引。

Step 7：构建问答应用。 在编排平台创建工作流或智能体应用，典型节点编排为：开始 → 检索（调用检索引擎）→ 提示词组装 → 模型生成 → 回复；开启答案来源引用，便于溯源；用典型业务问题做一轮回归测试。

Step 8：开放访问。 配置域名解析与证书，将编排平台入口置于负载均衡之后；有条件的企业可对接统一身份认证；对外只暴露必要端口，检索引擎端口严格限制在内网。

六、上线验证

1. 服务状态：两套服务的容器进程全部稳定运行，无反复重启；
2. 组件级验证：分别在检索引擎控制台做检索测试、在编排平台做纯模型对话测试，先排除单点故障再查集成链路；
3. 集成链路验证：从编排平台入口提问，确认回答引用了知识库片段且来源可溯源；
4. 性能验证：以典型并发（如 10～20 并发）压测，观察响应时间、模型限流与资源占用；
5. 日志检查：两侧日志无连续错误，重点关注解析超时、检索为空、API 鉴权失败三类记录；
6. 观察期：上线后观察 24～48 小时资源曲线，确认内存无持续上涨、CPU 无异常尖峰。

七、常见问题与排查

现象	可能原因	处理思路
服务启动失败，提示端口占用	两套服务默认宿主机端口相同	修改一方宿主机端口（如 80→8080），容器端口不动
修改端口后无法访问	安全组未放行；映射方向写反	放行新端口；确认 A:B 中 A 是宿主机端口
编排平台调用检索引擎报错	网络不通、地址端口写错、密钥失效	做内网连通性测试；核对地址与端口；重新生成密钥
文档解析失败或质量差	模板不匹配、OCR 资源不足	更换切分模板；降低并发解析；补充计算资源
提问命中不到知识	向量化未完成、召回参数过严	等待索引任务完成；放宽召回数量或相似度阈值
内存持续上涨直至重启	索引膨胀、并发过高	扩容内存；限制并发；拆分知识库
响应偏慢	模型限流、缺少缓存	申请更高配额；对高频问题增加缓存

八、运维与优化

监控告警：对 CPU、内存、磁盘、接口成功率、P95 响应时间与错误日志数量配置告警；解析任务队列长度是混合架构特有的关键指标，堆积往往意味着入库高峰需要错峰或扩容。

日志与审计：集中收集两套服务日志并统一保留周期；对管理员操作、知识库变更与密钥变更留存审计记录。

备份与恢复：定期备份原始文档、索引数据、平台配置与数据库，每季度至少演练一次恢复流程——备份是故障回滚的最后防线。

版本更新与回滚：更新前记录当前镜像版本与配置差异，先在测试环境验证再灰度到生产；保留旧版本镜像与配置快照，一旦异常可快速回滚到上一个稳定状态。

性能优化：将文档入库与在线问答隔离部署，避免批量解析影响在线延迟；对高频问答增加缓存；合理设置模型连接池、超时与重试参数；大型知识库拆分为多个子库，由编排层按业务路由。

安全控制：检索引擎仅内网可达；API Key 定期轮换并最小权限分发；全链路启用 HTTPS；敏感知识库单独隔离并限制调用方范围。

成本控制：按文档规模而非估算选择实例规格，避免长期超配；低频知识库归档并利用存储分层降低保存成本；监控模型调用的 token 消耗，通过压缩提示词与控制召回片段数量控制推理成本。

九、总结

本文围绕企业知识库问答系统的落地，给出了一条“编排平台 + 检索引擎”混合架构的完整部署路径：先明确两类平台的分工与互补关系，再完成资源与端口规划（核心是通过修改宿主机端口规避 80/443 冲突、同时保持容器端口不变），随后按照“先知识层、后应用层、再集成”的顺序完成部署，最后通过组件级与端到端双重验证确认链路可用，并以监控、备份与回滚机制保障长期稳定运行。部署完成后，团队获得的不是两个孤立系统，而是一条可插拔、可扩展的知识问答流水线：后续无论是替换检索框架、接入更多数据源，还是调整业务流程，都可以在不推翻整体架构的前提下平滑演进。