# englishstudy

**Repository Path**: aiagentdemo/englishstudy

## Basic Information

- **Project Name**: englishstudy
- **Description**: 英语学习AI Agent
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# English Study Agent

基于 LangChain 的英语学习智能体：FastAPI 后端 + Vue3 前端，支持词汇、语法纠错、
翻译、对话练习等工具，并使用 **RAG 检索动态管理对话上下文**（省 token、支持长对话）。

## 启动方式（两个终端）

```bash
# 终端1 - 后端
cd /Users/sxf/Documents/CozeTest/EngLishStudy
.venv/bin/pip install -r requirements.txt        # 首次或更新依赖后执行
.venv/bin/uvicorn server:app --reload --port 8000

# 终端2 - 前端
cd /Users/sxf/Documents/CozeTest/EngLishStudy/frontend
npm run dev
# 浏览器访问 http://localhost:5173
```

也可用命令行版：`.venv/bin/python main.py`

## RAG 上下文管理

为避免把整段对话历史都塞进 prompt（token 随对话线性增长、易超窗口），本项目
用 **RAG 检索 + 最近窗口** 的混合策略动态组装每轮上下文：

```
每轮发送给 LLM 的 chat_history =
    [SystemMessage: RAG 检索到的相关早期片段]   ← 按当前问题语义检索，按需取回
  + 最近 N 轮对话原文(Human/AI)                ← 解决"它/上面那个"等指代、连续追问
  + 当前用户输入
```

无论对话多长，注入的上下文体积基本恒定。

### 工作流程

- **写入**：每轮 `(user, assistant)` 合成片段 → 本地 embedding 转向量 → 存入 Chroma（按 `session_id` 分库隔离）。
- **检索**：用当前问题向量检索 Top-K 最相关历史，过相似度阈值、去重最近窗口已有内容，作为 `SystemMessage` 注入。
- **隔离**：前端按 `session_id`（localStorage 持久化）区分会话，`reset` 时换新会话。

### 关键文件

| 文件 | 作用 |
|------|------|
| `rag_memory.py` | RAG 记忆核心：embedding + 向量库 + session 隔离 + 检索/写入/清空 |
| `agent.py` | `build_chat_history()` 组装"检索片段 + 最近窗口"；`create_agent_executor()` |
| `server.py` | `/api/chat?message=&session_id=` 每轮检索注入 + 回答后写回 RAG |
| `frontend/src/composables/useChat.ts` | 生成并持久化 `session_id`，请求时携带 |

### 配置（环境变量，均有默认值）

| 变量 | 默认 | 说明 |
|------|------|------|
| `RAG_EMBED_MODEL` | `BAAI/bge-small-zh-v1.5` | 本地 embedding 模型 |
| `RAG_PERSIST_DIR` | `./.rag_store` | Chroma 持久化目录 |
| `RAG_RECENT_WINDOW` | `3` | 最近保留几轮原文 |
| `RAG_TOP_K` | `4` | 检索返回片段数 |
| `RAG_SCORE_THRESHOLD` | `0.15` | 相似度阈值（低于则丢弃） |

### 优雅降级

依赖缺失时自动退化、不影响主流程：
- 未装 `sentence-transformers` → 用纯 Python TF-IDF 兜底 embedding；
- 未装 `chromadb` → 用进程内内存向量库兜底（重启清空）。

`GET /api/health` 可查看当前 RAG 后端（`embedder` / `store`）。

> 要获得最佳语义检索效果，请确保安装了 `sentence-transformers` 和 `chromadb`
> （已在 `requirements.txt` 中）。首次运行会下载 embedding 模型。