# pagent

**Repository Path**: wdfe/pagent

## Basic Information

- **Project Name**: pagent
- **Description**: element plus + langchain + fastapi写的一个ai agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent System

一个功能完整的AI助手系统,支持知识库管理、Skill管理、多模型切换和智能对话功能。

## 功能特性

- **用户认证**: 多用户系统,JWT Token认证
- **模型管理**: 支持OpenAI、Anthropic、Ollama等多种模型提供商
- **知识库**: 
  - 🆕 基于ChromaDB的向量数据库
  - 🆕 支持两种嵌入模型切换(本地/云端)
  - 文档上传、混合检索(向量+关键词)、RAG增强回答
- **Skill系统**: 自定义AI行为和提示词
- **智能对话**: 流式输出、上下文管理、历史会话

## 技术栈

### 后端
- Python 3.10+
- FastAPI
- LangChain
- 🆕 ChromaDB (向量数据库)
- 🆕 SentenceTransformer / DashScope (嵌入模型)
- JWT认证

### 前端
- Vue 3
- Vite
- Element Plus
- Pinia
- Vue Router

## 快速开始

### 1. 环境要求

- Python 3.10+
- Node.js 18+
- npm 9+

### 2. 后端启动

```bash
# 进入项目目录
cd Aiagent

# 运行启动脚本(会自动安装依赖)
./start.sh
```

或者手动启动:

```bash
cd app
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

后端服务将运行在: http://localhost:8000
API文档: http://localhost:8000/docs

### 3. 前端启动

```bash
cd frontend
npm install
npm run dev
```

前端应用将运行在: http://localhost:5173

### 4. 配置环境变量

复制 `.env.example` 为 `.env` 并修改配置:

```bash
cp .env.example .env
```

编辑 `.env` 文件,设置SECRET_KEY等配置。

## 使用指南

### 第一步: 注册用户

访问 http://localhost:5173,点击注册创建账号。

### 第二步: 配置模型

1. 进入"模型设置"页面
2. 添加模型提供商(如OpenAI)
3. 输入API Key
4. 设为默认提供商

### 第三步: 上传知识(可选)

1. 进入"知识库"页面
2. 创建知识库集合
3. 上传文档(PDF/TXT/MD/DOCX)

### 第四步: 开始对话

1. 进入"聊天"页面
2. 选择模型和Skill(可选)
3. 开启"使用知识库"(可选)
4. 开始与AI对话

## 项目结构

```
Aiagent/
├── app/                    # 后端代码
│   ├── api/               # API路由
│   ├── core/              # 核心模块(认证/安全)
│   ├── services/          # 业务逻辑
│   ├── models/            # 数据模型
│   ├── storage/           # 数据存储
│   ├── utils/             # 工具函数
│   ├── main.py            # 应用入口
│   └── requirements.txt   # Python依赖
│
├── frontend/              # 前端代码
│   ├── src/
│   │   ├── api/          # API接口
│   │   ├── views/        # 页面视图
│   │   ├── components/   # 组件
│   │   ├── stores/       # 状态管理
│   │   └── router/       # 路由
│   └── package.json
│
├── workspace/             # 数据存储目录
│   ├── users.json         # 用户数据
│   ├── knowledge_base/    # 知识库元数据
│   ├── chromadb/          # 🆕 ChromaDB向量数据
│   ├── skills/            # Skills
│   ├── models/            # 模型配置
│   └── chats/             # 聊天记录
│
├── .env.example           # 环境变量示例
├── EMBEDDING_SWITCH_GUIDE.md  # 🆕 嵌入模型切换指南
├── QUICK_REFERENCE.md     # 🆕 快速参考卡片
└── start.sh              # 启动脚本
```

## 🆕 知识库系统升级 (v2.0)

### 新特性

1. **ChromaDB向量数据库**
   - 替代原有的FAISS实现
   - 支持持久化存储和高效检索
   - 自动集合管理

2. **双嵌入模型支持**
   - **本地模型**: SentenceTransformer (384维)
   - **云端模型**: 阿里云DashScope multimodal-embedding-v1 (1024维)
   - 通过环境变量 `EMBEDDING_PROVIDER` 轻松切换

3. **增强的检索算法**
   - 向量检索: ChromaDB余弦相似度
   - 关键词检索: BM25算法
   - 结果融合: RRF (Reciprocal Rank Fusion)

4. **多模态预留接口**
   - 为未来的图片上传和检索预留扩展点
   - 使用multimodal-embedding-v1天然支持多模态

### 快速切换嵌入模型

```bash
# 方法1: 修改.env文件
EMBEDDING_PROVIDER=local      # 切换到本地模型
EMBEDDING_PROVIDER=dashscope  # 切换到阿里云(默认)

# 方法2: 调用API
curl -X POST http://localhost:8000/api/knowledge/switch-embedding-provider \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"provider": "local"}'
```

详细文档请查看:
- [EMBEDDING_SWITCH_GUIDE.md](EMBEDDING_SWITCH_GUIDE.md) - 完整切换指南
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - 快速参考
- [UPGRADE_SUMMARY.md](UPGRADE_SUMMARY.md) - 升级总结

## API端点

### 认证
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `GET /api/auth/me` - 获取当前用户

### 模型管理
- `GET /api/models/providers` - 获取提供商列表
- `POST /api/models/providers` - 添加提供商
- `PUT /api/models/active` - 设置活跃提供商
- `GET /api/models/list` - 获取可用模型

### 知识库
- `GET /api/knowledge/collections` - 获取知识库列表
- `POST /api/knowledge/collections` - 创建知识库
- `POST /api/knowledge/upload` - 上传文档
- `POST /api/knowledge/search` - 搜索文档
- 🆕 `GET /api/knowledge/embedding-info` - 获取嵌入模型信息
- 🆕 `POST /api/knowledge/switch-embedding-provider` - 切换嵌入模型

### Skills
- `GET /api/skills/` - 获取Skills列表
- `POST /api/skills/` - 创建Skill
- `PUT /api/skills/{id}` - 更新Skill
- `POST /api/skills/{id}/test` - 测试Skill

### 聊天
- `GET /api/chat/sessions` - 获取会话列表
- `POST /api/chat/sessions` - 创建会话
- `POST /api/chat/completions` - 发送消息
- `POST /api/chat/stream` - 流式发送消息

## 注意事项

1. **API Key安全**: API Key会加密存储在本地,请妥善保管`.env`文件中的ENCRYPTION_KEY
2. **存储空间**: 所有数据存储在`workspace`目录,定期备份重要数据
3. **内存占用**: 向量化过程需要较多内存,建议至少4GB可用内存
4. **模型成本**: 使用商业API会产生费用,注意控制调用次数

## 故障排除

### 后端启动失败
- 检查Python版本是否>=3.10
- 检查依赖是否完整安装: `pip install -r requirements.txt`
- 检查端口8000是否被占用

### 前端启动失败
- 检查Node.js版本是否>=18
- 清除node_modules重新安装: `rm -rf node_modules && npm install`
- 检查端口5173是否被占用

### 聊天无响应
- 检查模型配置是否正确
- 检查API Key是否有效
- 查看浏览器控制台和后端日志
常用的国内镜像源：
清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
阿里云：https://mirrors.aliyun.com/pypi/simple/
豆瓣：https://pypi.douban.com/simple/
中科大：https://pypi.mirrors.ustc.edu.cn/simple/

## 许可证

MIT License