Criando um Aplicativo

Os aplicativos definem definições de runtime gerenciadas para implantações hospedadas, incluindo dimensionamento, armazenamento gerenciado, rede e autenticação. Esta tarefa explica como criar um aplicativo usando a Console do Oracle Cloud no serviço OCI Generative AI.

Na página da lista Aplicativos, selecione Criar aplicativo. Se precisar de ajuda para localizar a página da lista, consulte Listando Aplicativos.

Informações básicas

Informe um nome para a aplicação.
Inicie o nome com uma letra ou sublinhado, seguido de letras, números, hifens ou sublinhados. O comprimento pode ser de 1 a 255 caracteres.
(Opcional) Digite uma descrição para o aplicativo.
Selecione um compartimento no qual criar o aplicativo. O compartimento padrão é o mesmo da página de lista, mas você pode selecionar qualquer compartimento em que tenha permissão para trabalhar.

Dimensionamento

Importante

Se você planeja ativar o armazenamento de arquivos persistentes na etapa 3, defina Réplicas mínimas e Réplicas máximas como 1. O armazenamento persistente de arquivos suporta uma réplica nesta versão.

Para Dimensionamento Automático, defina como as implantações hospedadas são dimensionadas para lidar com a carga.
- Réplicas mínimas
  O número mínimo de réplicas que devem estar sempre em execução. Este valor deve ser menor ou igual ao número máximo de réplicas. O padrão é 1.
- Máximo de réplicas
  O número máximo de réplicas que podem ser executadas. Novas réplicas são adicionadas à medida que a carga aumenta, até esse limite. O padrão é 3 e o máximo é 30. Para desativar o dimensionamento automático, defina esse valor como Mínimo de réplicas.
Selecione uma métrica de dimensionamento.
O serviço adiciona réplicas quando a métrica selecionada excede o alvo configurado, até o valor máximo de réplicas.
- Utilização da CPU (%)
  Adiciona réplicas quando a utilização da CPU excede esse percentual, até o máximo de réplicas definido. Faixa: 50% a 95%.
- Utilização da memória (%)
  Adiciona réplicas quando a utilização da memória excede esse percentual, até o máximo de réplicas definido. Faixa: 50% a 95%.
- Solicitações simultâneas
  Adiciona réplicas quando as solicitações simultâneas excedem esse valor, até o máximo de réplicas que você definir. Faixa: 1 a 500.
- Solicitações por Segundo (RPS)
  Adiciona réplicas quando as solicitações por segundo excedem o destino configurado, até o máximo de réplicas definido.

Armazenamento

Na etapa 3, ative o armazenamento gerenciado pelo serviço que as implantações no aplicativo precisam: Armazenamento de Arquivos, OCI PostgreSQL, OCI Cache ou Oracle Autonomous AI Database. Você pode anexar um recurso de armazenamento de cada tipo.

O File Storage está disponível em um caminho de montagem de contêiner. Os detalhes da conexão do banco de dados e do cache são fornecidos por meio de variáveis de ambiente. O serviço gerencia o acesso ao armazenamento do aplicativo.

Em Armazenamento, ative as opções de que seu aplicativo precisa.

Armazenamento persistente de arquivos
Reter arquivos entre reinicializações e reimplantações de contêiner. Cada aplicativo pode ter um anexo de armazenamento de arquivos com uma cota fixa de 50 GB (50.000.000.000 de bytes).
Para esta opção:
1. Ative o Armazenamento de arquivos persistente.
2. Certifique-se de que Réplicas mínimas e Réplicas máximas nas definições de dimensionamento sejam 1. O armazenamento persistente de arquivos suporta uma réplica nesta versão.
3. Em Armazenamento, selecione uma das seguintes opções:
  - Criar um novo armazenamento: Digite um Nome de armazenamento. O serviço cria uma configuração de armazenamento no compartimento do aplicativo.
  - Selecionar um armazenamento existente no compartimento atual: Em Nome do armazenamento, selecione um recurso de armazenamento de arquivos ativo. Você pode usar Pesquisar e Filtrar para localizar um recurso. Se não houver armazenamento de arquivos ativo disponível, selecione Criar um novo armazenamento.
4. Para Caminho de montagem, mantenha /mnt/persistent/data ou digite outro caminho de contêiner absoluto válido. Não é possível alterar este caminho após a criação do aplicativo.
Aplicativos que usam o mesmo recurso de armazenamento recebem sistemas de arquivos separados. A seleção do armazenamento existente reutiliza sua configuração. Ele não compartilha arquivos de outro aplicativo.
Configure seu aplicativo para ler e gravar arquivos persistentes no caminho de montagem. O File Storage não usa uma variável de ambiente para informações de conexão. Para obter os requisitos de caminho, a configuração da API e o status do anexo, consulte Armazenamento de Arquivos Persistente para Aplicativos Hospedados.
OCI PostgreSQL
Ative o OCI PostgreSQL para fornecer um banco de dados gerenciado para implantações neste aplicativo.
Para esta opção:
- Informe o nome da variável do ambiente que recebe o URI da conexão do OCI PostgreSQL. O serviço adiciona a string de conexão à variável de ambiente especificada.
- Armazenamento: Selecione se deseja criar ou usar o armazenamento existente. Se você selecionar o armazenamento existente, o aplicativo compartilhará o recurso de armazenamento do OCI PostgreSQL com outros aplicativos na tenancy. Cada aplicativo recebe um banco de dados dedicado, e esse aplicativo tem permissão para acessar somente seu banco de dados dedicado.
Cache do OCI
Ative o OCI Cache para fornecer um cache gerenciado para implantações neste aplicativo. Para esta opção:
- Informe o nome da variável de ambiente que recebe o URI da conexão do Cache do OCI.
- Armazenamento: Selecione se deseja criar ou usar o armazenamento existente.
Oracle Autonomous Database
Ative o Oracle Autonomous AI Database para fornecer um banco de dados gerenciado para implantações neste aplicativo. Para esta opção:
- Informe o nome da variável de ambiente que recebe o URI da conexão do Autonomous AI Database.
Além da string de conexão, o serviço monta as credenciais do usuário do banco de dados nos seguintes arquivos locais no contêiner:
```
/mnt/secrets/adb/username
/mnt/secrets/adb/password
```

Ambiente

(Opcional) Informe uma ou mais Variáveis de Ambiente para a implantação como pares de chave/valor. Para cada variável, informe o nome da variável de ambiente e seu valor. Adicione quantas variáveis o aplicativo precisar.
(Opcional) Para Variáveis de ambiente do serviço Vault, informe o seguinte:
- Nome da variável
- OCID do Vault
- Chave do vault
- O serviço adiciona as informações do vault ao contêiner como um arquivo JSON. Exemplo de código JSON:
```
{
    "vaultId":<vault-ocid>,
    "key":<the secret in the vault>
}
```

Rede (Opcional)

Selecione como as implantações neste aplicativo roteiam o tráfego de saída e como os clientes acessam o ponto final de implantação.

Para Rede, selecione uma das seguintes opções.
- Padrão (gerenciado pelo serviço)
  Permite acesso de saída aos serviços do OCI e à internet pública por meio de uma rede gerenciada por serviço.
- Personalizado (gerenciado pelo cliente)
  Roteia o tráfego de saída por meio de uma VCN e sub-rede na tenancy usando uma conexão de ponto final privado. Essa opção é recomendada para implantações privadas e integradas à empresa. Para essa opção, selecione o seguinte:
  - Compartimento da VCN
  - VCN
  - Compartimento de sub-rede
  - Sub-rede
  Observação
  
  Se você selecionar uma rede personalizada, todo o tráfego de saída será roteado para a sub-rede da VCN. Se o aplicativo também precisar de acesso à Internet, considere o uso de uma sub-rede pública e a configuração da tabela de roteamento. Consulte Gateway de internet.
Selecione se a implantação ativa deste aplicativo é acessada por meio de um ponto final público ou privado.
- Público
  Acessível de fora da VCN.
- Privado
  Acessível somente de dentro da VCN.
  Importante
  
  Você deve usar um ponto final privado do serviço Generative AI. Se você não tiver um, crie um ponto final privado do serviço Generative AI.
  Informe o seguinte:
  - Compartimento de ponto final privado
  - Ponto final privado
Após a criação do aplicativo, você poderá acessá-lo por meio desse ponto final privado usando seu FQDN ou endereço IP. Exemplo de FQDN:
```
https://<pe-name>.pe.inference.generativeai.<region>
.oci.oraclecloud.com/20251112/hostedApplications/{your_application_ocid}
```

Autenticação

Na etapa 6, selecione uma das seguintes opções de autenticação:

Token do portador do domínio de identidades: Usa um token de acesso OAuth emitido por um domínio de identidades do OCI IAM. O token é enviado ao serviço de destino como um token de portador e o serviço valida o token antes de aceitar a solicitação. Como pré-requisito, execute as tarefas em Configurando a Autenticação de Token do Portador do Domínio de Identidades.
Sessão do browser do domínio de identidades: Usa o fluxo do Código de Autorização do OAuth 2.1 com Chave de Prova para Intercâmbio de Código (PKCE). Os usuários do browser são redirecionados para um domínio de identidades do OCI para acesso. O serviço de aplicativo hospedado obtém um token de acesso em seu nome e estabelece uma sessão do navegador que usa um cookie de sessão.
IAM do OCI: Usa autenticação de assinatura de solicitação do OCI IAM. Cada solicitação é assinada criptograficamente de acordo com os requisitos de assinatura de solicitação da API da OCI.
Sem autenticação: Permite solicitações sem autenticação gerenciada pela plataforma. Use esta opção para conteúdo público ou quando seu aplicativo gerenciar a autenticação.

Observação

Ao usar a API, use CreateHostedApplication para autenticação de domínio de identidades ou nenhuma autenticação. Em inboundAuthConfig, defina inboundAuthConfigType com um dos seguintes valores:

IDCS_AUTH_CONFIG: Autenticação do token do portador do domínio de identidades.
IDCS_SESSION_AUTH_CONFIG: Autenticação da sessão do browser do domínio de identidades usando o fluxo do Código de Autorização OAuth 2.1 com PKCE.
NO_AUTH_CONFIG: Desativa a autenticação do chamador gerenciada pela plataforma. Omita idcsConfig.

Para ambos os tipos de autenticação do domínio de identidades, inclua idcsConfig com os valores domainUrl e scope necessários. O esquema da API marca audience como opcional. Ele também define clientId e clientSecretVaultId como campos opcionais que se aplicam apenas a IDCS_SESSION_AUTH_CONFIG. O valor clientSecretVaultId é o OCID de um segredo do OCI Vault que contém o segredo do cliente OAuth. Para obter detalhes, consulte InboundAuthConfig e IdcsAuthConfig.

Para configurar nenhuma autenticação, forneça o objeto a seguir. Nenhuma inscrição separada na tenancy é necessária.

"inboundAuthConfig": {
  "inboundAuthConfigType": "NO_AUTH_CONFIG"
}

A omissão de inboundAuthConfig de uma atualização deixa inalterada a configuração de autenticação atual do aplicativo. Para desativar explicitamente a autenticação do chamador gerenciada pela plataforma, defina inboundAuthConfigType como NO_AUTH_CONFIG e omita idcsConfig.

Para criar um aplicativo que use a autenticação do OCI IAM, use CreateHostedApplicationIam com CreateHostedApplicationIamDetails. A API do OCI IAM não requer uma configuração OAuth ou IDCS.

Siga as etapas para o tipo de autenticação selecionado.

Token do portador do domínio de identidades

Para Tipo de autenticação, selecione Token do portador do domínio de identidades.
Selecione uma destas opções:
- Escolha um domínio de identidades existente
  Use o mesmo domínio de identidades no qual você criou o aplicativo integrado confidencial na Etapa 2. Criar um Aplicativo no Domínio de Identidades. Selecione os valores dos seguintes campos:
  - Compartimento do domínio de identidades
  - Domínio de identidades
- Colar um URL do domínio de identidades
  Exemplo: https://idcs-xxx.identity.oraclecloud.com:443
Para Escopo, informe o escopo configurado para o aplicativo no domínio de identidades.

O escopo especifica as permissões que o token de acesso concede. Use o escopo configurado na Etapa 3. Defina OAuth Definições.
(Opcional) Para Público, informe o público configurado para o aplicativo no domínio de identidades.

O público-alvo identifica o serviço ou a API para o qual o token de acesso se destina. Para encontrar esse valor, abra o aplicativo integrado no domínio de identidades, selecione configuração OAuth e copie Público-alvo principal.
Selecione Próximo.

Sessão do browser do domínio de identidades

Obtenha o URL, o escopo, o público e o ID do cliente do domínio de identidades para o aplicativo OAuth configurado para o fluxo Código de Autorização com PKCE. Armazene o segredo do cliente OAuth no OCI Vault e registre o OCID do segredo para o campo ID do vault secreto do cliente.

Para Tipo de autenticação, selecione Sessão do browser do domínio de identidades.
Em Tipo, selecione uma das seguintes opções:
- Escolher um domínio de identidades existente: Selecione o Compartimento do domínio de identidades e o Domínio de identidades para o aplicativo OAuth.
- Colar um URL do domínio de identidades: Digite o URL do domínio de identidades. Por exemplo, https://idcs-xxx.identity.oraclecloud.com:443.
Informe os seguintes valores exigidos pela Console para o aplicativo OAuth:
- Escopo: O escopo configurado no domínio de identidades.
- Público: O público configurado no domínio de identidades.
- ID do cliente OAuth: O ID do cliente do aplicativo OAuth usado para acesso ao browser.
- ID do vault de segredo do cliente: O OCID do segredo do Vault do OCI que contém o segredo do cliente do aplicativo OAuth.
(Opcional) Em Padrões de caminho de acesso público, selecione Adicionar padrão de caminho público e informe um caminho que possa ser acessado sem autenticação. Repita esse procedimento para cada caminho adicional.

Os caminhos devem começar com uma barra. Os exemplos incluem /health e /assets/*. As solicitações para correspondência de caminhos ignoram a autenticação. Adicione somente os caminhos destinados ao acesso sem acessar.
Selecione Próximo.

IAM do OCI

Para Tipo de autenticação, selecione IAM do OCI.

Esta opção usa autenticação de assinatura de solicitação do OCI IAM e não requer definições de domínio de identidades.
Selecione Próximo.

Nenhuma autenticação

Com essa opção, qualquer pessoa que possa acessar o endpoint pode enviar solicitações sem autenticação gerenciada pela plataforma. Se o acesso precisar de restrição, seu aplicativo deverá impor autenticação e autorização. Consulte Usando Nenhuma Autenticação.

Para Tipo de autenticação, selecione Nenhuma autenticação.
Nenhum campo de autenticação adicional é necessário.
Selecione Próximo.

Ativar Logs do Aplicativo

Ative o registro em log de recursos para rastrear a atividade do aplicativo, solucionar problemas e coletar insights operacionais para implantações hospedadas.

(Opcional) Ative Ativar log.
Para Categoria, selecione genai-hosted-deployment-log ou crie um novo grupo de logs.
Para Grupo de logs, selecione um grupo existente ou Criar novo grupo.
Selecione o compartimento que contém o grupo de logs.
Digite um nome de log.
(Opcional) Em Opções avançadas, selecione um período de retenção de log.
O período de retenção padrão é 1 mês (30 dias).

Verificar e Criar

Verifique as definições do aplicativo e selecione Criar aplicativo.

Observação

O tempo de criação do aplicativo depende dos recursos que o serviço provisiona para o aplicativo.

Se o armazenamento gerenciado estiver ativado, o serviço provisionará ou anexará o armazenamento selecionado, o que pode levar vários minutos.
Se a opção rede personalizada for selecionada, o serviço provisionará os recursos de ponte de rede necessários, o que também poderá levar alguns minutos.

Verifique as definições e selecione Criar aplicativo.

Se você selecionou Nenhuma autenticação, verifique se o Tipo de autenticação mostra esse valor.

Após a criação, exiba Tipo de autenticação em Autenticação na guia Configuração do aplicativo.

Dica

Depois de criar um aplicativo, você poderá exibir seus detalhes e executar outras tarefas, como movê-lo para outro compartimento, gerenciar suas tags ou excluí-lo. Use o menu Ações (três pontos) na Console para acessar essas tarefas. Você também pode criar uma implantação para o aplicativo em sua página de detalhes. Para obter mais informações, consulte Listando Aplicativos.

Documentação do Oracle Cloud Infrastructure