雷石家用K歌智能助手原型，统一入口同时支持 C端用户互动和 B端业务分析，通过 Agent 编排智能路由到对应知识库和工具。
echo-agent/
├── data/ # 模拟数据
│ ├── device_manual.json # 设备手册 (30条)
│ ├── songs.json # 歌曲库 (55首)
│ └── sales_channel.json # 销售/渠道数据 (32条)
├── src/
│ ├── rag/
│ │ └── knowledge_base.py # ChromaDB 向量知识库 (3个独立库)
│ ├── agent/
│ │ ├── echo_agent.py # 主 Agent 编排（Tool Use + 路由调度）
│ │ ├── c_tools.py # C端工具（设备问诊、图片问诊、选歌推荐）
│ │ └── b_tools.py # B端工具（销售数据查询）
│ └── api/
│ └── app.py # FastAPI 后端
├── templates/
│ └── index.html # Web UI (单页应用，内嵌所有 CSS/JS)
├── main.py # 启动入口
├── pyproject.toml # 项目依赖与工具配置（含 ruff 配置）
└── .env.example
pip install -e .cp .env.example .env
# 编辑 .env，填入你的通义千问 API Key.env 内容：
DASHSCOPE_API_KEY=sk-xxxxxxxx
QWEN_MODEL=qwen-plus
QWEN_VL_MODEL=qwen-vl-max
QWEN_EMBEDDING_MODEL=text-embedding-v3
python main.py服务启动后访问 http://localhost:8000
首次启动会初始化向量知识库（约10-30秒），之后启动直接加载缓存。
| 场景 | 描述 | 工具 |
|---|---|---|
| A | C端设备使用帮助 | search_device_guide |
| B | C端多模态设备问诊（图片上传） | analyze_device_image |
| C | C端智能选歌与练唱推荐 | search_songs |
| D | B端销售与渠道分析 | query_sales_data |
| E | C端+B端复合任务 | 多工具并发调用 |
系统维护 3个独立的 ChromaDB 向量集合：
| 集合名 | 内容 | 条目数 |
|---|---|---|
device_kb |
设备手册（4类设备 × 多问题类型） | 30条 |
song_kb |
歌曲元数据（含难度/场合/风格/练唱标签） | 55首 |
sales_kb |
销售报告、渠道档案、竞品分析 | 32条 |
为何分开而非合并？
- 避免跨域串扰：C端用户问"美视清蓝牙连接"时，不应召回销售退货率数据；B端查询"华南出货"时，不应混入设备手册内容。独立集合让每次检索在语义空间内只与同类文档竞争，Top-K 结果更精准。
- 独立优化：歌曲库需要按难度/场合/风格等多维度检索，设备库需要按设备类型过滤，销售库需要按区域/时间段匹配，各库的 metadata 字段和检索策略可以独立调整。
- 权限隔离：B端销售数据敏感，未来可对
sales_kb单独加访问控制，不影响 C端知识库。
Agent 使用通义千问原生 Function Calling（Tool Use），路由完全由 LLM 自主判断，无需硬编码规则：
- 每个工具的
description字段明确描述适用场景（C端/B端/图片） - 通义千问根据用户意图自动选择调用哪个工具，或同时调用多个工具（复合任务）
finish_reason == "tool_calls"时执行工具并将结果注入对话历史，循环直到stop
这种方式的优势：无需维护意图分类器，LLM 本身的语义理解即是路由引擎，天然支持复合任务的并发工具调用。
是什么：多模态设备问诊工具，接收用户上传的设备截图/报错图片，先用 qwen-vl-max Vision 模型提取图中的错误信息和界面状态，再以提取结果为 query 检索 device_kb，最终给出诊断和解决方案。
解决什么问题：用户遇到设备问题时，往往最直接的反应是截图，而非用文字描述错误码。纯文本 RAG 无法处理图片输入，该工具打通了"图片→文字描述→知识库检索→解答"的完整链路，覆盖需求文档中的场景B（多模态设备问诊）。
为什么选它：
- 场景真实：家用设备用户技术能力有限，截图求助比描述错误更自然
- 技术价值：展示多模态 LLM + RAG 的组合能力，是纯文本 Agent 的重要扩展
- 差异化：竞品（全民K歌、小爱同学）均不具备图片问诊能力
| 挑战 | 解决思路 |
|---|---|
| 中文语义检索质量 | 调用通义千问 text-embedding-v3 API，支持多语言语义检索，无需本地模型 |
| 复合任务工具调用顺序 | 依赖通义千问原生 Function Calling 的多工具调用能力，无需手动编排 |
| 多轮对话上下文 | EchoAgent 维护完整 history 列表，每轮对话追加，模型自动感知上下文 |
| 图片问诊准确性 | 两阶段处理：Vision 提取关键信息 → 以提取文本检索知识库，避免直接用原始图片做向量检索 |
- Python 3.12
- 通义千问 API Key（DASHSCOPE_API_KEY，在阿里云百炼控制台获取）
- 网络连接（调用通义千问 Embedding API，无需下载本地模型）
- 磁盘空间：约 50MB（向量数据库持久化存储）