模型与 API
API Key 错误或余额不足怎么办？
出现 401、402 或 403 时，检查 API Key 是否完整、是否属于当前服务商、账户是否有余额、Key 是否被禁用，以及 base_url 和鉴权方式是否正确。
公开日志或配置时不要展示完整 API Key。
下拉列表里找不到想使用的模型怎么办？
可以手动填写服务商提供的模型标识符。显示名称可以自定义，但 model_identifier 必须与服务商接口实际接受的名称一致，包括大小写和版本后缀。
如果手动填写后返回 model not found，应到服务商控制台确认账号是否有权使用该模型。
怎样配置视觉模型？
模型本身必须支持图片输入，并在 MaiBot 模型列表中启用视觉属性。仅凭名称中带有 vision、vl 或类似字样不能保证接口兼容，应以服务商文档和实际调用结果为准。
温度应该设置多少？
较低温度通常更稳定，较高温度通常更多样，但不同模型和推理模式对 temperature 的支持不同。部分模型会忽略温度，或者要求使用其他采样参数。
建议从服务商推荐值开始，根据回复效果逐步调整。
embedding 请求失败怎么办？
依次检查：
- 选择的确实是 embedding 模型，而不是聊天或视觉模型。
- 模型标识符、API Key 和
base_url正确。 - 服务提供标准 OpenAI 兼容接口时，端点通常为
/v1/embeddings。 - 输入没有超过模型长度限制。
- 返回向量维度与现有向量库一致。
- 网络、代理和服务商地区限制没有阻断请求。
文本嵌入用 embedding 任务，图片嵌入用独立的 image_embedding 任务，两者不能混用。更换 embedding 模型后如果维度变化，可能需要按记忆系统提供的维护功能重建向量。
图片嵌入模型怎么配？
图片记忆需要把图片本身编码成向量，要单独配置 [model_task_config.image_embedding]：
- 在模型列表里加入一个支持"图片输入到向量"的嵌入模型，并配好所属服务商
- 把它填进
image_embedding任务的model_list - 保存后到 WebUI 的「长期记忆 → 图片记忆」确认检索状态变为可用
几个容易踩的坑：
- 图片嵌入模型和文本嵌入模型是两个独立任务，
image_embedding留空不会回退到embedding，图片检索会直接不可用 image_embedding只支持单选模型，不按selection_strategy轮询- MaiBot 会自动适配百炼、硅基流动、火山的图片嵌入请求形状，但服务商地址需使用 HTTPS
- 模型不可用时会按配置间隔自动重试并明确显示"模型不可用"，不会静默改用别的模型
思考开关为什么不显示、或者关不掉？
WebUI 模型配置页的思考开关由服务商模板决定：模板没有声明思考元数据时不显示开关；reasoning_effort 类型的推理模型思考常开，只能调力度档位，不能关闭。个别模型还有额外限制，例如 Kimi k2.7-code 只支持开启思考、k3 系列不使用 thinking 参数、MiniMax M2.x 无法关闭思考。以页面上的提示为准，或改用 extra_params 手动写入。
用了编程套餐（Coding Plan）为什么返回 401？
智谱编程套餐（GLM Coding Plan）、火山方舟编程套餐（Ark Coding Plan）、阶跃 Step Plan 的凭证与按量付费 API Key 不通用，部分套餐的 Base URL 还因账号而异。请在服务商控制台确认套餐专属地址和套餐 Key，再按对应的服务商模板创建提供商。
内容来源
embedding 接口兼容性和多模态 embedding 的部分排查思路参考了社区协作文档《麦麦教程-常见问题速查/社区教程》，原文相关说明署名 ARC。本站已按当前实现修正端点和适用范围。