> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 自定义推理 Provider

> 连接兼容 LiteLLM 的推理 Provider、声明其模型，并控制可使用这些模型的主体。

自定义推理 Provider 用于将 OpenCore 连接到采用 LiteLLM 兼容 Provider 定义的模型服务。Provider 配置与其模型会一起保存；如果没有有效模型名称，就无法启用该 Provider。

## 兼容性

当服务出现在 Provider 选择器中，或具有该选择器可接受的 LiteLLM provider ID 时，使用此流程。配置的端点必须能从 OpenCore backend 访问，且 Provider 必须支持为各模型声明的 capability 所对应的请求格式。

自定义推理可用于 Lite 和 Standard，因为语言模型请求不依赖 OpenSearch。连接器知识与索引仍然要求 Standard。

## 添加 Provider

打开**模型与能力**，选择**语言模型**，然后添加 Custom Provider。保存前完成以下字段：

| 字段                    | 是否必填           | 含义                                                    |
| --------------------- | -------------- | ----------------------------------------------------- |
| Provider              | 是              | 用于路由请求的 LiteLLM provider ID；打开已保存 Provider 进行编辑后不能修改它 |
| API Key               | Provider 要求时必填 | Provider 端点使用的凭据                                      |
| API Base URL          | 否              | 自定义或自托管服务的基础端点                                        |
| API Version           | 否              | Provider adapter 要求时使用的特定 API 版本                      |
| Environment Variables | 否              | 传给 LiteLLM `completion()` 调用的额外键值属性                   |
| Display Name          | 普通 Admin 表单中必填 | OpenCore 中用于标识已配置 Provider 的名称                        |

普通 Admin 流程会校验 Provider 和 Display Name。提交表单前至少添加一个模型。

## 可选字段

| 字段                    | 何时设置                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| API Key               | 仅当端点使用 Provider key 鉴权时设置。真实值只能保存在受保护表单中。                                                                    |
| API Base URL          | 当 Provider 不使用其 adapter 默认端点时设置。在支持的 Docker 环境中，容器内可通过 `host.docker.internal` 访问宿主机；容器内的 `localhost` 指向容器自身。 |
| API Version           | 填写 Provider adapter 要求的准确版本；不需要时留空。                                                                          |
| Environment Variables | 只添加 Provider 已记录的属性。空 key 会被忽略；表单转换为 map 时，后出现的重复 key 会覆盖前值。                                                 |

不要把 Provider 凭据放入 Agent 指令、对话消息、模型名称、环境变量示例或源码仓库。共享排障材料只能使用占位值。

## 添加模型

| 模型字段         | 行为                                                                         |
| ------------ | -------------------------------------------------------------------------- |
| Model Name   | Provider 使用的模型标识，必填。至少需要一个非空名称。                                            |
| Display Name | 面向用户的可选标签；留空时 OpenCore 会回退到 Model Name。                                    |
| Input Type   | 选择 **Text Only** 或 **Text & Image**。该字段只声明图像输入支持，不能让不支持图像的 Provider 获得此能力。 |
| Max Tokens   | 该模型的可选最大输入 token 值。不需要覆盖时留空。                                               |

使用 **Add Model** 在同一 Provider 下配置更多模型。每个模型名称都必须与 Provider 接受的标识完全一致，并且只有确认端点接受图像输入后才能声明 **Text & Image**。

## 访问控制

| 访问选项                  | 结果                                                         |
| --------------------- | ---------------------------------------------------------- |
| All Users & Agents    | 让部署内所有用户与 Agent 都可使用已配置的 Provider 模型。                      |
| Named Groups & Agents | 仅允许所选群组与 Agent 使用。只有部署 tier 启用 business group 控制时才会显示群组选项。 |
| Admin                 | 即使选择了命名访问范围，也始终向 Admin 共享。                                 |

访问控制显示在普通 Admin 配置流程中，不显示在精简 onboarding 表单中。每次新增模型或目标使用者变化时，都应重新检查访问范围。

## 验证

1. 保存 Provider，并确认 OpenCore 报告已成功启用。
2. 使用应有访问权限的身份，确认每个已配置模型都出现在[语言模型](/opencore/models/language-models)页面。
3. 发送一个代表性文本请求。对于 **Text & Image** 模型，还要测试图像请求，并确认 Provider 确实接受该输入。
4. 如果请求失败，重新检查 Provider、API Base URL、API Version、Provider 特定的 Environment Variables，以及[模型凭据](/opencore/models/model-credentials)中说明的受保护凭据。