InsightFace Server com Docker: início rápido

Execute um dos blocos na raiz do repositório. O ficheiro Compose incluído é usado diretamente e determina a imagem a transferir. Se já tiver o repositório atualizado, ignore git clone.

Abra http://SERVER:18097/ para CPU ou http://SERVER:18098/ para CUDA 12. --accept-license aceita os termos do modelo; leia-os antes de executar o comando.

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, WebP ou BMP 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.

Numa instalação nova, acrescente --enable-liveness ao comando de instalação do modelo. Os modelos necessários são verificados e a ativação é guardada antes do primeiro arranque.

Num serviço em execução, use o comando correspondente abaixo e reinicie depois. A instalação normal e models addons install liveness não ativam a funcionalidade.

Reinicie o serviço após uma instalação bem-sucedida. up -d por si só não recarrega os ajustes de um contentor existente. A funcionalidade está desativada por predefinição; o registo tem o ajuste separado liveness_on_registration.

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.

São suportados buffalo_l, buffalo_m, buffalo_s, buffalo_sc, antelopev2, raccoon_s e raccoon_l. O Server usa apenas deteção e reconhecimento do Raccoon, sem o verificador do PrivateFrame. Mudar de modelo exige uma Collection compatível e novo registo ou migração dos dados.

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.

Mantenha /data, modelos e server/config persistentes. Copie SQLite e os recortes em conjunto sem escritas, ou use um instantâneo seguro para SQLite. Proteja-os como dados biométricos e ative autenticação por chave API e HTTPS antes de expor o serviço.

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.

Ambos os contentores usam root (0:0), uma única montagem /models gravável e um diretório de configuração gravável. Os diretórios de modelos e addons/ são criados conforme necessário. Não é preciso fornecer UID/GID do anfitrião nem ajustar permissões. O sistema de ficheiros raiz do contentor continua só de leitura.

Pare as escritas e faça uma cópia da base de dados e dos recortes. Atualize os ficheiros de implementação e integre os seus ajustes, preservando server/config/server.toml, modelos, nomes originais do projeto e volume, portas e chave API. Use o ficheiro Compose correspondente e acrescente os ficheiros de personalização e o nome do projeto quando necessário.

Transfira ambas as imagens e recrie o Server. restart não aplica novas imagens nem montagens. Verifique estado, fornecedor de execução, dados existentes e uma pesquisa conhecida. O mesmo modelo e contrato de embeddings preservam as amostras; mudar de modelo exige uma migração separada. Atualize também o SDK a partir do mesmo repositório atualizado.

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.

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.