常见问题
这里整理了使用 智元 Fast API 时最常遇到的问题, 方便你快速找到上手、调用和排查方向
如何快速上手?
- 先完成部署, 可参考 快速开始
- 首次进入系统后, 先到
配置管理 -> 管理员登录修改后台登录入口, 提高系统安全性 - 按顺序完成基础配置:
- 如果要给业务系统调用, 再去创建 应用 和 应用密钥
- 如果要给普通用户使用, 再去配置 用户管理、分组管理 和 站点配置
一定要先配置模型吗?
是的。
本系统的大部分能力都围绕模型展开, 无论是接口调用、用户权限、分组权限、应用权限还是智能助手页面, 最终都要先有可用模型。
如果还没有模型, 其他很多功能即使配置好了也无法真正使用。
如何快速接入模型?
有两种常见方式:
- 手动配置: 先建提供商, 再建模型, 按需要补充代理、密钥和价格规则
- 同步配置: 通过系统里的
同步功能快速导入可用模型
如果你想先尽快跑通流程, 建议优先用同步方式。
如何调用 API 接口?
本系统对外提供统一 API 入口, 大多数场景下可直接按 OpenAI 标准接口方式调用。
常见调用方式:
- OpenAI 风格接口: 按 OpenAI 官方格式调用
- Claude 风格接口: 使用
/v1/messages - Gemini 风格接口: 使用
/v1beta/models/{model}:{action}
如果你已经有对接 OpenAI 的代码, 通常只需要替换接口地址、模型名和应用密钥即可开始调用。
更详细的接口说明可查看 API 文档。
应该用哪个密钥来调用?
对外给业务系统调用时, 通常使用的是 应用密钥。
可以简单这样理解:
- 模型密钥 / 代理密钥: 给系统内部连接上游平台使用
- 应用密钥: 给你的业务系统、客户端或第三方调用方使用
如果只是普通用户在页面里使用系统, 一般不需要自己手动处理应用密钥。
为什么我已经配置了模型, 还是不能调用?
常见原因有:
- 模型没有可用上游密钥
- 模型被分组、会员、用户或应用权限限制住了
- 应用密钥已过期、额度不足或被禁用
- 应用密钥绑定了分组, 但分组里没有对应模型权限
- 调用 IP 不在白名单内, 或命中了黑名单
这类问题建议优先检查:
用户注册后为什么看不到功能?
常见原因有:
- 用户没有获得可用分组
- 用户没有获得可用模型权限
- 用户会员等级没有对应权限
- 站点关闭了相关注册或登录方式
- 站点配置了注册提示, 实际上不允许公开注册
如果是普通用户端问题, 建议重点检查:
应用密钥和用户额度是什么关系?
可以简单理解为“谁更严格, 就按谁生效”。
例如:
- 用户本身额度不足, 即使应用密钥还有额度, 也可能无法继续使用
- 应用设置了更小的额度限制, 就会先受应用限制
- 应用密钥又设置了单独额度, 那么还会继续受应用密钥限制
如果你希望把额度控制得更细, 建议同时配合:
- 用户额度
- 应用额度
- 应用密钥额度
- 分组额度
登录、注册、找回密码为什么没有显示?
这些能力是否显示, 取决于系统当前配置。
可分别在配置管理里控制:
- 用户端登录方式
- 代理商端登录方式
- 管理端登录方式
- 是否开放注册
- 是否开放找回密码
如果页面上没有对应入口, 一般不是前端问题, 而是当前配置没有开启。
站点标题、Logo、背景图在哪里改?
在 站点配置 中修改。
这里可以统一管理:
- 标题
- Logo
- Favicon
- 登录页背景图
- 版权信息
- 公告与文档展示内容
如果你是做多品牌或多代理商站点, 这个模块会比较常用。
如何查看调用花费和使用情况?
可以从几个模块查看:
如果你是要查“某一次请求为什么失败”, 优先看日志。
如果你是要查“最近花了多少额度”, 优先看账单和仪表盘。
API 接口报错怎么排查?
建议按这个顺序处理:
提问时应该提供哪些信息?
如果你准备在 issue 或交流群中提问, 建议至少提供:
- 你使用的是哪个版本
- 你在做什么操作
- 报错信息是什么
- 是否可以稳定复现
- 对应日志截图或文字内容
- 已经尝试过哪些排查方法
这样更容易快速定位问题。