AI 服务配置
系统管理员可以在界面中配置兼容 OpenAI API 的模型服务。保存并启用后，项目创建、问卷助手、质量检查、报告和判分等页面会按权限提供可用模型。
- 适合： 负责私有部署、模型采购和系统配置的管理员
- 前置条件： 已取得模型服务的 Base URL、API Key 和模型 ID，并确认网络可以访问服务地址
- 完成后： 系统显示 OpenAI 服务已启用，业务页面可以选择已配置模型
API Key 是服务端凭据。不要把密钥写入公开文档、聊天记录、问卷内容或前端环境变量；截图前必须确认密钥已遮罩。
第一步：打开 OpenAI 服务配置
使用系统管理员账号进入 配置管理，展开 AI 服务，找到 OpenAI 服务，点击右上角编辑按钮。
截图中的 API Key 只显示遮罩，Base URL、模型名称和模型 ID 应替换为组织实际购买或部署的服务信息。
第二步：填写连接信息
| 字段 | 作用 | 填写要求 |
|---|---|---|
| 开启状态 | 控制系统是否提供 AI 能力 | 信息填写完整并验证后再开启 |
| Base URL | 兼容 OpenAI API 的服务根地址 | 通常包含服务商要求的版本路径，例如 /v1 |
| API Key | 调用模型服务的凭据 | 已配置时留空会保留当前密钥 |
| 模型列表 | 定义业务页面可选择的模型 | 每行包含显示名称和实际模型 ID |
| 默认模型 ID | 新任务默认选择的模型 | 必须从模型列表中选择模型 ID |
显示名称 只用于页面展示，可以写成便于用户理解的名称；模型 ID 是实际请求值，必须与服务商提供的标识完全一致。不要把显示名称当作默认模型 ID。
第三步：设置生成参数
| 参数 | 可填范围 | 影响 |
|---|---|---|
| Max Tokens | 1 ～ 32000 | 限制单次生成的最大长度；还要受具体模型上限约束 |
| Temperature | 0 ～ 2，步长 0.1 | 越低通常越稳定，越高输出变化越大 |
| Top P | 0 ～ 1，步长 0.1 | 控制采样范围，越低输出通常越集中 |
优先使用模型服务商建议值。需要调整时，一次只修改一个参数，并用固定任务比较结果，避免无法判断变化来自哪个参数。
第四步：保存并验证
点击 保存。系统会校验模型列表、默认模型和参数范围；保存完成后，页面提示 OpenAI 服务配置保存成功，卡片摘要会显示：
- 状态为 已启用；
- Base URL 已配置；
- API Key 以圆点遮罩显示；
- 默认模型 ID 属于模型列表；
- 模型数量和名称符合预期。
随后使用普通业务账号在项目列表点击 新建 → AI 生成，确认模型出现在选择列表中，并用不含敏感数据的最小任务进行生成验证。
保存操作不会向模型服务发起连通性测试。“OpenAI 服务配置保存成功”只表示配置已写入系统；必须通过一次最小生成任务确认网络、密钥、模型 ID 和服务商配额均可用。
完成标志： 业务页面能够选择模型，生成任务正常返回内容，系统日志中没有鉴权或模型不存在错误。
变更与回滚
生产环境变更前记录当前 Base URL、模型列表、默认模型和参数；密钥只记录在组织认可的密钥管理系统中。
如果新配置不可用：
- 重新打开 OpenAI 服务，先关闭开启状态或恢复上一次可用配置；
- 保存后确认业务页面不再使用错误模型；
- 检查网络、API Key 权限、模型 ID 和服务商配额；
- 修复后用最小任务验证，再重新开放给用户。
上线检查清单
- Base URL 来自可信模型服务，并可从服务器访问
- API Key 只保存在配置中心或密钥管理系统
- 至少配置一个正确的模型 ID
- 默认模型 ID 已从模型列表中选择
- 生成参数符合模型限制
- 保存后 API Key 只显示遮罩
- 已使用非敏感内容完成最小生成验证
- 已确认模型服务的数据处理和日志留存政策
常见问题
为什么提示“请至少配置一个模型 ID”？
开启服务时模型列表不能为空。添加至少一行模型，并填写服务商提供的实际模型 ID。
为什么默认模型无法保存？
默认模型必须使用模型列表中的 模型 ID，不能手动填写显示名称。先维护模型列表，再从下拉框选择默认项。
编辑配置时 API Key 为空，是不是密钥丢失了？
不是。为防止密钥泄露，系统不会回填明文。已有密钥时留空并保存会保留当前值；只有轮换密钥时才输入新值。
保存成功但业务页面没有 AI 入口怎么办？
依次确认服务已开启、模型列表有效、账号拥有对应功能权限、当前项目已保存且项目类型支持该能力。仍失败时检查服务端网络和模型调用日志。
下一步
配置完成后，使用 AI 生成问卷与考试 做最小验证，再逐步开放 AI 问卷检查、AI 报告 和 AI 自动判分。