1panel自定义模型设置方法教程详解

在 1Panel 面板中集成外部 AI 服务或本地推理引擎，能让智能体和 AI 搜索功能直接调用你指定的模型资源。这种设置方式将连接信息与具体应用解耦，一旦配置完成，所有支持该模型账号的功能模块都能即时使用，无需重复输入凭证。

1Panel 左侧菜单 AI 下的模型管理入口及标签页布局

配置的核心在于准确填写服务端的接口地址和认证信息，并确保模型 ID 与服务端实际提供的名称一致。只要网络可达且协议兼容，无论是云服务商的兼容接口，还是自建 Ollama、vLLM 服务，都能通过统一入口接入。

1. 进入 AI 模型管理

登录 1Panel 面板后，在左侧导航栏找到并点击【AI】菜单，随后选择子菜单中的【模型】。页面加载后，你会看到顶部有【模型账号】和【本地模型】两个标签页。自定义外部接口或通用兼容服务的配置应在【模型账号】标签下进行，这里集中管理所有连接凭证。

2. 创建模型账号

在【模型账号】列表页面的右上角，点击【创建】按钮。弹出的表单中，首先填写【账号名称】。这个名称仅用于在 1Panel 内部识别，建议采用“服务商-用途”的格式，例如“内部推理-测试”，避免直接使用敏感信息作为名称。

2. 创建模型账号

3. 选择自定义提供商

在【模型提供商】下拉菜单中，根据目标服务类型进行选择。如果对接的是标准 OpenAI 兼容接口或其他通用 API，选择【自定义】；如果是本地部署的 Ollama 或 vLLM 服务，则直接选择对应的【Ollama】或【vLLM】选项。选择后，下方表单会根据提供商类型动态显示所需的配置字段。

4. 填写 API Key 和 Base URL

根据上一步的选择，填写必要的连接信息。对于【自定义】类型，通常需要填写【API Key】和【Base URL】。API Key 是服务端颁发的访问令牌，请确保复制完整且无多余空格。Base URL 应填写服务文档提供的 API 根地址，例如 https://api.example.com/v1，不要随意追加额外的路径参数，除非服务端明确要求。

若选择 Ollama 或 vLLM，系统可能会自动填充默认的本地地址（如 http://127.0.0.1:11434），此时只需确认端口是否正确即可。

5. 选择 API 类型

在【API 类型】选项中，确认服务端支持的协议标准。大多数自定义服务兼容 OpenAI 格式，但部分私有部署可能使用特定版本或变种。务必与服务端管理员确认支持的 API 类型，错误的协议选择会导致后续连接验证失败或消息发送异常。

5. 选择 API 类型

6. 维护模型池

【模型池】区域用于定义该账号下可用的具体模型。点击添加模型，填写【模型 ID】，这必须与服务端实际接受的模型名称完全一致，区分大小写。【显示名称】可以设置为中文或更易读的标识，方便在智能体中选择。同时，根据服务端限制，合理设置【Context Window】（上下文窗口）和【Max Tokens】（最大输出令牌数），这些参数会影响对话的长度和成本。

7. 保存并验证连接

检查所有填写项无误后，点击底部的【保存】按钮。返回模型账号列表，找到刚才创建的账号，点击操作列中的【验证连接】按钮。系统会尝试向 Base URL 发送请求以检查连通性和凭证有效性。如果显示“连接成功”，说明配置正确；若失败，请依次检查网络防火墙、API Key 有效性及 Base URL 格式。

8. 在智能体和 AI 搜索中选择模型

配置验证通过后，该模型账号即可被其他功能模块调用。进入【智能体】或【AI 搜索】的设置页面，在模型选择下拉列表中，你应该能看到新添加的账号及其下的模型 ID。选中它并进行一次简单的对话测试，确保实际业务流中能正常接收回复。

在智能体设置中调用已验证通过的自定义模型账号

9. 配置 Ollama 或 vLLM 本地模型

如果使用本地服务，需确保对应应用已在 1Panel 应用商店中安装并处于运行状态。对于 vLLM，部分高级功能可能需要专业版或企业版许可证支持。请注意，1Panel 的模型管理仅负责记录连接信息和模型元数据，不会自动下载或托管实际的模型权重文件，模型文件的管理仍需通过 Ollama 或 vLLM 自身的命令行或界面完成。

10. 检查凭证和权限

API Key 属于高敏感凭证，建议仅授予受信任的管理员角色访问【AI】>【模型】菜单的权限。在团队协作环境中，普通用户可能无法看到模型配置入口，这是由 1Panel 的角色权限控制决定的。定期轮换 API Key 并在更换后及时更新 1Panel 中的配置，能进一步提升安全性。

模型账号列表中显示验证通过的状态标识

完成上述步骤后，你的自定义模型已正式接入 1Panel。后续如需调整模型参数或切换服务端地址，只需回到模型账号编辑页面修改即可，所有关联的智能体将自动继承新的配置，无需逐个重新设置。