功能简介

AI客服-小灵是本系统内置的智能对话助手，挂在右下角「帮助球」里随呼随到。它接入了本系统的帮助文档（按模块整理的 wiki 页），能回答「这个功能怎么用、在哪个菜单操作、流程是什么」一类系统使用问题，并在答复中注明来源页名（如「详见《监考安排管理》」）；帮助资料未覆盖的，它会基于常识简要回答并说明这是通用建议，不会编造系统里不存在的菜单或功能。一期为纯文本对话，图表 / 图片分析（视觉能力）为二期功能。

模型方面采用「自配优先、默认兜底」：普通用户可在「我的模型设置」里填入自己的云端模型与 API key（DeepSeek、通义千问、智谱、Kimi、硅基流动、豆包等 OpenAI 兼容模型）；未自配的用户则统一使用超管在「LLM 全局设置」里配置的组织默认模型（一期推荐默认 DeepSeek V4-pro）。

入口与权限

• 对话入口：点开右下角帮助球（问号悬浮按钮）→ 在弹出面板里点「AI客服-小灵」按钮，唤起对话窗口；窗口可随处使用，不限于某个页面。
• 我的模型设置：对话窗口标题栏的「齿轮」图标，或直接访问 /assistant/settings（教师及以上自助维护自己的模型）。
• LLM 全局设置（超管）：帮助球面板内「LLM 全局设置（超管）」按钮，或访问 /admin/llm_settings（仅超管可见可用）。
• 可用角色：教师 / 管理员 / 超管。学生不可用（ai_assistant 模块对学生隐藏），预览 / 只读账号也被拒绝。前提是当前学院已开通「ai_assistant」模块且账号具备相应角色（超管对该模块恒为开通）。后端对所有 /assistant/* 写入口都有硬准入校验，前端是否显示入口只作体验优化，不能绕过权限。

操作步骤（分角色）

所有非学生用户：与小灵对话

1. 点开帮助球，点「AI客服-小灵」唤起对话窗口。
2. 在底部输入框直接用中文提问，例如「教学课件报送在哪里提交」「监考安排怎么确认」「达成度报告如何导入命题明细」。
3. 小灵按命中的帮助页作答，并可能注明来源页名；标注「（相关）」的为关联模块的简介，仅作交叉参考。
4. 标题栏「垃圾桶」图标可清空当前对话重新开始；对话过长（超过体量上限）时会提示新开会话或精简后再试。
5. 若提示「尚未配置可用的助手模型」，说明你未自配模型且系统也未设默认——按下一节自配模型，或联系管理员配置默认模型。

教师 / 管理员：配置「我的模型」（自选常用模型 + 自填 API key）

1. 进入「我的模型设置」（对话窗口齿轮图标 / /assistant/settings）。
2. 在表单的「常用模型」下拉里选一个（DeepSeek V4-pro / V4-flash、通义千问 Qwen-Max / Plus、智谱 GLM-4.7 / GLM-4-Flash、Kimi 8k / 128k、硅基流动、豆包，或「自定义」），选中后 base_url 与 model 会自动填好，旁边出现「获取该平台 API key →」链接。
3. 到对应平台申请并复制你自己的 API key，粘贴进 api_key 框（仅初次 / 更换时填，留空保留已有）。可按需微调 temperature、max_tokens、timeout。
4. 勾选「启用」后保存——启用后小灵会优先用你的模型与 API key。
5. 保存后可点「测试」做一次最小探活调用，确认连通（会显示延迟与响应片段）；列表里「上次测连」列会回写正常 / 失败。
6. 一个用户可存多条配置，但同一时间以最近更新的那条启用项为准；不需要的可「删除」。

超管：配置组织默认模型与助手默认（LLM 全局设置）

1. 进入「LLM 全局设置」（帮助球面板按钮 / /admin/llm_settings）。
2. 在「全局 profile」区新增 / 编辑组织级 profile：填 key、显示名、provider、base_url、model，粘贴 API key（同样 Fernet 加密落库，留空保留原密文），可「测试」探活。
3. 在「助手默认模型」区把「文本助手默认 profile」指向某个已启用的 profile（一期推荐指向 DeepSeek V4-pro），点「保存默认」。该指向写入 sidecar runtime/llm_assistant_state.json，跨容器重建存活。
4. 「视觉默认 profile」一期留空（DeepSeek V4 官方暂未提供图片输入）。
5. 设好后，所有未自配模型的用户对话即统一走该默认模型。

字段与状态口径

常见问题

• 提示「尚未配置可用的助手模型」：你未自配模型且系统未设默认。到「我的模型设置」自配一个并启用，或请超管在「LLM 全局设置」配默认模型。
• 发图片没反应 / 被拒绝：一期不支持图片输入，图表分析为二期功能，目前请只发文字。
• 测试连接失败：核对 base_url、model、API key 是否正确，平台账户是否有余额 / 额度，timeout 是否过短；失败信息会给出异常类型。
• 小灵答不准某个功能：它依赖已发布的帮助 wiki 页作答，未覆盖的模块只能给通用建议。如发现某模块说明缺失或过时，反馈给管理员补充帮助页即可提升命中。
• 找不到入口：确认当前学院已开通 ai_assistant 模块、账号不是学生 / 预览账号；学生账号本模块不可见。
• 敏感数据边界：请勿在对话里粘贴学生学号、成绩等敏感原始明细——对话会发往所配置的云端模型，应只描述操作问题，不贴原始数据表。

相关页面

• 教学资料报送 教学课件报送：小灵可答疑提交 / 审批 / 列宽等用法
• 达成度分析 课程目标达成度：小灵可答疑命题明细录入与报告导入
• 监考安排管理 监考安排管理：小灵可答疑查询确认、排班、通知等流程