codecamp

OpenAI Private Link

OpenAI Private Link 允许 Azure 工作负载通过 Azure 私有网络连接区域 OpenAI API 端点。为每个 OpenAI 提供的区域 Private Link Service 建立私有端点,将区域主机名映射到私有 DNS,再向该主机发送正常认证的 API 请求。

它适合严格要求 Azure 私有网络的组织。没有私网要求时,公开端点配置和运营更简单。Private Link 与 IP 允许列表、mTLS 不兼容;选择企业网络控制时可联系 OpenAI。

目前不支持自助开通。请联系 OpenAI 联系人或销售,申请访问并获取区域服务别名或资源标识。

理解 Private Link 的工作方式

旧版 v1 每个私有端点绑定特定 API 集群,当前区域方案有所不同:

对比项 旧版 v1 区域 Private Link
主机名 集群专用,如 privatelink.enterprise.unified-1.api.openai.com 区域主机,如 southcentralus.privatelink.api.openai.com
OpenAI 路由 固定一个 API 集群 区域私有边缘网关,可路由至多个后端集群
客户健康检查 旧 v1 健康检查路径 GET /v2/privatelink_healthcheck

请求先在私有 DNS 解析区域主机名,得到虚拟网络中的 Azure Private Endpoint,连接区域 OpenAI Private Link Service,再进入区域私有边缘网关,由其路由至该区域链路支持的企业 API 后端集群。

同一区域链路可绕开故障集群,OpenAI 增加后端也无须客户重配端点,但不会自动把流量迁移到另一区域私有端点。不要假设继承公开端点的路由行为;须配置应用跨区域故障转移。

选择区域端点

开通时 OpenAI 提供精确服务别名或资源 ID。当前生产主机如下:

区域 客户主机名
美国中南部 southcentralus.privatelink.api.openai.com
美国西部 westus.privatelink.api.openai.com
美国东部2 eastus2.privatelink.api.openai.com
西班牙中部/欧洲 spaincentral.privatelink.api.openai.com

西班牙中部/欧洲主机可能路由至北欧等其他欧洲区域的后端。

设置 Private Link

1. 提供开通信息

向 OpenAI 提供需要访问的 Azure 订阅 ID、OpenAI 组织 ID、所需区域,以及维护和区域流量切换通知的运维联系人。OpenAI 为订阅授予相应服务的可见性和批准,再提供别名或资源 ID。

2. 创建私有端点

每个所选区域创建一个端点。Azure 要求端点与客户虚拟网络同区域;--location 应设为该区域,可能不同于 OpenAI 服务区域。使用 OpenAI 提供的资源 ID:

来源示例 1(bash):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
az network private-endpoint create \
  --name openai-privatelink-southcentralus \
  --resource-group <customer-resource-group> \
  --location <customer-vnet-region> \
  --vnet-name <customer-vnet> \
  --subnet <customer-private-endpoint-subnet> \
  --private-connection-resource-id <openai-provided-pls-resource-id> \
  --connection-name openai-privatelink-southcentralus

若提供的是别名,使用别名并增加 --manual-request true:

来源示例 2(bash):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
az network private-endpoint create \
  --name openai-privatelink-southcentralus \
  --resource-group <customer-resource-group> \
  --location <customer-vnet-region> \
  --vnet-name <customer-vnet> \
  --subnet <customer-private-endpoint-subnet> \
  --private-connection-resource-id <openai-provided-pls-alias> \
  --connection-name openai-privatelink-southcentralus \
  --manual-request true

Azure 的别名连接要求此参数,但允许列表内订阅仍可能自动获批。也可通过 Azure 门户或 Terraform 完成等价配置。

3. 修改 DNS 前先测试连接

OpenAI 批准并由 Azure 配置端点后,记录私有 IP。通过 curl --resolve 测试区域主机,不先全局改 DNS:

来源示例 3(bash):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
curl -v \
  --resolve southcentralus.privatelink.api.openai.com:443:<PRIVATE_ENDPOINT_IP> \
  https://southcentralus.privatelink.api.openai.com/v2/privatelink_healthcheck

健康时返回 HTTP 200 和类似响应:

来源示例 4(json):

中文说明:来源配置或结果示例,按所在小节的字段、作用域与权限要求解释;JSON保持合法格式,CEL/声明匹配文本不是可独立运行的应用。

{ "message": "Service is up" }

路径必须是 /v2/privatelink_healthcheck。自动探测每区域端点最多 1 QPS,除非 OpenAI 批准其他频率。

4. 配置私有 DNS

让各区域主机在自己的网络中解析到对应私有端点 IP:

主机名 私有端点 IP
southcentralus.privatelink.api.openai.com <southcentralus-private-endpoint-ip>
westus.privatelink.api.openai.com <westus-private-endpoint-ip>
eastus2.privatelink.api.openai.com <eastus2-private-endpoint-ip>
spaincentral.privatelink.api.openai.com <spaincentral-private-endpoint-ip>

从应用使用的同一网络路径检查 DNS 与连通性:

来源示例 5(bash):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
nslookup southcentralus.privatelink.api.openai.com
curl -v https://southcentralus.privatelink.api.openai.com/v2/privatelink_healthcheck

5. 配置跨区域故障转移

客户端、服务网格、DNS 或负载均衡层须主动配置区域切换。探测每区域的 GET /v2/privatelink_healthcheck,200 视为可用,5xx、连接/TLS 错误或反复超时视为不可用。连续少量失败后再切换以避免抖动,后台持续探测故障区域,按运维政策恢复流量。

健康检查反映区域私有边缘链路后端集群状态。无已知后端、缺健康配置或健康集群不足会返回错误。若路由决策依赖特定模型或 API,再从同一路径低频发送针对该模型/API 的合成请求。

6. 更新应用基础 URL

将区域主机作为 API base URL:

来源示例 6(python):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
from openai import OpenAI

client = OpenAI(
    base_url="https://southcentralus.privatelink.api.openai.com/v1",
)

来源示例 7(ruby):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
client = OpenAI::Client.new(
  base_url: "https://southcentralus.privatelink.api.openai.com/v1"
)

SDK 从环境读取 OPENAI_API_KEY。也可直接调用:

来源示例 8(bash):

## [中文] 按本小节配置或检查区域Private Link;只改变网络路径,仍需正常API认证,跨区域故障转移由客户配置。
curl https://southcentralus.privatelink.api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Say hello from Private Link."
  }'

先在开发或预发布环境使用,再逐渐扩大流量。

核查配置

确认 OpenAI 已授权订阅访问所选区域服务、各端点获批、IP 已记录;curl --resolve 健康检查成功;应用网络内 DNS 解析正确;区域主机下代表性 /v1 API 可调用;探测已限流且记录错误区域/状态码/类型;在受控环境强制区域不健康并验证切换;运维文档明确 DNS、端点配置与区域路由的变更负责人。

核查端点兼容性

下表描述当前列出路由背后的部署配置,不替代客户实测。须在每个目标区域测试模型、产品开关、下游依赖、请求体限制、流式与 WebSocket 行为。Yes 表示该链路所有后端集群都有该路由,No 表示该区域链路没有该后端服务。

端点类别 美国中南部 美国西部 美国东部2 西班牙中部/欧洲
/v1/responses 是 是 是 是
/v1/chat/completions 是 是 是 是
/v1/completions 是 是 是 是
/v1/embeddings 是 是 是 是
/v1/audio/* (推理) 是 是 是 是
/v1/audio/* (管理) 是 否 否 是
/v1/models 是 是 是 是
/v1/files, /v1/uploads 是 是 是 是
/v1/batches 是 是 是 是
/v1/images/* 是 是 是 是
/v1/moderations 是 是 是 是
/v1/vector_stores 是 是 是 是
/v1/organization/audit_logs 是 是 是 是
其他 /v1/organization/*, /v1/usage 是 否 否 是
/v1/realtime 是 是 是 是

常见问题

是否自动跨区域故障转移

不会。区域内可路由到配置的其他后端集群,但不会自动将流量移到其他区域私有端点,须由应用配置。

应使用哪个健康检查

在区域主机调用 GET /v2/privatelink_healthcheck。旧 v1 路径探测的是后端集群健康链路,不应用作客户探针。

应用应使用哪个主机

使用区域主机和正常 /v1 路径,例如 https://southcentralus.privatelink.api.openai.com/v1。

AWS 或 Google Cloud 能否连接

不能直接连接。此能力专属 Azure。其他云须先通过客户管理的跨云私网或 Azure 代理进入 Azure,再经 Azure Private Link 连接 OpenAI。

是否改变认证方式

不改变。它只改变网络路径,仍要求正常的 OpenAI API 身份验证与授权。

是否支持所有 OpenAI API

不支持。取决于目标区域链路的每个后端集群是否都有相应 API。以矩阵为起点,再实测所需 API 与模型。

OpenAI API 组织访问限制
OpenAI 平台权限管理
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }