ailine/README.md

# AI Agent - 智能助手系统

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

---

## 🎯 核心功能

### 面向用户的功能

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

### 技术特性

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

---

## 🏗️ 技术架构

### 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| **LLM 服务** | 智谱 AI API / vLLM (Gemma-4) | 云端 API 或本地推理 |
| **Embedding** | 智谱 Embedding API | 向量嵌入（无需 PyTorch） |
| **Agent 框架** | LangGraph + LangChain | 工作流编排 |
| **向量数据库** | ChromaDB / pgvector | 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│  │
│  │ - RAG      │  │
│  └────────────┘  │
└────────┬─────────┘
         │
    ┌────┴────┐
    ↓         ↓
┌────────┐ ┌──────────┐
│PostgreSQL│ │ChromaDB  │
│(记忆存储)│ │(向量检索)│
└────────┘ └──────────┘
```

### 项目结构

```
Agent1/
├── agent.py              # Agent 服务核心（多模型管理）
├── graph_builder.py      # LangGraph 状态图构建器
├── tools.py              # 工具函数定义（@tool 装饰器）
├── backend.py            # FastAPI 后端应用
├── frontend.py           # Streamlit 前端界面
├── rag_example.py        # RAG 实现示例（无 PyTorch）
├── 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（推荐）

```
# 1. 配置环境变量
cp .env.example .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://localhost:8501
#   - 后端 API: http://localhost:8001
```

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

```
# 1. 启动 PostgreSQL
docker run -d --name postgres-langgraph \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=langgraph_db \
  -p 5432:5432 postgres:16

# 2. 安装依赖
pip install -r requirement.txt

# 3. 启动后端
python backend.py

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

---

## 📖 使用指南

### 基础对话

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

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

### 工具调用示例

| 功能 | 示例提问 |
|------|---------|
| 🌤️ 天气查询 | "上海今天天气如何？" |
| 📄 读取文本 | "读取 a.txt 的内容" |
| 📑 解析 PDF | "总结 b.pdf 的主要内容" |
| 📊 Excel 数据 | "显示 c.xlsx 的数据" |
| 🌐 网页抓取 | "抓取 https://example.com 的内容" |
| 🔍 知识库检索 | "根据知识库回答：XXX" |

### 多模型切换

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

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

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

---

## 🔧 开发指南

### 添加新工具

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

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

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

### 添加新模型

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

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

### Docker 部署

项目包含完整的 Docker 配置：

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

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

---

## ⚙️ 环境配置

### 配置文件说明

项目使用两个环境配置文件：

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

**使用方法：**

- **本地开发**：手动创建 `.env`，配置 `localhost` 相关地址
- **Docker 部署**：`cp .env.docker .env`，然后修改 API Key

### 必需的环境变量

代码中所有使用 `os.getenv()` 的地方都必须在 `.env` 文件中定义：

| 变量名 | 说明 | 本地开发示例 | Docker 部署示例 |
|--------|------|------------|----------------|
| `ZHIPUAI_API_KEY` | 智谱 AI API 密钥 | `your_key_here` | `your_key_here` |
| `VLLM_LOCAL_KEY` | vLLM 认证 Token | `token-abc123` | `token-abc123` |
| `VLLM_BASE_URL` | vLLM 服务地址 | `http://localhost:8000/v1` | `http://115.190.121.151:18000/v1` |
| `DB_URI` | PostgreSQL 连接字符串 | `postgresql://...@localhost:5432/...` | `postgresql://...@postgres:5432/...` |
| `API_URL` | 后端 API 地址 | `http://localhost:8001/chat` | （由 docker-compose.yml 注入） |

### 配置示例

#### 本地开发 (.env)
```bash
ZHIPUAI_API_KEY=your_api_key_here
VLLM_LOCAL_KEY=token-abc123
VLLM_BASE_URL=http://localhost:8000/v1
DB_URI=postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db?sslmode=disable
API_URL=http://localhost:8001/chat
```

#### Docker 部署 (.env.docker)
```bash
ZHIPUAI_API_KEY=your_api_key_here
VLLM_LOCAL_KEY=token-abc123
VLLM_BASE_URL=http://115.190.121.151:18000/v1
DB_URI=postgresql://postgres:mysecretpassword@postgres:5432/langgraph_db?sslmode=disable
# API_URL 在 docker-compose.yml 中配置为 http://backend:8001/chat
```

### 注意事项

- ⚠️ **不要硬编码敏感信息**：所有 API Key 必须通过环境变量配置
- ⚠️ **Docker 网络差异**：容器内使用服务名（如 `postgres`、`backend`），本地使用 `localhost`
- ⚠️ **修改后重启**：修改 `.env` 后，Docker 部署需要执行 `docker compose down && docker compose up -d --build`

---

## 🐛 故障排查

### 常见问题

**Q: 无法连接 PostgreSQL？**
```bash
# 检查容器状态
docker ps | grep postgres

# 查看日志
docker logs postgres-langgraph
```

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

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

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

---

## 📝 许可证

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

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！