Learning Assistant

一个面向课程场景的 AI 助教项目，包含：

• knowledge/：课程资料清洗、切块、索引、检索与生成的 RAG 管线
• web_app/：FastAPI Web 应用，提供学生问答、讲义学习页和教师工作台
• nanobot/：Agent 运行时、会话记忆、工具调用与教师侧辅助能力

当前仓库更适合课程内部部署或二次开发，不是“克隆后零配置即运行”的模板项目。

项目能力

• 学生用学号和密码登录后，与课程专属 AI 助教对话
• 支持讲义学习页 /lecture，按 enriched 讲义逐页阅读和提问
• 支持教师工作台 /teacher
• 教师可上传 PDF 教材或课件，触发增量解析和索引
• 内置课程级 SQLite，记录上传任务、问答埋点、提醒和统计任务
• 支持向量检索、BM25、RAPTOR 摘要节点和混合检索
• 提供并发压测脚本和 RAG 检索评估脚本

技术栈

• Python
• FastAPI + Jinja2 + SSE
• LangChain + Chroma + BM25
• LiteLLM 风格 Provider 配置
• SQLite

第三方与致谢

• nanobot/：Agent 运行时基于开源项目 HKUDS/nanobot，以 MIT License 发布。本仓库中的拷贝可能包含课程相关定制与扩展；上游许可全文见 nanobot/LICENSE。

仓库结构

learning_assistant/
├─ knowledge/              # RAG 管线与数据预处理 CLI
├─ nanobot/                # Agent 框架
├─ web_app/                # Web 应用
├─ scripts/                # 压测、评估、密码重置等脚本
├─ data/                   # 运行期数据目录（向量库、processed、course db 等）
├─ pyproject.toml          # knowledge 包依赖
└─ README.md

运行要求

建议使用 Python 3.11 或更高版本。

安装

在仓库根目录执行：

python -m venv .venv
.venv\Scripts\activate

pip install -e .
pip install -e .\nanobot
pip install -r web_app\requirements.txt

可选：

pip install streamlit httpx

• streamlit：用于检索调试 UI
• httpx：用于并发压测脚本

必备配置

这个项目除了安装依赖，还需要准备三类运行时配置。

仓库已经附带这些可提交的示例文件：

• .env.example
• .nanobot/config.example.json
• .nanobot/students/users.example.jsonl

通常做法是复制后改名：

copy .env.example .env
copy .nanobot\config.example.json .nanobot\config.json
copy .nanobot\students\users.example.jsonl .nanobot\students\users.jsonl

1. .env

knowledge/config.py 会从根目录 .env 读取模型与 embedding 配置。

常用变量示例：

OPENAI_API_KEY=your_llm_api_key
OPENAI_API_BASE=https://api.deepseek.com
MODEL_NAME=deepseek-chat

ZHIPUAI_API_KEY=your_embedding_api_key
EMBEDDING_MODEL=embedding-3

CHUNK_SIZE=1000
CHUNK_OVERLAP=200
SUB_CHUNK_MAX_CHARS=0
SUB_CHUNK_OVERLAP=150
RAG_TOP_K=4
KNOWLEDGE_EMBED_BATCH_SIZE=64

WEB_APP_SECRET=replace_with_a_long_random_string
MAX_CONCURRENT_LLM=20
REQUEST_TIMEOUT=120
LECTURE_CHAT_TIMEOUT=600
CHAT_RATE_LIMIT=10
COURSE_ID=rl

说明：

• OPENAI_API_KEY 和 DEEPSEEK_API_KEY 二选一即可
• ZHIPUAI_API_KEY 用于 embedding；没有它无法正常建库
• 生产环境必须显式设置 WEB_APP_SECRET

2. .nanobot/config.json

nanobot 默认从 ./.nanobot/config.json 读取 Provider 和 Agent 配置。

最小示例：

{
  "agents": {
    "defaults": {
      "workspace": "workspace",
      "model": "deepseek/deepseek-chat",
      "temperature": 0.3,
      "maxTokens": 4096,
      "maxToolIterations": 8,
      "memoryWindow": 50
    }
  },
  "providers": {
    "deepseek": {
      "apiKey": "your_api_key",
      "apiBase": "https://api.deepseek.com"
    }
  }
}

如果这里没有可用 API Key，Web 启动后聊天接口会返回 Agent 不可用。

3. .nanobot/students/users.jsonl

Web 登录依赖这个文件。每行一个 JSON 记录，例如：

{"id":"2024001","password":"rl2026","name":"张三","class":"计科1班","role":"student"}
{"id":"teacher01","password":"teacher2026","name":"任课教师","role":"teacher"}

如果安装了 bcrypt，系统会把明文密码自动迁移成哈希。

数据准备

默认数据根目录是 data/。常见流程如下。

1. 准备课程资料

把课程文档放入默认目录，或通过参数指定目录：

• data/pdfs/
• data/raw/textbooks/
• data/raw/ppt/

2. 生成清洗后的 chunk

最常用：

python -m knowledge ingest --llm-clean

如果你是按教材批次处理：

python -m knowledge ingest --llm-clean --book-id rl_book --docs-dir data/processed/textbooks/complete
python -m knowledge merge-corpus

3. 建索引

python -m knowledge index

这一步会生成：

• Chroma 向量库
• RAPTOR 摘要节点
• BM25 检索数据

4. 检索验证

python -m knowledge query --hybrid -q "什么是贝尔曼最优方程？"

启动 Web

uvicorn web_app.main:app --host 0.0.0.0 --port 8765

访问：

• 学生聊天页：http://127.0.0.1:8765
• 讲义学习页：http://127.0.0.1:8765/lecture
• 教师工作台：http://127.0.0.1:8765/teacher

如果要顶住较高并发，可以尝试：

uvicorn web_app.main:app --host 0.0.0.0 --port 8765 --workers 4

教师侧能力

教师端当前包含这些能力：

• 上传教材 PDF / 课件 PDF
• 查询资料处理任务状态
• 查看问答埋点汇总
• 导出课程问答埋点 CSV
• 管理提醒与学生 notice
• 触发后台统计任务

上传资料后，系统会在后台执行清洗和增量索引，不需要重建整个知识库。

常用脚本

重置测试密码：

python scripts/reset_passwords.py

并发压测：

python scripts/test_concurrent.py --base-url http://127.0.0.1:8765 --students 10 --messages 3

RAG 评估：

python scripts/evaluate_rag.py --generate 10
python scripts/evaluate_rag.py --evaluate --hybrid --k 5

检索调试 UI：

python -m knowledge retrieve-ui

运行期产物

默认会在仓库内生成这些内容：

• .nanobot/config.json
• .nanobot/students/users.jsonl
• .nanobot/sessions/
• .nanobot/workspace/
• data/processed/
• data/vector_db/
• data/course/rl_assistant.sqlite
• data/uploads/

这些都属于运行期数据，不建议提交到 GitHub。

注意事项

1. 需要手动准备运行数据

仓库中不包含：

• 真实 .nanobot/config.json
• 真实 .nanobot/students/users.jsonl
• 样例课程资料
• 预构建向量库

所以 README 必须明确“安装依赖后还需要配置 API Key、学生账号和课程资料”。

2. 公开仓库要强调隐私边界

项目会产生学生对话埋点、教师提醒、统计报表和本地 SQLite 数据。即使 .gitignore 已排除了敏感路径，也建议在 README 里明确：

• 不要提交学生账号与会话数据
• 不要提交 data/course/internal_ux_signals.jsonl
• 不要提交 .nanobot/workspace/memory/

已知限制

• 首次上手门槛较高，需要同时准备 LLM、embedding、nanobot 配置和课程数据
• README 无法替代课程内容处理规范，尤其是教材/讲义预处理链路
• 当前仓库更偏单课程部署，跨课程复用还需要继续抽象
• 没有内置 Docker、CI、示例数据和一键初始化脚本

---

如果你只是想在本地跑起来，最短路径是：

1. 准备 .env
2. 准备 .nanobot/config.json
3. 准备 .nanobot/students/users.jsonl
4. 放入课程资料后执行 python -m knowledge ingest --llm-clean
5. 执行 python -m knowledge index
6. 启动 uvicorn web_app.main:app --host 0.0.0.0 --port 8765