目录
master
分支2
标签1
+ 疑修
Web IDE
somunslotus
解决冲突
2个月前34次提交
目录README.md

LLM 问答系统

一个支持 OpenAI 和阿里千问大模型的问答系统，提供 HTTP 和流式接口，具备完整的会话管理功能。

功能特性

后端功能

  • ✅ 支持 OpenAI 系列模型（GPT-3.5、GPT-4 等）
  • ✅ 支持阿里千问系列模型（Qwen Turbo、Qwen Plus、Qwen Max）
  • ✅ HTTP 标准问答接口
  • ✅ 服务器推送事件（SSE）流式接口
  • ✅ 会话管理（创建、删除、更新）
  • ✅ 消息存储和历史记录
  • ✅ 良好的代码分层架构（Controller-Service-Repository）
  • ✅ RESTful API 设计
  • ✅ 异步数据库操作
  • ✅ CORS 跨域支持

前端功能

  • ✅ 现代化的 React + TypeScript 开发
  • ✅ 会话列表管理
  • ✅ 实时流式对话显示
  • ✅ 多模型选择
  • ✅ 响应式设计
  • ✅ 美观的用户界面

技术栈

后端

  • 框架: FastAPI
  • 数据库: SQLite / PostgreSQL / MySQL + SQLAlchemy (异步)
  • AI SDK: OpenAI SDK, DashScope SDK
  • 其他: Pydantic, Uvicorn

前端

  • 框架: React 18 + TypeScript
  • 构建工具: Vite
  • HTTP 客户端: Axios
  • 样式: CSS Modules

部署

  • 容器化: Docker + Docker Compose
  • Web 服务器: Nginx

项目结构

llm-QA/
├── backend/                 # 后端代码
│   ├── api/                # API 控制器层
│   │   ├── __init__.py
│   │   ├── chat.py         # 聊天接口
│   │   └── session.py      # 会话管理接口
│   ├── services/           # 服务层
│   │   ├── __init__.py
│   │   ├── llm_service.py  # LLM 集成服务
│   │   └── session_service.py  # 会话业务逻辑
│   ├── repositories/       # 数据访问层
│   │   ├── __init__.py
│   │   ├── session_repository.py
│   │   └── message_repository.py
│   ├── models/             # 数据模型
│   │   ├── __init__.py
│   │   ├── session.py
│   │   └── message.py
│   ├── schemas/            # 请求/响应模式
│   │   ├── __init__.py
│   │   ├── chat.py
│   │   └── session.py
│   ├── config.py           # 配置管理
│   ├── database.py         # 数据库配置
│   ├── main.py             # 应用入口
│   ├── requirements.txt    # Python 依赖
│   └── Dockerfile          # Docker 配置
├── frontend/               # 前端代码
│   ├── src/
│   │   ├── components/     # React 组件
│   │   │   ├── SessionList.tsx
│   │   │   ├── ChatArea.tsx
│   │   │   ├── MessageItem.tsx
│   │   │   └── NewSessionModal.tsx
│   │   ├── services/       # API 服务
│   │   │   └── api.ts
│   │   ├── types/          # TypeScript 类型
│   │   │   └── index.ts
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   ├── vite.config.ts
│   ├── nginx.conf          # Nginx 配置
│   └── Dockerfile
├── docker-compose.yml      # Docker Compose 配置
├── .env.example            # 环境变量示例
└── README.md               # 项目文档

快速开始

前置要求

  • Docker 20.10+
  • Docker Compose 1.29+
  • OpenAI API Key 或 阿里云 DashScope API Key

1. 克隆项目

git clone <repository-url>
cd llm-QA

2. 配置环境变量

复制 .env.example 到 .env 并填入你的 API Keys：

cp .env.example .env

编辑 .env 文件：

# Server Configuration（服务器部署时需要配置）
SERVER_IP=localhost          # 本地测试用localhost，服务器部署改为实际IP
SERVER_PORT=80              # 前端服务端口

# Database Configuration（数据库配置）
DB_TYPE=sqlite              # 数据库类型：sqlite, postgresql, mysql
SQLITE_DATABASE=./data/llm_qa.db

# 如果使用 PostgreSQL，配置以下参数：
# POSTGRES_HOST=postgres
# POSTGRES_PORT=5432
# POSTGRES_DB=llm_qa
# POSTGRES_USER=postgres
# POSTGRES_PASSWORD=your_secure_password

# 如果使用 MySQL，配置以下参数：
# MYSQL_HOST=mysql
# MYSQL_PORT=3306
# MYSQL_DB=llm_qa
# MYSQL_USER=root
# MYSQL_PASSWORD=your_secure_password

# OpenAI Configuration
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1

# Alibaba Qianwen Configuration
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

重要提示：

  • 🏠 本地开发/测试：SERVER_IP=localhost
  • 🌐 服务器部署：SERVER_IP=192.168.1.100（改为实际IP或域名）
  • 💾 数据库选择：默认使用 SQLite，生产环境推荐 PostgreSQL
  • 📖 详细配置说明：SERVER_CONFIG.md | DATABASE_CONFIG.md

3. 启动系统

方式一：使用启动脚本（推荐）

# 使用 SQLite（默认，无需额外配置数据库）
./start.sh

# 或者使用独立数据库（PostgreSQL / MySQL）
# 需先在 .env 中配置 DB_TYPE 和相关数据库参数
./start-with-db.sh

# 查看日志
./logs.sh

# 停止服务
./stop.sh

方式二：手动使用 Docker Compose

# 仅启动应用（使用 SQLite）
docker compose up -d

# 启动应用 + PostgreSQL
docker compose -f docker-compose.yml -f docker-compose.db.yml --profile postgres up -d

# 启动应用 + MySQL
docker compose -f docker-compose.yml -f docker-compose.db.yml --profile mysql up -d

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

数据库选择说明：

  • 💾 SQLite（默认）：零配置，适合开发和小型应用
  • 🐘 PostgreSQL：高性能，适合生产环境
  • 🐬 MySQL：成熟稳定，兼容性好

详细配置请参考：DATABASE_CONFIG.md

4. 访问应用

开发模式

后端开发

cd backend

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

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API Keys

# 运行开发服务器
python main.py

# API 文档访问地址：http://localhost:8000/docs

前端开发

cd frontend

# 安装依赖
npm install

# 运行开发服务器
npm run dev

# 访问地址：http://localhost:3000

API 文档

会话管理

创建会话

POST /api/sessions/
Content-Type: application/json

{
  "title": "我的第一个会话",
  "model_type": "openai",
  "model_name": "gpt-3.5-turbo"
}

获取会话列表

GET /api/sessions/

获取会话详情

GET /api/sessions/{session_id}?include_messages=true

更新会话

PATCH /api/sessions/{session_id}
Content-Type: application/json

{
  "title": "新的标题"
}

删除会话

DELETE /api/sessions/{session_id}

获取会话消息

GET /api/sessions/{session_id}/messages

聊天接口

标准聊天（非流式）

POST /api/chat/
Content-Type: application/json

{
  "session_id": "xxx",
  "message": "你好",
  "model_type": "openai",
  "model_name": "gpt-3.5-turbo",
  "temperature": 0.7,
  "max_tokens": 2000
}

流式聊天

POST /api/chat/stream
Content-Type: application/json

{
  "session_id": "xxx",
  "message": "你好",
  "model_type": "qianwen",
  "model_name": "qwen-max",
  "temperature": 0.7,
  "max_tokens": 2000
}

响应格式（SSE）：

data: {"content": "你", "done": false}

data: {"content": "好", "done": false}

data: {"content": "", "done": true, "message_id": "xxx"}

支持的模型

OpenAI 模型

  • gpt-3.5-turbo - GPT-3.5 Turbo
  • gpt-4 - GPT-4
  • gpt-4-turbo-preview - GPT-4 Turbo

阿里千问模型

  • qwen-turbo - 千问 Turbo（快速响应）
  • qwen-plus - 千问 Plus（平衡性能）
  • qwen-max - 千问 Max（最强性能）

架构设计

后端分层架构

┌─────────────────┐
│   API Layer     │  FastAPI 路由和控制器
├─────────────────┤
│  Service Layer  │  业务逻辑处理
├─────────────────┤
│ Repository Layer│  数据访问抽象
├─────────────────┤
│   Model Layer   │  数据模型定义
└─────────────────┘

优点：

  • 清晰的职责分离
  • 易于测试和维护
  • 灵活的数据源切换
  • 业务逻辑复用

前端组件架构

App
├── SessionList         # 会话列表组件
│   └── SessionItem
├── ChatArea            # 聊天区域组件
│   ├── MessageItem     # 消息组件
│   └── InputArea
└── NewSessionModal     # 新建会话弹窗

配置说明

后端配置 (backend/config.py)

  • OPENAI_API_KEY: OpenAI API 密钥
  • OPENAI_BASE_URL: OpenAI API 基础 URL
  • DASHSCOPE_API_KEY: 阿里云 DashScope API 密钥
  • APP_HOST: 应用监听地址（默认 0.0.0.0）
  • APP_PORT: 应用监听端口（默认 8000）
  • DATABASE_URL: 数据库连接 URL
  • CORS_ORIGINS: 允许的跨域来源

前端配置

  • 开发模式下，API 请求会代理到 http://backend:8000
  • 生产模式下，通过 Nginx 反向代理到后端

数据持久化

数据存储在 SQLite 数据库中，位于 backend/data/llm_qa.db。

数据表结构：

sessions - 会话表

  • id: 主键
  • title: 会话标题
  • model_type: 模型类型
  • model_name: 模型名称
  • created_at: 创建时间
  • updated_at: 更新时间
  • message_count: 消息数量

messages - 消息表

  • id: 主键
  • session_id: 会话 ID（外键）
  • role: 角色（user/assistant）
  • content: 消息内容
  • token_count: Token 数量
  • created_at: 创建时间

故障排查

后端启动失败

  1. 检查 API Keys 是否正确配置
  2. 检查端口 8000 是否被占用
  3. 查看日志：docker-compose logs backend

前端无法连接后端

  1. 确认后端服务正常运行
  2. 检查 Docker 网络配置
  3. 查看 Nginx 日志：docker-compose logs frontend

数据库问题

# 删除数据库重新初始化
rm -rf backend/data/llm_qa.db
docker-compose restart backend

性能优化

  1. 数据库优化: 使用索引、连接池
  2. 缓存策略: 静态资源缓存、API 响应缓存
  3. 流式响应: 降低首字节时间（TTFB）
  4. 异步处理: 使用 async/await 提高并发性能

安全建议

  1. 不要在代码中硬编码 API Keys
  2. 使用环境变量管理敏感信息
  3. 在生产环境启用 HTTPS
  4. 限制 CORS 允许的来源
  5. 实现请求频率限制

许可证

MIT License

联系方式

如有问题或建议，请提交 Issue。

祝您使用愉快！ 🎉

关于
README.md
671.0 KB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

©Copyright 2023 CCF 开源发展委员会
Powered by Trustie& IntelliDE 京ICP备13000930号