Tutorial: Conectar o AKS ao Azure OpenAI

2025-09-09

Este tutorial mostra como conectar seus aplicativos do Serviço Kubernetes do Azure (AKS) ao Azure OpenAI usando o Service Connector com autenticação de identidade de carga de trabalho. Você estabelecerá conexões sem credenciais implantando um aplicativo Python de exemplo que se comunica com o serviço OpenAI do Azure.

Você concluirá as seguintes tarefas:

Criar um cluster AKS e um recurso OpenAI do Azure com o modelo GPT-4
Configurar o Service Connector para estabelecer a conexão com a identidade da carga de trabalho
Clone um aplicativo de exemplo
Criar e enviar imagens de contêiner para o Registro de Contêiner do Azure
Implante o aplicativo no AKS e verifique a conexão
Clean up resources (Limpar recursos)

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- Use o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.
- Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
  - Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
  - Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.
  - Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.
Docker e kubectl para gerenciar imagens de contêiner e recursos do Kubernetes.
Uma compreensão básica de contêineres e AKS. Comece a preparar uma candidatura para o AKS.
Permissões de acesso para criar recursos do Azure OpenAI e implantar modelos.

Criar recursos do Azure OpenAI e AKS

Você inicia este tutorial criando vários recursos do Azure.

Crie um grupo de recursos para este tutorial.

az group create \
    --name MyResourceGroup \
    --___location eastus

Crie um cluster AKS com o seguinte comando ou consultando o início rápido do AKS. Neste tutorial, criamos a conexão de serviço e a definição de pod e implantamos o aplicativo de exemplo nesse cluster.
```
az aks create \
    --resource-group MyResourceGroup \
    --name MyAKSCluster \
    --enable-managed-identity \
    --node-count 1 \
    --generate-ssh-keys
```

Conecte-se ao cluster usando o comando az aks get-credentials .

az aks get-credentials \
    --resource-group MyResourceGroup \
    --name MyAKSCluster

Crie um recurso do Azure OpenAI usando o comando az cognitiveservices account create . Opcionalmente, consulte este tutorial para obter mais instruções. O Azure OpenAI é o serviço de destino ao qual o cluster AKS se conectará.

az cognitiveservices account create \
    --resource-group MyResourceGroup \
    --name MyOpenAI \
    --___location eastus \
    --kind OpenAI \
    --sku s0 \
    --custom-___domain myopenai \
    --subscription <SubscriptionID>

Implante um modelo com o comando az cognitiveservices deployment create . O modelo é usado no aplicativo de exemplo para testar a conexão.

az cognitiveservices account deployment create \
    --resource-group MyResourceGroup \
    --name MyOpenAI \
    --deployment-name MyModel \
    --model-name gpt-4 \
    --model-version 0613 \
    --model-format OpenAI \
    --sku-name "Standard" \
    --capacity 1

Crie um Registro de Contêiner do Azure (ACR) para armazenar o aplicativo de exemplo em contêiner. Use o comando az acr create ou consulte este tutorial.
```
az acr create \
    --resource-group MyResourceGroup \
    --name myregistry \
    --sku Standard
```
Habilite o pull anônimo usando o comando az acr update para que o cluster AKS possa consumir as imagens no registro.
```
az acr update \
    --resource-group MyResourceGroup \
    --name myregistry \
    --anonymous-pull-enabled
```
Crie uma identidade gerenciada atribuída pelo usuário com o comando az identity create ou consultando este tutorial. Quando a conexão é criada, a identidade gerenciada atribuída pelo usuário é usada para habilitar a identidade da carga de trabalho para cargas de trabalho AKS.
```
az identity create \
    --resource-group MyResourceGroup \
    --name MyIdentity
```

Criar uma conexão de serviço do AKS para o Azure OpenAI

Crie uma conexão de serviço entre um cluster AKS e o Azure OpenAI no portal do Azure ou na CLI do Azure.

Portal
CLI do Azure

Consulte o início rápido da conexão de serviço AKS para obter instruções para criar uma nova conexão e preencha as configurações referentes aos exemplos na tabela a seguir. Deixe todas as outras configurações com seus valores padrão.

Guia Noções básicas:

Definição	Valor de exemplo	Description
Espaço de nomes do Kubernetes	default	O namespace Kubernetes.
Tipo de serviço	Serviço OpenAI	O tipo de serviço de destino.
Nome da ligação	openai_conn	Use o nome da conexão fornecido pelo Service Connector ou escolha seu próprio nome de conexão.
Subscrição	A minha subscrição	A assinatura do Azure que contém seu recurso do Azure OpenAI.
OpenAI	MyOpenAI	O recurso OpenAI do Azure de destino ao qual você deseja se conectar.
Tipo de cliente	Python	A linguagem de programação ou estrutura para a configuração de conexão.

Guia Autenticação:

Configuração de autenticação	Valor de exemplo	Description
Tipo de autenticação	Identidade da carga de trabalho	O método de autenticação para conectar o aplicativo ao Azure OpenAI. A identidade da carga de trabalho é recomendada para maior segurança. Os métodos alternativos incluem cadeia de conexão e entidade de serviço e exigem considerações de gerenciamento de credenciais.
Subscrição	A minha subscrição	A assinatura que contém a identidade gerenciada atribuída pelo usuário.
Identidade gerenciada atribuída ao usuário	A minha identidade	A identidade gerenciada atribuída pelo usuário que permite a autenticação de identidade de carga de trabalho para o cluster AKS.

Depois que a conexão for criada, você poderá exibir seus detalhes no painel Conector de Serviço .

Crie uma conexão de serviço do AKS para o recurso OpenAI do Azure executando o comando az aks connection create cognitiveservices na CLI do Azure.

az aks connection create cognitiveservices \
   --workload-identity <user-identity-resource-id>

Ao usar o comando acima, o Service Connector solicita que você especifique o grupo de recursos AKS, o nome do cluster AKS, o grupo de recursos de serviço de destino, o nome da conta de serviço cognitivo e o ID do recurso de identidade atribuído pelo usuário passo a passo.

Como alternativa, você pode fornecer o comando completo diretamente:

az aks connection create cognitiveservices \
   --workload-identity <user-identity-resource-id> \
   --resource-group <aks-cluster-resource-group> \
   --name <aks-cluster-name> \
   --target-resource-group <target-cognitive-services-resource-group> \
   --account <target-cognitive-services-account>

Observação

Este tutorial usa a identidade da carga de trabalho para maior segurança. Para cenários de desenvolvimento, você também pode usar a autenticação de cadeia de conexão omitindo o --workload-identity parâmetro e usando --secret .

Aplicativo de exemplo Clone Python

Clone o repositório de exemplo:

git clone https://github.com/Azure-Samples/serviceconnector-aks-samples.git

Vá para a pasta de exemplo do repositório para o Azure OpenAI:

cd serviceconnector-aks-samples/azure-openai-workload-identity

Substitua <MyModel> o espaço reservado app.py no arquivo pelo nome do modelo que implantamos.

Criar e enviar imagens de contêiner para o Registro de Contêiner do Azure

Crie e envie as imagens para seu registro de contêiner usando o comando Azure CLI az acr build .
```
az acr build --registry myregistry --image sc-demo-openai-identity:latest ./
```
Visualize as imagens em seu registro de contêiner usando o comando az acr repository list .
```
az acr repository list --name myregistry --output table
```

Implantar e testar a conexão AKS para Azure OpenAI

Substitua os espaços reservados no pod.yaml arquivo na azure-openai-workload-identity pasta.
- Substitua <YourContainerImage> pelo nome da imagem criada anteriormente. Por exemplo, <myregistry>.azurecr.io/<sc-demo-openai-identity>:<latest>.
- Substitua <ServiceAccountCreatedByServiceConnector> pelo nome da conta de serviço. Ele pode ser encontrado no portal do Azure, no painel Service Connector .
- Substitua <SecretCreatedByServiceConnector> pelo nome secreto. Ele pode ser encontrado no portal do Azure, no painel Service Connector .
Implante o pod no cluster com o kubectl apply comando, que cria um pod nomeado sc-demo-openai-identity no namespace padrão do cluster AKS. Instale kubectl localmente usando o comando az aks install-cli se não estiver instalado.
```
kubectl apply -f pod.yaml
```
Verifique se a implantação foi bem-sucedida visualizando o pod com kubectl.
```
kubectl get pod/sc-demo-openai-identity
```
Verifique se a conexão é estabelecida visualizando os logs com kubectl.
```
kubectl logs pod/sc-demo-openai-identity
```

Clean up resources (Limpar recursos)

Se você não precisar mais dos recursos criados neste tutorial, limpe-os excluindo o grupo de recursos.

az group delete \
    --resource-group MyResourceGroup

Partilhar via