本页汇总模型自定义接入过程中的高频问题，覆盖导入不识别、启动失败、参数不生效等场景，帮助您快速定位原因。
1. 导入 config.json 后模型不识别 / 列表不显示
- 确认选择的是模型目录根部的
config.json 文件，而不是其它 JSON 文件
- 检查 JSON 语法是否合法，可用编辑器校验一遍
- 确认
name、version、entry 等核心字段齐全，见「模型接入流程总览」
- 检查
platformName、platformArch 是否与当前系统和架构匹配
- 检查
serverRequire 是否满足当前 AIGCPanel 版本
2. 模型启动失败或一直停留在启动中
- 检查入口文件路径是否正确、是否具备可执行权限
- 确认运行环境已随模型打包完整（如简易接入的
_aienv 目录）
- 看「日志」页输出，定位具体报错；必要时先用命令行手动运行入口验证
- 端口被占用时，换端口或留空由系统分配可用端口
3. 界面上看不到参数 / 参数修改不生效
- 确认已在 config.json 的
functions 中声明对应能力，见「模型能力声明说明」
- 确认
param 数组中定义了该参数（name、type 等字段完整）
- 参数由模型运行后返回，修改配置后需重启模型再查看
-
default 与 required 设置是否合理，避免界面出现空值
4. 能力调用后没有结果
- 检查结果输出约定是否正确：文件需真实存在且路径可读
- 返回的文件路径应是本地真实路径，不能是临时未生成的路径
- 单任务执行期间的重复调用会返回重试状态，稍后再查询即可
- 查看「日志」页确认入参是否如预期（text、video、audio 等）
5. 检测不到 CUDA / 无法使用本地模型
- 本地模型依赖 NVIDIA 显卡，确认驱动与 CUDA 环境正常
- 模型需向界面输出设备能力信息（如 UseCuda），否则前端无法判断
- 无 NVIDIA 显卡环境可改用云模型方案
6. 升级软件后模型不可用
- 核对模型
serverRequire 与当前软件版本是否仍满足
- 对照更新日志确认是否有接口或配置结构变更
- 建议同步升级模型版本，再重新导入测试
获取帮助
- 先准备：config.json、模型目录结构、完整日志截图
- 通过「工单反馈」提交，信息越完整定位越快
- 也可参考示例项目 aigcpanel-server-demo 对照排查
相关文档
