# ai_agent

**Repository Path**: leke_code/ai_agent

## Basic Information

- **Project Name**: ai_agent
- **Description**: 🤖 基于 FastAPI + Deep Agents + RAG 的智能客服系统

- 💬 多轮对话：支持上下文对话历史
- 📚 RAG 问答：基于知识库的智能问答
- ⚡ 流式输出：SSE 实时流式返回
- 🔍 向量检索：FAISS 相似度/MMR 检索
- 🌐 RESTful API：完整接口 + Gradio Web UI

支持智谱AI (GLM-4) / OpenAI 模型
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 AI 智能客服系统

基于 **FastAPI + Deep Agents + RAG + Weaviate** 的智能客服系统，提供 RESTful API 接口和 Web 界面。

## ✨ 功能特性

### 核心功能
- **📚 RAG 问答**: 基于用户手册进行智能问答
- **💬 多轮对话**: 支持上下文对话历史
- **⚡ 流式输出**: Server-Sent Events 实时流式返回
- **🔍 知识库搜索**: 支持相似度和 MMR 检索
- **📊 反馈管理**: 收集和分析用户反馈
- **✍️ 文章生成**: 基于智谱大模型的智能文章生成（支持流式/非流式）

### 技术架构
- **FastAPI 后端**: 高性能异步 API 框架
- **Deep Agents**: 基于 LangGraph 的 Agent 编排
- **LangChain**: 核心编排框架
- **Weaviate**: 远程向量数据库存储
- **Gradio**: Web 测试界面
- **Docker**: 容器化部署

### 支持的模型
- **LLM**: 智谱AI (glm-4.7, glm-4-plus, glm-4-flash)、OpenAI (gpt-4o, gpt-4o-mini)
- **Embedding**: OpenAI (text-embedding-3-small, text-embedding-3-large)、智谱AI (embedding-3)

## 📁 项目结构

```
ai_agent/
├── api/                        # FastAPI API 层
│   ├── main.py                 # 应用入口
│   ├── api/v1/                 # API 路由
│   │   ├── chat.py             # 对话接口
│   │   ├── knowledge.py        # 知识库接口
│   │   ├── session.py          # 会话管理
│   │   ├── feedback.py         # 反馈管理
│   │   └── system.py           # 系统信息
│   └── middleware/             # 中间件
│       ├── auth.py             # API Key 认证
│       ├── logging.py          # 日志记录
│       ├── cors.py             # 跨域配置
│       └── error_handler.py    # 错误处理
│
├── core/                       # 核心业务逻辑
│   ├── agent.py                # Agent 总入口（门面）
│   ├── agent_manager.py        # Agent 单例管理
│   ├── agents/                 # 智能体模块
│   │   ├── base.py             # 抽象基类
│   │   ├── customer_support.py # 客服智能体 + RAG 工具
│   │   └── zhipu_article_agent.py # 智谱文章生成智能体
│   ├── vector/                 # 向量存储模块
│   │   ├── base.py             # 抽象基类 + 工厂
│   │   └── weaviate_store.py   # Weaviate 实现
│   └── llm/                    # LLM 封装模块
│       ├── base.py             # 抽象基类 + 工厂
│       ├── openai_compatible.py# OpenAI 兼容实现
│       └── zhipu_llm.py        # 智谱 AI 实现
│
├── services/                   # 服务层
│   ├── chat_service.py         # 对话服务
│   ├── article_service.py      # 文章生成服务
│   ├── knowledge_service.py    # 知识库服务
│   ├── session_service.py      # 会话服务
│   └── feedback_service.py     # 反馈服务
│
├── models/                     # 数据模型
│   └── schemas/                # Pydantic 模型
│       ├── chat.py
│       ├── article.py          # 文章生成模型
│       ├── knowledge.py
│       ├── session.py
│       ├── feedback.py
│       └── system.py
│
├── config/                     # 配置管理
│   ├── settings.py             # Pydantic Settings
│   ├── logging_config.py       # 日志配置
│   ├── constants.py            # 常量定义
│   └── __init__.py
│
├── ui/                         # Gradio Web UI
│   ├── web.py
│   └── __init__.py
│
├── utils/                      # 工具模块
│   ├── env_loader.py           # 环境变量加载
│   ├── build_weaviate_store.py # Weaviate 向量库构建
│   ├── weaviate_retriever.py   # Weaviate 检索器
│   └── weaviate_viewer.py      # Weaviate GUI 查看器
│
├── component/                  # 组件模块
│   └── __init__.py
│
├── docker/                     # Docker 配置
│   ├── Dockerfile
│   └── docker-compose.yml
│
├── docs/                       # 文档
│   ├── core_analysis.md        # Core 模块分析
│   ├── circular_dependency_analysis.md # 循环依赖分析
│   ├── api.md                  # API 文档
│   └── deployment.md           # 部署文档
│
├── data/                       # 数据目录
│   ├── manuals/                # 用户手册
│   └── feedback/               # 反馈数据
│
├── examples/                   # 示例代码
│   └── frontend_article_generation.html # 文章生成前端示例
│
├── main.py                     # FastAPI 启动入口
├── run.py                      # 命令行/Web 模式入口
├── config.yaml                 # 配置文件
├── requirements.txt            # 依赖列表
└── .env.example                # 环境变量模板
```

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

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

编辑 `.env` 文件：

```env
# 智谱AI (LLM)
ZHIPUAI_API_KEY=your_zhipu_api_key_here

# OpenAI (Embedding)
OPENAI_API_KEY=your_openai_api_key_here

# API 认证（可选，生产环境建议设置）
API_KEY=your_api_key_here
```

### 3. 构建向量数据库

**首次使用必须先构建 Weaviate 向量数据库：**

```bash
python -m utils.build_weaviate_store
```

**强制重建：**

```bash
python -m utils.build_weaviate_store --force
```

### 4. 启动服务

**FastAPI 模式（推荐）：**

```bash
# 开发模式（自动重载）
python main.py --env dev --reload

# 生产模式
python main.py --env prod --workers 4
```

访问：
- **API 文档**: http://localhost:8000/docs
- **Gradio UI**: http://localhost:8000/gradio
- **健康检查**: http://localhost:8000/health
- **前端示例**: http://localhost:8080/frontend_article_generation.html（需单独启动）

启动前端示例服务器：
```bash
python -m http.server 8080 --directory examples
```

**原有模式（兼容）：**

```bash
# 命令行模式
python run.py --mode cli

# Web 界面模式（独立端口 7860）
python run.py --mode web
```

## 📡 API 接口

### 对话接口

**POST** `/api/v1/chat` - 同步对话

```bash
curl -X POST http://localhost:8000/api/v1/chat \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "如何发布文章？", "session_id": "user_123"}'
```

**POST** `/api/v1/chat/stream` - 流式对话 (SSE)

```bash
curl -X POST http://localhost:8000/api/v1/chat/stream \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "如何发布文章？", "session_id": "user_123"}' \
  --no-buffer
```

### 文章生成接口

**POST** `/api/v1/chat/article/generate` - 非流式文章生成

```bash
curl -X POST http://localhost:8000/api/v1/chat/article/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "写一篇关于人工智能未来发展趋势的文章",
    "domain": "AI",
    "max_length": 2000,
    "temperature": 0.7,
    "style": "professional",
    "language": "zh-CN"
  }'
```

响应示例：
```json
{
  "article": "人工智能（AI）正在快速改变我们的世界...",
  "word_count": 1856,
  "title": "人工智能的未来发展趋势",
  "summary": "本文探讨了AI技术的最新进展...",
  "metadata": {
    "model": "glm-4.7",
    "duration_ms": 3200,
    "style": "professional",
    "domain": "AI"
  }
}
```

**POST** `/api/v1/chat/article/generate/stream` - 流式文章生成 (SSE)

```bash
curl -X POST http://localhost:8000/api/v1/chat/article/generate/stream \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "写一篇关于区块链技术的介绍文章",
    "domain": "区块链",
    "max_length": 2000
  }' --no-buffer
```

SSE 响应格式：
```
data: {"content": "文章片段1", "done": false, "word_count": 50}

data: {"content": "文章片段2", "done": false, "word_count": 100}

data: {"content": "", "done": true, "word_count": 2000}

```

#### 文章生成参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `prompt` | string | 是 | - | 文章提示词/主题 |
| `domain` | string | 否 | null | 文章领域：AI/前端/后端/数据库/云计算/DevOps/安全/移动开发/区块链/知识文献/SpringBoot/SpringCloud/其他 |
| `max_length` | int | 否 | 2000 | 最大字数（100-10000） |
| `temperature` | float | 否 | 0.7 | 创意程度（0-1） |
| `style` | string | 否 | professional | 文章风格：professional/casual/academic/creative |
| `language` | string | 否 | zh-CN | 语言：zh-CN/en-US |
| `keywords` | array | 否 | null | 需要包含的关键词列表 |

### 其他接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/chat/article/generate` | 生成文章（非流式） |
| POST | `/api/v1/chat/article/generate/stream` | 生成文章（流式SSE） |
| GET | `/api/v1/knowledge/search` | 搜索知识库 |
| GET | `/api/v1/knowledge/manual` | 获取手册章节 |
| DELETE | `/api/v1/sessions/{id}` | 清除会话历史 |
| POST | `/api/v1/feedback` | 提交反馈 |
| GET | `/api/v1/system/info` | 系统信息 |
| GET | `/health` | 健康检查 |

详细 API 文档请参考：[docs/api.md](docs/api.md)

## 🐳 Docker 部署

### 使用 Docker Compose（推荐）

```bash
# 配置环境变量
cp .env.example .env
nano .env

# 构建向量库
docker-compose run --rm ai-support python -m utils.build_weaviate_store

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f
```

详细部署文档请参考：[docs/deployment.md](docs/deployment.md)

## ⚙️ 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ZHIPUAI_API_KEY` | 智谱AI API Key | - |
| `OPENAI_API_KEY` | OpenAI API Key | - |
| `API_KEY` | API 认证密钥 | 无（跳过认证） |
| `LOG_LEVEL` | 日志级别 | INFO |
| `DEBUG` | 调试模式 | false |
| `GRADIO_ENABLED` | 启用 Gradio UI | true |

### config.yaml 配置

```yaml
# LLM 配置
llm:
  provider: zhipu          # zhipu, openai
  model: glm-4.7
  temperature: 0.3

# Embedding 配置
embeddings:
  provider: openai         # openai, zhipu
  model: text-embedding-3-small

# 检索器配置
retriever:
  search_type: mmr         # similarity, mmr
  k: 5                     # 返回文档数
  lambda_mult: 0.5         # 多样性权重

# Weaviate 配置
weaviate:
  url: http://101.201.32.11:8080
  index_name: KnowledgeBase
```

## 📝 Python API 使用

```python
from core.agent import create_agent

# 初始化
agent = create_agent()

# 同步对话
response = agent.respond("如何注册账号？")
print(response)

# 流式对话
for chunk in agent.respond_stream("如何发布文章？"):
    print(chunk, end="", flush=True)

# 多轮对话
response = agent.respond("怎么登录？", session_id="user_123")
response = agent.respond("忘记密码？", session_id="user_123")
```

## 📖 文档

- [Core 模块分析](docs/core_analysis.md) - 核心架构详细说明
- [API 文档](docs/api.md) - RESTful API 详细说明
- [部署文档](docs/deployment.md) - Docker 和云服务器部署指南

## 📝 文章生成功能架构

文章生成功能采用**单一职责原则**设计的分层架构：

```
┌─────────────────────────────────────────────────────────────┐
│                        API Layer                             │
│  chat.py - 路由定义、请求校验、响应封装                       │
│  POST /api/v1/chat/article/generate                         │
│  POST /api/v1/chat/article/generate/stream                  │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│                      Service Layer                           │
│  article_service.py - 业务编排、异常处理、日志记录           │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│                       Agent Layer                            │
│  zhipu_article_agent.py - 模型调用、提示词构建、响应解析     │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│                       LLM Layer                              │
│  zhipu_llm.py - 智谱 API 通信                                │
└─────────────────────────────────────────────────────────────┘
```

### 核心模块说明

| 模块 | 职责 | 文件 |
|------|------|------|
| **API 层** | 定义 REST 接口、参数校验、SSE 流式响应 | `api/api/v1/chat.py` |
| **Service 层** | 业务逻辑编排、调用 Agent、封装响应 | `services/article_service.py` |
| **Agent 层** | 文章生成策略、提示词工程、标题/摘要提取 | `core/agents/zhipu_article_agent.py` |
| **Schema 层** | 请求/响应数据模型定义 | `models/schemas/article.py` |

### 支持的文章风格

- **professional**: 专业严谨，适合正式文档
- **casual**: 轻松易懂，适合博客文章
- **academic**: 学术论文风格，包含理论分析
- **creative**: 创意写作，运用比喻和独特视角

### 前端集成示例

前端示例位于 `examples/frontend_article_generation.html`，展示了：
- 非流式接口调用（一次性获取完整文章）
- 流式接口调用（SSE 实时接收内容）
- 参数配置界面（风格、语言、字数等）
- 元数据展示（标题、摘要、字数、耗时）

## 🔧 开发

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_api/

# 生成覆盖率报告
pytest --cov=.
```

### 代码结构

- **api/**: FastAPI 路由和中间件
- **services/**: 业务逻辑服务层
- **models/**: Pydantic 数据模型
- **config/**: 配置管理
- **core/**: 核心 Agent、向量存储、LLM 封装

## 📄 许可证

MIT License