StructuredTextEngine：从零构建的本地化RAG后端，无需API密钥的完整检索增强生成方案

一个基于FastAPI和ChromaDB的纯本地RAG系统，采用SentenceTransformers语义检索+余弦相似度重排序，结合Ollama本地大模型实现完全离线的文档问答，展示模块化架构与依赖注入的最佳实践。

• 原作者/维护者: solankinitish
• 来源平台: GitHub
• 原始标题: StructuredTextEngine
• 原始链接: https://github.com/solankinitish/structured-text-engine
• 发布时间: 2026年6月

---

检索增强生成（Retrieval-Augmented Generation，RAG）已成为大模型应用开发的主流范式。通过将外部知识库与语言模型结合，RAG能够在不重新训练模型的情况下，让AI回答基于特定领域知识的问题，同时减少幻觉（Hallucination）的发生。

然而，大多数RAG实现依赖于云端API服务：OpenAI的Embedding API、Pinecone或Weaviate的托管向量数据库、以及远程的大模型端点。这种架构虽然开发便捷，但存在几个不可忽视的痛点：

首先是数据隐私风险——敏感文档必须上传到第三方服务器进行处理和存储，这在金融、医疗、法律等对数据主权有严格要求的领域是不可接受的。其次是成本累积——随着文档规模和查询量的增长，API调用费用会快速攀升。第三是网络依赖——离线环境或网络不稳定场景下系统完全不可用。最后是供应商锁定——过度依赖特定服务商的API格式和定价策略，迁移成本高昂。

在这样的背景下，完全本地化的RAG方案应运而生：所有组件运行在用户自有硬件上，无需外部API调用，数据不出本地，成本可控且可预测。

---

StructuredTextEngine是一个从零构建的纯本地RAG后端系统，展示了如何不依赖任何框架抽象，从第一性原理出发搭建完整的检索增强生成流水线。项目采用Python 3.11开发，核心特性包括：

• 完全本地运行：无需API密钥，无需互联网连接，所有计算在本地完成
• 持久化向量存储：基于ChromaDB的跨会话文档索引
• 语义检索+重排序：SentenceTransformers生成稠密向量，余弦相似度进行结果重排
• 模块化LLM接入：通过依赖注入容器实现LLM provider的可插拔设计
• 严格 grounding：模型只能基于检索到的上下文回答，无法回答时返回"I don't know"

项目的技术栈选择体现了"够用且可控"的哲学：FastAPI提供高性能API层，Ollama负责本地大模型管理，SentenceTransformers处理文本嵌入，ChromaDB作为轻量级向量数据库。这种组合既保证了功能完整性，又避免了引入不必要的复杂度。

---

StructuredTextEngine的架构设计遵循关注点分离原则，每个模块职责清晰，通过依赖注入容器（Container）进行组件装配。

用户查询首先进入FastAPI路由层，由Controller转发给TextService。TextService作为编排器，协调检索和生成两个阶段：

用户查询 → FastAPI → Router → Controller → TextService
                                              │
                    ┌─────────────────────────┼─────────────────────────┐
                    │                         │                         │
              VectorRetriever          PromptManager              LLMClient
                    │                                               │
        ┌───────────┼───────────┐                                   │
        │           │           │                                   │
  EmbeddingService VectorStore  Reranker                            │
        │           │           │                                   │
        └───────────┴───────────┘                                   │
                    │                                               │
              检索到的上下文 → 构建Prompt → 调用本地LLM → 生成答案

VectorRetriever（向量检索器）

这是检索阶段的核心 orchestrator，内部协调三个子组件：

1. EmbeddingService：使用SentenceTransformers的all-MiniLM-L6-v2模型将查询文本编码为384维稠密向量。该模型在语义相似度任务上表现优异，且体积小巧（约80MB），适合本地部署。

2. VectorStore（ChromaDB）：负责存储文档块及其对应的向量表示，支持持久化存储到本地磁盘。首次运行时从docs/目录加载文档并建立索引，后续会话直接使用已有索引。

3. Reranker（重排序器）：采用余弦相似度对ChromaDB召回的Top-10结果进行重排序，选出最相关的Top-3作为最终上下文。这种"召回+精排"的两阶段策略在计算效率和结果质量之间取得了良好平衡。

PromptManager（提示管理器）

负责将检索到的上下文片段组装成结构化的prompt。系统强制要求模型仅基于提供的上下文回答问题，如果上下文中没有相关信息，必须明确回答"I don't know"。这种设计有效抑制了模型利用预训练知识进行"脑补"的倾向。

LLMClient（LLM客户端）

封装了与Ollama的交互细节，默认使用Mistral模型。通过抽象接口设计，可以轻松替换为其他本地模型（如Llama 3、Phi-3等）或未来可能支持的本地推理引擎。

---

系统的知识库构建流程同样体现了简洁实用的设计理念：