mirror of
https://github.com/handsomezhuzhu/QQuiz.git
synced 2026-02-20 20:10:14 +00:00
docs: 完善文档和清理项目，添加 Gemini 配置指南
主要更新： 📚 文档改进 - 新增 AI_CONFIGURATION.md：详细的 AI 提供商配置指南 - 新增 CHINA_MIRROR_GUIDE.md：中国镜像加速指南 - 删除 6 个过时文档（DEPLOYMENT.md, QUICK_START.md 等） - 更新 README.md：添加 Gemini 功能特性和 AI 提供商对比表 🧹 脚本清理 - 删除 11 个重复/过时脚本（从 25 个减少到 14 个） - 删除 PostgreSQL 相关脚本（项目使用 MySQL） - 删除重复的启动脚本（start_windows.bat, start_app.bat 等） ⚙️ 配置文件更新 - 更新 .env.example：添加 Gemini 配置示例和说明 - 默认 AI_PROVIDER 改为 gemini（推荐） - 添加各提供商的获取 API Key 链接 🎯 核心改进 - 突出 Gemini 原生 PDF 理解优势 - 提供清晰的 AI 提供商选择指南 - 简化项目结构，提高可维护性 清理内容： - 删除 docs: DEPLOYMENT.md, DOCKER_MIRROR_SETUP.md, GITHUB_PUSH_GUIDE.md, QUICK_START.md, README_QUICKSTART.md, START_HERE.txt - 删除 scripts: auto_setup_and_run.bat, check_postgres.bat, logs_windows.bat, push_to_github.bat, quick_config.bat, restart_docker.bat, setup_docker_mirror.bat, start_app.bat, start_postgres.bat, start_windows.bat, start_windows_china.bat 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
201
docs/AI_CONFIGURATION.md
Normal file
201
docs/AI_CONFIGURATION.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# AI 提供商配置指南
|
||||
|
||||
QQuiz 支持多个 AI 提供商，推荐使用 Google Gemini 以获得最佳的 PDF 解析体验。
|
||||
|
||||
## 🌟 推荐：Google Gemini
|
||||
|
||||
### 优势
|
||||
|
||||
- ✅ **原生 PDF 理解**：直接处理 PDF（最多1000页），完整保留图片、表格、公式
|
||||
- ✅ **免费额度充足**：每天免费 15 次/分钟，1500 次/天
|
||||
- ✅ **多模态理解**：支持图片、图表、公式的理解
|
||||
- ✅ **自定义代理**：支持配置自定义 Base URL 实现 Key 轮训等功能
|
||||
|
||||
### 获取 API Key
|
||||
|
||||
1. 访问 https://aistudio.google.com/apikey
|
||||
2. 使用 Google 账号登录
|
||||
3. 点击 "Create API Key"
|
||||
4. 复制生成的 API Key（格式：`AIza...`）
|
||||
|
||||
### 配置方式
|
||||
|
||||
#### 方式一：环境变量配置（推荐首次部署）
|
||||
|
||||
编辑 `.env` 文件：
|
||||
|
||||
```env
|
||||
AI_PROVIDER=gemini
|
||||
GEMINI_API_KEY=AIza-your-actual-gemini-api-key
|
||||
GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GEMINI_MODEL=gemini-2.0-flash-exp
|
||||
```
|
||||
|
||||
#### 方式二：管理员后台配置（推荐生产环境）
|
||||
|
||||
1. 使用管理员账号登录（默认：admin / admin123）
|
||||
2. 进入"系统设置"
|
||||
3. 选择 AI 提供商："Google Gemini (推荐)"
|
||||
4. 填入 API Key
|
||||
5. 点击"保存所有设置"
|
||||
|
||||
**优势**：无需重启服务即可生效，支持在线修改配置
|
||||
|
||||
### 自定义 Gemini Base URL（可选）
|
||||
|
||||
如果需要使用 Key 轮训服务或代理（例如提高速度、负载均衡），可以配置自定义 Base URL：
|
||||
|
||||
```env
|
||||
# 使用自定义代理服务
|
||||
GEMINI_BASE_URL=https://your-proxy-service.com/proxy/gemini-self
|
||||
```
|
||||
|
||||
**使用场景**：
|
||||
- Key 轮训（多个 API Key 负载均衡）
|
||||
- 国内加速代理
|
||||
- 自建中转服务
|
||||
|
||||
---
|
||||
|
||||
## 其他 AI 提供商
|
||||
|
||||
### OpenAI (GPT)
|
||||
|
||||
**限制**：⚠️ 仅支持文本解析，PDF 文件会通过文本提取处理，丢失图片和格式信息
|
||||
|
||||
#### 获取 API Key
|
||||
- 访问：https://platform.openai.com/api-keys
|
||||
- 创建新的 Secret Key
|
||||
|
||||
#### 配置
|
||||
```env
|
||||
AI_PROVIDER=openai
|
||||
OPENAI_API_KEY=sk-your-openai-api-key
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
```
|
||||
|
||||
**推荐模型**：
|
||||
- `gpt-4o-mini`（推荐，性价比高）
|
||||
- `gpt-4o`（最强，成本高）
|
||||
- `gpt-3.5-turbo`（便宜，效果一般）
|
||||
|
||||
---
|
||||
|
||||
### Anthropic (Claude)
|
||||
|
||||
**限制**：⚠️ 仅支持文本解析，PDF 文件会通过文本提取处理，丢失图片和格式信息
|
||||
|
||||
#### 获取 API Key
|
||||
- 访问：https://console.anthropic.com/settings/keys
|
||||
- 创建新的 API Key
|
||||
|
||||
#### 配置
|
||||
```env
|
||||
AI_PROVIDER=anthropic
|
||||
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
|
||||
ANTHROPIC_MODEL=claude-3-haiku-20240307
|
||||
```
|
||||
|
||||
**推荐模型**：
|
||||
- `claude-3-haiku-20240307`（推荐，速度快）
|
||||
- `claude-3-5-sonnet-20241022`（最强，成本高）
|
||||
- `claude-3-opus-20240229`（超强，成本很高）
|
||||
|
||||
---
|
||||
|
||||
### Qwen (通义千问)
|
||||
|
||||
**限制**：⚠️ 仅支持文本解析，PDF 文件会通过文本提取处理，丢失图片和格式信息
|
||||
|
||||
#### 获取 API Key
|
||||
- 访问：https://dashscope.console.aliyun.com/apiKey
|
||||
- 使用阿里云账号登录
|
||||
- 创建新的 API Key
|
||||
|
||||
#### 配置
|
||||
```env
|
||||
AI_PROVIDER=qwen
|
||||
QWEN_API_KEY=sk-your-qwen-api-key
|
||||
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
QWEN_MODEL=qwen-plus
|
||||
```
|
||||
|
||||
**推荐模型**：
|
||||
- `qwen-plus`（推荐，平衡）
|
||||
- `qwen-max`（最强，成本高）
|
||||
- `qwen-turbo`（快速，效果一般）
|
||||
- `qwen-long`（超长文本支持）
|
||||
|
||||
---
|
||||
|
||||
## AI 提供商对比表
|
||||
|
||||
| 提供商 | PDF 原生支持 | 图片/表格/公式 | 文本解析 | 免费额度 | 推荐度 |
|
||||
|--------|--------------|----------------|----------|----------|--------|
|
||||
| **Google Gemini** | ✅ 支持 | ✅ 完整保留 | ✅ | ⭐⭐⭐⭐⭐ | 最推荐 |
|
||||
| OpenAI (GPT) | ❌ 不支持 | ❌ 丢失 | ✅ | 💰 | ⭐⭐⭐⭐ |
|
||||
| Anthropic (Claude) | ❌ 不支持 | ❌ 丢失 | ✅ | 💰 | ⭐⭐⭐⭐ |
|
||||
| Qwen (通义千问) | ❌ 不支持 | ❌ 丢失 | ✅ | ✅ | ⭐⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 如何判断 AI 提供商是否配置正确？
|
||||
|
||||
上传一个包含题目的文档，如果能成功解析出题目，说明配置正确。查看后端日志可以看到详细的解析过程。
|
||||
|
||||
### Q2: 可以同时配置多个 AI 提供商吗？
|
||||
|
||||
可以。配置多个提供商的 API Key，通过 `AI_PROVIDER` 环境变量或管理员后台切换使用哪个提供商。
|
||||
|
||||
### Q3: Gemini 原生 PDF 处理和文本提取有什么区别？
|
||||
|
||||
- **原生 PDF 处理**（Gemini）：AI 直接"看"PDF，能识别图片中的文字、理解表格结构、识别数学公式
|
||||
- **文本提取**（其他提供商）：先用 PyPDF2/python-docx 提取纯文本，然后交给 AI，丢失所有图片和格式
|
||||
|
||||
**示例**：如果试卷中有带图的选择题，Gemini 能理解图片内容并提取题目，其他提供商只能提取文字部分。
|
||||
|
||||
### Q4: Gemini 自定义 Base URL 有什么用？
|
||||
|
||||
- **场景一**：使用多个 API Key 的轮训服务，避免单个 Key 频率限制
|
||||
- **场景二**：使用国内加速代理，提高访问速度
|
||||
- **场景三**：自建中转服务，统一管理和监控 API 调用
|
||||
|
||||
**格式要求**：Base URL 应该是完整的域名，例如 `https://your-service.com`，后端会自动拼接 `/v1beta/models/{model}:generateContent`
|
||||
|
||||
### Q5: 如果文档中没有提供答案怎么办？
|
||||
|
||||
QQuiz 会自动使用 AI 生成参考答案，标注为"AI参考答案："。这个功能对所有 AI 提供商都支持。
|
||||
|
||||
---
|
||||
|
||||
## 推荐配置方案
|
||||
|
||||
### 方案一：仅使用 Gemini（推荐）
|
||||
```env
|
||||
AI_PROVIDER=gemini
|
||||
GEMINI_API_KEY=your-key
|
||||
```
|
||||
- ✅ 最佳 PDF 支持
|
||||
- ✅ 免费额度充足
|
||||
- ✅ 配置简单
|
||||
|
||||
### 方案二：Gemini + OpenAI（备用）
|
||||
```env
|
||||
AI_PROVIDER=gemini
|
||||
GEMINI_API_KEY=your-gemini-key
|
||||
OPENAI_API_KEY=your-openai-key
|
||||
```
|
||||
- 主用 Gemini，当遇到限制时手动切换到 OpenAI
|
||||
|
||||
### 方案三：全配置（多选）
|
||||
配置所有提供商，根据需求灵活切换
|
||||
|
||||
---
|
||||
|
||||
**推荐流程**：
|
||||
1. 首次部署：使用 Gemini（免费额度充足）
|
||||
2. 生产环境：使用管理员后台配置，支持在线切换
|
||||
3. 高频使用：配置 Gemini 自定义 Base URL 使用 Key 轮训服务
|
||||
Reference in New Issue
Block a user