STACKIT RAG Template：企业级文档智能问答的完整技术方案

你有没有过这样的经历——翻遍公司几十份内部文档，找一个技术问题的答案，却怎么也搜不到？或者想让 AI 直接回答"我们去年Q3的技术架构选型是什么"，但通用大模型只会一本正经地胡说八道？检索增强生成（Retrieval-Augmented Generation，RAG） 正是解决这个问题的关键技术路线。而 STACKIT RAG Template 提供了从文档解析、向量检索到大模型生成的完整工程实现，而且是基于 Kubernetes 生产级部署的版本。

图：Langfuse 追踪界面，可实时监控 RAG 系统的对话质量与调用延迟

背景：为什么企业需要 RAG？

通用大语言模型（LLM）的知识有截止日期，而且对企业私有数据"一无所知"。直接 fine-tune 成本高昂、周期长、且容易遗忘已有知识。RAG 的思路更优雅：在回答问题时，先从私有文档库中检索相关片段，再将这些片段作为上下文喂给 LLM 生成答案。这样既保证答案来自真实数据，又利用了 LLM 的语言理解和生成能力。

STACKIT（欧洲最大云服务商德国电信旗下的云部门）开源的 RAG Template，是一个生产就绪的参考架构，包含了文档处理、向量数据库、大模型调用、API 服务、前端界面和可观测性的完整微服务套件。

核心架构：6个微服务如何协同

整个系统由 5 个后端服务 + 1 个前端应用 组成，采用微服务架构，通过 HTTP API 通信：

文档抽取服务（document-extractor）

这是整个流水线的入口。当用户上传一份 PDF 或 Word 文档时，document-extractor 负责将内容解析为结构化文本。它采用了多级降级策略——Docling 首先尝试从 PDF 和 Office 文档中提取富文本内容；如果 Docling 失败，降级到 MarkItDown 做轻量级 Markdown 转换；最后还有自定义提取器（PDF、MS Office、XML、EPUB）以及 Tesseract OCR 处理扫描件。Confluence 空间和网站 sitemap 也在支持范围内。

这种分层降级设计保证了格式兼容性最大化，不用担心用户上传了某个奇怪版本的文档就崩溃。

RAG 核心后端（rag-backend）

这是系统的"大脑"。rag-backend 连接向量数据库（Qdrant），负责向量化和语义检索。它基于 LangChain 实现，支持多种 LLM 提供者（STACKIT 自有 LLM API、Ollama 本地模型等），也支持多种嵌入模型（embedder）。系统使用 KeyDB（Redis 兼容）做会话历史缓存，保证多轮对话的上下文连贯性。

核心 API 包括：

• /chat/{session_id} — 带历史记录的多轮对话
• /information_pieces/upload — 上传文档块到向量数据库
• /information_pieces/remove — 从向量数据库删除文档
• /evaluate — 使用 RAGAS 框架评估问答质量

管理后端（admin-backend）

负责文档生命周期管理。它与 document-extractor 交互完成文档解析，与 rag-backend 交互将文档块存入向量数据库，文件本体存储在 S3 兼容对象存储（生产用 STACKIT Object Storage，本地开发用 MinIO）。用户通过 admin-backend 上传、查询文档处理状态，以及管理 Confluence 数据源。

MCP 服务器（mcp-server）

Model Context Protocol（MCP）服务器，这是一个近年兴起的新兴协议，旨在让 AI 助手能够调用外部工具。mcp-server 将 RAG 能力暴露为 MCP 工具，AI 助手（如 Claude Desktop）可以直接调用 chat_simple（简单问答）和 chat_with_history（带历史的多轮对话），返回结构化答案（含 answer、finish_reason、citations 引用）。

前端（frontend）

Vue 3 构建的 NX Monorepo，包含两个独立应用：

• chat-app（端口 4200）：用户对话界面，上传文档、提问、查看引用来源
• admin-app（端口 4300）：管理员界面，管理文档库、查看处理状态、配置数据源

前端使用 DaisyUI（Tailwind CSS 组件库）和 Onyx 图标库，支持明暗主题切换。

可观测性层

通过 Langfuse（开源 LLM 可观测性平台）追踪每次对话的 Prompt、Token 消耗、延迟和回答质量。Langfuse 已在 Helm Chart 中作为依赖项集成，开箱即用。

技术栈速览

上手体验：本地开发与生产部署

本地开发借助 Tilt 工具，只需一条命令即可启动完整开发环境——包括所有服务、数据库和前端热重载。Tiltfile 整合了构建、测试和热更新，开发体验对标生产环境的一致性配置。

生产部署通过 Helm Chart 一键部署到 Kubernetes 集群。Chart 依赖包括 Qdrant（向量数据库）、Langfuse（可观测性）、KeyDB（会话缓存）、Ollama（可选本地模型）和 MinIO（可选本地对象存储），全部可选启用。Terraform 脚本支持在 STACKIT 公有云上一键创建所需的基础设施（Kubernetes 集群、对象存储凭证、PostgreSQL 等）。

局限与挑战

1. 复杂度较高：6 个微服务 + Helm 依赖管理，对于初次接触 Kubernetes 的团队来说学习曲线较陡
2. 无 docker-compose：缺少 docker-compose.yml 作为轻量级一键启动方案，不熟悉 Kubernetes 的用户上手门槛较高
3. GPU 依赖：如果使用 Ollama 本地模型，需要配置 GPU；使用云端 LLM API 则无此需求
4. STACKIT 强绑定：Terraform 配置面向 STACKIT 公有云，迁移到其他云厂商需要自行调整
5. 多语言文档支持：中文文档的解析质量可能不如英文文档（受底层解析库影响）

行业意义

RAG 是当前企业 AI 落地最主流的技术路径之一。STACKIT RAG Template 的价值不仅在于提供了完整的代码实现，更在于它是经过生产验证的架构参考——Langfuse 集成、S3 对象存储、多级文档解析降级、MCP 协议支持，这些都是企业在实际项目中会遇到的真问题。开源意味着任何人都可以在此基础上快速定制，开发周期从"从零搭建 RAG 系统"缩短到"基于模板定制业务逻辑"。

GitHub 活跃度也印证了这一点：Issues 43 个，Commits 持续更新，PyPI 上有 4 个配套库（rag-core-api、rag-core-lib、admin-api-lib、extractor-api-lib）分别发布，说明维护者将其作为正规开源产品而非实验项目来运营。