Server com Docker: início rápido

Execute na raiz de um checkout completo e escolha uma única pilha Compose. CPU é o caminho mais simples e publica a porta 18097. CUDA publica 18098 e exige Driver compatível e NVIDIA Container Toolkit; não instale CUDA ou cuDNN no host para este contêiner.

Os comandos usam de propósito --accept-license sem interação e verificam buffalo_l logo depois. Execute somente após sua organização revisar e aceitar os termos. O instalador também aceita buffalo_m, buffalo_sc e antelopev2.

O código-fonte do Server e o SDK Python usam a licença MIT, mas arquivos e pesos de modelos não são cobertos por ela. Os pacotes públicos do InsightFace, incluindo buffalo_l, em geral se limitam à pesquisa acadêmica não comercial sem autorização comercial separada do InsightFace; auto-hospedar não concede direitos comerciais.

A instalação grava manifest.json e MODEL.LICENSE assinado em server/.models. verify valida identidade, assinatura, validade e autorização atual. A licença identifica modelo e uso permitido; é uma credencial de conformidade, não DRM nem checksum dos arquivos.

Inicie apenas a pilha instalada. Abra http://SERVER:18097/ para CPU ou http://SERVER:18098/ para CUDA. Depois de health, confira em Dashboard ou System se serviço, banco, modelo e execution provider estão prontos antes de cadastrar.

CUDA deve informar CUDAExecutionProvider. A inicialização valida GPU, Driver, CUDA/cuDNN/ONNX Runtime, sessões reais do detector e reconhecedor, placement do provider e warm-up. Em caso de falha, encerra em vez de voltar silenciosamente à CPU.

Em Collections, crie um ID estável como employees. Escolha um perfil anunciado por System, defina capacity conforme a memória e comece no threshold cosseno bruto padrão 0,4. A Collection fica vinculada à identidade e digest do modelo, dimensão, pré-processamento e perfil de detecção.

Em People, selecione a Collection e cadastre uma Person com uma ou mais imagens JPEG, PNG ou WebP nítidas. standard review é um bom começo: exige exatamente um rosto utilizável e verifica tamanho, confiança, nitidez, brilho e pose. Lotes aceitam sucesso parcial; examine cada motivo de rejeição.

Em Search, escolha a mesma Collection e envie outra foto da Person. Resultados são ordenados por similaridade cosseno bruta e a nota da Person é a maior entre os FaceSamples. Similaridade não é probabilidade. Nenhum match retorna corretamente uma lista vazia.

Os arquivos Compose desativam autenticação para avaliação isolada. Antes do acesso por outras pessoas ou redes, ative-a, coloque uma chave API longa e aleatória no ambiente secreto e reinicie a pilha escolhida. A Web UI pode manter a chave apenas na memória da aba atual.

Termine HTTPS em reverse proxy confiável, permita apenas origins necessários em vez de CORS amplo, imponha limites de taxa, corpo e tempo e restrinja Docker, /data, /models e backups. Nunca registre imagens, embeddings, credenciais RTSP ou chaves.

SQLite em /data é a fonte durável; índices exatos em memória são descartáveis. Compose monta modelos como somente leitura e guarda /data em volume nomeado. Faça backup conjunto do SQLite e dos crops com escritas paradas ou snapshot seguro para SQLite.

Use o comando down completo da pilha iniciada. down normal remove contêineres e rede, mas preserva o volume. Nunca acrescente -v: docker compose down -v exclui permanentemente o volume de dados.

Comece por health e examine System, status do contêiner e logs da pilha. Em CUDA, a falha de início é intencional se Driver, GPU, sessões, CUDAExecutionProvider, auditoria ou warm-up falharem; não existe retorno silencioso à CPU.

Toda resposta leva x-request-id e erros incluem request_id. Guarde-o com os logs correspondentes. 401 unauthorized costuma indicar chave ausente ou girada; 409 collection_model_mismatch, outro contrato; 422 face_not_found, nenhum rosto utilizável.