# light

**Repository Path**: GrainRain/light

## Basic Information

- **Project Name**: light
- **Description**: AI   智能体问答系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能问答系统 (Intelligent QA System)

基于大语言模型（LLM）和检索增强生成（RAG）技术的智能问答系统，支持自然语言交互、上下文理解以及基于特定知识库的问答。

## 📋 项目概述
clean
本项目采用前后端分离架构，利用 LangChain 框架实现智能路由、知识检索和对话生成。系统能够自动识别用户意图，并根据问题类型选择最优的处理策略（RAG 检索或通用对话）。

### 核心特性

- ✅ **智能意图识别**：基于 LangChain Tool Calling 的路由机制，自动区分知识查询和闲聊
- ✅ **RAG 检索增强**：支持向量数据库语义检索，提供基于事实的准确回答
- ✅ **多轮对话管理**：利用 PostgreSQL JSONB 存储对话历史，支持上下文理解
- ✅ **异步高性能**：FastAPI + asyncpg 异步架构，支持高并发请求
- ✅ **模块化设计**：清晰的代码结构，易于扩展和维护

## 🏗️ 技术栈

### 后端
- **框架**: FastAPI (Python 3.10+)
- **AI 框架**: LangChain
- **大语言模型**: OpenAI GPT-4 / Claude / 本地 Llama
- **关系型数据库**: PostgreSQL (支持 JSONB 和 pgvector)
- **向量数据库**: ChromaDB / Milvus

### 前端
- **框架**: Next.js (TypeScript)
- **样式**: Vanilla CSS / CSS Modules
- **状态管理**: React Context / Zustand

## 🚀 快速开始

### 1. 环境准备

#### 系统要求
- Python 3.10 或更高版本
- Node.js 18+ (用于前端开发)
- Docker (可选，用于数据库部署)

#### 克隆项目
```bash
git clone <your-repo-url>
cd light
```

### 2. 后端环境配置

#### 创建虚拟环境
```bash
# 创建 Python 虚拟环境
python3 -m venv .venv

# 激活虚拟环境
# macOS/Linux:
source .venv/bin/activate

# Windows:
# .venv\Scripts\activate
```

#### 安装依赖
```bash
pip install -r backend/requirements.txt
```

#### 配置环境变量
在项目根目录创建 `.env` 文件：
```bash
# 复制模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API Key
# OPENAI_API_KEY=sk-your-actual-key-here
```

### 3. 运行验证脚本

#### 测试智能路由功能
```bash
# 确保虚拟环境已激活
.venv/bin/python backend/app/core/agent_router.py
```

**预期输出**：
```
>>> 启动路由原型验证...

[测试 A: 专业查询]
回答内容: [系统会给出关于病假流程的专业回答]

[测试 B: 闲聊]
回答内容: [系统会给出友好的闲聊回复]
```

### 4. 启动开发服务器（待实现）

```bash
# 启动后端 API 服务
cd backend
uvicorn app.main:app --reload --port 8000

# 启动前端开发服务器（另一个终端）
cd frontend
npm run dev
```

## 📁 项目结构

```
light/
├── backend/                    # 后端代码
│   ├── app/
│   │   ├── core/              # 核心业务逻辑
│   │   │   └── agent_router.py  # 智能路由器（已实现）
│   │   ├── logic/             # 业务逻辑层
│   │   └── api/               # API 路由（待实现）
│   └── requirements.txt       # Python 依赖
├── frontend/                  # 前端代码（待实现）
├── docs/                      # 项目文档
│   └── architecture_design.md # 架构设计文档
├── .venv/                     # Python 虚拟环境（不提交到 Git）
├── .env                       # 环境变量配置（不提交到 Git）
└── README.md                  # 本文件
```

## 🔧 虚拟环境说明

### 什么是 `.venv`？

`.venv` 是 Python 的**虚拟环境目录**，用于隔离项目依赖，确保不同项目之间的库版本互不干扰。

### 核心作用

1. **依赖隔离**：每个项目拥有独立的 `site-packages`，避免版本冲突
2. **保持系统环境干净**：不污染系统级 Python 环境
3. **便于复现和部署**：通过 `requirements.txt` 精确记录依赖

### 如何使用

#### 激活虚拟环境
```bash
# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate
```

激活后，终端提示符会显示 `(.venv)`。

#### 退出虚拟环境
```bash
deactivate
```

#### 直接使用（无需激活）
```bash
# 直接指定虚拟环境中的 Python 路径
.venv/bin/python your_script.py
.venv/bin/pip install package_name
```

### 虚拟环境目录结构
```
.venv/
├── bin/              # 可执行文件（python, pip, activate）
├── lib/              # Python 标准库和第三方库
│   └── python3.x/
│       └── site-packages/  # pip 安装的包
└── pyvenv.cfg       # 虚拟环境配置
```

### 最佳实践

✅ **应该做的**：
- 每个项目创建独立的虚拟环境
- 将 `.venv` 添加到 `.gitignore`
- 使用 `requirements.txt` 记录依赖

❌ **不应该做的**：
- 在全局环境安装项目依赖
- 提交 `.venv` 到版本控制
- 多个项目共用一个虚拟环境

## 🔐 环境变量说明

### `.env` 文件

`.env` 文件用于存储敏感配置信息（如 API Key），**不应提交到 Git**。

#### 必需的环境变量
```bash
# OpenAI API 配置
OPENAI_API_KEY=your_actual_openai_api_key_here

# 可选：自定义 API 端点
# OPENAI_API_BASE=https://api.openai.com/v1
```

#### `.env` 与 `.venv` 的区别

| 项目 | `.venv` | `.env` |
|------|---------|--------|
| **类型** | 目录（文件夹） | 文件 |
| **作用** | 隔离 Python 依赖环境 | 存储环境变量（如 API Key） |
| **是否提交到 Git** | ❌ 否（太大） | ❌ 否（包含敏感信息） |
| **生成方式** | `python3 -m venv .venv` | 手动创建 |

## 📚 架构文档

详细的系统架构设计请参考：[docs/architecture_design.md](docs/architecture_design.md)

### 核心架构亮点

1. **智能路由机制**：基于 LangChain Tool Calling 的意图识别
2. **RAG 流水线**：查询优化 → 向量检索 → 重排序 → 答案合成
3. **数据库选型**：PostgreSQL + ChromaDB 组合，兼顾灵活性和性能
4. **异步架构**：FastAPI + asyncpg，支持高并发场景

## 🛠️ 开发指南

### 依赖管理

#### 安装新依赖
```bash
# 激活虚拟环境后
pip install package_name

# 更新 requirements.txt
pip freeze > backend/requirements.txt
```

#### 同步依赖
```bash
pip install -r backend/requirements.txt
```

### 代码规范

- Python 代码遵循 PEP 8 规范
- 使用类型注解（Type Hints）
- 函数和类添加 Docstring

## 📝 待办事项

- [ ] 实现 FastAPI 主应用框架
- [ ] 集成 ChromaDB 向量数据库
- [ ] 实现文档上传和向量化流程
- [ ] 开发前端 UI 界面
- [ ] 添加用户认证系统
- [ ] 实现对话历史持久化
- [ ] Docker 容器化部署
- [ ] 编写单元测试和集成测试

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

[待定]

---

**注意**：本项目目前处于开发阶段，部分功能尚未实现。请参考架构设计文档了解完整的系统规划。