Live-agent 是一个基于 FastAPI、LangGraph、Milvus 和 MCP 工具服务的智能体平台，支持普通对话、RAG 知识库问答、文件入库、工具调用、流式输出和前端可视化交互。
- Python 3.11+
- Node.js 20+
- Docker 和 Docker Compose
- DashScope API Key
项目依赖的主要外部服务包括：
- Milvus：向量数据库
- etcd：Milvus 元数据依赖
- MinIO：Milvus 对象存储依赖
- MCP 工具服务：日志、监控、天气、汇率
根目录需要 .env 文件，至少配置以下内容：
DASHSCOPE_API_KEY=你的 DashScope API Key
DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
DASHSCOPE_MODEL=qwen3.6-plus
MILVUS_HOST=milvus
MILVUS_PORT=19530
RAG_TOP_K=3
CHUNK_MAX_SIZE=800
ENABLE_RERANK=true
RERANK_MODEL=gte-rerank-v2
RERANK_MAX_CANDIDATES=60
RERANK_SCORE_THRESHOLD=0.3
RERANK_TIMEOUT=10.0
DEBUG=true在项目根目录执行：
docker compose up -d --build启动后常用访问地址：
后端 API: http://localhost:9900
后端文档: http://localhost:9900/api/docs
前端页面: http://localhost:9910
Milvus Attu: http://localhost:8000
主要容器端口：
app 9900
frontend 9910
log-server 8003
monitor-server 8004
weather-server 8005
exchange-server 8006
milvus 19530, 9091
attu 8000
停止服务：
docker compose down后端：
- FastAPI：HTTP API 服务
- Uvicorn：ASGI 运行服务
- Pydantic / pydantic-settings：请求响应模型和环境配置
- LangChain：LLM、Document、Tool 等智能体基础组件
- LangGraph：Agent 状态图、ReAct、Plan-Execute 流程编排
- DashScope：大模型、Embedding、Rerank 能力
- OpenAI Python SDK：通过 DashScope 兼容 OpenAI 格式接口调用模型和向量化
- Milvus / pymilvus：向量数据库和向量检索
- rank-bm25：BM25 关键词检索
- FastMCP：MCP 工具服务
- sse-starlette：流式 SSE 输出
- Loguru：日志
前端：
- Vue 3：前端 UI 框架
- Vite：前端开发和构建工具
- Nginx：容器内静态资源服务和反向代理
基础设施：
- Docker / Docker Compose：本地编排后端、前端、MCP、Milvus、etcd、MinIO、Attu
- etcd：Milvus 元数据存储
- MinIO：Milvus 对象存储
- Attu：Milvus Web 管理界面
- 智能对话：支持普通问答、工具调用问答和知识库问答。
- 流式输出：
/api/chat/stream通过 SSE 返回思考过程、工具调用结果和最终答案。 - RAG 知识库：支持上传文档、解析文档、切分文本、生成向量、写入 Milvus、检索相关片段。
- 混合检索：支持向量检索 + BM25 关键词检索，并通过 RRF 融合排序。
- Rerank：对召回文档进行相关性重排序，并可按阈值过滤低相关内容。
- MCP 工具调用：支持日志查询、指标查询、天气查询、汇率查询和货币换算。
- Agent 执行模式：支持智能路由、ReAct、Plan-Execute。
- 会话管理：维护会话消息、上下文和状态。
- 前端交互：提供聊天、文件上传、知识库结果、工具调用过程等可视化展示。
上传文件
-> parser_service 解析 PDF / Word / TXT / Markdown / JSON
-> splitter_service 切分文本块
-> embedding_service 调用 DashScope 生成向量
-> vector_store_manager / milvus_client 写入 Milvus
-> index_service 清理 BM25 缓存
-> 后续检索时重新构建或使用 BM25 索引
用户提问
-> chat API 接收请求
-> agent_service 根据 mode 选择执行方式
-> smart_route 判断使用普通回答、ReAct 或 Plan-Execute
-> 需要知识库时调用 retrieve_knowledge
-> 需要外部能力时调用 MCP 工具
-> RAG 检索返回相关文档片段
-> 可选 Rerank 过滤和排序
-> LLM 生成答案
-> 返回最终答案和执行 trace
用户复杂问题
-> planner 生成步骤计划
-> executor 执行当前步骤
-> replan 判断 continue / replan / respond
-> 循环直到任务完成
-> respond 生成最终回答
后端读取 MCP 服务配置
-> mcp_client 创建 MultiServerMCPClient
-> 加载各 MCP Server 暴露的工具
-> Agent 根据问题选择工具
-> MCP Server 执行查询
-> 工具结果返回给 Agent
-> Agent 汇总生成回答
RAG 是 Retrieval-Augmented Generation，即检索增强生成。项目不会只依赖模型自身知识回答，而是先从知识库检索相关文档片段，再把片段作为上下文交给大模型生成答案。
本项目的 RAG 核心模块：
app/services/parser_service.py：文档解析app/services/splitter_service.py：文本切分app/services/embedding_service.py：向量生成app/services/index_service.py：入库索引app/core/vector_store_manager.py：向量写入和检索封装app/core/milvus_client.py：Milvus 连接和 Collection 管理app/tools/knowledge_tool.py：Agent 使用的知识库检索工具
向量检索会把用户问题和文档片段转换成 Embedding 向量，然后在 Milvus 中查找语义距离最近的内容。它适合处理同义表达、语义相近但关键词不完全一致的问题。
项目默认 Embedding 配置：
embedding_model = text-embedding-v4
embedding_dim = 1024
BM25 是经典关键词检索算法，适合处理精确词命中、编号、术语、专有名词等场景。它和向量检索互补：
- 向量检索更擅长语义相似。
- BM25 更擅长关键词匹配。
本项目通过 rank-bm25 构建 BM25 索引，相关逻辑在：
app/core/hybrid_retriever.py
混合检索会同时执行：
向量检索 + BM25 关键词检索
然后使用 RRF（Reciprocal Rank Fusion）融合排序。RRF 不是简单相加原始分数，而是根据不同检索结果中的排名进行融合，减少不同检索算法分数尺度不一致的问题。
默认权重来自配置：
vector_weight = 0.6
bm25_weight = 0.4
rrf_k = 60
Rerank 用于对初步召回的候选文档再次排序。向量检索和 BM25 负责“召回更多可能相关的内容”，Rerank 负责“从候选内容中选出更相关的内容”。
项目中 Rerank 使用 DashScope 文本重排序接口，相关逻辑在：
app/services/reranker_service.py
默认配置：
ENABLE_RERANK=true
RERANK_MODEL=gte-rerank-v2
RERANK_MAX_CANDIDATES=60
RERANK_SCORE_THRESHOLD=0.3
RERANK_TIMEOUT=10.0
ReAct 是 Reasoning + Acting 的智能体模式。模型会边推理边决定是否调用工具，例如知识库检索、天气查询、汇率查询等。
在本项目中，ReAct 适合相对直接的问题，例如：
- 查询知识库内容
- 查询天气
- 查询汇率
- 查询日志或指标
Plan-Execute 适合更复杂的问题。它会先生成计划，再逐步执行，并在每一步后判断是否继续、重规划或直接回答。
核心模块：
app/agent/plan_executor/planner.py
app/agent/plan_executor/executor.py
app/agent/plan_executor/replan.py
app/agent/plan_executor/state.py
MCP 用于把外部能力封装成工具服务。本项目将日志、监控、天气、汇率拆成独立 MCP Server，后端 Agent 通过 MCP Client 动态加载工具。
当前 MCP 服务：
log-server 日志查询
monitor-server 指标/监控查询
weather-server 天气查询，数据源 Open-Meteo
exchange-server 汇率查询和货币换算
项目通过 SSE 返回流式对话结果，前端可以实时展示：
- 模型正在思考
- 正在调用哪个工具
- 工具返回了什么结果
- 最终答案内容
相关接口：
POST /api/chat/stream
前端使用 Vue 3 + Vite：
frontend/src/App.vue
frontend/src/main.js
frontend/src/styles.css
前端负责展示聊天界面、工具调用轨迹、知识库检索结果、汇率/天气等结构化结果，以及与后端 API 的交互。
project/
|-- app/ # FastAPI 后端主应用
| |-- main.py # 后端入口，创建 FastAPI 应用，注册路由和生命周期逻辑
| |-- config.py # 应用配置，统一读取 .env 和环境变量
| |-- __init__.py
| |
| |-- api/ # HTTP 接口层
| | |-- chat.py # 聊天接口
| | |-- file.py # 文件上传和文档处理接口
| | |-- health.py # 健康检查接口
| | |-- mcp.py # MCP 工具相关接口
| | |-- milvus.py # Milvus/知识库管理接口
| | `-- __init__.py
| |
| |-- services/ # 业务服务层
| | |-- agent_service.py # Agent 对话和执行服务
| | |-- embedding_service.py # 向量化服务
| | |-- index_service.py # 文档入库和索引服务
| | |-- llm_factory.py # LLM 创建和适配
| | |-- parser_service.py # 文档解析服务
| | |-- reranker_service.py # 重排序服务
| | |-- splitter_service.py # 文档切分服务
| | `-- __init__.py
| |
| |-- core/ # 核心基础能力
| | |-- hybrid_retriever.py # 混合检索逻辑
| | |-- milvus_client.py # Milvus 客户端管理
| | |-- vector_store_manager.py # 向量库管理封装
| | `-- __init__.py
| |
| |-- agent/ # Agent 编排和工具调用
| | |-- mcp_client.py # MCP 服务客户端
| | `-- plan_executor/ # 计划-执行-重规划流程
| | |-- planner.py # 生成任务计划
| | |-- executor.py # 执行计划步骤
| | |-- replan.py # 判断继续、重规划或响应
| | |-- state.py # 执行状态定义
| | |-- utils.py # 辅助方法
| | `-- __init__.py
| |
| |-- models/ # 请求和响应模型
| | |-- request.py
| | |-- response.py
| | `-- __init__.py
| |
| |-- prompts/ # Prompt 模板包，import app.prompts 实际加载这里
| | `-- __init__.py # 计划、重规划、最终响应、系统提示词、工具选择提示词
| |
| |-- tools/ # 后端本地工具封装
| | |-- knowledge_tool.py # 知识库检索工具
| | |-- time_tool.py # 时间工具
| | `-- __init__.py
| |
| `-- utils/ # 通用工具模块
| |-- api_errors.py # API 错误处理辅助
| |-- encoding.py # 编码初始化和兼容处理
| |-- logger.py # 日志配置
| |-- message_manager.py # 会话消息管理
| `-- __init__.py
|
|-- mcp_servers/ # 独立 MCP 工具服务
| |-- log_server.py # 日志查询 MCP 服务，默认端口 8003
| |-- monitor_server.py # 指标/监控查询 MCP 服务，默认端口 8004
| |-- weather_server.py # 天气查询 MCP 服务，默认端口 8005
| `-- exchange_server.py # 汇率查询和货币换算 MCP 服务，默认端口 8006
|
|-- frontend/ # Vue 3 + Vite 前端应用
| |-- src/
| | |-- App.vue # 主页面组件
| | |-- main.js # Vue 应用入口
| | `-- styles.css # 全局样式
| |-- public/ # 静态资源
| |-- index.html # Vite HTML 入口
| |-- package.json # 前端依赖和脚本
| |-- package-lock.json # npm 锁定文件
| |-- vite.config.js # Vite 配置
| |-- nginx.conf # 前端容器 Nginx 配置
| |-- Dockerfile # 前端镜像构建文件
| |-- dist/ # 前端构建产物，通常不手工维护
| `-- node_modules/ # 前端依赖目录，通常不手工维护
|
|-- docs/ # 项目文档
|
|-- test_docs/ # 测试用知识库文档
|
|-- uploads/ # 用户上传或测试上传的文件
|-- logs/ # 后端应用运行日志
|-- volumes/ # Docker 持久化数据卷
| |-- etcd/ # Milvus 依赖的 etcd 数据
| |-- milvus/ # Milvus 数据
| `-- minio/ # Milvus 依赖的 MinIO 对象数据
|
|-- .env # 本地环境变量配置
|-- .dockerignore # Docker 构建忽略规则
|-- .pre-commit-config.yaml # pre-commit 配置
|-- Dockerfile # 后端应用镜像构建文件
|-- Dockerfile.mcp # MCP 服务镜像构建文件
|-- docker-compose.yml # 后端、前端、MCP、Milvus 等容器编排
`-- pyproject.toml # Python 依赖、包配置、测试和代码检查配置
图 1 和图 2 展示了 ReAct 模式下调用天气 MCP 工具的效果。系统会根据用户问题自动调用天气查询工具，并在后续追问中保留同一会话的上下文，实现连续对话和历史记忆。
图 3 和图 4 展示了智能路由在复杂问题下自动切换到 Plan-Execute 模式的效果。对于日志分析、问题排查这类多步骤任务，系统会先规划执行步骤，再调用日志工具获取信息并汇总分析结果。
图 5 和图 6 展示了知识库检索问答效果。系统会从已入库文档中召回相关片段，并结合检索结果生成回答；前端会展示检索到的文档来源、分数和片段内容，方便核对答案依据。
图 7 展示了知识库管理页面。该页面支持上传知识文档，后端会完成解析、切分、向量化和入库；同时也支持直接输入关键词进行知识检索，用于验证索引效果和查看召回片段。
