# AI Agent 学习助教机器人

**Repository Path**: north-dream-testing/ai-agent--learning-tutor-robot

## Basic Information

- **Project Name**: AI Agent 学习助教机器人
- **Description**: 基于大语言模型与 LangChain Agent 框架构建的智能 Python 助教系统。系统通过 Agent 自主决策机制，自动识别学生问题类型并调度对应工具完成解答，覆盖**代码检查、报错解释、数学计算、知识点问答**四大核心场景，并基于 RAG 技术确保知识回答的准确性。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <h1 align="center">基于 Agent 的 Python 助教机器人</h1>
  <p align="center">
    <a href="#功能特性">功能</a> •
    <a href="#技术架构">架构</a> •
    <a href="#快速开始">部署</a> •
    <a href="#api-接口文档">API</a> •
    <a href="#常见问题">FAQ</a>
  </p>
</p>

---

## 项目概述

基于大语言模型与 LangChain Agent 框架构建的智能 Python 助教系统。系统通过 Agent 自主决策机制，自动识别学生问题类型并调度对应工具完成解答，覆盖**代码检查、报错解释、数学计算、知识点问答**四大核心场景，并基于 RAG 技术确保知识回答的准确性。

## 功能特性

### 智能对话交互

系统内置 AI 助教"小林"，支持多轮上下文对话，学生可用自然语言自由提问。

![智能对话交互](images/打招呼.png)

### 代码语法检查

学生提交 Python 代码片段，系统通过 AST 静态分析检测语法错误，定位问题行并给出修复建议。

| 前端交互界面 | Agent 工具调用日志 |
|:---:|:---:|
| ![代码检查-前端](images/test_check_code.png) | ![代码检查-Agent](images/agent_function_call_check_code.png) |

### 报错信息解释

学生粘贴 Python 运行时错误信息，系统以通俗中文解释错误根因，并给出可操作的修复方案。

| 前端交互界面 | Agent 工具调用日志 |
|:---:|:---:|
| ![报错解释-前端](images/test_explain_error.png) | ![报错解释-Agent](images/agent_function_call_explain_error.png) |

### Python 知识点问答

基于 RAG（检索增强生成）架构，系统先从 ChromaDB 向量库中检索最相关的知识片段，再结合检索内容生成回答，避免大模型幻觉。

| 前端交互界面 | Agent 工具调用日志 |
|:---:|:---:|
| ![知识问答-前端](images/test_ask_python_knowledge.png) | ![知识问答-Agent](images/agent_function_call_ask_python_knowledge.png) |

### 数学表达式计算

学生输入数学表达式，系统自动求值并返回计算结果。

| 前端交互界面 | Agent 工具调用日志 |
|:---:|:---:|
| ![数学计算-前端](images/test_calculate.png) | ![数学计算-Agent](images/agent_function_call_calculate.png) |

## 技术架构

### 系统架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        浏览器客户端                           │
│              HTML / CSS / JavaScript 单页应用                  │
└──────────────────────────┬──────────────────────────────────┘
                           │  HTTP REST API
┌──────────────────────────▼──────────────────────────────────┐
│                     FastAPI 后端服务                          │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              LangChain Agent (OPENAI_FUNCTIONS)        │  │
│  │                                                       │  │
│  │   ┌────────────┐  ────────────┐  ┌───────────────┐  │  │
│  │   │ check_code │  │explain_error│  │  calculate    │  │  │
│  │   │  (AST解析)  │  │  (LLM解释)  │  │  (eval求值)   │  │  │
│  │   └────────────┘  └────────────┘  └───────────────┘  │  │
│  │                                                       │  │
│  │   ┌───────────────────────────────────────────────┐   │  │
│  │   │         ask_python_knowledge (RAG 链路)         │   │  │
│  │   │  ChromaDB 检索 → 上下文注入 → LLM 生成回答      │   │  │
│  │   └───────────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              ChatMessageHistory 对话历史管理            │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌──────────────┐
   │  DeepSeek   │  │   ChromaDB  │  │ BGE 嵌入模型  │
   │  Chat API   │  │  向量数据库  │  │ bge-large-zh │
   │ (LLM 推理)  │  │ (知识存储)   │  │  (向量化)    │
   └─────────────┘  └─────────────┘  ──────────────┘
```

### 技术栈

| 层级 | 技术选型 | 版本 | 说明 |
|:---|:---|:---|:---|
| 大语言模型 | DeepSeek Chat | - | 通过 OpenAI 兼容 API 调用 |
| Agent 框架 | LangChain | 0.3.19 | OPENAI_FUNCTIONS Agent 类型 |
| 向量嵌入模型 | BAAI/bge-large-zh-v1.5 | - | 中文优化的 BGE 嵌入模型 |
| 向量数据库 | ChromaDB | 0.6.3 | 本地持久化 HNSW 索引 |
| 后端框架 | FastAPI + Uvicorn | 0.115.6 / 0.33.0 | 异步高性能 Web 框架 |
| 前端 | 原生 HTML/CSS/JS | - | 零依赖单页应用 |
| 容器化 | Docker + Docker Compose | v2+ | 一键部署 |
| 配置管理 | python-dotenv | 1.0.1 | 环境变量注入 |

### 核心模块说明

| 模块 | 文件 | 职责 |
|:---|:---|:---|
| 后端主服务 | `main.py` | FastAPI 路由、Agent 初始化、工具注册、RAG 链路 |
| 知识库构建 | `build_knowledge_base.py` | 文档加载、文本分块、向量入库 |
| 前端界面 | `static/index.html` | 聊天 UI、消息渲染、交互逻辑 |
| 依赖清单 | `requirements.txt` | Python 包版本锁定 |
| 容器配置 | `Dockerfile` | 镜像构建指令 |
| 编排配置 | `docker-compose.yml` | 服务编排、端口映射、卷挂载 |

## 项目结构

```
7.Python助教机器人_项目源码/
├── Dockerfile                              # Docker 镜像构建文件
├── docker-compose.yml                      # Docker Compose 服务编排
├── .env                                    # 环境变量（API 密钥等，不提交版本库）
├── .env.example                            # 环境变量模板
├── .dockerignore                           # Docker 构建排除规则
├── README.zh-cn.md                         # 项目说明文档（中文）
│
└── Agent-Based-Python-TA/
    └── 基于Agent的Python助教机器人/
        ├── main.py                         # FastAPI 后端 + Agent 核心逻辑
        ├── build_knowledge_base.py         # 知识库构建脚本
        ├── requirements.txt                # Python 依赖清单
        ├── static/
        │   └── index.html                  # 前端聊天界面
        ├── chromadb/                       # ChromaDB 向量数据库持久化目录
        │   ├── chroma.sqlite3              # 元数据 SQLite 数据库
        │   ── knowledge/
        │       └── Python_concept.docx     # 知识库源文档（Python 概念）
        └── images/                         # 功能演示截图
            ├── 打招呼.png
            ├── test_check_code.png
            ├── test_explain_error.png
            ├── test_ask_python_knowledge.png
            ├── test_calculate.png
            ├── agent_function_call_check_code.png
            ├── agent_function_call_explain_error.png
            ├── agent_function_call_ask_python_knowledge.png
            └── agent_function_call_calculate.png
```

## 快速开始

### 环境要求

| 依赖项 | 最低版本 | 说明 |
|:---|:---|:---|
| Docker | 20.10+ | 容器运行时 |
| Docker Compose | v2+ | 服务编排 |
| 可用内存 | 4 GB+ | 嵌入模型加载需要 |
| 可用磁盘 | 5 GB+ | 首次构建含模型下载 |

### 方式一：Docker 部署（推荐）

#### 1. 克隆项目

```bash
git clone <repository-url>
cd 7.Python助教机器人_项目源码
```

#### 2. 配置环境变量

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

编辑 `.env` 文件，填入你的 API 配置：

```env
# 大语言模型 API 配置
OPENAI_API_KEY=你的API密钥
OPENAI_BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat
```

> **说明**：`OPENAI_BASE_URL` 支持任何 OpenAI 兼容的 API 端点，包括 DeepSeek、OpenAI 官方、本地部署的 vLLM / Ollama 等。

#### 3. 构建并启动

```bash
docker compose up -d
```

首次构建预计耗时 10-20 分钟（需下载 Python 依赖和 BGE 嵌入模型约 1.3GB）。

#### 4. 访问应用

浏览器打开 **http://localhost:8080** 即可使用。

#### 常用运维命令

```bash
# 查看服务状态
docker compose ps

# 查看实时日志
docker compose logs -f python-ta

# 停止服务
docker compose down

# 重建镜像（代码修改后）
docker compose up -d --build
```

### 方式二：本地直接运行

```bash
# 1. 安装 Python 依赖
pip install -r Agent-Based-Python-TA/基于Agent的Python助教机器人/requirements.txt

# 2. 下载 BGE 嵌入模型（约 1.3GB）
huggingface-cli download BAAI/bge-large-zh-v1.5

# 3. 配置环境变量
export OPENAI_API_KEY=你的API密钥
export OPENAI_BASE_URL=https://api.deepseek.com
export MODEL_NAME=deepseek-chat

# 4. 启动服务
cd Agent-Based-Python-TA/基于Agent的Python助教机器人
uvicorn main:app --host 0.0.0.0 --port 8000
```

浏览器访问 **http://localhost:8000**。

### 方式三：中国大陆网络加速

国内网络访问 HuggingFace 和 PyPI 可能较慢，项目已内置加速配置：

- **PyPI 镜像**：Dockerfile 中使用阿里云 PyPI 镜像源
- **HuggingFace 镜像**：通过 `HF_ENDPOINT=https://hf-mirror.com` 环境变量切换至国内镜像
- **PyTorch CPU 版本**：使用 `--extra-index-url https://download.pytorch.org/whl/cpu` 避免下载 GPU 版 torch（节省约 2GB）

## 知识库管理

### 构建知识库

```bash
cd Agent-Based-Python-TA/基于Agent的Python助教机器人
python build_knowledge_base.py
```

构建流程：

1. **文档加载**：读取 `chromadb/knowledge/` 目录下的文档文件
2. **文本分块**：使用 `RecursiveCharacterTextSplitter` 切分（chunk_size=150, chunk_overlap=10）
3. **向量化**：通过 BGE 嵌入模型将文本块转换为向量
4. **入库存储**：写入 ChromaDB 向量数据库（HNSW 索引）

### 支持的文档格式

| 格式 | 扩展名 | 加载器 |
|:---|:---|:---|
| Word 文档 | `.docx` | UnstructuredWordDocumentLoader |
| PDF 文档 | `.pdf` | PDF 加载器 |
| 纯文本 | `.txt` | TextLoader |
| CSV 表格 | `.csv` | CSVLoader |
| Markdown | `.md` | Markdown 加载器 |

### 扩展知识库

1. 将新的知识文档放入 `chromadb/knowledge/` 目录
2. 重新执行 `python build_knowledge_base.py`
3. 重启服务使新知识生效

### 调整检索参数

在 `main.py` 中修改检索返回的文档数量：

```python
# 默认 k=1，返回最相关的 1 个文档块
retriever = db.as_retriever(search_kwargs={"k": 1})

# 如需更丰富的上下文，可增大 k 值
retriever = db.as_retriever(search_kwargs={"k": 3})
```

## API 接口文档

### POST /chat

发送聊天消息，获取 AI 助教回复。

**请求头：**

```
Content-Type: application/json
```

**请求体：**

```json
{
  "query": "Python的列表和元组有什么区别？"
}
```

**成功响应（200）：**

```json
{
  "response": "列表和元组都是Python中的序列类型，主要区别在于：列表是可变的..."
}
```

**错误响应（500）：**

```json
{
  "error": "内部服务器错误"
}
```

### GET /

返回前端聊天界面 HTML 页面。

**响应：** `text/html`，包含完整的聊天 UI。

### GET /static/*

静态资源服务，提供前端所需的 CSS、JS 等文件。

## 工作原理

### Agent 决策流程

```
用户输入问题
     │
     ▼
┌─────────────────┐
│  LangChain Agent │
│  分析问题意图     │
└────────┬────────
         │
    ┌────────┬────────────┬──────────────┐
    ▼         ▼            ▼              ▼
check_code  explain_error  calculate   ask_python_knowledge
 (AST)       (LLM)         (eval)       (RAG检索+生成)
    │         │            │              │
    ────┬────┴────────────┴──────────────┘
         ▼
   Agent 整合工具输出
         │
         ▼
   返回最终回答给用户
```

### RAG 检索增强生成流程

```
用户提问"Python列表是什么？"
         │
         ▼
┌─────────────────────┐
│  BGE 模型向量化问题   │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│  ChromaDB 相似度检索  │──→ 返回 Top-K 相关文档块
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│  文档块注入系统提示词  │
──────────┬──────────┘
           ▼
┌─────────────────────┐
│  DeepSeek 生成回答    │──→ "Python列表是一个有序且可变的集合..."
└─────────────────────┘
```

### 对话历史管理

系统使用 `ChatMessageHistory` 在服务端维护全局对话历史。每次请求时，完整的历史对话会被注入到 Agent 的系统提示词中，使模型能够理解上下文、保持对话连贯性。

## 环境变量配置

| 变量名 | 必填 | 默认值 | 说明 |
|:---|:---:|:---|:---|
| `OPENAI_API_KEY` | 是 | - | 大语言模型 API 密钥 |
| `OPENAI_BASE_URL` | 否 | `https://api.openai.com/v1` | API 端点地址 |
| `MODEL_NAME` | 否 | `deepseek-chat` | 模型名称 |
| `HF_ENDPOINT` | 否 | `https://huggingface.co` | HuggingFace 镜像地址 |
| `HF_HOME` | 否 | `~/.cache/huggingface` | 模型缓存目录 |

## 常见问题

### 首次启动非常慢

首次运行需要下载 BGE 嵌入模型（约 1.3GB）和 Python 依赖包。后续启动只需加载已缓存的模型，速度会显著提升。

### 如何切换大语言模型

修改 `.env` 文件中的两个变量即可：

```env
# 切换为 OpenAI 官方
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-3.5-turbo

# 切换为本地 Ollama
OPENAI_BASE_URL=http://localhost:11434/v1
MODEL_NAME=qwen2:7b
```

### 知识库回答不准确

可尝试以下调整：

1. 增大检索数量：修改 `main.py` 中 `search_kwargs={"k": 1}` 为更大的值
2. 优化知识文档：确保 `Python_concept.docx` 内容准确、结构清晰
3. 调整分块参数：修改 `build_knowledge_base.py` 中的 `chunk_size` 和 `chunk_overlap`

### 端口 8080 被占用

修改 `docker-compose.yml` 中的端口映射：

```yaml
ports:
  - "8081:8000"   # 将宿主机端口改为 8081
```

### 容器日志无输出

应用启动时需要加载嵌入模型（约 30-60 秒），此期间无日志输出属正常现象。可通过 `docker logs -f python-ta-bot` 持续观察。

### 依赖安装冲突

项目已简化 `requirements.txt` 为最小核心依赖集，由 pip 自动解析传递依赖。如遇版本冲突，可尝试：

```bash
pip install --upgrade pip
pip install -r requirements.txt --no-deps
```

## 贡献指南

欢迎通过以下方式参与贡献：

1. **Fork** 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交变更：`git commit -m 'feat: 添加某某功能'`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 **Pull Request**

### 代码规范

- Python 代码遵循 PEP 8 风格
- 提交信息使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范
- 新增功能需附带对应的测试用例

## 许可证

本项目仅供学习和研究使用。

## 致谢

| 项目 | 用途 | 链接 |
|:---|:---|:---|
| LangChain | Agent 编排框架 | https://github.com/langchain-ai/langchain |
| ChromaDB | 向量数据库 | https://github.com/chroma-core/chroma |
| BGE | 中文文本嵌入模型 | https://huggingface.co/BAAI/bge-large-zh-v1.5 |
| DeepSeek | 大语言模型 API | https://www.deepseek.com/ |
| FastAPI | Web 后端框架 | https://fastapi.tiangolo.com/ |