Utilizando Harbor como um Registro de Modelos de IA

O ecossistema de containers resolveu a distribuição de software décadas atrás: construa uma imagem, envie-a para um registry, puxe-a em qualquer lugar. Em contraste, o gerenciamento de modelos de IA permanece fragmentado. Os modelos vivem em shared drives, cloud buckets, ou são integrados diretamente em imagens de container. No entanto, e se pudéssemos tratar os modelos de IA da mesma forma que tratamos as imagens de container? Esta publicação explora os fundamentos técnicos que tornam isso possível: o que são os artefatos Open Container Initiative (OCI), como os modelos de IA são empacotados neles e como o Harbor evoluiu para se tornar um registry de modelos. Em seguida, compartilharemos um fluxo de trabalho completo, de ponta a ponta, desde o download de um modelo do Hugging Face, sua conversão para inferência em CPU com llama.cpp, o envio para o Harbor usando diferentes ferramentas de empacotamento e a implantação em um cluster Kubernetes com KServe e vLLM.

O PROBLEMA: POR QUE MODELOS DE IA PRECISAM DE UM REGISTRY

Um modelo de IA treinado é, em sua essência, uma coleção de arquivos: tensores de peso serializados em formatos como SafeTensors ou GGUF, uma configuração de tokenizer e metadados descrevendo a arquitetura e o processo de treinamento. Hoje, a distribuição desses arquivos geralmente envolve:

• Download do Hugging Face Hub ou de um "model zoo" similar
• Cópia dos pesos para um filesystem compartilhado (NFS ou S3)
• Incorporação dos pesos do modelo diretamente em uma imagem Docker junto com o servidor de inferência

No entanto, incorporar pesos em imagens de container confunde o ciclo de vida do modelo com o ciclo de vida do servidor de inferência. Um modelo de 7B parâmetros pode ter mais de 14GB, e você não quer reconstruir e reenviar uma imagem de vários gigabytes toda vez que atualiza seu código de serviço.

Consequentemente, o que as organizações precisam é de um sistema que forneça:

• Armazenamento versionado e imutável para artefatos de modelo
• Controle de acesso baseado em função (RBAC) e trilhas de auditoria
• Análise de vulnerabilidades do ambiente de serviço
• Replicação entre geografias e ambientes
• Integração com ferramentas de CI/CD e Kubernetes existentes

Os registries de container já fornecem tudo isso para imagens de container. A percepção chave é que a especificação OCI foi projetada para ser extensível o suficiente para armazenar qualquer tipo de artefato, incluindo modelos de IA.

ARTEFATOS OCI: A FUNDAÇÃO

O que é um Artefato OCI?

A Open Container Initiative (OCI) define três especificações: a Image Spec, a Distribution Spec e a Runtime Spec. Importante, embora a Image Spec tenha sido originalmente projetada para imagens de container, sua estrutura é deliberadamente genérica.

Uma imagem OCI é descrita por um manifest, que é um documento JSON contendo:

• Um config descriptor: Metadados sobre o artefato
• Um array de layer descriptors: Ponteiros para os blobs de conteúdo reais (tarballs, no caso de imagens de container)
• Um campo artifactType: Identifica que tipo de artefato é
• Annotations: Metadados arbitrários de chave-valor

A decisão de design crítica é que os blobs de layer são endereçados por conteúdo (referenciados por seu digest SHA-256) e o campo mediaType em cada descriptor informa ao registry e aos clientes como interpretar o conteúdo. Na verdade, nada na especificação exige que as layers contenham tarballs de filesystem; elas podem conter qualquer coisa. Essa extensibilidade é o que torna os artefatos OCI possíveis.

Um Helm chart, um módulo WASM, uma assinatura, um SBOM ou um modelo de IA podem ser armazenados em um registry compatível com OCI, juntamente com imagens de container, usando a mesma infraestrutura de distribuição.

Por exemplo, um manifest OCI para um modelo de IA pode ser assim:

Cada arquivo de modelo se torna uma layer, identificada por seu digest de conteúdo. As annotations carregam metadados estruturados sobre o modelo, como arquitetura, contagem de parâmetros e formato, permitindo que os registries forneçam recursos ricos de busca e exibição.

A Especificação de Modelo CNAI

Além disso, a comunidade Cloud Native AI (CNAI) está desenvolvendo uma especificação de modelo que se baseia na extensibilidade da OCI. Ela define chaves de annotation padronizadas para metadados de modelo:

• org.cnai.model.name – Nome do modelo legível por humanos
• org.cnai.model.architecture – Arquitetura do modelo (por exemplo, transformer, cnn)
• org.cnai.model.family – Família base do modelo (por exemplo, llama, phi-3, mistral)
• org.cnai.model.format – Formato de serialização (por exemplo, safetensors, gguf, onnx)
• org.cnai.model.param.size – Contagem de parâmetros (por exemplo, 1.1B, 7B, 70B)

Esta especificação ainda está evoluindo, mas fornece uma base para registries como o Harbor exibirem metadados específicos do modelo de forma significativa.

Ferramentas para Empacotar Modelos como Artefatos OCI

Uma das forças do ecossistema OCI é que várias ferramentas podem produzir e consumir artefatos compatíveis com OCI. Além disso, o Harbor é agnóstico à ferramenta que você usa porque é compatível com OCI. Ele armazena e serve artefatos OCI padrão, independentemente de como foram empacotados. Aqui estão as duas abordagens principais.

OCI Registry As Storage (ORAS)

ORAS é a CLI de baixo nível e uso geral para enviar arquivos arbitrários como artefatos OCI. Ele oferece controle total sobre media types, artifact types e annotations. ORAS constrói um manifest OCI válido, faz upload do conteúdo do arquivo como layers e envia tudo para qualquer registry compatível com OCI.

Capacidades chave:

• Tipos de artefato personalizados (--artifact-type)
• Media types personalizados por layer (sintaxe file:mediaType)
• Arquivos de configuração com media types personalizados (--config)
• Annotations (--annotation)
• Autenticação contra registries privados (oras login)

ORAS é ideal quando você precisa de controle granular sobre a estrutura do manifest OCI ou ao integrar em pipelines de CI/CD personalizados.

KitOps

KitOps é um projeto sandbox da CNCF que adota uma abordagem declarativa de nível superior. Você define um Kitfile que é um manifest YAML descrevendo seu modelo, datasets, código e metadados, e a CLI "kit" empacota tudo em um ModelKit, que é um artefato compatível com OCI. KitOps é construído especificamente para fluxos de trabalho de IA/ML e compreende a estrutura de projetos de ML. Você pode gerar automaticamente um Kitfile a partir de um diretório de modelo usando "kit init", que escaneia o diretório, identifica arquivos de modelo, configurações e documentação, e produz um manifest pronto para uso. Você também pode escrever ou editar o Kitfile manualmente para controle total.

Capacidades chave:

• Empacotamento declarativo baseado em YAML
• Agrupa modelo, datasets, código e documentação
• Saída compatível com OCI para qualquer registry OCI
• Integração com init container do Kubernetes para implantação
• Comando unpack para puxar e extrair componentes do modelo

KitOps é ideal para equipes que desejam uma maneira estruturada e reproduzível de empacotar projetos de ML inteiros.

COMO O HARBOR EVOLUIU PARA SUPORTAR MODELOS DE IA

A Fundação OCI do Harbor

Harbor é um projeto graduado da CNCF que se originou na VMware (agora parte da Broadcom) e é o registry de container open source padrão para ambientes cloud-native. Ele sempre foi compatível com OCI, o que significa que pode armazenar e distribuir qualquer artefato que esteja em conformidade com a OCI Distribution Specification.

Em particular, as capacidades centrais do Harbor que se transferem diretamente para o gerenciamento de modelos incluem:

• Multi-tenancy: Projetos atuam como namespaces, isolando modelos por equipe, ambiente ou caso de uso.
• RBAC: Controle de acesso granular para quem pode enviar (push), puxar (pull) ou administrar artefatos de modelo.
• Replicação: Replicação baseada em políticas entre instâncias do Harbor, ou de registries upstream (incluindo Hugging Face).
• Políticas de retenção: Limpeza automatizada de versões antigas de modelos com base em regras configuráveis.
• Log de auditoria: Rastreamento completo de quem enviou, puxou ou modificou artefatos de modelo.
• Garbage collection: Recuperação de armazenamento de layers de modelo não referenciadas.
• Gerenciamento de cotas: Controle do consumo de armazenamento por projeto.
• Verificação de assinatura: Integração Cosign e Notary para verificar a proveniência do modelo.

A Jornada do Modelo de IA

A jornada do Harbor em direção ao suporte a modelos de IA tem sido um esforço deliberado e impulsionado pela comunidade. Inicialmente, o esforço surgiu de um desafio prático enfrentado pelos parceiros da comunidade Harbor: distribuir modelos de ML separadamente dos servidores de inferência. Empacotar pesos de modelo de vários gigabytes dentro de imagens Docker tornava as construções de container lentas, as imagens enormes e os ciclos de vida do modelo e do servidor desnecessariamente acoplados.

A abordagem que emergiu foi armazenar os pesos do modelo como artefatos OCI autônomos, desacoplados da imagem do servidor de inferência. Isso permite:

• Versionamento independente de modelos e servidores
• Armazenamento eficiente através da deduplicação de layers endereçadas por conteúdo
• Pulls mais rápidos, apenas as layers de modelo alteradas precisam ser baixadas

Subsequentemente, no Harbor v2.13, a integração com o projeto Cloud Native AI (CNAI) trouxe capacidades de registry de modelo de primeira classe:

• Uma UI dedicada para navegar por artefatos de modelo, mostrando metadados como arquitetura, tamanho do parâmetro, formato e uma lista de arquivos.
• Suporte para annotations específicas do modelo no formato da especificação de modelo CNAI.
• Replicação de registries de modelo upstream (Harbor-to-Harbor e Harbor-from-HuggingFace).
• Pré-aquecimento P2P para distribuição de modelos grandes em locais de borda (edge locations).

A Arquitetura

O fluxo de alto nível é:

• Build e Push: Modelos de IA são empacotados no formato OCI usando qualquer uma das ferramentas descritas acima (ORAS ou KitOps) e enviados para o Harbor. O manifest inclui annotations específicas do modelo, e cada arquivo de modelo (pesos, configuração do tokenizer, etc.) torna-se uma layer OCI.
• Pull e Consumo: Sistemas downstream puxam modelos do Harbor usando ferramentas OCI padrão. No Kubernetes, os modelos podem ser puxados via init containers com a CLI ORAS, montados como imagens OCI através do recurso Modelcars do KServe, ou (a partir do Kubernetes 1.31) via o recurso nativo Image Volume. Localmente, llama.cpp ou qualquer runtime compatível pode carregar os arquivos de modelo puxados diretamente.

Como o Harbor fala a OCI Distribution Specification, ele não se importa com qual ferramenta foi usada para empacotar o artefato. ORAS e KitOps produzem artefatos OCI compatíveis com os padrões que o Harbor armazena, replica, escaneia e serve de forma idêntica.

EXEMPLO COMPLETO: DOWNLOAD, CONVERSÃO, EMPACOTAMENTO E PUSH

Esta seção descreve um fluxo de trabalho completo para o desenvolvimento de modelos:

1. Baixar um LLM pré-treinado do Hugging Face (arquivos de modelo regulares, não formato OCI).
2. Convertê-lo para o formato GGUF usando llama.cpp para inferência eficiente em CPU.
3. Empacotar o modelo como um artefato OCI e enviá-lo para o Harbor (demonstrado com duas ferramentas: ORAS, KitOps).

Usaremos o TinyLlama (1.1B parâmetros), um LLM compacto construído na arquitetura Llama 2. TinyLlama faz parte da amplamente reconhecida família Llama, possui licença Apache 2.0 e produz um arquivo GGUF de aproximadamente 670 MB na quantização Q4_K_M, pequeno o suficiente para rodar em qualquer CPU moderna e rápido para enviar e puxar através de um registry.

Estamos usando um modelo pronto do Hugging Face aqui para manter o foco no empacotamento OCI e no fluxo de trabalho do Harbor. As mesmas etapas de empacotamento e push se aplicam, quer você esteja trabalhando com um modelo que você mesmo ajustou, um modelo treinado do zero ou um modelo pré-treinado baixado como está.

Pré-requisitos

• Uma instância do Harbor (v2.13+) com um projeto criado (por exemplo, "ml-models")
• Python 3.9+ com pip
• Git (para clonar llama.cpp para conversão GGUF)
• Pelo menos um dos seguintes: CLI ORAS ou CLI KitOps instalados
• 4+ GB de espaço em disco livre

Etapa 1: Baixar o Modelo do Hugging Face

Para começar, os modelos no Hugging Face são armazenados usando Git LFS, não no formato OCI. Ao baixar um modelo, você obtém arquivos simples: arquivos de peso SafeTensors, arquivos de configuração JSON e um tokenizer. Estes são os arquivos brutos que precisam ser reempacotados no formato OCI para o Harbor.

Instale a CLI do Hugging Face Hub:

Baixe o modelo TinyLlama:

Isso baixa o modelo para o diretório ./tinyllama-hf/:

Estes são arquivos de modelo padrão do Hugging Face: pesos SafeTensors, uma configuração de modelo e arquivos de tokenizer. Neste ponto, o modelo é apenas um diretório de arquivos em seu disco local.

Etapa 2: Converter para o Formato GGUF com llama.cpp

Llama.cpp é uma biblioteca C/C++ altamente otimizada, projetada especificamente para executar Large Language Models (LLMs) com máxima eficiência em CPUs. Antes do llama.cpp, executar um LLM geralmente exigia uma GPU de ponta com muita VRAM. Llama.cpp nos permite usar CPUs para executar esses modelos. Nesta demonstração, implantaremos o modelo com suporte de CPU, portanto, faremos uso do llama.cpp.

Criado pela equipe llama.cpp, GGUF (GPT-Generated Unified Format) é um formato binário projetado para carregamento rápido de modelos e inferência eficiente em CPU. A conversão de SafeTensors para GGUF aplica quantização, o que reduz o tamanho do modelo e o consumo de memória, preservando a maior parte da qualidade do modelo. Assim, para melhorar o desempenho do modelo em CPUs, converteremos o modelo do formato Safetensor para GGUF.

Nota: Embora estejamos usando um modelo Hugging Face armazenado no formato SafeTensors, modelos no formato GGUF também estão disponíveis diretamente, caso em que esta etapa de quantização pode ser completamente ignorada.

Clone llama.cpp e instale suas dependências Python:

Primeiro, converta o modelo Hugging Face SafeTensors para o formato GGUF. Escolhemos o outtype como f16 (float de 16 bits) de precisão, pois f16 (meia precisão) é como a maioria dos modelos do Hugging Face são armazenados e preserva quase toda a inteligência original do modelo. Outras opções disponíveis são f32 (precisão máxima, mas tamanho de arquivo enorme), vf16, q8_0, auto e tq2_0.

Como você pode ver, o arquivo GGUF tem o mesmo tamanho (2.1 GB) que o arquivo SafeTensors. Uma vez que o modelo esteja disponível no formato GGUF, quantizamos o GGUF f16 para Q4_K_M usando a ferramenta llama-quantize para reduzir os pesos do modelo e o tamanho do arquivo:

Como você pode ver na captura de tela, o tamanho de cada peso do modelo é reduzido através do processo de quantização e nosso arquivo SafeTensors inicial de 2.1 GB foi convertido em um arquivo GGUF de aproximadamente 636 MB. Você pode excluir o arquivo f16 intermediário depois.

Após a conversão, o diretório contém tanto os arquivos originais do Hugging Face quanto o arquivo GGUF:

Você pode verificar se o arquivo GGUF funciona executando-o localmente com llama.cpp:

Etapa 3: Empacotar e Enviar o Modelo para o Harbor

Em seguida, pegamos os arquivos do modelo e os empacotamos como artefatos OCI para o Harbor. Aqui demonstramos duas abordagens de empacotamento. Cada uma produz um artefato OCI válido que o Harbor armazena e serve de forma idêntica. Escolha a abordagem que melhor se adapta ao fluxo de trabalho da sua equipe.

Opção A: Usando ORAS

ORAS oferece o maior controle sobre a estrutura do manifest OCI. Instale a CLI ORAS usando a documentação de instalação oficial. Autentique-se com o Harbor e, em seguida, envie os arquivos do modelo com annotations de metadados:

Analisando isso:

• harbor.example.com/ml-models/tinyllama:v1.0.0-gguf: A referência completa do artefato: registry/project/repository:tag
• --artifact-type: Declara isso como um artefato de modelo CNAI, não uma imagem de container.
• --annotation: Anexa metadados do modelo seguindo a convenção da especificação de modelo CNAI.
• Cada arquivo é listado com um media type explícito (file:mediaType), para que registries e clientes saibam como interpretar cada layer.

Podemos ver o modelo refletido na UI do Harbor como um artefato OCI:

[Imagem da UI do Harbor mostrando o artefato OCI]

Opção B: Usando KitOps

KitOps adota uma abordagem declarativa. Crie um Kitfile em seu diretório de projeto usando o comando kit init para gerar automaticamente o arquivo para o modelo:

Nota: Antes de executar "kit init", limpe o diretório removendo arquivos que você não deseja empacotar. O auto-scanner incluirá tudo, e se você deixar os pesos SafeTensors originais (~2.2 GB) e o GGUF f16 intermediário (~2.2 GB) junto com seu GGUF quantizado (~670 MB), o artefato resultante terá ~4.7 GB em vez de ~670 MB.

Em seguida, empacote e envie:

Podemos verificar o mesmo na UI do Harbor:

[Imagem da UI do Harbor mostrando o artefato OCI do KitOps]

Verificando no Harbor

Independentemente da ferramenta que você usou, navegue até a UI do Harbor. No projeto "ml-models", você verá o repositório "tinyllama" com a tag v1.0.0-gguf. A visualização de artefatos de modelo do Harbor exibirá as annotations (arquitetura, tamanho do parâmetro, formato) e listará os arquivos individuais no artefato.

OPERAÇÕES DO CICLO DE VIDA DO MODELO NO HARBOR

Uma vez que seu modelo esteja no Harbor, você tem acesso a todo o conjunto de operações do registry:

• Versionamento: Envie novas versões com novas tags (v1.1.0, v2.0.0). Versões anteriores permanecem imutáveis e podem ser puxadas. Isso se aplica independentemente da ferramenta (ORAS, KitOps) usada para enviar. O Harbor versiona artefatos OCI da mesma forma que versiona imagens de container.
• Replicação: Configure regras de replicação para sincronizar automaticamente modelos entre instâncias do Harbor, útil para promover modelos de um registry de staging para produção, ou distribuir modelos para locais de borda.
• Replicação do Hugging Face: O Harbor suporta replicação do Hugging Face como uma fonte upstream, permitindo que você espelhe modelos públicos em seu registry privado com controle de acesso e varredura.
• Políticas de retenção: Limpe automaticamente versões antigas de modelos com base em regras (por exemplo, mantenha as últimas 5 versões, exclua artefatos com mais de 90 dias).
• Controle de acesso: Use o RBAC do Harbor para controlar quem pode enviar modelos (cientistas de dados, pipelines de CI) versus quem pode puxá-los (sistemas de implantação, equipes específicas).
• Log de auditoria: Cada ação de push, pull e administrativa é registrada, fornecendo a rastreabilidade que as equipes de conformidade e governança exigem.

CONCLUSÃO

Em resumo, o ecossistema de containers passou anos construindo uma infraestrutura robusta para empacotar, distribuir e implantar artefatos de software. A extensibilidade da especificação OCI significa que os modelos de IA agora podem aproveitar essa mesma infraestrutura com a mesma segurança, governança e maturidade operacional.

O Harbor, como um registry graduado da CNCF, está particularmente bem posicionado para essa função. Suas capacidades de multi-tenancy, RBAC, replicação e varredura atendem aos requisitos de segurança e conformidade que as implantações de IA corporativas exigem. E como os modelos são armazenados como artefatos OCI padrão, todo o ecossistema de ferramentas compatíveis com OCI — ORAS, KitOps e outras — funciona de forma intercambiável.

Siga nossa série de blogs sobre Harbor:

• Blog 1 – Harbor: Seu Registry de Container Empresarial para uma Nuvem Privada Moderna
• Blog 2 – Reduzindo a Complexidade da Implantação do Harbor no Kubernetes
• Blog 3 – Tornando o Harbor Pronto para Produção: Considerações Essenciais para Implantação
• Blog 4 – Integrando o VMware Data Services Manager com o Harbor para um Registry Pronto para Produção
• Blog 5 – Usando o Harbor como Proxy Cache para Registries Baseados em Nuvem
• Blog 6 – Protegendo Sua Cadeia de Suprimentos de Software com o Harbor
• Blog 7 – Implementando Replicação Cross-Region com o Harbor no VMware Cloud Foundation

Descubra mais no Blog VMware Cloud Foundation (VCF).

Assine para receber as últimas publicações por e-mail.

Digite seu e-mail… Assinar