自定义上游接入

以 OpenAI 兼容形态接入自托管模型或私有网关——自定义入口地址、允许的请求类型限制、端点路径覆写、自签名与内部 CA 的 TLS 配置，以及一基底多实例的复用模式

自定义上游接入用于把自托管的模型服务或私有网关纳入灵渠模型池。只要目标服务遵循 OpenAI 兼容形态（暴露 /v1/chat/completions 等端点），就能以本页方式接入——指定其入口地址、限定允许的请求类型、必要时覆写端点路径，并为自签名或内部 CA 的 HTTPS 端点配置 TLS。

自定义上游接入在通用接入规则与 OpenAI 兼容接入之上，补充三类能力：自定义入口地址（指向你的私有端点）、请求类型限制（控制每个实例可执行哪些操作）、端点路径覆写（适配非标准 URL 形态）。本页只写这些差异。

1. 一基底、多实例

自定义上游接入的核心是：在同一个 OpenAI 兼容基底上，按不同配置创建多个上游实例，每个实例可有不同的入口地址、密钥与请求类型限制，相当于同一底层服务的"多个视图"。典型用法：

用法	说明
环境分离	为生产 / 预发 / 开发各建一个实例，指向不同入口地址、给不同请求类型权限
按角色控权	不同实例开放不同的请求类型，配合子账户密钥的模型范围做分级授权
灰度与试用	新建实例只开放试用请求类型，验证稳定后再放开完整能力

2. 接入配置

登记一个自定义上游，在标准接入字段上补 network_config（入口地址等网络配置）与 custom_provider_config（基底类型、允许的请求类型、路径覆写）：

curl https://your-platform/api/v1/providers \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "<自定义上游显示名>",
    "source": "self",
    "type": "openai-compatible",
    "models": ["<模型中性名>"],
    "network_config": {
      "base_url": "<私有端点入口地址>",
      "request_timeout": "60s"
    },
    "custom_provider_config": {
      "base_protocol": "openai-compatible",
      "allowed_requests": {
        "chat_completion": true,
        "chat_completion_stream": true,
        "embedding": false
      }
    }
  }'

字段	含义
`network_config.base_url`	私有端点的入口地址，所有请求以此为基址拼接路径
`custom_provider_config.base_protocol`	基底协议形态（此处为 `openai-compatible`）
`custom_provider_config.allowed_requests`	该实例允许的请求类型映射（见 §3）
`custom_provider_config.request_path_overrides`	端点路径覆写（见 §4）

3. 允许的请求类型

allowed_requests 控制该实例可执行哪些操作，按以下语义判定：

配置形态	行为
完全省略	全部操作放行（默认）
部分指定	仅显式设为 `true` 的操作放行，其余默认 `false`
给出空对象 `{}`	全部操作关闭

可控的操作类型：

操作	含义
`chat_completion`	标准对话补全
`chat_completion_stream`	流式对话补全
`embedding`	嵌入生成
`text_completion`	传统文本补全
`transcription`	语音转文本
`speech`	文本转语音

请求类型限制是分级授权的抓手。 给生产实例开放完整请求类型、给开发实例只开放非流式对话补全，再配合子账户密钥的模型范围，即可实现按环境、按角色的细粒度控权，无需为不同权限维护多套底层服务。

4. 端点路径覆写

当私有端点的 URL 形态与 OpenAI 默认路径不同时，用 request_path_overrides 按请求类型覆写路径。覆写值可为相对路径（相对 base_url）或完整 URL（绕过 base_url）：

{
  "request_path_overrides": {
    "chat_completion": "/api/v2/chat",
    "chat_completion_stream": "/api/v2/chat",
    "embedding": "/api/v2/embeddings"
  }
}

上例中，对话补全请求不再走默认的 /v1/chat/completions，而是发往 <私有端点入口地址>/api/v2/chat。若覆写值是带协议与主机的完整 URL，平台直接使用该 URL 并忽略 base_url，从而把不同请求类型路由到完全不同的端点。

适用场景：接入自托管或定制的模型服务、对接期望特定 URL 形态的私有网关、使用改了 API 路径的服务分支。

5. TLS：自签名与内部 CA

当私有端点用自签名证书或内部 CA 颁发的证书时（如隔离网络环境、内部服务），在 network_config 中配置 TLS。两个选项互斥，不可同时设置：

字段	类型	说明
`ca_cert_pem`	字符串	信任的 PEM 编码 CA 证书；端点用自定义 CA 时首选此项
`insecure_skip_verify`	布尔	关闭 TLS 证书校验；仅限可信的内部隔离环境，不建议用于生产

首选：提供内部 CA 证书（安全、可校验）：

{
  "network_config": {
    "base_url": "<内部端点入口地址>",
    "ca_cert_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  }
}

次选：跳过校验（仅限隔离网络环境）：

{
  "network_config": {
    "base_url": "<内部端点入口地址>",
    "insecure_skip_verify": true
  }
}

优先用 ca_cert_pem。 insecure_skip_verify: true 会关闭全部证书校验，存在被中间人攻击的风险，仅应在完全可信、与外网隔离的环境中临时使用；只要拿得到内部 CA 证书，就用 ca_cert_pem。接入配置校验会拒绝同时设置二者的组合。

6. 接入后调度

自定义上游一经接入，即与自有供应模型、第三方兼容上游进入同一个模型池，由路由中间件统一按分组、优先级、权重调度，享受相同的模型池准入、计量与护栏治理：

curl https://your-platform/api/v1/providers/<上游标识>/probe \
  -X POST \
  -H "Cookie: <控制台会话凭证>"

{
  "provider_id": "<上游标识>",
  "status": "available",
  "probe_latency_ms": 0,
  "probed_at": "<探测时间>"
}

探测通过后，其登记的中性名进入模型池准入判定（智能水平指数达门槛才参与路由）。自定义上游常与公有上游供给同一中性名，作为互为备份的候选层——自托管实例承接日常流量、公有上游作降级兜底，或反之。

对外仍只见中性名。 自定义上游接入后，模型同样以中性名出现在数据平面 GET /v1/models 与逐条调用记录中；私有端点地址、入口凭证等仅在运营控制台可见，不向客户应用暴露。其超时、重试、并发与队列容量等性能参数按性能与故障转移调优单独调优。

下一步

OpenAI 兼容接入：自定义上游所基于的 OpenAI 兼容协议映射要点。
通用接入规则：登记字段、模型池准入、分组路由与故障转移的统一规则。
性能与故障转移调优：自定义上游的超时、重试、健康检查与吞吐参数调优。
API 参考：上游接入接口的完整端点契约。