Guia de Implementação

Passo a passo para colocar o GuardaIA em funcionamento na empresa do seu cliente — da instalação ao redirecionamento do chat corporativo.

O que o GuardaIA faz

O GuardaIA é um gateway de governança de IA que fica entre os funcionários da empresa e os serviços de IA (ChatGPT, Claude, Gemini etc.). Ele:

• Intercepta os prompts antes de saírem da empresa
• Detecta e mascara dados sensíveis (CPF, CNPJ, cartão, chaves de API...)
• Bloqueia o envio se houver dados críticos (modo block)
• Controla o custo mensal por departamento e projeto
• Mantém trilha de auditoria imutável com hash encadeado
• Isola os dados de cada empresa (multi-tenant)

Fluxo de uma requisição:

Funcionário  →  GuardaIA  →  OpenAI / Claude / Gemini
               ↑ autentica       ↑ DLP mascara
               ↑ verifica cota   ↑ registra custo
               ↑ audita          ↑ devolve resposta

Planos comerciais e limites técnicos

Os planos comerciais passam a ser parte da operação técnica. O GuardaIA registra o plano da organização e usa essa informação para bloquear excessos e liberar recursos compatíveis.

Configurando o primeiro tenant (empresa cliente)

Configurando provedores de IA

O GuardaIA roteia automaticamente pelo prefixo do modelo:

ChatGPT (OpenAI)

No cofre, selecione o provedor openai e informe a chave de API. O roteamento automático direciona modelos gpt-, o1 e o3 para este provedor.

Provedores personalizados (Groq, Mistral, Ollama...)

Menu Chaves de IA (Cofre) → Catálogo de provedores → Cadastrar provedor. Informe o nome, a base URL compatível com a API OpenAI e os prefixos de modelo para roteamento automático.

# Exemplo: Groq
Nome: groq
Base URL: https://api.groq.com/openai/v1
Prefixos: llama-,mixtral-,gemma-

Configurando a proteção de dados (DLP)

Estratégia de implantação em 3 semanas

Para trocar o modo: menu Regras DLP → Modo de operação.

Regras personalizadas

Além dos detectores nativos (CPF, CNPJ, cartão, e-mail, chaves de API...), você pode cadastrar padrões próprios da empresa: matrícula de funcionário, número de prontuário, código de contrato etc.

Menu Regras DLP → Regras personalizadas → informe o padrão (expressão regular) e use o Testador para verificar antes de salvar.

# Exemplos de padrões úteis
Matrícula:     \bMAT-\d{6}\b
Prontuário:    \bPRT-\d{8}\b
NF-e:          \b\d{44}\b
Processo:      \d{7}-\d{2}\.\d{4}\.\d\.\d{2}\.\d{4}

Cotas e projetos

Cotas por departamento

Menu Políticas de Cota → defina o limite mensal em US$ por departamento. Quando atingir:

• 75% — alerta gerado (visível no dashboard e no chat)
• 80% — novo alerta de atenção
• 95% — alerta crítico
• 100% — bloqueio das requisições (HTTP 429) ou só alerta, conforme a política

Projetos com cota própria

Para projetos com orçamento separado (chatbot de atendimento, copilot de contratos...), crie um projeto e gere uma chave tg- vinculada a ele. A cota do projeto é independente da cota do departamento.

Menu Projetos → Criar projeto → defina o limite mensal.

Guarda de auditoria monitorada

A retenção dos registros armazenados deixou de ser apenas configuração técnica e passou a ser uma política contratual. O sistema compara o plano da organização com o prazo de retenção configurado e impede prazos acima do permitido.

• Starter: guarda máxima de 30 dias
• Pro: guarda máxima de 6 meses
• Enterprise: guarda máxima de 1 ano

Na tela Retenção de Prompts, o painel informa o plano atual, a política máxima permitida e se existe alguma divergência entre a idade do conteúdo retido e o prazo contratado.

Estimador de projetos

Antes de fechar o orçamento com o cliente, use o Estimador de Projetos (menu lateral): cole a especificação, informe o volume de usuários e veja a projeção de custo em todos os modelos disponíveis, com cenários baixo / esperado / alto.

Portal de chat corporativo

O portal de chat (/chat ou /t/{slug}/chat) é a interface que os funcionários usam para interagir com a IA. Ele é protegido pelo GuardaIA: o funcionário entra com a chave tg- do departamento, escolhe o provedor e o modelo e conversa normalmente.

O que o funcionário vê

• Seletor de provedor (ChatGPT, Claude, Gemini...) e modelo
• Cada resposta exibe tokens consumidos, custo e — se o DLP agiu — quantos dados foram mascarados
• Se a mensagem for bloqueada (DLP ou cota), aparece orientação clara do que fazer

Distribuindo as chaves

Gere uma chave tg- por departamento no painel. Envie a chave para o funcionário por e-mail ou sistema interno. O funcionário cola a chave no portal de chat uma única vez (fica salva na sessão do navegador).

Ir para produção

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

set TG_ADMIN_TOKEN=troque-por-um-valor-aleatorio-longo

TG_GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
TG_SUPERADMIN_EMAIL=voce@suaempresa.com

# Nginx (trecho)
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

[Unit]
Description=GuardaIA

[Service]
WorkingDirectory=/opt/tokenguard
ExecStart=/usr/bin/python run.py
EnvironmentFile=/opt/tokenguard/.env
Restart=always

[Install]
WantedBy=multi-user.target

Perguntas frequentes

O funcionário vai perceber que está passando pelo GuardaIA?

Depende da interface. No portal de chat (/chat), a marca é visível. Se o sistema interno do cliente já usava a API OpenAI, basta trocar a base_url para o GuardaIA, pois a resposta é idêntica ao formato OpenAI, com um campo extra tokenguard nos metadados.

O que acontece se o GuardaIA ficar fora do ar?

Os funcionários perdem o acesso à IA corporativa enquanto o serviço está indisponível. Em modo alta disponibilidade (roadmap), múltiplas instâncias com load balancer eliminam esse risco. Para ambientes críticos, configure monitoramento com alertas.

A chave de API da empresa está segura?

Sim. As chaves dos provedores são criptografadas com AES (Fernet) usando uma master key que nunca vai para o banco. O painel nunca exibe a chave em claro — nem no formulário, nem na listagem. Em produção, substitua o arquivo .master_key por um serviço de KMS (AWS KMS, Azure Key Vault, HashiCorp Vault).

Posso usar com n8n, LangChain ou outros frameworks?

Sim. O GuardaIA é compatível com qualquer cliente que suporte a API OpenAI. Basta configurar:

# n8n — nó "OpenAI"
Base URL: http://localhost:8000/v1
API Key:  tg-SEU-TOKEN-DE-DEPARTAMENTO

# Python / LangChain
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="tg-...")

# JavaScript
const openai = new OpenAI({ baseURL: 'http://localhost:8000/v1', apiKey: 'tg-...' });

Como exportar o relatório de DLP para a diretoria?

No menu Auditoria e Logs, use os filtros para selecionar o período e o status. Os dados podem ser exportados diretamente do browser (botão direito → Salvar) ou via API (GET /admin/dlp-findings-log?org_id=...) para integração com Power BI ou Google Data Studio.

O expurgo de prompts quebra a auditoria?

Não. O hash encadeado da auditoria é calculado sobre os metadados (tokens, custo, modelo, timestamp) — o conteúdo do prompt nunca participa do hash. Expurgar o conteúdo por LGPD preserva o Selo de Integridade da trilha auditável.