数字调音师

需要先安装 Python 依赖（后续 Step 3 数据导入也需要此环境）

conda create -n music_agent python=3.11 && conda activate music_agent pip install -r requirements.txt

Step 1 中已创建 Conda 环境，安装前端依赖

cd web && npm install && cd ..

🚀 快速开始

Windows 推荐使用统一入口：

.\soultuner.ps1 doctor
.\soultuner.ps1 up lite       # 无 GPU：Neo4j + API + 前端
.\soultuner.ps1 up standard   # 加 GraphZep + SearxNG
.\soultuner.ps1 up full       # 加独立音乐入库 Worker

无外部服务自测：

.\soultuner.ps1 mock

部署档位、端口和在线新歌入库流程见 DEPLOYMENT_PROFILES.md。

部署分为三步：① 前置准备 → ② 选择部署方式启动服务 → ③ 数据导入。

---

Step 1：前置准备（两种部署方式共用）

1.1 音乐数据：将 MP3 文件放入 data/processed_audio/audio/ 目录（路径可在 .env 中自定义）。

1.2 环境变量：

```bash cp .env.example .env

Step 2：选择部署方式

方式 A：Docker Compose（推荐）

后端镜像约 11 GB（含 PyTorch + M2D-CLAP 运行库）。模型权重通过 volume 挂载宿主机缓存，不打包进镜像。 ⚠️ GPU 要求：docker-compose.yml 默认开启 NVIDIA GPU 加速（用于 M2D-CLAP 跨模态推理）。需要宿主机已安装 NVIDIA Container Toolkit。如无 GPU，请注释掉 deploy.resources 段。

```bash

编辑 .env 中的 Docker 专用路径（download_models.py 运行后会输出）：

── Docker 部署需要显式指定 Neo4j 连接地址 ──

── 本地部署已在 .env 中配置，无需额外设置 ──

可选：本地大模型部署（WSL + SGLang）

针对 8GB 显存（如 RTX 4070）设备的优化部署方案，支持本地运行 Qwen3-4B 模型辅助意图识别。

1. 终端A (WSL)：启动大模型推理引擎

   wsl
   bash /path/to/SoulTuner-Agent/scripts/start_sglang.sh
   

1. 终端B (Windows)：在前端设置面板切换为本地模型

• 正常运行 python startup_all.py
• 打开系统设置 ⚙️ → 主提供商选择 sglang → 保存

---

一键启动（Neo4j + GraphZep + Backend + Frontend）

docker compose up -d

★ 实时跟踪后端启动日志（推荐首次启动时使用，可看到预热进度）

docker logs -f soultuner-backend

一键启动所有服务（后端 + 前端 + GraphZep + SearxNG）

python startup_all.py

编辑 .env：至少填入 SiliconFlow_API_KEY 和 NEO4J_PASSWORD

**1.3 模型权重下载**（首次必须，约 **2.4 GB**）：

⚙️ 配置

环境变量

📖 运行时设置面板（LLM 切换 / 检索参数 / RRF 权重等）及 API 端点文档详见 Technical_Report.md

---

前端: http://localhost:3003 | 后端 API: http://localhost:8501 | Neo4j: http://localhost:7474

<details>
<summary>Docker 常用运维命令</summary>

| 命令                                        | 说明                                           |
| ------------------------------------------- | ---------------------------------------------- |
| `docker logs -f soultuner-backend`        | 实时跟踪后端日志                               |
| `docker logs --tail 50 soultuner-backend` | 查看最后 50 行日志                             |
| `docker compose up -d --build backend`    | 代码修改后重新构建并启动后端                   |
| `docker compose restart backend`          | 重启后端（不重新构建）                         |
| `docker compose down`                     | 停止并移除所有容器                             |
| `docker compose down -v`                  | 停止并清除所有数据卷（⚠️ 会删除 Neo4j 数据） |

</details>

#### 方式 B：本地开发（Conda）

> ⚠️ 需先安装并启动 [Neo4j Desktop](https://neo4j.com/download/)，在 `.env` 中配置对应的 `NEO4J_URI` 和 `NEO4J_PASSWORD`。

Agent 工作流

意图识别支持 API 大模型（DeepSeek-V3.2 等）和本地 Qwen3-4B（SGLang 部署）双模式。本地模式下 HyDE 声学描述由独立模块生成。

web_search 意图现在直接路由到 web_fallback 节点（在线音乐 API 实时搜索），不再经过 HybridRetrieval。支持中文原文优先、多级查询词提取和 30s 试听版本检测。

偏好提取为独立 LangGraph 节点 extract_preferences，闲聊意图自动跳过。

下载模型权重（自动检测已有文件并跳过）

python scripts/download_models.py ```

💡 GraphZep 嵌入直接调用 SiliconFlow API (BAAI/bge-m3)，无需预下载。

---

M2D_CLAP_CACHE = M2D-CLAP 模型权重目录

HF_HOME = HuggingFace 模型缓存目录

🚀 开始预加载关键组件...

✅ M2D-CLAP 模型预加载完成 (14.9s)