# Rag-microservice
**Repository Path**: imageOptimize/rag-microservice
## Basic Information
- **Project Name**: Rag-microservice
- **Description**: 基于 LangChain 和 FastAPI 框架构建的 RAG (Retrieval-Augmented Generation) 微服务，提供 RESTful API 接口，支持文档检索和智能问答
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# RAG (检索增强生成) 微服务
基于 LangChain 和 FastAPI 框架构建的 RAG (Retrieval-Augmented Generation) 微服务，提供 RESTful API 接口，支持文档检索和智能问答。
## 📋 项目简介
本项目实现了一个完整的 RAG 微服务系统，能够：
- 🌐 提供 RESTful API 接口
- 📄 加载多种格式的文档（PDF、TXT、DOCX）
- ✂️ 智能分割文档为文本块
- 🔍 将文档向量化并存储到向量数据库
- 💡 根据用户问题检索相关文档
- 🤖 使用大语言模型生成准确答案
- 🐳 支持 Docker 容器化部署
- 📊 自动生成 API 文档
## 🏗️ 项目结构
```
.
├── app.py # FastAPI应用主入口
├── main.py # 命令行版本（保留）
├── rag_pipeline.py # RAG核心管道
├── config.py # 配置文件
├── api/ # API路由模块
│ └── routes.py # API路由定义
├── models/ # 数据模型
│ └── schemas.py # Pydantic数据模型
├── services/ # 服务层
│ └── rag_service.py # RAG业务逻辑服务
├── requirements.txt # 项目依赖
├── .env.example # 环境变量示例
├── Dockerfile # Docker镜像构建文件
├── docker-compose.yml # Docker Compose配置
├── start.sh # Linux/Mac启动脚本
├── start.bat # Windows启动脚本
├── README.md # 项目说明
├── documents/ # 文档存储目录
└── vectorstore/ # 向量数据库存储目录（自动创建）
```
## 🏗️ 架构层级
```
┌─────────────────────────────────────────────────────────────┐
│ 用户层 (Client Layer) │
│ Web浏览器 / API客户端 / 移动应用 │
└───────────────────────┬─────────────────────────────────────┘
│ HTTP Request
▼
┌─────────────────────────────────────────────────────────────┐
│ API 层 (API Layer) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FastAPI Application (app.py) │ │
│ │ - 路由注册 /api/v1/* │ │
│ │ - CORS 中间件 │ │
│ │ - 异常处理 │ │
│ └───────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌───────────────────▼──────────────────────────────────┐ │
│ │ API Routes (api/routes.py) │ │
│ │ - POST /query 查询接口 │ │
│ │ - POST /query/stream 流式查询 │ │
│ │ - POST /knowledge-base/build 构建知识库 │ │
│ │ - GET /observability/dashboard 监控面板 │ │
│ └───────────────────┬──────────────────────────────────┘ │
└───────────────────────┼─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 服务层 (Service Layer) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ RAGService (services/rag_service.py) │ │
│ │ - 单例模式管理 RAG 管道实例 │ │
│ │ - 延迟初始化（首次使用时加载模型） │ │
│ │ - 对话历史上下文管理 │ │
│ │ - 异常处理和状态检查 │ │
│ └───────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌───────────────────▼──────────────────────────────────┐ │
│ │ DynamicContextManager │ │
│ │ (services/dynamic_context_manager.py) │ │
│ │ - 向量检索历史对话 │ │
│ │ - 关键词检索补充 │ │
│ │ - 时间序列分析 │ │
│ │ - 动态截断和优化排列 │ │
│ └───────────────────┬──────────────────────────────────┘ │
└───────────────────────┼─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RAG 管道层 (RAG Pipeline Layer) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ RAGPipeline (rag_pipeline.py) │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ 阶段1: 意图识别 │ │ │
│ │ │ - 使用 LLM 识别意图 (chat/retrieval/statistics)│ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段2: 路由决策 │ │ │
│ │ │ - 根据意图选择处理流程 │ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段3: 多路召回（分层检索） │ │ │
│ │ │ - 向量检索 (Vector Retrieval) │ │ │
│ │ │ - 关键词检索 (BM25) │ │ │
│ │ │ - 混合检索 (Hybrid) │ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段4: 粗排序 (Coarse Ranking) │ │ │
│ │ │ - 多维度混合评分 │ │ │
│ │ │ - BM25F 评分 │ │ │
│ │ │ - 分数融合 │ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段5: 精排序 (Reranking) │ │ │
│ │ │ - 使用 LLM 重排序 │ │ │
│ │ │ - 相关性评分 │ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段6: 上下文构建 │ │ │
│ │ │ - 文档去重和合并 │ │ │
│ │ │ - 上下文格式化 │ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段7: 答案生成 │ │ │
│ │ │ - 统计查询：数据提取和计算 │ │ │
│ │ │ - 普通查询：LLM 生成答案 │ │ │
│ │ └───────────────────┬────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────▼────────────────────────────┐ │ │
│ │ │ 阶段8: 结果增强 │ │ │
│ │ │ - 答案后处理 │ │ │
│ │ │ - 结构化数据提取 │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 可观测性层 (Observability Layer) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ LayeredObservability │ │
│ │ (observability/layered_observability.py) │ │
│ │ - 全链路追踪 (Trace) │ │
│ │ - 分层指标收集 (Metrics) │ │
│ │ - 诊断面板 (Diagnostics) │ │
│ │ - 关联分析 (Correlation) │ │
│ └──────────────────────────────────────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 数据层 (Data Layer) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 向量数据库 (Chroma) │ │
│ │ - 文档向量存储 │ │
│ │ - 相似度检索 │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 嵌入模型 (HuggingFace Embeddings) │ │
│ │ - 文本向量化 │ │
│ │ - GPU 加速支持 │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ LLM (DeepSeek / OpenAI) │ │
│ │ - 意图识别 │ │
│ │ - 答案生成 │ │
│ │ - 重排序 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 流程图（Mermaid）
```mermaid
graph TB
Start([用户提问]) --> API[API层: 接收请求]
API --> Validate[参数验证]
Validate --> Service[服务层: RAGService]
Service --> CheckInit{检查初始化}
CheckInit -->|未初始化| Init[初始化RAG管道
加载模型]
CheckInit -->|已初始化| ContextCheck{是否有对话历史?}
Init --> ContextCheck
ContextCheck -->|有| ContextMgr[动态上下文管理器
提取相关历史对话]
ContextCheck -->|无| Pipeline[RAG管道: query方法]
ContextMgr --> Pipeline
Pipeline --> Intent[阶段1: 意图识别
_detect_intent]
Intent --> IntentType{意图类型?}
IntentType -->|chat| ChatLLM[直接调用LLM回答]
IntentType -->|retrieval/statistics| Routing[阶段2: 路由决策]
Routing --> MultiRetrieval[阶段3: 多路召回
_multi_retrieval]
MultiRetrieval --> VectorRet[向量检索
Vector Retrieval]
MultiRetrieval --> KeywordRet[关键词检索
BM25 Retrieval]
MultiRetrieval --> HybridRet[混合检索
Hybrid Retrieval]
VectorRet --> CoarseRank[阶段4: 粗排序
多维度评分]
KeywordRet --> CoarseRank
HybridRet --> CoarseRank
CoarseRank --> SemanticScore[语义相似度评分]
CoarseRank --> KeywordScore[关键词匹配评分]
CoarseRank --> BM25Score[BM25F评分]
CoarseRank --> HybridScore[混合评分融合]
HybridScore --> Rerank[阶段5: 精排序
LLM重排序]
Rerank --> ContextBuild[阶段6: 上下文构建
文档去重和格式化]
ContextBuild --> AnswerType{查询类型?}
AnswerType -->|statistics| StatsProcess[统计查询处理
数据提取和计算]
AnswerType -->|retrieval| GenLLM[阶段7: 答案生成
LLM生成答案]
StatsProcess --> Enhance[阶段8: 结果增强
_enhance_answer]
GenLLM --> Enhance
Enhance --> Format[格式化响应]
Format --> Response[返回JSON响应]
ChatLLM --> Response
Response --> End([返回给用户])
style Start fill:#e1f5ff
style End fill:#e1f5ff
style Intent fill:#fff4e1
style MultiRetrieval fill:#fff4e1
style CoarseRank fill:#fff4e1
style Rerank fill:#fff4e1
style GenLLM fill:#fff4e1
style Enhance fill:#fff4e1
```
## 📄 许可证
MIT License
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！