如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

Private Link

讓 Azure 工作負載透過 Azure Private Link 連線至區域 OpenAI API 端點。

使用 OpenAI Private Link,Azure 工作負載即可透過 Azure Private Link 存取區域 OpenAI API 端點,無須直接連線至公用 API 端點。請為 OpenAI 提供的每個區域 Private Link 服務建立私人端點,在私人 DNS 中將該區域的主機名稱對應至私人端點,然後照常向該主機名稱傳送經過驗證的 API 請求。

如果組織嚴格要求流量只能經由 Azure 私人網路傳輸,請使用 Private Link。如果沒有私人網路方面的要求,OpenAI 公用端點的設定與維運會比較簡單。Private Link 與 IP 允許清單或雙向 TLS(mTLS)不相容。如需協助選擇合適的企業網路控管措施,請聯絡 OpenAI。

Private Link 目前尚未開放自助申請。請洽你的 OpenAI 聯絡窗口或聯絡業務團隊,以申請存取權並取得所需的區域 Private Link 服務別名或資源識別碼。

部分客戶一直使用舊版 Private Link 方案(v1)。在舊版方案中,每個私人端點都會連線至特定的 OpenAI API 叢集。現行區域方案與舊版的差異如下:

舊版 Private Link(v1) 區域 Private Link
主機名稱 依叢集而定,例如 privatelink.enterprise.unified-1.api.openai.com 依區域而定,例如 southcentralus.privatelink.api.openai.com
OpenAI 路由 固定將請求傳送至單一 OpenAI API 叢集 區域私人邊緣閘道可將請求傳送至多個後端 OpenAI API 叢集
客戶使用的健康檢查 舊版 v1 健康檢查路徑 GET /v2/privatelink_healthcheck

請求會經過以下路徑:

  1. 應用程式透過你的私人 DNS 查詢區域 Private Link 主機名稱。
  2. DNS 將該主機名稱解析為虛擬網路中 Azure 私人端點的位址。
  3. 私人端點連線至該區域的 OpenAI Private Link 服務。
  4. Private Link 服務將請求傳送至 OpenAI 的區域私人邊緣閘道。
  5. 閘道將請求傳送至該區域路徑上已啟用企業功能的後端 OpenAI API 叢集。

在同一條區域路徑內,Private Link 可以繞過無法使用的後端叢集。OpenAI 也可以新增後端叢集,而你無須重新設定私人端點。Private Link 不會自動將流量從你選定的區域主機名稱轉送至其他區域的私人端點。請勿假設 Private Link 的路由行為與 OpenAI 公用端點相同。請自行設定應用程式如何在區域之間進行容錯移轉。

選擇區域端點

OpenAI 會在導入時提供確切的 Private Link 服務別名或資源識別碼。目前正式環境的區域主機名稱如下:

區域名稱 客戶使用的主機名稱
美國中南部 southcentralus.privatelink.api.openai.com
美國西部 westus.privatelink.api.openai.com
美國東部 2 eastus2.privatelink.api.openai.com
西班牙中部/歐盟 spaincentral.privatelink.api.openai.com

傳送至西班牙中部/歐盟主機名稱的請求,也可能會轉送至北歐等其他歐盟區域的後端叢集。

1. 提供導入所需的資訊

請將以下資訊提供給 OpenAI:

  • 需要存取 OpenAI Private Link 服務的 Azure 訂用帳戶 ID。
  • 你的 OpenAI 組織 ID。
  • 你需要使用的區域。
  • 負責接收維護與區域流量切換通知的維運聯絡人。

OpenAI 會授權這些訂用帳戶查看並連線至對應的區域 Private Link 服務,再提供服務別名或資源識別碼。

2. 建立私人端點

請為每個選定的區域各建立一個私人端點。Azure 要求私人端點與客戶的虛擬網路位於同一區域。請將 --location 設為虛擬網路所在的區域,這個區域可能與 OpenAI Private Link 服務所在的區域不同。

以下指令使用 OpenAI 提供的 Private Link 服務資源識別碼:

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

如果 OpenAI 提供的是別名,請使用該別名並加上 --manual-request true:

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 要求指定 --manual-request true 才能使用別名連線。存取清單中的訂用帳戶仍可獲得自動核准。

如果組織以基礎結構即程式碼的方式管理私人端點,可以透過 Azure 入口網站或 Terraform 執行類似的流程。

3. 變更 DNS 前先測試連線

等 OpenAI 核准私人端點且 Azure 完成佈建後,請記下該端點的私人 IP 位址。使用 curl --resolve 即可測試區域主機名稱,無須變更全域 DNS 設定:

curl -v \
  --resolve southcentralus.privatelink.api.openai.com:443:<PRIVATE_ENDPOINT_IP> \
  https://southcentralus.privatelink.api.openai.com/v2/privatelink_healthcheck

服務正常時會傳回 HTTP 200,並附上類似以下的訊息:

{ "message": "Service is up" }

健康檢查路徑必須是 /v2/privatelink_healthcheck。請控制自動健康檢查的流量。除非 OpenAI 核准其他頻率,否則每秒最多只能向每個區域端點傳送 1 個健康檢查請求(1 QPS)。

4. 設定私人 DNS

請建立私人 DNS 記錄,讓網路內的每個區域 OpenAI Private Link 主機名稱都能解析為對應的私人端點 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 和連線:

nslookup southcentralus.privatelink.api.openai.com
curl -v https://southcentralus.privatelink.api.openai.com/v2/privatelink_healthcheck

5. 設定跨區域容錯移轉

Private Link 提供區域入口,但流量仍會送往你選定的區域主機名稱。請設定用戶端、服務網格、DNS 層或負載平衡層,以便在區域之間進行容錯移轉。

建議採用以下做法:

  • 使用 GET /v2/privatelink_healthcheck 探測每個已設定的區域。
  • 收到 HTTP 200 時,將該區域視為可用。
  • 收到 5xx 回應、發生連線或 TLS 錯誤,或多次逾時時,將該區域視為無法使用。
  • 等到連續發生幾次錯誤後,再進行容錯移轉,以免在區域之間頻繁切換。
  • 在背景持續探測無法使用的區域,並依維運政策切回原區域。

區域健康檢查反映該區域私人邊緣路徑後方 OpenAI API 叢集的健康狀態。如果該區域沒有已知的後端叢集、缺少健康檢查設定,或正常運作的後端叢集數量不足,健康檢查就會傳回錯誤。

如果路由決策取決於特定 API 或模型,除了執行這項健康檢查,也請透過同一條網路路徑,以低頻率向該 API 和模型傳送模擬請求。

6. 更新應用程式的基底 URL

請使用區域 Private Link 主機名稱作為 OpenAI API 的基底 URL:

from openai import OpenAI

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

SDK 會從環境變數讀取 OPENAI_API_KEY。

你也可以直接呼叫區域端點:

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."
  }'

請先在開發或預備環境中測試,再逐步導入正式環境的流量。

檢查設定

導入或遷移至 Private Link 時,請逐項確認:

  • OpenAI 已確認你的 Azure 訂用帳戶 ID 可存取選定的區域 Private Link 服務。
  • 你已為每個選定的區域建立私人端點,且 OpenAI 已核准這些端點。
  • 你已記下各私人端點的 IP 位址。
  • curl --resolve 可成功存取 /v2/privatelink_healthcheck。
  • 從應用程式所在的網路查詢時,私人 DNS 會將區域主機名稱解析為私人端點 IP 位址。
  • 應用程式可以透過區域主機名稱呼叫具代表性的 /v1 API 端點。
  • 自動健康檢查已設定速率限制,並會在發生錯誤時記錄區域、狀態碼與錯誤類型。
  • 你已在受控環境中強制將一個區域設為不健康狀態,以測試應用程式的容錯移轉行為。
  • 維運文件已載明誰有權變更 DNS、私人端點設定及應用程式的區域路由。

檢查端點相容性

下表列出各公用 API 路由所對應服務的目前部署狀況。你仍須在自己的環境中實際驗證,並在每個目標區域測試模型可用性、產品存取條件、下游相依項目、請求大小限制,以及串流和 WebSocket 的行為。Yes 表示該區域路徑上的每個後端叢集都支援該路由。No 表示該路徑上未部署對應的後端服務。

端點類別 美國中南部 美國西部 美國東部 2 西班牙中部/歐盟
/v1/responses Yes Yes Yes Yes
/v1/chat/completions Yes Yes Yes Yes
/v1/completions Yes Yes Yes Yes
/v1/embeddings Yes Yes Yes Yes
/v1/audio/*(推論) Yes Yes Yes Yes
/v1/audio/*(管理) Yes No No Yes
/v1/models Yes Yes Yes Yes
/v1/files、/v1/uploads Yes Yes Yes Yes
/v1/batches Yes Yes Yes Yes
/v1/images/* Yes Yes Yes Yes
/v1/moderations Yes Yes Yes Yes
/v1/vector_stores Yes Yes Yes Yes
/v1/organization/audit_logs Yes Yes Yes Yes
其他 /v1/organization/* 端點、/v1/usage Yes No No Yes
/v1/realtime Yes Yes Yes Yes

常見問題

不會。區域私人邊緣路徑可將請求分送至該路徑上已設定的後端叢集,但不會自動將流量移轉至其他區域的私人端點。請設定應用程式,讓它能在你使用的各區域端點之間進行容錯移轉。

我應該使用哪一項健康檢查?

請對區域主機名稱執行 GET /v2/privatelink_healthcheck。舊版 v1 健康檢查路徑用於探測後端叢集的健康檢查路徑,請勿用於客戶端探測。

應用程式應使用哪個 API 主機名稱?

請使用區域主機名稱搭配一般的 /v1 API 路徑,例如 https://southcentralus.privatelink.api.openai.com/v1。

無法直接連線。Private Link 連線僅適用於 Azure。AWS 或 Google Cloud 工作負載必須先透過客戶自行管理的網路連線至 Azure,例如使用 Azure 中的 Proxy 或跨雲端私人連線,再從 Azure 透過 Azure Private Link 連線至 OpenAI。

不會。Private Link 只會改變網路路徑。請求仍須依照一般 OpenAI API 的方式進行驗證與授權。

不支援所有 API。能否使用某個 API,取決於選定區域路徑上的每個後端叢集是否都提供該 API。請先參考相容性表,再於每個目標區域測試你需要的各項 API 功能和模型。