Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Conformidade e Rasto de Auditoria

Aula 22 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Conformidade e Rasto de Auditoria
  2. Porquê um Rasto de Auditoria?
  3. Estrutura de um Registo de Auditoria
  4. Sistema de Auditoria Completo
  5. Consultas de Auditoria
  6. Retenção e Arquivo
  7. Lei Europeia da IA: O Que Muda
  8. Lista de Verificação de Conformidade
  9. Pontos-chave
  10. Teste os Seus Conhecimentos

Conformidade e Rasto de Auditoria

Para aplicações de IA em produção, a rastreabilidade é essencial. Um rasto de auditoria completo protege-o durante uma inspeção, uma disputa ou um incidente. Esta lição mostra-lhe como implementar um sistema de auditoria robusto, concluindo o curso ao reunir tudo o que construiu até agora — registo (logging), moderação e proteção de dados — numa única estrutura defensável.

Porquê um Rasto de Auditoria?

Quatro necessidades distintas convergem para a mesma infraestrutura. Primeiro, a conformidade regulamentar: o RGPD, a Lei Europeia da IA e as normas do setor exigem que demonstre o que o seu sistema faz, e uma demonstração sem registos não tem valor. Segundo, a rastreabilidade no sentido estrito — saber quem fez o quê, quando, com que resultado, mesmo seis meses depois. A depuração beneficia diariamente disto, pois compreender o comportamento inesperado do modelo requer recuperar as condições exatas da chamada. Finalmente, a responsabilização: documentar as decisões tomadas pela IA é o que lhe permitirá, quando chegar a altura, mostrar que uma recomendação contestada assentou num processo controlado.

Estrutura de um Registo de Auditoria

A dataclass abaixo é tanto um contrato como uma estrutura de dados. Agrupa identificadores, contexto da aplicação, o pedido, a resposta, o veredicto de moderação e metadados técnicos. Duas escolhas merecem a sua atenção. O identificador do utilizador aparece apenas sob forma hash, nunca em texto simples. E o prompt não é armazenado: apenas o seu hash e comprimento são guardados. Isto preserva a sua capacidade de provar que duas chamadas diziam respeito ao mesmo conteúdo sem criar um arquivo do que os seus utilizadores escreveram.

from dataclasses import dataclass, field, asdict
from datetime import datetime
from typing import Optional
import json
import uuid
import hashlib

@dataclass
class AuditRecord:
    """Registo de auditoria para uma chamada à API."""
    # Identificadores
    audit_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    timestamp: str = field(
        default_factory=lambda: datetime.now().isoformat()
    )

    # Contexto
    user_id_hash: str = ""  # Nunca o ID em texto simples
    session_id: str = ""
    application: str = ""

    # Pedido (sem dados sensíveis)
    model: str = ""
    prompt_hash: str = ""  # Hash do prompt, não o prompt em si
    prompt_length: int = 0

    # Resposta
    response_id: str = ""
    output_length: int = 0
    input_tokens: int = 0
    output_tokens: int = 0

    # Moderação
    input_flagged: bool = False
    output_flagged: bool = False

    # Metadados
    duration_ms: int = 0
    status: str = "success"
    error: Optional[str] = None

    def to_json(self) -> str:
        return json.dumps(asdict(self), ensure_ascii=False)

Sistema de Auditoria Completo

O cliente que aproveita esta estrutura encadeia a moderação de entrada, a chamada à API, a moderação de saída e escreve em todos os casos. A palavra importante é apenas anexação (append-only): o ficheiro JSONL é aberto em modo de anexação, nunca reescrito, o que é a condição para um registo ter valor probatório. Note o caminho de uma entrada assinalada: o registo é guardado antes de a exceção ser levantada, com o estado blocked_input. Um bloqueio deixa, portanto, um rasto tal como um sucesso, e o bloco except final garante que nenhum erro, seja qual for a sua origem, passa despercebido.

import time
from openai import OpenAI

class AuditedClient:
    """Cliente OpenAI com rasto de auditoria integrado."""

    def __init__(self, application: str, audit_store: str = "audit.jsonl"):
        self.client = OpenAI()
        self.application = application
        self.audit_store = audit_store

    def _hash(self, text: str) -> str:
        """Hash SHA-256 truncado para auditoria."""
        return hashlib.sha256(text.encode()).hexdigest()[:16]

    def _save_audit(self, record: AuditRecord):
        """Guarda um registo de auditoria (apenas anexação)."""
        with open(self.audit_store, "a", encoding="utf-8") as f:
            f.write(record.to_json() + "\n")

    def create(self, user_id: str, session_id: str,
               model: str, input: str, **kwargs) -> object:
        """Chamada à API com auditoria automática."""

        record = AuditRecord(
            user_id_hash=self._hash(user_id),
            session_id=session_id,
            application=self.application,
            model=model,
            prompt_hash=self._hash(input),
            prompt_length=len(input),
        )

        start = time.monotonic()

        try:
            # Moderação de entrada
            mod = self.client.moderations.create(
                model="omni-moderation-latest",
                input=input
            )
            record.input_flagged = mod.results[0].flagged

            if record.input_flagged:
                record.status = "blocked_input"
                self._save_audit(record)
                raise ValueError("Conteúdo de entrada inadequado")

            # Chamada à API
            response = self.client.responses.create(
                model=model,
                input=input,
                **kwargs
            )

            # Moderação de saída
            mod_out = self.client.moderations.create(
                model="omni-moderation-latest",
                input=response.output_text
            )
            record.output_flagged = mod_out.results[0].flagged

            # Preencher métricas
            record.response_id = response.id
            record.output_length = len(response.output_text)
            record.input_tokens = response.usage.input_tokens
            record.output_tokens = response.usage.output_tokens
            record.duration_ms = round((time.monotonic() - start) * 1000)
            record.status = "success"

            self._save_audit(record)
            return response

        except Exception as e:
            record.duration_ms = round((time.monotonic() - start) * 1000)
            record.status = "error"
            record.error = type(e).__name__
            self._save_audit(record)
            raise

# Utilização
audited = AuditedClient(application="support-chatbot")

response = audited.create(
    user_id="[email protected]",
    session_id="sess-abc123",
    model="gpt-5.6-terra",
    input="How do I return a product?"
)
print(response.output_text)

Neste exemplo, o endereço de e-mail passado como user_id nunca chega ao ficheiro: é transformado em hash assim que o registo é construído. Um ficheiro JSONL funciona bem para começar e para uma única instância; assim que vários processos escreverem em paralelo, direcione este fluxo para uma base de dados ou um coletor de registos.

Consultas de Auditoria

Um registo que não pode ser consultado serve apenas para ocupar espaço em disco. A leitura linha a linha do formato JSONL torna a exploração trivial, e o relatório abaixo resume o período coberto, a distribuição entre sucessos, erros e bloqueios, o consumo de tokens e a latência média. A contagem de utilizadores únicos baseia-se em hashes, o que prova, incidentalmente, que um registo pseudonimizado permanece perfeitamente analisável.

import json

def read_audit(file: str = "audit.jsonl") -> list[dict]:
    """Lê todos os registos de auditoria."""
    records = []
    try:
        with open(file, "r", encoding="utf-8") as f:
            for line in f:
                if line.strip():
                    records.append(json.loads(line))
    except FileNotFoundError:
        pass
    return records

def audit_report(file: str = "audit.jsonl") -> dict:
    """Gera um relatório de auditoria."""
    records = read_audit(file)

    if not records:
        return {"message": "Sem registos"}

    total = len(records)
    errors = sum(1 for r in records if r["status"] == "error")
    blocked = sum(1 for r in records if r["status"] == "blocked_input")
    tokens_total = sum(
        r.get("input_tokens", 0) + r.get("output_tokens", 0)
        for r in records
    )
    durations = [r["duration_ms"] for r in records if r["duration_ms"] > 0]

    return {
        "period": {
            "start": records[0]["timestamp"],
            "end": records[-1]["timestamp"],
        },
        "total_calls": total,
        "successes": total - errors - blocked,
        "errors": errors,
        "moderation_blocks": blocked,
        "tokens_consumed": tokens_total,
        "avg_latency_ms": round(sum(durations) / max(len(durations), 1)),
        "unique_users": len(set(r["user_id_hash"] for r in records)),
    }

print(json.dumps(audit_report(), indent=2, ensure_ascii=False))

Retenção e Arquivo

Manter dados indefinidamente contradiz o princípio da limitação da conservação; apagar demasiado cedo priva-o da prova de que possa necessitar. A rotação resolve este dilema: para além de uma duração que define — noventa dias aqui — os registos saem do ficheiro ativo para um arquivo datado, enquanto o registo atual é reescrito apenas com os recentes. Agende esta função como uma tarefa periódica e alinhe retention_days com a política validada pelo seu aconselhamento jurídico, não com um valor escolhido ao acaso.

from datetime import datetime, timedelta
import shutil
import os

def archive_audit(file: str = "audit.jsonl",
                  retention_days: int = 90):
    """Arquiva e limpa registos antigos."""
    records = read_audit(file)
    limit = datetime.now() - timedelta(days=retention_days)

    recent = []
    archives = []

    for record in records:
        date_record = datetime.fromisoformat(record["timestamp"])
        if date_record > limit:
            recent.append(record)
        else:
            archives.append(record)

    if archives:
        # Arquivar os antigos
        archive_name = f"audit_archive_{datetime.now().strftime('%Y%m%d')}.jsonl"
        with open(archive_name, "w", encoding="utf-8") as f:
            for record in archives:
                f.write(json.dumps(record, ensure_ascii=False) + "\n")

        # Reescrever o ficheiro principal com os recentes
        with open(file, "w", encoding="utf-8") as f:
            for record in recent:
                f.write(json.dumps(record, ensure_ascii=False) + "\n")

        print(f"Arquivados {len(archives)} registos em {archive_name}")
        print(f"Mantidos {len(recent)} registos recentes")

Lei Europeia da IA: O Que Muda

A Lei Europeia da IA (AI Act) impõe obrigações com base no nível de risco da sua aplicação. A lógica é graduada: quanto mais o seu sistema pese na vida das pessoas, mais rigorosos são os requisitos. Um chatbot de FAQ, um resumo ou uma tradução enquadram-se no risco mínimo e exigem apenas transparência básica. Assim que há conversação ou análise de sentimentos, passa para risco limitado, com a obrigação de informar o utilizador de que está a interagir com uma IA. O salto é abrupto para alto risco — pontuação de crédito, recrutamento, diagnóstico médico — onde se acrescentam avaliação de conformidade, gestão de riscos, documentação dos dados de treino, rastreabilidade completa, supervisão humana e demonstração de precisão. Certos usos, como a pontuação social ou a manipulação subliminar, são puramente proibidos.

# Avalie o nível de risco da sua aplicação
RISK_LEVELS = {
    "minimal": {
        "examples": ["chatbot de FAQ", "resumo de texto", "tradução"],
        "obligations": ["Transparência básica"]
    },
    "limited": {
        "examples": ["chatbot de atendimento ao cliente", "análise de sentimentos"],
        "obligations": ["Informar o utilizador de que está a interagir com uma IA"]
    },
    "high": {
        "examples": ["pontuação de crédito", "recrutamento", "diagnóstico médico"],
        "obligations": [
            "Avaliação de conformidade",
            "Sistema de gestão de riscos",
            "Dados de treino documentados",
            "Registo e rastreabilidade completa",
            "Supervisão humana obrigatória",
            "Precisão e robustez demonstradas"
        ]
    },
    "unacceptable": {
        "examples": ["pontuação social", "manipulação subliminar"],
        "obligations": ["PROIBIDO"]
    }
}

Situe honestamente o seu projeto nesta grelha antes de escrever a primeira linha de código: uma aplicação classificada como de alto risco impõe restrições arquitetónicas — registo exaustivo, ponto de controlo humano — que não podem ser enxertadas a posteriori num sistema desenhado sem elas.

Lista de Verificação de Conformidade

  • Rasto de auditoria apenas com anexação e carimbo de data/hora
  • Hash de dados pessoais nos registos (nunca em texto simples)
  • Moderação sistemática de entradas e saídas
  • Registo de atividades de tratamento RGPD atualizado
  • Política de retenção e arquivo definida
  • Avaliação do nível de risco da Lei da IA realizada
  • Informar os utilizadores de que estão a interagir com uma IA
  • Supervisão humana para decisões impactantes

Pontos-chave

  • Um rasto de auditoria é obrigatório para conformidade regulamentar
  • Registe em modo apenas de anexação: nunca modifique registos existentes
  • Transforme em hash todos os dados pessoais nos registos de auditoria
  • A Lei Europeia da IA classifica as aplicações por nível de risco
  • Implemente moderação automática E supervisão humana
  • Defina uma política de retenção e arquive regularmente

Teste os Seus Conhecimentos

Vinte e duas lições sobre a API: valide os mecanismos que sustentam a produção.

1. Porquê migrar para a API Responses em vez de permanecer na Chat Completions?

Resposta: É a API moderna da OpenAI: gestão integrada do estado da conversação, ferramentas nativas e evolução focada nela — a Chat Completions permanece suportada, mas é legada.

2. Como escolher entre Sol, Terra e Luna no lado da API?

Resposta: gpt-5.6-sol para tarefas exigentes, terra para o equilíbrio custo/qualidade, luna para volume económico — e o nível de raciocínio (none→max) é depois ajustado por pedido.

3. O que garante o Structured Output?

Resposta: Uma saída conforme com o esquema JSON fornecido — campos, tipos, estrutura — explorável por um programa sem análise defensiva ou reparação.

4. O que fazer perante um erro 429?

Resposta: Respeite os limites de taxa: tente novamente com retrocesso exponencial (e jitter), limite as tentativas e planeie um disjuntor — nunca um ciclo de repetição imediato.

5. Nomeie duas proteções indispensáveis no lado da segurança da aplicação.

Resposta: Moderação de conteúdo de entrada/saída através da API dedicada e defesa contra injeção de prompts: isolar instruções de dados, validar saídas, limitar capacidades expostas.

Produção, segurança, conformidade: os últimos três blocos do curso fazem a diferença entre um protótipo e um serviço — mantenha-os como lista de verificação.