# Agentic-RAG

**Repository Path**: ye_sheng0839/agentic-rag

## Basic Information

- **Project Name**: Agentic-RAG
- **Description**: 适合Langchain初学者学习的RAG系统，实践了Langchian 1.1的中间件概念
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-10
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: RAG, langchain

## README

# Agentic RAG (DeepSeek-V3.2)

> 基于 LangChain 1.1 标准 Agent 架构的 RAG 示例，配合 DeepSeek-Chat 与 FAISS，涵盖动态系统提示、工具调用和可溯源引用展示。

## 项目简介
- 后端：FastAPI + LangChain 1.1，提供上传、建库、召回测试与 Agent 对话接口。
- 前端：Vite + React，支持文件上传、知识库管理与带引用的对话体验。
- 知识库：双层切分（Markdown 章节 + 递归字符）+ OpenAI Embeddings + FAISS，本地存储于 `backend/data/vector_stores/`。
- Agent 特性：动态读取知识库元数据，组装场景化 System Prompt；工具返回 `content_and_artifact`，前端可展示引用和分数。

## 目录速览
```
backend/
├─ app/
│  ├─ main.py                  # 应用入口与 CORS 配置
│  ├─ api/endpoints.py         # 上传/建库/召回/对话接口
│  ├─ services/
│  │  ├─ file_service.py       # 文件清洗、切分、向量化、元数据生成
│  │  └─ agent_service.py      # Agent 编排、工具绑定、结果解析
├─ data/
│  ├─ uploads/                 # 上传文件临时存放
│  └─ vector_stores/           # FAISS 索引与 metadata.json
frontend/                      # Web 客户端，详情见 frontend/README.md
docs/                          # 项目的AI开发文档，用于展示项目开发过程
```

## 快速开始

### 环境配置
```bash
cp .env.example .env
# 根据实际情况修改 .env 文件中的各项参数
```

### 后端
```bash
cd backend
pip install -r requirements.txt                     # 安装依赖
uvicorn app.main:app --host 0.0.0.0 --port 8002 --reload  # 启动服务
curl http://localhost:8002/health                       # 健康检查
```

### 前端
```bash
cd ../frontend
pnpm install                                           # 或 npm install
pnpm dev                                               # 默认代理 http://localhost:8002
```

## 核心流程
1. 上传文件：`POST /api/upload`，返回文件名列表。  
2. 创建/重建知识库：`POST /api/kb/create`，参数 `kb_name`、`file_filenames`、`chunk_size`、`chunk_overlap`。  
3. 召回测试：`POST /api/kb/recall`，查看检索片段与分数。  
4. Agent 对话：`POST /api/chat`，携带 `query` 与可选 `kb_name`、`top_k`，返回回答与引用来源。

## API 速查
- `POST /api/upload`：上传 Markdown/文本文件。
- `POST /api/kb/create`：基于上传文件构建向量库。
- `POST /api/kb/recall`：仅检索不生成回答，返回文档片段与分数。
- `POST /api/chat`：Agentic RAG 对话，返回 `answer` 与 `sources`。
- `GET /health`：服务探活。

## 常见问题
- 未返回引用：确认调用时传入 `kb_name` 且知识库已通过 `/api/kb/create` 构建。
- 分数解读：FAISS L2 距离，数值越小相关性越高。
- 模型未响应：检查 `DEEPSEEK_API_KEY`/`OPENAI_API_KEY` 与 Base URL 是否可用。