Agents 项目

包含两个独立的 Agent：媒体下载器 和 内容分析器，基于 Pydantic AI 和 FastMCP 框架构建。

---

📁 项目结构

agents/
├── media_downloader/          # YouTube 搜索、下载、上传 Agent
│   ├── Dockerfile
│   ├── README.md
│   ├── requirements.txt
│   ├── run_api_server.py
│   └── src/server/
│       ├── mcp_server.py      # MCP 工具定义
│       └── api_server.py      # HTTP API 服务器
│
└── content_analyzer/           # Azure Content Understanding 分析 Agent
    ├── Dockerfile
    ├── README.md
    ├── requirements.txt
    ├── run_api_server.py
    └── src/server/
        ├── mcp_server.py      # MCP 工具定义
        └── api_server.py      # HTTP API 服务器

---

🤖 Agent 1: Media Downloader

功能概述

YouTube 视频搜索、下载和云存储上传服务。支持完整的搜索参数、多格式下载（MP3/MP4）、自动上传到 Azure Blob Storage。

处理逻辑

1. search_youtube - 搜索 YouTube 视频

处理流程：

用户输入搜索参数
    ↓
构建 RapidAPI 请求（包含所有搜索参数）
    ↓
调用 YouTube Search API
    ↓
解析响应数据（contents[].video）
    ↓
提取视频信息（ID、标题、频道、描述等）
    ↓
返回格式化的 JSON 结果

调用方式：

REST API:

POST http://localhost:8000/api/v1/search
Content-Type: application/json

{
  "query": "rick roll",
  "limit": 10
}

MCP 调用:

POST http://localhost:8000/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_youtube",
    "arguments": {
      "query": "rick roll",
      "limit": 10,
      "hl": "en",
      "gl": "US",
      "upload_date": "t",
      "type": "v",
      "duration": "s",
      "features": "li;hd",
      "sort": "v"
    }
  }
}

参数说明：

参数	类型	必需	默认值	说明
query	string	✅	-	搜索关键词
next	string	❌	null	分页 token（从上次结果获取）
hl	string	❌	"en"	语言代码
gl	string	❌	"US"	国家代码
upload_date	string	❌	null	上传日期：t=今天, w=本周, m=本月, y=今年
type	string	❌	"v"	内容类型：v=视频
duration	string	❌	null	时长：s=短, m=中, l=长
features	string	❌	null	特性：li=直播, hd=高清（用分号分隔）
sort	string	❌	null	排序：v=观看量, r=评分, d=日期
limit	integer	❌	10	返回结果数量

返回格式：

{
  "success": true,
  "query": "rick roll",
  "count": 10,
  "estimatedResults": "约 1,000,000 个结果",
  "next": "分页token（用于获取下一页）",
  "videos": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "duration": "3:34",
      "views": "1735021573 views",
      "channel": "Rick Astley",
      "description": "视频描述...",
      "thumbnail": "https://..."
    }
  ]
}

2. download_and_upload - 下载并上传

处理流程：

接收 video_id 或 youtube_url
    ↓
提取/验证 video_id
    ↓
调用 RapidAPI 获取下载链接列表
    ↓
根据 format 和 quality 选择最佳媒体流
    ↓
下载媒体文件到临时文件
    ↓
上传到 Azure Blob Storage
    ↓
生成 SAS URL（24小时有效）
    ↓
清理临时文件
    ↓
返回云存储 URL

调用方式：

REST API:

POST http://localhost:8000/api/v1/download
Content-Type: application/json

{
  "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "mp4",
  "quality": "720p"
}

MCP 调用:

{
  "method": "tools/call",
  "params": {
    "name": "download_and_upload",
    "arguments": {
      "video_id": "dQw4w9WgXcQ",
      "format": "mp4",
      "quality": "720p"
    }
  }
}

参数说明：

参数	类型	必需	默认值	说明
youtube_url	string	⚠️	null	YouTube URL（与 video_id 二选一）
video_id	string	⚠️	null	视频 ID（与 youtube_url 二选一）
format	string	❌	"mp4"	格式：mp3 或 mp4
quality	string	❌	"720p"	质量：360p, 720p, 1080p, 1440p, 2160p

媒体流选择逻辑：

• MP3 格式：查找 is_audio=true 的流
• MP4 格式：查找 is_audio=false 且匹配 quality 的流
• 降级策略：如果精确匹配失败，选择第一个匹配格式的流

返回格式：

{
  "success": true,
  "title": "Rick Astley - Never Gonna Give You Up",
  "author": "Rick Astley",
  "format": "mp4",
  "quality": "720p",
  "size_bytes": 26455880,
  "blob_name": "20260123120000_abc12345.mp4",
  "url": "https://dazhi1hao.blob.core.windows.net/media-files/20260123120000_abc12345.mp4?sp=r&st=...&se=...&sig=..."
}

3. search_and_download - 一键搜索下载

处理流程：

调用 search_youtube 搜索视频
    ↓
从结果中选择指定索引的视频
    ↓
调用 download_and_upload 下载并上传
    ↓
合并搜索结果和下载结果
    ↓
返回完整信息

调用方式：

REST API:

POST http://localhost:8000/api/v1/search_and_download
Content-Type: application/json

{
  "query": "rick roll",
  "format": "mp4",
  "quality": "720p",
  "index": 0
}

参数说明：

参数	类型	必需	默认值	说明
query	string	✅	-	搜索关键词
format	string	❌	"mp4"	下载格式
quality	string	❌	"720p"	视频质量
index	integer	❌	0	选择第几个搜索结果（从0开始）

---

🧠 Agent 2: Content Analyzer

功能概述

基于 Azure Content Understanding 的内容分析服务，支持音频、视频、图像的多模态分析，包括转录、摘要、关键帧提取等功能。

处理逻辑

1. analyze_audio - 音频分析

处理流程：

接收音频文件 URL
    ↓
提交分析请求到 Azure CU API（prebuilt-audioSearch）
    ↓
获取 operation_location（异步任务）
    ↓
轮询获取结果（每5秒，最多300秒）
    ↓
提取分析结果：
  - 转录文本（带时间戳）
  - 说话人识别
  - AI 生成的摘要
    ↓
返回格式化的结果

调用方式：

REST API:

POST http://localhost:8001/api/v1/analyze/audio
Content-Type: application/json

{
  "url": "https://dazhi1hao.blob.core.windows.net/media-files/xxx.mp3?sp=r&...",
  "wait_for_result": true
}

MCP 调用:

{
  "method": "tools/call",
  "params": {
    "name": "analyze_audio",
    "arguments": {
      "url": "https://...",
      "wait_for_result": true
    }
  }
}

参数说明：

参数	类型	必需	默认值	说明
url	string	✅	-	音频文件的公开 URL（支持 mp3, wav 等）
wait_for_result	boolean	❌	true	是否等待分析完成（false 时返回 operation_location）

异步模式： 如果 wait_for_result=false，返回：

{
  "success": true,
  "status": "submitted",
  "operation_id": "xxx-xxx-xxx",
  "operation_location": "https://.../analyzerResults/xxx?api-version=2025-11-01"
}

然后使用 get_operation_result 获取结果。

返回格式：

{
  "success": true,
  "analysis": {
    "status": "Succeeded",
    "analyzer": "prebuilt-audioSearch",
    "segments": [
      {
        "kind": "audioVisual",
        "mimeType": "audio/mpeg",
        "time_range": "0.0s - 30.3s",
        "summary": "AI 生成的摘要...",
        "transcript": [
          {
            "speaker": "Speaker 1",
            "time": "0.1s",
            "text": "Mr. Beast exposed...",
            "confidence": 0.954
          }
        ]
      }
    ],
    "usage": {
      "audio_hours": 0.009,
      "tokens": {
        "gpt-4.1-mini-input": 1562,
        "gpt-4.1-mini-output": 103
      }
    }
  }
}

2. analyze_video - 视频分析

处理流程：

接收视频文件 URL
    ↓
提交分析请求（prebuilt-videoSearch）
    ↓
轮询获取结果
    ↓
提取分析结果：
  - 关键帧时间点
  - 转录文本（带说话人）
  - 章节分段
  - AI 生成的摘要
    ↓
返回结果

调用方式：

REST API:

POST http://localhost:8001/api/v1/analyze/video
Content-Type: application/json

{
  "url": "https://.../video.mp4?sp=r&...",
  "wait_for_result": true
}

返回格式：

{
  "success": true,
  "analysis": {
    "status": "Succeeded",
    "analyzer": "prebuilt-videoSearch",
    "segments": [
      {
        "kind": "audioVisual",
        "mimeType": "video/x-m4v",
        "time_range": "0.7s - 43.2s",
        "resolution": "1080x608",
        "summary": "视频摘要...",
        "transcript": [...],
        "keyframes": {
          "count": 44,
          "times": ["0.7s", "2.1s", ...]
        }
      }
    ],
    "usage": {
      "video_hours": 0.013,
      "tokens": {...}
    }
  }
}

3. analyze_image - 图像分析

处理流程：

接收图像文件 URL
    ↓
提交分析请求（prebuilt-imageSearch）
    ↓
轮询获取结果
    ↓
提取图像描述和摘要
    ↓
返回结果

调用方式：

REST API:

POST http://localhost:8001/api/v1/analyze/image
Content-Type: application/json

{
  "url": "https://.../image.jpg",
  "wait_for_result": true
}

4. analyze_content - 自动检测并分析

处理流程：

接收媒体文件 URL
    ↓
根据文件扩展名自动检测类型：
  - .mp3, .wav, .m4a → audio
  - .mp4, .m4v, .mov → video
  - .jpg, .png, .gif → image
    ↓
调用对应的分析器
    ↓
返回结果

调用方式：

REST API:

POST http://localhost:8001/api/v1/analyze
Content-Type: application/json

{
  "url": "https://.../file.mp3",
  "content_type": "auto"  // 或 "audio", "video", "image"
}

5. get_operation_result - 获取异步结果

处理流程：

接收 operation_location URL
    ↓
轮询获取分析结果
    ↓
返回格式化的结果

调用方式：

REST API:

POST http://localhost:8001/api/v1/result
Content-Type: application/json

{
  "operation_location": "https://.../analyzerResults/xxx?api-version=2025-11-01"
}

---

🚀 启动方式

本地启动

# Media Downloader (端口 8000)
cd media_downloader
pip install -r requirements.txt
python run_api_server.py

# Content Analyzer (端口 8001)
cd content_analyzer
pip install -r requirements.txt
python run_api_server.py

Docker 启动

# 构建镜像
cd media_downloader
docker build -t media-downloader:latest .

cd ../content_analyzer
docker build -t content-analyzer:latest .

# 运行容器
docker run -d -p 8000:8000 media-downloader:latest
docker run -d -p 8001:8001 content-analyzer:latest

---

📡 API 端点总览

Media Downloader (端口 8000)

端点	方法	说明
/	GET	服务信息
/health	GET	健康检查
/mcp	POST	MCP HTTP 端点
/mcp/sse	GET/POST	MCP SSE 端点
/api/v1/search	POST	搜索视频
/api/v1/download	POST	下载并上传
/api/v1/search_and_download	POST	一键搜索下载

Content Analyzer (端口 8001)

端点	方法	说明
/	GET	服务信息
/health	GET	健康检查
/mcp	POST	MCP HTTP 端点
/mcp/sse	GET/POST	MCP SSE 端点
/api/v1/analyze	POST	自动分析
/api/v1/analyze/audio	POST	音频分析
/api/v1/analyze/video	POST	视频分析
/api/v1/analyze/image	POST	图像分析
/api/v1/result	POST	获取异步结果

---

🔄 完整工作流程示例

场景：搜索、下载并分析视频

# 1. 搜索视频
curl -X POST http://localhost:8000/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python tutorial", "limit": 5}'

# 2. 下载并上传到云存储
curl -X POST http://localhost:8000/api/v1/download \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "dQw4w9WgXcQ",
    "format": "mp4",
    "quality": "720p"
  }'

# 3. 使用返回的 URL 分析视频内容
curl -X POST http://localhost:8001/api/v1/analyze/video \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://dazhi1hao.blob.core.windows.net/media-files/xxx.mp4?sp=r&...",
    "wait_for_result": true
  }'

一键操作

# 搜索并下载（自动上传到云存储）
curl -X POST http://localhost:8000/api/v1/search_and_download \
  -H "Content-Type: application/json" \
  -d '{
    "query": "python tutorial",
    "format": "mp4",
    "quality": "720p",
    "index": 0
  }'

# 返回结果包含云存储 URL，可直接用于内容分析

---

⚙️ 配置说明

环境变量（从环境变量读取）

变量	必需	默认值	说明
OPENAI_BASE_URL	否	LiteLLM Gateway URL	LLM Gateway URL
LITELLM_GATEWAY_URL	否	同上	兼容变量名
OPENAI_API_KEY	否	sk	LLM API Key
LITELLM_MODEL	否	taiji/gpt-4o-mini	模型名称
API_PORT	否	8000/8001	服务端口

硬编码配置

以下配置已硬编码在代码中：

• RapidAPI Key: 已配置（YouTube 搜索下载）
• Azure Storage: 已配置（账户：dazhi1hao，容器：taijiagnetsp）
• Azure Content Understanding: 已配置（端点：taijiagnet.cognitiveservices.azure.com）

---

📝 错误处理

所有工具返回统一的 JSON 格式：

成功：

{
  "success": true,
  "data": {...}
}

失败：

{
  "success": false,
  "error": "错误描述"
}

---

🔗 相关链接

• Azure Content Understanding 文档
• RapidAPI YouTube Search