BaseAgent 全栈大模型智能体平台完整部署指南 —— 从零搭建你的 RAG + MCP + ReAct Agent

作者: soft-breeze1
项目地址: GitHub
技术栈: FastAPI + Vue 3 + LangChain + Qdrant + MCP + Celery + MySQL + Redis
版权声明: 本文为原创文章，遵循 MIT 协议，转载请注明出处。

一、项目简介

BaseAgent 是一个面向开发者的全栈 RAG（检索增强生成） 与 MCP（模型上下文协议） 智能 Agent 平台。它通过本地大语言模型和向量数据库驱动，提供知识库管理、技能编排、多模型调度与 ReAct 循环推理等核心能力。

一句话概括：它是一个 “可本地部署的 ChatGPT + 知识库 + 工具调用” 的完整解决方案。

核心特性一览

特性 技术实现
🧩 技能系统 基于 SKILL.md 的渐进式加载，支持动态工具注入与执行拦截器
📚 RAG 知识库 Parent-Child 分块 + Qdrant 向量检索 + Cross-Encoder 本地重排序
🔧 MCP 协议 原生支持 Model Context Protocol，可接入任意第三方 MCP Server
🧠 多模型聚合 统一接口对接 OpenAI / Ollama / DeepSeek / 智谱 / 通义千问
⚙️ ReAct 循环 内置思考-行动-观察推理引擎，支持智能路由与工具语义召回
🎨 前端仪表盘 Vue 3 + Element Plus 构建的现代化管理界面
📂 多格式文档 PDF（含 OCR）/ DOCX / Markdown / CSV / PPT / Excel 全系列文档解析
🗃️ 双层记忆 短期滑动窗口对话记忆 + 长期 Qdrant 向量记忆沉淀
⚡ SSE 流式推送 Server-Sent Events 打字机效果，心跳保活机制
🔄 异步任务 Celery 异步处理文档索引与长时间技能执行

✨ 界面效果预览

以下是系统核心功能实拍界面，按教程部署完成即可得到同款效果：

登录界面
▲ 系统登录界面（JWT 认证 + 用户注册功能）

智能对话界面
▲ 智能对话界面（支持 SSE 流式打字机效果 + ReAct 思考过程展示）

知识库管理界面
▲ 知识库管理界面（支持多格式文档上传 + 向量检索）

二、系统架构全景

整体采用 7 个容器的微服务架构：

┌──────────────────────────────────────────────────────────────┐
│                前端 (Vue 3 + Nginx)                          │
│                baseagent-frontend                            │
│                端口 :8080 → 80                               │
└───────────────────────────┬──────────────────────────────────┘
                            │ 反向代理 /api/ → backend:8000
                            ▼
┌──────────────────────────────────────────────────────────────┐
│              FastAPI 后端 (Uvicorn)                           │
│              baseagent-backend                                │
│              端口 :8000                                       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐│
│  │  Chat API    │ │  RAG 引擎    │ │  MCP 代理    │ │ 工具/技能管理 ││
│  │ (SSE 流式)   │ │              │ │              │ │    系统       ││
│  └──────────────┘ └──────────────┘ └──────────────┘ └───────────────┘│
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐  │
│  │  智能路由    │ │  双层记忆    │ │   渐进式技能披露系统         │  │
│  │ SmartRouter  │ │ MemorySrv    │ │   Progressive Disclosure     │  │
│  └──────────────┘ └──────────────┘ └──────────────────────────────┘  │
└───────┬──────────────────┬──────────────────┬─────────────────┬──────┘
        │                  │                  │                 │
        ▼                  ▼                  ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   MySQL 8.0  │  │   Redis 7    │  │  Qdrant 1.10 │  │ Celery Worker│
│    持久化    │  │     缓存     │  │    向量库    │  │   异步任务   │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘

核心处理流程：三阶智能路由

[用户输入] → [JWT 认证] → [上下文准备(历史/记忆/MCP工具发现)]
    │
    ├─ ① RAG Tier（指定知识库时）
    │   → Qdrant Child向量检索 → Parent段落恢复 
    │   → bge-reranker-v2-m3重排序 → LLM基于文档回答
    │
    ├─ ② Skill Tier（匹配内建技能时）
    │   → 语义匹配SKILL.md描述 → 单轮LLM执行 或 路由到Agent ReAct
    │
    ├─ ③ Agent Tier（ReAct循环 + 工具调用）
    │   → 意图分类 → 工具语义召回过滤 → bind_tools → 
    │     LLM思考→并发执行工具→观察结果→继续/结束
    │
    └─ ④ LLM Fallback（最终兜底）
        → 直接使用LLM自身知识回答问题

容器服务一览

容器名 镜像 端口映射 职责
baseagent-mysql mysql:8.0 3306:3306 主数据库（用户、对话、配置）
baseagent-redis redis:7-alpine 6379:6379 缓存 & Celery 消息代理
baseagent-qdrant qdrant/qdrant:v1.10.1 6333:6333 向量数据库（文档检索 + 语义索引 + 记忆存储）
baseagent-backend 自构建 (Dockerfile) 8000:8000 FastAPI 应用服务
baseagent-celery 自构建 (Dockerfile.celery) — 异步任务消费者
baseagent-frontend 自构建 (Dockerfile) 8080:8 Nginx 静态托管前端

三、环境准备

3.1 前置条件

工具 版本要求 说明
Docker Desktop ≥ 4.0 Windows 下必须打开 WSL 2 后端
Git ≥ 2.30 用于克隆仓库和 LFS 模型
系统内存 ≥ 8GB 推荐 16GB（所有容器 + 模型推理）
磁盘空间 ≥ 15GB 模型文件约 2.5GB + Docker 镜像约 5GB

3.2 安装 Docker Desktop（Windows）

# 1. 下载 Docker Desktop
#    https://www.docker.com/products/docker-desktop/
# 2. 安装时务必勾选 "Use WSL 2 instead of Hyper-V"
# 3. 安装完成后重启电脑
# 4. 验证安装
docker --version
docker-compose --version

⚠️ 重要：Docker Desktop 启动后，右下角鲸鱼图标必须显示为 Running 状态。

3.3 获取项目代码

# 克隆项目
# 进入项目所在目录（请替换为你的实际路径）
cd C:\Users\<用户名>\Desktop

git clone https://github.com/soft-breeze1/BaseAgent.git
cd BaseAgent

3.4 下载本地大模型（最关键的一步！）

本项目依赖 两个本地大模型文件，Git 仓库不包含它们，必须手动下载。

需要下载的模型

模型 用途 大小 下载地址
bge-reranker-v2-m3 RAG 重排序（Cross-Encoder） ~2.1 GB Hugging Face
bge-small-zh-v1.5 文本向量化（Embedding） ~133 MB Hugging Face

方式一：使用 Git LFS 克隆（推荐）

# 1. 安装 Git LFS
git lfs install

# 2. 在项目根目录下执行（约 2.1GB，耗时较长）
git clone https://huggingface.co/BAAI/bge-reranker-v2-m3

# 3. 克隆小模型（约 133MB，较快）
git clone https://huggingface.co/BAAI/bge-small-zh-v1.5

# 4. 将小模型复制为 hf_cache（Docker 挂载需要）
cp -r bge-small-zh-v1.5 hf_cache

方式二：手动下载（逐个文件下载）

访问 Hugging Face 页面，手动下载以下文件：

bge-reranker-v2-m3/ 目录需要：

文件 必须 说明
model.safetensors ✅ 核心模型权重（约 2.1GB）
config.json ✅ 模型配置
tokenizer.json ✅ 分词器
tokenizer_config.json ✅ 分词器配置
sentencepiece.bpe.model ✅ BPE 模型文件
special_tokens_map.json ✅ 特殊 token 映射

hf_cache/ 目录需要（bge-small-zh-v1.5 的副本）：

文件 必须 说明
model.safetensors ✅ 核心模型权重（约 133MB）
config.json ✅ 模型配置
tokenizer.json ✅ 分词器
tokenizer_config.json ✅ 分词器配置
vocab.txt ✅ 词表文件
special_tokens_map.json ✅ 特殊 token 映射

⚠️ 最终目录结构检查

下载完成后，请严格按照以下结构放置文件，绝对禁止目录嵌套：

<项目根目录>\                              ← 项目根目录
│
├── bge-reranker-v2-m3\                   ← 一级目录！
│   ├── model.safetensors                  (2.1GB，核心文件)
│   ├── config.json
│   ├── tokenizer.json
│   ├── tokenizer_config.json
│   ├── sentencepiece.bpe.model
│   ├── special_tokens_map.json
│   └── assets\                            (可选，CSS/JS 等)
│
├── hf_cache\                              ← bge-small-zh-v1.5 的副本！
│   ├── model.safetensors                  (133MB)
│   ├── config.json
│   ├── tokenizer.json
│   ├── tokenizer_config.json
│   ├── vocab.txt
│   └── special_tokens_map.json
│
├── docker-compose.yml                     ← 与模型目录平级
├── backend\
├── frontend\
└── ...

✅ 正确的路径示例：bge-reranker-v2-m3/model.safetensors

❌ 错误的路径示例：bge-reranker-v2-m3/bge-reranker-v2-m3/model.safetensors（套娃）

四、一键部署（Docker Compose）

4.1 启动所有服务

确认模型文件就位后，在项目根目录执行：

cd <项目根目录>

# 启动所有 6 个容器
docker-compose up -d

4.2 查看启动状态

# 查看所有容器运行状态
docker ps

# 你应该看到类似输出：
# CONTAINER ID   IMAGE                       STATUS         PORTS
# a1b2c3d4e5f6   qdrant/qdrant:v1.10.1      Up 2 minutes   0.0.0.0:6333->6333/tcp
# b2c3d4e5f6a7   mysql:8.0                  Up 2 minutes   0.0.0.0:3306->3306/tcp
# c3d4e5f6a7b8   redis:7-alpine             Up 2 minutes   0.0.0.0:6379->6379/tcp
# d4e5f6a7b8c9   baseagent-backend           Up 1 minute    0.0.0.0:8000->8000/tcp
# e5f6a7b8c9d0   baseagent-celery            Up 1 minute
# f6a7b8c9d0e1   baseagent-frontend          Up 1 minute    0.0.0.0:8080->80/tcp

# 查看实时启动日志
docker-compose logs -f

# 或者只看后端的日志
docker logs baseagent-backend -f

首次启动预期日志输出：

[BaseAgent] 系统基础工具已注册: 4 个
[BaseAgent] 实用工具包已注册: 8 个
[BaseAgent] 工具语义召回索引已初始化
[BaseAgent] ToolRetrieval: Embedding model pre-warmed in 7.52s
[BaseAgent] BaseAgent v1.0.0 started

4.3 验证部署

# 1. 健康检查
curl http://localhost:8000/health
# 返回: {"status":"ok"}

# 2. 根路径
curl http://localhost:8000/
# 返回: {"name":"BaseAgent","version":"1.0.0","status":"running"}

4.4 访问系统

一切就绪后，用浏览器访问以下地址：

组件 地址 功能
前端主界面 http://localhost:8080 完整的用户管理界面
后端 API http://localhost:8000 FastAPI 根路径
Swagger 文档 http://localhost:8000/docs 交互式 API 调试
Qdrant 看板 http://localhost:6333/dashboard 向量数据库管理
Redis 监测 redis-cli -h localhost -p 6379 ping 返回 PONG 即正常

五、各服务深度解析

5.1 MySQL 8.0（持久层）

mysql:
  image: mysql:8.0
  environment:
    MYSQL_ROOT_PASSWORD: root123
    MYSQL_DATABASE: baseagent
    MYSQL_USER: baseagent
    MYSQL_PASSWORD: baseagent123
  volumes:
    - mysql_data:/var/lib/mysql
    - ./backend/migrations/init.sql:/docker-entrypoint-initdb.d/init.sql

设计要点：

  • 数据卷持久化：mysql_data 命名卷，容器销毁数据不丢失
  • 自动初始化：migrations/init.sql 自动挂载到 MySQL 初始化目录
  • 健康检查：每 10 秒用 mysqladmin ping 检测，后端等待就绪后才启动
  • 存储内容：用户表、对话记录、消息历史、模型配置、MCP Server 配置、系统提示词等

表结构（由 SQLAlchemy ORM 自动建表）：

-- 核心表
users              -- 用户（密码 bcrypt 加密）
conversations       -- 对话（含 RAG 参数绑定）
chat_messages      -- 消息（含 tool_calls JSON 字段）
model_configs       -- 模型配置（多供应商）
knowledge_bases    -- 知识库（绑定集合名）
mcp_servers        -- MCP Server 注册
system_prompts     -- 全局系统提示词
skills             -- 技能执行记录

5.2 Redis 7（缓存层）

redis:
  image: redis:7-alpine
  ports:
    - "6379:6379"
  volumes:
    - redis_data:/data
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]

Redis 做了三件事：

用途 Key 格式 TTL 说明
对话热缓存 chat:{user_id}:conv:{conv_id}:msgs 1 小时 近期对话消息，减少 MySQL 读压力
对话元数据 chat:{user_id}:conv:{conv_id} 30 天 标题、创建时间、RAG 参数
Celery 消息队列 Redis DB 1/2 自动 Broker + Result Backend

读写策略：Redis 优先读 → MySQL 兜底 → 回写 Redis，既保证性能又保证数据不丢失。

5.3 Qdrant 向量数据库

qdrant:
  image: qdrant/qdrant:v1.10.1
  ports:
    - "6333:6333"
  volumes:
    - qdrant_data:/qdrant/storage
  healthcheck:
    test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/localhost/6333"]
    start_period: 15s

Qdrant 承载三大索引：

集合名称 用途 维度 距离算法
kb_{uuid} 知识库文档向量 依嵌入模型（256~1536） COSINE
user_memory_{user_id} 用户长期记忆 2560（qwen3-embedding:4b，可选） COSINE
tool_semantic_index 工具语义召回 512（bge-m3） COSINE

5.4 FastAPI 后端

Dockerfile 构建流程：

FROM python:3.11-slim

# 1. 换阿里云源加速 apt
# 2. 安装系统依赖（gcc, libmagic1, nodejs, npm）
# 3. 换阿里云 pip 源
# 4. 先装 CPU-only PyTorch（避免拉 CUDA 工具链，缩小镜像体积）
# 5. 装 Python 依赖（84 个包）
# 6. 全局安装 MCP 工具包 (@modelcontextprotocol/server-filesystem)
# 7. 设置 HF_ENDPOINT=https://hf-mirror.com（国内 HuggingFace 镜像）

容器内目录结构：

/app/
├── app/                    # Python 应用代码（以 volume 挂载，支持热更新）
│   ├── main.py             # 入口
│   ├── api/                # API 路由（9 个资源端点）
│   ├── services/           # 业务逻辑层
│   ├── tools/              # 工具实现
│   ├── rag/                # RAG 引擎
│   ├── core/               # 核心基础设施
│   ├── progressive_disclosure/  # 技能系统
│   ├── schemas/            # Pydantic 校验模型
│   ├── models/             # SQLAlchemy ORM 模型
│   └── tasks/              # Celery 异步任务
├── data/                   # 运行时数据（volume）
│   ├── uploads/            # 上传的文档
│   ├── skills/             # 技能文件
│   └── tool_configs.json   # 工具配置
├── models_cache/           # 本地模型（volume 挂载）
│   ├── bge-reranker-v2-m3/ # 重排序模型
│   └── bge-small-zh-v1.5/  # 向量化模型
└── output/                 # 技能产物输出

后端核心技术模块：

模块 文件位置 职责
LLMFactory app/services/llm_service.py 多模型统一封装（OpenAI / Ollama / DeepSeek 等）
SmartRouter app/services/smart_router.py 三阶智能路由（RAG → Skill → Agent → LLM）
ToolManager app/services/tool_manager.py 工具注册调度（系统工具 + MCP 工具 + 技能工具）
ToolRetrieval app/services/tool_retrieval.py 工具语义召回过滤（Qdrant + bge-m3）
RAGService app/services/rag_service.py RAG 检索管道
MemoryService app/services/memory_service.py 双层记忆系统
AgentState app/services/agent_state.py ReAct 循环状态管理

5.5 Celery Worker（异步任务）

# Dockerfile.celery
FROM python:3.11-slim

# ... 同上安装依赖 ...

CMD ["celery", "-A", "app.celery_app", "worker", "--loglevel=info", "--concurrency=4"]

异步任务列表：

任务 触发时机 说明
persist_message 非流式对话回复后 后台写 MySQL，不阻塞 HTTP 响应
process_document 上传文档后 解析→分块→嵌入→写入 Qdrant
execute_skill 技能执行 长时间运行的工作流

5.6 前端 Nginx

Nginx 配置要点：

# SSE 流式支持 — 核心配置！
location /api/ {
    proxy_pass http://backend:8000;
    
    # ★ 这四行缺一不可，否则 SSE 无法工作
    proxy_buffering off;       # 禁用缓冲
    proxy_cache off;           # 禁用缓存
    proxy_read_timeout 300s;   # 超时 5 分钟（SSE 长连接）
    chunked_transfer_encoding on;
}

前端构建流水线（多阶段构建）：

Stage 1 (build):  node:20-alpine → npm install → npm run build → dist/
Stage 2 (prod):   nginx:1.25-alpine → 复制 dist/ → 加载 nginx.conf → 服务 80 端口

六、项目目录结构详解

BaseAgent/
├── docker-compose.yml           # Docker 服务编排（6个容器）
│
├── backend/                     # 🐍 Python 后端
│   ├── Dockerfile               #   生产镜像构建
│   ├── Dockerfile.celery        #   Celery Worker 镜像
│   ├── requirements.txt         #   Python 依赖（84个包）
│   │
│   ├── app/
│   │   ├── main.py              #   FastAPI 入口 + 生命周期
│   │   ├── celery_app.py        #   Celery Worker 入口
│   │   │
│   │   ├── api/endpoints/       #   9 个 API 资源端点
│   │   │   ├── auth.py          #   认证（JWT 登录/注册）
│   │   │   ├── chat.py          #   SSE 流式对话
│   │   │   ├── knowledge.py     #   知识库 CRUD
│   │   │   ├── mcp.py           #   MCP Server 管理
│   │   │   ├── models.py        #   模型配置
│   │   │   ├── skills.py        #   技能列表/执行
│   │   │   ├── tools.py         #   工具注册与路由
│   │   │   ├── user.py          #   用户信息
│   │   │   └── system_prompt.py #   系统提示词
│   │   │
│   │   ├── core/                #   核心基础设施
│   │   │   ├── config.py        #   配置中心（Pydantic Settings）
│   │   │   ├── database.py      #   数据库引擎（SQLAlchemy）
│   │   │   ├── redis.py         #   Redis 客户端
│   │   │   ├── security.py      #   JWT 密码工具
│   │   │   └── mcp/             #   MCP 协议实现
│   │   │       ├── executor.py  #   HTTP/Stdio 执行器
│   │   │       ├── protocol.py  #   JSON-RPC 协议封装
│   │   │       ├── discovery.py #   工具发现与路由
│   │   │       └── process_manager.py  # Stdio 子进程管理
│   │   │
│   │   ├── models/              #   SQLAlchemy ORM 模型
│   │   ├── schemas/             #   Pydantic 校验模型
│   │   │
│   │   ├── services/            #   业务服务层
│   │   │   ├── llm_service.py   #   LLM 聚合工厂（多模型适配）
│   │   │   ├── rag_service.py   #   RAG 检索管道
│   │   │   ├── tool_manager.py  #   工具注册调度
│   │   │   ├── tool_retrieval.py#   工具语义召回
│   │   │   ├── smart_router.py  #   三阶智能路由
│   │   │   ├── memory_service.py#   双层记忆系统
│   │   │   └── agent_state.py   #   Agent 状态管理
│   │   │
│   │   ├── progressive_disclosure/  # 渐进式技能系统
│   │   │   ├── skill_manager.py #   磁盘扫描与元数据提取
│   │   │   ├── skill_runner.py  #   单轮 LLM+工具执行
│   │   │   ├── schema_builder.py#   工具 Schema 构建
│   │   │   ├── tool_injector.py #   工具注入器
│   │   │   └── execution_interceptor.py # 执行拦截器
│   │   │
│   │   ├── rag/                 #   RAG 引擎
│   │   │   ├── ingestion/       #   文档导入管道
│   │   │   │   ├── chunking/    #   Parent-Child 分块
│   │   │   │   ├── storage/     #   Parent 内容存储
│   │   │   │   └── loader/      #   PDF OCR 增强加载
│   │   │   └── libs/
│   │   │       ├── embedding/   #   向量化抽象
│   │   │       └── reranker/    #   Cross-Encoder 重排序
│   │   │
│   │   ├── tools/               #   工具实现
│   │   │   ├── system_tools/    #   文件系统 / 终端执行
│   │   │   └── utility_tools/   #   网页抓取 / Python沙箱
│   │   │
│   │   └── tasks/               #   Celery 异步任务
│   │
│   ├── skills/                  #   内建技能（SKILL.md）
│   │   ├── example_skill/       #       示例技能
│   │   ├── baoyu-format-markdown/ #     Markdown 排版
│   │   ├── csdn-blog-writer/    #       CSDN 博客写作
│   │   ├── slide-craft-skill-main/ #  幻灯片制作
│   │   └── test_skill_crafter/  #       测试技能
│   │
│   └── migrations/              #   数据库迁移脚本
│
├── frontend/                    # 🎨 Vue 3 前端
│   ├── Dockerfile               #   Nginx 生产镜像
│   ├── nginx.conf               #   路由转发配置
│   ├── vite.config.ts           #   Vite 打包配置
│   ├── package.json             #   依赖清单
│   └── src/
│       ├── main.ts              #   Vue 应用入口
│       ├── App.vue              #   根组件
│       ├── router/              #   路由配置
│       ├── stores/              #   Pinia 状态管理
│       ├── api/                 #   Axios API 客户端
│       ├── views/               #   页面组件（10个）
│       ├── components/          #   通用组件
│       └── styles/              #   全局样式
│
├── bge-reranker-v2-m3/          # 🧠 重排序模型（手动下载）
└── hf_cache/                    # 🧠 向量化模型（手动下载）

七、API 接口概览

系统提示词界面
▲ 系统提示词管理界面

端点 类别 说明
POST /api/v1/auth/register 认证 用户注册
POST /api/v1/auth/login 认证 登录获取 JWT Token
GET /api/v1/chat/stream 对话 SSE 流式对话（打字机效果）
POST /api/v1/chat/send 对话 非流式对话
GET /api/v1/knowledge/ 知识库 知识库列表查询
POST /api/v1/knowledge/upload 知识库 文档上传并索引
DELETE /api/v1/knowledge/{id} 知识库 删除知识库
GET /api/v1/mcp/servers MCP MCP Server 列表
POST /api/v1/mcp/servers MCP 添加 MCP Server
GET /api/v1/tools 工具 已注册工具列表
GET /api/v1/skills 技能 已发现技能列表
POST /api/v1/skills/execute 技能 执行一个技能
GET /api/v1/models/ 模型 模型配置列表
POST /api/v1/models/ 模型 添加模型配置
GET /api/v1/system-prompt/ 系统 系统提示词管理
GET /api/v1/users/me 用户 获取当前用户信息

八、开发模式（前后端分离调试）

8.1 本地开发拓扑

localhost:3000 (Vite Dev Server)          localhost:8000 (FastAPI)
┌─────────────────────┐                    ┌─────────────────────┐
│  Vue 3 + Vite       │   /api → proxy    │  Python + Uvicorn   │
│  热重载              │ ───────────────→  │  代码热重载(--reload)│
│                     │   ← SSE stream     │                     │
└─────────────────────┘                    └─────────────────────┘

8.2 启动开发环境

# Step 1: 启动基础设施（只需 MySQL + Redis + Qdrant）
docker-compose up -d mysql redis qdrant

# Step 2: 启动后端（Python 虚拟环境）
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Step 3: 启动前端（另一个终端）
cd frontend
npm install
npm run dev

# 访问 http://localhost:3000
# Vite 自动代理 /api → http://localhost:8000

⚠️ 若PowerShell提示「无法加载脚本」，先执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 放开执行策略，再激活虚拟环境。

8.3 常用运维命令

# ── 容器管理 ──
docker ps                              # 查看运行中的容器
docker-compose logs -f backend         # 跟踪后端日志
docker-compose logs -f frontend        # 跟踪前端日志
docker restart baseagent-backend       # 重启后端

# ── 构建与部署 ──
docker-compose up -d                   # 启动所有服务
docker-compose up -d --build           # 重新构建并启动
docker-compose down                    # 停止所有服务
docker-compose down -v                 # ⚠️ 停止并删除数据卷（数据全丢！）

# ── 数据库操作 ──
docker exec -it baseagent-mysql mysql -ubaseagent -pbaseagent123
# 进入后: USE baseagent; SHOW TABLES; SELECT * FROM users;

# ── Redis 操作 ──
docker exec -it baseagent-redis redis-cli
# 进入后: KEYS chat:*; GET key; FLUSHDB（清空缓存）

# ── Qdrant 操作 ──
# REST API: curl http://localhost:6333/collections
# UI: http://localhost:6333/dashboard

九、网络与端口映射详解

9.1 Docker 内部网络拓扑

所有容器通过自定义 bridge 网络 baseagent-net 通信：

baseagent-net (172.18.0.0/16)
│
├── mysql     ← 主机端口 3306
│   └── 其他容器通过  mysql:3306 访问（Docker DNS 解析）
│
├── redis     ← 主机端口 6379
│   └── 其他容器通过  redis:6379 访问
│
├── qdrant    ← 主机端口 6333
│   └── 其他容器通过  qdrant:6333 / http://qdrant:6333 访问
│
├── backend   ← 主机端口 8000
│   └── 前端通过 backend:8000 访问 API
│
├── celery-worker（无端口暴露）
│   └── 通过 redis://redis:6379/1 消费任务
│
└── frontend  ← 主机端口 8080 → 容器 80
    └── 用户通过 http://localhost:8080 访问

9.2 端口映射总结

容器端口 宿主机端口 用途
mysql:3306 0.0.0.0:3306 数据库直连（可用 Navicat/DataGrip 连接）
redis:6379 0.0.0.0:6379 Redis 直连（可用 RedisDesktopManager）
qdrant:6333 0.0.0.0:6333 Qdrant gRPC + REST API
backend:8000 0.0.0.0:8000 FastAPI 后端
frontend:80 0.0.0.0:8080 Nginx 前端页面

十、配置对接外部 LLM

模型配置界面
▲ 多模型配置管理界面（支持多供应商统一接入）

10.1 Ollama 本地模型（推荐，免费）

如果本地有 Ollama 服务（假设在宿主机运行）：

宿主机 (Windows)
┌──────────────────────────────────────┐
│  Ollama 服务                           │
│  http://localhost:11434                │
│  模型: qwen2.5:7b, qwen3-embedding:4b │
└──────────┬───────────────────────────┘
           │ host.docker.internal:11434
           ▼
Docker 容器
baseagent-backend  ← 通过 OLLAMA_HOST 连接
  1. 先确保宿主机已安装 Ollama 并拉取模型：
# 安装 Ollama（如果还没有）
winget install Ollama.Ollama

# 拉取必要的模型
ollama pull qwen2.5:7b          # 对话模型
ollama pull qwen3-embedding:4b  # 嵌入模型
ollama pull bge-m3              # 工具语义召回嵌入

  1. 后端通过 OLLAMA_HOST=http://host.docker.internal:11434 自动连接宿主机 Ollama

  2. 在前端 UI 中配置模型（登录后 → 模型管理）：

    • Provider: ollama
    • Model Name: qwen2.5:7b
    • API Base: 留空（后端自动拼接 OLLAMA_HOST）

10.2 OpenAI / 第三方 API（需要 Key）

供应商 Provider Model Name 示例 API Base
OpenAI openai gpt-4o-mini 留空（默认）
DeepSeek deepseek deepseek-chat 留空（自动填充）
通义千问 qwen qwen-max 留空（自动填充）
月之暗面 moonshot moonshot-v1-8k 留空（自动填充）
智谱 zhipu glm-4 留空（自动填充）
自定义 openai 任意模型名 填写你的 API Base URL

在环境变量或 .env 文件中设置：

# .env 文件
OPENAI_API_KEY=sk-your-openai-key

十一、配置 Tavily 联网搜索（可选但推荐）

BaseAgent 的联网搜索能力依赖 Tavily API。免费注册可获得每月 1000 次调用额度：

# Step 1: 访问 https://app.tavily.com 注册并获取 API Key
# Step 2: 在 .env 文件中设置
TAVILY_API_KEY=tvly-your-api-key-here

# Step 3: 重启后端
docker restart baseagent-backend

配置完成后，Agent 在 ReAct 循环中会自动判断是否需要调用 tavily_web_search 工具获取最新信息。

十二、数据备份与恢复

12.1 备份 MySQL 数据

# 导出全部数据
docker exec -it baseagent-mysql mysqldump -ubaseagent -pbaseagent123 baseagent > backup_$(Get-Date -Format "yyyyMMdd_HHmmss").sql

12.2 备份 Qdrant 数据

# 通过 Qdrant API 创建快照（推荐）
curl -X POST http://localhost:6333/collections/kb_xxxx/snapshots

# 或者直接备份数据卷目录（需要停止容器）
docker run --rm -v qdrant_data:/source -v ${PWD}:/backup alpine tar czf /backup/qdrant_backup.tar.gz -C /source .

12.3 全量恢复

# 停止并删除数据卷
docker-compose down -v

# 恢复 MySQL
docker-compose up -d mysql

# 等待 MySQL 就绪后执行:
Get-Content backup.sql | docker exec -i baseagent-mysql mysql -uroot -proot123 baseagent

# 恢复 Qdrant
docker run --rm -v qdrant_data:/target -v ${PWD}:/backup alpine tar xzf /backup/qdrant_backup.tar.gz -C /target

# 启动所有服务
docker-compose up -d

十三、常见问题与解决方案

❌ Q1: 后端启动时报 “Can’t connect to MySQL server”

sqlalchemy.exc.OperationalError: Can't connect to MySQL server on 'mysql'

原因：MySQL 容器尚未就绪，后端启动太快。

解决方案：

# 查看 MySQL 是否真的在运行
docker logs baseagent-mysql

# 检查 MySQL 健康检查状态
docker inspect baseagent-mysql | Select-String "health"

# 如果 MySQL 正常，手动重启后端
docker restart baseagent-backend

❌ Q2: Qdrant 健康检查一直失败

# 查看 Qdrant 日志
docker logs baseagent-qdrant

# 尝试直接通过 curl 验证
curl http://localhost:6333/collections
# 应该返回 JSON 集合列表，而非连接错误

❌ Q3: bge-reranker-v2-m3 模型下载位置不对

症状：后端日志中出现 No such file or directory: '/app/models_cache/bge-reranker-v2-m3/model.safetensors'

原因：模型目录嵌套。检查项目根目录结构，确保是 bge-reranker-v2-m3/model.safetensors 而非 bge-reranker-v2-m3/bge-reranker-v2-m3/model.safetensors。

❌ Q4: 前端页面空白 / 无法加载

# 查看 Nginx 是否正常运行
docker logs baseagent-frontend

# 手动验证前端构建产物
docker exec -it baseagent-frontend ls /usr/share/nginx/html
# 应该看到: index.html, assets/, favicon.svg

# 检查 API 代理是否正常工作
curl http://localhost:8080/api/v1/health
# 应该返回: {"status":"ok"}

❌ Q5: SSE 流式响应被截断或延迟

症状：前端收到第一个 token 需要等待 30 秒以上，或连接中途断开。

原因：Nginx 缓冲或代理超时设置不正确。

检查：

# 确认 nginx.conf 中以下配置已启用
docker exec -it baseagent-frontend cat /etc/nginx/conf.d/default.conf

# 必须包含:
#   proxy_buffering off;
#   proxy_cache off;
#   proxy_read_timeout 300s;
#   chunked_transfer_encoding on;

❌ Q6: Ollama 连接不上

症状：模型管理中添加 Ollama 后，测试连接失败。

排查：

# 1. 确认 Ollama 在宿主机上正常运行
ollama list

# 2. 确认 Docker 容器可以访问宿主机
docker exec baseagent-backend curl http://host.docker.internal:11434/api/tags

# 3. 检查后端环境变量
docker exec baseagent-backend echo %OLLAMA_HOST%
# 应输出: http://host.docker.internal:11434

❌ Q7: 上传文档后知识库搜索不到内容

# 1. 检查文档是否成功索引
docker logs baseagent-celery | Select-String "文档"
docker logs baseagent-backend | Select-String "RAG"

# 2. 检查 Qdrant 中是否有数据
curl http://localhost:6333/collections | ConvertFrom-Json | Select-Object -ExpandProperty result | Select-Object name

# 3. 手动触发重新索引（如果有 Celery 任务）

❌ Q8: Docker 磁盘空间不足

# 清理未使用的镜像、容器、网络
docker system prune -a

# 清理构建缓存
docker builder prune

# 查看各容器磁盘占用
docker system df

十四、性能调优建议

14.1 增加 ReAct 超时时间（处理复杂任务）

在 docker-compose.yml 的 backend 服务环境变量中修改：

environment:
  - REACT_GLOBAL_TIMEOUT=600       # 全局超时：10 分钟
  - REACT_MAX_ITERATIONS=50        # 最大推理步数
  - REACT_MAX_ROUNDS=30            # 最大工具调用轮数
  - REACT_TOOL_TIMEOUT=60          # 单工具调用超时：60 秒

14.2 增加 Celery Worker 并发数

# Dockerfile.celery
CMD ["celery", "-A", "app.celery_app", "worker", "--loglevel=info", "--concurrency=8"]

14.3 Qdrant 性能优化

qdrant:
  image: qdrant/qdrant:v1.10.1
  environment:
    - QDRANT__SERVICE__GRPC_PORT=6334  # 启用 gRPC（比 REST 快 3-5 倍）
    - QDRANT__STORAGE__OPTIMIZERS__DEFAULT_SEGMENT_NUMBER=2  # 减少段数

14.4 内存分配建议

服务 推荐内存 说明
MySQL 512MB ~ 1GB 默认已足够
Qdrant 1GB ~ 2GB 向量索引占用内存
Backend 2GB ~ 4GB 含 bge-reranker (2.1GB) 加载
Celery 512MB 文档处理时临时增加
Frontend 128MB Nginx 极轻量级

十五、核心技术亮点

15.1 渐进式技能系统（Progressive Disclosure）

技能管理界面
▲ 内建技能管理界面

BaseAgent 采用业界创新的渐进式技能加载架构：SKILL.md 技能文件平时不加载到 LLM 上下文中（零 Token 成本），只在 LLM 决定调用时动态注入。

模块 A: SkillManager (文件系统)
  └── 扫描 skills/ 目录 → 解析 YAML frontmatter → 缓存技能元数据

模块 B: SchemaBuilder (格式转换)
  └── build_tool_schema(skill_metadata) → OpenAI JSON Schema Tool 格式

模块 C: ToolInjector (PLANNER 阶段注入)
  └── 将虚拟工具追加到工具列表，LLM 自主决定是否调用

模块 D: ExecutionInterceptor (EXECUTOR 阶段拦截)
  └── 检测 load_skill_context_* 调用 → 读取真实 SKILL.md → 返回 Observation

15.2 工具语义召回机制

工具管理界面
▲ 工具列表管理界面

当工具数量从 5 个增长到 30+ 个时，全部绑定给 LLM 会导致 Token 浪费和决策质量下降。解决方案是构建工具语义索引：

  • 离线阶段：为每个工具预计算 512 维 Embedding（名称 + 触发词 + 描述）
  • 运行时：用户 Query → 本地 sentence-transformers 计算向量 → Qdrant 相似度搜索 → 过滤不相关工具
  • 零运行时网络依赖：Embedding 预计算 + 本地推理
  • 否定意图检测：用户说"不要图片"时跳过图片搜索工具

15.3 原生 MCP 1.0 协议集成

MCP扩展界面
▲ MCP 扩展服务配置界面

BaseAgent 原生实现 MCP 1.0 完整协议，支持两种传输模式：

模式 通信方式 适用场景
HTTP 模式 POST 请求到远端端点 Docker 部署（Sidecar 容器）、远程服务
Stdio 模式 子进程 stdin/stdout 管道 本地工具、脚本执行

安全控制：命令白名单/黑名单、环境变量隔离、内存/CPU/运行时三重限制、崩溃恢复指数退避。

15.4 RAG 知识库引擎

[离线索引]
文档上传 → 自适应Parent-Child分块 → Child嵌入 → Qdrant向量库 → 文档质量检查
                                       ↓
                                 ParentStore(JSON本地存储)
[在线检索]
用户Query → 文本嵌入 → Qdrant Child检索(Top-15) → Parent段落恢复
  → Cross-Encoder重排序(bge-reranker-v2-m3) → Top-3注入LLM → 引用回答

自适应分块策略：

  • 说明书：Parent=600字, Child=200字
  • 技术文档：Parent=900字, Child=256字
  • 通用：Parent=750字, Child=200字

15.5 双层记忆系统

记忆层 技术实现 特点
短期记忆 智能滑动窗口（最近 10 轮 + 工具链保护） 对话不断裂，缓存 Redis
长期记忆 Qdrant 向量存储 + LLM 自动提取 跨对话持久化，语义去重

个人信息设置界面
▲ 个人信息设置界面

十六、总结

至此，你已经从零完成了 BaseAgent 整站部署的全流程！这是一个生产级别的全栈智能 Agent 平台，覆盖了：

  • ✅ RAG 知识库 — Parent-Child 分块 + Qdrant 向量检索 + Cross-Encoder 重排序
  • ✅ ReAct 代理循环 — 思考→行动→观察的智能推理引擎（含去重/兜底/收敛控制）
  • ✅ MCP 协议集成 — 原生支持 HTTP + Stdio 双模式外部工具扩展
  • ✅ 多模型聚合 — OpenAI / Ollama / DeepSeek / 智谱 / 通义千问统一接入
  • ✅ 三阶智能路由 — RAG → Skill → Agent ReAct → LLM 自动降级
  • ✅ 渐进式技能系统 — 基于 SKILL.md 的零 Token 成本动态加载
  • ✅ 工具语义召回 — Qdrant + bge-m3 智能过滤不相关工具，降低 60% Token 消耗
  • ✅ 双层记忆系统 — 短期滑动窗口 + 长期向量记忆沉淀
  • ✅ SSE 流式推送 — 打字机效果 + 心跳保活
  • ✅ 异步任务 — Celery 处理文档索引与长时间任务

访问地址汇总：

  • 前端 UI：http://localhost:8080
  • API 文档：http://localhost:8000/docs
  • Qdrant 看板：http://localhost:6333/dashboard

如果你在部署过程中遇到任何问题，请参考第十三章的排错指南，或者查看容器日志定位问题。欢迎在评论区留言交流！

# 人工智能 # fastapi # vue.js # docker # 前端 # 后端 # redis
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

AI Agent 共享知识库实战：让 Hermes、Claude Code、Codex 共用一份记忆

要点说明是什么SQLite 单文件数据库，三个 Agent 共用解决什么多个 AI Agent 之间的信息孤岛问题怎么用Hermes 直接说，Claude Code/Codex 调py kb.py核心价值一次写入，三端共享；不再重复解释项目配置升级路径API 兼容 Cognee，可无缝迁移到知识图谱回到最初的那个场景——你再也不用对每个 Agent 重复"API 地址是 xxx"。告诉 Herme

avatar AI Agent技术社区
cover

为什么未来的一人公司，也需要一套 AI 组织？

avatar AI Agent技术社区
cover

景枢：基于 Elastic AI Agent Builder 的多景区购票智能运维中枢技术解析

avatar AI Agent技术社区