Private Link

Com o Private Link da OpenAI, as cargas de trabalho do Azure podem acessar os endpoints regionais da API da OpenAI pelo Azure Private Link, sem se conectar diretamente aos endpoints públicos da API. Crie um endpoint privado para cada serviço regional do Private Link fornecido pela OpenAI, mapeie o nome de host regional no DNS privado e envie as solicitações à API para esse nome de host com a autenticação habitual.

Use o Private Link se sua organização tiver requisitos rigorosos para manter o tráfego na rede privada do Azure. Se não houver exigência de rede privada, os endpoints públicos da OpenAI são mais simples de configurar e operar. O Private Link é incompatível com controles baseados em listas de IPs permitidos e com TLS mútuo (mTLS). Entre em contato com a OpenAI se precisar de ajuda para escolher os controles de rede adequados à sua empresa.

Entenda como o Private Link funciona

Alguns clientes ainda usam a solução legada do Private Link (v1), que conecta cada endpoint privado a um cluster específico da API da OpenAI. Veja como a solução regional atual se diferencia da anterior.

Cada solicitação percorre o seguinte caminho.

1. Seu aplicativo consulta o DNS privado para resolver um nome de host regional do Private Link.
2. O DNS retorna o endereço de um endpoint privado do Azure na sua rede virtual.
3. O endpoint privado se conecta ao serviço regional do Private Link da OpenAI.
4. O serviço do Private Link envia a solicitação ao gateway regional na borda da rede privada da OpenAI.
5. O gateway encaminha a solicitação a um cluster de backend da API da OpenAI habilitado para atender clientes empresariais naquela rota regional.

Dentro de uma rota regional, o Private Link pode desviar o tráfego de um cluster de backend indisponível, e a OpenAI pode adicionar clusters sem que você precise reconfigurar seus endpoints privados. O Private Link não transfere automaticamente o tráfego do nome de host regional selecionado para um endpoint privado de outra região. Não presuma que o Private Link segue as mesmas regras de roteamento dos endpoints públicos da OpenAI. Configure como seu aplicativo alternará entre regiões em caso de falha.

Escolha os endpoints regionais

Durante a configuração inicial, a OpenAI fornece o alias ou o identificador de recurso exato do serviço do Private Link. Estes são os nomes de host regionais atualmente em produção.

O tráfego destinado ao nome de host da região Espanha Central / UE pode ser encaminhado a clusters de backend em outras regiões da UE, como Norte da Europa.

Configure o Private Link

1. Forneça as informações para a configuração inicial

Envie à OpenAI os seguintes dados.

• Os IDs das assinaturas do Azure que precisam de acesso aos serviços do Private Link da OpenAI.
• O ID da organização na OpenAI.
• As regiões de que você precisa.
• Os contatos da equipe de operações que devem receber avisos de manutenção e de transferência de tráfego entre regiões.

A OpenAI permite que essas assinaturas vejam os serviços regionais do Private Link correspondentes, aprova o acesso e fornece os aliases ou identificadores de recurso dos serviços.

2. Crie os endpoints privados

Crie um endpoint privado para cada região selecionada. O Azure exige que o endpoint privado fique na mesma região da rede virtual do cliente. Defina --location como a região dessa rede, que pode ser diferente da região do serviço do Private Link da OpenAI.

O comando a seguir usa um identificador de recurso do serviço do Private Link fornecido pela OpenAI.

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

Se a OpenAI fornecer um alias, use-o e adicione --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

O Azure exige --manual-request true para conexões por alias. Mesmo assim, as assinaturas que constam na lista de acesso podem receber aprovação automática.

Se sua organização usa infraestrutura como código para gerenciar endpoints privados, siga um processo semelhante no portal do Azure ou no Terraform.

3. Teste a conectividade antes de alterar o DNS

Depois que a OpenAI aprovar o endpoint privado e o Azure concluir o provisionamento, anote o endereço IP privado do endpoint. Use curl --resolve para testar o nome de host regional sem alterar o DNS globalmente.

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

Quando o serviço está íntegro, a resposta contém o código HTTP 200 e uma mensagem como esta.

{ "message": "Service is up" }

Use exatamente o caminho /v2/privatelink_healthcheck para verificar a integridade. Limite o tráfego das verificações automatizadas a uma solicitação por segundo (1 QPS) por endpoint regional, a menos que a OpenAI aprove outra taxa.

4. Configure o DNS privado

Crie registros DNS privados para que, dentro da sua rede, cada nome de host regional do Private Link da OpenAI seja resolvido para o endereço IP do endpoint privado correspondente.

Verifique o DNS e a conectividade pelo mesmo caminho de rede que seu aplicativo usa.

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

5. Configure o failover entre regiões

O Private Link oferece um ponto de entrada regional, mas o destino do tráfego continua sendo o nome de host regional que você selecionar. Configure o failover entre regiões no cliente, na malha de serviços, na camada de DNS ou na camada de balanceamento de carga.

Siga estas recomendações.

• Verifique cada região configurada com GET /v2/privatelink_healthcheck.
• Considere a região disponível quando receber o código HTTP 200.
• Considere a região indisponível em caso de respostas 5xx, erros de conexão, erros de TLS ou falhas repetidas por tempo limite excedido.
• Para evitar alternâncias frequentes entre regiões, aguarde alguns erros consecutivos antes de acionar o failover.
• Continue verificando a região indisponível em segundo plano e retorne o tráfego a ela conforme sua política operacional.

A verificação de integridade regional reflete o estado dos clusters da API da OpenAI que atendem à rota na borda da rede privada. A região retorna um erro se não houver clusters de backend conhecidos, se faltar a configuração de verificação de integridade ou se o número de clusters de backend íntegros for insuficiente.

Se a decisão de roteamento depender de uma API ou de um modelo específico, complemente a verificação de integridade com solicitações sintéticas de baixa frequência a essa API e a esse modelo pelo mesmo caminho de rede.

6. Atualize as URLs base do aplicativo

Use o nome de host regional do Private Link como URL base da API da OpenAI.

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"
)

O SDK lê OPENAI_API_KEY do seu ambiente.

Você também pode chamar o endpoint regional diretamente.

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

Comece em um ambiente de desenvolvimento ou de homologação. Depois, direcione o tráfego de produção aos poucos para o endpoint.

Verifique sua configuração

Use esta lista durante a configuração inicial ou a migração para o Private Link.

• A OpenAI confirmou que as assinaturas do Azure identificadas pelos IDs informados têm acesso aos serviços regionais do Private Link selecionados.
• Você criou os endpoints privados de cada região selecionada, e a OpenAI os aprovou.
• Você anotou os endereços IP dos endpoints privados.
• O teste com curl --resolve em /v2/privatelink_healthcheck é bem-sucedido.
• Na rede do aplicativo, o DNS privado resolve os nomes de host regionais para os endereços IP dos endpoints privados.
• O aplicativo consegue chamar um endpoint representativo da API /v1 usando o nome de host regional.
• A automação das verificações de integridade limita a taxa de solicitações e, em caso de erro, registra a região, o código de status e o tipo de erro.
• Você simulou a indisponibilidade de uma região em um ambiente controlado para testar o failover do aplicativo.
• A documentação operacional indica quem pode alterar o DNS, a configuração dos endpoints privados e o roteamento regional do aplicativo.

Verifique a compatibilidade dos endpoints

A matriz a seguir mostra a configuração de implantação atual dos serviços que atendem às rotas públicas da API listadas abaixo. Valide também o funcionamento no seu ambiente. Em cada região de destino, teste a disponibilidade dos modelos, as condições de acesso aos recursos do produto, as dependências de serviços subsequentes, os limites de tamanho das solicitações e o comportamento do streaming e das conexões WebSocket. Yes (Sim) indica que todos os clusters de backend da rota regional oferecem a rota da API. No (Não) indica que o serviço de backend está ausente nessa rota regional.

Perguntas frequentes

O Private Link faz failover automático entre regiões?

Não. A rota regional na borda da rede privada pode distribuir o tráfego entre os clusters de backend configurados, mas não o transfere automaticamente para um endpoint privado de outra região. Configure o aplicativo para fazer failover entre os endpoints regionais que você usa.

Qual verificação de integridade devo usar?

Use GET /v2/privatelink_healthcheck no nome de host regional. Os caminhos de verificação da v1 consultam a rota interna de integridade dos clusters de backend. Não os use para verificações do lado do cliente.

Qual nome de host da API os aplicativos devem usar?

Use o nome de host regional com o caminho habitual da API, /v1, como em https://southcentralus.privatelink.api.openai.com/v1.

Cargas de trabalho da AWS ou do Google Cloud podem se conectar pelo Private Link?

Não diretamente. A conectividade do Private Link é específica do Azure. Cargas de trabalho da AWS ou do Google Cloud só podem se conectar por uma rede gerenciada pelo cliente que dê acesso ao Azure, por exemplo, por meio de um proxy no Azure ou de uma conexão privada entre nuvens. A partir do Azure, a conexão com a OpenAI passa pelo Azure Private Link.

O Private Link altera a autenticação?

Não. O Private Link altera apenas o caminho de rede. As solicitações continuam exigindo a autenticação e a autorização habituais da API da OpenAI.

O Private Link oferece suporte a todas as APIs da OpenAI?

Não. O suporte depende da disponibilidade da API em todos os clusters de backend que atendem à rota regional selecionada. Use a matriz de compatibilidade como ponto de partida e teste cada interface de API e cada modelo de que você precisa em todas as regiões de destino.