视频问答平台 (Video QA Platform)

基于 YouTube 视频的智能问答系统，采用 RAG (Retrieval-Augmented Generation) 架构。

🚀 生产环境部署: 查看生产环境部署指南

✨ RapidAPI 集成: 完全绕过 YouTube bot 检测 - 查看 RapidAPI 集成成功报告

✨ 核心功能

🎯 已实现功能

✅ 视频库管理: 添加 YouTube 视频 URL，自动构建知识库
✅ 智能问答: 基于视频内容的语义搜索和 AI 问答
✅ 视频溯源: 提供精确的视频片段引用和时间戳跳转
✅ 多轮对话: 支持上下文理解的连续对话
✅ 限流保护: Redis 限流防止滥用 (3 视频/小时/IP)
✅ Docker 部署: 一键启动所有服务
✅ 多层降级策略: 自动切换最佳数据源

🚀 视频/字幕获取策略 (多层降级)

系统采用智能降级策略，确保最高成功率：

方案 1: RapidAPI (主要 - 推荐) ⭐

✅ 无需 Cookies - 自动认证
✅ 绕过 Bot 检测 - 商业 API 完全避免封禁
✅ 稳定可靠 - SLA 保障
⚠️ 按量计费 - 需要 RapidAPI 订阅

配置:

RAPIDAPI_KEY=your-rapidapi-key
RAPIDAPI_HOST=youtube-media-downloader.p.rapidapi.com

方案 2: YouTube Data API v3 (备用)

✅ 官方 API - 可靠稳定
✅ 免费配额 - 10,000 units/day
❌ 无字幕内容 - 仅元数据

方案 3: yt-dlp + Cookies (次级备用)

✅ 开源免费
⚠️ 需要 Cookies - 需定期更新
⚠️ Bot 检测风险 - 可能失败

方案 4: Whisper API (最终备用)

✅ 总是可用 - 音频转录
❌ 成本高 - OpenAI 转录费用
❌ 速度慢 - 需下载音频

自动降级流程:

RapidAPI → YouTube API → yt-dlp + Cookies → Whisper
   ⭐主要      备用          次级备用        最终备用

技术栈

后端

Framework: FastAPI + Python 3.11
Database: PostgreSQL 15 + pgvector (向量数据库)
Task Queue: Celery + Redis
AI: OpenAI API (Embeddings + GPT-4 + Whisper)
Video:
- RapidAPI YouTube Media Downloader (主要) ⭐
- YouTube Data API v3 (备用)
- yt-dlp (次级备用)

前端

Framework: React 18 + TypeScript
Build Tool: Vite
Styling: Tailwind CSS

基础设施

Container: Docker + Docker Compose
Video Processing: RapidAPI / yt-dlp / youtube-transcript-api
Audio Transcription: OpenAI Whisper API

快速开始

1. 环境准备

确保已安装:

Docker & Docker Compose
Node.js 20+ (开发环境)
Python 3.11+ (开发环境)

2. 配置环境变量

cp .env.example .env

编辑 .env 文件，填入必要的配置：

必需配置:

# OpenAI (必需)
OPENAI_API_KEY=sk-proj-...

# Database (自动配置)
DATABASE_URL=postgresql+asyncpg://admin:gw123123@localhost:5432/video_qa
REDIS_URL=redis://localhost:6379/0

推荐配置 (选择一种):

选项 A: RapidAPI (推荐 - 最佳方案) ⭐

# RapidAPI - 绕过所有 bot 检测，无需 cookies
RAPIDAPI_KEY=your-rapidapi-key  # 从 https://rapidapi.com 获取
RAPIDAPI_HOST=youtube-media-downloader.p.rapidapi.com

选项 B: YouTube Data API (免费备用)

# YouTube Data API v3 (免费但有配额限制)
YOUTUBE_API_KEY=your-youtube-api-key  # 从 Google Cloud Console 获取

选项 C: Cookies (最后备用)

需要手动配置浏览器 cookies (见下文)
容易被 bot 检测
需要定期更新

3. 配置视频获取方案

🌟 方案 A: RapidAPI (推荐 - 零维护)

获取 API Key
- 访问 RapidAPI YouTube Media Downloader
- 订阅计划 (有免费试用)
- 复制 API Key

配置环境变量

RAPIDAPI_KEY=your-api-key-here
RAPIDAPI_HOST=youtube-media-downloader.p.rapidapi.com

优势
- ✅ 无需 Cookies
- ✅ 零维护成本
- ✅ 完全绕过 bot 检测
- ✅ 商业 SLA 保障

详细文档: RAPIDAPI_INTEGRATION_SUCCESS.md

方案 B: YouTube Cookies (备用 - 需维护)

如果已配置 RapidAPI 或 YouTube Data API，可跳过此步骤

🚀 方法 1: 自动从浏览器导出 (推荐)

Windows:

# 从 Edge 导出 (默认)
export_cookies.bat

# 或从 Chrome 导出
export_cookies.bat chrome

Linux/macOS:

# 从 Chrome 导出
python export_cookies.py chrome

# 从 Edge 导出
python export_cookies.py edge

重启容器:

docker-compose restart api celery_worker

方法 2: 手动导出

安装浏览器扩展 EditThisCookie
登录 YouTube，访问任意视频
导出 cookies 为 JSON 格式
保存到 backend/cookies/youtube.json

详细指南:

4. 启动服务

使用 Docker Compose 启动所有服务：

docker-compose up -d

查看服务状态:

docker-compose ps

查看日志:

# 所有服务
docker-compose logs -f

# 特定服务
docker-compose logs -f api
docker-compose logs -f celery_worker

服务地址:

前端: http://localhost:3000
后端 API: http://localhost:8000
API 文档: http://localhost:8000/docs
PostgreSQL: localhost:5432
Redis: localhost:6379

5. 验证部署

访问 http://localhost:3000，你应该看到：

✅ 前端界面加载
✅ 可以添加 YouTube 视频
✅ 视频处理成功（查看日志确认使用了哪个方案）
✅ 可以进行问答

测试视频: dQw4w9WgXcQ (Rick Astley - Never Gonna Give You Up)

开发模式

后端开发

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 复制环境变量
cp .env.example .env

# 启动开发服务器
uvicorn app.main:app --reload

# 启动 Celery worker
celery -A app.tasks.celery_app worker --loglevel=info

前端开发

cd frontend
npm install
npm run dev

项目结构

.
├── backend/
│   ├── app/
│   │   ├── api/              # API 路由
│   │   ├── models/           # 数据模型
│   │   ├── services/         # 业务逻辑
│   │   │   ├── youtube_service.py          # YouTube Data API
│   │   │   ├── rapidapi_youtube_service.py # RapidAPI 集成 ⭐
│   │   │   └── rate_limiter.py             # 限流服务
│   │   ├── tasks/            # Celery 任务
│   │   │   └── indexing.py   # 视频索引管道 (含降级逻辑)
│   │   ├── db/               # 数据库配置
│   │   ├── config.py         # 配置管理
│   │   └── main.py           # 应用入口
│   ├── db/
│   │   └── init.sql          # 数据库初始化
│   ├── cookies/              # YouTube Cookies (可选)
│   ├── docs/                 # 技术文档
│   ├── tests/                # 测试
│   ├── requirements.txt      # Python 依赖
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/       # React 组件
│   │   ├── pages/            # 页面组件
│   │   ├── types/            # TypeScript 类型
│   │   └── main.tsx          # 应用入口
│   ├── package.json          # Node 依赖
│   └── Dockerfile.dev
├── docker-compose.yml        # Docker 编排
├── .env.example              # 环境变量模板
└── README.md                 # 项目文档

架构设计

系统架构图

┌─────────────────────────────────────────┐
│         Frontend (React + TS)           │
│         http://localhost:3000           │
└─────────────────┬───────────────────────┘
                  │
                  ↓
┌─────────────────────────────────────────┐
│      FastAPI Backend (Python)           │
│       http://localhost:8000             │
│                                         │
│  ┌────────────────────────────────┐    │
│  │  视频/字幕获取 (智能降级)      │    │
│  │                                │    │
│  │  1. RapidAPI ⭐ (主要)        │    │
│  │     └─> 无需 cookies          │    │
│  │     └─> 绕过 bot 检测        │    │
│  │                                │    │
│  │  2. YouTube Data API (备用)   │    │
│  │     └─> 官方 API              │    │
│  │     └─> 仅元数据              │    │
│  │                                │    │
│  │  3. yt-dlp + cookies (次级)   │    │
│  │     └─> 需要 cookies          │    │
│  │     └─> 可能被检测            │    │
│  │                                │    │
│  │  4. Whisper (最终备用)        │    │
│  │     └─> 音频转录              │    │
│  │     └─> 成本高但稳定          │    │
│  └────────────────────────────────┘    │
│                                         │
│  ┌────────────────────────────────┐    │
│  │  RAG 问答系统                  │    │
│  │  - 向量搜索 (pgvector)         │    │
│  │  - OpenAI GPT-4                │    │
│  │  - 流式响应                    │    │
│  └────────────────────────────────┘    │
└────────┬────────────────────┬──────────┘
         │                    │
         ↓                    ↓
┌─────────────────┐  ┌─────────────────┐
│   PostgreSQL    │  │  Celery Worker  │
│   + pgvector    │  │  (Background)   │
│   port: 5432    │  │                 │
└─────────────────┘  └─────────────────┘
         │                    │
         ↓                    ↓
┌──────────────────────────────────────┐
│           Redis (Cache)              │
│            port: 6379                │
└──────────────────────────────────────┘

索引管道 (Indexing Pipeline)

离线处理流程，将视频转化为可检索的向量数据：

视频元数据获取 (智能降级)
- RapidAPI → YouTube API → yt-dlp
字幕/转录获取 (智能降级)
- RapidAPI → yt-dlp → youtube-transcript-api → Whisper
文本处理
- 语义分块 (400 tokens/chunk, 50 overlap)
- 向量嵌入 (OpenAI text-embedding-3-small)
- 存储到 pgvector

查询管道 (Query Pipeline)

在线实时处理流程，响应用户提问：

问题 → 向量化
向量 → 相似性搜索 (pgvector)
检索结果 → 构建上下文
上下文 + 问题 → LLM 生成答案
答案 + 视频引用 → 流式返回

API 文档

启动服务后访问: http://localhost:8000/docs

主要接口：

POST /api/videos - 添加视频
GET /api/videos - 获取视频列表
POST /api/chat - 问答 (SSE 流式)
GET /api/conversations/{id} - 获取对话历史

📚 文档导航

🚀 部署文档

DOCKER_DEPLOYMENT_SUCCESS.md - Docker 部署成功报告 ⭐
PRODUCTION_DEPLOYMENT_GUIDE.md - 生产环境部署指南
PRODUCTION_DEPLOYMENT_STATUS.md - 部署状态

📋 其他文档

FINAL_IMPLEMENTATION_SUMMARY.md - 完整实施总结
SYSTEM_STATUS.md - 系统状态
ROLLBACK_SUMMARY.md - Phase 3 回滚总结

开发进度

🎯 成本优化建议

成本对比

方案	成本	成功率	维护成本
RapidAPI	💰 按量	⭐⭐⭐⭐⭐	✅ 零
YouTube API	✅ 免费*	⭐⭐⭐⭐	✅ 零
yt-dlp	✅ 免费	⭐⭐⭐	⚠️ 高
Whisper	💰💰 高	⭐⭐⭐⭐⭐	✅ 零

*免费配额有限

常见问题

Q: RapidAPI 是必需的吗？

A: 不是必需的。系统有多层降级策略，会自动尝试 YouTube API、yt-dlp 等免费方案。但 RapidAPI 提供最高成功率且无需维护。

Q: 如何选择配置方案？

A:

推荐: RapidAPI (零维护，最高成功率)
免费: YouTube API + yt-dlp + cookies (需要维护)
稳定: 同时配置多个方案，自动降级

Q: Cookies 需要多久更新一次？

A: 通常 1-2 周。如果配置了 RapidAPI，则不需要 cookies。

Q: 视频处理失败怎么办？

A:

检查日志查看使用了哪个方案
如果所有方案失败，考虑配置 RapidAPI
查看 DOCKER_DEPLOYMENT_SUCCESS.md 的故障排除部分

贡献指南

Fork 项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
开启 Pull Request

许可证

MIT License

联系方式

项目链接: https://github.com/yourusername/video-qa-platform

最后更新: 2025-10-05 Docker 状态: ✅ 运行中 RapidAPI 状态: ✅ 已集成 测试状态: ✅ 通过

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
.env.example		.env.example
.env.production.example		.env.production.example
.gitignore		.gitignore
CELERY_TASK_FIX.md		CELERY_TASK_FIX.md
CLAUDE.md		CLAUDE.md
COLLECTION_UX_IMPROVEMENTS.md		COLLECTION_UX_IMPROVEMENTS.md
COOKIES_SETUP_REQUIRED.md		COOKIES_SETUP_REQUIRED.md
DEPLOY_TO_PRODUCTION.md		DEPLOY_TO_PRODUCTION.md
DOCKER_DEPLOYMENT_SUCCESS.md		DOCKER_DEPLOYMENT_SUCCESS.md
PHASE3_UX_OPTIMIZATION.md		PHASE3_UX_OPTIMIZATION.md
PHASE4_AUTO_COLLECTION.md		PHASE4_AUTO_COLLECTION.md
PHASE4_COMPLETION.md		PHASE4_COMPLETION.md
PHASE4_MVP_SUMMARY.md		PHASE4_MVP_SUMMARY.md
PRODUCTION_COOKIES_GUIDE.md		PRODUCTION_COOKIES_GUIDE.md
QUICKSTART_DEPLOYMENT.md		QUICKSTART_DEPLOYMENT.md
RAPIDAPI_INTEGRATION_SUCCESS.md		RAPIDAPI_INTEGRATION_SUCCESS.md
RAPIDAPI_SETUP.md		RAPIDAPI_SETUP.md
README.md		README.md
SERVER_COOKIES_UPDATE.md		SERVER_COOKIES_UPDATE.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
export_cookies.bat		export_cookies.bat
export_cookies.py		export_cookies.py
package-lock.json		package-lock.json
package.json		package.json
setup_github.bat		setup_github.bat
start.bat		start.bat
stop_edge.bat		stop_edge.bat
test_youtube_simple.py		test_youtube_simple.py
update_cookies.bat		update_cookies.bat

QLZIX/video-qa-platform

Folders and files

Latest commit

History

Repository files navigation