Em julho de 2026, nove modelos de IA de pesos abertos foram publicados em apenas doze dias, segundo o AI Release Tracker: o Inkling da Thinking Machines Lab (975 mil milhões de parâmetros), o Kimi K3 da Moonshot AI (2,8 biliões de parâmetros), o Hy3 da Tencent, o Laguna S 2.1 da poolside e mais cinco lançamentos de peso semelhante. Cada um destes ficheiros pesa dezenas ou centenas de gigabytes e é descarregado por milhares de programadores todas as semanas sem qualquer verificação de que o ficheiro recebido é, de facto, o que o laboratório publicou. É aqui que entra a Sigstore, um projeto de código aberto que já protege bibliotecas de software e que está a começar a proteger também os pesos dos modelos de IA.
Este tutorial mostra, passo a passo, como assinar e verificar modelos de IA com a Sigstore e o formato safetensors, usando ferramentas reais (a biblioteca sigstore, o pacote model-signing e o huggingface_hub) num projeto completo que podes reutilizar amanhã no teu próprio pipeline. Não é teoria: no final vais ter um script funcional que assina um modelo, publica a assinatura e recusa carregar qualquer ficheiro que tenha sido alterado.
Se trabalhas numa equipa que já usa modelos open weight em produção, quer sejam pequenos modelos de classificação treinados internamente, quer sejam derivados de modelos como o Kimi K3 ou o GLM-5.2, este guia serve para fechar uma lacuna que a maioria das equipas ainda não resolveu: como provar, de forma verificável e não apenas “de confiança”, que o ficheiro que está a correr em produção é o mesmo que foi validado pela equipa de segurança. Vamos usar um modelo pequeno para os exemplos práticos (para não obrigar ninguém a descarregar centenas de gigabytes só para aprender), mas cada comando funciona exatamente da mesma forma com modelos de qualquer escala.
Porque a Proveniência de Modelos de IA se Tornou Urgente em 2026
Durante anos, descarregar um modelo de IA era como descarregar qualquer outro ficheiro: confiavas no nome do repositório e seguias em frente. Isso mudou de forma abrupta em 2026. Com o Inkling a chegar como um modelo de 975 mil milhões de parâmetros publicado sob licença Apache 2.0 a 15 de julho, com pesos disponíveis para download no próprio dia do anúncio, e com o Kimi K3 a somar 2,8 biliões de parâmetros (104 mil milhões ativos por token) e pesos publicados no Hugging Face a 27 de julho sob a Kimi K3 License, o volume de ficheiros de pesos a circular multiplicou-se em semanas.
O problema não é só de escala. É de confiança. Um ficheiro de modelo modificado pode incluir código malicioso escondido num checkpoint, pesos subtilmente alterados para introduzir um comportamento indesejado, ou simplesmente uma versão desatualizada e vulnerável apresentada como a mais recente. A Google Research, num artigo técnico sobre a proteção da cadeia de fornecimento de software de IA, resume o raciocínio: “For signing open models, we recommend Sigstore, a free, public-good service that simplifies code signing and verification by abstracting away most key-management complexity.” Ou seja: assinar modelos deixou de ser um exercício académico e passou a ser uma prática recomendada por quem constrói a infraestrutura que todos usamos.
Outros lançamentos do mesmo mês reforçam o padrão. O GLM-5.2 da Zhipu AI (753 mil milhões de parâmetros, licença MIT) e o Laguna S 2.1 da poolside (118 mil milhões de parâmetros totais, 8 mil milhões ativos, licença OpenMDW-1.1) foram ambos publicados com documentação extensa de proveniência, incluindo logs de treino e harnesses de avaliação divulgados publicamente. Isto mostra que a indústria está a caminhar para um padrão onde publicar pesos já não basta: é preciso também provar de onde vieram e que não foram adulterados depois de saírem do laboratório.
Há ainda uma pressão regulatória a empurrar nesta direção. O AI Act da União Europeia já exige documentação técnica e transparência para modelos de fundação, e equipas que operam em Portugal e no resto da UE vão precisar cada vez mais de provar, com registos auditáveis, que o modelo em produção corresponde ao modelo que foi avaliado e aprovado internamente. Assinar cada versão do modelo com a Sigstore dá-te esse registo sem teres de construir infraestrutura própria de raiz.
Sigstore Explicado: Assinaturas Sem Gestão de Chaves
A Sigstore nasceu para resolver um problema antigo da assinatura digital: guardar e gerir chaves privadas com segurança é difícil, caro e propenso a erros. Em vez de pedir a cada programador para gerar e proteger um par de chaves GPG para sempre, a Sigstore usa certificados de curta duração emitidos através de identidade OIDC (a mesma tecnologia que usas para “iniciar sessão com o Google” ou “com o GitHub”). O certificado só existe durante a assinatura e é depois registado publicamente num livro de transparência chamado Rekor.
Ryan Hurst, um dos contribuidores do projeto, explica o objetivo central da Sigstore desta forma: “We need to make it possible to verify provenance along the entire chain and the goal of the Sigstore effort is to enable just that.” Na prática, isto significa que qualquer pessoa (não só quem assinou) pode verificar, anos depois, que um determinado ficheiro corresponde exatamente ao que foi assinado, sem precisar de confiar cegamente em ninguém: basta consultar o registo público.
A equipa de segurança da Google resume o benefício direto para quem consome modelos de IA: “Using digital signatures like those from Sigstore, we allow users to verify that the model used by the application is exactly the model that was created by the developers.” É exatamente este o problema que este tutorial resolve: garantir que o ficheiro .safetensors que carregas no teu servidor de inferência é, byte a byte, o mesmo que o laboratório publicou.
A Sigstore não nasceu para modelos de IA. O projeto começou como resposta a incidentes de cadeia de fornecimento de software, o tipo de ataque em que um pacote popular no npm ou no PyPI é comprometido e passa a distribuir código malicioso a todos os que o instalam. O mesmo raciocínio aplica-se, sem alterações de fundo, a um ficheiro de pesos de um modelo: se um repositório popular no Hugging Face for comprometido e um atacante substituir os pesos por uma versão alterada, quem descarregar esse modelo sem verificação não tem forma de saber. A adaptação da Sigstore ao domínio dos modelos de IA, através do projeto model-signing, é recente mas já é usada por vários laboratórios de investigação para assinar as suas próprias publicações.
Safetensors vs Pickle: o Risco Que Está a Ser Eliminado
Antes de assinar seja o que for, vale a pena perceber porque o formato do ficheiro importa tanto quanto a assinatura. Durante anos, o formato mais comum para guardar pesos de modelos em PyTorch foi o pickle (ficheiros .bin ou .pt). O problema é que um ficheiro pickle não guarda só números: pode conter instruções de código Python que são executadas automaticamente no momento em que o ficheiro é carregado. Um checkpoint malicioso disfarçado de modelo popular pode, teoricamente, executar código arbitrário na máquina de quem o carrega.
O formato safetensors, criado pela Hugging Face, resolve isto pela raiz: guarda apenas tensores (os números dos pesos) e metadados, sem qualquer capacidade de execução de código. Um ficheiro .safetensors corrompido ou malicioso não consegue correr código, só pode, no máximo, conter números errados. Combinar safetensors com assinatura Sigstore cobre os dois lados do problema: o formato elimina a classe de ataque “execução de código ao carregar”, e a assinatura elimina a classe de ataque “troca do ficheiro depois de publicado”. A documentação oficial da Hugging Face sobre segurança do Hub confirma esta separação de responsabilidades entre formato seguro e verificação de integridade.
| Método | Gestão de chaves | Registo público auditável | Custo | Adequado a ficheiros de dezenas de GB |
|---|---|---|---|---|
| Checksum SHA-256 manual | Não aplicável | Não | Grátis | Sim, mas sem prova de autoria |
| Assinatura GPG tradicional | Chave privada permanente, gerida pelo utilizador | Não, por defeito | Grátis | Sim, mas frágil se a chave se perder |
| Sigstore (Fulcio + Rekor) | Certificados efémeros via OIDC, sem chave permanente | Sim, no Rekor | Grátis (bem público) | Sim, com hashing paralelo para ficheiros grandes |
| Assinatura de código proprietária (ex: Authenticode) | Certificado pago, renovação anual | Parcial | Pago (licença anual) | Sim, mas pensado para executáveis, não para tensores |
Pré-Requisitos e Versões Necessárias
Antes de avançar, confirma que tens o seguinte instalado. As versões abaixo correspondem às versões mais recentes publicadas no PyPI no momento em que este tutorial foi escrito, por isso confirma sempre a versão atual antes de instalar em produção. Nenhuma destas ferramentas exige conta paga nem infraestrutura própria: tudo o que precisas está disponível em bibliotecas de código aberto e no serviço público da Sigstore.
- Python 3.10 ou superior (recomendado 3.11+ para melhor desempenho no hashing de ficheiros grandes)
pip23 ou superior- Pacote
sigstore(versão 4.5.0 à data deste tutorial) — a biblioteca e CLI oficial da Sigstore para Python - Pacote
model-signing(versão 1.1.1) — o projeto oficial do OpenSSF/Sigstore especializado em assinar pesos de modelos, incluindo safetensors, ONNX, GGUF e checkpoints do TensorFlow - Pacote
huggingface_hub(versão 1.31.0), para descarregar modelos diretamente do Hub - Pacote
safetensors(versão 0.8.0) — para inspecionar e validar o conteúdo dos ficheiros de pesos - Uma conta gratuita numa identidade OIDC suportada (GitHub, Google ou Microsoft) para assinar com a Sigstore pública
- Cerca de 5 GB de espaço livre em disco se quiseres seguir o tutorial com um modelo pequeno de teste (não é preciso descarregar o Inkling completo de 975 mil milhões de parâmetros para aprender o processo)
Nota importante: não precisas de nenhuma chave privada, cartão de crédito ou conta paga. A Sigstore pública (usada neste tutorial) é um serviço de bem público mantido pela Linux Foundation e parceiros como a Google, e destina-se precisamente a projetos de código aberto.
Passo 1 e 2: Preparar o Ambiente e Instalar as Ferramentas
Passo 1: Criar um ambiente virtual isolado
Começa sempre por isolar as dependências num ambiente virtual. Isto evita conflitos de versões entre este projeto e outros que tenhas na máquina.
mkdir verificacao-modelos-ia
cd verificacao-modelos-ia
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pipPasso 2: Instalar as bibliotecas de assinatura e verificação
Com o ambiente ativo, instala as quatro bibliotecas necessárias numa única linha.
pip install sigstore model-signing huggingface_hub safetensors
# confirmar as versões instaladas
python3 -c "import sigstore, model_signing, huggingface_hub, safetensors; \
print('sigstore ok'); print('model_signing ok'); \
print('huggingface_hub', huggingface_hub.__version__); \
print('safetensors', safetensors.__version__)"Resultado esperado no terminal:
sigstore ok
model_signing ok
huggingface_hub 1.31.0
safetensors 0.8.0Passo 3 e 4: Obter e Inspecionar um Modelo Open Weight
Passo 3: Descarregar um modelo em formato safetensors
Para seguir o tutorial sem precisar de descarregar centenas de gigabytes, usa um modelo pequeno publicado em safetensors. O processo é idêntico para um modelo de escala Inkling ou Kimi K3, só muda o tempo de download e o tempo de hashing.
from huggingface_hub import snapshot_download
caminho_local = snapshot_download(
repo_id="hf-internal-testing/tiny-random-gpt2",
allow_patterns=["*.safetensors", "*.json"],
local_dir="./modelo-teste"
)
print("Modelo descarregado para:", caminho_local)Em produção, substituis o repo_id pelo modelo real que a tua equipa vai usar, por exemplo o repositório oficial do Kimi K3 ou do GLM-5.2 no Hugging Face Hub.
Passo 4: Confirmar que o ficheiro é mesmo safetensors e não pickle disfarçado
Nunca assumas que um ficheiro com extensão .safetensors é seguro só pela extensão. Confirma o cabeçalho do formato antes de continuar.
from safetensors import safe_open
with safe_open("./modelo-teste/model.safetensors", framework="pt") as f:
chaves = list(f.keys())
print(f"Tensores encontrados: {len(chaves)}")
print("Primeiros 5 tensores:", chaves[:5])Se este comando falhar com um erro de formato, o ficheiro não é um safetensors válido e não deve ser carregado em produção sem investigação adicional.
Passo 5 e 6: Gerar o Hash e Assinar o Modelo com Sigstore
Passo 5: Autenticar-te com a tua identidade OIDC
A assinatura com a Sigstore pública abre automaticamente uma janela do browser para autenticares com o GitHub, Google ou Microsoft. Não precisas de criar nenhuma conta nova nem gerar chaves.
model_signing sign ./modelo-teste \
--signature ./modelo-teste.sigstore \
--model_path ./modelo-testePasso 6: Assinar e publicar o bundle no registo de transparência
Depois de autenticado, a ferramenta calcula o hash de todos os ficheiros do diretório do modelo (em paralelo, para não demorar horas em modelos grandes), assina o resultado e publica o bundle no Rekor. Para um modelo pequeno como o usado neste tutorial, o processo completo demora menos de um segundo depois da autenticação. Para um modelo com centenas de gigabytes, a maior parte do tempo vai para o cálculo do hash, não para a assinatura em si. O resultado no terminal é semelhante a este:
Waiting for browser authentication...
Identity verified: [email protected] via GitHub
Hashing 3 files (14.2 MB total)... done in 0.4s
Signing manifest... done
Publishing to Rekor transparency log... done
Signature written to: ./modelo-teste.sigstore
Rekor log index: 218044931O ficheiro .sigstore gerado é o que deves distribuir junto com o modelo. Ele não contém nenhuma chave secreta, apenas o certificado efémero, a assinatura e a referência ao registo público, exatamente como descrito no repositório oficial do projeto: “The verification part reads the sigstore bundle file and firstly verifies that the signature is valid and secondly compute the model’s file hashes again to compare against the signed ones.”
Passo 7 e 8: Publicar o Bundle e Verificar no Registo de Transparência
Passo 7: Distribuir o modelo junto com o bundle de assinatura
Quando publicares o modelo (num repositório interno, num bucket privado ou no próprio Hugging Face Hub como ficheiro adicional), inclui sempre o ficheiro .sigstore ao lado dos pesos. Sem ele, quem receber o modelo não tem como verificar nada, mesmo que a assinatura exista algures no registo público: sem o bundle à mão, a verificação exige localizar manualmente o índice do Rekor correto, o que não é prático num fluxo de trabalho do dia a dia.
modelo-teste/
├── config.json
├── model.safetensors
└── model.safetensors.sigstore # bundle de assinatura, distribuir sempre juntoPasso 8: Confirmar a entrada no registo público do Rekor
Qualquer pessoa, incluindo alguém sem acesso ao teu repositório, pode consultar publicamente se aquele índice do Rekor existe e a que identidade corresponde. Isto é o que separa a Sigstore de uma assinatura GPG comum: a prova de autoria fica registada de forma independente do canal de distribuição.
python3 -c "
from sigstore.rekor import RekorClient
client = RekorClient.production()
entrada = client.log.entries.get(log_index=218044931)
print('Assinante verificado:', entrada.attestation.certificate.identity)
"Passo 9 e 10: Verificar a Assinatura Antes de Carregar o Modelo
Passo 9: Verificar a integridade e a identidade do assinante
Este é o passo que realmente importa em produção: antes de carregar qualquer modelo, verifica a assinatura. Tens de indicar a identidade esperada (o email ou domínio de quem deveria ter assinado), para evitar que uma assinatura válida mas de origem errada passe despercebida.
model_signing verify ./modelo-teste \
--signature ./modelo-teste.sigstore \
--identity "[email protected]" \
--identity-provider "https://github.com/login/oauth"Se tudo estiver correto, o resultado é:
Verifying signature bundle...
Certificate identity matches expected: [email protected]
Recomputing file hashes... done
Hashes match signed manifest.
VERIFICATION SUCCESSFULPasso 10: Simular uma adulteração para confirmar que a verificação falha
Um passo que a maioria das equipas salta, mas que é essencial: testa deliberadamente um cenário de falha. Altera um único byte do ficheiro de pesos e corre a verificação outra vez.
echo -n "X" | dd of=./modelo-teste/model.safetensors bs=1 seek=100 count=1 conv=notrunc
model_signing verify ./modelo-teste \
--signature ./modelo-teste.sigstore \
--identity "[email protected]"O resultado correto deve ser uma falha explícita:
Recomputing file hashes... done
Hash mismatch on: model.safetensors
VERIFICATION FAILED: file has been modified since signingSe este teste não falhar, alguma coisa está mal configurada no teu pipeline e precisas de investigar antes de confiar na verificação em produção.
Passo 11 e 12: Automatizar a Verificação num Pipeline CI/CD
Passo 11: Adicionar a verificação como um passo obrigatório no deployment
A verificação manual serve para aprender o processo, mas em produção deve correr automaticamente sempre que um modelo é implantado. Um exemplo de workflow do GitHub Actions que bloqueia o deployment se a verificação falhar:
name: verificar-modelo-antes-do-deploy
on:
workflow_dispatch:
jobs:
verificar:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install model-signing sigstore
- name: Verificar assinatura do modelo
run: |
model_signing verify ./modelos/producao \
--signature ./modelos/producao.sigstore \
--identity "[email protected]" \
--identity-provider "https://github.com/login/oauth"Passo 12: Registar o resultado da verificação para auditoria
Para efeitos de auditoria e conformidade (relevante também à luz do AI Act europeu sobre transparência de modelos), guarda o resultado de cada verificação, não apenas o resultado final do deployment.
import subprocess
import json
resultado = subprocess.run(
["model_signing", "verify", "./modelos/producao",
"--signature", "./modelos/producao.sigstore",
"--identity", "[email protected]"],
capture_output=True, text=True
)
registo = {
"modelo": "producao",
"sucesso": resultado.returncode == 0,
"saida": resultado.stdout,
}
with open("auditoria-verificacao.jsonl", "a") as f:
f.write(json.dumps(registo) + "\n")Projeto Completo: Script de Verificação Ponta a Ponta
Juntando todos os passos anteriores, este é o script completo que podes guardar como verificar_modelo.py e reutilizar em qualquer projeto. Ele descarrega o modelo, confirma o formato safetensors, verifica a assinatura Sigstore e só depois liberta o caminho local para o resto da aplicação.
import subprocess
import sys
from pathlib import Path
from huggingface_hub import snapshot_download
from safetensors import safe_open
def descarregar_modelo(repo_id: str, destino: str) -> str:
caminho = snapshot_download(
repo_id=repo_id,
allow_patterns=["*.safetensors", "*.json", "*.sigstore"],
local_dir=destino,
)
return caminho
def confirmar_formato_seguro(caminho_modelo: str) -> bool:
ficheiros = list(Path(caminho_modelo).glob("*.safetensors"))
if not ficheiros:
print("ERRO: nenhum ficheiro .safetensors encontrado")
return False
for ficheiro in ficheiros:
try:
with safe_open(str(ficheiro), framework="pt"):
pass
except Exception as erro:
print(f"ERRO: {ficheiro} não é um safetensors válido ({erro})")
return False
return True
def verificar_assinatura(caminho_modelo: str, bundle: str, identidade: str) -> bool:
resultado = subprocess.run(
["model_signing", "verify", caminho_modelo,
"--signature", bundle, "--identity", identidade],
capture_output=True, text=True,
)
print(resultado.stdout)
return resultado.returncode == 0
def carregar_modelo_com_seguranca(repo_id: str, identidade_esperada: str) -> str:
destino = f"./modelos/{repo_id.replace('/', '_')}"
caminho = descarregar_modelo(repo_id, destino)
if not confirmar_formato_seguro(caminho):
sys.exit("Abortado: formato de ficheiro inseguro")
bundle = f"{caminho}.sigstore"
if not verificar_assinatura(caminho, bundle, identidade_esperada):
sys.exit("Abortado: assinatura inválida ou identidade incorreta")
print(f"Modelo {repo_id} verificado e pronto a usar em: {caminho}")
return caminho
if __name__ == "__main__":
carregar_modelo_com_seguranca(
repo_id="hf-internal-testing/tiny-random-gpt2",
identidade_esperada="[email protected]",
)Este script recusa-se a devolver um caminho utilizável se qualquer uma das três verificações falhar (formato, integridade ou identidade). É este o comportamento que queres num pipeline de produção: falhar de forma ruidosa em vez de carregar silenciosamente um modelo suspeito. Podes adaptar a função carregar_modelo_com_seguranca para chamar diretamente o teu framework de inferência (vLLM, llama.cpp ou o servidor que já usas) assim que a verificação passa, mantendo a mesma barreira de segurança em todos os pontos de entrada da tua aplicação.
Comparação de Modelos Open Weight Publicados em Julho de 2026
Para perceberes a escala do problema que este tutorial resolve, esta tabela resume os principais lançamentos de modelos de pesos abertos do último mês e o respetivo nível de divulgação de proveniência à data do lançamento.
| Modelo | Laboratório | Parâmetros | Licença | Divulgação de proveniência |
|---|---|---|---|---|
| Inkling | Thinking Machines Lab | 975B (multimodal) | Apache 2.0 | Pesos no dia do anúncio (15 jul. 2026) |
| Kimi K3 | Moonshot AI | 2,8T total / 104B ativos por token | Kimi K3 License | Pesos publicados a 27 jul. 2026 |
| Hy3 | Tencent | 295B total / 21B ativos | Open weight permissiva | Model card oficial no lançamento |
| Laguna S 2.1 | poolside | 118B total / 8B ativos | OpenMDW-1.1 | Logs de treino e harness de avaliação publicados |
| GLM-5.2 | Zhipu AI / Z.ai | 753B | MIT | Documentação pública de tarefas agentic |
Repara que nenhum destes lançamentos inclui, por defeito, uma assinatura Sigstore verificável pelo público no momento em que os pesos ficam disponíveis. Isso não significa que os laboratórios não se importem com integridade, significa apenas que a prática de assinar pesos de modelos com Sigstore ainda está a dar os primeiros passos fora dos círculos de investigação em segurança. É precisamente esta lacuna que o processo descrito neste tutorial preenche do lado de quem consome estes modelos: mesmo que o laboratório de origem não assine o ficheiro, a tua equipa pode assinar a versão que validou internamente antes de a colocar em produção, criando o teu próprio elo de confiança a partir desse ponto.
Erros Comuns ao Assinar e Verificar Modelos de IA
Estes são os erros que mais vezes acontecem quando uma equipa adota assinatura de modelos pela primeira vez. A maioria não vem de má-fé, vem de tratar a assinatura como uma checkbox de conformidade em vez de um processo com implicações reais na segurança do sistema.
- Assinar depois de já teres distribuído o modelo. A assinatura só protege o que acontece depois de ser gerada. Se o modelo já circulou sem assinatura, qualquer cópia anterior não tem forma de ser diferenciada de uma cópia adulterada, e assinar tarde dá uma falsa sensação de segurança retroativa que não existe.
- Verificar apenas o hash e ignorar a identidade do assinante. Confirmar que o ficheiro não mudou não serve de nada se não confirmares também quem o assinou. Um atacante pode assinar um modelo malicioso com a própria identidade dele, e se o teu script de verificação não comparar a identidade esperada, vai aceitar essa assinatura como válida.
- Guardar o ficheiro
.sigstorenum local diferente do modelo. Se o bundle de assinatura se perder ou for esquecido num deployment, ninguém consegue verificar nada e a prática de assinar torna-se inútil na prática. Trata o bundle como parte inseparável do artefacto, não como um extra opcional. - Confiar apenas na extensão do ficheiro para assumir que é safetensors. Como visto no Passo 4, a extensão pode mentir. Confirma sempre o conteúdo real do ficheiro antes de o carregar em qualquer framework.
- Não testar o cenário de falha. Muitas equipas configuram a verificação, veem que passa uma vez e nunca mais testam se ela realmente bloqueia um ficheiro adulterado (Passo 10). Sem esse teste, não sabes se a verificação protege alguma coisa ou se está apenas a imprimir mensagens de sucesso sem validar nada.
- Assumir que a assinatura substitui a análise de segurança do próprio modelo. A Sigstore garante que o ficheiro não mudou desde que foi assinado, não garante que o conteúdo original seja seguro ou livre de vieses. São verificações complementares, não substitutas uma da outra.
- Deixar a lista de identidades autorizadas desatualizada. Quando alguém sai da equipa ou muda de função, a conta usada para assinar deve ser removida da lista de identidades aceites na verificação. Uma lista desatualizada é uma porta aberta que ninguém está a vigiar.
Resolução de Problemas: 8 Situações Frequentes
Uma lista de referência rápida para os problemas mais comuns ao configurar este fluxo pela primeira vez. Guarda esta tabela junto da documentação interna do teu pipeline, porque a maioria destes problemas só aparece semanas depois da configuração inicial, quando alguém em ambiente diferente do teu tenta reproduzir o processo.
| Sintoma | Causa provável | Como resolver |
|---|---|---|
| “Browser authentication timed out” | A janela OIDC não foi confirmada a tempo ou o ambiente não tem browser gráfico | Corre num terminal com acesso a browser, ou usa o modo de dispositivo (device flow) da CLI para servidores sem interface gráfica |
| “Hash mismatch” logo após assinar, sem ter alterado nada | O ficheiro foi reescrito (normalização de fim de linha, permissões) entre a assinatura e a verificação | Assina sempre a partir do ficheiro final tal como será distribuído, sem passos de conversão a meio |
| “Certificate identity does not match expected” | A conta usada para assinar não corresponde ao identificador esperado na verificação | Confirma o email exato associado ao provedor OIDC e usa-o tal como aparece no certificado |
| Download do modelo muito lento antes mesmo de chegar à assinatura | Modelos como o Kimi K3, com 2,8 biliões de parâmetros, resultam em ficheiros de várias centenas de gigabytes | Usa allow_patterns para descarregar só os ficheiros necessários e considera hashing paralelo com múltiplos processos |
“safe_open” lança erro de formato num ficheiro .safetensors | O ficheiro foi truncado a meio do download ou corrompido em trânsito | Volta a descarregar e confirma o tamanho do ficheiro contra o valor esperado no repositório de origem |
| Verificação passa localmente mas falha no pipeline CI/CD | Versões diferentes do pacote model-signing entre o ambiente local e o runner | Fixa a versão exata no ficheiro de dependências (model-signing==1.1.1) em ambos os ambientes |
| Rekor devolve “entry not found” para um índice válido | Atraso de propagação no registo público logo após a assinatura | Espera alguns segundos e tenta novamente, o Rekor é eventualmente consistente, não instantâneo |
| A equipa recusa adotar o processo por “ser lento” | A verificação está a ser feita manualmente em cada deployment em vez de automatizada | Move a verificação para o pipeline CI/CD (Passo 11) para que corra sem intervenção humana |
Se nenhuma destas situações corresponder ao erro que estás a ver, o primeiro passo de diagnóstico deve ser sempre correr o comando com um nível de detalhe (verbose) mais alto e confirmar que as versões instaladas em cada ambiente (local, CI/CD, produção) são exatamente as mesmas. A grande maioria dos problemas reportados pela comunidade do projeto model-signing no GitHub resume-se a incompatibilidades de versão entre ambientes, não a falhas na própria ferramenta.
Boas Práticas Avançadas para Equipas e Produção
Depois de teres o fluxo básico a funcionar, há um conjunto de práticas que separam uma configuração de teste de uma configuração pronta para produção.
Primeiro, define uma lista fechada de identidades autorizadas a assinar modelos que entram em produção, e rejeita automaticamente qualquer assinatura válida mas de uma identidade fora dessa lista. A Sigstore não impede que qualquer pessoa com conta GitHub assine um modelo, o controlo de quem é o assinante legítimo é responsabilidade da tua organização, não da ferramenta.
Segundo, guarda uma cópia local do índice do Rekor associado a cada modelo em produção, além de depender da consulta em tempo real. Isto protege contra cenários raros de indisponibilidade do serviço público e permite auditorias offline.
Terceiro, se a tua organização tiver requisitos de conformidade que impeçam depender de infraestrutura pública partilhada, considera montar uma instância privada do Sigstore (o próprio projeto disponibiliza essa opção), mantendo o mesmo modelo de certificados efémeros mas com a tua própria autoridade de certificação interna.
Quarto, integra a verificação de proveniência com a análise de segurança do próprio conteúdo do modelo. O artigo de referência da Google Research nota que “Sigstore’s public signing ledgers form the foundation of trust for SLSA provenance”, mas isso cobre a cadeia de custódia, não o comportamento do modelo. Combina este tutorial com ferramentas de avaliação de segurança e vieses antes de considerares um modelo pronto para produção.
Por fim, documenta o processo de verificação no model card interno da tua equipa, incluindo a identidade esperada do assinante e a data da última verificação bem-sucedida. Isto facilita auditorias futuras e a integração de novos elementos na equipa.
Vale ainda a pena configurar alertas automáticos quando uma verificação falha no pipeline, em vez de depender de alguém a reparar num log vermelho no meio de centenas de execuções. Uma falha de verificação de assinatura deve ter a mesma prioridade que uma falha de testes críticos: bloqueia o deployment e notifica a equipa de segurança de imediato, não apenas a equipa de infraestrutura que fez o deploy.
Perguntas Frequentes
A Sigstore é gratuita para uso comercial?
Sim. A instância pública da Sigstore é mantida como um serviço de bem público sem custos de utilização, tanto para projetos pessoais como comerciais. Empresas com requisitos regulatórios específicos podem optar por montar a sua própria instância privada, mas isso é uma escolha adicional, não um requisito. A maioria das equipas que seguem este tutorial nunca vai precisar de sair da instância pública.
Preciso de converter modelos antigos em pickle para safetensors antes de os assinar?
Não é obrigatório: o model-signing consegue assinar outros formatos, incluindo checkpoints PyTorch tradicionais. No entanto, é recomendável converter para safetensors sempre que possível, porque a assinatura protege contra adulteração, mas não elimina o risco de execução de código associado ao formato pickle em si.
O que acontece se eu perder o ficheiro .sigstore mas ainda tiver o modelo?
Se souberes o índice do Rekor onde a assinatura original foi publicada, consegues recuperar o bundle a partir do registo público. Se não tiveres esse índice guardado nem o bundle original, não há forma de reconstruir a assinatura, terás de assinar o modelo novamente (o que só protege a partir desse novo momento).
A verificação da Sigstore funciona sem ligação à internet?
A verificação completa contra o registo público do Rekor precisa de ligação à internet. Para ambientes isolados (air-gapped), é possível guardar previamente uma cópia local do bundle de assinatura e da entrada do Rekor, permitindo verificação offline com base nesses dados guardados.
Quanto tempo demora a assinar um modelo do tamanho do Kimi K3 ou do Inkling?
Depende sobretudo da velocidade de leitura de disco e da largura de banda de upload, já que o hashing é feito em paralelo por ficheiro. Para modelos na casa das centenas de gigabytes, como o Inkling (975 mil milhões de parâmetros), o passo de hashing pode demorar vários minutos, mas a assinatura em si (a parte criptográfica) é quase instantânea.
Posso usar este processo com modelos guardados em GGUF, o formato usado pelo llama.cpp?
Sim, o projeto model-signing suporta múltiplos formatos de serialização de modelos além do safetensors, incluindo GGUF, ONNX e checkpoints do TensorFlow. O fluxo de assinatura e verificação é o mesmo independentemente do formato, só muda o parser interno usado para calcular o hash.
É preciso ser dono do repositório no Hugging Face para assinar um modelo?
Não. Qualquer pessoa com uma identidade OIDC pode assinar qualquer ficheiro, incluindo modelos de terceiros, para o seu próprio uso interno. O que importa é que, na verificação, definas a identidade esperada como sendo a tua própria (ou da tua equipa), não a do autor original do modelo, a não ser que o próprio laboratório publique uma assinatura oficial.
Esta prática substitui os testes de segurança feitos por ferramentas de red-teaming de modelos?
Não. A assinatura de modelos resolve o problema de integridade e proveniência (garantir que o ficheiro não foi alterado e identificar quem o publicou). Não substitui testes de segurança que avaliam o comportamento do modelo em si, como deteção de vieses, resistência a jailbreaks ou fugas de dados de treino. São camadas complementares, não intercambiáveis: uma equipa madura em segurança de IA usa as duas em conjunto, uma para garantir a origem do ficheiro e outra para garantir que o conteúdo desse ficheiro se comporta como esperado.
