Intermediário 12 minPlano diário

Immich: pesquisar suas fotos com uma IA locale

Folhas de papel estão espalhadas ao lado de um notebook sobre uma mesa de madeira.

O Immich, a alternativa auto-hospedada ao Google Fotos, permite encontrar uma foto digitando uma descrição ("cachorro na praia", "bolo de aniversário") em vez de um nome de arquivo. Essa pesquisa de fotos com IA se baseia em um modelo CLIP que roda no seu servidor, no contêiner de machine learning do Immich. Este guia explica como ela funciona, como escolher um modelo multilíngue para pesquisar em francês, quais erros observar e o que realmente sai da sua rede. O procedimento descrito segue a documentação oficial; ele não foi reproduzido em uma instância de teste para este guia.

Por Mohamed Meguedmi·Atualização 2026-11-21·Testado no Windows, macOS e Linux

#Pesquisa de fotos com IA no Immich: o princípio

O recurso se chama Smart Search na documentação do Immich ("pesquisa inteligente" ou pesquisa por contexto na interface). Ele não lê suas fotos em tempo real no momento da consulta. Ele se baseia em duas operações distintas, ambas a cargo do serviço immich-machine-learning.

  1. 01
    Indexação das imagens
    Para cada foto, o codificador de imagens do modelo CLIP calcula um vetor numérico (um embedding) que resume seu conteúdo visual. Esse vetor é armazenado no banco de dados do Immich. Esse é o trabalho da tarefa "Smart Search" visível na administração; em uma fototeca grande, ela pode demorar bastante.
  2. 02
    Codificação da consulta
    Quando você digita uma frase, o codificador de texto do mesmo modelo a transforma, por sua vez, em um vetor.
  3. 03
    Comparaison
    O Immich retorna as fotos cujo vetor está mais próximo do vetor da sua frase. Não há geração de texto nem "compreensão" no sentido de um chatbot: é uma busca por similaridade em um espaço comum de imagens e texto.

Consequência direta: o texto e as imagens precisam ter sido codificados pelo mesmo modelo. Se você trocar de modelo, todas as fotos precisam ser reindexadas; caso contrário, os vetores antigos e novos deixam de ser comparáveis.

#O CLIP não é um assistente de visão

O kit completo para criar o seu próprio assistente de IA.

Aproveite a nossa experiência e um percurso guiado para criar o seu assistente local e usar a sua IA no dia a dia.

  • Espaço online vitalício
  • PDF + arquivos
  • Reembolsado em 30 dias

É comum confundir a pesquisa CLIP do Immich com os modelos de "visão" que rodamos com Ollama (Qwen3-VL, Gemma etc.). São duas ferramentas diferentes, que atendem a duas necessidades diferentes.

O que o CLIP faz no Immich
Classificar suas fotos por proximidade com uma frase. O resultado é uma lista de imagens ordenadas, não uma resposta redigida. O modelo é pequeno e a indexação é feita uma vez; depois, a busca é rápida.
O que um assistente de visão faz
Descrever uma imagem, responder a uma pergunta sobre o conteúdo dela, ler texto (OCR), comparar duas imagens. Ele gera texto, imagem por imagem, e custa muito mais em processamento e memória.
O que o CLIP não sabe fazer
Responder a « quantas pessoas há nesta foto? », descrever uma cena, ler de forma confiável um documento fotografado ou contar. Ele fornece uma pontuação de semelhança, nada mais.
O que o Immich não integra nativamente
Um LLM de visão que escreveria legendas ou conversaria com a sua fototeca. Existem projetos de terceiros, mas eles não fazem parte do Immich e não são abordados aqui.

Se você precisa encontrar “a foto do quadro branco de terça-feira”, o CLIP muitas vezes basta. Se você precisa extrair o texto desse quadro ou resumi-lo, é preciso um modelo de visão, por exemplo via Ollama, em uma imagem que você envia explicitamente para ele.

#Pré-requisitos

Uma instância do Immich funcionando
Instalada com o docker-compose.yml oficial, que inclui o serviço immich-machine-learning. Se você o removeu do seu arquivo compose, a busca inteligente não vai funcionar.
Uma conta de administrador
A escolha do modelo e a execução das tarefas de indexação são feitas na administração do servidor.
Memória e tempo
Um modelo CLIP maior exige mais RAM e indexa mais devagar. Não publicamos números de duração: eles dependem do modelo, da quantidade de fotos, da CPU ou da GPU, e não temos nenhuma medição documentada para lhe fornecer.
Aceleração de hardware (opcional)
O Immich documenta aceleração do machine learning (CUDA para NVIDIA, OpenVINO para Intel, ROCm para AMD, ARM NN e RKNN para algumas placas ARM). Ela não é obrigatória: a CPU basta, só que mais devagar.
Um backup recente
Trocar de modelo não mexe nos seus arquivos, mas reexecutar tarefas pesadas em um servidor doméstico é um bom momento para verificar se o backup do banco de dados e dos originais está em dia.

Para verificar se o serviço de machine learning está rodando, a partir da pasta que contém o seu docker-compose.yml:

Terminal — status e logs do contêiner de ML
# Lister les services Immich et leur état
docker compose ps

# Suivre les journaux du service de machine learning
docker compose logs -f immich-machine-learning

#Ativar a busca de fotos com IA e escolher um modelo multilíngue

O modelo padrão indicado pela documentação do Immich é o ViT-B-32__openai, um CLIP treinado principalmente com legendas em inglês. Ele funciona, mas uma consulta em francês geralmente dá resultados menos relevantes do que a mesma consulta em inglês. A documentação recomenda usar um modelo multilíngue se você pesquisa em um idioma diferente do inglês.

  1. 01
    Abrir as configurações de machine learning
    No Immich, abra Administração, depois Configurações e então a seção Machine Learning. Verifique se o machine learning está ativado e se a URL do serviço aponta de fato para o seu contêiner (por padrão, o serviço immich-machine-learning do arquivo compose).
  2. 02
    Escolher o modelo CLIP
    Na subseção Smart Search, substitua o nome do modelo. Os modelos oferecidos são publicados pela equipe do Immich no Hugging Face, e a documentação remete a uma lista que indica, para cada um, seu tamanho, seus requisitos de memória e se é multilíngue. Entre as famílias multilíngues citadas estão nllb-clip (por exemplo, nllb-clip-base-siglip__v1, nllb-clip-large-siglip__v1) e XLM-Roberta (por exemplo, XLM-Roberta-Large-Vit-B-16Plus). Copie o nome exato da lista oficial: um erro de digitação impede o download.
  3. 03
    Gravar
    Na próxima vez que for necessário, o contêiner de ML baixa o modelo do Hugging Face e o mantém em cache (volume model-cache do compose oficial). Por isso, a primeira chamada pode ser lenta ou falhar se o servidor não tiver acesso à Internet.
  4. 04
    Reexecutar a indexação de toda a fototeca
    Em Administration, abra as tarefas (Jobs). Na linha Smart Search, execute o processamento em todas as fotos (« All »), e não apenas nas que estão faltando (« Missing »): os vetores calculados com o modelo antigo não são mais compatíveis. Acompanhe o andamento na mesma página e nos logs do contêiner.
  5. 05
    Testar com algumas consultas conhecidas
    Escolha três ou quatro fotos cujo conteúdo você conhece, pesquise-as em francês e verifique se elas aparecem nos resultados. Esse é o seu único teste de verdade: a relevância depende da sua biblioteca de fotos, e não podemos garanti-la a distância.
!
Enquanto a reindexação não terminar, os resultados ficam inconsistentes
Durante o processamento, parte das fotos tem vetores do novo modelo e a outra parte, do antigo. Os resultados podem parecer ruins ou incompletos. Aguarde o fim da tarefa Smart Search antes de avaliar um modelo.

Qual modelo escolher? A documentação não aponta um « melhor » modelo universal. O trade-off é o clássico: um modelo maior (variantes large) promete mais relevância, mas consome mais memória e indexa mais devagar; um modelo base é mais leve. Em um servidor pequeno ou em um NAS sem GPU, comece com uma variante base multilíngue; se a relevância decepcionar e a máquina tiver folga, experimente uma variante maior, sabendo que será preciso reindexar tudo.

i
Idioma da consulta e modelos NLLB
Os modelos nllb-clip se baseiam em um codificador de texto multilíngue que leva em conta o idioma da consulta. Segundo a documentação, o Immich usa o idioma configurado na interface para esses modelos. Portanto, mantenha a interface em francês se você pesquisa em francês. Esse comportamento pode mudar de uma versão para outra: confira a página "Searching" da documentação da sua versão.

#Pesquisar suas fotos em francês

Depois que a indexação terminar, a busca é feita pela barra de pesquisa do aplicativo web ou mobile. Dependendo da versão, a interface oferece vários tipos de busca: contexto (a busca CLIP), nome do arquivo, descrição e, nas versões recentes, texto reconhecido por OCR. Para uma busca por descrição, mantenha o modo contexto.

Descreva o que aparece na imagem
“bicicleta vermelha encostada em um muro”, “pôr do sol no mar”, “criança soprando velinhas”. O CLIP reage a objetos, cenas, cores, atmosferas.
Evite o que a imagem não mostra
“férias de 2019 na casa do Paul” não corresponde a nada visível. Para data, local ou pessoa, use os filtros.
Combine com os filtros
O painel de filtros permite restringir por pessoas (reconhecimento facial, outra função do mesmo contêiner de ML), local, câmera, datas e tipo de mídia. Uma consulta curta com dois filtros costuma ser melhor do que uma frase longa.
Reformulez
Se "gato" der resultados demais, seja mais específico: "gato preto dormindo em um sofá". Se nada aparecer, simplifique. Teste também em inglês: se o inglês funcionar nitidamente melhor, seu modelo provavelmente é monolíngue.
Não confunda com a busca por texto
O modo de contexto não lê o texto das fotos. Para encontrar uma captura de tela pelo conteúdo escrito, use a pesquisa por OCR, se a sua versão oferecer, ou a pesquisa por nome de arquivo ou descrição.

Os resultados são ordenados por similaridade e não há um limiar de “corresponde / não corresponde”: a busca sempre retorna algo, mesmo para uma consulta absurda. Os primeiros resultados são os mais próximos; quanto mais você desce, menos relevantes eles são.

#Privacidade: o que fica com você

Esse é o principal argumento a favor de uma pesquisa de fotos com IA auto-hospedada, mas ele merece ser formulado com precisão. Este guia descreve a arquitetura documentada; ele não constitui uma auditoria da sua instalação e não garante que nenhum dado saia da sua rede.

Os cálculos
Na configuração oficial, a codificação das fotos e das consultas é feita pelo contêiner immich-machine-learning, na sua máquina. Os embeddings são armazenados no seu banco de dados PostgreSQL.
O download dos modelos
Os pesos dos modelos são baixados do Hugging Face no primeiro uso. Esse tráfego de saída é normal; ele não contém suas fotos. Depois que o modelo está em cache, ele não é baixado novamente enquanto você mantiver o volume.
Um ML remoto
A URL do serviço de machine learning é configurável: você pode rodar o contêiner de ML em outra máquina (um PC com GPU, por exemplo). Nesse caso, suas fotos trafegam até essa máquina. Mantenha-a na sua rede local ou atrás de uma VPN, nunca exposta diretamente na Internet.
As outras funções
Os mapas, a verificação de versão ou outras configurações podem contatar serviços externos. Eles são independentes da busca CLIP; revise as configurações do servidor se o seu objetivo é funcionar sem conexões de saída.
Desativar
O machine learning, ou apenas a pesquisa inteligente, pode ser desativado nas configurações. Suas fotos continuam acessíveis; você perde apenas a pesquisa por descrição.
→
Servidor sem acesso à internet
Se o seu servidor estiver isolado, o modelo não conseguirá ser baixado. Uma abordagem é liberar o acesso de saída durante o primeiro download e depois bloqueá-lo: o modelo permanece no volume de cache. Em seguida, confira nos logs do contêiner de ML se ele está de fato carregando o modelo a partir do cache.

#Erros frequentes e solução de problemas

A pesquisa não retorna nada ou retorna um erro
O contêiner de ML está parado ou inacessível, ou a URL nas configurações está errada. Verifique docker compose ps e os logs do immich-machine-learning.
Falha no download do modelo
Nome do modelo digitado errado, sem acesso ao Hugging Face ou disco cheio. Os logs do contêiner de ML geralmente indicam qual é o caso.
O contêiner de ML reinicia em loop
Muitas vezes é falta de memória com um modelo grande, ou uma imagem de aceleração (por exemplo, -cuda) que não corresponde ao hardware. Volte para um modelo menor ou para a imagem de CPU para isolar o problema.
Resultados ruins após trocar de modelo
A tarefa Smart Search foi executada apenas nas fotos faltantes, ou ainda não terminou. Execute-a novamente em todas as fotos.
Resultados ruins em francês, corretos em inglês
O modelo ativo é monolíngue (por exemplo, o padrão ViT-B-32__openai). Mude para um modelo multilíngue e reindexe.
Fotos novas não encontradas
A indexação de novos arquivos passa pela fila de tarefas. Se ela estiver pausada ou sobrecarregada, as fotos recentes ainda não têm vetor. Verifique a página de tarefas.
Terminal — reiniciar o serviço de ML após uma alteração
# Redémarrer uniquement le conteneur de machine learning
docker compose restart immich-machine-learning

# Afficher les 100 dernières lignes de journal
docker compose logs --tail=100 immich-machine-learning

#Limitações e fontes

Este guia não publica nenhum tempo de indexação, nenhum consumo de memória medido nem nenhuma pontuação de relevância: não temos nenhuma medição documentada (hardware, versão, modelo, tamanho da fototeca) para apresentar a você. As ordens de grandeza que você encontra on-line dependem muito desses parâmetros; a única referência confiável é um teste no seu próprio servidor, com algumas consultas cuja resposta você conhece.

O Immich evolui rápido. Os nomes dos menus, a lista de modelos disponíveis e os tipos de pesquisa mudam de uma versão para outra. As informações acima se baseiam na página "Searching" da documentação oficial, consultada pela redação em 30 de outubro de 2026; elas não foram verificadas novamente no dia da publicação. Em caso de divergência, vale a documentação da sua versão: docs.immich.app/features/searching/.

i
Busca CLIP e RAG, mesma ideia
A busca CLIP funciona como a parte de “busca” de um RAG: embeddings armazenados, uma consulta codificada, uma comparação de similaridade. A diferença é que o modelo codifica tanto imagens quanto texto no mesmo espaço. Se você já montou um RAG com seus documentos, já tem o modelo mental certo.

#Para se aprofundar

A busca CLIP encontra fotos; para descrevê-las, fazer perguntas sobre elas ou extrair texto delas, é preciso um modelo de visão. Estes guias do site aprofundam o assunto.

LLM multimodal com visão em execução local: analisar imagens com Ollama
O guia relacionado: descrever uma imagem, fazer OCR, consultar uma foto com um modelo de visão local. O complemento natural da busca CLIP.
Qwen3-VL local com Ollama
Um modelo de visão preciso para analisar em detalhe as fotos que a busca do Immich ajudou você a encontrar.
BGE-M3: embeddings que falam francês
O mesmo princípio de embeddings multilíngues aplicado a texto, para entender por que um modelo monolíngue prejudica consultas em francês.
Este guia ajudou você?

Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.