AI 与 BYOK
Semestra 的 AI 功能使用你自己的服务商。密钥如何保存、用哪个模型。
Sem（助手）、课程大纲和课表识别、图片读取以及文件搜索，都会调用你配置的 AI 服务商：使用你自己的密钥（BYOK）。 Semestra 不转售模型调用，所以没有 AI 额度，Semestra 也不会收 AI 费用；费用由你的服务商直接向你收取。
在哪里配置
全局设置里的 AI 分组：
| 页面 | 内容 |
|---|---|
| 服务商 | 你的服务商：类型、名称、接口地址、密钥，以及接口支持的能力 |
| 模型 | 每种用途使用哪个模型，以及可选的模型参数 |
| 用量 | 已用的 token 数和估算费用 |
密钥如何保存
- 密钥写入数据库前用服务器的
SEMESTRA_ENCRYPTION_KEY加密。API 只会返回打码后的提示。 - 保存服务商前会先试调用一次，修改密钥时也会再试一次。
- 数据导出永远不包含密钥。导入备份后，原本有密钥的服务商会保持关闭，直到你重新填写密钥。
用途
每次 AI 调用都有一个用途，每种用途需要服务商具备一种能力。
| 用途 | 用于 | 需要的能力 |
|---|---|---|
| Sem | 与助手对话，以及压缩对话 | chat |
| 读取文档 | 从课程大纲中提取课程信息、截止日期和成绩构成 | chat |
| 读取图片 | 课表截图 | vision |
| OCR | 扫描版 PDF 和照片里的文字 | vision |
| 搜索 | 在课程文件中查找段落 | embedding |
| 轻量任务 | 对话标题、推荐问题、整理 Sem 的记忆 | chat |
文件索引
新添加的课程文件会立即读取并建立索引，扫描页会在这时交给图像模型、段落交给搜索模型。想控制这部分开销，可以在学业项目（或某门课程）的设置里关闭 文件索引 → 自动为新文件建立索引。关闭期间添加的文件，在你手动建立索引或导入用到它时才会建立索引。
搜索向量只对生成它的模型有效，所以更换搜索模型会在后台为所有已建立索引的文件重新计算向量。已有向量时，设置里会先确认再更换。
由哪个模型回答
对每种用途，Semestra 依次尝试：
- 你在模型页为这个用途选择的模型，前提是它的服务商已启用且具备所需能力。
- 任一已启用且具备该能力的服务商，使用该服务商类型的推荐模型。
- 自部署实例上的全实例服务商。
都不满足时，功能会显示一个不打扰的“连接 AI”提示，而不是报错。
推荐模型（第 2 步使用）：
| 服务商 | Sem、读取文档、读取图片 | 轻量任务 | 搜索 |
|---|---|---|---|
| Anthropic | claude-sonnet-5-5 | claude-haiku-5-5 | （无） |
| OpenAI | gpt-5；读取文档和图片用 gpt-5-mini | gpt-5-nano | text-embedding-3-small |
| Gemini | gemini-2.5-pro；读取文档和图片用 gemini-2.5-flash | gemini-2.5-flash-lite | gemini-embedding-001 |
| Ollama | qwen3:8b（不读图片） | qwen3:8b | nomic-embed-text |
OCR 使用轻量任务的模型（Ollama 没有）。自部署的服务器也可以在本机用 PaddleOCR 识别、完全不用模型，见本机 OCR。搜索用的向量也可以在本机计算，见本机 embedding。
兼容接口没有推荐模型：请在模型页选择；接口不能列出模型时，直接输入模型名。
费用估算
用量页用服务器内置的 genai-prices 价格表估算费用。兼容接口按接口地址匹配（DeepSeek、 OpenRouter 等）；没有已知价格的模型不显示费用，Ollama 始终免费。