Private Link

OpenAI Private Link를 사용하면 Azure 워크로드가 공개 API 엔드포인트에 직접 연결하는 대신 Azure Private Link를 통해 지역 OpenAI API 엔드포인트에 도달할 수 있습니다. OpenAI가 제공하는 각 지역 Private Link Service에 대한 프라이빗 엔드포인트를 만들고, 사설 DNS에 지역 호스트 이름을 매핑하고, 일반 인증된 API 요청을 그 호스트 이름으로 보내세요.

조직이 트래픽을 Azure 사설 네트워킹에 유지하라는 엄격한 요구 사항이 있을 때 Private Link를 사용하세요. 사설 네트워크 요구 사항이 없다면 OpenAI의 공개 엔드포인트가 설정하고 운영하기 더 간단합니다. Private Link는 IP 허용 목록 제어나 상호 TLS(mTLS)와 호환되지 않습니다. 올바른 엔터프라이즈 네트워크 제어를 선택하는 데 도움이 필요하면 OpenAI에 문의하세요.

Private Link는 현재 셀프서비스가 아닙니다. OpenAI 담당자와 협력하거나 영업에 문의해 접근을 요청하고 필요한 지역 Private Link Service 별칭이나 리소스 식별자를 받으세요.

출처: 문서

본문

Private Link 작동 방식 이해하기

일부 고객은 각 Private Endpoint를 특정 OpenAI API 클러스터에 연결하는 레거시 Private Link 솔루션(v1)을 사용해 왔습니다. 현재 지역 솔루션은 다음과 같은 점에서 다릅니다:

	레거시 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`

요청은 다음 경로를 따릅니다:

애플리케이션이 사설 DNS를 통해 지역 Private Link 호스트 이름을 해석합니다.
호스트 이름이 가상 네트워크의 Azure Private Endpoint로 해석됩니다.
Private Endpoint가 지역 OpenAI Private Link Service에 연결합니다.
Private Link Service가 요청을 OpenAI의 지역 프라이빗 엣지 게이트웨이로 보냅니다.
게이트웨이가 요청을 해당 지역 레일(rail)의 엔터프라이즈 지원 지원 OpenAI API 클러스터로 라우팅합니다.

지역 레일 내에서 Private Link는 사용할 수 없는 지원 클러스터를 우회해 라우팅할 수 있으며, OpenAI는 Private Endpoint를 다시 구성할 필요 없이 지원 클러스터를 추가할 수 있습니다. 선택한 지역 호스트 이름에서 다른 지역 Private Endpoint로 트래픽을 자동으로 이동하지는 않습니다. Private Link가 OpenAI의 공개 엔드포인트 라우팅 동작을 상속한다고 가정하지 마세요. 애플리케이션이 지역 간에 어떻게 장애 조치(failover)하는지 구성하세요.

지역 엔드포인트 선택

OpenAI는 온보딩 중 정확한 Private Link Service 별칭 또는 리소스 식별자를 제공합니다. 현재 프로덕션 지역 호스트 이름은 다음과 같습니다:

지역 라벨	고객 호스트 이름
South Central US	`southcentralus.privatelink.api.openai.com`
West US	`westus.privatelink.api.openai.com`
East US 2	`eastus2.privatelink.api.openai.com`
Spain Central / EU	`spaincentral.privatelink.api.openai.com`

Spain Central / EU 호스트 이름은 North Europe 같은 다른 EU 지역의 지원 클러스터로 라우팅할 수 있습니다.

Private Link 설정

1. 온보딩 정보 제공

OpenAI에 다음을 보내세요:

OpenAI Private Link Services에 접근해야 하는 Azure 구독 ID.
OpenAI 조직 ID.
필요한 지역.
유지보수 및 지역 트래픽 전환 공지용 운영 담당자.

OpenAI는 적절한 지역 Private Link Services에 대한 구독 가시성과 승인을 부여한 뒤 Private Link Service 별칭 또는 리소스 식별자를 제공합니다.

2. 프라이빗 엔드포인트 만들기

선택한 각 지역에 대해 Private Endpoint를 하나 만드세요. Azure는 Private Endpoint가 고객 가상 네트워크의 지역을 공유하도록 요구합니다. --location을 그 지역으로 설정하세요. 이는 OpenAI Private Link Service 지역과 다를 수 있습니다.

다음 명령은 OpenAI 제공 Private Link Service 리소스 식별자를 사용합니다:

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를 요구합니다. 접근 목록에 있는 구독은 여전히 자동 승인을 받을 수 있습니다.

조직이 infrastructure as code로 Private Endpoint를 관리한다면 유사한 Azure Portal 또는 Terraform 워크플로를 사용하세요.

3. DNS 변경 전 연결 테스트

OpenAI가 Private Endpoint를 승인하고 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 QPS.

4. 사설 DNS 구성

각 지역 OpenAI Private Link 호스트 이름이 네트워크 내부의 해당 Private Endpoint IP 주소로 해석되도록 사설 DNS 레코드를 만드세요:

호스트 이름	Private Endpoint 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 오류 또는 반복적인 타임아웃을 사용 불가로 처리하세요.
플래핑(flapping)을 피하기 위해 소수의 연속 오류 후에만 장애 조치하세요.
사용 불가 지역을 백그라운드에서 계속 프로브하고 운영 정책에 따라 페일백하세요.

지역 상태 확인은 프라이빗 엣지 레일 뒤의 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",
)

client = OpenAI::Client.new(
  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 ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Say hello from Private Link."
  }'

개발 또는 스테이징 환경에서 시작한 뒤 트래픽을 점진적으로 올리세요.

구성 확인

Private Link 온보딩 또는 마이그레이션 중 이 체크리스트를 사용하세요:

OpenAI가 Azure 구독 ID가 선택한 지역 Private Link Services에 접근할 수 있다고 확인했습니다.
Private Endpoint를 만들었고 OpenAI가 선택한 각 지역에 대해 승인했습니다.
Private Endpoint IP 주소를 기록했습니다.
curl --resolve가 /v2/privatelink_healthcheck에 성공합니다.
사설 DNS가 애플리케이션 네트워크에서 지역 호스트 이름을 Private Endpoint IP 주소로 해석합니다.
애플리케이션이 지역 호스트 이름을 통해 대표 /v1 API 엔드포인트를 호출할 수 있습니다.
상태 확인 자동화가 요율 제한되고 오류에 대해 지역, 상태 코드, 오류 유형을 로그합니다.
통제된 환경에서 지역을 비정상으로 만들어 애플리케이션이 장애 조치하는 방식을 테스트했습니다.
운영 문서에 DNS, Private Endpoint 구성, 애플리케이션 지역 라우팅을 변경할 수 있는 사람을 식별해 두었습니다.

엔드포인트 호환성 확인

다음 매트릭스는 나열된 공개 API 경로 뒤 서비스의 현재 배포 구성을 반영합니다. 라이브 고객 검증을 대체하지 않습니다: 각 대상 지역에서 모델 가용성, 제품 게이트, 다운스트림 의존성, 요청 크기 한도, 스트리밍 동작, WebSocket 동작을 테스트하세요. Yes는 지역 레일의 모든 지원 클러스터에 경로가 있음을, No는 지원 서비스가 그 레일에 없음을 의미합니다.

엔드포인트 계열	South Central US	West US	East US 2	Spain Central / EU
`/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/*` (Inference)	Yes	Yes	Yes	Yes
`/v1/audio/*` (management)	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
Other `/v1/organization/*`, `/v1/usage`	Yes	No	No	Yes
`/v1/realtime`	Yes	Yes	Yes	Yes

자주 묻는 질문

Private Link는 지역 간에 자동으로 장애 조치되나요?

아니요. 지역 프라이빗 엣지 레일은 구성된 지원 클러스터 간에 라우팅할 수 있지만, 트래픽을 다른 지역 Private Endpoint로 자동 이동하지는 않습니다. 사용하는 지역 엔드포인트 전체에서 애플리케이션이 장애 조치하도록 구성하세요.

어떤 상태 확인을 사용해야 하나요?

지역 호스트 이름에서 GET /v2/privatelink_healthcheck를 사용하세요. 이전 v1 상태 확인 경로는 지원 클러스터 상태 레일을 프로브하므로 고객 대상 프로브로 사용하지 마세요.

애플리케이션은 어떤 API 호스트 이름을 사용해야 하나요?

지역 호스트 이름과 일반 /v1 API 경로를 사용하세요. 예: https://southcentralus.privatelink.api.openai.com/v1.

AWS나 Google Cloud 워크로드가 Private Link로 연결될 수 있나요?

직접은 아닙니다. Private Link 연결은 Azure 전용입니다. AWS나 Google Cloud의 워크로드는 Azure 프록시나 크로스 클라우드 사설 연결 패턴 같은 고객 관리 네트워킹을 통해서만 Azure에 연결한 뒤, Azure에서 Azure Private Link를 통해 OpenAI에 연결할 수 있습니다.

Private Link가 인증을 변경하나요?

아니요. Private Link는 네트워크 경로만 변경합니다. 요청에는 여전히 일반 OpenAI API 인증과 권한 부여가 필요합니다.

Private Link가 모든 OpenAI API를 지원하나요?

아니요. 지원 여부는 선택한 지역 레일의 모든 지원 클러스터에 API가 있는지에 따라 다릅니다. 호환성 매트릭스를 시작점으로 사용한 뒤, 필요한 각 API 표면과 모델을 모든 대상 지역에서 테스트하세요.

더 알아보기 (Learn more)

Private Link 원문