在有自定义模型入口的 ima 客户端中填写 API Key、接口地址和模型 ID，完成保存与切换。说明 Base URL 的填写方式，并排查认证失败、模型不存在和请求失败；自定义聊天模型与外部系统读取 ima 知识库需要分别配置。

本教程说明如何让 ima 使用外部模型 API。需要准备服务商提供的 API Key、接口地址（Base URL）和准确的模型 ID，并在 ima 的模型菜单中找到“添加自定义模型”。

以下截图展示有该入口的客户端。电脑端与手机端的菜单名称、入口位置可能随版本变化；若当前版本没有自定义模型入口，先查看 ima 官方说明，不要把 API Key 填进普通对话框。

在 ima 中添加自定义模型

在ima copilot的对话界面底部，找到「DS 快速」按钮（如图1红框），点击它展开模型选择菜单。

ima 对话界面底部的 DS 快速模型菜单入口

在模型菜单中，找到「添加自定义模型」按钮，点击它进入自定义模型配置页。

ima 模型菜单中的添加自定义模型按钮

在“添加自定义模型”页面，点击「模型厂商」下拉框。若需对接第三方或自建接口，选择「+ 自定义」；已选中时可跳过此步。

ima 模型厂商下拉菜单中的自定义选项

在配置页中填写以下三项，密钥和接口地址应来自同一个服务商：

接口地址：填写服务商给出的 Base URL。截图示例是 https://api.llm-token.cn/v1；使用其他服务商时应替换为对应地址。这里填写基础地址，不能直接照抄完整的 /chat/completions 请求 URL，也不要重复添加 /v1。
API Key：填写该接口对应的密钥，复制时检查首尾空格；不要使用另一个服务商的密钥。
模型名称：从服务商当前可用模型列表复制准确 ID，保留大小写、连字符和版本后缀。截图中的旧型号只用于展示配置位置。

初次配置时，输入和输出长度先保持默认，用一条短问题确认接入。之后再根据模型及客户端限制调整。

ima 自定义模型的接口地址、API Key、模型名称与保存按钮

填写完毕后，点击右上角「保存」，检查该配置是否出现在「自定义模型」列表中。

回到模型选择菜单，在「自定义模型」列表中选中刚添加的模型，发送一条短问题。保存配置只确认信息已记录，收到正常回答后才确认本次调用成功。

ima 模型菜单中已选中的自定义模型

ima 自定义模型请求失败怎么办？

先记录完整错误信息和请求时间，按失败阶段检查：

现象	优先检查
提示认证失败或返回 401	Key 是否完整、是否有效，是否属于当前接口地址对应的服务商
提示模型不存在或无权访问	模型 ID 是否与当前可用列表完全一致，该 Key 是否有访问权限
返回 404 或找不到接口	是否把完整请求路径填成 Base URL，是否重复出现 `/v1/v1`
保存成功但发送失败	是否已切换到新配置，账户额度、接口状态和客户端网络是否正常
短问题成功、长内容失败	输入与输出长度、上下文预算及服务商限额

向服务商反馈时提供请求时间、模型 ID、错误信息和请求 ID（如有），隐藏 API Key。

本教程配置的是 ima 调用外部聊天模型。如果需要让外部 Agent 读取或写入 ima 知识库，应另行核对 ima 官方提供的接口、认证与访问权限；保存一个自定义聊天模型不会完成这项配置。

使用服务商当前模型目录中的准确 ID，并分别查看输入、输出和缓存计费。模型名称、可用范围与价格可能调整，不应从旧截图复制型号或推断当前费用。

输入、输出和缓存输入可能采用不同单价。图片、视频或按次计费的模型请核对计费单位。模型 ID 和价格以实时定价页为准，实际扣费以账单记录为准。