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 tarefa | Conceito HF | Biblioteca | Arquivo de referência |
|---|---|---|---|
| Classificação de texto | AutoModelForSequenceClassification | transformers | references/text-classification.md |
| Classificação de tokens (NER) | AutoModelForTokenClassification | transformers | references/token-classification-ner.md |
| Embeddings de texto | modelo de embedding de sentença | sentence-transformers | references/embeddings.md |
| Geração de imagem | pipeline de difusão | diffusers | references/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 comuvicornem 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 emlocalhost. 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 a0.0.0.0ou 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ó executepip installou inicieuvicornvocê 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>-apino
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ão8000).
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_familyretornar 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 omodel_idestá errado/com erro de digitação, ou o repositório é fechado/privado. Não é possível
dizer qual. Primeiro reconfirme omodel_idexato 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 — vejareferences/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 middleware413emmain.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.pyretornatask_family: unknown: os metadados do repositório estão incompletos. Pergunte
ao usuário diretamente qual das quatro famílias é, e passe--taskexplicitamente 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 dereferences/architecture.mdem vez de forçá-lo
a um dos quatro arquivos de referência. - A instalação do
requirements.txtgerado é lenta/enorme:torchediffuserssão grandes; avise o
usuário antes de executarpip installse a família de tarefas os puxar.