# turing-physics-teacher

**Repository Path**: zybzyb1/turing-physics-teacher

## Basic Information

- **Project Name**: turing-physics-teacher
- **Description**: 基于人教版初中物理教材的本地AI教育智能体
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📘 图灵物理智教

一个基于人教版初中物理教材的 **本地 AI 教育智能体**。

**无需联网，数据安全，安装简单，完全免费。**

---

## ✨ 核心特色

| 特色 | 说明 |
|------|------|
| 🏠 **全离线运行** | 所有 AI 模型和数据都在你的电脑上运行，不需要联网，保护学生隐私。 |
| 💡 **启发式引导** | 采用苏格拉底式提问，引导学生主动思考，而不是直接给出答案。最后还会总结知识点。 |
| 📚 **基于教材** | 回答内容来源于人教版物理教材，有据可查，不会瞎编。 |
| ⚡ **实时显示** | 可以看到 AI “思考”的过程，生成完后会自动隐藏草稿，只留下清晰的教学内容。 |
| 📂 **多格式支持** | 支持 PDF、TXT、Word、Excel 等多种资料格式。 |

---

## 🖥️ 环境要求

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | Windows 10 / 11 | Windows 11 |
| 内存 | 8 GB | 16 GB 或更高 |
| 显卡 | 无硬性要求（CPU 也能跑） | NVIDIA 显卡（显存 ≥ 8 GB） |
| Python | 3.9 或更高版本 | 3.11 及以上 |

> 💡 **没有独立显卡也可以运行**，只是生成回答的速度会慢一些（大约 1~3 分钟一个回答）。

---

## 🚀 快速开始（一步一步跟着做）

### 第一步：安装 Ollama 并下载 AI 模型

Ollama 是一个让你在本地运行 AI 模型的工具，我们先把它装好。

1. 打开浏览器，访问 [https://ollama.com](https://ollama.com) ，点击 **Download** 下载 Windows 版本。
2. 双击安装文件，一路点击“下一步”完成安装。安装完成后，任务栏右下角会出现一只羊驼的图标 🦙。
3. 按键盘上的 `Win + R`，输入 `cmd`，回车打开命令提示符（一个黑底白字的窗口）。
4. 在命令提示符里依次输入下面两行命令，每输完一行按一次回车。  
   **这个过程会下载几个 GB 的模型文件，请确保网络稳定，耐心等待下载完成。**

    ollama pull qwen3.5:9b
    ollama pull shaw/dmeta-embedding-zh

5. 看到 `success` 字样，就说明下载成功了。

### 第二步：下载本项目代码

1. 在你想存放项目的文件夹（比如桌面）里，**按住 Shift 键**，同时点击鼠标右键，选择 **“在此处打开命令提示符”** 或 **“在终端中打开”**。
2. 在弹出的命令窗口中输入下面的命令，回车执行（这会把项目下载到你的电脑上）：

    git clone https://gitee.com/Lucky-peihao/turing-physics-teacher.git
  
   > 如果没有安装 Git，可以去 [https://git-scm.com](https://git-scm.com) 下载安装，或者直接在 Gitee 网页上点击“克隆/下载” → “下载 ZIP” 然后解压到文件夹。

3. 下载完成后，进入项目文件夹：

    cd turing-physics-teacher

### 第三步：安装 Python 依赖库

项目需要一些 Python 扩展包才能运行，我们需要把它们装好。

1. **创建虚拟环境**（给项目一个干净的环境，避免和电脑上其他 Python 项目冲突）：

    python -m venv venv

2. **激活虚拟环境**（每次运行项目前都要执行这一步）：  
   在命令提示符里执行：

    venv\Scripts\activate.bat

   执行后，命令行最前面会出现 `(venv)`，说明环境激活成功。

3. **安装依赖包**：

    pip install -r requirements.txt

   等待安装完成，看到 `Successfully installed ...` 就说明安装成功了。

### 第四步：放入教材 PDF 并构建知识库

你需要准备人教版物理教材的 PDF 文件（比如八年级上册、八年级下册、九年级全一册）。

1. 在项目文件夹里，新建一个名为 `physics_books` 的文件夹（如果还没有的话）。
2. 把你准备好的教材 PDF 文件（以及任何你想让 AI 参考的 Word、Excel 知识点文档）**复制到这个 `physics_books` 文件夹里**。
3. 在命令提示符中（确保已激活 `(venv)` 环境），运行下面的命令：

    python create_knowledge_base.py

   - 程序会自动扫描 `physics_books` 文件夹里的所有 PDF、Word、Excel 文件。
   - 首次运行会处理文档并生成知识库，**可能需要几分钟**，请耐心等待，不要关闭窗口。
   - 当看到 `✅ 知识库构建完成！` 时，说明知识库已经可以用了。
   - **以后每次往 `physics_books` 里新增或修改文件后，都需要重新运行这个命令更新知识库。**

### 第五步：启动应用

在命令提示符中（确保已激活 `(venv)` 环境），执行：

    streamlit run app.py

稍等片刻，程序会自动打开你的默认浏览器，进入 **图灵物理智教** 的网页界面。  
如果浏览器没有自动打开，可以手动在浏览器地址栏输入 `http://localhost:8501` 并按回车。

现在，你可以在左侧选择 **📚 交互问答**，输入物理问题，AI 老师就会开始引导式教学啦！

> ⚠️ **注意**：那个命令提示符窗口**不要关掉**，关闭窗口程序就会停止。你可以把它最小化。

---

## 🌐 如何让其他学生或老师访问（局域网共享）

如果你想让学生在教室的电脑、平板或手机上也能访问你这个 AI 教师，可以按以下步骤操作。

1. 在原本的启动命令后面加上 `--server.address 0.0.0.0`，像这样：

    streamlit run app.py --server.address 0.0.0.0

2. 查看你这台电脑的 IP 地址：  
   打开新的命令提示符，输入 `ipconfig`，找到 `IPv4 地址`（通常是 `192.168.x.x` 这样的格式），记下来。

3. 让其他设备**连接同一个 Wi-Fi 或同一个局域网**，然后在浏览器中输入：

    http://你的IP地址:8501

   例如：`http://192.168.1.105:8501`

> 💡 你的电脑必须保持开机，且命令提示符不能关闭。

---

## ⚙️ 参数调优（可选）

如果觉得回答太慢、太长、或者想关闭调试信息，可以打开 `app.py`，在文件最前面的 **“🎛️ 用户可调参数配置区”** 进行修改。那里有详细的中文注释，修改后保存，重启应用即可生效。

常用的调整项包括：
- `DEBUG_MODE`：`True` 显示性能统计，`False` 隐藏。
- `QA_TIMEOUT`：请求超时时间，单位秒。
- `QA_CONTEXT_MAX_LENGTH`：AI 每次参考的教材片段长度，减小可提速。
- `OLLAMA_QA_NUM_PREDICT`：AI 最多生成的回答字数，减小可提速。

---

## 📂 项目文件结构

   图灵物理智教/
   ├── app.py                  # 主程序
   ├── create_knowledge_base.py # 知识库构建脚本
   ├── test_ollama.py          # 测试 Ollama 是否连通
   ├── requirements.txt        # Python 依赖包列表
   ├── .gitignore              # Git 忽略规则
   ├── LICENSE                 # MIT 开源许可证
   ├── README.md               # 本说明文档
   ├── docs/                   # 可选的截图或说明图片
   ├── physics_books/          # 放入教材 PDF 的地方（需要自己创建）
   ├── physics_db/             # 生成的知识库文件夹（自动生成）
   └── venv/                   # 虚拟环境（自动生成）

---

## 🔧 常见问题

**Q：提示“无法连接 Ollama 服务”？**  
A：请确认 Ollama 正在运行（任务栏右下角有羊驼图标）。如果没有，从开始菜单重新打开 Ollama。

**Q：运行 `create_knowledge_base.py` 时卡住不动？**  
A：首次运行需要处理很多文档，可能耗时几分钟，请耐心等待。如果长时间没有反应，可以关闭窗口，检查 `physics_books` 里是否有图片特别多的 Excel 文件，可以先把 Excel 另存为 CSV 格式再放入。

**Q：提问时一直显示“正在思考”或最后提示超时？**  
A：可以尝试在 `app.py` 参数配置区把 `QA_CONTEXT_MAX_LENGTH` 改小（比如 1000），以及把 `OLLAMA_QA_NUM_PREDICT` 改小（比如 512），保存后重启应用。

**Q：没有 NVIDIA 显卡能用吗？**  
A：可以，Ollama 会自动使用 CPU 进行推理，速度会稍慢一些，但完全可用。

**Q：支持 Mac 或 Linux 吗？**  
A：项目的核心代码是跨平台的，你只需要根据 Mac/Linux 的终端习惯调整激活虚拟环境的命令（例如 `source venv/bin/activate`），以及注意文件路径的写法即可。

---

## 📄 许可证

本项目采用 **MIT 许可证**，详情见 `LICENSE` 文件。你可以自由使用、修改和分发，但请保留原作者信息。

---

**🧑‍🏫 教育为本，技术为用 —— 让 AI 成为物理教师的得力助手。**