Criar um projeto para a Microsoft Foundry

• Não são necessários outros pré-requisitos ao usar o portal.

• Configura o teu ambiente de desenvolvimento.

• Antes de executar código, execute az login ou az login --use-device-code no seu ambiente.

• Instalar pacotes: pip install azure-identity azure-mgmt-cognitiveservices~=13.7.0. Se estiver numa célula de notebook, use, em vez disso, o %pip install.

• Usa pip show azure-mgmt-cognitiveservices para verificar se a tua versão é 13.7 ou superior.

• Validação rápida: Antes de criar um projeto, verifique o seu SDK e autenticação testando o cliente:

  from azure.identity import DefaultAzureCredential
  from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
  
  # Test authentication by instantiating the client
  credential = DefaultAzureCredential()
  subscription_id = "<your-subscription-id>"  # Replace with your subscription ID
  client = CognitiveServicesManagementClient(credential, subscription_id)
  print("✓ Authentication successful! Ready to create a project.")
  

• Comece o seu script com o seguinte código para criar a ligação e as client variáveis utilizadas ao longo deste artigo. Este exemplo cria o projeto no Leste dos EUA:

  from azure.identity import DefaultAzureCredential
  from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
  
  subscription_id = 'your-subscription-id'
  resource_group_name = 'your-resource-group-name'
  foundry_resource_name = 'your-foundry-resource-name'
  foundry_project_name = 'your-foundry-project-name'
  location = 'eastus'
  
  client = CognitiveServicesManagementClient(
      credential=DefaultAzureCredential(), 
      subscription_id=subscription_id,
      api_version="2025-04-01-preview"
  )
  

• (Opcional) Se tiver várias contas, adicione o ID do inquilino da Microsoft Entra ID que quer usar em DefaultAzureCredential:

  DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
  

• Instala o CLI do Azure.
• Defina o valor padrão para subscription.

# Set your default subscription
az account set --subscription "{subscription-name}"

Estes passos fornecem uma forma de criar um novo recurso do Azure com as definições básicas predefinidas.

Para criar um projeto Foundry, siga estes passos:

1. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se à Foundry (nova).

   

2. O projeto em que estás a trabalhar aparece no canto superior esquerdo.

3. Para criar um novo projeto, selecione o nome do projeto e depois selecione Criar novo projeto.

4. Dê um nome ao seu projeto e selecione Criar projeto. Ou consulte a próxima secção para opções avançadas.

Opções avançadas

1. Você cria um projeto Foundry num recurso Foundry. O portal cria automaticamente este recurso quando cria o projeto. Selecione um grupo de Recursos existente para usar, ou deixe o padrão para criar um novo grupo de recursos.

   Dica

   Especialmente para começar, crie um novo grupo de recursos para o seu projeto. O grupo de recursos facilita a gestão conjunta do projeto e de todos os seus recursos.

2. Selecione uma localização ou use o padrão. O local é a região onde os recursos do projeto são alojados.

3. Selecione Criar. Vê-se o progresso da criação de recursos. O projeto é criado quando o processo está concluído.

Para criar um projeto Foundry:

• Adicione o seguinte código para criar um projeto Foundry usando as variáveis e a conexão client da secção de pré-requisitos.

  # Create resource
  resource = client.accounts.begin_create(
      resource_group_name=resource_group_name,
      account_name=foundry_resource_name,
      account={
          "location": location,
          "kind": "AIServices",
          "sku": {"name": "S0",},
          "identity": {"type": "SystemAssigned"},
          "properties": {
              "allowProjectManagement": True,
              "customSubDomainName": foundry_resource_name
          }
      }
  )
  
  # Wait for the resource creation to complete
  resource_result = resource.result()
  
  # Create default project
  project = client.projects.begin_create(
      resource_group_name=resource_group_name,
      account_name=foundry_resource_name,
      project_name=foundry_project_name,
      project={
          "location": location,
          "identity": {
              "type": "SystemAssigned"
          },
          "properties": {}
      }
  )
  

  Referências: CognitiveServicesManagementClient.

1. Cria um grupo de recursos ou usa um já existente. Por exemplo, crie my-foundry-rg em eastus:

   az group create --name my-foundry-rg --location eastus
   

   Verifique se o grupo de recursos existe:

   az group show --name my-foundry-rg --query properties.provisioningState --output tsv
   

   A saída mostra Succeeded.

2. Crie o recurso Foundry com a gestão de projetos ativada. Por exemplo, crie my-foundry-resource no my-foundry-rg grupo de recursos:

   az cognitiveservices account create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --kind AIServices \
       --sku S0 \
       --location eastus \
       --custom-domain my-foundry-resource \
       --assign-identity \
       --allow-project-management true
   

   Use estes valores:

   Parameter	Purpose
   --assign-identity	Cria a identidade gerida que a gestão de projetos exige. Sem ela, a criação do projeto falha devido a um erro que indica que uma identidade gerida deve ser ativada no recurso.
   --allow-project-management	Permite o gerenciamento de projetos. Não podes mudar esta definição depois de criares o recurso.
   --custom-domain	Deve ser globalmente único. Se my-foundry-resource for tomado, o comando falha com CustomDomainInUse. Escolha um nome diferente e execute o comando novamente.

3. Cria um projecto. Por exemplo, crie my-foundry-project em :my-foundry-resource

   az cognitiveservices account project create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --location eastus
   

4. Verifique se o recurso está provisionado:

   az cognitiveservices account show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --query properties.provisioningState --output tsv
   

   O resultado deve mostrar Succeeded. Se o resultado apresentar um estado diferente, verifique as suas permissões, a disponibilidade na sua região e as quotas de recursos. Para mais ajuda, consulte Criar um recurso multi-serviço.

5. Verifique se o projeto foi criado:

   az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query properties.provisioningState --output tsv
   

   O resultado deve mostrar Succeeded. Se o comando falhar com uma mensagem a indicar que uma identidade gerida deve ser ativada, confirme que criou o recurso com --assign-identity.

Referência: az cognitiveservices account project

Na página inicial do projeto, vê o endpoint do projeto e a chave API do projeto. Não precisas da chave API se usares autenticação Microsoft Entra ID.

# Get project
project = client.projects.get(
    resource_group_name=resource_group_name,
    account_name=foundry_resource_name,
    project_name=foundry_project_name
)
print(project)

Referências: CognitiveServicesManagementClient.

Para visualizar as definições do projeto, use o az cognitiveservices account project show comando. Por exemplo:

az cognitiveservices account project show \
--name my-foundry-resource \
--resource-group my-foundry-rg \
--project-name my-foundry-project

1. No portal da Foundry, selecione Gerir no canto superior direito da navegação.
2. Selecione Project details no painel esquerdo.
3. Selecione o separador Utilizadores.
4. Selecionar Adicionar utilizador no canto superior direito.
5. Introduza o endereço de email do membro da equipa.
6. Selecionar Adicionar.

Repita estes passos para cada membro da equipa ou grupo de segurança.

Use o portal CLI do Azure ou Foundry para gerir atribuições de funções. O SDK Python não suporta operações de atribuição de papéis.

1. Obtenha o ID do recurso do projeto:

   PROJECT_ID=$(az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query id -o tsv)
   

2. Atribua a função Foundry User a um membro da equipa:

   Importante

   As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

   az role assignment create \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --assignee "user@contoso.com" \
       --assignee-principal-type User \
       --scope $PROJECT_ID
   

Para adicionar um grupo de segurança em vez de um utilizador individual:

az role assignment create \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --assignee-object-id "<security-group-object-id>" \
    --assignee-principal-type Group \
    --scope $PROJECT_ID

1. Verifique a atribuição de funções:

   az role assignment list \
       --scope $PROJECT_ID \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --output table
   

Referência: az role assignment

1. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se à Foundry (nova).
2. Na navegação no canto superior direito, selecione Gerir.
3. No painel esquerdo, selecione Project details.
4. No canto superior direito, selecione o ícone do caixote do lixo para eliminar o projeto.

Este código utiliza as variáveis e a ligação client dos pré-requisitos. Para eliminar um único projeto:

client.projects.begin_delete(
    resource_group_name, foundry_resource_name, foundry_project_name
)

Referências: CognitiveServicesManagementClient.

Eliminar um recurso da Foundry e todos os seus projetos:

# Delete projects
projects = client.projects.list(resource_group_name, foundry_resource_name)

for project in projects: 
    print("Deleting project:", project.name)
    client.projects.begin_delete(resource_group_name, foundry_resource_name,
        project_name=project.name.split('/')[-1]
    ).wait()

# Delete resource
print("Deleting resource:", foundry_resource_name)
client.accounts.begin_delete(resource_group_name, foundry_resource_name).wait()

Referências: CognitiveServicesManagementClient.

Execute o seguinte comando:

az cognitiveservices account project delete \
--name my-foundry-resource \
--resource-group my-foundry-rg \
--project-name my-foundry-project

Referências ao comando: az cognitiveservices account project delete.