hello-agents/Co-creation-projects/aatanxiao12-beep-YingQian

# 映前 (YingQian) — 多智能体电影推荐助手

基于 HelloAgents + TMDB：关灯之前，先把今晚的片定下来。

📝 项目简介

「映前」解决「今晚看什么」的选择困难。用户填写心情、观影对象、类型、时长等偏好后，系统通过 Pipeline + Tool-use 多智能体流水线，从 TMDB 真实片库中检索候选并给出带理由的精选推荐。

• 解决问题：偏好分散、候选太多、容易编造片名
• 特色：三阶段 Agent 协作 + TMDB 工具取真片 + id 白名单校验
• 适用场景：个人/情侣/朋友快速定片；也可当 HelloAgents 多 Agent 编排示例

✨ 核心功能

• 画像 Agent：生成口味摘要与检索线索（TasteProfile）
• 检索 Agent：调用 TMDB discover / search 拉取真实候选
• 推荐 Agent：仅在候选 id 内精选并写中文理由
• 「换一批」：复用画像、排除已出 id
• 片库浏览 / 详情双通道 REST API
• React 前端（品牌「映前」）

🛠️ 技术栈

• HelloAgents：SimpleAgent + Tool（多 Agent 串行 Pipeline）
• 后端：FastAPI、Pydantic、httpx
• 数据源：TMDB API
• 前端：Vite + React + TypeScript
• LLM：OpenAI 兼容接口（如 DeepSeek）

🚀 快速开始

环境要求

• Python 3.10+
• Node.js 18+（可选，跑前端）
• TMDB Access Token 或 API Key
• OpenAI 兼容 LLM（LLM_API_KEY / LLM_BASE_URL / LLM_MODEL_ID）

安装依赖

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
# source .venv/bin/activate

pip install -r ../requirements.txt
pip install jupyterlab   # 若要跑 main.ipynb

配置 API 密钥

必须把 .env 放在 backend/ 目录（代码读取 backend/.env）：

# 在项目根目录 aatanxiao12-beep-YingQian/ 下
cp .env.example backend/.env

# Windows PowerShell
# Copy-Item .env.example backend\.env

编辑 backend/.env，至少填写：

TMDB_ACCESS_TOKEN=你的TMDB_Token
# 或 TMDB_API_KEY=你的Key

LLM_API_KEY=你的LLM密钥
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL_ID=deepseek-v4-flash

方式 A：Jupyter 快速演示（推荐评审）

# 仍在 backend/ 且已激活 venv
cd ..
jupyter lab
# 打开 main.ipynb，按顺序运行单元格

Notebook 会调用完整推荐流水线，打印画像摘要与推荐片单。

方式 B：启动 Web 服务

cd backend
python run.py

• API：http://127.0.0.1:8000
  
• 文档：http://127.0.0.1:8000/docs
  

前端（可选）：

cd frontend
npm install
npm run dev

浏览器打开 http://127.0.0.1:5173

📖 使用示例

1）Notebook 一键推荐

见 main.ipynb。核心调用等价于：

import sys
from pathlib import Path
sys.path.insert(0, str(Path("backend").resolve()))

from app.models.schemas import RecommendRequest
from app.agents.movie_recommender_agent import MultiAgentMovieRecommender

req = RecommendRequest(
    mood="放松",
    party_type="独自",
    genres=["剧情", "喜剧"],
    max_runtime_minutes=120,
    region_preference="不限",
    year_preference="近10年",
    free_text="不要太沉重",
)
result, trace_id = MultiAgentMovieRecommender().recommend(req)
for m in result.movies:
    print(m.title, m.reason)

2）HTTP API

curl -X POST http://127.0.0.1:8000/api/recommend \
  -H "Content-Type: application/json" \
  -d "{\"mood\":\"虐心\",\"party_type\":\"朋友\",\"genres\":[\"爱情\"],\"region_preference\":\"不限\",\"year_preference\":\"近10年\"}"

成功时返回约 5 部电影卡片（含 title、poster_url、reason 等）以及可选的 taste_profile。

3）前端

打开首页 → 填写偏好 → 「开始荐片」→ 结果页查看理由；可「换一批」或去「片库」浏览。

🎯 项目亮点

• 真片约束：检索必须走 TMDB Tool，推荐阶段用候选 id 白名单，降低幻觉片名
• 多 Agent 分工：画像 / 检索 / 推荐职责清晰，便于教学与扩展
• 可降级兜底：检索 Agent 解析失败时可用规则 discover 回退
• 完整产品形态：不仅有 Agent Demo，还有 FastAPI + 前端交互

📊 性能说明（参考）

在 DeepSeek + 本机可访问 TMDB 的环境下，一次完整推荐大约：

阶段	参考耗时
画像 Agent	~5–8s
检索 Agent（含 1 次 discover）	~15–25s
推荐 Agent	~10–15s
合计	约 40–50s

TMDB 本身通常 <2s；主要时间在 LLM。国内网络若连不上 api.themoviedb.org，需代理/VPN。

🔮 未来计划

• 无自由文本时规则化画像，跳过一轮 LLM
• 默认规则 discover，复杂意图再启用检索 Agent
• 短片过滤 / 时长下限等检索质量优化
• 前端进度与真实阶段日志对齐

📂 项目结构

aatanxiao12-beep-YingQian/
├── README.md
├── requirements.txt
├── .env.example
├── .gitignore
├── main.ipynb                 # 快速演示入口
├── backend/
│   ├── .env.example           # 同根目录示例（便于放 backend/.env）
│   ├── app/                   # Agents / Tools / API / TMDB
│   ├── tests/
│   ├── run.py
│   └── pyproject.toml
└── frontend/
    ├── src/
    ├── package.json
    └── ...

🤝 贡献指南

欢迎提出 Issue 和 Pull Request！

📄 许可证

MIT License

👤 作者

• GitHub: @aatanxiao12-beep

🙏 致谢

感谢 Datawhale 社区和 Hello-Agents 项目！