# agentic-rag-langgraph-demo

**Repository Path**: ai-agent-learning/agentic-rag-langgraph-demo

## Basic Information

- **Project Name**: agentic-rag-langgraph-demo
- **Description**: 示例项目：实现 Agentic RAG 与人机协作，基于 LangGraph 的工作流编排
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-23
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agentic RAG 智能物流助手

#### 项目介绍

基于 LangGraph 的 Agentic RAG 智能物流助手 Demo，实现人机协作，可解析图片、调用工具、展示多种卡片类型。

---

## 技术栈

| 类别 | 技术选型 | 说明 |
|------|----------|------|
| 工作流编排 | LangGraph |  最新版本的工作流编排框架 |
| LLM | OpenAI GPT-4o | 多模态模型，支持图片解析 |
| 向量数据库 | Milvus | 高性能向量检索 |
| 文档解析 | Unstructured | PDF/Word/图片等文档解析 |
| 文档存储 | 阿里云 OSS | 海量文档存储 |
| 关系数据库 | PostgreSQL | 存储短期记忆（会话）+ 长期记忆 |
| 前端框架 | Vue3 + Vite | 现代前端开发框架 |
| 通信协议 | SSE | Server-Sent Events 流式推送 |

---

## 核心功能

1. **多模态对话** - 支持文字和图片输入，GPT-4o 解析图片内容
2. **Agentic RAG** - 智能检索、工具调用、人机协作
3. **知识库管理** - 文档上传、解析、向量化存储、语义检索
4. **SSE 实时推送** - 流式响应，前端动态展示各类卡片
5. **记忆管理** - 会话短期记忆 + 用户长期记忆

---

## SSE 事件类型设计

前端通过 SSE 接收后端推送的流式数据，每行数据为 JSON 格式：

```json
{"eventData":"文本内容","eventType":1001}
```

| eventType | 名称 | 说明 |
|-----------|------|------|
| 1001 | 数据事件 | 文本内容 |
| 1002 | 停止事件 | 流式响应结束，标识对话完成 |
| 1003 | 卡片事件 | 运单卡、承运商卡、司机卡、地图卡等 |
| 1004 | RAG 检索来源 | 知识库检索来源信息 |
| 1005 | 工具调用链 | 工具调用过程、参数、结果 |
| 1006 | 人机协作 | 需要用户批准的确认框 |
| ... | 扩展事件 | 可根据需要扩展 |

---

## 项目目录结构（LangGraph CLI）

使用 LangGraph CLI 创建的项目结构：

```
agentic-rag-langgraph-demo/
├── front-design/                 # 前端原型（静态 HTML）
├── backend/                      # 后端项目（LangGraph CLI）
│   ├── src/
│   │   ├── agent.py             # Agent 定义，包含 create_agent 函数
│   │   ├── graph/               # LangGraph 工作流
│   │   │   ├── nodes/           # 节点定义
│   │   │   │   ├── __init__.py
│   │   │   │   ├── router.py    # 路由节点
│   │   │   │   ├── retrieval.py # RAG 检索节点
│   │   │   │   ├── tool_call.py # 工具调用节点
│   │   │   │   └── response.py  # 响应生成节点
│   │   │   ├── state.py          # 状态定义
│   │   │   └── builder.py        # 工作流构建器
│   │   ├── services/             # 业务服务
│   │   │   ├── __init__.py
│   │   │   ├── llm.py           # LLM 服务
│   │   │   ├── vectorstore.py   # 向量存储
│   │   │   ├── document.py      # 文档处理
│   │   │   └── oss.py           # OSS 存储
│   │   ├── memory/               # 记忆管理
│   │   │   ├── __init__.py
│   │   │   ├── short_term.py    # 短期记忆（会话）
│   │   │   └── long_term.py     # 长期记忆（用户画像）
│   │   └── tools/                # 工具定义
│   │       ├── __init__.py
│   │       └── mock_tools.py    # 模拟工具（运单/承运商查询）
│   ├── .env                     # 环境变量
│   ├── requirements.txt         # 依赖
│   └── langgraph.json           # LangGraph CLI 配置文件
├── frontend/                    # 前端项目（Vue3 + Vite）
│   ├── src/
│   │   ├── api/                 # API 调用
│   │   ├── components/          # 组件
│   │   ├── views/               # 页面
│   │   ├── stores/              # 状态管理
│   │   └── utils/               # 工具函数
│   └── package.json
└── README.md
```

---

## 前端配置

在 `frontend/src/config.js` 中配置用户信息：

```javascript
// 用户配置（Demo 使用固定配置）
export const USER_CONFIG = {
  userId: "user_001",      // 用户 ID
  userName: "张三"          // 用户名称
};
```

会话 ID (session_id) 由前端自动生成 UUID。

---

## 环境变量

### 后端 (.env)

```bash
# OpenAI
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=agentic_rag

# Milvus
MILVUS_HOST=localhost
MILVUS_PORT=19530

# 阿里云 OSS
OSS_ACCESS_KEY_ID=xxx
OSS_ACCESS_KEY_SECRET=xxx
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_BUCKET_NAME=your-bucket
```

---

## 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/your-repo/agentic-rag-langgraph-demo.git
cd agentic-rag-langgraph-demo
```

### 2. 后端启动

```bash
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 启动服务
python main.py
```

### 3. 前端启动

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问 http://localhost:5173

---

## 设计原则

本项目代码遵循以下设计原则：

1. **可维护性** - 清晰的目录结构，模块职责明确
2. **可读性** - 全面注释，命名规范，类型提示
3. **可扩展性** - 插件化设计，便于添加新功能
4. **灵活性** - 配置驱动，易于调整
5. **简洁性** - 避免过度设计，保持代码简洁
6. **可复用性** - 通用组件和服务抽象

---

## 许可证

MIT License