基于 LangGraph + MCP的智能音乐推荐 Agent：从意图到可解释推荐的全链路实践

想要有实力
0 阅读5分钟

摘要（导语）

我自己做了一个开源的智能音乐推荐 Agent，基于 LangGraph 工作流与硅基流动 LLM，提供自然语言多维度音乐推荐（心情/场景/流派/相似歌曲等），前端采用 Streamlit，开箱即用。文章将从架构、核心流程、关键模块到部署与扩展（含 MCP/Spotify 集成）进行系统讲解，并给出可直接运行的示例代码与配置模板。

  • 关键词：音乐推荐、LangGraph、大模型应用、硅基流动、Streamlit、MCP
  • 适读人群：AI 应用开发者、推荐系统从业者、原型/课题研究人员
  • 项目地址：https://github.com/imagist13/Muisc-Research

求求大家为我的仓库点个star，我之后会不断更新该项目，同时也期待大家提交PR。

屏幕截图 2025-11-10 164711.png

一个基于AI的智能音乐推荐系统，使用LangGraph构建，支持自然语言交互和个性化推荐。
🎯 智能理解心情、场景、流派等需求，一键生成推荐歌单
🔍 集成搜索、推荐与解释，让你知道每首歌的推荐理由
⚙️ 基于 LangGraph + Streamlit，轻量部署即可运行
🔐 支持自定义 LLM（DeepSeek、Qwen 等）与本地音乐数据

目录

  • 一、项目简介
  • 二、快速上手（5 分钟跑通）
  • 三、系统架构
  • 四、核心流程（从意图到结果）
  • 五、关键模块详解
  • 六、示例代码（启动与 API 调用）
  • 七、进阶能力：MCP/Spotify 集成
  • 八、测试与故障排查
  • 九、性能与演进方向
  • 十、开源信息与参考资料
  • 附录：setting.json 最小配置模板

一、项目简介

  • 项目定位：一个能“听懂你”的音乐推荐 Agent。支持心情、场景、流派、艺术家、相似歌曲等多维度推荐，并输出可解释理由。

屏幕截图 2025-11-10 160341.png

  • 技术选型：

    • LangGraph + LangChain：工作流编排与 LLM 应用框架
    • 硅基流动（SiliconFlow）：DeepSeek/Qwen 等模型服务
    • Streamlit：轻量 Web UI
    • Python + asyncio + Pydantic：后端与数据校验

  • 使用场景：原型开发、A/B 测试、课程/分享 Demo、课题研究。

二、快速上手（5 分钟跑通）

# 1. 克隆并进入目录
git clone <your-repo-url>
cd deep-search

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

# 3. 添加配置（见文末 setting.json 模板）
# 4. 启动 Web 应用
python run_music_app.py

启动后访问：http://localhost:8501

常见交互示例：

  • “我现在心情很好，推荐一些开心的音乐”
  • “适合运动时听的音乐”
  • “搜索周杰伦的歌曲”
  • “有没有类似《晴天》的歌曲”

屏幕截图 2025-11-10 160610.png

三、系统架构

  • 插图位（建议：系统组件架构图）
    • 建议包含：User、Streamlit UI、Agent（LangGraph）、LLM（SiliconFlow）、Tools、本地数据源或外部音乐 API

模块划分：

  • config/：配置加载（支持 setting.json 与环境变量）
  • llms/：LLM 抽象与硅基流动实现（OpenAI 兼容）
  • graphs/：音乐推荐工作流图与状态管理
  • prompts/：提示词
  • tools/：音乐工具与 MCP 适配
  • music_agent.py：Agent 主入口
  • music_app.py：Streamlit 前端
  • data/music_database.json：本地数据（可替换实际 API）

四、核心流程（从意图到结果）

  • 插图位（建议：流程图/时序图）
    1. 用户输入自然语言
    2. 意图识别 analyze_intent
    3. 意图路由 route_by_intent
      • search / recommend_by_mood / recommend_by_activity / recommend_by_genre / recommend_by_artist / general_chat
    4. 分支节点处理：搜索/推荐/聊天
    5. 生成可解释结果（推荐理由/结构化 JSON）
    6. Web 展示与交互

五、关键模块详解

  • 配置管理 config/settings_loader.py
    • 优先从 setting.json 读取，回退到环境变量
    • 统一注入 API Key、Base URL、默认模型等
  • LLM 封装 llms/siliconflow_llm.py
    • 使用 OpenAI 兼容客户端 + 硅基流动 Base URL
    • 便于更换模型或供应商，业务侧零侵入
  • 工作流 graphs/music_graph.py
    • 定义状态、节点与路由；将“意图理解 → 任务执行 → 结果生成”模块化
  • 工具层 tools/
    • 搜索、相似度、推荐引擎能力
    • MCP 适配（后续对接外部 API/工具）
  • 前端 music_app.py
    • 输入 + 结果卡片/列表 + 理由
    • 侧边栏快捷按钮（心情/场景/流派）

屏幕截图 2025-11-10 173942.png

六、示例代码（启动与 API 调用）

  • 启动脚本片段（自动检查环境变量并启动 Streamlit）：
# run_music_app.py（节选）
def main():
    print("=" * 60)
    print("🎵 音乐推荐Agent - 启动中...")
    print("=" * 60)
    if not check_env():
        sys.exit(1)

    print("\n正在启动Streamlit应用...")
    print("访问地址: http://localhost:8501")
    subprocess.run([
        sys.executable, "-m", "streamlit", "run", "music_app.py",
        "--server.headless=true"
    ])
  • Python API 使用：
import asyncio
from music_agent import MusicRecommendationAgent

async def main():
    agent = MusicRecommendationAgent()
    result = await agent.get_recommendations("我现在心情很好，推荐一些开心的音乐")
    print(result["response"])

    search_result = await agent.search_music("周杰伦", genre="流行")
    for song in search_result["results"]:
        print(f"{song['title']} - {song['artist']}")

asyncio.run(main())

七、进阶能力：MCP/Spotify 集成

  • MCP Server（示例位于 mcp/）
    • siliconflow_server.py：将硅基流动能力以 MCP 工具暴露
    • music_server_updated_2025.py：更完整的音乐工具集合
  • 对接 Spotify/网易云（规划/可行性）
    • 使用官方 API 获取检索/音频特征/艺人画像
    • 将检索与相似度计算外包给外部服务，提升覆盖与准确率

屏幕截图 2025-11-10 160502.png

八、测试与故障排查

  • 建议测试项：
    • 意图识别正确率（多样化输入）
    • JSON 输出校验（字段/类型/长度）
    • 超时与重试策略、网络异常处理
  • 常见问题：
    • 未设置 SILICONFLOW_API_KEY：请在 setting.json 或环境变量中配置
    • Streamlit 启动失败：尝试 streamlit run music_app.py
    • 返回格式不规范：检查提示词或在工作流增加 JSON 清洗步骤

九、性能与演进方向

  • 性能优化：
    • 模型/温度/上下文裁剪
    • 缓存与去重（相同意图/相似请求）
    • 前端分页与懒加载
  • 可演进方向：
    • 实时对接音乐 API（检索/音频特征）
    • 播放与歌单管理
    • 长期偏好学习（向量检索 + 反馈闭环）
    • 多模态信号（封面图、歌词情感分析）
    • 子图/策略拆分与多模型协同

十、开源信息与参考资料

  • 许可证：MIT
  • 主要依赖：LangGraph、LangChain、openai/兼容客户端、Streamlit、Pydantic、asyncio
  • 参考：
    • LangGraph 官方文档
    • 硅基流动 API 文档
    • Streamlit 文档
    • Spotify/网易云开放平台文档（如需）

附录：setting.json 最小配置模板

{
  "SILICONFLOW_API_KEY": "",
  "SILICONFLOW_BASE_URL": "https://api.siliconflow.cn/v1",
  "SILICONFLOW_CHAT_MODEL": "Qwen/Qwen2.5-72B-Instruct",
  "TAILYAPI_API_KEY": "",
  "TAILYAPI_BASE_URL": "https://api.tavily.com",
  "APP_NAME": "DeepSearch Quickstart",
  "SPOTIFY_CLIENT_ID": "",
  "SPOTIFY_CLIENT_SECRET": ""
}

文末 CTA

如果你对“能听懂你”的音乐推荐系统感兴趣，欢迎 Star、Fork 与交流。也欢迎在评论区分享你的使用体验或改进建议，一起把这个 Agent 打磨成可落地、可扩展的高质量 AI 应用。 Githup仓库地址：github.com/imagist13/M…

avatar
文章
阅读
粉丝