Configurar funcionalidade de IA - Usuário
Referência de interface da tela de configuração de funcionalidades de IA por usuário no portal teleradiológico. Este documento descreve o fluxo funcional entre a interface, a PACS AI API e a API do portal para exibir e gerenciar as funcionalidades disponíveis por usuário.
As funcionalidades de IA são utilizadas em diversos locais do portal teleradiológico para auxiliar gestores e médicos em análises, resumos e gerações de exames, entre outros. A tela de configuração centraliza quais recursos estão habilitados, quais providers e prompts são aplicados e como cada funcionalidade se comporta na interface.
Diagrama de sequência — ativar e configurar funcionalidade
Fluxo para ativar uma funcionalidade, escolher provider (GPT ou Gemini), modelo, token e salvar:
Sobre o fluxo
- A seleção de GPT ou Gemini altera a lista de modelos retornada pela AI-API.
- Salvar token e Salvar configuração são ações distintas: primeiro valida/persiste a credencial, depois grava a funcionalidade habilitada.
Etapas
Passo a passo visual para ativar e configurar uma funcionalidade de IA, conforme o diagrama acima.
1. Acessar o painel
Após a autenticação no portal siga esses passos para acessar as preferências de usuário e as configurações de funcionalidades de IA:
1.1 Preferências de Usuário
1.2 Acessar aba IA
2. Aceite Termo de Uso
Para poder utilizar as funcionalidades de IA é necessário ler e aceitar o termo de uso imposto pelo proprietário
3. Ativar a funcionalidade
Na tabela de funcionalidades, localize o recurso desejado (ex.: revisão de laudo, ortografia, resumo de exames) e ative o toggle ou marque a opção correspondente.
4. Selecionar o provider de IA
Com a funcionalidade ativa, escolha o provider no campo disponível: Exemplo: GPT (OpenAI) ou Gemini (Google).
5. Selecionar o modelo
Após escolher o provider, a interface carrega os modelos disponíveis. Selecione o modelo desejado na lista (ex.: gpt-5.2, gemini-2.5-pro).
6. Informar o token
Acesse o formulário clicando no ícone de lápis e preencha o campo de token de autenticação com a credencial válida do provider selecionado (API key ou token conforme o contrato do serviço). Clique em Salvar para persistir a credencial.
O botão Salvar para Todos é utilizado para persistir a mesma chave de integração para todas as funcionalidades
7. Personalizar prompt
Opcionalmente é disponibilizado a modificação do prompt, a seção de tarefas enviadas para o modelo de IA.
7.1 Inserir personalização
Caso ainda não tenha uma personalização, basta digitar, de preferência em formato de etapas separadas por "-", no campo correspondente. Estando com o campo vazio, uma sugestão irá aparecer junto com um botão Editar prompt, ao clicar nesse botão, o texto sugerido será aplicado ao campo para ser utilizado ou alterado.
7.2 Editar personalização
Caso já exista uma personalização, para editá-la é necessário clicar no botão Editar no rodapé do formulário
7.3 Salvar
Por fim, clique no botão Salvar para persistir as alterações.
Deixar o campo de prompt vazio faz com que as tarefas padrões definidas pela aplicação serão utilizadas
8. Salvar a configuração
Com o token salvo, clique em Salvar para gravar as seleções.
Endpoints utilizados
Lista abaixo com as rotas utilizadas nesse fluxo e um descritivo sobre cada uma.
| Endpoint | Descrição |
|---|---|
API GET /configurationAI/user/# | Retorna as configurações das funcionalidades da preferência do usuário, informativo de token preenchido e seus respectivos prompts personalizados (se houver). |
API GET /termOfUse?type=ia | Traz informações sobre o aceite dos termos de uso para liberar ou bloquear o acesso às configurações. |
AI_API GET /provider | Traz informações sobre os providers e modelos de inteligência artificial a serem selecionados nas configurações. |
AI_API GET /prompts | Retorna os registros dos prompts padrões da aplicação para todas as funcionalidades, incluindo idiomas pt-BR, es-ES e en-US, tais como persona, regras, tarefas e resposta. |
API PUT /configurationAI/user/# | Atualiza a persistência de configurações de uma funcionalidade. Utilizada nesse contexto para atualizar o token. |
API PUT /configurationAI/user/#/batch | Atualiza a persistência com o formulário preenchido das alterações e registros das configurações de todas as funcionalidades. |
Legenda:
#se refere ao ID do usuário.
Regras de formulário
Lista os campos obrigatórios para que as configurações de uma ou mais funcionalidades possam ser persistidas.
| Campo | Regra |
|---|---|
has_secret_key | Formato boolean (verdadeiro ou falso) — indica se a funcionalidade está ativa ou não. Obrigatório. |
ia_selected | Formato string — indica qual provider de modelos de IA será utilizado. Obrigatório se has_secret_key estiver ativo. |
ia_model_selected | Formato string — indica qual modelo de IA foi selecionado de acordo com o provider. Obrigatório se has_secret_key estiver ativo. |
secret_key | Formato string — chave de acesso (token) para autenticar com o modelo selecionado de acordo com o provider. |
prompt | Formato string — instruções personalizadas designadas à funcionalidade. |
Mapeamento de erros
Lista os possíveis erros básicos que podem ocorrer durante o fluxo de configuração.
| Situação | Resposta da API | Comportamento |
|---|---|---|
| Abrir aba Módulos → IA — falha ao buscar termo de uso | API GET /termOfUse?type=ia | Aparece um aviso vermelho no topo dizendo que o termo não pôde ser carregado e um toast de erro. A tela de configuração fica bloqueada. |
| Clicar em Aceitar termo — falha genérica | API POST /configurationAI/termOfUse/acceptance | Toast informando que não foi possível aceitar o termo. A configuração continua bloqueada. |
| Clicar em Aceitar termo — aceite já existe | API POST /configurationAI/termOfUse/acceptance | Toast informando que o termo já foi aceito. A tela não libera a configuração automaticamente. |
| Abrir aba IA — falha ao listar providers | AI_API GET /provider | Toast de erro. Os campos de provedor e modelo ficam sem opções para escolher. |
| Abrir aba IA — falha ao listar prompts padrão | AI_API GET /prompts | Nenhum aviso aparece. Ao abrir o editor de prompt, não há exemplo nem texto auxiliar. |
| Usuário não é proprietário nem gestor tenta salvar a grade | O botão Salvar fica desabilitado. | |
| Funcionalidade marcada sem provedor e/ou modelo e/ou token | O botão Salvar fica desabilitado. O campo de token fica destacado em vermelho se faltar a chave. | |
| Provedor ou modelo selecionado está depreciado/inativo | AI_API GET /provider | A opção aparece marcada como depreciada e não pode ser escolhida de novo. O botão Salvar fica desabilitado e um aviso explica que há modelo inativo. |
| Editar token — campo vazio | Toast pedindo um token válido. A janela continua aberta e nada é salvo. | |
| Editar token — salvar (uma funcionalidade) falha | API PUT /configurationAI/user/# | Toast de erro. A janela continua aberta e o token não é aplicado. |
| Editar token — salvar para todos falha | API PUT /configurationAI/user/#/batch | Toast de erro. A janela continua aberta e nenhum token é atualizado. |
| Abrir editor de prompt — configuração da linha não encontrada | Toast dizendo que a configuração de IA não foi encontrada. O editor não abre. | |
| Abrir editor de token — configuração da linha não encontrada | Toast dizendo que a configuração de IA não foi encontrada. O editor não abre. | |
| Salvar prompt no modal — falha | API PUT /configurationAI/user/# | Toast de erro. O prompt não é salvo. |
| Salvar da grade — falha | API PUT /configurationAI/user/#/batch | Toast informando que não foi possível atualizar as configurações. As alterações não são confirmadas. |
Relacionado
- ⚙️ API: PACS AI API