ailine/README.md

# AI Agent - 智能助手系统

一个基于 LangGraph + FastAPI 的智能对话助手，支持多模型切换、RAG 知识库检索、文件处理和网页抓取等功能。

---

## 🎯 核心功能

### 面向用户的功能

- 💬 **智能对话**：支持多轮对话，自动记忆上下文
- 🌤️ **天气查询**：实时获取各地天气信息
- 📄 **文档处理**：读取 TXT、PDF、Excel 等格式文件
- 🌐 **网页抓取**：提取网页正文内容
- 🔍 **知识库检索（RAG）**：基于向量数据库的智能问答
- 🔄 **多模型切换**：前端可选择不同大语言模型

### 技术特性

- ✅ **持久化记忆**：PostgreSQL 存储对话历史，重启不丢失
- ✅ **高可用架构**：模型自动降级，确保服务稳定
- ✅ **前后端分离**：FastAPI 后端 + Streamlit 前端
- ✅ **Docker 部署**：一键启动所有服务
- ✅ **远程服务架构**：PostgreSQL 和 Qdrant 部署在远程服务器

---

## 🏗️ 技术架构

### 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| **LLM 服务** | 智谱 AI API / llama.cpp (Gemma-4 GGUF) | 云端 API 或本地推理 |
| **Embedding** | llama.cpp (embeddinggemma-300M GGUF) | 本地向量嵌入服务 |
| **Agent 框架** | LangGraph + LangChain | 工作流编排 |
| **向量数据库** | Qdrant | RAG 知识检索（远程服务器） |
| **后端框架** | FastAPI + Uvicorn | RESTful API + WebSocket |
| **前端框架** | Streamlit | 交互式 Web 界面 |
| **数据库** | PostgreSQL 16 | 对话记忆持久化（远程服务器） |
| **容器化** | Docker + Docker Compose | 服务编排 |

### 架构图

```
┌──────────────┐
│   用户浏览器   │  Streamlit 前端 (8501)
└──────┬───────┘
       │ HTTP/WebSocket
       ↓
┌──────────────────┐
│  FastAPI 后端     │  端口 8001
│  ┌────────────┐  │
│  │ AIAgent    │  │  多模型管理
│  └─────┬──────┘  │
│        │          │
│  ┌─────▼──────┐  │
│  │LangGraph   │  │  工作流引擎
│  │ StateGraph │  │
│  └─────┬──────┘  │
│        │          │
│  ┌─────▼──────┐  │
│  │ Tools      │  │  工具集合
│  │ - Weather  │  │
│  │ - File IO  │  │
│  │ - Web Scrap│  │
│  │ - Memory   │  │
│  └────────────┘  │
└────────┬─────────┘
         │
    ┌────┴────────────────────┐
    ↓                         ↓
┌──────────────┐    ┌──────────────┐
│  PostgreSQL  │    │   Qdrant     │
│ (远程服务器)  │    │ (远程服务器)  │
│  115.190...  │    │  115.190...  │
└──────────────┘    └──────────────┘
```

### 项目结构

```
Agent1/
├── app/
│   ├── __init__.py
│   ├── config.py              # 配置管理
│   ├── state.py               # 状态定义
│   ├── prompts.py             # 提示模板
│   ├── logger.py              # 日志工具
│   ├── tools.py               # 工具函数定义
│   ├── memory/
│   │   ├── __init__.py
│   │   └── mem0_client.py     # Mem0 客户端封装
│   ├── nodes/
│   │   ├── __init__.py
│   │   ├── router.py          # 路由决策
│   │   ├── llm_call.py        # LLM 调用节点
│   │   ├── tool_call.py       # 工具执行节点
│   │   ├── retrieve_memory.py # 记忆检索节点
│   │   └── summarize.py       # 记忆存储节点
│   ├── graph_builder.py       # LangGraph 图构建器
│   ├── agent.py               # Agent 服务核心
│   └── backend.py             # FastAPI 后端应用
├── frontend/
│   └── app.py                 # Streamlit 前端界面
├── docker/
│   ├── docker-compose.yml     # Docker 服务编排
│   ├── Dockerfile.backend     # 后端镜像构建
│   └── Dockerfile.frontend    # 前端镜像构建
├── requirement.txt            # Python 依赖
├── .env                       # 环境变量配置
└── user_docs/                 # 用户文档目录
    ├── a.txt
    ├── b.pdf
    └── c.xlsx
```

---

## 🚀 快速开始

详细启动指南请查看 [QUICKSTART.md](QUICKSTART.md)

### 方式一：Docker Compose（推荐）

```bash
# 1. 配置环境变量
cp .env.docker .env
# 编辑 .env 文件，填入真实的 API Key

# 2. 启动所有服务
docker compose -f docker/docker-compose.yml up -d --build

# 3. 访问应用
# 如果配置了 Nginx 反向代理：http://your-domain.com 或 http://your-server-ip
# 如果未配置 Nginx（直接访问）：
#   - 前端: http://127.0.0.1:8501
#   - 后端 API: http://127.0.0.1:8001
```

### 方式二：本地开发模式

```bash
# 1. 安装依赖
pip install -r requirement.txt

# 2. 配置环境变量
cp .env.docker .env
# 编辑 .env，根据本地/远程环境调整配置

# 3. 启动后端
python app/backend.py

# 4. 启动前端（新终端）
cd frontend && streamlit run app.py
```

---

## 📖 使用指南

### 基础对话

直接在聊天框输入问题即可：

```
你好，请介绍一下自己
今天北京天气怎么样？
帮我总结一下 a.txt 的内容
```

### 工具调用示例

| 功能 | 示例提问 |
|------|---------|
| 🌤️ 天气查询 | "上海今天天气如何？" |
| 📄 读取文本 | "读取 a.txt 的内容" |
| 📑 解析 PDF | "总结 b.pdf 的主要内容" |
| 📊 Excel 数据 | "显示 c.xlsx 的数据" |
| 🌐 网页抓取 | "抓取 https://example.com 的内容" |
| 🔍 长期记忆 | "记住我喜欢吃川菜" → "我有什么饮食偏好？" |

### 多模型切换

1. 在左侧边栏选择模型：
   - **智谱 GLM-4**：在线服务，速度快
   - **本地 Gemma-4**：本地部署，隐私性好

2. 可随时切换，甚至在同一会话中

3. 点击 "🔄 新会话" 清空当前对话

---

## 🔧 开发指南

### 添加新工具

在 `app/tools.py` 中添加新的 `@tool` 装饰函数：

```python
@tool
def my_new_tool(param: str) -> str:
    """
    工具描述（会显示给 LLM）
    
    Args:
        param: 参数说明
        
    Returns:
        返回值说明
    """
    # 实现逻辑
    return result
```

工具会自动注册到 `AVAILABLE_TOOLS` 列表中。

### 添加新模型

在 `app/agent.py` 的 `initialize()` 方法中添加模型配置：

```python
model_configs = {
    "zhipu": self._create_zhipu_llm,
    "local": self._create_local_llm,
    "new_model": self._create_new_model_llm,  # 添加新模型
}
```

### Docker 部署

项目包含完整的 Docker 配置：

- **docker-compose.yml**：服务编排（Backend + Frontend，连接远程数据库）
- **Dockerfile.backend**：后端镜像构建
- **Dockerfile.frontend**：前端镜像构建
- **.gitea/workflows/deploy.yml**：CI/CD 自动化部署

详见 [QUICKSTART.md](QUICKSTART.md) 的 Docker 部署章节。

---

## ⚙️ 环境配置

### 配置文件说明

项目采用三层环境配置文件体系：

| 文件 | 用途 | 是否提交 Git |
|------|------|------------|
| `.env.example` | 配置模板 | ✅ 是 |
| `.env` | 实际使用的配置 | ❌ 否（已忽略） |
| `.env.docker` | Docker 部署模板 | ✅ 是 |

**使用方法：**

- **本地开发**：`cp .env.example .env`，修改为 127.0.0.1 相关地址
- **Docker 部署**：`cp .env.docker .env`，使用远程服务器地址

### 必需的环境变量

| 变量名 | 说明 | 本地开发示例 | Docker 部署示例 |
|--------|------|------------|----------------|
| `QDRANT_URL` | Qdrant 向量数据库地址 | `http://127.0.0.1:6333` | `http://your-server:6333` |
| `QDRANT_COLLECTION_NAME` | Qdrant 集合名称 | `mem0_user_memories` | `your_collection_name` |
| `VLLM_BASE_URL` | LLM 服务地址（本地） | `http://127.0.0.1:8081/v1` | `http://your-server:8081/v1` |
| `LLAMACPP_EMBEDDING_URL` | Embedding 服务地址（本地） | `http://127.0.0.1:8082/v1` | `http://your-server:8082/v1` |
| `VLLM_BASE_URL` | LLM 服务地址（Docker） | `http://host.docker.internal:18000/v1` | `http://your-server:18000/v1` |
| `LLAMACPP_EMBEDDING_URL` | Embedding 服务地址（Docker） | `http://host.docker.internal:18001/v1` | `http://your-server:18001/v1` |
| `LLAMACPP_API_KEY` | llama.cpp API 密钥 | `your-llamacpp-api-key` | `your-real-api-key` |
| `ZHIPUAI_API_KEY` | 智谱AI API密钥 | `your-zhipuai-api-key` | `your-real-api-key` |
| `DEEPSEEK_API_KEY` | DeepSeek API密钥 | `your-deepseek-api-key` | `your-real-api-key` |
| `VLLM_BASE_URL` | vLLM 服务地址 | `http://127.0.0.1:8081/v1` | `http://your-server:8081/v1` |
| `LOG_LEVEL` | 日志级别 | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR` |
| `ENABLE_GRAPH_TRACE` | 是否启用图流转追踪 | `true` | `true`/`false` |
| `MEMORY_SUMMARIZE_INTERVAL` | 对话摘要生成间隔 | `10` | `5`/`10`/`15` |

### 配置示例

#### 本地开发 (.env)
```
ZHIPUAI_API_KEY=your_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
LLAMACPP_API_KEY=token-abc123
VLLM_BASE_URL=http://127.0.0.1:8081/v1
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1  # 本地开发
# 或
LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1  # Docker容器访问宿主机
QDRANT_URL=http://115.190.121.151:6333
DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
API_URL=http://127.0.0.1:8083/chat
```

#### Docker 部署 (.env.docker)
```
ZHIPUAI_API_KEY=your_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
LLAMACPP_API_KEY=token-abc123
VLLM_BASE_URL=http://127.0.0.1:8081/v1
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1  # 本地开发
# 或
LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1  # Docker容器访问宿主机
QDRANT_URL=http://115.190.121.151:6333
DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
# API_URL 在 docker-compose.yml 中配置为 http://backend:8083/chat
```

### 注意事项

- ⚠️ **不要硬编码敏感信息**：所有 API Key 必须通过环境变量配置
- ⚠️ **远程服务依赖**：确保可以访问远程 PostgreSQL (115.190.121.151:5432) 和 Qdrant (115.190.121.151:6333)
- ⚠️ **修改后重启**：修改 `.env` 后，Docker 部署需要执行 `docker compose down && docker compose up -d --build`

---

## 🐛 故障排查

### 常见问题

**Q: 无法连接远程数据库？**
```bash
# 测试 PostgreSQL
psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT version();"

# 测试 Qdrant
curl http://115.190.121.151:6333/collections
```

**Q: 后端启动失败？**
- 确认端口 8001 未被占用
- 检查 `.env` 中的 API Key 是否正确
- 查看启动日志确认模型初始化成功

**Q: 模型切换后无响应？**
- 检查所选模型的配置是否正确
- 确认 vLLM 容器是否运行（如使用本地模型）
- 尝试切换到另一个模型

更多问题排查请查看 [QUICKSTART.md](QUICKSTART.md)

---

## 📝 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！