AI 与班级知识库
AI 是辅助能力，默认关闭。它只做识别、整理、检索和预填，不参与出分：评分与结算始终由后端规则执行，所有正式动作仍由有权限的用户在页面确认。
功能
| 功能 | Worker | 说明 |
|---|---|---|
| 材料整理 | worker:ai | 学生上传图片或 PDF，模型识别后生成候选申报草稿，由本人逐项核对 |
| 班级知识 Agent | worker:agent | 班级资料安全转换后可被检索；「问 Agent」回答规则问题并引用原文 |
| 平台产品知识 | — | 内置的页面与操作说明，运维可在 Agent 配置中维护，帮助回答「在哪里交材料」一类问题 |
两个 Worker 常驻但空闲，真正的调用闸门在运维台开关，开启后即时生效，无需重启容器。只运行后端依赖、另行托管 API 的部署可以用 docker compose --profile ai up -d 单独启动它们。
模型配置
在运维台「Agent 配置」管理多个 OpenAI 兼容供应商，并按用途路由：
| 用途 | 场景 |
|---|---|
material.vision | 材料整理：识图 |
material.compose | 材料整理：组织候选草稿 |
knowledge.ocr | 班级资料 OCR |
agent.text | 知识问答 |
agent.vision | 带图片附件的问答 |
每个供应商的 API Key 在运维页分别保存，由 AI_CONFIG_SECRET_KEY 加密。APP_ENV=prod 时必须设置这个 32 字节密钥；开发环境留空会使用固定的本机默认值。
.env 中的 LLM_* 单端点变量只供旧部署迁移和没有 OPS_DATABASE_URL 的精简部署回退，新部署无需填写。
私网模型
AI HTTP 客户端默认拒绝访问私有网段，防止被用作 SSRF 跳板。只有使用自建内网模型端点时，才设置 AI_ALLOW_PRIVATE_NETWORK=true。这个开关需要显式开启，APP_ENV=dev 也不会自动放行。
批量与并发
| 变量 | 默认 | 范围 |
|---|---|---|
AI_MAX_BATCH | 100 | 1—100，单批材料数 |
AI_CONCURRENCY | 2 | 1—8 |
AI_MAX_PDF_PAGES | 64 | 1—64 |
LLM_TIMEOUT | 90s | 5 秒—10 分钟 |
启用班级知识 Agent
需要同时满足：
- 平台开启 AI、知识库与知识外发；
- 班管在本班确认第三方处理授权；
- 班级资料已完成转换，状态为可检索或部分可检索；
- 未超过每日用量上限。
班管撤销授权后，新的问答和 OCR 会立即停止。班级资料的可见范围决定学生、小组和班管各自能否检索；运维无法查看这些文件。关闭知识开关时，worker:agent 仍可完成不外发的纯文本转换。
外部 Agent
用户自己的 Agent 通过 MCP 接入，由用户自己的模型完成分析，不依赖站内 AI 开关或模型额度。