# rag-app

**Repository Path**: barbosa/rag-app

## Basic Information

- **Project Name**: rag-app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java 知识库 RAG 应用

> 基于 Spring AI + Milvus + Python Core 的高性能智能问答系统

这是一个典型的 **Java/Python 双栈 RAG** 实现方案，结合了 Java 在业务逻辑编排上的稳健性和 Python 在 AI 生态（LangChain/Embedding）上的灵活性。

---

## 📋 快速开始

### 1. 环境准备
- **Docker**: 核心三件套（Milvus, MinIO, Etcd）+ Attu 可视化控制台。
- **Python 3.10+**: 位于 `rag-langchain` 目录中。
- **Java 17+**: 位于 `rag-api` 等模块中。

### 2. 项目结构

```bash
rag-app/
├── rag-api/                   # Java API 层 (Spring Boot) - 处理业务逻辑与工作流
├── rag-langchain/             # Python RAG 核心层 (FastAPI) [大脑]
│   ├── app/
│   │   ├── ingestion/         # 增强版入库管道 (Markdown 感知 + 哈希去重)
│   │   ├── middleware/        # 分布式追踪 (Trace ID: ingest_xxx / query_xxx)
│   │   └── vectorize_docs.py  # 核心向量化脚本
│   └── .venv/                 # Python 运行时环境
├── docs/                      # 标准化项目文档系统
│   ├── architecture/          # 核心架构设计文档 (入库管道、日志追踪)
│   ├── implementation-plans/  # 历史实施方案归档
│   └── reports/               # 评测与测试报告 (召回率分析)
├── milvus/                    # Milvus 部署配置 (Docker Compose)
└── rag-starter/               # Java 端启动入口
```

---

## �️ 核心特性

- **🚀 增强型入库管道**: 支持全量 Markdown 递归感知切分，自带 MD5 内容哈希去重，彻底告别重复检索。
- **🔍 全链路 TraceID**: 模拟生产级追踪系统，所有日志均带有 `X-Trace-ID`，支持跨语言追踪（Java -> Python）。
- **📊 自动化召回评测**: 自研 `evaluate_recall.py` 工具，支持 Top-K 检索详情分析与语义偏移诊断。
- **🖥️ 可视化控制**: 集成了 **Attu** 控制台，通过 `http://localhost:8000` 实时观测向量库变动。

---

## 🧪 评测与自检系统

运行以下命令执行首次召回效果评测：
```bash
cd rag-langchain
export PYTHONPATH=$PYTHONPATH:.
.venv/bin/python app/evaluate_recall.py --k 5
```

---

## 📚 深度文档
- [📖 Python 入库管道设计](docs/architecture/ingestion-pipeline.md)
- [📖 日志与分布式追踪设计](docs/architecture/logging-and-tracing.md)
- [📈 召回效果首次评测报告](docs/reports/recall-evaluation-v1.md)

---

## 📝 当前状态 (Last Updated: 2026-02-02)

### ✅ 已完成
- [x] **基础设施**: Milvus + Attu 容器化部署完成。
- [x] **Python 核心**: 实现了基于 BGE-M3 的高性能语义检索内核。
- [x] **日志增强**: 全链路 Trace ID 注入机制，支持 `app.log` 和 `ingest.log`。
- [x] **召回评测**: 完成首轮 4549 条数据的召回基准测试。

### ⏳ 待完成 (Phase 2 & 3)
- [ ] **混合搜索 (Hybrid Search)**: 引入关键词检索提升标题匹配精度。
- [ ] **Rerank 精排**: 针对 Top-N 结果进行二次精排。
- [ ] **Java/Python 全链路打通**: 优化跨语言调用与错误处理。

---
**💡 提示**：如需修改 API 配置，请编辑根目录下的 `.env` 文件。