更新操作和个人任务指南
学生能够跑通 LLM 课程助手，理解模型 API、知识库和页面交互，并借助 AI 分析教育问题、设计开发应用、测试与反思。
本文件是仓库入口。路线：跑通原示例 → 修改一条资料或导师要求并复测 → 自主项目指南 → 自己的工作区 → 整理作品并提交共创 PR。自主项目提供初始化与交付脚本，支持复制 Demo 或从空白开始；核心 AI 功能使用指定国产算力 API，应用类型由真实需求决定。
LLM Learning Assistant 是一个面向大模型学习者的开源学习助手，帮助你理解知识、排查实验问题，并根据资料出处核对回答。你可以把自己的课程笔记、实验指南和常见问题放入知识库，搭建自己的学习工具。
项目适用于个人自学和课程教学。自学时，可以用它答疑、追问和记录学习过程；课堂中，学生还可以提交实验、查看反馈和求助，教师与助教可以发布任务、审阅作业和维护知识库。
仓库提供可运行的代码和配套指南，支持直接使用与二次开发。页面名称为「课程学习助手」，可用于小学、中学、大学各学科：把该课资料放入知识库后，回答只依据这些资料并给出处。
默认知识库为大学大模型课程（课程说明.md、实验指南.md、常见问题.md）。小学科学资料移至 examples/四年级声音/，不参与默认检索。只索引 knowledge/ 顶层的 Markdown；回答范围取决于已加入的资料。已有索引需重新执行快速启动中的建索引步骤，以移除旧资料。
课程说明.md
实验指南.md
常见问题.md
knowledge/
开发过程包含数据整理、模型 API 接入、RAG 检索、工具调用、应用开发、评测与部署。技术栈为 Python 标准库、HTML/JavaScript 和 SQLite，具备 Python 基础即可开始。
学习助手的完整页面包含账号与导航、知识问答、资料来源、回答反馈和人工求助入口。先看整体界面，再了解下面的具体功能。
整体预览来自本地实际运行的应用，使用示例账号，问答回放此前真实 API 验证保存的回答。
教师与助教还可以通过看板管理学生、实验任务、提交审阅、求助回复和知识库。
以下功能截图来自沐曦验证环境，账号与作业为示例，问答调用真实模型。完整操作见项目实现。
输入知识或实验问题，查看回答并展开来源核对依据。遇到新情况，可以补充实际日志继续追问。
学生提交实际结果和附件，教师或助教审阅后给出完成结论与具体意见；需要修改时可以重新提交并保留历史版本。
助手无法解决的问题可以附上对话并提交求助。学生查看教师或助教的回复，补充信息或确认解决。
教师或助教编辑资料并重建索引，再用原问题复问，核对新增资料是否支持回答。图中练习口令用于演示资料更新生效。
需要 Python 3.10+、Git、浏览器，以及一个兼容 OpenAI 格式、支持模型列表和文本生成的 API。课程部署使用沐曦实例，应用通过 API 调用模型，自身不要求 GPU；也可部署在自己的服务器。
仅体验 Demo 时，可直接使用下面的上游地址。计划提交共创 PR 时，建议先在 GitLink 页面 Fork，再将克隆地址换成自己 Fork 页面显示的地址。已经克隆上游也不必删除重来，后续按 PR 指南连接自己的 Fork。
在本机或服务器终端执行（Windows 的 Python 命令可能是 python；先确认版本为3.10或以上）：
python
git clone https://gitlink.org.cn/ccf-ai-infra/llm-learning-assistant.git cd llm-learning-assistant python3 -m pip install -r requirements.txt
项目无需额外 Python 依赖，本地运行数据默认保存在 outputs/。服务器部署可通过 LLM_DATA_DIR 指定独立的数据目录，各终端保持一致。环境、SSH 和 VS Code 连接方法见前置环境配置。
outputs/
LLM_DATA_DIR
完成效果： 进入仓库后，可以看到 app/、docs/、knowledge/ 和 tests/。
app/
docs/
tests/
在 app/config.json 中修改 model_api：
app/config.json
model_api
"model_api": { "base_url": "https://ai.gitee.com/v1", "model": "<你有权限使用的实际模型名称>", "max_tokens": 4096, "retries": 2 }
将尖括号占位内容替换为自己资源包支持的准确模型名，共创项目沿用课程指定服务地址。模型列表存在不代表当前令牌有调用权限，以下检查还会执行一次真实生成。令牌通过隐藏输入提供，输入时屏幕不回显字符是正常现象，粘贴后按回车，令牌保存在当前进程中：
python3 app/rag.py build python3 app/server.py --check --ask-key
看到 success、model_present、generation_ok 均为 true，说明模型列表与一次真实生成检查通过。报告保存在数据目录的 model_probe.json。
success
model_present
generation_ok
model_probe.json
完成效果： 索引输出包含资料块数量和保存路径，模型检查的三项结果为 true。
索引路径由数据目录决定，资料修改后块数也会变化。
该检查图来自沐曦实例上的真实 API 验证，实际结果以自己的接口为准。
python3 app/server.py --ask-key
服务启动时重新输入模型令牌。也可通过 LLM_API_KEY 环境变量提供令牌，通过 LLM_BASE_URL、LLM_MODEL 覆盖模型配置。
LLM_API_KEY
LLM_BASE_URL
LLM_MODEL
完成效果： 终端显示访问地址和数据目录，并保持运行。
这是本地界面预览的实际启动输出，临时数据目录仅用于截图；自己的部署使用默认目录或指定的 LLM_DATA_DIR。
本机运行时直接在浏览器打开终端显示的地址，不需要 SSH 或端口转发。服务会持续占用当前终端，这不是卡住；需要执行其他命令时另开一个终端并确认所在目录，结束服务按 Ctrl+C。若8000端口被占用，使用 --port 8001 并打开对应地址。
--port 8001
只有在远程服务器运行时，才通过 VS Code 端口转发访问；也可在本机执行以下 SSH 转发命令：
ssh -N -L 8000:127.0.0.1:8000 -p <SSH端口> <用户名>@<主机地址>
打开 http://127.0.0.1:8000/，看到登录或注册页面后，输入自己的用户名和密码，点击“注册学生账号”。已有账号直接登录。
http://127.0.0.1:8000/
在学习助手中提问“GPU 不可见时先检查什么？”，查看回答并展开来源。继续补充自己的实际输出，体验多轮排障。
完成效果： 登录成功，问题得到回答，来源可展开，回答反馈和求助入口可用。下面展示从页面顶部到页尾的完整应用预览，包含标题、账号、导航及当前页面全部内容。
完整预览来自本地实际运行的应用，使用示例账号；问答回放此前真实 API 验证保存的回答，本次截图未重新调用模型。实际部署按第 3.2 节配置自己的接口。
需要发布实验、审阅作业或从页面维护知识库时，在另一个终端创建教学账号：
python3 app/server.py --create-user teacher01 --role teacher python3 app/server.py --create-user ta01 --role ta
创建时隐藏输入密码，仅首次执行。个人部署者也可以使用教师账号维护自己的资料。正式教学需要 HTTPS 入口及对应 public_url、secure_cookie 配置，见部署与交付。
public_url
secure_cookie
完成效果： 教学账号登录后能看到教师看板，包括学生进度、实验任务、提交审阅、求助和知识库维护。以下为完整页面，账号及任务均为示例。
公共注册默认获得学生角色。教师与助教权限相同，由部署者授权；学生只能访问本人记录。将已注册用户设为助教，可在服务器执行：
python3 app/server.py --grant-role registered_user --role ta
实验提交支持 UTF-8 文本类文件，默认最多 3 个附件、每个 5 MB，可配置。自动检查提供格式和缺项线索，实验是否完成由教师或助教审阅。
从替换资料到增加功能的完整练习见二次开发指南；实现原理与源码讲解见项目实现。
建议先跑通原项目，再一次修改一个部分，并验证修改效果。需要维护自己的版本时，可先在平台 Fork 仓库，再克隆自己的副本。
examples/四年级声音/
my project/knowledge/
title
scope
prompt
acceptance.modules
python3 app/rag.py build python3 app/rag.py query '你的课程问题'
不同课程独立部署并使用独立数据目录，保留原课程的账号和提交记录。
修改 app/config.json 中的模型地址、名称和参数；调整系统提示词 prompt，或在 app/assistant.py 修改回答策略。
app/assistant.py
修改后重新检查模型接口并重启。对同一题集保留修改前后的回答，人工判断事实、出处和帮助是否有效。不要只凭回答长度或关键词命中判断收益。
app/index.html
app/teaching.py
app/accounts.py
app/storage.py
data_dir
app/rag.py
app/tools.py
app/server.py
修改配置或代码后重启，修改资料后重建索引。更改数据目录需停服并迁移；给已有数据库增加字段时，要编写迁移，不能只修改初始化建表语句。
向量检索、推理部署、微调和更复杂的 Agent 可作为后续扩展，以产品评测验证收益。先完成核心教学流程，再增加技术模块。
先运行不需要真实令牌的业务测试：
python3 tests/evaluate.py smoke
再启动真实服务，用学生账号评测自己的课程问题。换课后同步修改 tests/questions.jsonl 中的题目、预期状态和来源。
tests/questions.jsonl
python3 tests/evaluate.py regression --username student01 --output outputs/evaluation/before.jsonl
修改后输出到 after.jsonl，保持题集、模型和参数一致。评测生成逐题结果、人工复核 CSV、配置快照和汇总；结果文件不覆盖。RAG 与无资料模型的对照方法见测试与交付。
after.jsonl
交付标准： 新用户能够按 README 独立启动，用三个角色完成答疑、提交审阅、求助回复和知识更新；记录重启后保留，跨学生访问被拒绝。
先按 README 运行，再读项目实现理解源码，选择二次开发练习，最后按测试与交付验证成果。
llm-learning-assistant/ ├── README.md ├── LICENSE ├── requirements.txt ├── docs/ # 操作指南与 images/ 截图 ├── app/ │ ├── server.py # HTTP 接口与服务编排 │ ├── accounts.py # 账号、会话与授权 │ ├── teaching.py # 教学业务与知识维护 │ ├── storage.py # 数据库与文件存储 │ ├── assistant.py # 模型调用与回答策略 │ ├── rag.py # 资料索引与检索 │ ├── tools.py # 工具与审计 │ ├── index.html # 浏览器页面 │ └── config.json # 非敏感配置 ├── knowledge/ # 原 LLM 课程助手知识库 ├── examples/ # 可选跨学科资料，不参与默认检索 ├── my project/ # 学生代码、知识库、提示词与设计材料 ├── scripts/ # 初始化、测试记录、检查与交付整理 └── tests/ # 业务测试与模型评测
账号、提交、对话和运行日志位于服务端数据目录，不进入 Git 仓库。本地开发测试可使用默认 outputs/；教学部署指定服务器目录，备份数据库、附件和课程资料。
代码改编自 Full Link Development of Large Models 的课程应用示例，采用木兰宽松许可证第 2 版。知识资料为可替换的教学示例，目前放了大学大模型课程和小学科学课程。
版权所有：中国计算机学会技术支持：开源发展技术委员会 京ICP备13000930号-9 京公网安备 11010802047560号
学习目标与阅读路线
学生能够跑通 LLM 课程助手，理解模型 API、知识库和页面交互，并借助 AI 分析教育问题、设计开发应用、测试与反思。
本文件是仓库入口。路线：跑通原示例 → 修改一条资料或导师要求并复测 → 自主项目指南 → 自己的工作区 → 整理作品并提交共创 PR。自主项目提供初始化与交付脚本，支持复制 Demo 或从空白开始；核心 AI 功能使用指定国产算力 API，应用类型由真实需求决定。
LLM Learning Assistant
1. 项目简介
LLM Learning Assistant 是一个面向大模型学习者的开源学习助手，帮助你理解知识、排查实验问题，并根据资料出处核对回答。你可以把自己的课程笔记、实验指南和常见问题放入知识库，搭建自己的学习工具。
项目适用于个人自学和课程教学。自学时，可以用它答疑、追问和记录学习过程；课堂中，学生还可以提交实验、查看反馈和求助，教师与助教可以发布任务、审阅作业和维护知识库。
仓库提供可运行的代码和配套指南，支持直接使用与二次开发。页面名称为「课程学习助手」，可用于小学、中学、大学各学科：把该课资料放入知识库后，回答只依据这些资料并给出处。
默认知识库为大学大模型课程（
课程说明.md、实验指南.md、常见问题.md）。小学科学资料移至 examples/四年级声音/，不参与默认检索。只索引knowledge/顶层的 Markdown；回答范围取决于已加入的资料。已有索引需重新执行快速启动中的建索引步骤，以移除旧资料。开发过程包含数据整理、模型 API 接入、RAG 检索、工具调用、应用开发、评测与部署。技术栈为 Python 标准库、HTML/JavaScript 和 SQLite，具备 Python 基础即可开始。
2. 效果展示
2.1 项目整体预览
学习助手的完整页面包含账号与导航、知识问答、资料来源、回答反馈和人工求助入口。先看整体界面，再了解下面的具体功能。
整体预览来自本地实际运行的应用，使用示例账号，问答回放此前真实 API 验证保存的回答。
教师与助教还可以通过看板管理学生、实验任务、提交审阅、求助回复和知识库。
查看教师看板完整预览
以下功能截图来自沐曦验证环境，账号与作业为示例，问答调用真实模型。完整操作见项目实现。
2.2 知识答疑与实验排障
输入知识或实验问题，查看回答并展开来源核对依据。遇到新情况，可以补充实际日志继续追问。
2.3 实验提交与人工反馈
学生提交实际结果和附件，教师或助教审阅后给出完成结论与具体意见；需要修改时可以重新提交并保留历史版本。
2.4 求助与留言回复
助手无法解决的问题可以附上对话并提交求助。学生查看教师或助教的回复，补充信息或确认解决。
2.5 知识库更新与效果验证
教师或助教编辑资料并重建索引，再用原问题复问，核对新增资料是否支持回答。图中练习口令用于演示资料更新生效。
3. 快速启动
3.1 获取代码
需要 Python 3.10+、Git、浏览器，以及一个兼容 OpenAI 格式、支持模型列表和文本生成的 API。课程部署使用沐曦实例，应用通过 API 调用模型，自身不要求 GPU；也可部署在自己的服务器。
仅体验 Demo 时，可直接使用下面的上游地址。计划提交共创 PR 时，建议先在 GitLink 页面 Fork，再将克隆地址换成自己 Fork 页面显示的地址。已经克隆上游也不必删除重来，后续按 PR 指南连接自己的 Fork。
在本机或服务器终端执行（Windows 的 Python 命令可能是
python；先确认版本为3.10或以上）：项目无需额外 Python 依赖，本地运行数据默认保存在
outputs/。服务器部署可通过LLM_DATA_DIR指定独立的数据目录，各终端保持一致。环境、SSH 和 VS Code 连接方法见前置环境配置。完成效果： 进入仓库后，可以看到
app/、docs/、knowledge/和tests/。3.2 配置模型
在
app/config.json中修改model_api：将尖括号占位内容替换为自己资源包支持的准确模型名，共创项目沿用课程指定服务地址。模型列表存在不代表当前令牌有调用权限，以下检查还会执行一次真实生成。令牌通过隐藏输入提供，输入时屏幕不回显字符是正常现象，粘贴后按回车，令牌保存在当前进程中：
看到
success、model_present、generation_ok均为 true，说明模型列表与一次真实生成检查通过。报告保存在数据目录的model_probe.json。完成效果： 索引输出包含资料块数量和保存路径，模型检查的三项结果为 true。
索引路径由数据目录决定，资料修改后块数也会变化。
该检查图来自沐曦实例上的真实 API 验证，实际结果以自己的接口为准。
3.3 启动服务
服务启动时重新输入模型令牌。也可通过
LLM_API_KEY环境变量提供令牌，通过LLM_BASE_URL、LLM_MODEL覆盖模型配置。完成效果： 终端显示访问地址和数据目录，并保持运行。
这是本地界面预览的实际启动输出，临时数据目录仅用于截图；自己的部署使用默认目录或指定的
LLM_DATA_DIR。本机运行时直接在浏览器打开终端显示的地址，不需要 SSH 或端口转发。服务会持续占用当前终端，这不是卡住；需要执行其他命令时另开一个终端并确认所在目录，结束服务按 Ctrl+C。若8000端口被占用，使用
--port 8001并打开对应地址。只有在远程服务器运行时，才通过 VS Code 端口转发访问；也可在本机执行以下 SSH 转发命令：
3.4 打开页面并开始学习
打开
http://127.0.0.1:8000/，看到登录或注册页面后，输入自己的用户名和密码，点击“注册学生账号”。已有账号直接登录。在学习助手中提问“GPU 不可见时先检查什么？”，查看回答并展开来源。继续补充自己的实际输出，体验多轮排障。
完成效果： 登录成功，问题得到回答，来源可展开，回答反馈和求助入口可用。下面展示从页面顶部到页尾的完整应用预览，包含标题、账号、导航及当前页面全部内容。
完整预览来自本地实际运行的应用，使用示例账号；问答回放此前真实 API 验证保存的回答，本次截图未重新调用模型。实际部署按第 3.2 节配置自己的接口。
3.5 教学功能（可选）
需要发布实验、审阅作业或从页面维护知识库时，在另一个终端创建教学账号：
创建时隐藏输入密码，仅首次执行。个人部署者也可以使用教师账号维护自己的资料。正式教学需要 HTTPS 入口及对应
public_url、secure_cookie配置，见部署与交付。完成效果： 教学账号登录后能看到教师看板，包括学生进度、实验任务、提交审阅、求助和知识库维护。以下为完整页面，账号及任务均为示例。
查看教师看板完整预览
4. 使用指南
公共注册默认获得学生角色。教师与助教权限相同，由部署者授权；学生只能访问本人记录。将已注册用户设为助教，可在服务器执行：
实验提交支持 UTF-8 文本类文件，默认最多 3 个附件、每个 5 MB，可配置。自动检查提供格式和缺项线索，实验是否完成由教师或助教审阅。
5. 二次开发
从替换资料到增加功能的完整练习见二次开发指南；实现原理与源码讲解见项目实现。
建议先跑通原项目，再一次修改一个部分，并验证修改效果。需要维护自己的版本时，可先在平台 Fork 仓库，再克隆自己的副本。
5.1 替换学习资料
knowledge/中的大模型课程资料，补充出处与适用环境。声音资料可从examples/四年级声音/选读。自主项目资料放在my project/knowledge/，独立运行与索引配置将在自主项目指南中补齐。app/config.json的title、scope、prompt。当前提示词面向小学、中学、大学各学科，不写死某一门课；若本次部署只服务一门课，再把范围写进提示词。使用章节步骤工具时，同步调整acceptance.modules。不同课程独立部署并使用独立数据目录，保留原课程的账号和提交记录。
5.2 换模型或调整回答
修改
app/config.json中的模型地址、名称和参数；调整系统提示词prompt，或在app/assistant.py修改回答策略。修改后重新检查模型接口并重启。对同一题集保留修改前后的回答，人工判断事实、出处和帮助是否有效。不要只凭回答长度或关键词命中判断收益。
5.3 修改功能或界面
app/index.htmlapp/teaching.pyapp/accounts.pyapp/storage.py、data_dirapp/rag.pyapp/tools.pyapp/server.py修改配置或代码后重启，修改资料后重建索引。更改数据目录需停服并迁移；给已有数据库增加字段时，要编写迁移，不能只修改初始化建表语句。
向量检索、推理部署、微调和更复杂的 Agent 可作为后续扩展，以产品评测验证收益。先完成核心教学流程，再增加技术模块。
5.4 验证并交付修改
先运行不需要真实令牌的业务测试：
再启动真实服务，用学生账号评测自己的课程问题。换课后同步修改
tests/questions.jsonl中的题目、预期状态和来源。修改后输出到
after.jsonl，保持题集、模型和参数一致。评测生成逐题结果、人工复核 CSV、配置快照和汇总；结果文件不覆盖。RAG 与无资料模型的对照方法见测试与交付。交付标准： 新用户能够按 README 独立启动，用三个角色完成答疑、提交审阅、求助回复和知识更新；记录重启后保留，跨学生访问被拒绝。
6. 教程与仓库结构
先按 README 运行，再读项目实现理解源码，选择二次开发练习，最后按测试与交付验证成果。
账号、提交、对话和运行日志位于服务端数据目录，不进入 Git 仓库。本地开发测试可使用默认
outputs/；教学部署指定服务器目录，备份数据库、附件和课程资料。7. 来源与许可
代码改编自 Full Link Development of Large Models 的课程应用示例，采用木兰宽松许可证第 2 版。知识资料为可替换的教学示例，目前放了大学大模型课程和小学科学课程。