环境搭建

简介

AgentChat是一个基于大语言模型(LLM)的智能代理通信平台，采用前后端分离架构。本指南将详细说明如何搭建完整的本地开发环境，包括Python后端、Vue.js前端、数据库连接以及向量数据库配置。

前置要求

在开始之前，请确保您的系统满足以下要求：

系统要求

操作系统: Windows 10+ / macOS 10.15+ / Linux Ubuntu 18.04+
内存: 至少 8GB RAM (推荐 16GB+)
存储空间: 至少 2GB 可用磁盘空间

必需软件

Python: 3.12+ (推荐使用 Python 3.12.x)
Node.js: 18+ (推荐使用 LTS 版本)
npm: 8+ (随 Node.js 自带)
Git: 2.20+ (用于版本控制)

可选但推荐

Poetry: Python包管理工具 (用于依赖管理)
Conda: Python虚拟环境管理器
Docker: 容器化部署选项

项目结构概览

AgentChat采用模块化的项目结构：

图表来源

章节来源

Python环境配置

1. 创建虚拟环境

推荐使用以下方法之一创建隔离的Python环境：

方法一：使用Python venv

bash

# 创建虚拟环境
python -m venv agentchat_env

# 激活虚拟环境
# Windows:
agentchat_env\Scripts\activate
# macOS/Linux:
source agentchat_env/bin/activate

方法二：使用Conda

bash

# 创建Conda环境
conda create -n agentchat python=3.12

# 激活环境
conda activate agentchat

2. 安装依赖

项目支持两种依赖安装方式：

方式一：使用Poetry (推荐)

bash

# 安装Poetry (如果尚未安装)
curl -sSL https://install.python-poetry.org | python -

# 安装项目依赖
cd AgentChat
poetry install

方式二：使用pip

bash

# 安装pip (如果尚未安装)
python -m ensurepip --upgrade

# 安装项目依赖
cd AgentChat
pip install -e .

依赖项详情

根据pyproject.toml文件，项目需要以下核心依赖：

组件类别	主要依赖	版本要求
Web框架	FastAPI	^0.121.0
数据库	SQLModel	^0.0.27
AI模型	LangChain	^1.0.3
向量数据库	ChromaDB	^1.3.4
向量数据库	Milvus	^2.6.3
缓存	Redis	^7.0.1
文件处理	PyMuPDF	^0.1.8

章节来源

Node.js和前端依赖

1. 安装Node.js

确保安装了Node.js 18+版本：

bash

# 检查Node.js版本
node --version

# 检查npm版本
npm --version

2. 安装前端依赖

导航到前端目录并安装依赖：

bash

cd src/frontend
npm install

3. 前端技术栈

前端项目使用以下技术栈：

技术	版本	用途
Vue.js	^3.4.21	前端框架
TypeScript	^5.4.3	类型安全
Vite	^5.2.8	构建工具
Element Plus	^2.7.0	UI组件库
Pinia	^2.1.7	状态管理
Axios	^1.6.8	HTTP客户端

4. 前端脚本命令

前端项目提供了以下npm脚本：

命令	功能	说明
`npm run dev`	开发服务器	启动热重载开发服务器
`npm run build`	生产构建	构建生产环境代码
`npm run preview`	预览构建	预览生产构建效果
`npm run lint`	代码检查	TypeScript类型检查

章节来源

数据库和服务配置

1. 数据库配置

AgentChat支持多种数据库配置，主要使用MySQL和Redis。

MySQL配置

yaml

mysql:
  endpoint: "mysql+pymysql://root:mingguang@localhost:3306/agentchat"
  async_endpoint: "mysql+aiomysql://root:mingguang@localhost:3306/agentchat"

Redis配置

yaml

redis:
  endpoint: "redis://localhost:6379"

2. 向量数据库配置

项目支持两种向量数据库：

ChromaDB配置

yaml

rag:
  vector_db:
    host: "47.95.23.87"
    port: "19530"
    mode: "chroma"

Milvus配置

yaml

# 需要在代码中实现
rag:
  vector_db:
    mode: "milvus"

3. 外部服务配置

LLM服务配置

yaml

multi_models:
  conversation_model:
    api_key: "sk-6d47d94f4c7343579030b6a75b65f31f"
    base_url: "https://api.deepseek.com/v1"
    model_name: "deepseek-chat"

工具服务配置

yaml

tools:
  weather:
    api_key: "fac0ad465078da96a3ec6ba1ccc6746f"
  tavily:
    api_key: "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"

4. 配置文件结构

配置文件位于src/backend/agentchat/config.yaml，包含以下主要部分：

图表来源

src/backend/agentchat/config.yaml

章节来源

启动开发环境

1. 使用自动化脚本启动

项目提供了一键启动脚本，简化开发环境启动过程。

启动步骤

激活Python虚拟环境

bash

# Windows
agentchat_env\Scripts\activate
# macOS/Linux
source agentchat_env/bin/activate

运行启动脚本

bash

cd AgentChat
python scripts/start.py

脚本执行流程

图表来源

scripts/start.py

脚本功能特性

自动路径检测: 自动识别项目根目录和子目录结构
依赖自动安装: 智能查找并安装Python依赖
并发启动: 同时启动前后端服务
实时日志: 混合显示前后端日志输出
优雅关闭: 支持Ctrl+C优雅停止所有服务

2. 服务访问地址

后端API: http://127.0.0.1:7860
前端开发服务器: http://127.0.0.1:5173 (由Vite自动分配)

3. 启动验证

启动成功后，您应该能看到以下输出：

🚀 [Step 1] 正在查找依赖文件...
📦 发现依赖文件: ./requirements.txt
⏳ 正在安装依赖 (pip install)...
✅ 依赖安装完成！

🚀 [Step 2] 启动后端 (cwd: src/backend)...
🚀 [Step 3] 启动前端 (cwd: src/frontend)...

✨ 服务已启动！日志将混合显示在下方。
🛑 按 Ctrl+C 可停止服务。

章节来源

常见问题解决

1. 依赖安装失败

问题现象

❌ 依赖安装失败，脚本终止。

解决方案

检查依赖文件

bash

# 确认项目根目录存在依赖文件
ls requirements.txt  # Linux/macOS
dir requirements.txt  # Windows

手动安装依赖

bash

# 使用pip手动安装
pip install -r requirements.txt

# 或使用poetry
poetry install

网络问题处理

bash

# 设置国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

2. 端口冲突

问题现象

ERROR: Port 7860 is already in use

解决方案

修改配置文件 编辑src/backend/agentchat/config.yaml：

yaml

server:
  host: "127.0.0.1"
  port: 7861  # 修改为其他可用端口

临时更换端口

bash

# 后端单独启动时指定端口
uvicorn agentchat.main:app --port 7861

3. Node.js相关问题

问题：npm不是内部或外部命令

bash

# 解决方案：检查Node.js安装
node --version
npm --version

# 如果未安装，从官网下载：
# https://nodejs.org/

问题：前端依赖安装失败

bash

# 清理缓存重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

4. 数据库连接问题

MySQL连接失败

bash

# 检查MySQL服务状态
# Windows:
net start mysql
# Linux:
sudo systemctl start mysql
# macOS:
brew services start mysql

Redis连接失败

bash

# 检查Redis服务
redis-cli ping
# 如果失败，启动Redis服务
redis-server

5. 向量数据库连接问题

ChromaDB连接失败

bash

# 检查ChromaDB服务
pip install chromadb
python -c "import chromadb; print('ChromaDB installed')"

Milvus连接失败

bash

# 检查Milvus服务
pip install pymilvus
python -c "import pymilvus; print('Milvus installed')"

6. 权限问题

Windows权限问题

powershell

# 以管理员身份运行PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Unix/Linux权限问题

bash

# 确保脚本可执行
chmod +x scripts/start.py

手动启动方式

如果自动化脚本无法正常工作，可以手动启动各个服务。

1. 后端服务启动

方法一：使用Uvicorn直接启动

bash

cd src/backend
uvicorn agentchat.main:app --reload --port 7860

方法二：使用Python直接运行

bash

cd src/backend
python -m agentchat.main

后端服务特性

热重载: 开发时自动重启
调试模式: 显示详细错误信息
健康检查: /health端点可用

2. 前端服务启动

bash

cd src/frontend
npm run dev

前端服务特性

热重载: 文件变更自动刷新
TypeScript支持: 类型安全开发
Vue DevTools: 浏览器扩展支持

3. 单独启动各组件

数据库初始化

bash

cd src/backend
python -c "
from agentchat.database.init_data import init_database, init_default_agent
import asyncio
asyncio.run(init_database())
asyncio.run(init_default_agent())
print('数据库初始化完成')
"

Redis缓存服务

bash

# 启动Redis (如果未启动)
redis-server

向量数据库服务

bash

# ChromaDB (本地模式)
python -c "
import chromadb
client = chromadb.Client()
print('ChromaDB连接成功')
"

# Milvus (需要单独安装和配置)

章节来源

环境变量配置

1. 配置文件优先级

AgentChat使用YAML配置文件，支持以下配置方式：

图表来源

src/backend/agentchat/settings.py

2. 关键配置项

数据库连接配置

yaml

mysql:
  endpoint: "${MYSQL_ENDPOINT:-mysql+pymysql://root:password@localhost:3306/agentchat}"
  async_endpoint: "${ASYNC_MYSQL_ENDPOINT:-mysql+aiomysql://root:password@localhost:3306/agentchat}"

redis:
  endpoint: "${REDIS_ENDPOINT:-redis://localhost:6379}"

LLM API配置

yaml

multi_models:
  conversation_model:
    api_key: "${OPENAI_API_KEY:-your-api-key-here}"
    base_url: "${OPENAI_BASE_URL:-https://api.openai.com/v1}"
    model_name: "${CONVERSATION_MODEL:-gpt-4}"

向量数据库配置

yaml

rag:
  vector_db:
    mode: "${VECTOR_DB_MODE:-chroma}"  # chroma, milvus
    host: "${VECTOR_DB_HOST:-localhost}"
    port: "${VECTOR_DB_PORT:-19530}"

3. 环境变量设置

Windows PowerShell

powershell

$env:MYSQL_ENDPOINT="mysql+pymysql://root:password@localhost:3306/agentchat"
$env:REDIS_ENDPOINT="redis://localhost:6379"
$env:OPENAI_API_KEY="your-api-key-here"

Windows CMD

cmd

set MYSQL_ENDPOINT=mysql+pymysql://root:password@localhost:3306/agentchat
set REDIS_ENDPOINT=redis://localhost:6379
set OPENAI_API_KEY=your-api-key-here

Linux/macOS Bash

bash

export MYSQL_ENDPOINT="mysql+pymysql://root:password@localhost:3306/agentchat"
export REDIS_ENDPOINT="redis://localhost:6379"
export OPENAI_API_KEY="your-api-key-here"

4. 配置文件模板

创建.env文件（可选）：

bash

# 数据库配置
MYSQL_ENDPOINT=mysql+pymysql://root:password@localhost:3306/agentchat
ASYNC_MYSQL_ENDPOINT=mysql+aiomysql://root:password@localhost:3306/agentchat

# 缓存配置
REDIS_ENDPOINT=redis://localhost:6379

# LLM配置
OPENAI_API_KEY=your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
CONVERSATION_MODEL=gpt-4

# 向量数据库
VECTOR_DB_MODE=chroma
VECTOR_DB_HOST=localhost
VECTOR_DB_PORT=19530

章节来源

环境搭建 ​

目录 ​

简介 ​

前置要求 ​

系统要求 ​

必需软件 ​

可选但推荐 ​

项目结构概览 ​

Python环境配置 ​

1. 创建虚拟环境 ​

方法一：使用Python venv ​

方法二：使用Conda ​

2. 安装依赖 ​

方式一：使用Poetry (推荐) ​

方式二：使用pip ​

依赖项详情 ​

Node.js和前端依赖 ​

1. 安装Node.js ​

2. 安装前端依赖 ​

3. 前端技术栈 ​

4. 前端脚本命令 ​

数据库和服务配置 ​

1. 数据库配置 ​

MySQL配置 ​

Redis配置 ​

2. 向量数据库配置 ​

ChromaDB配置 ​

Milvus配置 ​

3. 外部服务配置 ​

LLM服务配置 ​

工具服务配置 ​

4. 配置文件结构 ​

启动开发环境 ​

1. 使用自动化脚本启动 ​

启动步骤 ​

脚本执行流程 ​

脚本功能特性 ​

2. 服务访问地址 ​

3. 启动验证 ​

常见问题解决 ​

1. 依赖安装失败 ​

问题现象 ​

解决方案 ​

2. 端口冲突 ​

问题现象 ​

解决方案 ​

3. Node.js相关问题 ​

问题：npm不是内部或外部命令 ​

问题：前端依赖安装失败 ​

4. 数据库连接问题 ​

MySQL连接失败 ​

Redis连接失败 ​

5. 向量数据库连接问题 ​

ChromaDB连接失败 ​

Milvus连接失败 ​

6. 权限问题 ​

Windows权限问题 ​

Unix/Linux权限问题 ​

手动启动方式 ​

1. 后端服务启动 ​

方法一：使用Uvicorn直接启动 ​

方法二：使用Python直接运行 ​

后端服务特性 ​

2. 前端服务启动 ​

前端服务特性 ​

3. 单独启动各组件 ​

数据库初始化 ​

Redis缓存服务 ​

向量数据库服务 ​

环境变量配置 ​

1. 配置文件优先级 ​

2. 关键配置项 ​

数据库连接配置 ​

LLM API配置 ​

向量数据库配置 ​

3. 环境变量设置 ​

Windows PowerShell ​

Windows CMD ​

Linux/macOS Bash ​

4. 配置文件模板 ​

环境搭建

目录

简介

前置要求

系统要求

必需软件

可选但推荐

项目结构概览

Python环境配置

1. 创建虚拟环境

方法一：使用Python venv

方法二：使用Conda

2. 安装依赖

方式一：使用Poetry (推荐)

方式二：使用pip

依赖项详情

Node.js和前端依赖

1. 安装Node.js

2. 安装前端依赖

3. 前端技术栈

4. 前端脚本命令

数据库和服务配置

1. 数据库配置

MySQL配置

Redis配置

2. 向量数据库配置

ChromaDB配置

Milvus配置

3. 外部服务配置

LLM服务配置

工具服务配置

4. 配置文件结构

启动开发环境

1. 使用自动化脚本启动

启动步骤

脚本执行流程

脚本功能特性

2. 服务访问地址

3. 启动验证

常见问题解决

1. 依赖安装失败

问题现象

解决方案

2. 端口冲突

问题现象

解决方案

3. Node.js相关问题

问题：npm不是内部或外部命令

问题：前端依赖安装失败

4. 数据库连接问题

MySQL连接失败

Redis连接失败

5. 向量数据库连接问题

ChromaDB连接失败

Milvus连接失败

6. 权限问题

Windows权限问题

Unix/Linux权限问题

手动启动方式

1. 后端服务启动

方法一：使用Uvicorn直接启动

方法二：使用Python直接运行

后端服务特性

2. 前端服务启动

前端服务特性

3. 单独启动各组件

数据库初始化

Redis缓存服务

向量数据库服务

环境变量配置

1. 配置文件优先级

2. 关键配置项

数据库连接配置

LLM API配置

向量数据库配置

3. 环境变量设置

Windows PowerShell

Windows CMD

Linux/macOS Bash

4. 配置文件模板