Private Link

O OpenAI Private Link permite que cargas de trabalho do Azure acessem endpoints regionais da API da OpenAI por meio do Azure Private Link, em vez de se conectarem diretamente a endpoints públicos da API. Crie um endpoint privado para cada Private Link Service regional fornecido pela OpenAI, mapeie seu nome de host regional no DNS privado e envie solicitações de API com a autenticação habitual para esse nome de host.

Use o Private Link quando sua organização tiver requisitos rigorosos para manter o tráfego na rede privada do Azure. Se você não tiver requisitos de rede privada, os endpoints públicos da OpenAI são mais simples de configurar e operar. O Private Link não é compatível com controles de lista de IPs permitidos nem com TLS mútuo (mTLS); entre em contato com a OpenAI se precisar de ajuda para escolher os controles de rede corporativa adequados.

Entenda como o Private Link funciona

Alguns clientes vêm usando a solução legada do Private Link (v1), que conecta cada Private Endpoint a um cluster específico da API da OpenAI. A solução regional atual apresenta as seguintes diferenças:

Uma solicitação segue este caminho:

1. Seu aplicativo resolve um nome de host regional do Private Link por meio do seu DNS privado.
2. O nome de host é resolvido para um Azure Private Endpoint na sua rede virtual.
3. O Private Endpoint se conecta ao OpenAI Private Link Service regional.
4. O Private Link Service envia a solicitação ao gateway regional de borda privada da OpenAI.
5. O gateway roteia a solicitação para um cluster de backend da API da OpenAI habilitado para uso empresarial nessa via regional.

Dentro de uma via regional, o Private Link pode desviar o tráfego de um cluster de backend indisponível, e a OpenAI pode adicionar clusters de backend sem exigir que você reconfigure seus Private Endpoints. Ele não transfere automaticamente o tráfego do nome de host regional que você selecionou para um Private Endpoint de outra região. Não presuma que o Private Link herde o comportamento de roteamento dos endpoints públicos da OpenAI; configure como seu aplicativo fará a transferência para outra região em caso de falha.

Escolha os endpoints regionais

A OpenAI fornece o alias ou identificador de recurso exato do Private Link Service durante a integração inicial. Os nomes de host regionais atualmente em produção são:

O nome de host de Spain Central / UE pode rotear solicitações para clusters de backend em outras regiões da UE, como North Europe.

Configure o Private Link

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

Envie à OpenAI:

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

A OpenAI concede às assinaturas visibilidade e aprovação para os Private Link Services regionais apropriados e, em seguida, fornece os aliases ou identificadores de recursos desses serviços.

2. Crie endpoints privados

Crie um Private Endpoint para cada região selecionada. O Azure exige que o Private Endpoint esteja na mesma região da rede virtual do cliente. Defina --location como essa região, que pode ser diferente da região do OpenAI Private Link Service.

O comando a seguir usa um identificador de recurso do Private Link Service 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; as assinaturas na lista de acesso ainda podem receber aprovação automática.

Use um fluxo de trabalho semelhante no portal do Azure ou no Terraform se sua organização gerencia Private Endpoints por meio de infraestrutura como código.

3. Teste a conectividade antes de alterar o DNS

Depois que a OpenAI aprovar o Private Endpoint e o Azure provisioná-lo, obtenha seu endereço IP privado. 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

Uma resposta que indica funcionamento normal retorna HTTP 200 com uma mensagem como:

{ "message": "Service is up" }

Use o caminho exato de verificação de integridade: /v2/privatelink_healthcheck. Mantenha baixo o tráfego das verificações automatizadas de integridade: use no máximo 1 QPS por endpoint regional, a menos que a OpenAI aprove uma taxa diferente.

4. Configure o DNS privado

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

Verifique o DNS e a conectividade pelo mesmo caminho de rede usado pelo seu aplicativo:

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

5. Transfira o tráfego entre regiões em caso de falha

O Private Link fornece um ponto de entrada regional, mas seu tráfego continua direcionado ao nome de host regional que você selecionar. Configure seu cliente, malha de serviços, camada de DNS ou camada de balanceamento de carga para transferir o tráfego entre regiões em caso de falha.

Comportamento recomendado:

• Verifique cada região configurada com GET /v2/privatelink_healthcheck.
• Considere HTTP 200 como indicação de disponibilidade.
• Considere respostas 5xx, erros de conexão, erros de TLS ou tempos limite excedidos repetidamente como indicação de indisponibilidade.
• Transfira o tráfego somente após um pequeno número de erros consecutivos para evitar alternâncias frequentes entre regiões.
• Continue verificando a região indisponível em segundo plano e volte a direcionar o tráfego para ela de acordo com sua política operacional.

A verificação de integridade regional reflete a integridade dos clusters da API da OpenAI que atendem à rota de borda privada. Uma região retorna um erro se não houver clusters de suporte conhecidos, se a configuração de integridade estiver ausente ou se não houver clusters de suporte íntegros suficientes.

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

6. Atualize as URLs base da aplicação

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 homologação e, depois, migre o tráfego gradualmente.

Verifique sua configuração

Use esta lista de verificação durante a configuração inicial ou a migração para o Private Link:

• A OpenAI confirmou que os IDs das suas assinaturas do Azure podem acessar os serviços regionais do Private Link selecionados.
• Você criou endpoints privados, e a OpenAI os aprovou para cada região selecionada.
• Você registrou os endereços IP dos endpoints privados.
• curl --resolve funciona corretamente ao acessar /v2/privatelink_healthcheck.
• O DNS privado resolve os nomes de host regionais para os endereços IP dos endpoints privados a partir da rede da aplicação.
• A aplicação consegue chamar um endpoint representativo da API /v1 pelo nome de host regional.
• A automação das verificações de integridade tem um limite de taxa e registra a região, o código de status e o tipo de erro quando ocorrem erros.
• Você testou como a aplicação alterna para outra região em caso de falha, forçando uma região a ficar sem integridade em um ambiente controlado.
• Sua documentação operacional identifica quem pode alterar o DNS, a configuração dos endpoints privados e o roteamento regional da aplicação.

Verifique a compatibilidade dos endpoints

A matriz a seguir reflete a configuração atual de implantação dos serviços que atendem às rotas públicas de API listadas. Ela não substitui a validação prática pelo cliente: teste a disponibilidade dos modelos, as condições de acesso aos produtos, as dependências de serviços subsequentes, os limites de tamanho das requisições, o comportamento de streaming e o comportamento de WebSocket em cada região de destino. Yes significa que todos os clusters de suporte da rota regional têm a rota de API; No significa que o serviço de suporte está ausente dessa rota regional.

Perguntas frequentes

O Private Link alterna automaticamente entre regiões em caso de falha?

Não. A via regional de borda privada pode rotear solicitações entre os clusters de backend configurados, mas não transfere automaticamente seu tráfego para um endpoint privado de outra região. Configure seu aplicativo para alternar entre os endpoints regionais que você usa em caso de falha.

Qual verificação de integridade devo usar?

Use GET /v2/privatelink_healthcheck no nome de host regional. Os caminhos antigos de verificação de integridade da v1 sondam a via de integridade dos clusters de backend, portanto, não os use como sondas voltadas ao cliente.

Qual nome de host da API os aplicativos devem usar?

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

As 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. As cargas de trabalho na AWS ou no Google Cloud só podem se conectar por meio de uma rede gerenciada pelo cliente que dê acesso ao Azure, como um proxy no Azure ou uma arquitetura de conectividade privada entre nuvens, e depois do Azure à OpenAI 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 normais da API da OpenAI.

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

Não. O suporte depende de a API estar disponível em todos os clusters de backend da via regional selecionada. Use a matriz de compatibilidade como ponto de partida e depois teste cada interface de API e modelo de que você precisa em todas as regiões de destino.