# fastapi-demo

**Repository Path**: wanggang826/fastapi-demo

## Basic Information

- **Project Name**: fastapi-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-16
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大模型RAG项目后台接口

这是一个基于Python FastAPI框架实现的大模型RAG项目的后台接口部分。

## 项目结构

```
app/
├── admin/                # API路由
│   └── v1/             # API版本1
│       ├── __init__.py # 路由注册
│       └── knowledge.py # 知识库API
├── core/               # 核心配置
│   ├── config.py       # 配置类
│   └── logger.py       # 日志配置
├── db/                 # 数据库相关
│   ├── __init__.py
│   └── session.py      # 数据库会话
├── models/             # 数据库模型
│   ├── __init__.py
│   └── knowledge.py    # 知识库模型
├── schemas/            # Pydantic模型
│   ├── __init__.py
│   └── knowledge.py    # 知识库Schema
├── services/           # 业务逻辑
│   ├── __init__.py
│   └── knowledge.py    # 知识库服务
├── utils/              # 工具函数
│   └── __init__.py
└── main.py             # 主应用
```

## 功能特性

- 知识库管理：创建、查询、更新、删除、启用/禁用
- 支持分页和关键词搜索
- 基于MySQL的关系数据存储
- 基于Elasticsearch的文档元数据和向量数据存储
- 完整的日志记录

## 环境要求

- Python 3.8+
- MySQL 8.0+
- Elasticsearch 8.0+

## 安装

### 安装ES

ES的密码等会在目录下的.env文件里.

启动和停止服务,在安装目录下执行:
````
start.sh
stop.sh
````

## 测试

1. 运行所有测试
```
pytest
```

2. 运行特定目录的测试
```
pytest tests/unit
```

3. 运行特定文件的测试
```
pytest tests/unit/test_document_service.py
```
4. 运行测试并生成覆盖率报告
```
pytest --cov=app tests/
cd your_dir
sudo curl -fsSL https://elastic.co/start-local | sudo sh
```


## 部署项目

1. 克隆仓库

```bash
git clone <repository-url>
cd <repository-directory>
```
2. 创建虚拟环境
```
conda create -n ai_rag python=3.12
conda activate ai_rag
```

2. 安装依赖

```bash
pip install -r requirements.txt
```

3. 配置环境变量

复制`.env.example`文件为`.env`，并根据实际情况修改配置。

```bash
cp .env.example .env
```

## 运行

```bash
# 开发模式
python -m app.main 或 ./start.sh

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## API文档

启动应用后，可以通过以下URL访问API文档：

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc


# 编码规范

## API 路由例规范
1. 获取列表
```
GET /admin/v1/wechat-mp/list?page=1&size=10&keyword=test
```

2. 获取详情
```
GET /admin/v1/wechat-mp/detail?config_id=1
```

3. 创建
```
POST /admin/v1/wechat-mp/create
Body: {...}
```

4. 更新
```
POST /admin/v1/wechat-mp/update?config_id=1
Body: {...}
```

5. 删除
```
POST /wechat-mp/delete?config_id=1
```

## model
model目录定义基本的数据结构,要和数据库字段一一对应.

## schemas
schemas目录定义接口请求和响应的数据结构.
1. 请求参数命令规范:XxxCreate, XxxUpdate, XxxDelete
2. 响应命令规范: XxxResponse, XxxRelResponse(包含了关联数据,比如知识库的响应里,把创建人姓名 部门名称这些数据也包含进去了), XxxListItemResponse, XxxPaginatedResponse

## service
service 用 staticmethod ,全部做成静态方法
尽量少用join查询
service层返回model中定义的类,service中不能使用schemas中定义的类

### 方法命名
1. create 创建
2. update 更新
3. get 根据id获取, get_rel 根据id获取基本信息及关联信息 
4. 根据其它参数获取方法名 get_by_employee
4. get_list 获取列表
5. search_by_name 搜索

## 其它
1. post请求时,参数全部通过body上提交json格式的数据.
2. 时间一律用数字,bigint, 在终端显示时格式化