Communitygithub.com

Habilidades para Servir Modelos de ML

Uma coleção de Habilidades de Agente para servir modelos de machine learning, do backend de API ao frontend.

O que é Habilidades para Servir Modelos de ML?

Esta habilidade permite que um agente de IA (como Claude Code, Cursor, etc.) construa automaticamente um projeto FastAPI completo e profissional para servir um modelo do Hugging Face localmente. Ela suporta quatro famílias de tarefas principais: classificação de texto, classificação de tokens (NER), embeddings de texto e geração de imagens. O agente inspeciona o modelo, lê arquivos de referência específicos para a tarefa e gera uma estrutura de projeto bem organizada com código de inicialização do modelo otimizado, pontos de extremidade de inferência validados, tratamento de erros, health checks e bateladas com limites explícitos. O escopo é estritamente local, sem Docker, Kubernetes ou frontend. A habilidade prioriza a segurança e a usabilidade, adicionando limites de tamanho de entrada e custo, e evitando expor o serviço além do localhost sem autenticação adicional. O resultado é um projeto que o usuário pode executar com `uvicorn`, com instruções claras e testes, permitindo uma implementação rápida e confiável de APIs de ML.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add nynuz/ml-serving-skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Construtor FastAPI a partir de Modelo HF

O que esta habilidade faz

Pega um model_id do Hugging Face e gera um projeto FastAPI autossuficiente, local e de nível profissional
em torno dele: estrutura de aplicação em camadas, modelo carregado uma vez na inicialização (nunca por requisição), um
ponto de extremidade de inferência adequado à tarefa, batelada com limites explícitos, validação de entrada/saída,
health e readiness probes, tratamento estruturado de erros e scripts opcionais de avaliação/benchmark.

Ela suporta quatro famílias de tarefas, cada uma com uma forma de endpoint e biblioteca subjacente diferentes:

Família de tarefaConceito HFBibliotecaArquivo de referência
Classificação de textoAutoModelForSequenceClassificationtransformersreferences/text-classification.md
Classificação de tokens (NER)AutoModelForTokenClassificationtransformersreferences/token-classification-ner.md
Embeddings de textomodelo de embedding de sentençasentence-transformersreferences/embeddings.md
Geração de imagempipeline de difusãodiffusersreferences/image-generation.md

Limites de escopo — leia isto antes de começar

  • Apenas local. Sem Docker, sem Kubernetes, sem implantação em nuvem (Railway, AWS, etc.). A saída
    é um projeto que o usuário executa com uvicorn em sua própria máquina.
  • Apenas backend. Nunca gere código de frontend/cliente (React, Next.js, chamadas fetch, etc.). Se o
    usuário quiser uma UI para chamar a API, diga que isso é uma preocupação separada e pare no limite da API.
    É permitido habilitar CORS local permissivo para que um servidor de desenvolvimento frontend possa chamar a API mais tarde —
    isso é uma preocupação de configuração do backend, não código de frontend.
  • Servir, não treinar. Se o usuário quiser fine-tune ou treinar um modelo, esta habilidade é a
    ferramenta errada — diga isso.
  • Modelo de ameaça local e de usuário único. Os serviços gerados NÃO têm autenticação e NÃO têm limite
    de taxa por design — eles são feitos para rodar em localhost. Eles impõem limites de custo de entrada (tamanho
    do lote, comprimento por string, parâmetros de geração e um limite de tamanho do corpo da requisição → 413). Sempre diga
    ao usuário para não vincular o serviço a 0.0.0.0 ou expô-lo além do localhost sem primeiro adicionar autenticação,
    limite de taxa e uma política de CORS reforçada — esses estão fora do escopo aqui.
  • Não instale ou inicie nada sem perguntar. Estruture o projeto e dê ao usuário os comandos exatos
    para executar. Só execute pip install ou inicie uvicorn você mesmo se o usuário explicitamente pedir
    para verificar se funciona — algumas dessas dependências (torch, diffusers) são downloads grandes.

Fluxo de trabalho

Etapa 1: Coletar entradas

Você precisa:

  • model_id (obrigatório) — o ID do Hugging Face Hub, ex.: distilbert-base-uncased-finetuned-sst-2-english.
  • Diretório de saída (pergunte se não for fornecido, caso contrário, padrão ./<model-name-slug>-api no
    diretório de trabalho atual).
  • Opcional: um caminho para um pequeno conjunto de dados de avaliação rotulado (para avaliação de corretude mais tarde), uma porta
    (padrão 8000).

Se o usuário apenas descrever o que fez em um notebook ("Eu carrego com pipeline(...), ele
classifica sentimento"), peça o model_id exato se não foi informado — tudo a jusante
depende disso.

Etapa 2: Inspecionar o modelo

Execute o inspetor incluído — ele só acessa a API pública do HF Hub, nunca baixa os pesos do modelo:

python scripts/inspect_model.py <model_id>

Ele imprime JSON com task_family, pipeline_tag, library_name, architectures, id2label (se
disponível), num_labels, uma contagem aproximada de parâmetros e uma nota de recomendação de dispositivo.

  • Se task_family retornar como uma das quatro famílias suportadas, prossiga.
  • Se retornar "unknown" ou você discordar do palpite (alguns repositórios têm metadados ausentes/errados),
    pergunte ao usuário qual das quatro famílias de tarefas se aplica — não adivinhe silenciosamente errado,
    a forma de todo o endpoint depende disso.
  • Se o script relatar not_found_or_gated, a API pública do HF retornou 401/403/404 — isso significa
    que o model_id está errado/com erro de digitação, ou o repositório é fechado/privado. Não é possível
    dizer qual. Primeiro reconfirme o model_id exato com o usuário (erros de digitação e namespaces de organização errados são
    a causa mais comum); só se estiver confirmado como correto, trate como fechado e peça ao usuário
    para aceitar a licença na página do modelo e autenticar. Prefira passar o token através da variável de ambiente
    HF_TOKEN (HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>) ou
    huggingface-cli login — evite a flag --token, pois um token na linha de comando vaza para
    o histórico do shell e a lista de processos.

Etapa 3: Ler o arquivo de referência correspondente

Antes de estruturar, leia references/<task-family>.md para a família de tarefas da Etapa 2. Ele contém
o código exato de carregamento do pipeline/modelo, o esquema de requisição/resposta e peculiaridades específicas da tarefa
(ex.: mapeamento de rótulos para classificação, agregação de entidades para NER, estratégia de pooling para embeddings,
codificação de imagem para geração). Leia também references/architecture.md uma vez por sessão — ele cobre
as partes que são idênticas em todas as quatro famílias de tarefas (carregamento lifespan, health probes, CORS,
tratamento de erros) para que você não tenha que redescobri-las cada vez.

Use a habilidade transformers-huggingface já instalada para tudo sobre carregamento de modelo,
tokenização, posicionamento de dispositivo (CPU/CUDA/MPS) ou escolha de dtype que surgir além do que o
arquivo de referência cobre — ela tem os padrões autorizados para a biblioteca transformers.

Etapa 4: Estruturar o projeto

Execute o gerador com a família de tarefas e qualquer informação de rótulo/config obtida na Etapa 2:

python scripts/scaffold_project.py \
  --model-id "<model_id>" \
  --task <text-classification|token-classification|embeddings|image-generation> \
  --output-dir "<output_dir>" \
  --id2label-json "<caminho-para-json-ou-json-inline>"   # opcional, apenas classificação/NER

Execute python scripts/scaffold_project.py --help para ver todas as flags (porta, tamanho máximo do lote, comprimento máximo
de entrada / tamanho da imagem, etc.) — passe qualquer coisa relevante que você aprendeu na Etapa 2 em vez de
manter os padrões gerados se você tiver valores melhores.

Isso produz:

<output_dir>/
├── app/
│   ├── main.py            # FastAPI() + lifespan (carregar modelo uma vez, aquecer), CORS, montagem de rota
│   ├── core/
│   │   ├── config.py      # pydantic-settings: MODEL_ID, DEVICE, MAX_BATCH_SIZE, etc. do ambiente
│   │   └── model.py       # load_model() / função de inferência para a família de tarefas escolhida
│   ├── api/
│   │   └── routes.py      # endpoint da tarefa + /health/live + /health/ready + /v1/info
│   └── schemas.py         # Modelos de requisição/resposta Pydantic com restrições Field
├── tests/
│   ├── test_health.py
│   └── test_inference.py  # caminho feliz + um caso de erro de validação
├── requirements.txt       # apenas o que esta família de tarefas precisa
├── .env.example
├── README.md              # instruções de execução, documentação do endpoint, nota de CORS
└── .gitignore

O estruturalista preenche o que pode determinar programaticamente (id do modelo, família de tarefas, rótulos se
você os passou). Você ainda precisa revisar app/core/model.py e
app/schemas.py gerados
em comparação com o arquivo de referência da Etapa 3 — o estruturalista não chama o modelo,
então não pode saber coisas como o conjunto exato de rótulos se você não passou --id2label-json, ou se um
modelo NER precisa de aggregation_strategy="simple". Preencha quaisquer marcadores # TODO que ele deixar.

Etapa 5: Verificar as preocupações transversais de produção

Cada projeto gerado deve ter todos estes — verifique-os explicitamente, é fácil deixá-los cair silenciosamente
ao editar manualmente o código gerado:

  • Modelo carregado no lifespan, não no momento da importação ou por requisição (app/main.py)
  • Uma chamada de aquecimento (uma inferência dummy) logo após o carregamento, para que a primeira requisição real não seja
    a lenta — veja references/architecture.md
  • /health/live (processo ativo, sem verificações de dependência) é uma função diferente de
    /health/ready (verifica se o modelo está carregado) — confundi-las causa cascatas de reinicialização, veja
    references/architecture.md
  • Cada resposta de inferência inclui o id/versão do modelo — inegociável, é como você depura
    "qual modelo produziu isso" mais tarde
  • A entrada do lote tem um comprimento/tamanho máximo imposto pelo servidor (Field(..., max_length=...)) — um lote
    ilimitado é um gasto ilimitado de GPU/CPU. O estruturalista também limita cada string individual
    (StringConstraints(max_length=...), ajuste com --max-chars-per-text) e rejeita corpos de requisição muito grandes
    através de um middleware 413 em main.py (--max-request-mb) — verifique se ambos sobreviveram a qualquer
    edição manual, já que a verificação de tamanho do corpo é a única proteção que dispara antes de o payload ser
    analisado na memória
  • Inferência vinculada a CPU/GPU é executada via anyio.to_thread.run_sync(...), nunca diretamente em um manipulador
    async def — caso contrário, bloqueia o loop de eventos para todas as outras requisições em andamento
  • Erros de validação retornam 422 com uma mensagem útil; erros de modelo/tempo de execução são capturados e mapeados para
    um erro HTTP tipado, nunca um 500 não tratado com um stack trace vazando para o cliente

Veja references/batching.md para o padrão de lote-array usado por padrão e quando (raramente, para uma
configuração local de usuário único) o micro-batch dinâmico valeria a complexidade adicional.

Etapa 6: Testes

O estruturalista gera tests/test_health.py e tests/test_inference.py usando
fastapi.testclient.TestClient (veja references/testing-and-evaluation.md). Leia-os,
ajuste a entrada de amostra / forma esperada para corresponder ao modelo real e diga ao usuário para executar:

pytest

Etapa 7: Avaliação e benchmark (opcional, apenas se o usuário quiser)

Dois scripts independentes estão incluídos — copie-os para o diretório do projeto gerado (eles não
fazem parte do aplicativo FastAPI em si, são ferramentas que chamam o servidor em execução):

  • scripts/evaluate.py — corretude: executa um conjunto de dados rotulado (CSV/JSONL) contra a API em execução
    e relata acurácia/F1 (classificação, NER) ou verificações de sanidade de similaridade de cosseno (embeddings).
    Precisa dos dados rotulados do usuário — peça um caminho, ou pule isso se eles ainda não tiverem um.
  • scripts/benchmark.py — desempenho: dispara requisições concorrentes na API em execução e relata
    latência p50/p95/p99 e throughput. Não precisa de dados rotulados, apenas algumas entradas de exemplo.

Veja references/testing-and-evaluation.md para uso exato e como interpretar a saída.

Etapa 8: Finalização

Dê ao usuário os comandos exatos para executar localmente:

cd <output_dir>
python -m venv .venv && source .venv/bin/activate   # ou .venv\Scripts\activate no Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Aponte-os para /docs para teste interativo (UI OpenAPI automática do FastAPI). Diga explicitamente
o que você não fez: sem imagem Docker, sem implantação em nuvem, sem código de frontend. Se eles quiserem
qualquer um desses em seguida, isso está fora desta habilidade.

Solução de problemas

  • inspect_model.py retorna task_family: unknown: os metadados do repositório estão incompletos. Pergunte
    ao usuário diretamente qual das quatro famílias é, e passe --task explicitamente para o estruturalista.
  • Modelo precisa de trust_remote_code=True / código personalizado: sinalize isso ao usuário antes de estruturar
    — significa que código arbitrário do Hub será executado localmente; obtenha confirmação explícita antes de gerar um
    projeto que defina essa flag.
  • Usuário quer uma família de tarefas que não está na tabela (ex.: fala, tradução, VQA): diga claramente que
    esta habilidade atualmente cobre apenas as quatro famílias listadas, e ofereça-se para construir o wrapper FastAPI
    manualmente usando os mesmos padrões arquiteturais de references/architecture.md em vez de forçá-lo
    a um dos quatro arquivos de referência.
  • A instalação do requirements.txt gerado é lenta/enorme: torch e diffusers são grandes; avise o
    usuário antes de executar pip install se a família de tarefas os puxar.

Habilidades Relacionadas