Data_Source/PROJECT_OVERVIEW.md

项目总览

项目结构

.
├── api.py                          # FastAPI主服务（搜索、创作指导、AI分析、Agent）
├── ai_analyzer.py                  # AI分析核心模块
├── ai_agent.py                     # AI Agent智能代理模块 ⭐
├── test_ai_analysis.py             # AI功能测试脚本
├── test_agent.py                   # Agent测试脚本 ⭐
├── requirements.txt                # Python依赖包
├── .env.example                    # 环境变量示例
├── .env                           # 环境变量配置（需自行创建）
├── .gitignore                     # Git忽略文件
├── QUICKSTART.md                  # 快速开始指南
├── README_AI.md                   # AI功能详细文档
├── README_AGENT.md                # Agent功能详细文档 ⭐
├── PROJECT_OVERVIEW.md            # 本文件
│
├── prompts/                       # 提示词目录
│   ├── analyze_prompt.md         # 数据分析提示词
│   └── agent_prompt.md           # Agent系统提示词 ⭐
│
├── douyin_data_soupce/           # 数据源模块
│   ├── douyin_search_crawler.py          # 搜索爬虫
│   ├── douyin_creative_guidance_playwright.py  # 创作指导爬虫
│   ├── douyin_cookie.json                # Cookie配置
│   └── douyin_data/                      # 数据存储目录
│       ├── douyin_creative_guidance_*.json
│       └── douyin_search_*.json
│
└── douyin_data/                  # 额外数据目录
    └── *.json

核心功能

1. 数据抓取

• 搜索爬虫: 根据关键词搜索抖音视频
• 创作指导爬虫: 抓取抖音创作指导页面的热门视频

2. API接口

• POST /api/search - 搜索抖音视频
• POST /api/creative-guidance - 获取创作指导数据
• POST /api/analyze - AI分析视频数据
• POST /api/analyze-file - AI分析JSON文件
• POST /api/agent - AI智能代理（推荐）

3. AI分析

• 使用阿里云百炼大模型
• 支持自定义提示词
• 多维度数据分析（内容趋势、互动数据、创作者分析等）

4. AI Agent（新功能）⭐

• 自主决策: 理解用户意图，自动选择工具
• 函数调用: 支持多轮工具调用
• 提示词驱动: 通过修改提示词控制行为
• 工具扩展: 轻松添加新工具

技术栈

• Web框架: FastAPI
• 爬虫: Playwright
• AI模型: 阿里云百炼（DashScope）
• 数据格式: JSON, CSV, TXT
• 环境管理: python-dotenv

使用流程

推荐流程（使用AI Agent）⭐

1. 配置环境
   ├── 安装依赖: pip install -r requirements.txt
   ├── 配置Cookie: douyin_data_soupce/douyin_cookie.json
   └── 配置API Key: .env

2. 使用AI Agent（一步到位）
   ├── 方式1: API接口
   │   └── POST /api/agent
   │       └── {"query": "帮我分析一下游戏类视频的热门趋势"}
   ├── 方式2: 命令行
   │   └── python ai_agent.py --query "分析游戏类视频"
   └── 方式3: 测试脚本
       └── python test_agent.py

3. Agent自动完成
   ├── 理解用户意图
   ├── 选择工具获取数据
   ├── 分析数据
   └── 给出总结和建议

传统流程（手动控制）

1. 配置环境
   ├── 安装依赖: pip install -r requirements.txt
   ├── 配置Cookie: douyin_data_soupce/douyin_cookie.json
   └── 配置API Key: .env

2. 抓取数据
   ├── 方式1: API接口
   │   └── POST /api/creative-guidance
   └── 方式2: 命令行
       └── python douyin_data_soupce/douyin_creative_guidance_playwright.py

3. AI分析
   ├── 方式1: API接口
   │   ├── POST /api/analyze (直接传数据)
   │   └── POST /api/analyze-file (分析文件)
   ├── 方式2: 命令行
   │   └── python ai_analyzer.py --file xxx.json
   └── 方式3: Python代码
       └── from ai_analyzer import AIAnalyzer

4. 查看结果
   ├── API返回JSON
   ├── 命令行输出
   └── 保存到文件

配置说明

1. Cookie配置 (douyin_data_soupce/douyin_cookie.json)

用于抖音登录认证，格式：

[
  {
    "name": "cookie_name",
    "value": "cookie_value",
    "domain": ".douyin.com",
    "path": "/"
  }
]

2. 环境变量 (.env)

# 阿里云百炼API Key
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx

# 使用的模型（可选）
DASHSCOPE_MODEL=qwen-plus

3. 提示词 (prompts/analyze_prompt.md)

自定义AI分析的提示词，控制分析的维度和输出格式。

API使用示例

1. 抓取游戏类创作指导

curl -X POST "http://localhost:8001/api/creative-guidance" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "游戏",
    "headless": true
  }'

2. AI分析数据

curl -X POST "http://localhost:8001/api/analyze-file" \
  -H "Content-Type: application/json" \
  -d '{
    "json_file": "douyin_data_soupce/douyin_data/douyin_creative_guidance_游戏_20260107_112545.json",
    "custom_instruction": "重点分析爆款视频特征"
  }'

命令行使用示例

1. 抓取数据

# 抓取游戏分类
python douyin_data_soupce/douyin_creative_guidance_playwright.py \
  --category 游戏 \
  --cookie douyin_data_soupce/douyin_cookie.json

# 手动模式（需要手动登录）
python douyin_data_soupce/douyin_creative_guidance_playwright.py \
  --category 游戏 \
  --manual

2. AI分析

# 分析JSON文件
python ai_analyzer.py \
  --file douyin_data_soupce/douyin_data/douyin_creative_guidance_游戏_20260107_112545.json

# 使用自定义提示词
python ai_analyzer.py \
  --file xxx.json \
  --prompt prompts/analyze_prompt.md \
  --instruction "重点分析互动率"

# 保存结果
python ai_analyzer.py \
  --file xxx.json \
  --output analysis_result.txt

数据格式

视频数据结构

{
  "page_url": "https://...",
  "category": "游戏",
  "crawl_time": "2026-01-07T11:25:45",
  "total_videos": 50,
  "videos": [
    {
      "index": 1,
      "author": "作者名",
      "description": "视频描述",
      "authorLink": "作者链接",
      "duration": "03:25",
      "hot": "98.5万",
      "plays": "150万",
      "likes": "8.5万",
      "comments": "3200",
      "hotWords": ["热词1", "热词2"],
      "hashTags": ["#标签1", "#标签2"]
    }
  ]
}

AI分析结果结构

{
  "success": true,
  "analysis": "分析结果文本...",
  "model": "qwen-plus",
  "video_count": 50,
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 1500,
    "total_tokens": 6500
  }
}

支持的分类

• 全部
• 美食
• 旅行
• 泛生活
• 汽车
• 科技
• 游戏
• 二次元

支持的AI模型

• qwen-turbo - 快速响应
• qwen-plus - 平衡性能（推荐）
• qwen-max - 最强性能
• qwen-long - 超长文本

注意事项

1. Cookie有效期: Cookie会过期，需要定期更新
2. API限流: 注意抖音和阿里云的API调用频率限制
3. Token消耗: AI分析会消耗Token，注意成本控制
4. 数据隐私: 敏感数据请谨慎使用云端API
5. 浏览器依赖: 首次使用需要安装Playwright浏览器

快速开始

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

# 2. 安装Playwright浏览器
playwright install chromium

# 3. 配置环境
cp .env.example .env
# 编辑 .env 填入API Key

# 4. 测试AI功能
python test_ai_analysis.py

# 5. 启动API服务
python api.py

文档索引

• 快速开始 - 5分钟上手指南
• AI功能详解 - AI分析功能完整文档
• AI Agent详解 - AI智能代理完整文档 ⭐
• API文档 - 启动服务后访问

获取帮助

• 查看命令行帮助: python ai_analyzer.py --help
• 查看API文档: 启动服务后访问 /docs
• 测试功能: python test_ai_analysis.py