🔴 YT导航器

📋 概述

YT导航器是一款基于人工智能的应用程序，可帮助您高效地浏览和搜索YouTube频道内容。无需手动观看数小时的视频来查找特定信息，YT导航器让您可以：

1. 🔍 使用自然语言查询搜索频道内的视频
2. 💬 与频道内容进行对话，根据视频字幕获取答案
3. ⏱️ 发现带有精确时间戳的相关视频片段

非常适合研究人员、学生、内容创作者，以及任何需要快速从YouTube频道中提取信息的人。

✨ 主要功能

• 🔐 身份验证：安全登录与独立会话
• 📺 频道管理：每频道最多扫描100个视频，并生成频道摘要
• 🔍 搜索：使用语义搜索找到相关视频片段
• 💬 对话：与了解频道内容的AI进行交流

1- 📥 频道数据获取

在此步骤中，用户输入YouTube频道URL，系统会先验证该链接的有效性，然后提取频道用户名。接着，系统会获取频道的详细信息，包括标题、描述和头像，并将其存储在数据库中。

连接到频道后，用户可以选择要扫描的视频数量（最多100个）。随后，系统会通过两条路径并行处理这些视频：

1. 📊 提取视频元数据并保存到关系型数据库（PostgreSQL）
2. 📝 提取视频字幕，将其分割成片段，转换为向量嵌入，并存储到向量数据库（PGVector）

当这两个过程完成后，频道内容即可用于搜索和对话功能。

graph TD
    A[用户输入YouTube频道URL] --> B[验证URL]
    B --> C[获取频道详情]
    C --> G[用户选择要扫描的视频数量]
    G --> H[获取视频详情]
    H --> I[处理视频元数据]

    H --> J[提取视频字幕]
    I --> K1[保存到关系型数据库]
    J --> L[分割成视频片段]
    L --> M[生成嵌入]
    M --> K2[添加到向量数据库]
    K1 --> N[频道已准备好用于搜索/聊天]
    K2 --> N

2 - 🔍 查询频道

查询过程始于用户输入自然语言查询，以在整个频道内容中进行搜索。系统会同时通过语义搜索（使用向量嵌入）和关键词搜索（使用BM25）来处理该查询，从而获得全面的结果。这些结果会被合并，结合来自关系型数据库的视频元数据进行丰富，并去除重复项。随后，一个交叉编码模型会根据与查询的相关性对结果重新排序。系统会对相关性得分进行标准化，按视频分组，并返回最相关的视频及其具体的字幕片段。用户界面会显示这些结果，包括视频缩略图、标题、相关字幕片段，以及直接指向视频中出现相关信息的确切时间戳的链接。

graph TD
    A[用户输入自然语言查询] --> D1[执行语义搜索]
    A --> D2[执行关键词搜索]
    D1 --> E[合并搜索结果]
    D2 --> E
    E --> F[获取视频元数据]
    F --> H[去除重复]
    H --> I[重新排序结果]
    I --> J[标准化得分]
    J --> L[返回顶级视频和片段]

3 - 💬 与频道对话

聊天界面通过ReAct框架，促进用户与熟悉频道内容的AI代理之间的互动。当用户发送消息时，系统会通过决策机制确定合适的响应类型。消息可以有三种处理方式：

1. 🔄 直接回复，无需调用工具，适用于一般性问题；
2. ⛔ 静态回复，用于不相关的问题；
3. 🛠️ 工具辅助回复，通过查询向量数据库从视频字幕中提取具体信息。在工具辅助回复的情况下，代理会循环利用其工具（语义搜索和SQL查询执行）来收集信息，然后再生成完整的回答。

这一过程可以有效减少幻觉现象，并允许使用较小的模型来处理复杂任务。

graph TD
    A[__start__] --> B[route_message
    llama-3.1-8b-instant]

    B -.-> C[non_tool_calls_reply
    llama-3.1-8b-instant]
    B -.-> D[static_not_relevant_reply
    llama-3.1-8b-instant]
    B -.-> E[tool_calls_reply
    qwen-qwq-32b]

    subgraph React Agent qwen-qwq-32b
        E1[__start__] --> E2[agent]
        E2 -.continue.-> E3[tools]
        E2 -.end.-> E4[__end__]
        E3 --> E2
    end

    C --> F[__end__]
    D --> F
    E --> F

4. 代理工作流图

🧰 技术栈

• 🖥️ 后端：
  • Django（Python）
  • PostgreSQL
  • Structlog用于日志记录
  • Pydantic用于数据验证
• 🧠 AI与机器学习：
  • LangGraph用于对话式AI
  • Sentence Transformers用于语义搜索
  • PGVector作为向量数据库
  • BM25用于关键词搜索
  • bge-small-en-v1.5用于嵌入
  • qwen-qwq-32b和llama-3.1-8b-instant来自Groq
• ⚙️ 数据处理：
  • Scrapetube用于抓取视频
  • youtube-transcript-api用于获取字幕
• 🎨 前端：
  • Django模板搭配现代CSS
  • 响应式设计

🚀 安装

💻 不使用Docker

1. 克隆仓库

git clone https://github.com/wassim249/YT-Navigator

2. 创建虚拟环境并安装依赖

python -m venv venv
source venv/bin/activate
pip install -e .

3. 确保您已运行PostgreSQL数据库。

4. 在根目录下从.env.example文件创建.env文件。

cp .env.example .env

5. 创建Django迁移并迁移数据库

python manage.py migrate

6. 运行开发或生产服务器

make dev # 用于开发
make prod # 用于生产

🐳 使用 Docker

1. 从 .env.example 文件中在根目录创建一个 .env 文件（请确保将 POSTGRES_HOST 设置为 db）。

cp .env.example .env

2. 构建 Docker 镜像

make build-docker

3. 运行 Docker 容器

make run-docker

📖 使用说明

1. 📝 注册与登录

创建账户即可开始使用。

2. 🔗 连接 YouTube 频道

在首页输入 YouTube 频道的 URL 以进行连接。系统将获取该频道的相关信息。

3. 📥 扫描视频

连接频道后，您可以扫描其视频。选择要扫描的视频数量（视频越多，结果越全面，但处理时间也会更长）。

4. 🔍 搜索信息

使用搜索功能可在所有已扫描的视频中查找特定信息。系统将返回：

• 🎯 带有时间戳的相关视频片段
• 📝 匹配内容的文本转录
• 🔗 可直接跳转到指定时间点观看视频的链接

5. 💬 与频道对话

通过聊天机器人界面，您可以就频道内容进行交流。AI 将根据已扫描视频中的信息作出回应。

👨‍💻 开发

📁 项目结构

• app/: 主 Django 应用程序

  • models/: 数据库模型（频道、视频、视频片段）
  • views/: 用于网页和 API 端点的视图函数
  • services/: 核心功能（抓取、向量数据库、AI 代理）
  • templates/: HTML 模板
  • static/: CSS、JavaScript 等静态文件

• yt_navigator/: Django 项目的设置与配置

🛠️ 使用 Makefile

项目包含一个 Makefile，其中提供了一些实用命令： 运行 make help 查看可用命令。

make help

🗺️ 路线图

• 🐳 添加 Docker 支持
• ✅ 添加测试
• 📋 添加对播放列表/短视频扫描的支持
• 📱 改善移动端体验
• 🌐 添加多语言支持

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

1. 分支仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一项很棒的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

🤵 作者

• wassim249

YT-Navigator 快速上手指南

YT-Navigator 是一款基于 AI 的开源工具，旨在帮助用户高效地导航和搜索 YouTube 频道内容。它支持通过自然语言搜索视频片段、与频道内容进行对话聊天，并能精准定位相关视频的时间戳。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Python: 3.8 或更高版本
• 数据库: PostgreSQL (需已安装并运行，建议安装 pgvector 扩展以支持向量搜索)
• 构建工具: make (可选，用于简化命令执行)
• API Key: 需要准备 Groq API Key (用于调用 Llama 3.1 和 Qwen 模型)

国内开发者提示：

• 建议使用国内镜像源加速 Python 包下载（如清华源或阿里源）。
• 若无法直接访问 HuggingFace 下载嵌入模型 (bge-small-en-v1.5)，请配置国内镜像或使用离线模型文件。

安装步骤

您可以选择直接使用本地环境安装或通过 Docker 部署。

方式一：本地环境安装 (推荐用于开发)

1. 克隆项目仓库

   git clone https://github.com/wassim249/YT-Navigator
   cd YT-Navigator
   

2. 创建虚拟环境并安装依赖 (国内用户建议使用 -i 指定镜像源)

   python -m venv venv
   source venv/bin/activate  # Windows 用户请使用: venv\Scripts\activate
   
   # 使用清华源加速安装
   pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
   

3. 配置环境变量 复制示例配置文件并根据实际情况修改（特别是数据库连接和 Groq API Key）。

   cp .env.example .env
   

   编辑 .env 文件，确保填入正确的 GROQ_API_KEY 和 DATABASE_URL。

4. 初始化数据库 确保 PostgreSQL 服务已启动，然后执行迁移：

   python manage.py migrate
   

5. 启动服务

   make dev
   # 如果没有 make 工具，可直接运行：python manage.py runserver
   

方式二：Docker 部署 (推荐用于生产或快速体验)

1. 配置环境变量

   cp .env.example .env
   

   注意：在 Docker 模式下，请将 .env 中的 POSTGRES_HOST 设置为 db。

2. 构建并运行容器

   make build-docker
   make run-docker
   

   (若无 make 工具，可手动执行 docker-compose up --build)

基本使用

安装完成后，打开浏览器访问 http://127.0.0.1:8000 (默认端口)，按以下步骤操作：

1. 注册与登录

首次使用需创建账号并登录，系统将为您隔离会话数据。

2. 连接 YouTube 频道

在首页输入框中粘贴目标 YouTube 频道的 URL。系统会自动验证并获取频道标题、描述及头像信息。

3. 扫描视频内容

连接成功后，选择需要扫描的视频数量（最多 100 个）。

• 注意：扫描过程包含提取元数据、下载字幕、分段及生成向量嵌入，视频数量越多耗时越长。
• 扫描完成后，频道内容即可被检索。

4. 搜索与对话

• 语义搜索：在搜索框输入自然语言问题（例如："如何配置 Django 数据库？”），系统将返回相关的视频片段、具体时间点及字幕摘要。
• AI 聊天：切换到聊天界面，像与普通 AI 对话一样提问。Agent 会基于已扫描的视频内容回答，并引用具体来源，有效减少幻觉。

更多高级功能（如 Playlist 支持、多语言适配）将在后续版本更新中提供。