# agentTest

**Repository Path**: GrainRain/agent-test

## Basic Information

- **Project Name**: agentTest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentScope 智能问答系统

基于 AgentScope 框架的智能问答系统，采用**单 Agent + 多工具**架构，配备现代化 Web 前端界面。

## 功能特性

- ✅ **知识库问答 (RAG)**: 基于向量检索的增强问答
- ✅ **图片召回**: 检索并返回相关图片
- ✅ **数据分析**: 对检索内容进行汇总和分析
- ✅ **流式输出**: 支持打字机效果的实时响应
- ✅ **现代化 UI**: 类 Gemini 风格的聊天界面

## 快速开始

### 1. 安装后端依赖

```bash
# 安装 Python 依赖
pip install agentscope llama-index-embeddings-openai llama-index-llms-openai fastapi uvicorn

# 或使用 pip3
pip3 install agentscope llama-index-embeddings-openai llama-index-llms-openai fastapi uvicorn
```

### 2. 安装前端依赖

```bash
cd frontend
npm install
```

### 3. 配置 API

编辑 `configs/model_config.json`，填入你的 API Key 和 Base URL：

```json
[
  {
    "config_name": "openai_llm",
    "model_name": "gpt-4o-mini",
    "api_key": "你的API密钥",
    "api_base": "https://api.openai.com/v1",
    "generate_args": {
      "temperature": 0.5
    }
  }
]
```

### 4. 添加知识库（可选）

将文档放入 `data/` 目录（支持 `.txt`, `.md` 格式）。

## 运行系统

### 方式一：前后端分离运行（开发模式）

**启动后端服务：**

```bash
# 在项目根目录运行
python3 api.py
# 或
uvicorn api:app --reload --host 0.0.0.0 --port 8000
```

后端服务将在 http://localhost:8000 启动。

**启动前端服务：**

```bash
# 在另一个终端窗口
cd frontend
npm run dev
```

前端服务将在 http://localhost:5173 启动。

**访问应用：**

打开浏览器访问 http://localhost:5173

### 方式二：命令行模式

如果只需要命令行交互，可以直接运行：

```bash
python3 main.py
```

## 运行测试

### 前端测试

```bash
cd frontend
npm test
```

### 后端测试

```bash
pip3 install pytest hypothesis
python3 -m pytest tests/ -v
```

## 项目结构

```
agent-test/
├── api.py                      # FastAPI 后端服务
├── main.py                     # 命令行入口
├── configs/
│   └── model_config.json       # 模型配置
├── data/
│   ├── documents/              # 原始文档
│   ├── images/                 # 图片资源
│   └── vector_store/           # 向量存储
├── frontend/                   # React 前端
│   ├── src/
│   │   ├── components/         # UI 组件
│   │   ├── hooks/              # React Hooks
│   │   ├── services/           # API 服务
│   │   ├── types/              # TypeScript 类型
│   │   └── utils/              # 工具函数
│   ├── package.json
│   └── vite.config.ts
├── src/
│   ├── agent.py                # ReActAgent 定义
│   ├── tools/
│   │   ├── retriever.py        # 文档检索工具
│   │   ├── image_retriever.py  # 图片检索工具
│   │   └── analyzer.py         # 数据分析工具
│   ├── knowledge/
│   │   ├── loader.py           # 文档加载器
│   │   └── vector_store.py     # 向量存储
│   └── utils/
│       └── embeddings.py       # 向量编码
├── tests/                      # 后端测试
└── docs/
    └── design.md               # 设计文档
```

## API 接口

### POST /chat/stream

流式聊天接口，使用 Server-Sent Events (SSE)。

**请求体：**
```json
{
  "query": "你的问题",
  "history": []
}
```

**SSE 事件类型：**
- `tool_start` - 工具开始执行
- `tool_end` - 工具执行完成
- `content_delta` - 内容增量
- `stream_end` - 流结束
- `error` - 错误信息

### POST /chat

非流式聊天接口（备用）。

### GET /health

健康检查接口。

## 使用示例

### 知识库问答
```
用户: AgentScope 有什么核心特性？
小智: [已调用工具: retrieve_docs]
      根据知识库，AgentScope 的核心特性包括：
      1. 易于使用 - 高级 Python API
      2. 鲁棒性 - 内置错误处理
      3. 可扩展性 - 支持大规模系统
      4. RAG 支持 - 知识库集成
      5. 工具调用 - ReAct 模式
```

### 数据分析
```
用户: 总结一下这些文档的主要内容
小智: [已调用工具: retrieve_docs, analyze_data]
      分析结果：...
```

## 架构说明

采用 **单 Agent + 多工具** 架构：

```
┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React)                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      App Component                         │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │  │
│  │  │   Header    │  │  ChatArea   │  │   InputArea     │   │  │
│  │  │ (New Chat)  │  │ (Messages)  │  │ (Send Message)  │   │  │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                   │
│                              ▼ SSE                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Backend (FastAPI)                            │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  POST /chat/stream  →  StreamingResponse (SSE)            │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                   │
│                              ▼                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   ReAct Agent System                       │  │
│  │    ┌──────────┬──────────┬──────────┐                     │  │
│  │    │retrieve  │retrieve  │analyze   │                     │  │
│  │    │_docs     │_images   │_data     │                     │  │
│  │    └──────────┴──────────┴──────────┘                     │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

详细设计请参考 [设计文档](docs/design.md)。

## 常见问题

### Q: 前端无法连接后端？

确保后端服务已启动，并且运行在 8000 端口。检查 CORS 配置是否正确。

### Q: 模型调用失败？

检查 `configs/model_config.json` 中的 API Key 和 Base URL 是否正确配置。

### Q: 知识库检索无结果？

确保 `data/` 目录下有文档文件，首次运行会自动建立向量索引。

## License

MIT