Private Link

OpenAI Private Link를 사용하면 Azure 워크로드가 퍼블릭 API 엔드포인트에 직접 연결하는 대신 Azure Private Link를 통해 지역별 OpenAI API 엔드포인트에 접근할 수 있습니다. OpenAI가 제공하는 지역별 Private Link 서비스마다 프라이빗 엔드포인트를 만들고, 프라이빗 DNS에서 해당 지역 호스트 이름을 엔드포인트의 IP 주소에 매핑하세요. 그런 다음 평소와 같은 방식으로 인증된 API 요청을 해당 호스트 이름으로 보내세요.

조직에서 트래픽을 반드시 Azure 프라이빗 네트워크 안에서만 전송해야 한다면 Private Link를 사용하세요. 프라이빗 네트워크 사용 요건이 없다면 OpenAI 퍼블릭 엔드포인트를 설정하고 운영하는 편이 더 간단합니다. Private Link는 IP 허용 목록 기반 접근 제어나 상호 TLS(mTLS)와 호환되지 않습니다. 조직에 적합한 네트워크 접근 제어 방식을 선택하는 데 도움이 필요하면 OpenAI에 문의하세요.

Private Link 작동 방식

일부 고객이 사용해 온 기존 Private Link 솔루션(v1)은 각 프라이빗 엔드포인트를 특정 OpenAI API 클러스터에 연결합니다. 현재의 지역별 솔루션과는 다음과 같은 차이가 있습니다.

요청은 다음 경로를 거칩니다.

1. 애플리케이션이 프라이빗 DNS에서 지역별 Private Link 호스트 이름을 조회합니다.
2. DNS는 해당 호스트 이름에 대해 고객 가상 네트워크에 있는 Azure 프라이빗 엔드포인트의 IP 주소를 반환합니다.
3. 프라이빗 엔드포인트가 해당 지역의 OpenAI Private Link 서비스에 연결됩니다.
4. Private Link 서비스가 요청을 OpenAI의 지역별 프라이빗 에지 게이트웨이로 보냅니다.
5. 게이트웨이가 요청을 해당 지역 경로에서 엔터프라이즈 요청을 처리하도록 설정된 백엔드 OpenAI API 클러스터로 전달합니다.

같은 지역 경로 안에서는 Private Link가 사용 불가능한 백엔드 클러스터를 우회할 수 있습니다. OpenAI가 백엔드 클러스터를 추가해도 고객이 프라이빗 엔드포인트를 다시 구성할 필요는 없습니다. 다만 선택한 지역 호스트 이름으로 보낸 트래픽이 다른 지역의 프라이빗 엔드포인트로 자동 전환되지는 않습니다. OpenAI 퍼블릭 엔드포인트와 동일한 라우팅 동작을 기대하지 말고, 애플리케이션의 지역 간 장애 조치 방식을 구성하세요.

지역별 엔드포인트 선택

온보딩 과정에서 OpenAI가 해당 Private Link 서비스의 정확한 별칭 또는 리소스 식별자를 제공합니다. 현재 프로덕션 환경의 지역별 호스트 이름은 다음과 같습니다.

스페인 중부 / EU 호스트 이름으로 보낸 요청은 북유럽 등 다른 EU 지역의 백엔드 클러스터로 라우팅될 수 있습니다.

Private Link 설정

1. 온보딩 정보 제공

다음 정보를 OpenAI에 보내세요.

• OpenAI Private Link 서비스에 액세스해야 하는 Azure 구독의 ID
• OpenAI 조직 ID
• 사용할 지역
• 유지 관리 및 지역 간 트래픽 전환 알림을 받을 운영 담당자 연락처

OpenAI는 해당 구독에 필요한 지역별 Private Link 서비스를 조회할 권한을 부여하고 해당 서비스에 대한 액세스를 승인한 다음, 서비스 별칭 또는 리소스 식별자를 제공합니다.

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

선택한 지역마다 프라이빗 엔드포인트를 하나씩 만드세요. Azure에서는 프라이빗 엔드포인트가 고객 가상 네트워크와 같은 지역에 있어야 합니다. --location에는 고객 가상 네트워크의 지역을 지정하세요. 이 지역은 OpenAI Private Link 서비스의 지역과 다를 수 있습니다.

다음 명령어는 OpenAI가 제공한 Private Link 서비스 리소스 식별자를 사용합니다.

12345678az 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를 추가하세요.

123456789az 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 Portal이나 Terraform에서도 비슷한 워크플로우를 사용할 수 있습니다.

3. DNS 변경 전 연결 테스트

OpenAI가 프라이빗 엔드포인트를 승인하고 Azure가 프로비저닝하면 해당 엔드포인트의 프라이빗 IP 주소를 기록하세요. curl --resolve를 사용하면 전체 DNS 설정을 변경하지 않고도 지역 호스트 이름으로 연결을 테스트할 수 있습니다.

123curl -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 구성

고객 네트워크 안에서 각 지역의 OpenAI Private Link 호스트 이름을 조회하면 해당 프라이빗 엔드포인트의 IP 주소가 반환되도록 프라이빗 DNS 레코드를 만드세요.

애플리케이션이 사용하는 네트워크 경로에서 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로 사용하세요.

1
2
3
4
5from openai import OpenAI

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

1
2
3client = OpenAI::Client.new(
  base_url: "https://southcentralus.privatelink.api.openai.com/v1"
)

SDK는 환경 변수에서 OPENAI_API_KEY를 읽습니다.

지역별 엔드포인트를 직접 호출할 수도 있습니다.

1
2
3
4
5
6
7curl 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는 해당 지역 경로의 모든 백엔드 클러스터에 해당 API 경로가 있다는 뜻입니다. No는 해당 지역 경로에 그 요청을 처리하는 백엔드 서비스가 없다는 뜻입니다.

자주 묻는 질문

Private Link는 지역 간 장애 조치를 자동으로 수행하나요?

아니요. 지역별 프라이빗 에지 경로는 해당 경로에 구성된 여러 백엔드 클러스터로 요청을 라우팅할 수 있지만, 다른 지역의 프라이빗 엔드포인트로 트래픽을 자동 전환하지는 않습니다. 장애가 발생하면 사용 중인 다른 지역 엔드포인트로 전환하도록 애플리케이션을 구성하세요.

상태 확인에는 어떤 경로를 사용해야 하나요?

지역 호스트 이름으로 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 인터페이스와 모델을 각각 테스트하세요.